@rocicorp/zero 1.10.0-canary.0 → 1.10.0-canary.10

package/out/zero-cache/src/services/change-streamer/replica-poller.js

@@ -0,0 +1,55 @@
+import { Database } from "../../../../zqlite/src/db.js";
+import { getReplicationState } from "../replicator/schema/replication-state.js";
+import { StatementRunner } from "../../db/statements.js";
+import { Subscription } from "../../types/subscription.js";
+import { assert } from "console";
+import { clearInterval } from "timers";
+//#region ../zero-cache/src/services/change-streamer/replica-poller.ts
+var CHECK_INTERVAL_MS = 10 * 1e3;
+/**
+* The single-node equivalent of a backup monitor polls the replica file every
+* 30 seconds and schedules cleanup when the watermark
+* (i.e. stateVersion) moves forward.
+*/
+var ReplicaPoller = class {
+	id = "replica-poller";
+	#lc;
+	#replicaFile;
+	#stream;
+	#pollReplicaTimer;
+	#lastWatermark = "";
+	constructor(lc, replicaFile) {
+		this.#lc = lc.withContext("component", this.id);
+		this.#replicaFile = replicaFile;
+		this.#stream = Subscription.create({ cleanup: () => clearInterval(this.#pollReplicaTimer) });
+	}
+	start() {
+		assert(this.#pollReplicaTimer === void 0, `Already called start()`);
+		this.#lc.info?.(`starting replica monitor`);
+		this.#pollReplica();
+		this.#pollReplicaTimer = setInterval(this.#pollReplica, CHECK_INTERVAL_MS);
+		return this.#stream;
+	}
+	#pollReplica = () => {
+		const db = new Database(this.#lc, this.#replicaFile);
+		try {
+			const { stateVersion } = getReplicationState(new StatementRunner(db));
+			if (stateVersion !== this.#lastWatermark) {
+				this.#lastWatermark = stateVersion;
+				this.#lc.debug?.(`replicated up to watermark ${stateVersion}`);
+				this.#stream.push({
+					watermark: stateVersion,
+					backupTimeMs: Date.now()
+				});
+			}
+		} catch (e) {
+			this.#lc.error?.(`Unable to read watermark from replica`, e);
+		} finally {
+			db.close();
+		}
+	};
+};
+//#endregion
+export { ReplicaPoller };
+
+//# sourceMappingURL=replica-poller.js.map

package/out/zero-cache/src/services/change-streamer/replica-poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replica-poller.js","names":["#lc","#replicaFile","#stream","#pollReplicaTimer","#pollReplica","#lastWatermark"],"sources":["../../../../../../zero-cache/src/services/change-streamer/replica-poller.ts"],"sourcesContent":["import {assert} from 'console';\nimport {clearInterval} from 'timers';\nimport type {LogContext} from '@rocicorp/logger';\nimport {Database} from '../../../../zqlite/src/db.ts';\nimport {StatementRunner} from '../../db/statements.ts';\nimport type {Source} from '../../types/streams.ts';\nimport {Subscription} from '../../types/subscription.ts';\nimport {getReplicationState} from '../replicator/schema/replication-state.ts';\nimport type {BackedUpWatermark} from './backup-monitor.ts';\n\nconst CHECK_INTERVAL_MS = 10 * 1000;\n\n/**\n * The single-node equivalent of a backup monitor polls the replica file every\n * 30 seconds and schedules cleanup when the watermark\n * (i.e. stateVersion) moves forward.\n */\nexport class ReplicaPoller {\n  readonly id = 'replica-poller';\n  readonly #lc: LogContext;\n  readonly #replicaFile: string;\n  readonly #stream: Subscription<BackedUpWatermark>;\n  #pollReplicaTimer: NodeJS.Timeout | undefined;\n\n  #lastWatermark: string = '';\n\n  constructor(lc: LogContext, replicaFile: string) {\n    this.#lc = lc.withContext('component', this.id);\n    this.#replicaFile = replicaFile;\n    this.#stream = Subscription.create<BackedUpWatermark>({\n      cleanup: () => clearInterval(this.#pollReplicaTimer),\n    });\n  }\n\n  start(): Source<BackedUpWatermark> {\n    assert(this.#pollReplicaTimer === undefined, `Already called start()`);\n    this.#lc.info?.(`starting replica monitor`);\n    // Perform the first poll immediately to avoid unnecessarily waiting\n    // during single-node development.\n    this.#pollReplica();\n    this.#pollReplicaTimer = setInterval(this.#pollReplica, CHECK_INTERVAL_MS);\n    return this.#stream;\n  }\n\n  readonly #pollReplica = () => {\n    const db = new Database(this.#lc, this.#replicaFile);\n    try {\n      const {stateVersion} = getReplicationState(new StatementRunner(db));\n      if (stateVersion !== this.#lastWatermark) {\n        this.#lastWatermark = stateVersion;\n        this.#lc.debug?.(`replicated up to watermark ${stateVersion}`);\n        this.#stream.push({watermark: stateVersion, backupTimeMs: Date.now()});\n      }\n    } catch (e) {\n      this.#lc.error?.(`Unable to read watermark from replica`, e);\n    } finally {\n      db.close();\n    }\n  };\n}\n"],"mappings":";;;;;;;AAUA,IAAM,oBAAoB,KAAK;;;;;;AAO/B,IAAa,gBAAb,MAA2B;CACzB,KAAc;CACd;CACA;CACA;CACA;CAEA,iBAAyB;CAEzB,YAAY,IAAgB,aAAqB;EAC/C,KAAKA,MAAM,GAAG,YAAY,aAAa,KAAK,EAAE;EAC9C,KAAKC,eAAe;EACpB,KAAKC,UAAU,aAAa,OAA0B,EACpD,eAAe,cAAc,KAAKC,iBAAiB,EACrD,CAAC;CACH;CAEA,QAAmC;EACjC,OAAO,KAAKA,sBAAsB,KAAA,GAAW,wBAAwB;EACrE,KAAKH,IAAI,OAAO,0BAA0B;EAG1C,KAAKI,aAAa;EAClB,KAAKD,oBAAoB,YAAY,KAAKC,cAAc,iBAAiB;EACzE,OAAO,KAAKF;CACd;CAEA,qBAA8B;EAC5B,MAAM,KAAK,IAAI,SAAS,KAAKF,KAAK,KAAKC,YAAY;EACnD,IAAI;GACF,MAAM,EAAC,iBAAgB,oBAAoB,IAAI,gBAAgB,EAAE,CAAC;GAClE,IAAI,iBAAiB,KAAKI,gBAAgB;IACxC,KAAKA,iBAAiB;IACtB,KAAKL,IAAI,QAAQ,8BAA8B,cAAc;IAC7D,KAAKE,QAAQ,KAAK;KAAC,WAAW;KAAc,cAAc,KAAK,IAAI;IAAC,CAAC;GACvE;EACF,SAAS,GAAG;GACV,KAAKF,IAAI,QAAQ,yCAAyC,CAAC;EAC7D,UAAU;GACR,GAAG,MAAM;EACX;CACF;AACF"}

package/out/zero-cache/src/services/change-streamer/schema/tables.d.ts

@@ -43,9 +43,12 @@ export type BackfillingColumn = {
     column: string;
     backfill: BackfillID;
 };
+interface PurgeLock {
+    release(): Promise<void>;
+}
 export declare function setupCDCTables(lc: LogContext, db: postgres.TransactionSql, shard: ShardID): Promise<void>;
 export declare function markResetRequired(sql: PostgresDB, shard: ShardID): Promise<void>;
-export declare function ensureReplicationConfig(lc: LogContext, db: PostgresDB, subscriptionState: Pick<SubscriptionState, 'publications' | 'replicaVersion' | 'watermark'>, shard: ShardID, autoReset: boolean, setTimeoutFn?: typeof setTimeout): Promise<void>;
+export declare function ensureReplicationConfig(lc: LogContext, db: PostgresDB, subscriptionState: Pick<SubscriptionState, 'publications' | 'replicaVersion' | 'watermark'>, shard: ShardID, autoReset: boolean, purgeLock?: PurgeLock, setTimeoutFn?: typeof setTimeout): Promise<void>;
 export declare const CHANGE_STREAMER_APP_NAME = "zero-change-streamer";
 export declare class AutoResetSignal extends AbortError {
     readonly name = "AutoResetSignal";
@@ -68,4 +71,5 @@ export declare class AutoResetSignal extends AbortError {
  * since the blocked connection is inside a pending transaction.
  */
 export declare function terminateChangeDBLockHolders(lc: LogContext, db: PostgresDB, shard: ShardID): Promise<void>;
+export {};
 //# sourceMappingURL=tables.d.ts.map

package/out/zero-cache/src/services/change-streamer/schema/tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../../../../../zero-cache/src/services/change-streamer/schema/tables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAErC,OAAO,EAAC,UAAU,EAAC,MAAM,0CAA0C,CAAC;AAGpE,OAAO,EAAC,KAAK,UAAU,EAAC,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAY,KAAK,OAAO,EAAC,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,UAAU,EACV,MAAM,EACN,aAAa,EACd,MAAM,8CAA8C,CAAC;AACtD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,8CAA8C,CAAC;AAOpF,eAAO,MAAM,SAAS,QAAQ,CAAC;AAM/B,MAAM,MAAM,cAAc,GAAG;IAG3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAmBF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,UASzD;AAED,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC;AAaF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,UAiBlD;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,CAAC;CACtB,CAAC;AAYF,wBAAsB,cAAc,CAClC,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,QAAQ,CAAC,cAAc,EAC3B,KAAK,EAAE,OAAO,iBAIf;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,iBAKtE;AAED,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,UAAU,EACd,iBAAiB,EAAE,IAAI,CACrB,iBAAiB,EACjB,cAAc,GAAG,gBAAgB,GAAG,WAAW,CAChD,EACD,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,EAClB,YAAY,GAAE,OAAO,UAAuB,iBAwH7C;AAMD,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,IAAI,qBAAqB;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,OAAO,iBA4Cf"}
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../../../../../zero-cache/src/services/change-streamer/schema/tables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAErC,OAAO,EAAC,UAAU,EAAC,MAAM,0CAA0C,CAAC;AAGpE,OAAO,EAAC,KAAK,UAAU,EAAC,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAY,KAAK,OAAO,EAAC,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,UAAU,EACV,MAAM,EACN,aAAa,EACd,MAAM,8CAA8C,CAAC;AACtD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,8CAA8C,CAAC;AAOpF,eAAO,MAAM,SAAS,QAAQ,CAAC;AAM/B,MAAM,MAAM,cAAc,GAAG;IAG3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAmBF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,UASzD;AAED,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC;AAaF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,UAiBlD;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,CAAC;CACtB,CAAC;AAYF,UAAU,SAAS;IACjB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAsB,cAAc,CAClC,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,QAAQ,CAAC,cAAc,EAC3B,KAAK,EAAE,OAAO,iBAIf;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,iBAKtE;AAED,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,UAAU,EACd,iBAAiB,EAAE,IAAI,CACrB,iBAAiB,EACjB,cAAc,GAAG,gBAAgB,GAAG,WAAW,CAChD,EACD,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,EAClB,SAAS,CAAC,EAAE,SAAS,EACrB,YAAY,GAAE,OAAO,UAAuB,iBA4H7C;AAMD,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,IAAI,qBAAqB;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,OAAO,iBA4Cf"}

package/out/zero-cache/src/services/change-streamer/schema/tables.js

@@ -77,7 +77,7 @@ async function markResetRequired(sql, shard) {
   UPDATE ${sql(cdcSchema(shard))}."replicationConfig"
     SET "resetRequired" = true`;
 }
-async function ensureReplicationConfig(lc, db, subscriptionState, shard, autoReset, setTimeoutFn = setTimeout) {
+async function ensureReplicationConfig(lc, db, subscriptionState, shard, autoReset, purgeLock, setTimeoutFn = setTimeout) {
 	const { publications, replicaVersion, watermark } = subscriptionState;
 	const replicaConfig = {
 		publications,
@@ -100,6 +100,7 @@ async function ensureReplicationConfig(lc, db, subscriptionState, shard, autoRes
 			if (replicaVersion !== replicaConfig.replicaVersion || !equals(new Set(publications), new Set(replicaConfig.publications))) {
 				if (replicaConfig.replicaVersion !== watermark) throw new AutoResetSignal(`Cannot reset change db@${replicaVersion} to service replica@${replicaConfig.replicaVersion} from watermark ${watermark}`);
 				lc.info?.(`Data in cdc tables @${replicaVersion} is incompatible with replica @${replicaConfig.replicaVersion}. Clearing tables.`);
+				purgeLock?.release();
 				needsTruncate = true;
 				stmts.push(sql`TRUNCATE TABLE ${sql(schema)}."replicationState"`, sql`TRUNCATE TABLE ${sql(schema)}."changeLog"`, sql`TRUNCATE TABLE ${sql(schema)}."replicationConfig"`, sql`TRUNCATE TABLE ${sql(schema)}."tableMetadata"`, sql`TRUNCATE TABLE ${sql(schema)}."backfilling"`);
 			}

package/out/zero-cache/src/services/change-streamer/schema/tables.js.map

@@ -1 +1 @@
-{"version":3,"file":"tables.js","names":[],"sources":["../../../../../../../zero-cache/src/services/change-streamer/schema/tables.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {ident} from 'pg-format';\nimport type postgres from 'postgres';\nimport {type PendingQuery, type Row} from 'postgres';\nimport {AbortError} from '../../../../../shared/src/abort-error.ts';\nimport {equals} from '../../../../../shared/src/set-utils.ts';\nimport {runTx} from '../../../db/run-transaction.ts';\nimport {type PostgresDB} from '../../../types/pg.ts';\nimport {cdcSchema, type ShardID} from '../../../types/shards.ts';\nimport type {\n  BackfillID,\n  Change,\n  TableMetadata,\n} from '../../change-source/protocol/current/data.ts';\nimport type {SubscriptionState} from '../../replicator/schema/replication-state.ts';\n\n// For readability in the sql statements.\nfunction schema(shard: ShardID) {\n  return ident(cdcSchema(shard));\n}\n\nexport const PG_SCHEMA = 'cdc';\n\nfunction createSchema(shard: ShardID) {\n  return /*sql*/ `CREATE SCHEMA IF NOT EXISTS ${schema(shard)};`;\n}\n\nexport type ChangeLogEntry = {\n  // A strictly monotonically increasing, lexicographically sortable\n  // value that uniquely identifies a position in the change stream.\n  watermark: string;\n  change: Change;\n};\n\ntype FullChangeLogEntry = ChangeLogEntry & {pos: number};\n\nfunction createChangeLogTable(shard: ShardID) {\n  // Note: The \"change\" column used to be JSONB, but that was problematic in that\n  // it does not handle the NULL unicode character.\n  // https://vladimir.varank.in/notes/2021/01/you-dont-insert-unicode-null-character-as-postgres-jsonb/\n  return /*sql*/ `\n  CREATE TABLE ${schema(shard)}.\"changeLog\" (\n    watermark  TEXT,\n    pos        INT8,\n    change     JSON NOT NULL,\n    precommit  TEXT,  -- Only exists on commit entries. Purely for debugging.\n    PRIMARY KEY (watermark, pos)\n  );\n`;\n}\n\n/**\n * Tracks the watermark from which to resume the change stream and the\n * current owner (task ID) acting as the single writer to the changeLog.\n */\nexport type ReplicationState = {\n  lastWatermark: string;\n  owner: string | null;\n  ownerAddress: string | null;\n};\n\nexport function createReplicationStateTable(shard: ShardID) {\n  return /*sql*/ `\n  CREATE TABLE ${schema(shard)}.\"replicationState\" (\n    \"lastWatermark\" TEXT NOT NULL,\n    \"owner\" TEXT,\n    \"ownerAddress\" TEXT,\n    \"lock\" INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n`;\n}\n\nexport async function discoverChangeStreamerAddress(\n  shard: ShardID,\n  sql: PostgresDB,\n): Promise<string | null> {\n  const result = await sql<{ownerAddress: string | null}[]> /*sql*/ `\n    SELECT \"ownerAddress\" FROM ${sql(cdcSchema(shard))}.\"replicationState\"`;\n  return result[0].ownerAddress;\n}\n\n/**\n * This mirrors the analogously named table in the SQLite replica\n * (`services/replicator/schema/replication-state.ts`), and is used\n * to detect when the replica has been reset and is no longer compatible\n * with the current ChangeLog.\n */\nexport type ReplicationConfig = {\n  replicaVersion: string;\n  publications: readonly string[];\n};\n\nfunction createReplicationConfigTable(shard: ShardID) {\n  return /*sql*/ `\n  CREATE TABLE ${schema(shard)}.\"replicationConfig\" (\n    \"replicaVersion\" TEXT NOT NULL,\n    \"publications\" TEXT[] NOT NULL,\n    \"resetRequired\" BOOL,\n    \"lock\" INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n`;\n}\n\nexport function createBackfillTables(shard: ShardID) {\n  return /*sql*/ `\n  CREATE TABLE ${schema(shard)}.\"tableMetadata\" (\n    \"schema\" TEXT NOT NULL,\n    \"table\" TEXT NOT NULL,\n    \"metadata\" JSONB NOT NULL,\n    PRIMARY KEY(\"schema\", \"table\")\n  );\n\n  CREATE TABLE ${schema(shard)}.\"backfilling\" (\n    \"schema\" TEXT NOT NULL,\n    \"table\" TEXT NOT NULL,\n    \"column\" TEXT NOT NULL,\n    \"backfill\" JSONB NOT NULL,\n    PRIMARY KEY(\"schema\", \"table\", \"column\")\n  );\n  `;\n}\n\nexport type TableMetadataRow = {\n  schema: string;\n  table: string;\n  metadata: TableMetadata;\n};\n\nexport type BackfillingColumn = {\n  schema: string;\n  table: string;\n  column: string;\n  backfill: BackfillID;\n};\n\nfunction createTables(shard: ShardID) {\n  return (\n    createSchema(shard) +\n    createChangeLogTable(shard) +\n    createReplicationStateTable(shard) +\n    createReplicationConfigTable(shard) +\n    createBackfillTables(shard)\n  );\n}\n\nexport async function setupCDCTables(\n  lc: LogContext,\n  db: postgres.TransactionSql,\n  shard: ShardID,\n) {\n  lc.info?.(`Setting up CDC tables`);\n  await db.unsafe(createTables(shard));\n}\n\nexport async function markResetRequired(sql: PostgresDB, shard: ShardID) {\n  const schema = cdcSchema(shard);\n  await sql`\n  UPDATE ${sql(schema)}.\"replicationConfig\"\n    SET \"resetRequired\" = true`;\n}\n\nexport async function ensureReplicationConfig(\n  lc: LogContext,\n  db: PostgresDB,\n  subscriptionState: Pick<\n    SubscriptionState,\n    'publications' | 'replicaVersion' | 'watermark'\n  >,\n  shard: ShardID,\n  autoReset: boolean,\n  setTimeoutFn: typeof setTimeout = setTimeout,\n) {\n  const {publications, replicaVersion, watermark} = subscriptionState;\n  const replicaConfig = {publications, replicaVersion};\n  const replicationState: ReplicationState = {\n    lastWatermark: replicaVersion,\n    owner: null,\n    ownerAddress: null,\n  };\n  const schema = cdcSchema(shard);\n\n  await runTx(db, async sql => {\n    const stmts: PendingQuery<Row[]>[] = [];\n    let needsTruncate = false;\n    const results = await sql<\n      {\n        replicaVersion: string;\n        publications: string[];\n        resetRequired: boolean | null;\n      }[]\n    > /*sql*/ `\n    SELECT \"replicaVersion\", \"publications\", \"resetRequired\" \n      FROM ${sql(schema)}.\"replicationConfig\"`;\n\n    if (results.length) {\n      const {replicaVersion, publications} = results[0];\n      if (\n        replicaVersion !== replicaConfig.replicaVersion ||\n        !equals(new Set(publications), new Set(replicaConfig.publications))\n      ) {\n        if (replicaConfig.replicaVersion !== watermark) {\n          throw new AutoResetSignal(\n            `Cannot reset change db@${replicaVersion} to ` +\n              `service replica@${replicaConfig.replicaVersion} ` +\n              `from watermark ${watermark}`,\n          );\n        }\n        lc.info?.(\n          `Data in cdc tables @${replicaVersion} is incompatible ` +\n            `with replica @${replicaConfig.replicaVersion}. Clearing tables.`,\n        );\n        // Note: The order of TRUNCATE matters. The replicationState table is\n        //       truncated before the changeLog table, in order to acquire\n        //       (exclusive) locks on the tables in the same order that the\n        //       storer.ts acquires locks when writing the changeLog, namely:\n        //\n        // 1. SELECT ... FROM replicationState FOR UPDATE;\n        // 2. INSERT INTO changeLog ...;\n        //    ...\n        // n. UPDATE replicationState ...;\n        needsTruncate = true;\n        stmts.push(\n          sql`TRUNCATE TABLE ${sql(schema)}.\"replicationState\"`,\n          sql`TRUNCATE TABLE ${sql(schema)}.\"changeLog\"`,\n          sql`TRUNCATE TABLE ${sql(schema)}.\"replicationConfig\"`,\n          sql`TRUNCATE TABLE ${sql(schema)}.\"tableMetadata\"`,\n          sql`TRUNCATE TABLE ${sql(schema)}.\"backfilling\"`,\n        );\n      }\n    }\n    // Initialize (or re-initialize TRUNCATED) tables\n    if (results.length === 0 || needsTruncate) {\n      // The storer uses the earliest changeLog entry as the safe watermark\n      // from which subscribers can be resumed. These initial entries ensure\n      // that subscribers can start from a freshly synced replica, even if\n      // new changes have been replicated and not purged from the changeLog.\n      //\n      // TODO: Replace this with an explicit `firstWatermark` column in the\n      //       change db.\n      const watermark = replicaConfig.replicaVersion;\n      const initialTx: FullChangeLogEntry[] = [\n        {watermark, pos: 0, change: {tag: 'begin'}},\n        {watermark, pos: 1, change: {tag: 'commit'}},\n      ];\n\n      stmts.push(\n        sql`INSERT INTO ${sql(schema)}.\"replicationConfig\" ${sql(replicaConfig)}`,\n        sql`INSERT INTO ${sql(schema)}.\"replicationState\"  ${sql(replicationState)} \n              ON CONFLICT (lock) DO UPDATE SET ${sql(replicationState)}`,\n        ...initialTx.map(\n          change => sql`INSERT INTO ${sql(schema)}.\"changeLog\" ${sql(change)}`,\n        ),\n      );\n\n      if (needsTruncate) {\n        // The TRUNCATE statements require ACCESS EXCLUSIVE locks, which may\n        // be blocked by old storer catchup reads. Race against a timeout\n        // that terminates the blocking backends if the TRUNCATE takes too\n        // long.\n        const timer = setTimeoutFn(async () => {\n          lc.info?.(\n            'ensureReplicationConfig blocked, terminating lock holders',\n          );\n          await terminateChangeDBLockHolders(lc, db, shard);\n        }, LOCK_HOLDER_TERMINATE_TIMEOUT_MS);\n        try {\n          return await Promise.all(stmts);\n        } finally {\n          clearTimeout(timer);\n        }\n      }\n      return Promise.all(stmts);\n    }\n\n    const {resetRequired} = results[0];\n    if (resetRequired) {\n      if (autoReset) {\n        throw new AutoResetSignal('reset required by replication stream');\n      }\n      lc.error?.(\n        '\\n\\n\\n' +\n          'Reset required but --auto-reset is not enabled.\\n' +\n          'This can happen for upstream databases that do not support event triggers.\\n' +\n          'To correct this, see https://zero.rocicorp.dev/docs/connecting-to-postgres#schema-changes' +\n          '\\n\\n\\n',\n      );\n    }\n\n    return [];\n  });\n}\n\n// The time to wait for a TRUNCATE in ensureReplicationConfig before\n// terminating blocking backends via terminateChangeDBLockHolders.\nconst LOCK_HOLDER_TERMINATE_TIMEOUT_MS = 5_000;\n\nexport const CHANGE_STREAMER_APP_NAME = 'zero-change-streamer';\n\nexport class AutoResetSignal extends AbortError {\n  readonly name = 'AutoResetSignal';\n}\n\n/**\n * Terminates zero-cache backends that are blocking the current backend\n * from acquiring locks on CDC tables (e.g., during TRUNCATE).\n *\n * This is used during change-DB takeover when the new replication-manager's\n * `ensureReplicationConfig` needs to TRUNCATE tables, but the old\n * replication-manager's storer is still reading from them (e.g., large\n * catchup cursors).\n *\n * The function:\n * 1. Finds backends waiting for a lock on a TRUNCATE in {schema}\n * 2. Uses `pg_blocking_pids()` to identify which backends are blocking them\n * 3. Terminates blocking backends that have `application_name = 'zero-change-streamer'`\n *\n * Must be called on a **separate connection** from the one that is blocked,\n * since the blocked connection is inside a pending transaction.\n */\nexport async function terminateChangeDBLockHolders(\n  lc: LogContext,\n  db: PostgresDB,\n  shard: ShardID,\n) {\n  const schema = cdcSchema(shard);\n\n  // Step 1: Find backends that are blocked waiting for a lock,\n  // whose query involves a TRUNCATE on this shard's CDC schema.\n  const blocked = await db<{pid: number}[]>`\n    SELECT pid FROM pg_stat_activity\n      WHERE wait_event_type = 'Lock'\n        AND application_name = ${CHANGE_STREAMER_APP_NAME}\n        AND query LIKE ${'%TRUNCATE%' + schema + '%'}`;\n\n  if (blocked.length === 0) {\n    lc.info?.('no blocked TRUNCATE backends found');\n    return;\n  }\n\n  const blockedPids = blocked.map(r => r.pid);\n  lc.info?.(`found blocked TRUNCATE backends: ${JSON.stringify(blockedPids)}`);\n\n  // Step 2: For each blocked backend, find and terminate its blockers\n  // that are zero-change-streamer connections.\n  const terminated = await db<\n    {pid: number; applicationName: string; query: string; terminated: boolean}[]\n  >`\n    SELECT pid, application_name as \"applicationName\", query,\n           pg_terminate_backend(pid) as terminated\n      FROM pg_stat_activity\n      WHERE pid = ANY(\n        SELECT unnest(pg_blocking_pids(blocked.pid))\n          FROM unnest(${blockedPids}::int[]) AS blocked(pid)\n      )\n      AND application_name = ${CHANGE_STREAMER_APP_NAME}\n      AND pid != ALL(${blockedPids}::int[])`;\n\n  if (terminated.length === 0) {\n    lc.info?.(`no ${CHANGE_STREAMER_APP_NAME} blockers found to terminate`);\n  } else {\n    for (const {pid, applicationName, query, terminated: ok} of terminated) {\n      lc.info?.(\n        `terminated blocking backend pid=${pid} app=${applicationName} ok=${ok} query=${query.slice(0, 200)}`,\n      );\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"tables.js","names":[],"sources":["../../../../../../../zero-cache/src/services/change-streamer/schema/tables.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {ident} from 'pg-format';\nimport type postgres from 'postgres';\nimport {type PendingQuery, type Row} from 'postgres';\nimport {AbortError} from '../../../../../shared/src/abort-error.ts';\nimport {equals} from '../../../../../shared/src/set-utils.ts';\nimport {runTx} from '../../../db/run-transaction.ts';\nimport {type PostgresDB} from '../../../types/pg.ts';\nimport {cdcSchema, type ShardID} from '../../../types/shards.ts';\nimport type {\n  BackfillID,\n  Change,\n  TableMetadata,\n} from '../../change-source/protocol/current/data.ts';\nimport type {SubscriptionState} from '../../replicator/schema/replication-state.ts';\n\n// For readability in the sql statements.\nfunction schema(shard: ShardID) {\n  return ident(cdcSchema(shard));\n}\n\nexport const PG_SCHEMA = 'cdc';\n\nfunction createSchema(shard: ShardID) {\n  return /*sql*/ `CREATE SCHEMA IF NOT EXISTS ${schema(shard)};`;\n}\n\nexport type ChangeLogEntry = {\n  // A strictly monotonically increasing, lexicographically sortable\n  // value that uniquely identifies a position in the change stream.\n  watermark: string;\n  change: Change;\n};\n\ntype FullChangeLogEntry = ChangeLogEntry & {pos: number};\n\nfunction createChangeLogTable(shard: ShardID) {\n  // Note: The \"change\" column used to be JSONB, but that was problematic in that\n  // it does not handle the NULL unicode character.\n  // https://vladimir.varank.in/notes/2021/01/you-dont-insert-unicode-null-character-as-postgres-jsonb/\n  return /*sql*/ `\n  CREATE TABLE ${schema(shard)}.\"changeLog\" (\n    watermark  TEXT,\n    pos        INT8,\n    change     JSON NOT NULL,\n    precommit  TEXT,  -- Only exists on commit entries. Purely for debugging.\n    PRIMARY KEY (watermark, pos)\n  );\n`;\n}\n\n/**\n * Tracks the watermark from which to resume the change stream and the\n * current owner (task ID) acting as the single writer to the changeLog.\n */\nexport type ReplicationState = {\n  lastWatermark: string;\n  owner: string | null;\n  ownerAddress: string | null;\n};\n\nexport function createReplicationStateTable(shard: ShardID) {\n  return /*sql*/ `\n  CREATE TABLE ${schema(shard)}.\"replicationState\" (\n    \"lastWatermark\" TEXT NOT NULL,\n    \"owner\" TEXT,\n    \"ownerAddress\" TEXT,\n    \"lock\" INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n`;\n}\n\nexport async function discoverChangeStreamerAddress(\n  shard: ShardID,\n  sql: PostgresDB,\n): Promise<string | null> {\n  const result = await sql<{ownerAddress: string | null}[]> /*sql*/ `\n    SELECT \"ownerAddress\" FROM ${sql(cdcSchema(shard))}.\"replicationState\"`;\n  return result[0].ownerAddress;\n}\n\n/**\n * This mirrors the analogously named table in the SQLite replica\n * (`services/replicator/schema/replication-state.ts`), and is used\n * to detect when the replica has been reset and is no longer compatible\n * with the current ChangeLog.\n */\nexport type ReplicationConfig = {\n  replicaVersion: string;\n  publications: readonly string[];\n};\n\nfunction createReplicationConfigTable(shard: ShardID) {\n  return /*sql*/ `\n  CREATE TABLE ${schema(shard)}.\"replicationConfig\" (\n    \"replicaVersion\" TEXT NOT NULL,\n    \"publications\" TEXT[] NOT NULL,\n    \"resetRequired\" BOOL,\n    \"lock\" INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n  );\n`;\n}\n\nexport function createBackfillTables(shard: ShardID) {\n  return /*sql*/ `\n  CREATE TABLE ${schema(shard)}.\"tableMetadata\" (\n    \"schema\" TEXT NOT NULL,\n    \"table\" TEXT NOT NULL,\n    \"metadata\" JSONB NOT NULL,\n    PRIMARY KEY(\"schema\", \"table\")\n  );\n\n  CREATE TABLE ${schema(shard)}.\"backfilling\" (\n    \"schema\" TEXT NOT NULL,\n    \"table\" TEXT NOT NULL,\n    \"column\" TEXT NOT NULL,\n    \"backfill\" JSONB NOT NULL,\n    PRIMARY KEY(\"schema\", \"table\", \"column\")\n  );\n  `;\n}\n\nexport type TableMetadataRow = {\n  schema: string;\n  table: string;\n  metadata: TableMetadata;\n};\n\nexport type BackfillingColumn = {\n  schema: string;\n  table: string;\n  column: string;\n  backfill: BackfillID;\n};\n\nfunction createTables(shard: ShardID) {\n  return (\n    createSchema(shard) +\n    createChangeLogTable(shard) +\n    createReplicationStateTable(shard) +\n    createReplicationConfigTable(shard) +\n    createBackfillTables(shard)\n  );\n}\n\ninterface PurgeLock {\n  release(): Promise<void>;\n}\n\nexport async function setupCDCTables(\n  lc: LogContext,\n  db: postgres.TransactionSql,\n  shard: ShardID,\n) {\n  lc.info?.(`Setting up CDC tables`);\n  await db.unsafe(createTables(shard));\n}\n\nexport async function markResetRequired(sql: PostgresDB, shard: ShardID) {\n  const schema = cdcSchema(shard);\n  await sql`\n  UPDATE ${sql(schema)}.\"replicationConfig\"\n    SET \"resetRequired\" = true`;\n}\n\nexport async function ensureReplicationConfig(\n  lc: LogContext,\n  db: PostgresDB,\n  subscriptionState: Pick<\n    SubscriptionState,\n    'publications' | 'replicaVersion' | 'watermark'\n  >,\n  shard: ShardID,\n  autoReset: boolean,\n  purgeLock?: PurgeLock,\n  setTimeoutFn: typeof setTimeout = setTimeout,\n) {\n  const {publications, replicaVersion, watermark} = subscriptionState;\n  const replicaConfig = {publications, replicaVersion};\n  const replicationState: ReplicationState = {\n    lastWatermark: replicaVersion,\n    owner: null,\n    ownerAddress: null,\n  };\n  const schema = cdcSchema(shard);\n\n  await runTx(db, async sql => {\n    const stmts: PendingQuery<Row[]>[] = [];\n    let needsTruncate = false;\n    const results = await sql<\n      {\n        replicaVersion: string;\n        publications: string[];\n        resetRequired: boolean | null;\n      }[]\n    > /*sql*/ `\n    SELECT \"replicaVersion\", \"publications\", \"resetRequired\" \n      FROM ${sql(schema)}.\"replicationConfig\"`;\n\n    if (results.length) {\n      const {replicaVersion, publications} = results[0];\n      if (\n        replicaVersion !== replicaConfig.replicaVersion ||\n        !equals(new Set(publications), new Set(replicaConfig.publications))\n      ) {\n        if (replicaConfig.replicaVersion !== watermark) {\n          throw new AutoResetSignal(\n            `Cannot reset change db@${replicaVersion} to ` +\n              `service replica@${replicaConfig.replicaVersion} ` +\n              `from watermark ${watermark}`,\n          );\n        }\n        lc.info?.(\n          `Data in cdc tables @${replicaVersion} is incompatible ` +\n            `with replica @${replicaConfig.replicaVersion}. Clearing tables.`,\n        );\n        // Release any purge lock held by the caller; the changeLog is\n        // incompatible with the replica and needs to be truncated.\n        void purgeLock?.release();\n\n        // Note: The order of TRUNCATE matters. The replicationState table is\n        //       truncated before the changeLog table, in order to acquire\n        //       (exclusive) locks on the tables in the same order that the\n        //       storer.ts acquires locks when writing the changeLog, namely:\n        //\n        // 1. SELECT ... FROM replicationState FOR UPDATE;\n        // 2. INSERT INTO changeLog ...;\n        //    ...\n        // n. UPDATE replicationState ...;\n        needsTruncate = true;\n        stmts.push(\n          sql`TRUNCATE TABLE ${sql(schema)}.\"replicationState\"`,\n          sql`TRUNCATE TABLE ${sql(schema)}.\"changeLog\"`,\n          sql`TRUNCATE TABLE ${sql(schema)}.\"replicationConfig\"`,\n          sql`TRUNCATE TABLE ${sql(schema)}.\"tableMetadata\"`,\n          sql`TRUNCATE TABLE ${sql(schema)}.\"backfilling\"`,\n        );\n      }\n    }\n    // Initialize (or re-initialize TRUNCATED) tables\n    if (results.length === 0 || needsTruncate) {\n      // The storer uses the earliest changeLog entry as the safe watermark\n      // from which subscribers can be resumed. These initial entries ensure\n      // that subscribers can start from a freshly synced replica, even if\n      // new changes have been replicated and not purged from the changeLog.\n      //\n      // TODO: Replace this with an explicit `firstWatermark` column in the\n      //       change db.\n      const watermark = replicaConfig.replicaVersion;\n      const initialTx: FullChangeLogEntry[] = [\n        {watermark, pos: 0, change: {tag: 'begin'}},\n        {watermark, pos: 1, change: {tag: 'commit'}},\n      ];\n\n      stmts.push(\n        sql`INSERT INTO ${sql(schema)}.\"replicationConfig\" ${sql(replicaConfig)}`,\n        sql`INSERT INTO ${sql(schema)}.\"replicationState\"  ${sql(replicationState)} \n              ON CONFLICT (lock) DO UPDATE SET ${sql(replicationState)}`,\n        ...initialTx.map(\n          change => sql`INSERT INTO ${sql(schema)}.\"changeLog\" ${sql(change)}`,\n        ),\n      );\n\n      if (needsTruncate) {\n        // The TRUNCATE statements require ACCESS EXCLUSIVE locks, which may\n        // be blocked by old storer catchup reads. Race against a timeout\n        // that terminates the blocking backends if the TRUNCATE takes too\n        // long.\n        const timer = setTimeoutFn(async () => {\n          lc.info?.(\n            'ensureReplicationConfig blocked, terminating lock holders',\n          );\n          await terminateChangeDBLockHolders(lc, db, shard);\n        }, LOCK_HOLDER_TERMINATE_TIMEOUT_MS);\n        try {\n          return await Promise.all(stmts);\n        } finally {\n          clearTimeout(timer);\n        }\n      }\n      return Promise.all(stmts);\n    }\n\n    const {resetRequired} = results[0];\n    if (resetRequired) {\n      if (autoReset) {\n        throw new AutoResetSignal('reset required by replication stream');\n      }\n      lc.error?.(\n        '\\n\\n\\n' +\n          'Reset required but --auto-reset is not enabled.\\n' +\n          'This can happen for upstream databases that do not support event triggers.\\n' +\n          'To correct this, see https://zero.rocicorp.dev/docs/connecting-to-postgres#schema-changes' +\n          '\\n\\n\\n',\n      );\n    }\n\n    return [];\n  });\n}\n\n// The time to wait for a TRUNCATE in ensureReplicationConfig before\n// terminating blocking backends via terminateChangeDBLockHolders.\nconst LOCK_HOLDER_TERMINATE_TIMEOUT_MS = 5_000;\n\nexport const CHANGE_STREAMER_APP_NAME = 'zero-change-streamer';\n\nexport class AutoResetSignal extends AbortError {\n  readonly name = 'AutoResetSignal';\n}\n\n/**\n * Terminates zero-cache backends that are blocking the current backend\n * from acquiring locks on CDC tables (e.g., during TRUNCATE).\n *\n * This is used during change-DB takeover when the new replication-manager's\n * `ensureReplicationConfig` needs to TRUNCATE tables, but the old\n * replication-manager's storer is still reading from them (e.g., large\n * catchup cursors).\n *\n * The function:\n * 1. Finds backends waiting for a lock on a TRUNCATE in {schema}\n * 2. Uses `pg_blocking_pids()` to identify which backends are blocking them\n * 3. Terminates blocking backends that have `application_name = 'zero-change-streamer'`\n *\n * Must be called on a **separate connection** from the one that is blocked,\n * since the blocked connection is inside a pending transaction.\n */\nexport async function terminateChangeDBLockHolders(\n  lc: LogContext,\n  db: PostgresDB,\n  shard: ShardID,\n) {\n  const schema = cdcSchema(shard);\n\n  // Step 1: Find backends that are blocked waiting for a lock,\n  // whose query involves a TRUNCATE on this shard's CDC schema.\n  const blocked = await db<{pid: number}[]>`\n    SELECT pid FROM pg_stat_activity\n      WHERE wait_event_type = 'Lock'\n        AND application_name = ${CHANGE_STREAMER_APP_NAME}\n        AND query LIKE ${'%TRUNCATE%' + schema + '%'}`;\n\n  if (blocked.length === 0) {\n    lc.info?.('no blocked TRUNCATE backends found');\n    return;\n  }\n\n  const blockedPids = blocked.map(r => r.pid);\n  lc.info?.(`found blocked TRUNCATE backends: ${JSON.stringify(blockedPids)}`);\n\n  // Step 2: For each blocked backend, find and terminate its blockers\n  // that are zero-change-streamer connections.\n  const terminated = await db<\n    {pid: number; applicationName: string; query: string; terminated: boolean}[]\n  >`\n    SELECT pid, application_name as \"applicationName\", query,\n           pg_terminate_backend(pid) as terminated\n      FROM pg_stat_activity\n      WHERE pid = ANY(\n        SELECT unnest(pg_blocking_pids(blocked.pid))\n          FROM unnest(${blockedPids}::int[]) AS blocked(pid)\n      )\n      AND application_name = ${CHANGE_STREAMER_APP_NAME}\n      AND pid != ALL(${blockedPids}::int[])`;\n\n  if (terminated.length === 0) {\n    lc.info?.(`no ${CHANGE_STREAMER_APP_NAME} blockers found to terminate`);\n  } else {\n    for (const {pid, applicationName, query, terminated: ok} of terminated) {\n      lc.info?.(\n        `terminated blocking backend pid=${pid} app=${applicationName} ok=${ok} query=${query.slice(0, 200)}`,\n      );\n    }\n  }\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/change-streamer/shard-sampling.d.ts

@@ -0,0 +1,11 @@
+import type { ShardID } from '../../types/shards.ts';
+/**
+ * Stable percentage sampling keyed by shard and an arbitrary identity: a
+ * subscriber's task for read routing, a watermark for catchup comparison.
+ *
+ * The same key always lands in the same bucket, so raising `percent` only ever
+ * adds to the sampled set, and every process in a shard agrees on the set
+ * without coordinating.
+ */
+export declare function isSampledForShard(shard: ShardID, key: string, percent: number): boolean;
+//# sourceMappingURL=shard-sampling.d.ts.map

package/out/zero-cache/src/services/change-streamer/shard-sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-sampling.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/shard-sampling.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,uBAAuB,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,OAAO,CAQT"}

package/out/zero-cache/src/services/change-streamer/shard-sampling.js

@@ -0,0 +1,19 @@
+import { h32 } from "../../../../shared/src/hash.js";
+//#region ../zero-cache/src/services/change-streamer/shard-sampling.ts
+/**
+* Stable percentage sampling keyed by shard and an arbitrary identity: a
+* subscriber's task for read routing, a watermark for catchup comparison.
+*
+* The same key always lands in the same bucket, so raising `percent` only ever
+* adds to the sampled set, and every process in a shard agrees on the set
+* without coordinating.
+*/
+function isSampledForShard(shard, key, percent) {
+	if (percent >= 100) return true;
+	if (percent <= 0) return false;
+	return h32(`${shard.appID}/${shard.shardNum}:${key}`) % 100 < percent;
+}
+//#endregion
+export { isSampledForShard };
+
+//# sourceMappingURL=shard-sampling.js.map

package/out/zero-cache/src/services/change-streamer/shard-sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-sampling.js","names":[],"sources":["../../../../../../zero-cache/src/services/change-streamer/shard-sampling.ts"],"sourcesContent":["import {h32} from '../../../../shared/src/hash.ts';\nimport type {ShardID} from '../../types/shards.ts';\n\n/**\n * Stable percentage sampling keyed by shard and an arbitrary identity: a\n * subscriber's task for read routing, a watermark for catchup comparison.\n *\n * The same key always lands in the same bucket, so raising `percent` only ever\n * adds to the sampled set, and every process in a shard agrees on the set\n * without coordinating.\n */\nexport function isSampledForShard(\n  shard: ShardID,\n  key: string,\n  percent: number,\n): boolean {\n  if (percent >= 100) {\n    return true;\n  }\n  if (percent <= 0) {\n    return false;\n  }\n  return h32(`${shard.appID}/${shard.shardNum}:${key}`) % 100 < percent;\n}\n"],"mappings":";;;;;;;;;;AAWA,SAAgB,kBACd,OACA,KACA,SACS;CACT,IAAI,WAAW,KACb,OAAO;CAET,IAAI,WAAW,GACb,OAAO;CAET,OAAO,IAAI,GAAG,MAAM,MAAM,GAAG,MAAM,SAAS,GAAG,KAAK,IAAI,MAAM;AAChE"}

package/out/zero-cache/src/services/change-streamer/snapshot-reservations.d.ts

@@ -0,0 +1,24 @@
+import type { LogContext } from '@rocicorp/logger';
+import type { Source } from '../../types/streams.ts';
+import type { BackupConfig } from './change-streamer-service.ts';
+import type { SnapshotMessage } from './snapshot.ts';
+import type { ChangeLogReadSource } from './sqlite-change-log-read-router.ts';
+export declare class SnapshotReservations {
+    #private;
+    constructor(lc: LogContext, backupConfig: BackupConfig, onClose?: ((taskID: string) => void) | undefined);
+    open(taskID: string): Source<SnapshotMessage>;
+    close(taskID: string): void;
+    isCurrent(taskID: string, source: Source<SnapshotMessage>): boolean;
+    confirmationsRequired(): boolean;
+    unconfirmedTaskIDs(): string[];
+    /** Confirms one reservation with the bounds of its pinned read source. */
+    confirmFor(taskID: string, replicaVersion: string, minWatermark: string, source: ChangeLogReadSource): void;
+    /**
+     * Notes that a confirmation was deferred, returning true only the first time
+     * for this reservation. Confirmation is retried on every backup, so an
+     * undeduplicated count would measure backups rather than delayed followers.
+     */
+    noteConfirmationDelayed(taskID: string): boolean;
+    getReservedWatermarks(): string[];
+}
+//# sourceMappingURL=snapshot-reservations.d.ts.map

package/out/zero-cache/src/services/change-streamer/snapshot-reservations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-reservations.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot-reservations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,wBAAwB,CAAC;AAOnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oCAAoC,CAAC;AAE5E,qBAAa,oBAAoB;;gBAO7B,EAAE,EAAE,UAAU,EACd,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS;IAOlD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC;IAY7C,KAAK,CAAC,MAAM,EAAE,MAAM;IAIpB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,eAAe,CAAC,GAAG,OAAO;IAwCnE,qBAAqB;IASrB,kBAAkB,IAAI,MAAM,EAAE;IAM9B,0EAA0E;IAC1E,UAAU,CACR,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,mBAAmB,GAC1B,IAAI;IAgBP;;;;OAIG;IACH,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIhD,qBAAqB;CAMtB"}

package/out/zero-cache/src/services/change-streamer/snapshot-reservations.js

@@ -0,0 +1,119 @@
+import { Subscription } from "../../types/subscription.js";
+import { litestreamMonitorMetricAttrs, litestreamSnapshotReservationConfirmDuration, litestreamSnapshotReservationDuration } from "../litestream/metrics.js";
+//#region ../zero-cache/src/services/change-streamer/snapshot-reservations.ts
+var SnapshotReservations = class {
+	#lc;
+	#backupConfig;
+	#onClose;
+	#reservations = /* @__PURE__ */ new Map();
+	constructor(lc, backupConfig, onClose) {
+		this.#lc = lc.withContext("component", "snapshot-reserver");
+		this.#backupConfig = backupConfig;
+		this.#onClose = onClose;
+	}
+	open(taskID) {
+		this.close(taskID);
+		const instanceID = {};
+		const downstream = Subscription.create({ cleanup: () => this.#close(taskID, instanceID) });
+		this.#reservations.set(taskID, new Reservation(instanceID, downstream));
+		this.#lc.info?.(`created snasphot reservation for ${taskID}`);
+		return downstream;
+	}
+	close(taskID) {
+		this.#close(taskID, void 0);
+	}
+	isCurrent(taskID, source) {
+		return this.#reservations.get(taskID)?.owns(source) ?? false;
+	}
+	#metricAttrs() {
+		return litestreamMonitorMetricAttrs(this.#backupConfig.backupURL, this.#backupConfig.litestreamVersion, "view_syncer");
+	}
+	#close(taskID, cancelledInstanceID) {
+		const res = this.#reservations.get(taskID);
+		if (res && (!cancelledInstanceID || res.instanceID === cancelledInstanceID)) {
+			this.#reservations.delete(taskID);
+			this.#onClose?.(taskID);
+			res.close();
+			const duration = Date.now() - res.startTime.getTime();
+			this.#lc.info?.(`ended snapshot reservation for ${taskID} (${duration} ms)`);
+			litestreamSnapshotReservationDuration().recordMs(duration, {
+				...this.#metricAttrs(),
+				result: cancelledInstanceID ? "cancelled" : "closed",
+				confirmed: res.confirmed()
+			});
+		}
+	}
+	confirmationsRequired() {
+		for (const res of this.#reservations.values()) if (!res.confirmed()) return true;
+		return false;
+	}
+	unconfirmedTaskIDs() {
+		return [...this.#reservations.entries()].filter(([, reservation]) => !reservation.confirmed()).map(([taskID]) => taskID);
+	}
+	/** Confirms one reservation with the bounds of its pinned read source. */
+	confirmFor(taskID, replicaVersion, minWatermark, source) {
+		const res = this.#reservations.get(taskID);
+		if (res && !res.confirmed()) {
+			this.#lc.info?.(`reserving change-log entries since ${minWatermark} for ${taskID}`);
+			res.confirm(this.#backupConfig.backupURL, replicaVersion, minWatermark);
+			litestreamSnapshotReservationConfirmDuration().recordMs(Date.now() - res.startTime.getTime(), {
+				...this.#metricAttrs(),
+				source
+			});
+		}
+	}
+	/**
+	* Notes that a confirmation was deferred, returning true only the first time
+	* for this reservation. Confirmation is retried on every backup, so an
+	* undeduplicated count would measure backups rather than delayed followers.
+	*/
+	noteConfirmationDelayed(taskID) {
+		return this.#reservations.get(taskID)?.noteDelayed() ?? false;
+	}
+	getReservedWatermarks() {
+		return Array.from(this.#reservations.values(), ({ reservedWatermark }) => reservedWatermark).filter((watermark) => watermark !== null);
+	}
+};
+var Reservation = class {
+	instanceID;
+	startTime = /* @__PURE__ */ new Date();
+	#downstream;
+	#watermark = null;
+	#delayNoted = false;
+	constructor(instanceID, downstream) {
+		this.instanceID = instanceID;
+		this.#downstream = downstream;
+	}
+	get reservedWatermark() {
+		return this.#watermark;
+	}
+	confirmed() {
+		return this.#watermark !== null;
+	}
+	owns(source) {
+		return this.#downstream === source;
+	}
+	noteDelayed() {
+		if (this.#delayNoted) return false;
+		this.#delayNoted = true;
+		return true;
+	}
+	confirm(backupURL, replicaVersion, minWatermark) {
+		if (this.#watermark === null) {
+			if (this.#downstream.active) this.#downstream.push(["status", {
+				tag: "status",
+				backupURL,
+				replicaVersion,
+				minWatermark
+			}]);
+			this.#watermark = minWatermark;
+		}
+	}
+	close() {
+		this.#downstream.cancel();
+	}
+};
+//#endregion
+export { SnapshotReservations };
+
+//# sourceMappingURL=snapshot-reservations.js.map

package/out/zero-cache/src/services/change-streamer/snapshot-reservations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-reservations.js","names":["#lc","#backupConfig","#onClose","#reservations","#close","#metricAttrs","#downstream","#watermark","#delayNoted"],"sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot-reservations.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport type {Source} from '../../types/streams.ts';\nimport {Subscription} from '../../types/subscription.ts';\nimport {\n  litestreamMonitorMetricAttrs,\n  litestreamSnapshotReservationConfirmDuration,\n  litestreamSnapshotReservationDuration,\n} from '../litestream/metrics.ts';\nimport type {BackupConfig} from './change-streamer-service.ts';\nimport type {SnapshotMessage} from './snapshot.ts';\nimport type {ChangeLogReadSource} from './sqlite-change-log-read-router.ts';\n\nexport class SnapshotReservations {\n  readonly #lc: LogContext;\n  readonly #backupConfig: BackupConfig;\n  readonly #onClose: ((taskID: string) => void) | undefined;\n  readonly #reservations = new Map<string, Reservation>();\n\n  constructor(\n    lc: LogContext,\n    backupConfig: BackupConfig,\n    onClose?: ((taskID: string) => void) | undefined,\n  ) {\n    this.#lc = lc.withContext('component', 'snapshot-reserver');\n    this.#backupConfig = backupConfig;\n    this.#onClose = onClose;\n  }\n\n  open(taskID: string): Source<SnapshotMessage> {\n    this.close(taskID);\n\n    const instanceID = {};\n    const downstream = Subscription.create<SnapshotMessage>({\n      cleanup: () => this.#close(taskID, instanceID),\n    });\n    this.#reservations.set(taskID, new Reservation(instanceID, downstream));\n    this.#lc.info?.(`created snasphot reservation for ${taskID}`);\n    return downstream;\n  }\n\n  close(taskID: string) {\n    this.#close(taskID, undefined);\n  }\n\n  isCurrent(taskID: string, source: Source<SnapshotMessage>): boolean {\n    return this.#reservations.get(taskID)?.owns(source) ?? false;\n  }\n\n  #metricAttrs() {\n    return litestreamMonitorMetricAttrs(\n      this.#backupConfig.backupURL,\n      this.#backupConfig.litestreamVersion,\n      'view_syncer',\n    );\n  }\n\n  #close(taskID: string, cancelledInstanceID: InstanceID | undefined) {\n    const res = this.#reservations.get(taskID);\n    if (\n      res &&\n      (!cancelledInstanceID || res.instanceID === cancelledInstanceID)\n    ) {\n      // Note: delete first, so that the reservation is gone when close() is called.\n      this.#reservations.delete(taskID);\n      this.#onClose?.(taskID);\n      res.close();\n\n      const duration = Date.now() - res.startTime.getTime();\n      this.#lc.info?.(\n        `ended snapshot reservation for ${taskID} (${duration} ms)`,\n      );\n      // `result` reports how the reservation ended and `confirmed` whether it\n      // ever received its bounds. They are separate dimensions: a follower\n      // that gives up while waiting for a confirmation is\n      // `result=cancelled, confirmed=false`, which a single collapsed\n      // attribute cannot distinguish from a client that simply went away.\n      litestreamSnapshotReservationDuration().recordMs(duration, {\n        ...this.#metricAttrs(),\n        result: cancelledInstanceID ? 'cancelled' : 'closed',\n        confirmed: res.confirmed(),\n      });\n    }\n  }\n\n  confirmationsRequired() {\n    for (const res of this.#reservations.values()) {\n      if (!res.confirmed()) {\n        return true;\n      }\n    }\n    return false;\n  }\n\n  unconfirmedTaskIDs(): string[] {\n    return [...this.#reservations.entries()]\n      .filter(([, reservation]) => !reservation.confirmed())\n      .map(([taskID]) => taskID);\n  }\n\n  /** Confirms one reservation with the bounds of its pinned read source. */\n  confirmFor(\n    taskID: string,\n    replicaVersion: string,\n    minWatermark: string,\n    source: ChangeLogReadSource,\n  ): void {\n    const res = this.#reservations.get(taskID);\n    if (res && !res.confirmed()) {\n      this.#lc.info?.(\n        `reserving change-log entries since ${minWatermark} for ${taskID}`,\n      );\n      res.confirm(this.#backupConfig.backupURL, replicaVersion, minWatermark);\n      // Measured from `open()`, not from the first confirmation attempt: what\n      // matters is how long the follower waited before it could restore.\n      litestreamSnapshotReservationConfirmDuration().recordMs(\n        Date.now() - res.startTime.getTime(),\n        {...this.#metricAttrs(), source},\n      );\n    }\n  }\n\n  /**\n   * Notes that a confirmation was deferred, returning true only the first time\n   * for this reservation. Confirmation is retried on every backup, so an\n   * undeduplicated count would measure backups rather than delayed followers.\n   */\n  noteConfirmationDelayed(taskID: string): boolean {\n    return this.#reservations.get(taskID)?.noteDelayed() ?? false;\n  }\n\n  getReservedWatermarks() {\n    return Array.from(\n      this.#reservations.values(),\n      ({reservedWatermark}) => reservedWatermark,\n    ).filter(watermark => watermark !== null);\n  }\n}\n\ntype InstanceID = {};\n\nclass Reservation {\n  readonly instanceID: InstanceID;\n  readonly startTime: Date = new Date();\n  readonly #downstream: Subscription<SnapshotMessage>;\n  #watermark: string | null = null;\n  #delayNoted = false;\n\n  constructor(\n    instanceID: InstanceID,\n    downstream: Subscription<SnapshotMessage>,\n  ) {\n    this.instanceID = instanceID;\n    this.#downstream = downstream;\n  }\n\n  get reservedWatermark() {\n    return this.#watermark;\n  }\n\n  confirmed() {\n    return this.#watermark !== null;\n  }\n\n  owns(source: Source<SnapshotMessage>): boolean {\n    return this.#downstream === source;\n  }\n\n  noteDelayed(): boolean {\n    if (this.#delayNoted) {\n      return false;\n    }\n    this.#delayNoted = true;\n    return true;\n  }\n\n  confirm(backupURL: string, replicaVersion: string, minWatermark: string) {\n    if (this.#watermark === null) {\n      if (this.#downstream.active) {\n        this.#downstream.push([\n          'status',\n          {tag: 'status', backupURL, replicaVersion, minWatermark},\n        ]);\n      }\n      this.#watermark = minWatermark;\n    }\n  }\n\n  close() {\n    this.#downstream.cancel();\n  }\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/change-streamer/snapshot.d.ts

@@ -1,5 +1,5 @@
 /**
- * Definitions for the `snapshot` API, which serves the purpose of:
+ * The `snapshot` API serves the purpose of:
  * - informing subscribers (i.e. view-syncers) of the (litestream)
  *   backup location from which to restore a replica snapshot
  * - checking whether a restored backup or existing replica is
@@ -11,7 +11,9 @@
  *   serves as the minimum interval to wait before cleaning up
  *   backed up changes.
  */
+import type { LogContext } from '@rocicorp/logger';
 import * as v from '../../../../shared/src/valita.ts';
+import { type NormalizedZeroConfig } from '../../config/normalize.ts';
 declare const statusSchema: v.ObjectType<{
     tag: v.Type<"status">;
     /**
@@ -77,5 +79,6 @@ export declare const snapshotMessageSchema: v.UnionType<[v.TupleType<[v.Type<"st
     minWatermark: v.Type<string>;
 }, undefined>]>]>;
 export type SnapshotMessage = v.Infer<typeof statusMessageSchema>;
+export declare function reserveAndGetSnapshotStatus(lc: LogContext, config: NormalizedZeroConfig): Promise<SnapshotStatus>;
 export {};
 //# sourceMappingURL=snapshot.d.ts.map

package/out/zero-cache/src/services/change-streamer/snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,CAAC,MAAM,kCAAkC,CAAC;AAEtD,QAAA,MAAM,YAAY;;IAGhB;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;aAEH,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAE1D,QAAA,MAAM,mBAAmB;;IAxBvB;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;eAMmE,CAAC;AAEzE,eAAO,MAAM,qBAAqB;;IA1BhC;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;iBAQ4D,CAAC;AAElE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,CAAC,MAAM,kCAAkC,CAAC;AACtD,OAAO,EAAC,KAAK,oBAAoB,EAAC,MAAM,2BAA2B,CAAC;AAKpE,QAAA,MAAM,YAAY;;IAGhB;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;aAEH,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAE1D,QAAA,MAAM,mBAAmB;;IAxBvB;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;eAMmE,CAAC;AAEzE,eAAO,MAAM,qBAAqB;;IA1BhC;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;iBAQ4D,CAAC;AAElE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAElE,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAiDzB"}

package/out/zero-cache/src/services/change-streamer/snapshot.js

@@ -1,18 +1,10 @@
+import { sleep } from "../../../../shared/src/sleep.js";
 import { valita_exports } from "../../../../shared/src/valita.js";
+import { getShardConfig } from "../../types/shards.js";
+import "../../config/normalize.js";
+import { ChangeStreamerHttpClient } from "./change-streamer-http.js";
+import { resolver } from "@rocicorp/resolver";
 //#region ../zero-cache/src/services/change-streamer/snapshot.ts
-/**
-* Definitions for the `snapshot` API, which serves the purpose of:
-* - informing subscribers (i.e. view-syncers) of the (litestream)
-*   backup location from which to restore a replica snapshot
-* - checking whether a restored backup or existing replica is
-*   compatible with the change-streamer
-* - preventing change-log cleanup while a snapshot restore is in
-*   progress
-* - tracking the approximate time it takes from the beginning of
-*   snapshot "reservation" to the subsequent subscription, which
-*   serves as the minimum interval to wait before cleaning up
-*   backed up changes.
-*/
 var statusSchema = valita_exports.object({
 	tag: valita_exports.literal("status"),
 	/**
@@ -36,7 +28,40 @@ var statusSchema = valita_exports.object({
 });
 var statusMessageSchema = valita_exports.tuple([valita_exports.literal("status"), statusSchema]);
 var snapshotMessageSchema = valita_exports.union(statusMessageSchema);
+function reserveAndGetSnapshotStatus(lc, config) {
+	const { promise: status, resolve, reject } = resolver();
+	(async function() {
+		const abort = new AbortController();
+		process.on("SIGINT", () => abort.abort());
+		process.on("SIGTERM", () => abort.abort());
+		for (let i = 0;; i++) {
+			let err;
+			try {
+				let resolved = false;
+				const stream = await reserveSnapshot(lc, config);
+				for await (const msg of stream) {
+					resolve(msg[1]);
+					resolved = true;
+				}
+				if (resolved) break;
+			} catch (e) {
+				err = e;
+			}
+			lc.warn?.(`Unable to reserve snapshot (attempt ${i + 1}). Retrying in 5 seconds.`, String(err));
+			try {
+				await sleep(5e3, abort.signal);
+			} catch (e) {
+				return reject(e);
+			}
+		}
+	})();
+	return status;
+}
+function reserveSnapshot(lc, config) {
+	const { taskID, change, changeStreamer } = config;
+	return new ChangeStreamerHttpClient(lc, getShardConfig(config), change.db, changeStreamer.uri).reserveSnapshot(taskID);
+}
 //#endregion
-export { snapshotMessageSchema };
+export { reserveAndGetSnapshotStatus, snapshotMessageSchema };
 
 //# sourceMappingURL=snapshot.js.map

package/out/zero-cache/src/services/change-streamer/snapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.js","names":[],"sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot.ts"],"sourcesContent":["/**\n * Definitions for the `snapshot` API, which serves the purpose of:\n * - informing subscribers (i.e. view-syncers) of the (litestream)\n *   backup location from which to restore a replica snapshot\n * - checking whether a restored backup or existing replica is\n *   compatible with the change-streamer\n * - preventing change-log cleanup while a snapshot restore is in\n *   progress\n * - tracking the approximate time it takes from the beginning of\n *   snapshot \"reservation\" to the subsequent subscription, which\n *   serves as the minimum interval to wait before cleaning up\n *   backed up changes.\n */\n\nimport * as v from '../../../../shared/src/valita.ts';\n\nconst statusSchema = v.object({\n  tag: v.literal('status'),\n\n  /**\n   * The location from which litestream should perform the restore.\n   */\n  backupURL: v.string(),\n\n  /**\n   * The `replicaVersion` of the backup. If a subscriber's restored or\n   * existing replica is of a different version, it should delete it and\n   * retry the restore from litestream (i.e. equivalent to a\n   * `WrongReplicaVersion` response from a `/changes` subscription).\n   */\n  replicaVersion: v.string(),\n\n  /**\n   * The earliest watermark from which catchup is possible. If the\n   * subscriber's replica is older that this watermark, it should delete it\n   * and (retry the) restore from litestream (i.e. equivalent to a\n   * `WatermarkTooOld` response from a `/changes` subscription).\n   */\n  minWatermark: v.string(),\n});\n\nexport type SnapshotStatus = v.Infer<typeof statusSchema>;\n\nconst statusMessageSchema = v.tuple([v.literal('status'), statusSchema]);\n\nexport const snapshotMessageSchema = v.union(statusMessageSchema);\n\nexport type SnapshotMessage = v.Infer<typeof statusMessageSchema>;\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,IAAM,eAAe,eAAE,OAAO;CAC5B,KAAK,eAAE,QAAQ,QAAQ;;;;CAKvB,WAAW,eAAE,OAAO;;;;;;;CAQpB,gBAAgB,eAAE,OAAO;;;;;;;CAQzB,cAAc,eAAE,OAAO;AACzB,CAAC;AAID,IAAM,sBAAsB,eAAE,MAAM,CAAC,eAAE,QAAQ,QAAQ,GAAG,YAAY,CAAC;AAEvE,IAAa,wBAAwB,eAAE,MAAM,mBAAmB"}
+{"version":3,"file":"snapshot.js","names":[],"sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot.ts"],"sourcesContent":["/**\n * The `snapshot` API serves the purpose of:\n * - informing subscribers (i.e. view-syncers) of the (litestream)\n *   backup location from which to restore a replica snapshot\n * - checking whether a restored backup or existing replica is\n *   compatible with the change-streamer\n * - preventing change-log cleanup while a snapshot restore is in\n *   progress\n * - tracking the approximate time it takes from the beginning of\n *   snapshot \"reservation\" to the subsequent subscription, which\n *   serves as the minimum interval to wait before cleaning up\n *   backed up changes.\n */\n\nimport type {LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport {sleep} from '../../../../shared/src/sleep.ts';\nimport * as v from '../../../../shared/src/valita.ts';\nimport {type NormalizedZeroConfig} from '../../config/normalize.ts';\nimport {getShardConfig} from '../../types/shards.ts';\nimport type {Source} from '../../types/streams.ts';\nimport {ChangeStreamerHttpClient} from './change-streamer-http.ts';\n\nconst statusSchema = v.object({\n  tag: v.literal('status'),\n\n  /**\n   * The location from which litestream should perform the restore.\n   */\n  backupURL: v.string(),\n\n  /**\n   * The `replicaVersion` of the backup. If a subscriber's restored or\n   * existing replica is of a different version, it should delete it and\n   * retry the restore from litestream (i.e. equivalent to a\n   * `WrongReplicaVersion` response from a `/changes` subscription).\n   */\n  replicaVersion: v.string(),\n\n  /**\n   * The earliest watermark from which catchup is possible. If the\n   * subscriber's replica is older that this watermark, it should delete it\n   * and (retry the) restore from litestream (i.e. equivalent to a\n   * `WatermarkTooOld` response from a `/changes` subscription).\n   */\n  minWatermark: v.string(),\n});\n\nexport type SnapshotStatus = v.Infer<typeof statusSchema>;\n\nconst statusMessageSchema = v.tuple([v.literal('status'), statusSchema]);\n\nexport const snapshotMessageSchema = v.union(statusMessageSchema);\n\nexport type SnapshotMessage = v.Infer<typeof statusMessageSchema>;\n\nexport function reserveAndGetSnapshotStatus(\n  lc: LogContext,\n  config: NormalizedZeroConfig,\n): Promise<SnapshotStatus> {\n  const {promise: status, resolve, reject} = resolver<SnapshotStatus>();\n\n  void (async function () {\n    const abort = new AbortController();\n    process.on('SIGINT', () => abort.abort());\n    process.on('SIGTERM', () => abort.abort());\n\n    for (let i = 0; ; i++) {\n      let err: unknown;\n      try {\n        let resolved = false;\n        const stream = await reserveSnapshot(lc, config);\n        for await (const msg of stream) {\n          // Capture the value of the status message that the change-streamer\n          // backup monitor returns, and hold the connection open to\n          // \"reserve\" the snapshot and prevent change log cleanup.\n          resolve(msg[1]);\n          resolved = true;\n        }\n        // The change-streamer itself closes the connection when the\n        // subscription is started (or the reservation retried).\n        if (resolved) {\n          break;\n        }\n      } catch (e) {\n        err = e;\n      }\n      // Retry in the view-syncer since it cannot proceed until it connects\n      // to a (compatible) replication-manager. In particular, a\n      // replication-manager that does not support the view-syncer's\n      // change-streamer protocol will close the stream with an error; this\n      // retry logic essentially delays the startup of a view-syncer until\n      // a compatible replication-manager has been rolled out, allowing\n      // replication-manager and view-syncer services to be updated in\n      // parallel.\n      lc.warn?.(\n        `Unable to reserve snapshot (attempt ${i + 1}). Retrying in 5 seconds.`,\n        String(err),\n      );\n      try {\n        await sleep(5000, abort.signal);\n      } catch (e) {\n        return reject(e);\n      }\n    }\n  })();\n\n  return status;\n}\n\nfunction reserveSnapshot(\n  lc: LogContext,\n  config: NormalizedZeroConfig,\n): Promise<Source<SnapshotMessage>> {\n  const {taskID, change, changeStreamer} = config;\n  const shardID = getShardConfig(config);\n\n  const changeStreamerClient = new ChangeStreamerHttpClient(\n    lc,\n    shardID,\n    change.db,\n    changeStreamer.uri,\n  );\n\n  return changeStreamerClient.reserveSnapshot(taskID);\n}\n"],"mappings":";;;;;;;AAuBA,IAAM,eAAe,eAAE,OAAO;CAC5B,KAAK,eAAE,QAAQ,QAAQ;;;;CAKvB,WAAW,eAAE,OAAO;;;;;;;CAQpB,gBAAgB,eAAE,OAAO;;;;;;;CAQzB,cAAc,eAAE,OAAO;AACzB,CAAC;AAID,IAAM,sBAAsB,eAAE,MAAM,CAAC,eAAE,QAAQ,QAAQ,GAAG,YAAY,CAAC;AAEvE,IAAa,wBAAwB,eAAE,MAAM,mBAAmB;AAIhE,SAAgB,4BACd,IACA,QACyB;CACzB,MAAM,EAAC,SAAS,QAAQ,SAAS,WAAU,SAAyB;CAEpE,CAAM,iBAAkB;EACtB,MAAM,QAAQ,IAAI,gBAAgB;EAClC,QAAQ,GAAG,gBAAgB,MAAM,MAAM,CAAC;EACxC,QAAQ,GAAG,iBAAiB,MAAM,MAAM,CAAC;EAEzC,KAAK,IAAI,IAAI,IAAK,KAAK;GACrB,IAAI;GACJ,IAAI;IACF,IAAI,WAAW;IACf,MAAM,SAAS,MAAM,gBAAgB,IAAI,MAAM;IAC/C,WAAW,MAAM,OAAO,QAAQ;KAI9B,QAAQ,IAAI,EAAE;KACd,WAAW;IACb;IAGA,IAAI,UACF;GAEJ,SAAS,GAAG;IACV,MAAM;GACR;GASA,GAAG,OACD,uCAAuC,IAAI,EAAE,4BAC7C,OAAO,GAAG,CACZ;GACA,IAAI;IACF,MAAM,MAAM,KAAM,MAAM,MAAM;GAChC,SAAS,GAAG;IACV,OAAO,OAAO,CAAC;GACjB;EACF;CACF,GAAG;CAEH,OAAO;AACT;AAEA,SAAS,gBACP,IACA,QACkC;CAClC,MAAM,EAAC,QAAQ,QAAQ,mBAAkB;CAUzC,OAAO,IAP0B,yBAC/B,IAHc,eAAe,MAI7B,GACA,OAAO,IACP,eAAe,GAGV,EAAqB,gBAAgB,MAAM;AACpD"}

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-catchup.d.ts

@@ -0,0 +1,99 @@
+import type { LogContext } from '@rocicorp/logger';
+import { sleep } from '../../../../shared/src/sleep.ts';
+import type { WatermarkedChange } from './change-streamer.ts';
+import type { Forwarder } from './forwarder.ts';
+import type { CatchupPlan } from './sqlite-change-log-reader.ts';
+import type { Subscriber } from './subscriber.ts';
+export interface SQLiteChangeLogCatchupReader {
+    plan(fromWatermark: string): CatchupPlan;
+    read(fromWatermark: string, throughWatermark: string, batchSize: number, signal?: AbortSignal): AsyncIterable<readonly WatermarkedChange[]>;
+    close(): void;
+}
+/**
+ * Slice 9 replaces this no-op implementation with a guard that waits for an
+ * in-flight purge and blocks new purge dispatch while the subscriber's ACK is
+ * made visible to the Forwarder.
+ */
+export interface SQLiteChangeLogCleanupGuard {
+    runWhilePurgeBlocked<T>(register: () => T): Promise<T>;
+}
+export type SQLiteChangeLogCatchupOptions = {
+    batchSize: number;
+    barrierTimeoutMs: number;
+    barrierPollIntervalMs?: number | undefined;
+    cleanupGuard?: SQLiteChangeLogCleanupGuard | undefined;
+    sleep?: typeof sleep | undefined;
+    now?: (() => number) | undefined;
+    /** Opens slice 11's process-local breaker after registration has committed. */
+    onFailure?: ((failure: SQLiteChangeLogCatchupFailure) => void) | undefined;
+};
+export type SQLiteChangeLogCatchupRequest = {
+    /**
+     * Whether the routing warm-up gate classified the log as warm *for this
+     * subscriber*. The coordinator is opened once and reused, so this cannot be
+     * a property of it: `coldReadPercent` serves some subscribers from a log
+     * that is still inside its warm-up window, and the catchup metrics have to
+     * separate those from steady-state serving.
+     */
+    readonly logWarm?: boolean | undefined;
+};
+export type SQLiteChangeLogCatchupFailure = 'barrier-timeout' | 'reader-error';
+export type SQLiteChangeLogCatchupRegistration = {
+    readonly kind: 'registered';
+} | {
+    readonly kind: 'uncovered';
+    readonly minWatermark: string;
+} | {
+    readonly kind: 'declined';
+    readonly error: unknown;
+} | {
+    readonly kind: 'handled';
+};
+/**
+ * Coordinates a serving subscriber's gap-free transition from replica-local
+ * SQLite catchup to the Forwarder's live stream.
+ *
+ * Registration and required-head capture happen in one synchronous callback.
+ * The subscriber therefore either sees a transaction in SQLite catchup or in
+ * its live backlog (duplicates across that boundary are filtered by
+ * Subscriber), never in neither place.
+ */
+export declare class SQLiteChangeLogCatchup implements Disposable {
+    #private;
+    constructor(lc: LogContext, forwarder: Forwarder, reader: SQLiteChangeLogCatchupReader, opts: SQLiteChangeLogCatchupOptions);
+    /**
+     * Registers the subscriber before resolving. Catchup itself continues in
+     * the background so subscribe() does not wait for SQLite to reach the
+     * required head.
+     */
+    catchup(subscriber: Subscriber, captureRequiredHead: () => string | Promise<string>, request?: SQLiteChangeLogCatchupRequest): Promise<SQLiteChangeLogCatchupRegistration>;
+    /**
+     * Notes that the change-log writer has committed `watermark`, i.e. that the
+     * log's head has advanced to it. The writer runs in this process, so this is
+     * the event itself rather than a subscriber's ACK of it.
+     *
+     * It is a wakeup, not an authority: `plan()` still decides what can be read.
+     * A notification that never arrives costs the barrier a poll interval, and one
+     * that arrives early costs an extra `plan()` call.
+     */
+    onChangeLogCommit(watermark: string): void;
+    remove(subscriber: Subscriber): void;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+/**
+ * A barrier that gave up on the replica reaching the required head. Both
+ * reasons mean "not yet", not "never", so both end the subscription cleanly
+ * for a retry rather than failing it.
+ */
+export declare class SQLiteChangeLogBarrierError extends Error {
+}
+/** The replica did not reach the required head before the deadline. */
+export declare class SQLiteChangeLogBarrierTimeoutError extends SQLiteChangeLogBarrierError {
+    readonly name = "SQLiteChangeLogBarrierTimeoutError";
+}
+/** Waiting any longer would have cost more than reconnecting. */
+export declare class SQLiteChangeLogBarrierBacklogError extends SQLiteChangeLogBarrierError {
+    readonly name = "SQLiteChangeLogBarrierBacklogError";
+}
+//# sourceMappingURL=sqlite-change-log-catchup.d.ts.map