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

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

@@ -0,0 +1,391 @@
+import { assert } from "../../../../shared/src/asserts.js";
+import { getOrCreateCounter, getOrCreateLatencyHistogram, getOrCreateValueHistogram } from "../../observability/metrics.js";
+import { CHANGE_LOG_STREAM_TABLE, readChangeLogMeta } from "../replicator/change-log-db.js";
+import { SQLITE_CHANGE_LOG_PLAN_SQL } from "./sqlite-change-log-reader.js";
+import { SQLiteChangeLogPurger } from "../replicator/sqlite-change-log-purger.js";
+import { Lock } from "@rocicorp/lock";
+//#region ../zero-cache/src/services/change-streamer/sqlite-change-log-purge-scheduler.ts
+/**
+* The duration target for any one purge statement, enforced by the purger's
+* measured-budget feedback. Purge runs on the writer's own
+* connection, in the stream loop's process, so a statement's duration stalls
+* the appending path — and the fan-out behind it — directly. The bench's
+* 100 ms bound was derived for the replicator's write worker; this budget is
+* measured against an event loop that also owes progress to fan-out, catchup,
+* and websocket keepalives, so it is deliberately tighter.
+*/
+var DEFAULT_STATEMENT_TARGET_MS = 20;
+/**
+* Batches per pass. This bounds one pass's bookkeeping, not the drain: a pass
+* that hits the limit asks its caller for an immediate continuation.
+*/
+var DEFAULT_MAX_BATCHES_PER_PASS = 100;
+/**
+* The backstop poll while waiting for the writer's open transaction to
+* commit. The commit notification normally arrives first; this covers an
+* interrupted stream, whose rollback does not notify.
+*/
+var DEFAULT_IN_TRANSACTION_POLL_MS = 1e3;
+/**
+* Whether the cleanup coordinator still owes this floor a pass. Deliberately
+* not the purger's eligibility query, in two ways:
+*
+* - `remains`: rows younger than the retention cutoff are not eligible *yet*,
+*   but they will be, and their presence asks the cleanup coordinator for a
+*   deferred pass even on a quiet source.
+* - `headBehindFloor`: a head behind the floor means the writer is expected
+*   to replay commits below it (e.g. after reconnecting while the backup
+*   outran this log). Those rows do not exist to count yet, writer commits
+*   only wake an in-flight waiter, and backup monitors never resend an
+*   unchanged floor — so reporting quiescence here would disarm cleanup for
+*   good. An empty log (no head) defers for the same reason.
+*/
+var BELOW_FLOOR_REMAINS_SQL = `
+  SELECT
+    EXISTS (
+      SELECT 1 FROM "${CHANGE_LOG_STREAM_TABLE}"
+      WHERE "watermark" < @floor
+        AND "watermark" < (SELECT max("watermark") FROM "${CHANGE_LOG_STREAM_TABLE}")
+    ) AS "remains",
+    coalesce(
+      (SELECT max("watermark") FROM "${CHANGE_LOG_STREAM_TABLE}") < @floor,
+      1
+    ) AS "headBehindFloor"
+`;
+/**
+* Runs bounded SQLite change-log purge passes on the writer's own connection.
+*
+* The caller supplies the current durable cleanup floor independently of any
+* other change-log implementation and owns the timing of subsequent passes.
+* Within a pass this class drains bounded batches, re-checking live subscriber
+* ACKs before each one and releasing the cleanup guard between them, so a
+* catchup registration or snapshot reservation never waits longer than one
+* batch.
+*
+* Purge windows exist only between the writer's commits: purge shares the
+* writer's connection, so it cannot run inside the writer's open transaction,
+* and a batch that finds one waits for the commit notification instead.
+*
+* The result tells the cleanup coordinator whether the next pass should be
+* immediate or deferred. This class deliberately owns no cleanup timer: the
+* same level-triggered coordinator continues a large drain, advances the
+* retention clock on a quiet source, and retries changing external state.
+*/
+var SQLiteChangeLogPurgeScheduler = class {
+	#lc;
+	#connection;
+	#subscriberAcks;
+	#opts;
+	#now;
+	#setTimeoutFn;
+	#clearTimeoutFn;
+	#yield;
+	/**
+	* The mutex that serializes purge batches with catchup registration and
+	* reservation pauses. It is only ever held across a synchronous section —
+	* one batch, or one registration — never across a yield, which is what
+	* bounds any waiter to a single batch's duration.
+	*/
+	#lock = new Lock();
+	/**
+	* Open snapshot reservations, reference-counted by taskID. Purge pauses
+	* while any is open. Counted rather than a set so that a reservation retry
+	* -- whose cancel-then-recreate can resolve its old resume after its new
+	* suspend -- still nets out.
+	*/
+	#pausedBy = /* @__PURE__ */ new Map();
+	/** Waiters for the writer's next commit (or rollback). */
+	#writerIdleWaiters = /* @__PURE__ */ new Set();
+	#purgedRows = getOrCreateCounter("replica", "sqlite_change_log.purged_rows", "Rows removed from the SQLite change log by the purge scheduler.");
+	#passDuration = getOrCreateLatencyHistogram("replica", "sqlite_change_log.purge_cycle_duration", "Duration of one SQLite change-log purge pass, including the yields between its batches.");
+	#passBatches = getOrCreateValueHistogram("replica", "sqlite_change_log.purge_cycle_batches", {
+		description: "Purge batches run per SQLite change-log purge pass.",
+		unit: "{batch}",
+		bucketBoundaries: [
+			1,
+			2,
+			5,
+			10,
+			25,
+			50,
+			100,
+			250
+		]
+	});
+	#declines = getOrCreateCounter("replica", "sqlite_change_log.purge_declined", "SQLite change-log purge passes that ended before draining, by reason.");
+	#floorProbes = getOrCreateCounter("replica", "sqlite_change_log.purge_floor_probe", "Invariant-14 probe outcomes: whether the transaction at the purge floor is still servable after each pass. \"violation\" means history at or above the floor was purged and alerts; \"cold-log\" means the log never held it, which is routine at every fork and resumption.");
+	#cache;
+	#stopped = false;
+	/**
+	* The guard that brackets catchup registration: required-head capture and
+	* `Forwarder.add()` run under the same mutex as purge batches, so the
+	* registered ACK is visible to `Forwarder.getAcks()` before the next batch
+	* evaluates its gate.
+	*/
+	cleanupGuard = { runWhilePurgeBlocked: (register) => this.#lock.withLock(register) };
+	/**
+	* @param connection the writer's own connection (§3.3). `undefined` until
+	*     the writer's first reconcile creates the file, and again after the
+	*     writer fails soft and deletes it — both of which defer the pass rather
+	*     than fail it, so a later coordinator pass picks up a late-appearing
+	*     file without a restart.
+	* @param subscriberAcks live subscriber ACKs, re-read before every batch so
+	*     the supplied floor remains safe throughout an asynchronous drain.
+	*/
+	constructor(lc, connection, subscriberAcks, opts) {
+		assert(Number.isSafeInteger(opts.retentionMs) && opts.retentionMs > 0, "sqliteChangeLogRetentionMs must be a positive integer");
+		assert(Number.isSafeInteger(opts.batchRows) && opts.batchRows > 0, "sqliteChangeLogPurgeBatchRows must be a positive integer");
+		this.#lc = lc.withContext("component", "sqlite-change-log-purge");
+		this.#connection = connection;
+		this.#subscriberAcks = subscriberAcks;
+		this.#opts = opts;
+		this.#now = opts.now ?? Date.now;
+		this.#setTimeoutFn = opts.setTimeoutFn ?? setTimeout;
+		this.#clearTimeoutFn = opts.clearTimeoutFn ?? clearTimeout;
+		this.#yield = opts.yieldFn ?? (() => new Promise((resolve) => setImmediate(resolve)));
+	}
+	/**
+	* Runs one purge pass for the current durable cleanup `floor`.
+	* Never rejects; a failed pass is logged and reported as `stopped: 'error'`.
+	*/
+	async purge(floor) {
+		if (this.#stopped) return this.#skipped(floor, "stopped");
+		try {
+			return await this.#runPass(floor);
+		} catch (e) {
+			this.#lc.warn?.("error purging the SQLite change log", e);
+			this.#declines.add(1, { reason: "error" });
+			return this.#skipped(floor, "error", "deferred");
+		}
+	}
+	/**
+	* Pauses purging while `taskID` holds a snapshot reservation. The returned
+	* promise resolves once no purge batch is in flight, i.e. once the bounds a
+	* backup monitor is about to advertise cannot be invalidated by a batch
+	* that had already been dispatched.
+	*/
+	pause(taskID) {
+		this.#pausedBy.set(taskID, (this.#pausedBy.get(taskID) ?? 0) + 1);
+		return this.#lock.withLock(() => {});
+	}
+	/**
+	* Ends one of `taskID`'s pauses. A later coordinator pass can purge once
+	* every reservation has ended. Unknown `taskID`s are ignored.
+	*/
+	resume(taskID) {
+		const count = this.#pausedBy.get(taskID);
+		if (count === void 0) return;
+		if (count > 1) {
+			this.#pausedBy.set(taskID, count - 1);
+			return;
+		}
+		this.#pausedBy.delete(taskID);
+	}
+	/**
+	* Notes that the writer's open transaction has ended, waking any batch
+	* waiting for a purge window. A missed notification costs one poll
+	* interval, never correctness.
+	*/
+	onWriterIdle() {
+		for (const waiter of this.#writerIdleWaiters) waiter();
+		this.#writerIdleWaiters.clear();
+	}
+	stop() {
+		this.#stopped = true;
+		this.onWriterIdle();
+	}
+	async #runPass(floor) {
+		const startedAt = performance.now();
+		let batches = 0;
+		let deletedRows = 0;
+		let stopped;
+		let db;
+		try {
+			for (;;) {
+				if (this.#stopped) {
+					stopped = "stopped";
+					break;
+				}
+				if (this.#pausedBy.size > 0) {
+					stopped = "paused";
+					break;
+				}
+				const connection = this.#connection();
+				if (connection === void 0) {
+					db = void 0;
+					this.#lc.debug?.("skipping SQLite change-log purge: the writer has not opened the log");
+					stopped = "writer-unavailable";
+					break;
+				}
+				db = connection;
+				if (batches >= Math.max(1, this.#opts.maxBatchesPerPass ?? DEFAULT_MAX_BATCHES_PER_PASS)) {
+					stopped = "batch-limit";
+					break;
+				}
+				if (connection.inTransaction) {
+					await this.#awaitWriterIdle();
+					continue;
+				}
+				const outcome = await this.#lock.withLock(() => {
+					if (this.#connection() !== connection || connection.inTransaction) return { kind: "retry" };
+					const declined = this.#gate(floor);
+					if (declined !== void 0) return {
+						kind: "declined",
+						reason: declined
+					};
+					return {
+						kind: "purged",
+						result: this.#cacheFor(connection).purger.purgeBatch({
+							externalFloor: floor,
+							retentionCutoffMs: this.#now() - this.#opts.retentionMs,
+							maxRows: this.#opts.batchRows,
+							maxDurationMs: this.#opts.statementTargetMs ?? DEFAULT_STATEMENT_TARGET_MS
+						})
+					};
+				});
+				if (outcome.kind === "retry") continue;
+				if (outcome.kind === "declined") {
+					stopped = outcome.reason;
+					break;
+				}
+				batches++;
+				deletedRows += outcome.result.deletedRows;
+				if (!outcome.result.moreEligible) break;
+				await this.#yield();
+			}
+		} catch (e) {
+			this.#lc.warn?.("error purging the SQLite change log", e);
+			stopped = "error";
+		}
+		const probe = db === void 0 ? void 0 : this.#probeFloor(db, floor);
+		let continuation;
+		try {
+			continuation = this.#continuation(floor, stopped);
+		} catch (e) {
+			this.#lc.warn?.("unable to determine whether SQLite change-log purge should continue", e);
+			continuation = "deferred";
+			stopped ??= "error";
+		}
+		if (deletedRows > 0) this.#purgedRows.add(deletedRows);
+		if (batches > 0) {
+			this.#passBatches.record(batches);
+			this.#passDuration.recordMs(performance.now() - startedAt);
+		}
+		if (stopped !== void 0) this.#declines.add(1, { reason: stopped });
+		if (batches > 0 || stopped !== "writer-unavailable") this.#lc.debug?.("SQLite change-log purge pass", { sqliteChangeLogPurge: {
+			floor,
+			batches,
+			deletedRows,
+			stopped,
+			probe,
+			continuation
+		} });
+		return {
+			floor,
+			batches,
+			deletedRows,
+			stopped,
+			probe,
+			continuation
+		};
+	}
+	/**
+	* Reports whether the level-triggered cleanup coordinator should run again.
+	* Rows below the floor but inside the retention window require a deferred
+	* pass even when no new backup watermark arrives, and so does a head behind
+	* the floor: the rows the writer replays into that gap arrive after this
+	* check, with no other event armed to reap them.
+	*/
+	#continuation(floor, stopped) {
+		switch (stopped) {
+			case "batch-limit": return "immediate";
+			case "stopped": return;
+			case "paused":
+			case "subscriber-behind":
+			case "writer-unavailable":
+			case "error": return "deferred";
+			case void 0: {
+				const db = this.#connection();
+				if (db === void 0) return "deferred";
+				const { remains, headBehindFloor } = this.#cacheFor(db).belowFloorRemains.get({ floor });
+				return remains === 0 && headBehindFloor === 0 ? void 0 : "deferred";
+			}
+		}
+	}
+	/**
+	* No purge while a connected subscriber is behind the supplied floor. The
+	* cleanup coordinator has already provided the reconnect grace period; an
+	* empty live set places no additional constraint on the durable floor.
+	*/
+	#gate(floor) {
+		for (const ack of this.#subscriberAcks()) if (ack < floor) return "subscriber-behind";
+	}
+	/**
+	* The live check on invariant 14 — what makes running this slice dark worth
+	* anything: in `write` mode nothing reads the log, so a wrong floor would
+	* otherwise stay invisible until the canary rollout two slices later.
+	*/
+	#probeFloor(db, floor) {
+		try {
+			const row = this.#cacheFor(db).plan.get({ fromWatermark: floor });
+			const { headWatermark, minWatermark } = row;
+			if (headWatermark === null || minWatermark === null) return;
+			let outcome;
+			if (floor > headWatermark) outcome = "ahead";
+			else if (floor < minWatermark || row.boundaryExists === 0) {
+				const { seedWatermark } = readChangeLogMeta(db);
+				outcome = seedWatermark <= floor ? "violation" : "cold-log";
+			} else outcome = "retained";
+			this.#floorProbes.add(1, { outcome });
+			if (outcome === "violation") this.#lc.error?.("SQLite change log purged history at or above the purge floor. A follower restoring to that watermark would get `too-old` and take a full restore.", { sqliteChangeLogFloorProbe: {
+				floor,
+				...row
+			} });
+			return outcome;
+		} catch (e) {
+			this.#lc.warn?.("unable to probe the SQLite change-log purge floor", e);
+			return;
+		}
+	}
+	/** Resolves once the writer's open transaction has committed or rolled back. */
+	#awaitWriterIdle() {
+		return new Promise((resolve) => {
+			let timer;
+			const waiter = () => {
+				if (timer !== void 0) this.#clearTimeoutFn(timer);
+				this.#writerIdleWaiters.delete(waiter);
+				resolve();
+			};
+			this.#writerIdleWaiters.add(waiter);
+			timer = this.#setTimeoutFn(waiter, this.#opts.inTransactionPollMs ?? DEFAULT_IN_TRANSACTION_POLL_MS);
+		});
+	}
+	/**
+	* The per-connection statements, rebuilt if the writer's connection ever
+	* changes. The purger's prepared statements survive a reseed — SQLite
+	* re-prepares on schema change — but not a different `Database`.
+	*/
+	#cacheFor(db) {
+		if (this.#cache?.db !== db) this.#cache = {
+			db,
+			purger: new SQLiteChangeLogPurger(db),
+			plan: db.prepare(SQLITE_CHANGE_LOG_PLAN_SQL),
+			belowFloorRemains: db.prepare(BELOW_FLOOR_REMAINS_SQL)
+		};
+		return this.#cache;
+	}
+	#skipped(floor, reason, continuation) {
+		return {
+			floor,
+			batches: 0,
+			deletedRows: 0,
+			stopped: reason,
+			probe: void 0,
+			continuation
+		};
+	}
+};
+//#endregion
+export { SQLiteChangeLogPurgeScheduler };
+
+//# sourceMappingURL=sqlite-change-log-purge-scheduler.js.map

package/out/zero-cache/src/services/change-streamer/sqlite-change-log-purge-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-purge-scheduler.js","names":["#lc","#connection","#subscriberAcks","#opts","#now","#setTimeoutFn","#clearTimeoutFn","#yield","#lock","#pausedBy","#writerIdleWaiters","#purgedRows","#passDuration","#passBatches","#declines","#floorProbes","#stopped","#skipped","#runPass","#awaitWriterIdle","#gate","#cacheFor","#probeFloor","#continuation","#cache"],"sources":["../../../../../../zero-cache/src/services/change-streamer/sqlite-change-log-purge-scheduler.ts"],"sourcesContent":["import {Lock} from '@rocicorp/lock';\nimport type {LogContext} from '@rocicorp/logger';\nimport {assert} from '../../../../shared/src/asserts.ts';\nimport type {Database, Statement} from '../../../../zqlite/src/db.ts';\nimport {\n  getOrCreateCounter,\n  getOrCreateLatencyHistogram,\n  getOrCreateValueHistogram,\n} from '../../observability/metrics.ts';\nimport {\n  CHANGE_LOG_STREAM_TABLE,\n  readChangeLogMeta,\n} from '../replicator/change-log-db.ts';\nimport {SQLiteChangeLogPurger} from '../replicator/sqlite-change-log-purger.ts';\nimport type {SQLiteChangeLogCleanupGuard} from './sqlite-change-log-catchup.ts';\nimport {SQLITE_CHANGE_LOG_PLAN_SQL} from './sqlite-change-log-reader.ts';\n\n/**\n * The duration target for any one purge statement, enforced by the purger's\n * measured-budget feedback. Purge runs on the writer's own\n * connection, in the stream loop's process, so a statement's duration stalls\n * the appending path — and the fan-out behind it — directly. The bench's\n * 100 ms bound was derived for the replicator's write worker; this budget is\n * measured against an event loop that also owes progress to fan-out, catchup,\n * and websocket keepalives, so it is deliberately tighter.\n */\nconst DEFAULT_STATEMENT_TARGET_MS = 20;\n\n/**\n * Batches per pass. This bounds one pass's bookkeeping, not the drain: a pass\n * that hits the limit asks its caller for an immediate continuation.\n */\nconst DEFAULT_MAX_BATCHES_PER_PASS = 100;\n\n/**\n * The backstop poll while waiting for the writer's open transaction to\n * commit. The commit notification normally arrives first; this covers an\n * interrupted stream, whose rollback does not notify.\n */\nconst DEFAULT_IN_TRANSACTION_POLL_MS = 1_000;\n\n/** Why a pass stopped before draining the eligible set. */\nexport type PurgeStopReason =\n  // The scheduler was stopped.\n  | 'stopped'\n  // A snapshot reservation is open.\n  | 'paused'\n  // The writer has not opened the change log (the file does not exist yet),\n  // or has failed soft and deleted it.\n  | 'writer-unavailable'\n  // A connected subscriber's ACK is behind the floor. Re-checked before every\n  // batch so a registration that lands mid-drain is honored by the very next\n  // batch.\n  | 'subscriber-behind'\n  // The per-pass batch limit was reached with history still eligible.\n  | 'batch-limit'\n  // The pass failed; the error was logged and counted.\n  | 'error';\n\n/**\n * The invariant-14 probe's classification of `plan(floor)` after a pass.\n *\n * `too-old` at the floor is not by itself a violation: a log that never held\n * that history — routine at every fork, restore, and rolling restart — returns\n * `too-old` without having purged anything. Only the seed point distinguishes\n * the two, which is why `seedWatermark` is in the v2 meta row:\n *\n * ```\n * violation  ⇔  plan(floor) is `too-old`  AND  seedWatermark <= floor\n * ```\n */\nexport type FloorProbeOutcome =\n  // plan(floor) is `range`: the transaction at the floor survives as a\n  // restoring follower's catchup boundary.\n  | 'retained'\n  // The floor is above the log's head, i.e. the log is stale/frozen and the\n  // head cap is what held retention. Nothing at the floor was ever purged.\n  | 'ahead'\n  // plan(floor) is `too-old` but the log was seeded above the floor: it never\n  // held that history. Charted, and feeds the fork/resumption reach\n  // measurement; not an alert.\n  | 'cold-log'\n  // plan(floor) is `too-old` and the log demonstrably once held the floor.\n  // This is an invariant-14 violation: the only copy a restoring follower\n  // could catch up from was purged.\n  | 'violation';\n\n/** When the cleanup coordinator should run another pass. */\nexport type PurgeContinuation =\n  // The pass hit its batch limit while eligible history remained.\n  | 'immediate'\n  // Progress depends on time or external state: retention, a subscriber ACK,\n  // a reservation, the writer becoming available, or a transient error.\n  | 'deferred';\n\nexport type PurgePassResult = {\n  /** The external floor the pass used. */\n  readonly floor: string;\n  readonly batches: number;\n  readonly deletedRows: number;\n  /** Why the pass ended before draining, if it did. */\n  readonly stopped: PurgeStopReason | undefined;\n  /** The invariant-14 probe's outcome, when the log was available to probe. */\n  readonly probe: FloorProbeOutcome | undefined;\n  /** Whether, and how soon, the cleanup coordinator should run another pass. */\n  readonly continuation: PurgeContinuation | undefined;\n};\n\nexport type SQLiteChangeLogPurgeSchedulerOptions = {\n  /**\n   * `sqliteChangeLogRetentionMs`: the minimum retention window, ANDed on top\n   * of the external floor. It can only make purge more conservative — the\n   * purger never accepts it as a standalone bound.\n   */\n  readonly retentionMs: number;\n  /**\n   * `sqliteChangeLogPurgeBatchRows`: the starting chunk size per batch. Not\n   * the bound — the statement duration target is.\n   */\n  readonly batchRows: number;\n  readonly statementTargetMs?: number | undefined;\n  readonly maxBatchesPerPass?: number | undefined;\n  readonly inTransactionPollMs?: number | undefined;\n  /** The clock the retention cutoff is measured against. Defaults to `Date.now`. */\n  readonly now?: (() => number) | undefined;\n  readonly setTimeoutFn?: typeof setTimeout | undefined;\n  readonly clearTimeoutFn?: typeof clearTimeout | undefined;\n  /**\n   * Awaited between batches so fan-out and catchup make progress. Defaults to\n   * a macrotask (`setImmediate`), so pending I/O runs before the next batch.\n   */\n  readonly yieldFn?: (() => Promise<void>) | undefined;\n};\n\ntype ConnectionCache = {\n  readonly db: Database;\n  readonly purger: SQLiteChangeLogPurger;\n  readonly plan: Statement;\n  readonly belowFloorRemains: Statement;\n};\n\ntype PlanRow = {\n  readonly headWatermark: string | null;\n  readonly minWatermark: string | null;\n  readonly boundaryExists: number;\n};\n\n/**\n * Whether the cleanup coordinator still owes this floor a pass. Deliberately\n * not the purger's eligibility query, in two ways:\n *\n * - `remains`: rows younger than the retention cutoff are not eligible *yet*,\n *   but they will be, and their presence asks the cleanup coordinator for a\n *   deferred pass even on a quiet source.\n * - `headBehindFloor`: a head behind the floor means the writer is expected\n *   to replay commits below it (e.g. after reconnecting while the backup\n *   outran this log). Those rows do not exist to count yet, writer commits\n *   only wake an in-flight waiter, and backup monitors never resend an\n *   unchanged floor — so reporting quiescence here would disarm cleanup for\n *   good. An empty log (no head) defers for the same reason.\n */\nconst BELOW_FLOOR_REMAINS_SQL = /*sql*/ `\n  SELECT\n    EXISTS (\n      SELECT 1 FROM \"${CHANGE_LOG_STREAM_TABLE}\"\n      WHERE \"watermark\" < @floor\n        AND \"watermark\" < (SELECT max(\"watermark\") FROM \"${CHANGE_LOG_STREAM_TABLE}\")\n    ) AS \"remains\",\n    coalesce(\n      (SELECT max(\"watermark\") FROM \"${CHANGE_LOG_STREAM_TABLE}\") < @floor,\n      1\n    ) AS \"headBehindFloor\"\n`;\n\n/**\n * Runs bounded SQLite change-log purge passes on the writer's own connection.\n *\n * The caller supplies the current durable cleanup floor independently of any\n * other change-log implementation and owns the timing of subsequent passes.\n * Within a pass this class drains bounded batches, re-checking live subscriber\n * ACKs before each one and releasing the cleanup guard between them, so a\n * catchup registration or snapshot reservation never waits longer than one\n * batch.\n *\n * Purge windows exist only between the writer's commits: purge shares the\n * writer's connection, so it cannot run inside the writer's open transaction,\n * and a batch that finds one waits for the commit notification instead.\n *\n * The result tells the cleanup coordinator whether the next pass should be\n * immediate or deferred. This class deliberately owns no cleanup timer: the\n * same level-triggered coordinator continues a large drain, advances the\n * retention clock on a quiet source, and retries changing external state.\n */\nexport class SQLiteChangeLogPurgeScheduler {\n  readonly #lc: LogContext;\n  readonly #connection: () => Database | undefined;\n  readonly #subscriberAcks: () => Iterable<string>;\n  readonly #opts: SQLiteChangeLogPurgeSchedulerOptions;\n  readonly #now: () => number;\n  readonly #setTimeoutFn: typeof setTimeout;\n  readonly #clearTimeoutFn: typeof clearTimeout;\n  readonly #yield: () => Promise<void>;\n\n  /**\n   * The mutex that serializes purge batches with catchup registration and\n   * reservation pauses. It is only ever held across a synchronous section —\n   * one batch, or one registration — never across a yield, which is what\n   * bounds any waiter to a single batch's duration.\n   */\n  readonly #lock = new Lock();\n\n  /**\n   * Open snapshot reservations, reference-counted by taskID. Purge pauses\n   * while any is open. Counted rather than a set so that a reservation retry\n   * -- whose cancel-then-recreate can resolve its old resume after its new\n   * suspend -- still nets out.\n   */\n  readonly #pausedBy = new Map<string, number>();\n\n  /** Waiters for the writer's next commit (or rollback). */\n  readonly #writerIdleWaiters = new Set<() => void>();\n\n  readonly #purgedRows = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.purged_rows',\n    'Rows removed from the SQLite change log by the purge scheduler.',\n  );\n  readonly #passDuration = getOrCreateLatencyHistogram(\n    'replica',\n    'sqlite_change_log.purge_cycle_duration',\n    'Duration of one SQLite change-log purge pass, including the yields ' +\n      'between its batches.',\n  );\n  readonly #passBatches = getOrCreateValueHistogram(\n    'replica',\n    'sqlite_change_log.purge_cycle_batches',\n    {\n      description: 'Purge batches run per SQLite change-log purge pass.',\n      unit: '{batch}',\n      bucketBoundaries: [1, 2, 5, 10, 25, 50, 100, 250],\n    },\n  );\n  readonly #declines = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.purge_declined',\n    'SQLite change-log purge passes that ended before draining, by reason.',\n  );\n  readonly #floorProbes = getOrCreateCounter(\n    'replica',\n    'sqlite_change_log.purge_floor_probe',\n    'Invariant-14 probe outcomes: whether the transaction at the purge ' +\n      'floor is still servable after each pass. \"violation\" means history ' +\n      'at or above the floor was purged and alerts; \"cold-log\" means the ' +\n      'log never held it, which is routine at every fork and resumption.',\n  );\n\n  #cache: ConnectionCache | undefined;\n  #stopped = false;\n\n  /**\n   * The guard that brackets catchup registration: required-head capture and\n   * `Forwarder.add()` run under the same mutex as purge batches, so the\n   * registered ACK is visible to `Forwarder.getAcks()` before the next batch\n   * evaluates its gate.\n   */\n  readonly cleanupGuard: SQLiteChangeLogCleanupGuard = {\n    runWhilePurgeBlocked: register => this.#lock.withLock(register),\n  };\n\n  /**\n   * @param connection the writer's own connection (§3.3). `undefined` until\n   *     the writer's first reconcile creates the file, and again after the\n   *     writer fails soft and deletes it — both of which defer the pass rather\n   *     than fail it, so a later coordinator pass picks up a late-appearing\n   *     file without a restart.\n   * @param subscriberAcks live subscriber ACKs, re-read before every batch so\n   *     the supplied floor remains safe throughout an asynchronous drain.\n   */\n  constructor(\n    lc: LogContext,\n    connection: () => Database | undefined,\n    subscriberAcks: () => Iterable<string>,\n    opts: SQLiteChangeLogPurgeSchedulerOptions,\n  ) {\n    assert(\n      Number.isSafeInteger(opts.retentionMs) && opts.retentionMs > 0,\n      'sqliteChangeLogRetentionMs must be a positive integer',\n    );\n    assert(\n      Number.isSafeInteger(opts.batchRows) && opts.batchRows > 0,\n      'sqliteChangeLogPurgeBatchRows must be a positive integer',\n    );\n    this.#lc = lc.withContext('component', 'sqlite-change-log-purge');\n    this.#connection = connection;\n    this.#subscriberAcks = subscriberAcks;\n    this.#opts = opts;\n    this.#now = opts.now ?? Date.now;\n    this.#setTimeoutFn = opts.setTimeoutFn ?? setTimeout;\n    this.#clearTimeoutFn = opts.clearTimeoutFn ?? clearTimeout;\n    this.#yield =\n      opts.yieldFn ??\n      (() => new Promise<void>(resolve => setImmediate(resolve)));\n  }\n\n  /**\n   * Runs one purge pass for the current durable cleanup `floor`.\n   * Never rejects; a failed pass is logged and reported as `stopped: 'error'`.\n   */\n  async purge(floor: string): Promise<PurgePassResult> {\n    if (this.#stopped) {\n      return this.#skipped(floor, 'stopped');\n    }\n    try {\n      return await this.#runPass(floor);\n    } catch (e) {\n      this.#lc.warn?.('error purging the SQLite change log', e);\n      this.#declines.add(1, {reason: 'error'});\n      return this.#skipped(floor, 'error', 'deferred');\n    }\n  }\n\n  /**\n   * Pauses purging while `taskID` holds a snapshot reservation. The returned\n   * promise resolves once no purge batch is in flight, i.e. once the bounds a\n   * backup monitor is about to advertise cannot be invalidated by a batch\n   * that had already been dispatched.\n   */\n  pause(taskID: string): Promise<void> {\n    this.#pausedBy.set(taskID, (this.#pausedBy.get(taskID) ?? 0) + 1);\n    return this.#lock.withLock(() => {});\n  }\n\n  /**\n   * Ends one of `taskID`'s pauses. A later coordinator pass can purge once\n   * every reservation has ended. Unknown `taskID`s are ignored.\n   */\n  resume(taskID: string): void {\n    const count = this.#pausedBy.get(taskID);\n    if (count === undefined) {\n      return;\n    }\n    if (count > 1) {\n      this.#pausedBy.set(taskID, count - 1);\n      return;\n    }\n    this.#pausedBy.delete(taskID);\n  }\n\n  /**\n   * Notes that the writer's open transaction has ended, waking any batch\n   * waiting for a purge window. A missed notification costs one poll\n   * interval, never correctness.\n   */\n  onWriterIdle(): void {\n    for (const waiter of this.#writerIdleWaiters) {\n      waiter();\n    }\n    this.#writerIdleWaiters.clear();\n  }\n\n  stop(): void {\n    this.#stopped = true;\n    this.onWriterIdle();\n  }\n\n  async #runPass(floor: string): Promise<PurgePassResult> {\n    const startedAt = performance.now();\n    let batches = 0;\n    let deletedRows = 0;\n    let stopped: PurgeStopReason | undefined;\n    let db: Database | undefined;\n\n    try {\n      for (;;) {\n        if (this.#stopped) {\n          stopped = 'stopped';\n          break;\n        }\n        if (this.#pausedBy.size > 0) {\n          stopped = 'paused';\n          break;\n        }\n        const connection = this.#connection();\n        if (connection === undefined) {\n          db = undefined;\n          this.#lc.debug?.(\n            'skipping SQLite change-log purge: the writer has not opened the log',\n          );\n          stopped = 'writer-unavailable';\n          break;\n        }\n        db = connection;\n        if (\n          batches >=\n          Math.max(\n            1,\n            this.#opts.maxBatchesPerPass ?? DEFAULT_MAX_BATCHES_PER_PASS,\n          )\n        ) {\n          stopped = 'batch-limit';\n          break;\n        }\n        if (connection.inTransaction) {\n          // Purge windows exist only between the writer's commits (§3.3).\n          await this.#awaitWriterIdle();\n          continue;\n        }\n\n        const outcome = await this.#lock.withLock(() => {\n          // Everything the wait above established is re-checked under the lock:\n          // the writer may have begun another transaction or failed soft while\n          // this batch's acquisition was queued behind a registration.\n          if (this.#connection() !== connection || connection.inTransaction) {\n            return {kind: 'retry'} as const;\n          }\n          const declined = this.#gate(floor);\n          if (declined !== undefined) {\n            return {kind: 'declined', reason: declined} as const;\n          }\n          const result = this.#cacheFor(connection).purger.purgeBatch({\n            externalFloor: floor,\n            retentionCutoffMs: this.#now() - this.#opts.retentionMs,\n            maxRows: this.#opts.batchRows,\n            maxDurationMs:\n              this.#opts.statementTargetMs ?? DEFAULT_STATEMENT_TARGET_MS,\n          });\n          return {kind: 'purged', result} as const;\n        });\n\n        if (outcome.kind === 'retry') {\n          continue;\n        }\n        if (outcome.kind === 'declined') {\n          stopped = outcome.reason;\n          break;\n        }\n        batches++;\n        deletedRows += outcome.result.deletedRows;\n        if (!outcome.result.moreEligible) {\n          break;\n        }\n        // Release the loop — and the guard, released above — so fan-out,\n        // catchup, and registrations make progress between batches.\n        await this.#yield();\n      }\n    } catch (e) {\n      // Earlier batches committed independently and must remain visible in the\n      // result and metrics. Finalize the partial pass, including its floor\n      // probe, rather than replacing it with an empty skipped result.\n      this.#lc.warn?.('error purging the SQLite change log', e);\n      stopped = 'error';\n    }\n\n    const probe = db === undefined ? undefined : this.#probeFloor(db, floor);\n    let continuation: PurgeContinuation | undefined;\n    try {\n      continuation = this.#continuation(floor, stopped);\n    } catch (e) {\n      // A connection can fail soft between the pass and this level check. Keep\n      // completed batches visible and ask the coordinator to retry later.\n      this.#lc.warn?.(\n        'unable to determine whether SQLite change-log purge should continue',\n        e,\n      );\n      continuation = 'deferred';\n      stopped ??= 'error';\n    }\n    if (deletedRows > 0) {\n      this.#purgedRows.add(deletedRows);\n    }\n    if (batches > 0) {\n      this.#passBatches.record(batches);\n      this.#passDuration.recordMs(performance.now() - startedAt);\n    }\n    if (stopped !== undefined) {\n      this.#declines.add(1, {reason: stopped});\n    }\n    if (batches > 0 || stopped !== 'writer-unavailable') {\n      this.#lc.debug?.('SQLite change-log purge pass', {\n        sqliteChangeLogPurge: {\n          floor,\n          batches,\n          deletedRows,\n          stopped,\n          probe,\n          continuation,\n        },\n      });\n    }\n    return {floor, batches, deletedRows, stopped, probe, continuation};\n  }\n\n  /**\n   * Reports whether the level-triggered cleanup coordinator should run again.\n   * Rows below the floor but inside the retention window require a deferred\n   * pass even when no new backup watermark arrives, and so does a head behind\n   * the floor: the rows the writer replays into that gap arrive after this\n   * check, with no other event armed to reap them.\n   */\n  #continuation(\n    floor: string,\n    stopped: PurgeStopReason | undefined,\n  ): PurgeContinuation | undefined {\n    switch (stopped) {\n      case 'batch-limit':\n        return 'immediate';\n      case 'stopped':\n        return undefined;\n      case 'paused':\n      case 'subscriber-behind':\n      case 'writer-unavailable':\n      case 'error':\n        return 'deferred';\n      case undefined: {\n        // A read is safe even inside the writer's open transaction; it just\n        // observes the uncommitted head, which is never below the floor.\n        const db = this.#connection();\n        if (db === undefined) {\n          return 'deferred';\n        }\n        const {remains, headBehindFloor} = this.#cacheFor(\n          db,\n        ).belowFloorRemains.get<{\n          remains: number;\n          headBehindFloor: number;\n        }>({floor});\n        return remains === 0 && headBehindFloor === 0 ? undefined : 'deferred';\n      }\n    }\n  }\n\n  /**\n   * No purge while a connected subscriber is behind the supplied floor. The\n   * cleanup coordinator has already provided the reconnect grace period; an\n   * empty live set places no additional constraint on the durable floor.\n   */\n  #gate(floor: string): 'subscriber-behind' | undefined {\n    for (const ack of this.#subscriberAcks()) {\n      if (ack < floor) {\n        return 'subscriber-behind';\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * The live check on invariant 14 — what makes running this slice dark worth\n   * anything: in `write` mode nothing reads the log, so a wrong floor would\n   * otherwise stay invisible until the canary rollout two slices later.\n   */\n  #probeFloor(db: Database, floor: string): FloorProbeOutcome | undefined {\n    try {\n      const cache = this.#cacheFor(db);\n      const row = cache.plan.get<PlanRow>({fromWatermark: floor});\n      const {headWatermark, minWatermark} = row;\n      if (headWatermark === null || minWatermark === null) {\n        return undefined;\n      }\n      let outcome: FloorProbeOutcome;\n      if (floor > headWatermark) {\n        outcome = 'ahead';\n      } else if (floor < minWatermark || row.boundaryExists === 0) {\n        const {seedWatermark} = readChangeLogMeta(db);\n        outcome = seedWatermark <= floor ? 'violation' : 'cold-log';\n      } else {\n        outcome = 'retained';\n      }\n      this.#floorProbes.add(1, {outcome});\n      if (outcome === 'violation') {\n        this.#lc.error?.(\n          'SQLite change log purged history at or above the purge floor. A ' +\n            'follower restoring to that watermark would get `too-old` and ' +\n            'take a full restore.',\n          {sqliteChangeLogFloorProbe: {floor, ...row}},\n        );\n      }\n      return outcome;\n    } catch (e) {\n      this.#lc.warn?.('unable to probe the SQLite change-log purge floor', e);\n      return undefined;\n    }\n  }\n\n  /** Resolves once the writer's open transaction has committed or rolled back. */\n  #awaitWriterIdle(): Promise<void> {\n    return new Promise<void>(resolve => {\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      const waiter = () => {\n        if (timer !== undefined) {\n          this.#clearTimeoutFn(timer);\n        }\n        this.#writerIdleWaiters.delete(waiter);\n        resolve();\n      };\n      this.#writerIdleWaiters.add(waiter);\n      timer = this.#setTimeoutFn(\n        waiter,\n        this.#opts.inTransactionPollMs ?? DEFAULT_IN_TRANSACTION_POLL_MS,\n      );\n    });\n  }\n\n  /**\n   * The per-connection statements, rebuilt if the writer's connection ever\n   * changes. The purger's prepared statements survive a reseed — SQLite\n   * re-prepares on schema change — but not a different `Database`.\n   */\n  #cacheFor(db: Database): ConnectionCache {\n    if (this.#cache?.db !== db) {\n      this.#cache = {\n        db,\n        purger: new SQLiteChangeLogPurger(db),\n        plan: db.prepare(SQLITE_CHANGE_LOG_PLAN_SQL),\n        belowFloorRemains: db.prepare(BELOW_FLOOR_REMAINS_SQL),\n      };\n    }\n    return this.#cache;\n  }\n\n  #skipped(\n    floor: string,\n    reason: PurgeStopReason,\n    continuation?: PurgeContinuation | undefined,\n  ): PurgePassResult {\n    return {\n      floor,\n      batches: 0,\n      deletedRows: 0,\n      stopped: reason,\n      probe: undefined,\n      continuation,\n    };\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,62 @@
+import type { LogContext } from '@rocicorp/logger';
+import type { WatermarkedChange } from './change-streamer.ts';
+export type CatchupPlan = {
+    readonly kind: 'range';
+    readonly minWatermark: string;
+    readonly headWatermark: string;
+} | {
+    readonly kind: 'ahead';
+    readonly headWatermark: string;
+} | {
+    readonly kind: 'too-old';
+    readonly minWatermark: string;
+    readonly headWatermark: string;
+} | {
+    readonly kind: 'not-ready';
+};
+/**
+ * Seeks to the final position so validating a boundary does not scan every row
+ * of a large transaction. Exported so the focused query-plan test covers the
+ * production subquery.
+ */
+export declare const SQLITE_CHANGE_LOG_BOUNDARY_SQL = "\n  SELECT\n    \"precommit\" = @fromWatermark AND\n      \"tag\" = 'commit' AS \"boundaryExists\"\n  FROM \"_zero.changeLogStream\"\n  WHERE \"watermark\" = @fromWatermark\n  ORDER BY \"pos\" DESC\n  LIMIT 1\n";
+/**
+ * The log describes its own bounds; nothing here reads the replica.
+ * `max("watermark")` is the head because a transaction's rows commit atomically,
+ * so the log never ends mid-transaction.
+ *
+ * `min` and `max` are deliberately kept as *separate* scalar subqueries: SQLite
+ * applies its single-aggregate index optimization only when the aggregate is
+ * alone in its query, so `SELECT min(x), max(x) FROM t` degrades to a full scan
+ * while two scalar subqueries are two index seeks. The query-plan test pins
+ * this.
+ *
+ * Exported so that test can cover the production query.
+ */
+export declare const SQLITE_CHANGE_LOG_PLAN_SQL = "\n  SELECT\n    (SELECT max(\"watermark\") FROM \"_zero.changeLogStream\")\n      AS \"headWatermark\",\n    (SELECT min(\"watermark\") FROM \"_zero.changeLogStream\")\n      AS \"minWatermark\",\n    coalesce((\n  SELECT\n    \"precommit\" = @fromWatermark AND\n      \"tag\" = 'commit' AS \"boundaryExists\"\n  FROM \"_zero.changeLogStream\"\n  WHERE \"watermark\" = @fromWatermark\n  ORDER BY \"pos\" DESC\n  LIMIT 1\n), 0) AS \"boundaryExists\"\n";
+/** Exported so the focused query-plan test covers the production query. */
+export declare const SQLITE_CHANGE_LOG_READ_BATCH_SQL = "\n  SELECT\n    \"watermark\",\n    \"pos\",\n    \"tag\",\n    \"change\"\n  FROM \"_zero.changeLogStream\"\n  WHERE (\"watermark\", \"pos\") > (?, ?)\n    AND \"watermark\" <= ?\n  ORDER BY \"watermark\", \"pos\"\n  LIMIT ?\n";
+/**
+ * Reads the change log without retaining a SQLite snapshot while a consumer
+ * processes a batch.
+ *
+ * The log lives in its own database beside the replica
+ * (`changeLogFileName(replicaFile)`), which this reader opens read-only; it
+ * never opens the replica. The connection therefore keeps the journal mode
+ * configured by the change-log writer. Callers pin a head with {@link plan}
+ * before passing it to {@link read}.
+ *
+ * A change-streamer can start before the replicator has created the log, so the
+ * stream table may not exist yet. Statements are prepared on first use rather
+ * than in the constructor, and {@link plan} reports `not-ready` until they can
+ * be; a reader constructed too early becomes usable once the writer catches up.
+ */
+export declare class SQLiteChangeLogReader implements Disposable {
+    #private;
+    constructor(lc: LogContext, changeLogFile: string);
+    plan(fromWatermark: string): CatchupPlan;
+    read(fromWatermark: string, throughWatermark: string, batchSize: number, signal?: AbortSignal | undefined): AsyncIterable<readonly WatermarkedChange[]>;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=sqlite-change-log-reader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-change-log-reader.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/sqlite-change-log-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AASjD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,sBAAsB,CAAC;AAE5D,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GACD;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAC,GACxD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GAKD;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAC,CAAC;AAiBjC;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,uNAQ1C,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,ucAOtC,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,gCAAgC,wOAW5C,CAAC;AAMF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,qBAAsB,YAAW,UAAU;;gBAK1C,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM;IAQjD,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,WAAW;IAqBjC,IAAI,CACT,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,GAC/B,aAAa,CAAC,SAAS,iBAAiB,EAAE,CAAC;IA2D9C,KAAK,IAAI,IAAI;IAQb,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAuCzB"}