Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: keep this machine's federation identity when restoring another machine's backup (#12596)

[._.]/ Adam Eivyc7da345aeded
diff --git a/client/src/components/BackupWidget.jsx b/client/src/components/BackupWidget.jsx
index ebfd7f22c1..1f8f47a561 100644
--- a/client/src/components/BackupWidget.jsx
+++ b/client/src/components/BackupWidget.jsx
@@ -64,6 +64,12 @@ const snapshotSourceLabel = (snapshot) =>
snapshot.sourceLabel || snapshot.source || 'Current machine';
const legacyStoreNames = (stores, status) =>
stores.filter(store => store.status === status).map(store => store.store).join(', ');
+const restoreRequest = (snapshot, filter, adoptIdentity) => ({
+ snapshotId: snapshot.id,
+ ...(snapshot.source ? { source: snapshot.source } : {}),
+ subdirFilter: filter.trim() || null,
+ ...(adoptIdentity ? { adoptIdentity: true } : {}),
+});
// ---------------------------------------------------------------------------
// RestorePanel
@@ -71,36 +77,45 @@ const legacyStoreNames = (stores, status) =>
function RestorePanel({ snapshot, onClose, restoring, onRestoreStateChange }) {
const filterId = useId();
+ const adoptIdentityId = useId();
const [filter, setFilter] = useState('');
+ // Kept apart from the accepted preview so the adopt checkbox stays on screen
+ // while toggling it invalidates that preview (#12596).
+ const [identityMismatch, setIdentityMismatch] = useState(null);
+ const [adoptIdentity, setAdoptIdentity] = useState(false);
const [acceptedPreview, setAcceptedPreview] = useState(null);
const [previewing, setPreviewing] = useState(false);
const previewGenerationRef = useRef(0);
- const currentRequest = {
- snapshotId: snapshot.id,
- ...(snapshot.source ? { source: snapshot.source } : {}),
- subdirFilter: filter.trim() || null,
- };
+ const currentRequest = restoreRequest(snapshot, filter, adoptIdentity);
const previewMatchesCurrentRequest = acceptedPreview
&& acceptedPreview.request.snapshotId === currentRequest.snapshotId
&& acceptedPreview.request.source === currentRequest.source
- && acceptedPreview.request.subdirFilter === currentRequest.subdirFilter;
+ && acceptedPreview.request.subdirFilter === currentRequest.subdirFilter
+ && acceptedPreview.request.adoptIdentity === currentRequest.adoptIdentity;
- const handleFilterChange = useCallback((event) => {
+ const invalidatePreview = useCallback(() => {
previewGenerationRef.current += 1;
- setFilter(event.target.value);
setAcceptedPreview(null);
setPreviewing(false);
}, []);
+ const handleFilterChange = useCallback((event) => {
+ invalidatePreview();
+ setFilter(event.target.value);
+ setIdentityMismatch(null);
+ setAdoptIdentity(false);
+ }, [invalidatePreview]);
+
+ const handleAdoptIdentityChange = useCallback((event) => {
+ invalidatePreview();
+ setAdoptIdentity(event.target.checked);
+ }, [invalidatePreview]);
+
const handlePreview = useCallback(async () => {
const generation = previewGenerationRef.current + 1;
previewGenerationRef.current = generation;
- const request = {
- snapshotId: snapshot.id,
- ...(snapshot.source ? { source: snapshot.source } : {}),
- subdirFilter: filter.trim() || null,
- };
+ const request = restoreRequest(snapshot, filter, adoptIdentity);
setPreviewing(true);
setAcceptedPreview(null);
const outcome = await api.restoreBackup({
@@ -117,8 +132,15 @@ function RestorePanel({ snapshot, onClose, restoring, onRestoreStateChange }) {
toast.error(`Preview failed: ${outcome.previewError.message}`);
return;
}
- if (outcome.previewResult) setAcceptedPreview({ request, result: outcome.previewResult });
- }, [snapshot.id, snapshot.source, filter]);
+ if (outcome.previewResult) {
+ const { identityPreserved, identityAdopted } = outcome.previewResult;
+ const mismatch = identityPreserved ?? identityAdopted ?? null;
+ setIdentityMismatch(mismatch);
+ // Never send an adoption the operator can no longer see or uncheck.
+ if (!mismatch) setAdoptIdentity(false);
+ setAcceptedPreview({ request: mismatch ? request : restoreRequest(snapshot, filter, false), result: outcome.previewResult });
+ }
+ }, [snapshot, filter, adoptIdentity]);
const handleRestore = useCallback(async () => {
if (!previewMatchesCurrentRequest || restoring) return;
@@ -197,6 +219,30 @@ function RestorePanel({ snapshot, onClose, restoring, onRestoreStateChange }) {
Preview changes
</button>
+ {identityMismatch && (
+ <div className="space-y-2 rounded border border-port-warning/40 bg-port-warning/10 p-2 text-xs text-port-warning" role="alert">
+ <p className="flex items-start gap-1.5">
+ <AlertTriangle size={13} className="mt-0.5 shrink-0" />
+ <span className="min-w-0 break-words">
+ This snapshot belongs to another federation identity ({identityMismatch.snapshotInstanceId ?? 'unreadable'}) than this machine ({identityMismatch.liveInstanceId ?? 'unreadable'}). {adoptIdentity
+ ? 'Its instances.json (identity, peers and pair secrets) will replace this machine\'s. If that machine is still running, both will claim the same tasks and sync records.'
+ : 'This machine keeps its own instances.json, so it stays a separate peer; every other file restores normally.'}
+ </span>
+ </p>
+ <label htmlFor={adoptIdentityId} className="flex items-start gap-2 text-gray-300">
+ <input
+ id={adoptIdentityId}
+ type="checkbox"
+ checked={adoptIdentity}
+ onChange={handleAdoptIdentityChange}
+ disabled={restoring}
+ className="mt-0.5"
+ />
+ <span>Adopt the snapshot&apos;s identity — only if the machine that made it is retired</span>
+ </label>
+ </div>
+ )}
+
{/* Dry-run results */}
{preview && (
<div>
diff --git a/client/src/components/BackupWidget.test.jsx b/client/src/components/BackupWidget.test.jsx
index 2f770dd251..aca5d3aa46 100644
--- a/client/src/components/BackupWidget.test.jsx
+++ b/client/src/components/BackupWidget.test.jsx
@@ -237,6 +237,64 @@ describe('BackupWidget snapshots', () => {
expect(mockToast.success).toHaveBeenCalledWith('File restore complete — 1 file(s) restored');
});
+ it('keeps the live federation identity unless the operator adopts the snapshot identity (#12596)', async () => {
+ const ids = { liveInstanceId: 'live-instance', snapshotInstanceId: 'other-instance' };
+ mockRestoreBackup
+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ brain/example.json'], identityPreserved: ids })
+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ instances.json'], identityAdopted: ids })
+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ instances.json'], identityAdopted: ids });
+ renderWidget();
+
+ await openRestorePanel();
+ fireEvent.click(screen.getByRole('button', { name: 'Preview changes' }));
+ expect(await screen.findByText(/This machine keeps its own instances.json/)).toBeInTheDocument();
+ const adopt = screen.getByRole('checkbox', { name: /Adopt the snapshot.s identity/ });
+ expect(adopt).not.toBeChecked();
+
+ // Adopting changes what execution does, so the old preview cannot authorize it.
+ fireEvent.click(adopt);
+ expect(screen.queryByRole('button', { name: /^Restore \d/ })).not.toBeInTheDocument();
+ expect(screen.getByText(/will replace this machine.s/)).toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Preview changes' }));
+ expect(await screen.findByText('>f+++++++++ instances.json')).toBeInTheDocument();
+ expect(mockRestoreBackup).toHaveBeenNthCalledWith(2, {
+ snapshotId: '2026-08-25T11-00-00',
+ subdirFilter: null,
+ adoptIdentity: true,
+ dryRun: true,
+ }, { silent: true });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Restore 1 file(s)' }));
+ await waitFor(() => expect(mockRestoreBackup).toHaveBeenNthCalledWith(3, {
+ snapshotId: '2026-08-25T11-00-00',
+ subdirFilter: null,
+ adoptIdentity: true,
+ dryRun: false,
+ }, { silent: true }));
+ });
+
+ it('drops a hidden adoption when a fresh preview shows no identity mismatch (#12596)', async () => {
+ mockRestoreBackup
+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ brain/example.json'], identityPreserved: { liveInstanceId: 'a', snapshotInstanceId: 'b' } })
+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ brain/example.json'] })
+ .mockResolvedValueOnce({ changedFiles: ['>f+++++++++ brain/example.json'] });
+ renderWidget();
+
+ await openRestorePanel();
+ fireEvent.click(screen.getByRole('button', { name: 'Preview changes' }));
+ fireEvent.click(await screen.findByRole('checkbox', { name: /Adopt the snapshot.s identity/ }));
+ fireEvent.click(screen.getByRole('button', { name: 'Preview changes' }));
+
+ fireEvent.click(await screen.findByRole('button', { name: 'Restore 1 file(s)' }));
+ expect(screen.queryByRole('checkbox')).not.toBeInTheDocument();
+ await waitFor(() => expect(mockRestoreBackup).toHaveBeenNthCalledWith(3, {
+ snapshotId: '2026-08-25T11-00-00',
+ subdirFilter: null,
+ dryRun: false,
+ }, { silent: true }));
+ });
+
it('describes restore as files-only and never claims all data is up to date', async () => {
mockRestoreBackup.mockResolvedValueOnce({ changedFiles: [] });
renderWidget();
diff --git a/docs/BACKUP.md b/docs/BACKUP.md
index dd24a12eb9..6ddd748e81 100644
--- a/docs/BACKUP.md
+++ b/docs/BACKUP.md
@@ -521,6 +521,16 @@ A full restore also installs the snapshot's `migrations.applied.json`, so the ne
`data/database-authority.json` is backed up as cutover evidence but is never installed by a file restore. It records which database backend a completed cutover retired on the machine that ran it, so restoring it from another machine's snapshot (or from an older snapshot after a reverse cutover) would make PortOS refuse its own healthy database with `DATABASE_RETIRED_BACKEND`, including after a restart. Every file restore therefore excludes it, in preview and execution alike, and the integrity preflight ignores it too. The destination's existing file stays byte-for-byte as it was: an absent record stays absent and a damaged one stays fail-closed. The same preservation covers the other machine-local authority and recovery records — `peer-execution/`, `peer-execution-catalog.json`, `peer-execution-grants.json`, `peer-execution-authority.json`, `peer-execution-recovery.jsonl`, `workflow-maintenance/` (the graceful-maintenance journal and abandoned-run receipts) and `backup-admission/` (which snapshots also skip) — so a snapshot's copy is evidence only (see [STORAGE.md](./STORAGE.md)). Other records in the snapshot restore normally. Selecting any of these paths, including `database-authority.json` itself, is refused with `BACKUP_RESTORE_MACHINE_LOCAL` before anything is transferred. This does not touch an active maintenance journal (`database-maintenance/`): its recovery semantics are unchanged, and another machine's cutover endpoints are never imported. To change which backend is authoritative, run a database cutover.
+#### Federation identity is kept unless adopted
+
+`data/instances.json` holds this install's federation identity (`self.instanceId`), its peer list and each peer's pair secret. A shared destination lists every machine's snapshots, so installing another machine's file would give two live installs one identity: both would claim the same CoS tasks, sign pushes with the same pair credentials and advance the same per-peer sync cursors (#12596). Before verification, a restore whose scope reaches `instances.json` (a full restore or `subdirFilter: 'instances.json'`) compares the snapshot's `self.instanceId` with the live file's:
+
+- **Same identity, or no live identity** (this machine's own older snapshot, or a never-federated install): the file restores as before.
+- **Different identity:** the live file is kept byte-for-byte. It is excluded from the rsync transfer, the manifest selection and the scope inventory exactly like the machine-local records above, so preview and execution agree, and both report `identityPreserved: { liveInstanceId, snapshotInstanceId }`. Every other file restores normally. An unreadable live file counts as an identity (`liveInstanceId: null`), since its owner cannot be known; an unreadable snapshot file reports `snapshotInstanceId: null`.
+- **`adoptIdentity: true`** installs the snapshot's file anyway and reports `identityAdopted`. Use it only to replace a retired machine. The restore panel shows the mismatch with an unchecked "Adopt the snapshot's identity — only if the machine that made it is retired" checkbox; toggling it requires a new preview.
+
+Any restore that does not install the snapshot's `instances.json` (including a snapshot that had none when checked) excludes it from the transfer, so bytes that appear later cannot reach the live file. Because the choice is made before verification, execution re-checks it under the identity writer lock immediately before rsync starts; if the live identity changed in between (a first pairing, for example), the restore is refused with `409 BACKUP_RESTORE_IDENTITY_CHANGED` before any file is written. Whenever a restore installs `instances.json`, the memoized instance id is dropped after the transfer (even a partial one), so `getInstanceId()` and peer request headers follow the restored identity without a restart.
+
### Database — `restorePostgres()`
Replays the snapshot's `portos-db.sql` into the live database via `psql -v ON_ERROR_STOP=1 --single-transaction`, so the **SQL replay is atomic**: a failed replay rolls back.
@@ -645,9 +655,9 @@ boundary there rather than nesting another wrapper. Snapshot integrity is
verified before any boundary is acquired, and a dry run acquires none of them.
The peer-execution identity fence is shorter-lived: it wraps only the rsync
-transfer, never reconciliation, and only when the scope can reach
-`instances.json` and the snapshot actually contains that file (probed inside the
-held boundaries).
+transfer, never reconciliation, and only when the restore installs
+`instances.json` (see [Federation identity is kept unless adopted](#federation-identity-is-kept-unless-adopted);
+decided before verification, so a preview reports the same choice).
A restore callback must never call a queued settings write API; cache reload reads
directly and does not re-enter the queue.
diff --git a/server/lib/peerHttpClient.js b/server/lib/peerHttpClient.js
index 7a5ff8aaef..43ffd94242 100644
--- a/server/lib/peerHttpClient.js
+++ b/server/lib/peerHttpClient.js
@@ -74,6 +74,8 @@ function peerCredentialHeaders(peer, selfInstanceId) {
}
// Our own federation instance id, memoized after the first successful read.
+// A restore that installs instances.json drops it (resetSelfInstanceIdCache,
+// #12596), so the restored id applies without a restart.
// Resolved through a dynamic import of the identity leaf (#6836): harmless to
// static-import now (services/instanceIdentity.js is a leaf with no edge back
// to this module — the old cycle ran through services/instances.js, which
@@ -91,8 +93,8 @@ async function selfInstanceId() {
return cachedSelfInstanceId;
}
-/** Test-support: drop the memoized instance id. */
-export function __resetSelfInstanceIdForTests() {
+/** Drop the memoized instance id; the next hop re-reads the identity leaf. */
+export function resetSelfInstanceIdCache() {
cachedSelfInstanceId = null;
}
diff --git a/server/lib/peerHttpClient.test.js b/server/lib/peerHttpClient.test.js
index 28f947f1ca..a50d65db87 100644
--- a/server/lib/peerHttpClient.test.js
+++ b/server/lib/peerHttpClient.test.js
@@ -85,7 +85,7 @@ import {
PEER_BODY_IDLE_TIMEOUT,
peerAuthHeaders,
derivePeerAuthToken,
- __resetSelfInstanceIdForTests,
+ resetSelfInstanceIdCache,
} from './peerHttpClient.js';
import { RESPONSE_TOO_LARGE } from './httpClient.js';
@@ -107,7 +107,7 @@ describe('peerHttpClient', () => {
beforeEach(() => {
selfInstanceId = 'self-instance-id';
- __resetSelfInstanceIdForTests();
+ resetSelfInstanceIdCache();
calls = [];
globalThis.fetch = async (url, options) => {
calls.push({ url, options });
@@ -117,7 +117,7 @@ describe('peerHttpClient', () => {
afterEach(() => {
globalThis.fetch = realFetch;
- __resetSelfInstanceIdForTests();
+ resetSelfInstanceIdCache();
});
it('identifies this install with X-PortOS-Instance-Id on every hop', async () => {
@@ -221,7 +221,7 @@ describe('peerHttpClient', () => {
it('omits the header entirely when this install has no identity yet', async () => {
selfInstanceId = 'unknown';
- __resetSelfInstanceIdForTests();
+ resetSelfInstanceIdCache();
await peerFetch('http://peer.example/x');
expect(calls[0].options.headers['X-PortOS-Instance-Id']).toBeUndefined();
});
@@ -246,7 +246,7 @@ describe('peerHttpClient', () => {
beforeEach(() => {
servers = [];
selfInstanceId = 'self-instance-id';
- __resetSelfInstanceIdForTests();
+ resetSelfInstanceIdCache();
});
afterEach(async () => {
@@ -254,7 +254,7 @@ describe('peerHttpClient', () => {
server.close(resolve);
server.closeAllConnections();
})));
- __resetSelfInstanceIdForTests();
+ resetSelfInstanceIdCache();
});
const serve = async (handler) => {
@@ -324,13 +324,13 @@ describe('peerHttpClient', () => {
beforeEach(() => {
selfInstanceId = 'self-instance-id';
- __resetSelfInstanceIdForTests();
+ resetSelfInstanceIdCache();
});
afterEach(async () => {
if (fixture) await fixture.close();
fixture = null;
- __resetSelfInstanceIdForTests();
+ resetSelfInstanceIdCache();
});
it('destroys an unbounded response stream after it exceeds maxBytes', async () => {
diff --git a/server/lib/validation.js b/server/lib/validation.js
index 9cb7a33912..30c9cd0665 100644
--- a/server/lib/validation.js
+++ b/server/lib/validation.js
@@ -1178,7 +1178,9 @@ export const restoreRequestSchema = z.object({
snapshotId: z.string().min(1),
source: snapshotSourceSchema.optional(),
subdirFilter: subdirFilterSchema.optional().nullable(),
- dryRun: z.boolean().optional().default(true)
+ dryRun: z.boolean().optional().default(true),
+ // Install a snapshot's different federation identity over this machine's (#12596).
+ adoptIdentity: z.boolean().optional().default(false)
});
export const restoreDbRequestSchema = z.object({
diff --git a/server/routes/backup.js b/server/routes/backup.js
index 0c4a09f98c..88e1877818 100644
--- a/server/routes/backup.js
+++ b/server/routes/backup.js
@@ -87,7 +87,7 @@ router.delete('/snapshots/:snapshotId', asyncHandler(async (req, res) => {
// POST /api/backup/restore
router.post('/restore', asyncHandler(async (req, res) => {
- const { snapshotId, source, subdirFilter, dryRun } = validateRequest(restoreRequestSchema, req.body);
+ const { snapshotId, source, subdirFilter, dryRun, adoptIdentity } = validateRequest(restoreRequestSchema, req.body);
const settings = await getSettings();
const destPath = settings.backup?.destPath;
if (!destPath) {
@@ -96,6 +96,7 @@ router.post('/restore', asyncHandler(async (req, res) => {
const result = await backup.restoreSnapshot(destPath, snapshotId, {
dryRun,
subdirFilter,
+ adoptIdentity,
...(source ? { source } : {}),
});
res.json(result);
diff --git a/server/routes/backup.test.js b/server/routes/backup.test.js
index 3f9504f200..2634f36d4c 100644
--- a/server/routes/backup.test.js
+++ b/server/routes/backup.test.js
@@ -368,10 +368,27 @@ describe('backup routes', () => {
expect(backup.restoreSnapshot).toHaveBeenCalledWith(
'/dest',
'snap-1',
- { dryRun: false, subdirFilter: 'data' }
+ { dryRun: false, subdirFilter: 'data', adoptIdentity: false }
);
});
+ it('forwards an explicit identity adoption and refuses a non-boolean one (#12596)', async () => {
+ getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
+ backup.restoreSnapshot.mockResolvedValue({ changedFiles: [] });
+ const adopted = await request(buildApp())
+ .post('/api/backup/restore')
+ .send({ snapshotId: 'snap-1', dryRun: false, adoptIdentity: true });
+ expect(adopted.status).toBe(200);
+ expect(backup.restoreSnapshot).toHaveBeenCalledWith('/dest', 'snap-1', expect.objectContaining({ adoptIdentity: true }));
+
+ backup.restoreSnapshot.mockClear();
+ const refused = await request(buildApp())
+ .post('/api/backup/restore')
+ .send({ snapshotId: 'snap-1', dryRun: false, adoptIdentity: 'yes' });
+ expect(refused.status).toBe(400);
+ expect(backup.restoreSnapshot).not.toHaveBeenCalled();
+ });
+
it('refuses a restore of a snapshot whose deletion is in progress with a structured conflict (#10898)', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restoreSnapshot.mockRejectedValueOnce(new ServerError(
@@ -398,6 +415,7 @@ describe('backup routes', () => {
expect(backup.restoreSnapshot).toHaveBeenCalledWith('/dest', 'snap-1', {
dryRun: true,
subdirFilter: null,
+ adoptIdentity: false,
source: '@legacy',
});
});
diff --git a/server/services/backup.js b/server/services/backup.js
index a2f4e6b126..0f07832c68 100644
--- a/server/services/backup.js
+++ b/server/services/backup.js
@@ -1434,7 +1434,7 @@ async function reconcileLiveFileRestore(subdirFilter) {
}
}
-function manifestDataEntries(manifest, srcDir, subdirFilter) {
+function manifestDataEntries(manifest, srcDir, subdirFilter, isSkippedPath = isRestorePreservedPath) {
if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)
|| !manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)
|| !Number.isInteger(manifest.fileCount) || manifest.fileCount < 0
@@ -1469,7 +1469,7 @@ function manifestDataEntries(manifest, srcDir, subdirFilter) {
// Still recorded in dataPaths (inventory consistency), but never hashed:
// Finder may rewrite a hashed metadata file that restore never transfers.
- if (isRestorePreservedPath(normalized) || isOsMetadataFile(segments.at(-1))) continue;
+ if (isSkippedPath(normalized) || isOsMetadataFile(segments.at(-1))) continue;
if (!subdirFilter || normalized === subdirFilter || normalized.startsWith(`${subdirFilter}/`)) {
selected.push({ filePath, expectedHash });
}
@@ -1532,6 +1532,56 @@ const restoreScopeIsPreservedFile = (subdirFilter) => {
return isRestorePreservedPath(normalized);
};
+/**
+ * `instances.json` holds this install's federation identity (`self.instanceId`),
+ * its peers and their pair secrets. A shared destination offers every machine's
+ * snapshots, so installing another machine's file would give two live installs
+ * one identity: each claims the other's CoS tasks and signs pushes with the
+ * other's pair credentials (#12596). A restore therefore installs it only when
+ * the identities match, the live install has none, or the operator adopts the
+ * snapshot's identity (replacing a retired machine). Otherwise it is preserved
+ * through the same three places as RESTORE_PRESERVED_FILES.
+ */
+const IDENTITY_FILE = 'instances.json';
+const IDENTITY_RSYNC_EXCLUDE = `--exclude=/${caseInsensitiveGlob(IDENTITY_FILE)}`;
+const isIdentityPath = relativePath => typeof relativePath === 'string' && relativePath.toLowerCase() === IDENTITY_FILE;
+const IDENTITY_ABSENT = Symbol('identity-absent');
+
+async function readIdentityFile(path) {
+ const { ok, value } = await readJSONFileStrict(path, IDENTITY_ABSENT, { logError: false });
+ if (ok && value === IDENTITY_ABSENT) return { present: false, readable: true, instanceId: null };
+ const instanceId = ok ? value?.self?.instanceId : null;
+ return { present: true, readable: ok, instanceId: typeof instanceId === 'string' && instanceId ? instanceId : null };
+}
+
+/**
+ * Whether this restore installs the snapshot's instances.json. Decided before
+ * the integrity preflight so preview and execution exclude the same bytes. An
+ * unreadable live file counts as an identity (fail closed): only adoption
+ * replaces it, since its owner cannot be known.
+ */
+async function resolveIdentityRestore(srcDir, subdirFilter, adoptIdentity) {
+ const notInstalled = { installs: false, preserved: null, adopted: null };
+ if (subdirFilter && !isIdentityPath(subdirFilter)) return notInstalled;
+ const snapshot = await readIdentityFile(join(srcDir, IDENTITY_FILE));
+ if (!snapshot.present) return notInstalled;
+ const live = await readIdentityFile(join(PATHS.data, IDENTITY_FILE));
+ const liveHasIdentity = live.present && (live.instanceId !== null || !live.readable);
+ if (!liveHasIdentity || (live.instanceId !== null && live.instanceId === snapshot.instanceId)) {
+ return { installs: true, preserved: null, adopted: null };
+ }
+ const ids = { liveInstanceId: live.instanceId, snapshotInstanceId: snapshot.instanceId };
+ return adoptIdentity
+ ? { installs: true, preserved: null, adopted: ids }
+ : { ...notInstalled, preserved: ids };
+}
+
+// `beforeTransfer`: nothing was written, so the caller must not report a partial restore.
+const identityChangedError = () => Object.assign(new ServerError(
+ 'This machine\'s federation identity (instances.json) changed after the restore was checked. Nothing was restored; preview the restore again.',
+ { status: 409, code: 'BACKUP_RESTORE_IDENTITY_CHANGED' },
+), { beforeTransfer: true });
+
const snapshotFileIntegrityError = (snapshotId, unmanifestedPath = null) => new ServerError(
// Name the offending entry: without it the operator is told their only backup
// failed integrity and given nothing to act on.
@@ -1546,7 +1596,7 @@ const snapshotFileIntegrityError = (snapshotId, unmanifestedPath = null) => new
* (rsync `--checksum` digests only regular files in scope, so the largest one
* bounds the longest explainable silence between `-ii` heartbeats).
*/
-async function snapshotScopeInventory(srcDir, subdirFilter) {
+async function snapshotScopeInventory(srcDir, subdirFilter, isSkippedPath = isRestorePreservedPath) {
const scopePath = subdirFilter
? resolve(srcDir, ...subdirFilter.split('/'))
: srcDir;
@@ -1577,7 +1627,7 @@ async function snapshotScopeInventory(srcDir, subdirFilter) {
// not inflate the digest floor either.
if (isOsMetadataFile(basename(filePath))) continue;
const scopedPath = relative(srcDir, filePath).replaceAll('\\', '/');
- if (isRestorePreservedPath(scopedPath)) continue;
+ if (isSkippedPath(scopedPath)) continue;
if (info.size > largestFileBytes) largestFileBytes = info.size;
const normalized = relative(srcDir, filePath).replaceAll('\\', '/');
@@ -1620,7 +1670,10 @@ async function assertRestoreStorageCompatible(srcDir, inventory, snapshotId) {
}
}
-async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter) {
+async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter, { preserveIdentity = false } = {}) {
+ const isSkippedPath = preserveIdentity
+ ? path => isRestorePreservedPath(path) || isIdentityPath(path)
+ : isRestorePreservedPath;
// A unique fallback distinguishes a genuinely absent legacy manifest from an
// existing file whose parsed value is JSON null.
const manifestRead = await readJSONFileStrict(
@@ -1639,7 +1692,7 @@ async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter
// still needs the largest in-scope file. PostgreSQL also needs a complete
// inventory to reject ignored legacy metadata; only the file escape hatch
// can retain the old best-effort behavior when inventory fails.
- const legacyInventory = await snapshotScopeInventory(srcDir, subdirFilter).catch(() => null);
+ const legacyInventory = await snapshotScopeInventory(srcDir, subdirFilter, isSkippedPath).catch(() => null);
await assertRestoreStorageCompatible(srcDir, legacyInventory, snapshotId);
return {
status: 'unverified',
@@ -1649,7 +1702,7 @@ async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter
};
}
- const manifestEntries = manifestDataEntries(manifestRead.value, srcDir, subdirFilter);
+ const manifestEntries = manifestDataEntries(manifestRead.value, srcDir, subdirFilter, isSkippedPath);
if (!manifestEntries) {
throw new ServerError(`Snapshot integrity manifest is invalid: ${snapshotId}`, {
status: 409,
@@ -1661,7 +1714,7 @@ async function verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter
// Hash agreement is insufficient if rsync can also copy files the manifest
// never recorded. Rebuild the same regular-file inventory in the selected
// scope and reject additions before rsync reads or overwrites anything.
- const inventory = await snapshotScopeInventory(srcDir, subdirFilter)
+ const inventory = await snapshotScopeInventory(srcDir, subdirFilter, isSkippedPath)
.catch(() => null);
if (!inventory) throw snapshotFileIntegrityError(snapshotId);
await assertRestoreStorageCompatible(srcDir, inventory, snapshotId);
@@ -1703,8 +1756,11 @@ function restoreIdleTimeoutMs(largestFileBytes = 0) {
* @param {object} options
* @param {boolean} [options.dryRun=true] - If true, do not write any files
* @param {string|null} [options.subdirFilter=null] - Limit restore to a subdirectory
+ * @param {boolean} [options.adoptIdentity=false] - Install a snapshot's different
+ * federation identity (instances.json) over the live one; only for replacing a
+ * retired machine. Without it the live identity is preserved (`identityPreserved`).
*/
-export async function restoreSnapshot(destPath, snapshotId, { dryRun = true, subdirFilter: requestedFilter = null, source } = {}) {
+export async function restoreSnapshot(destPath, snapshotId, { dryRun = true, subdirFilter: requestedFilter = null, source, adoptIdentity = false } = {}) {
// Canonicalize once: manifest selection, the inventory and the rsync include
// chain each spell the filter differently, so `brain/` or `./brain` would
// select nothing yet verify clean. An all-dot/empty filter means no filter.
@@ -1736,17 +1792,21 @@ export async function restoreSnapshot(destPath, snapshotId, { dryRun = true, sub
// neither explicit deletion nor retention can remove verified bytes while
// rsync still reads them (#10898).
return withSnapshotRead(resolved.snapshotDir, snapshotId,
- () => restoreHeldSnapshot(resolved, snapshotId, { dryRun, subdirFilter }));
+ () => restoreHeldSnapshot(resolved, snapshotId, { dryRun, subdirFilter, adoptIdentity: adoptIdentity === true }));
}
-async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, { dryRun, subdirFilter }) {
+async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, { dryRun, subdirFilter, adoptIdentity }) {
await assertSnapshotRestorable(snapshotDir, snapshotId, currentSource);
const srcDir = join(snapshotDir, 'data');
+ const identity = await resolveIdentityRestore(srcDir, subdirFilter, adoptIdentity);
+ // Keyed on the approval, not on a mismatch: a snapshot instances.json that
+ // appears after the check must not reach the live file unfenced.
+ const preserveIdentity = !identity.installs;
// Run the preflight independently for preview and execution. A preview is an
// aid to confirmation, not an integrity lease: snapshot bytes may change
// between requests, especially on removable or network-backed destinations.
- const verification = await verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter);
+ const verification = await verifySnapshotFiles(snapshotDir, srcDir, snapshotId, subdirFilter, { preserveIdentity });
// A full restore installs the snapshot's ledger too, so the next boot re-runs
// whatever it lacks; only a folder restore can leave restored files behind
// migrations the live ledger already records.
@@ -1757,6 +1817,8 @@ async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, {
const restoreNotes = (restoredLegacyStores) => ({
...(ledgerGap !== undefined && { ledgerGap }),
...(restoredLegacyStores.length > 0 && { restoredLegacyStores }),
+ ...(identity.preserved && { identityPreserved: identity.preserved }),
+ ...(identity.adopted && { identityAdopted: identity.adopted }),
});
// Restore must compare destination bytes even when size and mtime match.
@@ -1787,7 +1849,8 @@ async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, {
// Same placement rule: excluded before the include chain, and kept out of the
// manifest selection and inventory above, so what rsync may write is exactly
// what the preflight verified.
- const flags = ['-ii', '--checksum', ...OS_METADATA_RSYNC_EXCLUDES, ...RESTORE_PRESERVED_RSYNC_EXCLUDES];
+ const flags = ['-ii', '--checksum', ...OS_METADATA_RSYNC_EXCLUDES, ...RESTORE_PRESERVED_RSYNC_EXCLUDES,
+ ...(preserveIdentity ? [IDENTITY_RSYNC_EXCLUDE] : [])];
if (dryRun) flags.push('--dry-run');
if (subdirFilter) {
// Anchored with a leading `/` — rsync matches an unanchored pattern against
@@ -1820,7 +1883,14 @@ async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, {
const changedFiles = await withLiveFileRestoreOwners(scope, srcDir, () => transferAndReconcileLiveFiles({
subdirFilter,
transfer: async () => {
- const changed = await transferWithIdentityFence({ scope, srcDir, transferFiles });
+ const changed = await transferWithIdentityFence({
+ installsIdentity: identity.installs,
+ assertIdentityUnchanged: async () => {
+ const current = await resolveIdentityRestore(srcDir, subdirFilter, adoptIdentity);
+ if (JSON.stringify(current) !== JSON.stringify(identity)) throw identityChangedError();
+ },
+ transferFiles,
+ });
restoredLegacyStores = await convertRestoredLegacySplitStores(legacyStores);
return changed;
},
@@ -1955,19 +2025,29 @@ function withLiveFileRestoreOwners(scope, srcDir, operation) {
/**
* Peer-execution identity fence: shorter-lived than the owners above. It wraps
- * ONLY the rsync transfer, never reconciliation, and only when the scope can
- * touch instances.json AND the snapshot actually carries that file — probed
- * here, inside the already-held owners.
+ * ONLY the rsync transfer, never reconciliation, and only when this restore
+ * installs instances.json (resolveIdentityRestore). The decision was made
+ * before verification, so it is re-checked here under the identity writer lock:
+ * a live identity written since then (first pairing, ensureSelf) must not be
+ * overwritten without adoption. The memoized instance id is dropped even after
+ * a partial transfer, so the process never stamps an id the file no longer holds.
*/
-async function transferWithIdentityFence({ scope, srcDir, transferFiles }) {
- const identityInScope = !scope || scope === 'instances.json';
- const snapshotHasIdentity = identityInScope && await stat(join(srcDir, 'instances.json')).then(
- info => info.isFile(),
- error => { if (error.code === 'ENOENT') return false; throw error; },
- );
- if (!snapshotHasIdentity) return transferFiles();
- const { withPeerExecutionIdentityRestore } = await import('./peerExecutionRuntime.js');
- return withPeerExecutionIdentityRestore(transferFiles);
+async function transferWithIdentityFence({ installsIdentity, assertIdentityUnchanged, transferFiles }) {
+ if (!installsIdentity) return transferFiles();
+ const [{ withPeerExecutionIdentityRestore }, { resetInstanceIdCache }, { resetSelfInstanceIdCache }] = await Promise.all([
+ import('./peerExecutionRuntime.js'),
+ import('./instanceIdentity.js'),
+ import('../lib/peerHttpClient.js'),
+ ]);
+ return withPeerExecutionIdentityRestore(async () => {
+ await assertIdentityUnchanged();
+ try {
+ return await transferFiles();
+ } finally {
+ resetInstanceIdCache();
+ resetSelfInstanceIdCache();
+ }
+ });
}
/**
@@ -1980,6 +2060,7 @@ async function transferAndReconcileLiveFiles({ subdirFilter, transfer }) {
const [result] = await Promise.allSettled([transfer()]);
const reconciliationError = await reconcileLiveFileRestore(subdirFilter).then(() => null, error => error);
if (result.status === 'rejected') {
+ if (result.reason?.beforeTransfer) throw result.reason;
const partialRestoreError = new Error(
`${result.reason.message}. Some files may already have been overwritten because file restore is not transactional.${reconciliationError ? ` ${reconciliationError.message}` : ''}`,
{ cause: result.reason },
diff --git a/server/services/backup.test.js b/server/services/backup.test.js
index a5402760d6..d7b6b78ac5 100644
--- a/server/services/backup.test.js
+++ b/server/services/backup.test.js
@@ -43,7 +43,12 @@ function testDataRoot() {
}
vi.mock('../lib/fileUtils.js', async (importOriginal) => {
const actual = await importOriginal();
- return makePathsProxy(actual, { dataRoot: testDataRoot, overrides: { atomicWrite: vi.fn(actual.atomicWrite) } });
+ // dataPath is overridden too: instanceIdentity.js resolves instances.json
+ // through it, and the restore identity tests read that file (#12596).
+ return makePathsProxy(actual, { dataRoot: testDataRoot, overrides: {
+ atomicWrite: vi.fn(actual.atomicWrite),
+ dataPath: (...segments) => joinPath(testDataRoot(), ...segments),
+ } });
});
afterAll(() => {
@@ -2885,20 +2890,150 @@ describe('restoreSnapshot manifest verification', () => {
}
}
- it('invalidates execution grants before restoring instance identity bytes', async context => {
+ it.for([
+ { name: 'a never-federated install', live: null },
+ { name: 'this machine\'s own older snapshot', live: '{"self":{"instanceId":"00000000-0000-4000-8000-000000000001"},"peers":[{"id":"newer-peer"}]}' },
+ ])('installs instance identity bytes for $name, invalidating execution grants first', async ({ live }, context) => {
await withRealRsync(context, async () => {
const { createPeerExecutionAuthority } = await import('../lib/peerExecutionAuthority.js');
const path = joinPath(PATHS.data, 'peer-execution-authority.json');
+ const identityPath = joinPath(PATHS.data, 'instances.json');
await realFs.rm(path, { force: true });
- const authority = createPeerExecutionAuthority(PATHS.data);
- const before = authority.initialize();
- const identity = '{"self":{"instanceId":"00000000-0000-4000-8000-000000000001"},"peers":[]}';
- const hash = await writeSnapshotFile('instances.json', identity);
- await writeManifest({ 'instances.json': hash });
- await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false, subdirFilter: 'instances.json' });
- expect(authority.read().epoch).not.toBe(before.epoch);
- expect(await realFs.readFile(joinPath(PATHS.data, 'instances.json'), 'utf8')).toBe(identity);
- await realFs.rm(path, { force: true });
+ await realFs.rm(identityPath, { force: true });
+ if (live) await realFs.writeFile(identityPath, live);
+ try {
+ const authority = createPeerExecutionAuthority(PATHS.data);
+ const before = authority.initialize();
+ const identity = '{"self":{"instanceId":"00000000-0000-4000-8000-000000000001"},"peers":[]}';
+ const hash = await writeSnapshotFile('instances.json', identity);
+ await writeManifest({ 'instances.json': hash });
+ const result = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false, subdirFilter: 'instances.json' });
+ expect(result).not.toHaveProperty('identityPreserved');
+ expect(authority.read().epoch).not.toBe(before.epoch);
+ expect(await realFs.readFile(identityPath, 'utf8')).toBe(identity);
+ } finally {
+ await realFs.rm(path, { force: true });
+ await realFs.rm(identityPath, { force: true });
+ }
+ });
+ });
+
+ // #12596: a shared destination lists every machine's snapshots. Installing
+ // another machine's instances.json would give two live installs one
+ // federation identity, so a restore keeps the live one unless adopted.
+ describe('federation identity (#12596)', () => {
+ const LIVE_ID = '00000000-0000-4000-8000-00000000000a';
+ const OTHER_ID = '00000000-0000-4000-8000-00000000000b';
+ const LIVE_IDENTITY = JSON.stringify({ self: { instanceId: LIVE_ID }, peers: [{ id: 'live-peer' }] });
+ const OTHER_IDENTITY = JSON.stringify({ self: { instanceId: OTHER_ID }, peers: [{ id: 'other-peer' }] });
+ const identityPath = () => joinPath(PATHS.data, 'instances.json');
+
+ async function seedOtherMachine({ live = LIVE_IDENTITY } = {}) {
+ // A wrong manifest hash for instances.json proves a preserved identity
+ // is neither verified nor transferred, like the other preserved files.
+ await writeSnapshotFile('instances.json', OTHER_IDENTITY);
+ const neighbor = await writeSnapshotFile(RECORD, '{"value":"snapshot"}');
+ await writeManifest({ 'instances.json': '0'.repeat(64), [RECORD]: neighbor });
+ await realFs.rm(joinPath(PATHS.data, RECORD), { force: true });
+ await realFs.writeFile(identityPath(), live);
+ }
+
+ afterEach(async () => {
+ await realFs.rm(identityPath(), { force: true });
+ await realFs.rm(joinPath(PATHS.data, 'peer-execution-authority.json'), { force: true });
+ const { resetInstanceIdCache } = await import('./instanceIdentity.js');
+ resetInstanceIdCache();
+ });
+
+ it.for([
+ { name: 'full restore', options: {} },
+ { name: 'folder restore of instances.json', options: { subdirFilter: 'instances.json' } },
+ ])('a $name keeps a different live identity byte-for-byte and reports it in preview and execution', async ({ options }, context) => {
+ await withRealRsync(context, async () => {
+ await seedOtherMachine();
+ const { getInstanceId } = await import('./instanceIdentity.js');
+ expect(await getInstanceId()).toBe(LIVE_ID);
+ const identityPreserved = { liveInstanceId: LIVE_ID, snapshotInstanceId: OTHER_ID };
+
+ const preview = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: true, ...options });
+ expect(preview).toMatchObject({ identityPreserved, verification: { status: 'verified' } });
+ expect(preview.changedFiles.some(line => line.includes('instances.json'))).toBe(false);
+
+ const result = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false, ...options });
+ expect(result).toMatchObject({ identityPreserved });
+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe(LIVE_IDENTITY);
+ expect(await getInstanceId()).toBe(LIVE_ID);
+ expect(existsSync(joinPath(PATHS.data, RECORD))).toBe(!options.subdirFilter);
+ });
+ });
+
+ it('keeps an unreadable live identity rather than guessing whose it was', async context => {
+ await withRealRsync(context, async () => {
+ await seedOtherMachine({ live: '{ not json' });
+ const result = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false });
+ expect(result.identityPreserved).toEqual({ liveInstanceId: null, snapshotInstanceId: OTHER_ID });
+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe('{ not json');
+ });
+ });
+
+ it('refuses, before writing, when a live identity appears after the restore was checked', async context => {
+ await withRealRsync(context, async () => {
+ await seedOtherMachine();
+ await writeManifest({
+ 'instances.json': createHash('sha256').update(OTHER_IDENTITY).digest('hex'),
+ [RECORD]: createHash('sha256').update('{"value":"snapshot"}').digest('hex'),
+ });
+ // Never federated when checked; paired while verification runs.
+ await realFs.rm(identityPath(), { force: true });
+ fs.readFile.mockImplementation(async (path, ...rest) => {
+ if (String(path).endsWith('manifest.json')) await realFs.writeFile(identityPath(), LIVE_IDENTITY);
+ return realFs.readFile(path, ...rest);
+ });
+
+ await expect(restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false }))
+ .rejects.toMatchObject({ status: 409, code: 'BACKUP_RESTORE_IDENTITY_CHANGED' });
+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe(LIVE_IDENTITY);
+ expect(existsSync(joinPath(PATHS.data, RECORD))).toBe(false);
+ });
+ });
+
+ it('never installs a snapshot identity that appeared after the check', async context => {
+ await withRealRsync(context, async () => {
+ // A legacy snapshot (no manifest) without instances.json when checked.
+ await writeSnapshotFile(RECORD, '{"value":"snapshot"}');
+ await realFs.writeFile(identityPath(), LIVE_IDENTITY);
+ fs.readFile.mockImplementation(async (path, ...rest) => {
+ if (String(path).endsWith('manifest.json')) await writeSnapshotFile('instances.json', OTHER_IDENTITY);
+ return realFs.readFile(path, ...rest);
+ });
+
+ await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false });
+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe(LIVE_IDENTITY);
+ expect(await realFs.readFile(joinPath(PATHS.data, RECORD), 'utf8')).toBe('{"value":"snapshot"}');
+ });
+ });
+
+ it('installs an adopted identity and serves it without a restart', async context => {
+ await withRealRsync(context, async () => {
+ await seedOtherMachine();
+ await writeManifest({
+ 'instances.json': createHash('sha256').update(OTHER_IDENTITY).digest('hex'),
+ [RECORD]: createHash('sha256').update('{"value":"snapshot"}').digest('hex'),
+ });
+ const { getInstanceId } = await import('./instanceIdentity.js');
+ expect(await getInstanceId()).toBe(LIVE_ID);
+ const identityAdopted = { liveInstanceId: LIVE_ID, snapshotInstanceId: OTHER_ID };
+
+ const preview = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: true, adoptIdentity: true });
+ expect(preview).toMatchObject({ identityAdopted });
+ expect(preview).not.toHaveProperty('identityPreserved');
+ expect(preview.changedFiles.some(line => line.includes('instances.json'))).toBe(true);
+
+ const result = await restoreSnapshot(tmpRoot, 'snap-1', { dryRun: false, adoptIdentity: true });
+ expect(result).toMatchObject({ identityAdopted });
+ expect(await realFs.readFile(identityPath(), 'utf8')).toBe(OTHER_IDENTITY);
+ expect(await getInstanceId()).toBe(OTHER_ID);
+ });
});
});
@@ -3584,6 +3719,8 @@ describe('restoreSnapshot snapshotId, filter flags, and settings re-sync', () =>
'--exclude=/[pP][eE][eE][rR]-[eE][xX][eE][cC][uU][tT][iI][oO][nN]-[rR][eE][cC][oO][vV][eE][rR][yY].[jJ][sS][oO][nN][lL]',
'--exclude=/[wW][oO][rR][kK][fF][lL][oO][wW]-[mM][aA][iI][nN][tT][eE][nN][aA][nN][cC][eE]',
'--exclude=/[bB][aA][cC][kK][uU][pP]-[aA][dD][mM][iI][sS][sS][iI][oO][nN]',
+ // No snapshot instances.json was approved for install (#12596).
+ '--exclude=/[iI][nN][sS][tT][aA][nN][cC][eE][sS].[jJ][sS][oO][nN]',
'--dry-run',
// Leading `/` is load-bearing: rsync matches an unanchored pattern
// against the end of every path, so `brain/***` would also restore
@@ -3618,6 +3755,8 @@ describe('restoreSnapshot snapshotId, filter flags, and settings re-sync', () =>
'--exclude=/[pP][eE][eE][rR]-[eE][xX][eE][cC][uU][tT][iI][oO][nN]-[rR][eE][cC][oO][vV][eE][rR][yY].[jJ][sS][oO][nN][lL]',
'--exclude=/[wW][oO][rR][kK][fF][lL][oO][wW]-[mM][aA][iI][nN][tT][eE][nN][aA][nN][cC][eE]',
'--exclude=/[bB][aA][cC][kK][uU][pP]-[aA][dD][mM][iI][sS][sS][iI][oO][nN]',
+ // No snapshot instances.json was approved for install (#12596).
+ '--exclude=/[iI][nN][sS][tT][aA][nN][cC][eE][sS].[jJ][sS][oO][nN]',
]);
});
diff --git a/server/services/instanceIdentity.js b/server/services/instanceIdentity.js
index 559e63885e..e3e9536b1b 100644
--- a/server/services/instanceIdentity.js
+++ b/server/services/instanceIdentity.js
@@ -109,6 +109,15 @@ export async function getInstanceId() {
return cachedInstanceId;
}
+/**
+ * Drop the memoized id so the next read follows instances.json. A file restore
+ * that installs instances.json calls this, or the running process would keep
+ * stamping its old id while getSelf() returned the restored one (#12596).
+ */
+export function resetInstanceIdCache() {
+ cachedInstanceId = null;
+}
+
/**
* Resolve this machine's real federation instance id, creating the local
* identity on the cold path. `getInstanceId()` returns the