From 99c3c670a58c781a8dbf49e307ca3e53dc903faf Mon Sep 17 00:00:00 2001 From: Maurice Date: Tue, 17 Nov 2026 12:19:13 +0100 Subject: [PATCH] fix(demo): keep a demo baseline per engine and check it before every reset The baseline was travel-baseline.db on both engines and went straight into the swap, so a SQLite baseline left in the data directory made every hourly reset of a Postgres demo fail inside pg_restore, and never got replaced. It is now named after the engine's archive entry (travel-baseline.db on SQLite, travel-baseline.pgdump on Postgres), and the backup port's new checkCopy refuses one the engine cannot restore before the swap; the reset then saves a fresh baseline and logs the reason instead of failing hourly. --- server/src/demo/demo-reset.ts | 29 +++++++++++-- server/src/nest/admin/demo-reset.job.ts | 2 +- .../nest/backup/postgres-database-backup.ts | 10 +++++ .../src/nest/backup/sqlite-database-backup.ts | 19 ++++++++ .../database/database-backup.interface.ts | 9 ++++ .../tests/unit/demo/demo-addon-policy.test.ts | 2 + .../tests/unit/demo/demo-reset-path.test.ts | 16 +++++++ .../unit/demo/demo-reset-sessions.test.ts | 2 + .../nest/postgres-database-backup.test.ts | 14 ++++++ .../sqlite-database-backup-check-copy.test.ts | 43 +++++++++++++++++++ wiki/Demo-Mode.md | 2 + 11 files changed, 144 insertions(+), 4 deletions(-) create mode 100644 server/tests/unit/nest/sqlite-database-backup-check-copy.test.ts diff --git a/server/src/demo/demo-reset.ts b/server/src/demo/demo-reset.ts index df2724322..b7d2a240b 100644 --- a/server/src/demo/demo-reset.ts +++ b/server/src/demo/demo-reset.ts @@ -16,7 +16,16 @@ import { RequestContext, type EntityManager } from '@mikro-orm/core'; import fs from 'fs'; import path from 'path'; -const baselinePath = path.join(resolveDataPaths().dataDir, 'travel-baseline.db'); +/** + * The baseline the hourly reset returns to, named for the engine that wrote + * it after the database's own archive entry: `travel-baseline.db` on SQLite, + * `travel-baseline.pgdump` on Postgres. An install that changes engine keeps + * its data directory, so a baseline the other engine left there is never + * taken for this one's. + */ +function baselinePathFor(database: DatabaseBackupStrategy): string { + return path.join(resolveDataPaths().dataDir, `travel-baseline${path.extname(database.archiveEntry)}`); +} /** * The active fork's `EntityManager`, resolved via `RequestContext.getEntityManager()` @@ -49,6 +58,7 @@ export function requireEntityManager(): EntityManager { * closes the connection, swaps the baseline in atomically and reopens it. */ async function resetDemoUser(database: DatabaseBackupStrategy): Promise { + const baselinePath = baselinePathFor(database); if (!fs.existsSync(baselinePath)) { console.log('[Demo Reset] No baseline found, skipping. Admin must save baseline first.'); return; @@ -59,6 +69,18 @@ async function resetDemoUser(database: DatabaseBackupStrategy): Promise { return; } + // A baseline this engine cannot restore (damaged, or written by an older + // build under this name) would fail inside the swap every hour. It is + // replaced by the current database once, with the reason in the log. + const refusal = await database.checkCopy(baselinePath); + if (refusal) { + console.warn( + `[Demo Reset] The baseline cannot be restored here (${refusal}); saving the current database as the baseline.`, + ); + await saveBaseline(database); + return; + } + // Plan 3i Task 3 / R3 (SAFE spike verdict, task-0-report.md §7): the // pre-close reads (DMR1/DMR2) run through THIS fork — the one // `CronRegistrarService.register()`'s `wrappedTick` already opened for the @@ -183,6 +205,7 @@ async function saveBaseline(database: DatabaseBackupStrategy): Promise { return; } + const baselinePath = baselinePathFor(database); const pending = baselinePath + '.tmp'; fs.rmSync(pending, { force: true }); await database.snapshot(pending); @@ -190,8 +213,8 @@ async function saveBaseline(database: DatabaseBackupStrategy): Promise { console.log('[Demo] Baseline saved'); } -function hasBaseline(): boolean { - return fs.existsSync(baselinePath); +function hasBaseline(database: DatabaseBackupStrategy): boolean { + return fs.existsSync(baselinePathFor(database)); } /** diff --git a/server/src/nest/admin/demo-reset.job.ts b/server/src/nest/admin/demo-reset.job.ts index c17bf07ec..418789711 100644 --- a/server/src/nest/admin/demo-reset.job.ts +++ b/server/src/nest/admin/demo-reset.job.ts @@ -64,7 +64,7 @@ export class DemoResetJob implements OnApplicationBootstrap { * not read as the reopen failing. */ private async saveFirstBaselineIfSeeded(): Promise { - if (!takeExampleTripsSeeded() || hasBaseline()) return; + if (!takeExampleTripsSeeded() || hasBaseline(this.database)) return; try { await withRequestContext({ em: this.em }, () => saveBaseline(this.database)); } catch (err: unknown) { diff --git a/server/src/nest/backup/postgres-database-backup.ts b/server/src/nest/backup/postgres-database-backup.ts index 0166d878d..ad40bf0c6 100644 --- a/server/src/nest/backup/postgres-database-backup.ts +++ b/server/src/nest/backup/postgres-database-backup.ts @@ -32,6 +32,11 @@ export async function checkPostgresDump(extractDir: string, binDir: string | und ? 'This backup holds a SQLite database, which cannot be restored into a Postgres database.' : `Invalid backup: ${PG_ARCHIVE_ENTRY} not found`; } + return checkPostgresDumpFile(dump, binDir); +} + +/** Why the dump at `dump` cannot be restored into a Postgres database, or null: the checks of {@link checkPostgresDump}. */ +async function checkPostgresDumpFile(dump: string, binDir: string | undefined): Promise { let executed: string[]; try { executed = await pgDumpMigrations(dump, binDir); @@ -107,6 +112,11 @@ export class PostgresDatabaseBackup implements DatabaseBackupStrategy { if (refusal) throw new DomainError(400, refusal); } + /** A kept copy must be a dump this build can restore: a SQLite file a switch of engine left behind is refused. */ + checkCopy(file: string): Promise { + return checkPostgresDumpFile(file, this.connection.binDir); + } + /** A dump of the database a restore is about to replace, in the data directory. */ keepCopyBeforeRestore(): Promise { const target = path.join(this.paths.dataDir, `pre-restore-${Date.now()}.pgdump`); diff --git a/server/src/nest/backup/sqlite-database-backup.ts b/server/src/nest/backup/sqlite-database-backup.ts index 970491cf2..1308aa4fa 100644 --- a/server/src/nest/backup/sqlite-database-backup.ts +++ b/server/src/nest/backup/sqlite-database-backup.ts @@ -9,6 +9,9 @@ import { Injectable } from '@nestjs/common'; import fs from 'fs'; import path from 'path'; +/** The first 16 bytes of every SQLite database file. */ +const SQLITE_HEADER = Buffer.from('SQLite format 3\0', 'latin1'); + /** * The backup port on a SQLite file, the engine TREK runs on by default. * @@ -61,6 +64,22 @@ export class SqliteDatabaseBackup implements DatabaseBackupStrategy { if (refusal) throw new DomainError(refusal.status, refusal.error); } + /** A SQLite file starts with its format header; anything else (a Postgres dump, an empty file) is refused. */ + async checkCopy(file: string): Promise { + const header = Buffer.alloc(SQLITE_HEADER.length); + try { + const fd = fs.openSync(file, 'r'); + try { + fs.readSync(fd, header, 0, header.length, 0); + } finally { + fs.closeSync(fd); + } + } catch (err: unknown) { + return `${file} cannot be read (${err instanceof Error ? err.message : String(err)})`; + } + return header.equals(SQLITE_HEADER) ? null : `${file} is not a SQLite database`; + } + /** A copy of the database a restore is about to replace, next to it: the swap deletes the current file. */ keepCopyBeforeRestore(): Promise { const target = path.join(path.dirname(this.lifecycle.file), `pre-restore-${Date.now()}.db`); diff --git a/server/src/nest/database/database-backup.interface.ts b/server/src/nest/database/database-backup.interface.ts index 7e9a83e5d..1b48b9a42 100644 --- a/server/src/nest/database/database-backup.interface.ts +++ b/server/src/nest/database/database-backup.interface.ts @@ -49,6 +49,15 @@ export interface DatabaseBackupStrategy { */ verify(extractDir: string): Promise; + /** + * Why `file`, a copy kept on disk (the demo baseline), cannot be put in place + * by `replace` on this engine, or null when it can: SQLite wants a SQLite + * file, Postgres a dump with TREK's migration history from this or an older + * TREK. Checked before every swap, so a file another engine left behind is + * refused with a reason instead of failing inside the swap. + */ + checkCopy(file: string): Promise; + /** * Keeps a copy of the database a restore is about to replace. Best effort: a * database broken enough to need the restore may not copy, and that must not diff --git a/server/tests/unit/demo/demo-addon-policy.test.ts b/server/tests/unit/demo/demo-addon-policy.test.ts index 7c10fe3d0..55bd06e11 100644 --- a/server/tests/unit/demo/demo-addon-policy.test.ts +++ b/server/tests/unit/demo/demo-addon-policy.test.ts @@ -156,7 +156,9 @@ describe('demo addon policy across the hourly reset', () => { vi.spyOn(fs, 'existsSync').mockImplementation(((p: fs.PathLike) => String(p) === BASELINE) as typeof fs.existsSync); // The stand-in swap brings back a baseline whose shelf an admin had changed. const database = { + archiveEntry: 'travel.db', canSnapshot: () => true, + checkCopy: vi.fn(async () => null), checkpoint: vi.fn(async () => undefined), replace: vi.fn(async () => { await scramble(); diff --git a/server/tests/unit/demo/demo-reset-path.test.ts b/server/tests/unit/demo/demo-reset-path.test.ts index 99af90f70..edba957ab 100644 --- a/server/tests/unit/demo/demo-reset-path.test.ts +++ b/server/tests/unit/demo/demo-reset-path.test.ts @@ -67,6 +67,8 @@ describe('demo-reset DB path', () => { lifecycle as unknown as DatabaseLifecycle, maintenance as unknown as SqliteMaintenance, ); + // The baseline here exists only in the existsSync stand-in; DEMORESET-008 covers a refused one. + vi.spyOn(database, 'checkCopy').mockResolvedValue(null); }); afterEach(() => { @@ -155,4 +157,18 @@ describe('demo-reset DB path', () => { expect(console.error).not.toHaveBeenCalledWith('[Demo Reset] Failed to restore baseline:', expect.anything()); expect(renameSync).not.toHaveBeenCalled(); }); + + it('DEMORESET-008: a baseline this engine cannot restore is not swapped in, but replaced by a fresh one', async () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined); + vi.spyOn(database, 'checkCopy').mockResolvedValue(`${BASELINE} is not a SQLite database`); + + await withCtx(() => resetDemoUser(database)); + + expect(database.checkCopy).toHaveBeenCalledWith(BASELINE); + expect(lifecycle.close).not.toHaveBeenCalled(); + expect(copyFileSync).not.toHaveBeenCalled(); + expect(maintenance.vacuumInto).toHaveBeenCalledWith(BASELINE + '.tmp'); + expect(renameSync).toHaveBeenCalledWith(BASELINE + '.tmp', BASELINE); + expect(warn).toHaveBeenCalledWith(expect.stringMatching(/is not a SQLite database\); saving the current database/)); + }); }); diff --git a/server/tests/unit/demo/demo-reset-sessions.test.ts b/server/tests/unit/demo/demo-reset-sessions.test.ts index 65c037629..8ddb755d6 100644 --- a/server/tests/unit/demo/demo-reset-sessions.test.ts +++ b/server/tests/unit/demo/demo-reset-sessions.test.ts @@ -47,7 +47,9 @@ describe('demo reset and the signed-in sessions', () => { await deleteRows(t, UserSessions); }; database = { + archiveEntry: 'travel.db', canSnapshot: () => true, + checkCopy: vi.fn(async () => null), checkpoint: vi.fn(async () => undefined), replace: vi.fn(async () => { await swap(); diff --git a/server/tests/unit/nest/postgres-database-backup.test.ts b/server/tests/unit/nest/postgres-database-backup.test.ts index 19a304469..4baa4070e 100644 --- a/server/tests/unit/nest/postgres-database-backup.test.ts +++ b/server/tests/unit/nest/postgres-database-backup.test.ts @@ -169,4 +169,18 @@ describe('PostgresDatabaseBackup', () => { expect(backup.location()).toBe('Postgres postgresql://trek:***@db/trek'); await expect(postgresBackup({}).snapshot(path.join(root, 'c.pgdump'))).rejects.toThrow(/without TREK_DB_URL/); }); + + it('PGBACKUP-007: a kept copy (the demo baseline) passes only as a dump with TREK history this build knows', async () => { + const copy = path.join(root, 'travel-baseline.pgdump'); + writeFileSync(copy, 'dump'); + installFakeTool(bin, 'pg_restore', { snippets: [listsMigrations(KNOWN.slice(0, 2))] }); + await expect(backup.checkCopy(copy)).resolves.toBeNull(); + + const notADump = failsWith('pg_restore: error: input file does not appear to be a valid archive'); + installFakeTool(bin, 'pg_restore', { snippets: [notADump] }); + await expect(backup.checkCopy(copy)).resolves.toBe('Uploaded file is not a valid Postgres dump'); + + installFakeTool(bin, 'pg_restore', { snippets: [listsMigrations(['Migration20990101000000_from_the_future'])] }); + await expect(backup.checkCopy(copy)).resolves.toMatch(/made by a newer TREK version/); + }); }); diff --git a/server/tests/unit/nest/sqlite-database-backup-check-copy.test.ts b/server/tests/unit/nest/sqlite-database-backup-check-copy.test.ts new file mode 100644 index 000000000..bf91cc4c4 --- /dev/null +++ b/server/tests/unit/nest/sqlite-database-backup-check-copy.test.ts @@ -0,0 +1,43 @@ +/** + * SqliteDatabaseBackup.checkCopy: a kept copy (the demo baseline) is put back + * only when it is a SQLite file; a Postgres dump an engine switch left under + * the same name, an empty file or a missing one is refused with a reason. + */ +import { SqliteDatabaseBackup } from '../../../src/nest/backup/sqlite-database-backup'; +import type { DatabaseLifecycle } from '../../../src/nest/database/database-lifecycle.service'; + +import Database from 'better-sqlite3'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; + +let dir: string; +const backup = new SqliteDatabaseBackup({ file: ':memory:' } as unknown as DatabaseLifecycle, {} as never); + +beforeEach(() => { + dir = mkdtempSync(path.join(tmpdir(), 'trek-check-copy-')); +}); +afterEach(() => { + rmSync(dir, { recursive: true, force: true }); +}); + +describe('SqliteDatabaseBackup.checkCopy', () => { + it('SQLCOPY-001: a SQLite file passes', async () => { + const file = path.join(dir, 'travel-baseline.db'); + const db = new Database(file); + db.exec('CREATE TABLE t (x INTEGER)'); + db.close(); + await expect(backup.checkCopy(file)).resolves.toBeNull(); + }); + + it('SQLCOPY-002: anything else is refused, naming the file', async () => { + const dump = path.join(dir, 'dump.db'); + writeFileSync(dump, 'PGDMP\u0001\u000e\u0000 not sqlite at all'); + await expect(backup.checkCopy(dump)).resolves.toBe(`${dump} is not a SQLite database`); + const empty = path.join(dir, 'empty.db'); + writeFileSync(empty, ''); + await expect(backup.checkCopy(empty)).resolves.toBe(`${empty} is not a SQLite database`); + await expect(backup.checkCopy(path.join(dir, 'missing.db'))).resolves.toMatch(/missing\.db cannot be read/); + }); +}); diff --git a/wiki/Demo-Mode.md b/wiki/Demo-Mode.md index 2cf692f5f..689b73f48 100644 --- a/wiki/Demo-Mode.md +++ b/wiki/Demo-Mode.md @@ -56,6 +56,8 @@ TREK schedules an automatic hourly reset of the demo database. At each reset: If no baseline has been saved yet, the reset is skipped and a message is logged. +On a [Postgres](Database-Postgres) install the baseline is a `pg_dump` file, `travel-baseline.pgdump`, restored into the database instead of a file swap. Each engine reads only its own baseline, and checks it before every reset: a baseline it cannot restore (a damaged file, or one another engine wrote under its name) is replaced by a fresh one from the current database, with the reason in the log, instead of failing every hour. + The seeder defaults the admin address to `admin@trek.app` while the reset defaults it to `admin@nomad.app`, a legacy quirk that is pinned deliberately. With `DEMO_ADMIN_EMAIL` unset the reset looks up an address that does not exist, finds no admin row, and skips the carry-over entirely; a password change, API key or avatar set after the baseline was saved is lost on every hourly reset. Set `DEMO_ADMIN_EMAIL` (to `admin@trek.app`, for instance) if you want them to survive. Unlike the seed-time variables above, the reset reads it on every run, so setting it on an already-seeded instance and restarting is enough. The instance-wide Maps and Unsplash keys stored in `app_settings` are carried across either way, so map and photo search keep working after a reset.