@rocicorp/zero 1.11.0-canary.2 → 1.11.0-canary.20

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

@@ -0,0 +1,92 @@
+/**
+ * Pure schema definitions for the `/snapshot` reservation status message.
+ *
+ * These live in their own module (depending only on valita) so that both
+ * {@link snapshot.ts} (which also pulls in the change-streamer HTTP client) and
+ * {@link subscribe.ts} can import them without forming an import cycle.
+ */
+import * as v from '../../../../shared/src/valita.ts';
+export declare const statusSchema: v.ObjectType<{
+    tag: v.Type<"status">;
+    /**
+     * The location from which litestream should perform the restore.
+     */
+    backupURL: v.Type<string>;
+    /**
+     * The `replicaVersion` of the backup. If a subscriber's restored or
+     * existing replica is of a different version, it should delete it and
+     * retry the restore from litestream (i.e. equivalent to a
+     * `WrongReplicaVersion` response from a `/changes` subscription).
+     */
+    replicaVersion: v.Type<string>;
+    /**
+     * The earliest watermark from which catchup is possible. If the
+     * subscriber's replica is older that this watermark, it should delete it
+     * and (retry the) restore from litestream (i.e. equivalent to a
+     * `WatermarkTooOld` response from a `/changes` subscription).
+     */
+    minWatermark: v.Type<string>;
+    /**
+     * The size in bytes of the replication-manager's replica when the snapshot
+     * was reserved, used as an estimate of the size of the restored replica
+     * when reporting restore progress. Absent from older replication-managers.
+     */
+    replicaSize: v.Optional<number>;
+}, undefined>;
+export type SnapshotStatus = v.Infer<typeof statusSchema>;
+export declare const statusMessageSchema: v.TupleType<[v.Type<"status">, v.ObjectType<{
+    tag: v.Type<"status">;
+    /**
+     * The location from which litestream should perform the restore.
+     */
+    backupURL: v.Type<string>;
+    /**
+     * The `replicaVersion` of the backup. If a subscriber's restored or
+     * existing replica is of a different version, it should delete it and
+     * retry the restore from litestream (i.e. equivalent to a
+     * `WrongReplicaVersion` response from a `/changes` subscription).
+     */
+    replicaVersion: v.Type<string>;
+    /**
+     * The earliest watermark from which catchup is possible. If the
+     * subscriber's replica is older that this watermark, it should delete it
+     * and (retry the) restore from litestream (i.e. equivalent to a
+     * `WatermarkTooOld` response from a `/changes` subscription).
+     */
+    minWatermark: v.Type<string>;
+    /**
+     * The size in bytes of the replication-manager's replica when the snapshot
+     * was reserved, used as an estimate of the size of the restored replica
+     * when reporting restore progress. Absent from older replication-managers.
+     */
+    replicaSize: v.Optional<number>;
+}, undefined>]>;
+export declare const snapshotMessageSchema: v.UnionType<[v.TupleType<[v.Type<"status">, v.ObjectType<{
+    tag: v.Type<"status">;
+    /**
+     * The location from which litestream should perform the restore.
+     */
+    backupURL: v.Type<string>;
+    /**
+     * The `replicaVersion` of the backup. If a subscriber's restored or
+     * existing replica is of a different version, it should delete it and
+     * retry the restore from litestream (i.e. equivalent to a
+     * `WrongReplicaVersion` response from a `/changes` subscription).
+     */
+    replicaVersion: v.Type<string>;
+    /**
+     * The earliest watermark from which catchup is possible. If the
+     * subscriber's replica is older that this watermark, it should delete it
+     * and (retry the) restore from litestream (i.e. equivalent to a
+     * `WatermarkTooOld` response from a `/changes` subscription).
+     */
+    minWatermark: v.Type<string>;
+    /**
+     * The size in bytes of the replication-manager's replica when the snapshot
+     * was reserved, used as an estimate of the size of the restored replica
+     * when reporting restore progress. Absent from older replication-managers.
+     */
+    replicaSize: v.Optional<number>;
+}, undefined>]>]>;
+export type SnapshotMessage = v.Infer<typeof statusMessageSchema>;
+//# sourceMappingURL=snapshot-message.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-message.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot-message.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,CAAC,MAAM,kCAAkC,CAAC;AAEtD,eAAO,MAAM,YAAY;;IAGvB;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;aAEH,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;IA/B9B;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;eAM0E,CAAC;AAEhF,eAAO,MAAM,qBAAqB;;IAjChC;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;iBAQ4D,CAAC;AAElE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

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

@@ -0,0 +1,42 @@
+import { valita_exports } from "../../../../shared/src/valita.js";
+//#region ../zero-cache/src/services/change-streamer/snapshot-message.ts
+/**
+* Pure schema definitions for the `/snapshot` reservation status message.
+*
+* These live in their own module (depending only on valita) so that both
+* {@link snapshot.ts} (which also pulls in the change-streamer HTTP client) and
+* {@link subscribe.ts} can import them without forming an import cycle.
+*/
+var statusSchema = valita_exports.object({
+	tag: valita_exports.literal("status"),
+	/**
+	* The location from which litestream should perform the restore.
+	*/
+	backupURL: valita_exports.string(),
+	/**
+	* The `replicaVersion` of the backup. If a subscriber's restored or
+	* existing replica is of a different version, it should delete it and
+	* retry the restore from litestream (i.e. equivalent to a
+	* `WrongReplicaVersion` response from a `/changes` subscription).
+	*/
+	replicaVersion: valita_exports.string(),
+	/**
+	* The earliest watermark from which catchup is possible. If the
+	* subscriber's replica is older that this watermark, it should delete it
+	* and (retry the) restore from litestream (i.e. equivalent to a
+	* `WatermarkTooOld` response from a `/changes` subscription).
+	*/
+	minWatermark: valita_exports.string(),
+	/**
+	* The size in bytes of the replication-manager's replica when the snapshot
+	* was reserved, used as an estimate of the size of the restored replica
+	* when reporting restore progress. Absent from older replication-managers.
+	*/
+	replicaSize: valita_exports.number().optional()
+});
+var statusMessageSchema = valita_exports.tuple([valita_exports.literal("status"), statusSchema]);
+valita_exports.union(statusMessageSchema);
+//#endregion
+export { statusSchema };
+
+//# sourceMappingURL=snapshot-message.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-message.js","names":[],"sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot-message.ts"],"sourcesContent":["/**\n * Pure schema definitions for the `/snapshot` reservation status message.\n *\n * These live in their own module (depending only on valita) so that both\n * {@link snapshot.ts} (which also pulls in the change-streamer HTTP client) and\n * {@link subscribe.ts} can import them without forming an import cycle.\n */\n\nimport * as v from '../../../../shared/src/valita.ts';\n\nexport const 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  /**\n   * The size in bytes of the replication-manager's replica when the snapshot\n   * was reserved, used as an estimate of the size of the restored replica\n   * when reporting restore progress. Absent from older replication-managers.\n   */\n  replicaSize: v.number().optional(),\n});\n\nexport type SnapshotStatus = v.Infer<typeof statusSchema>;\n\nexport const statusMessageSchema = v.tuple([v.literal('status'), statusSchema]);\n\nexport const snapshotMessageSchema = v.union(statusMessageSchema);\n\nexport type SnapshotMessage = v.Infer<typeof statusMessageSchema>;\n"],"mappings":";;;;;;;;;AAUA,IAAa,eAAe,eAAE,OAAO;CACnC,KAAK,eAAE,QAAQ,QAAQ;;;;CAKvB,WAAW,eAAE,OAAO;;;;;;;CAQpB,gBAAgB,eAAE,OAAO;;;;;;;CAQzB,cAAc,eAAE,OAAO;;;;;;CAOvB,aAAa,eAAE,OAAO,EAAE,SAAS;AACnC,CAAC;AAID,IAAa,sBAAsB,eAAE,MAAM,CAAC,eAAE,QAAQ,QAAQ,GAAG,YAAY,CAAC;AAEzC,eAAE,MAAM,mBAAmB"}

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

@@ -1,7 +1,7 @@
 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 { SnapshotMessage } from './snapshot-message.ts';
 import type { ChangeLogReadSource } from './sqlite-change-log-read-router.ts';
 export declare class SnapshotReservations {
     #private;

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

@@ -1 +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;;IAM/B,YACE,EAAE,EAAE,UAAU,EACd,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,EAKjD;IAED,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAU5C;IAED,KAAK,CAAC,MAAM,EAAE,MAAM,QAEnB;IAED,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,eAAe,CAAC,GAAG,OAAO,CAElE;IAsCD,qBAAqB,YAOpB;IAED,kBAAkB,IAAI,MAAM,EAAE,CAI7B;IAED,0EAA0E;IAC1E,UAAU,CACR,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,mBAAmB,GAC1B,IAAI,CAcN;IAED;;;;OAIG;IACH,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE/C;IAED,qBAAqB,aAKpB;CACF"}
+{"version":3,"file":"snapshot-reservations.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot-reservations.ts"],"names":[],"mappings":"AACA,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,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oCAAoC,CAAC;AAE5E,qBAAa,oBAAoB;;IAM/B,YACE,EAAE,EAAE,UAAU,EACd,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,EAKjD;IAED,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAU5C;IAED,KAAK,CAAC,MAAM,EAAE,MAAM,QAEnB;IAED,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,eAAe,CAAC,GAAG,OAAO,CAElE;IAsCD,qBAAqB,YAOpB;IAED,kBAAkB,IAAI,MAAM,EAAE,CAI7B;IAED,0EAA0E;IAC1E,UAAU,CACR,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,mBAAmB,GAC1B,IAAI,CAmBN;IAeD;;;;OAIG;IACH,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE/C;IAED,qBAAqB,aAKpB;CACF"}

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

@@ -1,5 +1,6 @@
 import { Subscription } from "../../types/subscription.js";
 import { litestreamMonitorMetricAttrs, litestreamSnapshotReservationConfirmDuration, litestreamSnapshotReservationDuration } from "../litestream/metrics.js";
+import { statSync } from "node:fs";
 //#region ../zero-cache/src/services/change-streamer/snapshot-reservations.ts
 var SnapshotReservations = class {
 	#lc;
@@ -16,7 +17,7 @@ var SnapshotReservations = class {
 		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}`);
+		this.#lc.info?.(`created snapshot reservation for ${taskID}`);
 		return downstream;
 	}
 	close(taskID) {
@@ -55,13 +56,23 @@ var SnapshotReservations = class {
 		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);
+			res.confirm(this.#backupConfig.backupURL, replicaVersion, minWatermark, this.#replicaSize());
 			litestreamSnapshotReservationConfirmDuration().recordMs(Date.now() - res.startTime.getTime(), {
 				...this.#metricAttrs(),
 				source
 			});
 		}
 	}
+	#replicaSize() {
+		const { replicaFile } = this.#backupConfig;
+		if (!replicaFile) return;
+		try {
+			return statSync(replicaFile).size;
+		} catch (e) {
+			this.#lc.warn?.(`Unable to get the size of ${replicaFile}`, e);
+			return;
+		}
+	}
 	/**
 	* Notes that a confirmation was deferred, returning true only the first time
 	* for this reservation. Confirmation is retried on every backup, so an
@@ -98,13 +109,14 @@ var Reservation = class {
 		this.#delayNoted = true;
 		return true;
 	}
-	confirm(backupURL, replicaVersion, minWatermark) {
+	confirm(backupURL, replicaVersion, minWatermark, replicaSize) {
 		if (this.#watermark === null) {
 			if (this.#downstream.active) this.#downstream.push(["status", {
 				tag: "status",
 				backupURL,
 				replicaVersion,
-				minWatermark
+				minWatermark,
+				replicaSize
 			}]);
 			this.#watermark = minWatermark;
 		}

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

@@ -1 +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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"}
+{"version":3,"file":"snapshot-reservations.js","names":["#lc","#backupConfig","#onClose","#reservations","#close","#metricAttrs","#replicaSize","#downstream","#watermark","#delayNoted"],"sources":["../../../../../../zero-cache/src/services/change-streamer/snapshot-reservations.ts"],"sourcesContent":["import {statSync} from 'node:fs';\nimport 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-message.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 snapshot 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(\n        this.#backupConfig.backupURL,\n        replicaVersion,\n        minWatermark,\n        this.#replicaSize(),\n      );\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  #replicaSize(): number | undefined {\n    const {replicaFile} = this.#backupConfig;\n    if (!replicaFile) {\n      return undefined;\n    }\n    try {\n      return statSync(replicaFile).size;\n    } catch (e) {\n      this.#lc.warn?.(`Unable to get the size of ${replicaFile}`, e);\n      return undefined;\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(\n    backupURL: string,\n    replicaVersion: string,\n    minWatermark: string,\n    replicaSize: number | undefined,\n  ) {\n    if (this.#watermark === null) {\n      if (this.#downstream.active) {\n        this.#downstream.push([\n          'status',\n          {tag: 'status', backupURL, replicaVersion, minWatermark, replicaSize},\n        ]);\n      }\n      this.#watermark = minWatermark;\n    }\n  }\n\n  close() {\n    this.#downstream.cancel();\n  }\n}\n"],"mappings":";;;;AAaA,IAAa,uBAAb,MAAkC;CAChC;CACA;CACA;CACA,gCAAyB,IAAI,IAAyB;CAEtD,YACE,IACA,cACA,SACA;EACA,KAAKA,MAAM,GAAG,YAAY,aAAa,mBAAmB;EAC1D,KAAKC,gBAAgB;EACrB,KAAKC,WAAW;CAClB;CAEA,KAAK,QAAyC;EAC5C,KAAK,MAAM,MAAM;EAEjB,MAAM,aAAa,CAAC;EACpB,MAAM,aAAa,aAAa,OAAwB,EACtD,eAAe,KAAKE,OAAO,QAAQ,UAAU,EAC/C,CAAC;EACD,KAAKD,cAAc,IAAI,QAAQ,IAAI,YAAY,YAAY,UAAU,CAAC;EACtE,KAAKH,IAAI,OAAO,oCAAoC,QAAQ;EAC5D,OAAO;CACT;CAEA,MAAM,QAAgB;EACpB,KAAKI,OAAO,QAAQ,KAAA,CAAS;CAC/B;CAEA,UAAU,QAAgB,QAA0C;EAClE,OAAO,KAAKD,cAAc,IAAI,MAAM,GAAG,KAAK,MAAM,KAAK;CACzD;CAEA,eAAe;EACb,OAAO,6BACL,KAAKF,cAAc,WACnB,KAAKA,cAAc,mBACnB,aACF;CACF;CAEA,OAAO,QAAgB,qBAA6C;EAClE,MAAM,MAAM,KAAKE,cAAc,IAAI,MAAM;EACzC,IACE,QACC,CAAC,uBAAuB,IAAI,eAAe,sBAC5C;GAEA,KAAKA,cAAc,OAAO,MAAM;GAChC,KAAKD,WAAW,MAAM;GACtB,IAAI,MAAM;GAEV,MAAM,WAAW,KAAK,IAAI,IAAI,IAAI,UAAU,QAAQ;GACpD,KAAKF,IAAI,OACP,kCAAkC,OAAO,IAAI,SAAS,KACxD;GAMA,sCAAsC,EAAE,SAAS,UAAU;IACzD,GAAG,KAAKK,aAAa;IACrB,QAAQ,sBAAsB,cAAc;IAC5C,WAAW,IAAI,UAAU;GAC3B,CAAC;EACH;CACF;CAEA,wBAAwB;EACtB,KAAK,MAAM,OAAO,KAAKF,cAAc,OAAO,GAC1C,IAAI,CAAC,IAAI,UAAU,GACjB,OAAO;EAGX,OAAO;CACT;CAEA,qBAA+B;EAC7B,OAAO,CAAC,GAAG,KAAKA,cAAc,QAAQ,CAAC,EACpC,QAAQ,GAAG,iBAAiB,CAAC,YAAY,UAAU,CAAC,EACpD,KAAK,CAAC,YAAY,MAAM;CAC7B;;CAGA,WACE,QACA,gBACA,cACA,QACM;EACN,MAAM,MAAM,KAAKA,cAAc,IAAI,MAAM;EACzC,IAAI,OAAO,CAAC,IAAI,UAAU,GAAG;GAC3B,KAAKH,IAAI,OACP,sCAAsC,aAAa,OAAO,QAC5D;GACA,IAAI,QACF,KAAKC,cAAc,WACnB,gBACA,cACA,KAAKK,aAAa,CACpB;GAGA,6CAA6C,EAAE,SAC7C,KAAK,IAAI,IAAI,IAAI,UAAU,QAAQ,GACnC;IAAC,GAAG,KAAKD,aAAa;IAAG;GAAM,CACjC;EACF;CACF;CAEA,eAAmC;EACjC,MAAM,EAAC,gBAAe,KAAKJ;EAC3B,IAAI,CAAC,aACH;EAEF,IAAI;GACF,OAAO,SAAS,WAAW,EAAE;EAC/B,SAAS,GAAG;GACV,KAAKD,IAAI,OAAO,6BAA6B,eAAe,CAAC;GAC7D;EACF;CACF;;;;;;CAOA,wBAAwB,QAAyB;EAC/C,OAAO,KAAKG,cAAc,IAAI,MAAM,GAAG,YAAY,KAAK;CAC1D;CAEA,wBAAwB;EACtB,OAAO,MAAM,KACX,KAAKA,cAAc,OAAO,IACzB,EAAC,wBAAuB,iBAC3B,EAAE,QAAO,cAAa,cAAc,IAAI;CAC1C;AACF;AAIA,IAAM,cAAN,MAAkB;CAChB;CACA,4BAA2B,IAAI,KAAK;CACpC;CACA,aAA4B;CAC5B,cAAc;CAEd,YACE,YACA,YACA;EACA,KAAK,aAAa;EAClB,KAAKI,cAAc;CACrB;CAEA,IAAI,oBAAoB;EACtB,OAAO,KAAKC;CACd;CAEA,YAAY;EACV,OAAO,KAAKA,eAAe;CAC7B;CAEA,KAAK,QAA0C;EAC7C,OAAO,KAAKD,gBAAgB;CAC9B;CAEA,cAAuB;EACrB,IAAI,KAAKE,aACP,OAAO;EAET,KAAKA,cAAc;EACnB,OAAO;CACT;CAEA,QACE,WACA,gBACA,cACA,aACA;EACA,IAAI,KAAKD,eAAe,MAAM;GAC5B,IAAI,KAAKD,YAAY,QACnB,KAAKA,YAAY,KAAK,CACpB,UACA;IAAC,KAAK;IAAU;IAAW;IAAgB;IAAc;GAAW,CACtE,CAAC;GAEH,KAAKC,aAAa;EACpB;CACF;CAEA,QAAQ;EACN,KAAKD,YAAY,OAAO;CAC1B;AACF"}

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

@@ -12,73 +12,11 @@
  *   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">;
-    /**
-     * The location from which litestream should perform the restore.
-     */
-    backupURL: v.Type<string>;
-    /**
-     * The `replicaVersion` of the backup. If a subscriber's restored or
-     * existing replica is of a different version, it should delete it and
-     * retry the restore from litestream (i.e. equivalent to a
-     * `WrongReplicaVersion` response from a `/changes` subscription).
-     */
-    replicaVersion: v.Type<string>;
-    /**
-     * The earliest watermark from which catchup is possible. If the
-     * subscriber's replica is older that this watermark, it should delete it
-     * and (retry the) restore from litestream (i.e. equivalent to a
-     * `WatermarkTooOld` response from a `/changes` subscription).
-     */
-    minWatermark: v.Type<string>;
-}, undefined>;
-export type SnapshotStatus = v.Infer<typeof statusSchema>;
-declare const statusMessageSchema: v.TupleType<[v.Type<"status">, v.ObjectType<{
-    tag: v.Type<"status">;
-    /**
-     * The location from which litestream should perform the restore.
-     */
-    backupURL: v.Type<string>;
-    /**
-     * The `replicaVersion` of the backup. If a subscriber's restored or
-     * existing replica is of a different version, it should delete it and
-     * retry the restore from litestream (i.e. equivalent to a
-     * `WrongReplicaVersion` response from a `/changes` subscription).
-     */
-    replicaVersion: v.Type<string>;
-    /**
-     * The earliest watermark from which catchup is possible. If the
-     * subscriber's replica is older that this watermark, it should delete it
-     * and (retry the) restore from litestream (i.e. equivalent to a
-     * `WatermarkTooOld` response from a `/changes` subscription).
-     */
-    minWatermark: v.Type<string>;
-}, undefined>]>;
-export declare const snapshotMessageSchema: v.UnionType<[v.TupleType<[v.Type<"status">, v.ObjectType<{
-    tag: v.Type<"status">;
-    /**
-     * The location from which litestream should perform the restore.
-     */
-    backupURL: v.Type<string>;
-    /**
-     * The `replicaVersion` of the backup. If a subscriber's restored or
-     * existing replica is of a different version, it should delete it and
-     * retry the restore from litestream (i.e. equivalent to a
-     * `WrongReplicaVersion` response from a `/changes` subscription).
-     */
-    replicaVersion: v.Type<string>;
-    /**
-     * The earliest watermark from which catchup is possible. If the
-     * subscriber's replica is older that this watermark, it should delete it
-     * and (retry the) restore from litestream (i.e. equivalent to a
-     * `WatermarkTooOld` response from a `/changes` subscription).
-     */
-    minWatermark: v.Type<string>;
-}, undefined>]>]>;
-export type SnapshotMessage = v.Infer<typeof statusMessageSchema>;
-export declare function reserveAndGetSnapshotStatus(lc: LogContext, config: NormalizedZeroConfig): Promise<SnapshotStatus>;
-export {};
+import type { ReservationFollowup, SnapshotReserver } from './change-streamer-http.ts';
+import type { SnapshotStatus } from './subscribe.ts';
+export type { SnapshotStatus };
+export declare function reserveAndGetSnapshotStatus(lc: LogContext, taskID: string, changeStreamer: SnapshotReserver): Promise<{
+    reserved: SnapshotStatus;
+    followup: ReservationFollowup;
+}>;
 //# 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,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"}
+{"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;AASjD,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EAAC,cAAc,EAAC,CAAC;AAE7B,wBAAsB,2BAA2B,CAC/C,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,gBAAgB,GAC/B,OAAO,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAA;CAAC,CAAC,CAmDpE"}

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

@@ -1,67 +1,35 @@
+import { AbortError } from "../../../../shared/src/abort-error.js";
 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";
+import { promiseOrAbort } from "../../../../shared/src/promise-race.js";
 //#region ../zero-cache/src/services/change-streamer/snapshot.ts
-var statusSchema = valita_exports.object({
-	tag: valita_exports.literal("status"),
-	/**
-	* The location from which litestream should perform the restore.
-	*/
-	backupURL: valita_exports.string(),
-	/**
-	* The `replicaVersion` of the backup. If a subscriber's restored or
-	* existing replica is of a different version, it should delete it and
-	* retry the restore from litestream (i.e. equivalent to a
-	* `WrongReplicaVersion` response from a `/changes` subscription).
-	*/
-	replicaVersion: valita_exports.string(),
-	/**
-	* The earliest watermark from which catchup is possible. If the
-	* subscriber's replica is older that this watermark, it should delete it
-	* and (retry the) restore from litestream (i.e. equivalent to a
-	* `WatermarkTooOld` response from a `/changes` subscription).
-	*/
-	minWatermark: valita_exports.string()
-});
-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());
+async function reserveAndGetSnapshotStatus(lc, taskID, changeStreamer) {
+	const abort = new AbortController();
+	const { signal } = abort;
+	const onSignal = () => abort.abort(new AbortError("SIGTERM/SIGINT"));
+	process.on("SIGINT", onSignal);
+	process.on("SIGTERM", onSignal);
+	try {
 		for (let i = 0;; i++) {
 			let err;
+			const reservation = changeStreamer.reserveSnapshot(taskID);
 			try {
-				let resolved = false;
-				const stream = await reserveSnapshot(lc, config);
-				for await (const msg of stream) {
-					resolve(msg[1]);
-					resolved = true;
-				}
-				if (resolved) break;
+				return await promiseOrAbort(reservation, signal);
 			} 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);
+			if (signal.aborted) {
+				reservation.then(({ followup }) => followup.cancel(), () => {});
+				throw err;
 			}
+			lc.warn?.(`Unable to reserve snapshot (attempt ${i + 1}). Retrying in 5 seconds.`, String(err));
+			await sleep(5e3, signal);
 		}
-	})();
-	return status;
-}
-function reserveSnapshot(lc, config) {
-	const { taskID, change, changeStreamer } = config;
-	return new ChangeStreamerHttpClient(lc, getShardConfig(config), change.db, changeStreamer.uri).reserveSnapshot(taskID);
+	} finally {
+		process.off("SIGINT", onSignal);
+		process.off("SIGTERM", onSignal);
+	}
 }
 //#endregion
-export { reserveAndGetSnapshotStatus, snapshotMessageSchema };
+export { reserveAndGetSnapshotStatus };
 
 //# 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 * 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"}
+{"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 {AbortError} from '../../../../shared/src/abort-error.ts';\nimport {promiseOrAbort} from '../../../../shared/src/promise-race.ts';\nimport {sleep} from '../../../../shared/src/sleep.ts';\n\n// The schema definitions live in the pure schema module (with no dependency on\n// the HTTP client) so that subscribe.ts can import them without forming an\n// import cycle through change-streamer-http.ts. Imported here for local use and\n// re-exported for existing consumers.\nimport type {\n  ReservationFollowup,\n  SnapshotReserver,\n} from './change-streamer-http.ts';\nimport type {SnapshotStatus} from './subscribe.ts';\n\nexport type {SnapshotStatus};\n\nexport async function reserveAndGetSnapshotStatus(\n  lc: LogContext,\n  taskID: string,\n  changeStreamer: SnapshotReserver,\n): Promise<{reserved: SnapshotStatus; followup: ReservationFollowup}> {\n  const abort = new AbortController();\n  const {signal} = abort;\n  // Use our own AbortError as the abort reason (rather than the native\n  // DOMException that AbortController.abort() defaults to) so that\n  // promiseOrAbort()'s rejection, which propagates `signal.reason` verbatim,\n  // is always an instance of the shared AbortError type.\n  const onSignal = () => abort.abort(new AbortError('SIGTERM/SIGINT'));\n  process.on('SIGINT', onSignal);\n  process.on('SIGTERM', onSignal);\n\n  try {\n    for (let i = 0; ; i++) {\n      let err: unknown;\n      const reservation = changeStreamer.reserveSnapshot(taskID);\n      try {\n        return await promiseOrAbort(reservation, signal);\n      } catch (e) {\n        err = e;\n      }\n      if (signal.aborted) {\n        // promiseOrAbort() does not cancel the loser of the race: the\n        // reservation may still resolve later. If it does, cancel its\n        // connection rather than leaking it, since this function has already\n        // given up and nobody will call followup.subscribe().\n        reservation.then(\n          ({followup}) => followup.cancel(),\n          () => {},\n        );\n        throw err;\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      await sleep(5000, signal);\n    }\n  } finally {\n    // This function is called repeatedly (e.g. by the replicator's restore\n    // loop), so the signal handlers must not outlive the reservation.\n    process.off('SIGINT', onSignal);\n    process.off('SIGTERM', onSignal);\n  }\n}\n"],"mappings":";;;;AA+BA,eAAsB,4BACpB,IACA,QACA,gBACoE;CACpE,MAAM,QAAQ,IAAI,gBAAgB;CAClC,MAAM,EAAC,WAAU;CAKjB,MAAM,iBAAiB,MAAM,MAAM,IAAI,WAAW,gBAAgB,CAAC;CACnE,QAAQ,GAAG,UAAU,QAAQ;CAC7B,QAAQ,GAAG,WAAW,QAAQ;CAE9B,IAAI;EACF,KAAK,IAAI,IAAI,IAAK,KAAK;GACrB,IAAI;GACJ,MAAM,cAAc,eAAe,gBAAgB,MAAM;GACzD,IAAI;IACF,OAAO,MAAM,eAAe,aAAa,MAAM;GACjD,SAAS,GAAG;IACV,MAAM;GACR;GACA,IAAI,OAAO,SAAS;IAKlB,YAAY,MACT,EAAC,eAAc,SAAS,OAAO,SAC1B,CAAC,CACT;IACA,MAAM;GACR;GASA,GAAG,OACD,uCAAuC,IAAI,EAAE,4BAC7C,OAAO,GAAG,CACZ;GACA,MAAM,MAAM,KAAM,MAAM;EAC1B;CACF,UAAU;EAGR,QAAQ,IAAI,UAAU,QAAQ;EAC9B,QAAQ,IAAI,WAAW,QAAQ;CACjC;AACF"}

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

@@ -25,6 +25,11 @@ export type SQLiteChangeLogWriterOptions = {
     onRebuilt?: (() => void) | undefined;
     /** Overridable for tests. */
     now?: (() => number) | undefined;
+    /**
+     * Percentage of transactions that retain the rollout-only per-message
+     * timing and source-vs-stored hash validation. Defaults to 1.
+     */
+    shadowValidationPercent?: number | undefined;
 };
 /**
  * Appends the canonical change stream to the SQLite change log, from the
@@ -98,7 +103,7 @@ export declare class SQLiteChangeLogWriter {
      * Writes one stream message, committing at transaction boundaries. Never
      * throws: a write failure disables the writer instead of failing the stream.
      */
-    write(change: ChangeStreamData, json: string): void;
+    write(change: ChangeStreamData, json: string, storedChange?: string): void;
     /**
      * Discards the open transaction, if any. Called when the change stream is
      * interrupted mid-transaction.

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

@@ -1 +1 @@
-{"version":3,"file":"sqlite-change-log-writer.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/sqlite-change-log-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,8BAA8B,CAAC;AAM3D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,iDAAiD,CAAC;AAKtF,OAAO,EAUL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAE1B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAML,KAAK,iCAAiC,EACvC,MAAM,kDAAkD,CAAC;AAE1D,MAAM,MAAM,4BAA4B,GAAG;IACzC,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACrD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACtC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACrC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,qBAAqB;;IAUhC,YAAY,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,4BAA4B,EAI7D;IAED,qEAAqE;IACrE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;OAOG;IACH,IAAI,UAAU,IAAI,QAAQ,GAAG,SAAS,CAErC;IAED,2EAA2E;IAC3E,KAAK,IAAI,iCAAiC,GAAG,SAAS,CAErD;IAED;;;;;;;;;;;;;OAaG;IACH,SAAS,CACP,UAAU,EAAE,oBAAoB,GAC/B,oBAAoB,GAAG,SAAS,CAElC;IAED;;;;;OAKG;IACH,gBAAgB,CACd,IAAI,EAAE,MAAM,oBAAoB,GAC/B,oBAAoB,GAAG,SAAS,CAElC;IA2GD;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAgElD;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAWZ;IAED,KAAK,IAAI,IAAI,CAWZ;CA6BF"}
+{"version":3,"file":"sqlite-change-log-writer.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/sqlite-change-log-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAKjD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,8BAA8B,CAAC;AAM3D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,iDAAiD,CAAC;AAKtF,OAAO,EAUL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAE1B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAML,KAAK,iCAAiC,EACvC,MAAM,kDAAkD,CAAC;AAG1D,MAAM,MAAM,4BAA4B,GAAG;IACzC,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACrD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACtC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACrC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IACjC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,qBAAqB;;IAYhC,YAAY,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,4BAA4B,EAY7D;IAED,qEAAqE;IACrE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;OAOG;IACH,IAAI,UAAU,IAAI,QAAQ,GAAG,SAAS,CAErC;IAED,2EAA2E;IAC3E,KAAK,IAAI,iCAAiC,GAAG,SAAS,CAErD;IAED;;;;;;;;;;;;;OAaG;IACH,SAAS,CACP,UAAU,EAAE,oBAAoB,GAC/B,oBAAoB,GAAG,SAAS,CAElC;IAED;;;;;OAKG;IACH,gBAAgB,CACd,IAAI,EAAE,MAAM,oBAAoB,GAC/B,oBAAoB,GAAG,SAAS,CAElC;IA2GD;;;OAGG;IACH,KAAK,CACH,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,MAAM,EACZ,YAAY,SAA8C,GACzD,IAAI,CA4FN;IAeD;;;OAGG;IACH,KAAK,IAAI,IAAI,CAYZ;IAED,KAAK,IAAI,IAAI,CAYZ;CA6BF"}

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-writer.js

@@ -1,12 +1,16 @@
+import { assert } from "../../../../shared/src/asserts.js";
 import { must } from "../../../../shared/src/must.js";
+import { h32 } from "../../../../shared/src/hash.js";
 import { readCookieRowCounts, readCookies } from "../replicator/change-log-cookies.js";
 import { StatementRunner } from "../../db/statements.js";
 import { isSQLiteCorruption, logSQLiteCorruptionDiagnostics } from "../../db/sqlite-corruption.js";
 import { ChangeLogRebuildRequired, changeLogFileName, changeLogWipeReason, deleteChangeLogDB, openChangeLogDBForWriting, readChangeLogHead, rebuildChangeLogDBForWriting, reconcileChangeLog } from "../replicator/change-log-db.js";
+import { extractChangeSubstring } from "./change-log-codec.js";
 import { ChangeLogStreamWriter } from "../replicator/change-log-stream-writer.js";
 import { SQLiteChangeLogObserver, getSQLiteChangeLogInfo, logSQLiteChangeLogStartup, recordSQLiteChangeLogReconcile } from "../replicator/sqlite-change-log-observability.js";
 import { SqliteError } from "@rocicorp/zero-sqlite3";
 //#region ../zero-cache/src/services/change-streamer/sqlite-change-log-writer.ts
+var DEFAULT_SHADOW_VALIDATION_PERCENT = 1;
 /**
 * Appends the canonical change stream to the SQLite change log, from the
 * change-streamer's own stream loop.
@@ -41,14 +45,18 @@ var SQLiteChangeLogWriter = class {
 	#lc;
 	#opts;
 	#now;
+	#shadowValidationPercent;
 	#db;
 	#writer;
 	#observer;
 	#disabled = false;
+	#validateTransaction = false;
 	constructor(lc, opts) {
 		this.#lc = lc.withContext("component", "sqlite-change-log-writer");
 		this.#opts = opts;
 		this.#now = opts.now ?? Date.now;
+		this.#shadowValidationPercent = opts.shadowValidationPercent ?? DEFAULT_SHADOW_VALIDATION_PERCENT;
+		assert(Number.isInteger(this.#shadowValidationPercent) && this.#shadowValidationPercent >= 0 && this.#shadowValidationPercent <= 100, "SQLite change-log shadow validation percentage must be an integer between 0 and 100");
 	}
 	/** False once the writer has failed soft, or after {@link close}. */
 	get enabled() {
@@ -161,26 +169,28 @@ var SQLiteChangeLogWriter = class {
 	* Writes one stream message, committing at transaction boundaries. Never
 	* throws: a write failure disables the writer instead of failing the stream.
 	*/
-	write(change, json) {
+	write(change, json, storedChange = extractChangeSubstring(json, change[1].tag)) {
 		const writer = this.#writer;
 		const db = this.#db;
 		if (this.#disabled || writer === void 0 || db === void 0) return;
-		const observer = this.#observer;
-		observer?.messageReceived(change, json);
 		const [type, msg] = change;
-		const startedAt = performance.now();
+		if (type === "begin") this.#validateTransaction = this.#isSelectedForShadowValidation(change[2].commitWatermark);
+		const validateTransaction = this.#validateTransaction;
+		const observer = this.#observer;
+		observer?.messageReceived(change, json, validateTransaction, storedChange);
+		const startedAt = validateTransaction ? performance.now() : void 0;
 		try {
 			let commit = null;
 			switch (type) {
 				case "begin":
-					writer.begin(change[2].commitWatermark, json);
+					writer.begin(change[2].commitWatermark, json, storedChange, validateTransaction);
 					break;
 				case "commit": {
 					const { watermark } = change[2];
 					const commitStart = performance.now();
 					commit = {
 						watermark,
-						stats: writer.commit(watermark, json, this.#now()),
+						stats: writer.commit(watermark, json, this.#now(), storedChange),
 						logCommitMs: performance.now() - commitStart
 					};
 					break;
@@ -189,14 +199,16 @@ var SQLiteChangeLogWriter = class {
 					writer.rollback();
 					break;
 				default:
-					writer.append(json, msg);
+					writer.append(json, msg, storedChange);
 					break;
 			}
-			observer?.messageProcessed(change, commit, performance.now() - startedAt);
+			observer?.messageProcessed(change, commit, startedAt === void 0 ? void 0 : performance.now() - startedAt);
 			if (commit !== null && commit.stats.cookieMutations.length > 0) observer?.cookiesMutated(commit.stats.cookieMutations, readCookieRowCounts(db));
 			if (commit !== null) this.#opts.onCommit?.(commit.watermark);
+			if (type === "commit" || type === "rollback") this.#validateTransaction = false;
 		} catch (e) {
-			observer?.messageFailed(change, e, performance.now() - startedAt);
+			observer?.messageFailed(change, e, startedAt === void 0 ? void 0 : performance.now() - startedAt);
+			this.#validateTransaction = false;
 			if (isConstraintViolation(e)) observer?.invariantFailure("SQLite change-log insert violated a constraint, which means a transaction above the resume watermark was not truncated", {
 				tag: msg.tag,
 				error: String(e)
@@ -204,12 +216,17 @@ var SQLiteChangeLogWriter = class {
 			this.#failSoft("writing to the SQLite change log", e);
 		}
 	}
+	#isSelectedForShadowValidation(watermark) {
+		const percent = this.#shadowValidationPercent;
+		return percent >= 100 || percent > 0 && h32(`${this.#opts.identity.generation}/${this.#opts.identity.replicaID ?? ""}:${watermark}`) % 100 < percent;
+	}
 	/**
 	* Discards the open transaction, if any. Called when the change stream is
 	* interrupted mid-transaction.
 	*/
 	abort() {
 		const writer = this.#writer;
+		this.#validateTransaction = false;
 		if (this.#disabled || writer === void 0) return;
 		this.#observer?.abort();
 		try {
@@ -220,6 +237,7 @@ var SQLiteChangeLogWriter = class {
 	}
 	close() {
 		this.#disabled = true;
+		this.#validateTransaction = false;
 		this.#writer = void 0;
 		this.#observer = void 0;
 		const db = this.#db;