@rocicorp/zero 0.0.0-202410031711

package/out/zero-cache/src/server/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../../../zero-cache/src/server/main.ts"],"names":[],"mappings":"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"}

package/out/zero-cache/src/server/replicator.d.ts

@@ -0,0 +1,3 @@
+import { type Worker } from '../types/processes.js';
+export default function runWorker(parent: Worker, ...args: string[]): Promise<void>;
+//# sourceMappingURL=replicator.d.ts.map

package/out/zero-cache/src/server/replicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replicator.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/replicator.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAQ/B,wBAA8B,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,iBA+BxE"}

package/out/zero-cache/src/server/replicator.js

@@ -0,0 +1,35 @@
+import { pid } from 'node:process';
+import { assert } from '../../../shared/src/asserts.js';
+import { must } from '../../../shared/src/must.js';
+import { getZeroConfig } from '../config/zero-config.js';
+import { ChangeStreamerHttpClient } from '../services/change-streamer/change-streamer-http.js';
+import { NULL_CHECKPOINTER } from '../services/replicator/checkpointer.js';
+import { ReplicatorService } from '../services/replicator/replicator.js';
+import { runOrExit } from '../services/runner.js';
+import { parentWorker, singleProcessMode, } from '../types/processes.js';
+import { setUpMessageHandlers, setupReplica, } from '../workers/replicator.js';
+import { createLogContext } from './logging.js';
+export default async function runWorker(parent, ...args) {
+    const config = await getZeroConfig();
+    assert(args.length > 0, `replicator mode not specified`);
+    const mode = args[0];
+    const workerName = `${mode === 'backup' ? 'backup' : 'serving'}-replicator`;
+    const lc = createLogContext(config.log, { worker: workerName });
+    const replica = setupReplica(lc, mode, config.replicaDbFile);
+    const changeStreamer = config.changeStreamerUri
+        ? new ChangeStreamerHttpClient(lc, config.changeStreamerUri)
+        : new ChangeStreamerHttpClient(lc);
+    const replicator = new ReplicatorService(lc, `${workerName}-${pid}`, changeStreamer, replica, NULL_CHECKPOINTER);
+    setUpMessageHandlers(lc, replicator, parent);
+    void runOrExit(lc, replicator);
+    // Signal readiness once the first ReplicaVersionReady notification is received.
+    for await (const _ of replicator.subscribe()) {
+        parent.send(['ready', { ready: true }]);
+        break;
+    }
+}
+// fork()
+if (!singleProcessMode()) {
+    void runWorker(must(parentWorker), ...process.argv.slice(2));
+}
+//# sourceMappingURL=replicator.js.map

package/out/zero-cache/src/server/replicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replicator.js","sourceRoot":"","sources":["../../../../../zero-cache/src/server/replicator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,GAAG,EAAC,MAAM,cAAc,CAAC;AACjC,OAAO,EAAC,MAAM,EAAC,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAC,IAAI,EAAC,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAC,aAAa,EAAC,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAC,wBAAwB,EAAC,MAAM,qDAAqD,CAAC;AAC7F,OAAO,EAAC,iBAAiB,EAAC,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAC,iBAAiB,EAAC,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAChD,OAAO,EACL,YAAY,EACZ,iBAAiB,GAElB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,oBAAoB,EACpB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAC,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAE9C,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,SAAS,CAAC,MAAc,EAAE,GAAG,IAAc;IACvE,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;IACrC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,+BAA+B,CAAC,CAAC;IAEzD,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAmB,CAAC;IACvC,MAAM,UAAU,GAAG,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,aAAa,CAAC;IAC5E,MAAM,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,GAAG,EAAE,EAAC,MAAM,EAAE,UAAU,EAAC,CAAC,CAAC;IAE9D,MAAM,OAAO,GAAG,YAAY,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IAE7D,MAAM,cAAc,GAAG,MAAM,CAAC,iBAAiB;QAC7C,CAAC,CAAC,IAAI,wBAAwB,CAAC,EAAE,EAAE,MAAM,CAAC,iBAAiB,CAAC;QAC5D,CAAC,CAAC,IAAI,wBAAwB,CAAC,EAAE,CAAC,CAAC;IAErC,MAAM,UAAU,GAAG,IAAI,iBAAiB,CACtC,EAAE,EACF,GAAG,UAAU,IAAI,GAAG,EAAE,EACtB,cAAc,EACd,OAAO,EACP,iBAAiB,CAClB,CAAC;IAEF,oBAAoB,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAE7C,KAAK,SAAS,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAE/B,gFAAgF;IAChF,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC,CAAC,CAAC;QACtC,MAAM;IACR,CAAC;AACH,CAAC;AAED,SAAS;AACT,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;IACzB,KAAK,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/out/zero-cache/src/server/syncer.d.ts

@@ -0,0 +1,3 @@
+import { type Worker } from '../types/processes.js';
+export default function runWorker(parent: Worker): Promise<void>;
+//# sourceMappingURL=syncer.d.ts.map

package/out/zero-cache/src/server/syncer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncer.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/server/syncer.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAK/B,wBAA8B,SAAS,CAAC,MAAM,EAAE,MAAM,iBAoDrD"}

package/out/zero-cache/src/server/syncer.js

@@ -0,0 +1,45 @@
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pid } from 'node:process';
+import { must } from '../../../shared/src/must.js';
+import { randInt } from '../../../shared/src/rand.js';
+import { getZeroConfig } from '../config/zero-config.js';
+import { MutagenService } from '../services/mutagen/mutagen.js';
+import { DatabaseStorage } from '../services/view-syncer/database-storage.js';
+import { PipelineDriver } from '../services/view-syncer/pipeline-driver.js';
+import { Snapshotter } from '../services/view-syncer/snapshotter.js';
+import { ViewSyncerService } from '../services/view-syncer/view-syncer.js';
+import { pgClient } from '../types/pg.js';
+import { parentWorker, singleProcessMode, } from '../types/processes.js';
+import { Subscription } from '../types/subscription.js';
+import { Syncer } from '../workers/syncer.js';
+import { createLogContext } from './logging.js';
+export default async function runWorker(parent) {
+    const config = await getZeroConfig();
+    // Consider parameterizing these (in main) based on total number of workers.
+    const MAX_CVR_CONNECTIONS = 5;
+    const MAX_MUTAGEN_CONNECTIONS = 5;
+    const lc = createLogContext(config.log, { worker: 'syncer' });
+    const cvrDB = pgClient(lc, config.cvrDbUri, {
+        max: MAX_CVR_CONNECTIONS,
+    });
+    const upstreamDB = pgClient(lc, config.upstreamUri, {
+        max: MAX_MUTAGEN_CONNECTIONS,
+    });
+    const dbWarmup = Promise.allSettled([
+        ...Array.from({ length: MAX_CVR_CONNECTIONS }, () => cvrDB `SELECT 1`.simple().execute()),
+        ...Array.from({ length: MAX_MUTAGEN_CONNECTIONS }, () => upstreamDB `SELECT 1`.simple().execute()),
+    ]);
+    const tmpDir = config.storageDbTmpDir ?? tmpdir();
+    const operatorStorage = DatabaseStorage.create(lc, path.join(tmpDir, `sync-worker-${pid}-${randInt(1000000, 9999999)}`));
+    const viewSyncerFactory = (id, sub) => new ViewSyncerService(lc, id, cvrDB, new PipelineDriver(lc, new Snapshotter(lc, config.replicaDbFile), operatorStorage.createClientGroupStorage(id)), sub);
+    const mutagenFactory = (id) => new MutagenService(lc, config.shard.id, id, upstreamDB, config);
+    new Syncer(lc, config, viewSyncerFactory, mutagenFactory, parent).run();
+    await dbWarmup;
+    parent.send(['ready', { ready: true }]);
+}
+// fork()
+if (!singleProcessMode()) {
+    void runWorker(must(parentWorker));
+}
+//# sourceMappingURL=syncer.js.map

package/out/zero-cache/src/server/syncer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncer.js","sourceRoot":"","sources":["../../../../../zero-cache/src/server/syncer.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,23 @@
+import { LogContext } from '@rocicorp/logger';
+import { type Source } from '../../../../zero-cache/src/types/streams.js';
+import type { Service } from '../service.js';
+import type { ChangeStreamer, Downstream, SubscriberContext } from './change-streamer.js';
+export declare const CHANGES_URL_PATTERN = "/api/replication/:version/changes";
+export declare const DEFAULT_PORT = 2999;
+export type Options = {
+    port: number;
+};
+export declare class ChangeStreamerHttpServer implements Service {
+    #private;
+    readonly id = "change-streamer-http-server";
+    constructor(lc: LogContext, delegate: ChangeStreamer, opts?: Partial<Options>);
+    start(): Promise<void>;
+    run(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare class ChangeStreamerHttpClient implements ChangeStreamer {
+    #private;
+    constructor(lc: LogContext, uriOrPort?: string | number);
+    subscribe(ctx: SubscriberContext): Source<Downstream>;
+}
+//# sourceMappingURL=change-streamer-http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"change-streamer-http.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/change-streamer-http.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAS5C,OAAO,EACL,KAAK,MAAM,EAGZ,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,mBAAmB,sCAAsC,CAAC;AAEvE,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,qBAAa,wBAAyB,YAAW,OAAO;;IACtD,QAAQ,CAAC,EAAE,iCAAiC;gBAQ1C,EAAE,EAAE,UAAU,EACd,QAAQ,EAAE,cAAc,EACxB,IAAI,GAAE,OAAO,CAAC,OAAO,CAAM;IAavB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBpB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAI5B;AAED,qBAAa,wBAAyB,YAAW,cAAc;;gBAIjD,EAAE,EAAE,UAAU,EAAE,SAAS,GAAE,MAAM,GAAG,MAAqB;IASrE,SAAS,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAAC,UAAU,CAAC;CAMtD"}

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

@@ -0,0 +1,98 @@
+import websocket from '@fastify/websocket';
+import { LogContext } from '@rocicorp/logger';
+import Fastify, {} from 'fastify';
+import * as v from '../../../../shared/src/valita.js';
+import WebSocket from 'ws';
+import { jsonValueSchema } from '../../../../zero-cache/src/types/bigint-json.js';
+import { streamIn, streamOut, } from '../../../../zero-cache/src/types/streams.js';
+import { URLParams } from '../../../../zero-cache/src/types/url-params.js';
+import { RunningState } from '../running-state.js';
+export const CHANGES_URL_PATTERN = '/api/replication/:version/changes';
+export const DEFAULT_PORT = 2999;
+export class ChangeStreamerHttpServer {
+    id = 'change-streamer-http-server';
+    #lc;
+    #delegate;
+    #fastify;
+    #port;
+    #state = new RunningState(this.id);
+    constructor(lc, delegate, opts = {}) {
+        const { port = DEFAULT_PORT } = opts;
+        this.#lc = lc.withContext('component', this.id);
+        this.#delegate = delegate;
+        this.#fastify = Fastify();
+        this.#port = port;
+    }
+    // start() is used in unit tests.
+    // run() is the lifecycle method called by the ServiceRunner.
+    async start() {
+        await this.#fastify.register(websocket);
+        this.#fastify.get('/', (_req, res) => res.send('OK'));
+        this.#fastify.addHook('preValidation', this.#checkParams);
+        this.#fastify.get(CHANGES_URL_PATTERN, { websocket: true }, this.#subscribe);
+        const address = await this.#fastify.listen({ port: this.#port });
+        this.#lc.info?.(`Server listening at ${address}`);
+    }
+    async run() {
+        await this.start();
+        await this.#state.stopped();
+    }
+    // Avoid upgrading to a websocket if the params are bad.
+    #checkParams = async (req, reply) => {
+        if (req.url === '/' || req.url.startsWith('/?')) {
+            return; // Health check
+        }
+        try {
+            getSubscriberContext(req);
+        }
+        catch (e) {
+            this.#lc.error?.('bad request', String(e));
+            await reply.code(400).send(e instanceof Error ? e.message : String(e));
+        }
+    };
+    #subscribe = async (ws, req) => {
+        const ctx = getSubscriberContext(req); // #checkSubscribe guarantees this.
+        const downstream = this.#delegate.subscribe(ctx);
+        await streamOut(this.#lc, downstream, ws);
+    };
+    async stop() {
+        await this.#fastify.close();
+        this.#state.stop(this.#lc);
+    }
+}
+export class ChangeStreamerHttpClient {
+    #lc;
+    #uri;
+    constructor(lc, uriOrPort = DEFAULT_PORT) {
+        this.#lc = lc;
+        this.#uri =
+            typeof uriOrPort === 'string'
+                ? uriOrPort
+                : `ws://localhost:${uriOrPort}` +
+                    CHANGES_URL_PATTERN.replace(':version', 'v0');
+    }
+    subscribe(ctx) {
+        const params = getParams(ctx);
+        const ws = new WebSocket(this.#uri + `?${params.toString()}`);
+        return streamIn(this.#lc, ws, downstreamSchema);
+    }
+}
+// TODO: Define this more precisely.
+const downstreamSchema = v.array(jsonValueSchema);
+function getSubscriberContext(req) {
+    const url = new URL(req.url, req.headers.origin ?? 'http://localhost');
+    const params = new URLParams(url);
+    return {
+        id: params.get('id', true),
+        replicaVersion: params.get('replicaVersion', true),
+        watermark: params.get('watermark', true),
+        initial: params.getBoolean('initial'),
+    };
+}
+function getParams(ctx) {
+    return new URLSearchParams({
+        ...ctx,
+        initial: ctx.initial ? 'true' : 'false',
+    });
+}
+//# sourceMappingURL=change-streamer-http.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"change-streamer-http.js","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/change-streamer-http.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,39 @@
+import { LogContext } from '@rocicorp/logger';
+import type { PostgresDB } from '../../../../zero-cache/src/types/pg.js';
+import type { Sink, Source } from '../../../../zero-cache/src/types/streams.js';
+import { type ChangeStreamerService, type Commit, type DownstreamChange } from './change-streamer.js';
+import { type ReplicationConfig } from './schema/tables.js';
+/**
+ * Performs initialization and schema migrations to initialize a ChangeStreamerImpl.
+ */
+export declare function initializeStreamer(lc: LogContext, changeDB: PostgresDB, changeSource: ChangeSource, replicationConfig: ReplicationConfig): Promise<ChangeStreamerService>;
+/**
+ * Internally all Downstream messages (not just commits) are given a watermark.
+ * These are used for internal ordering for:
+ * 1. Replaying new changes in the Storer
+ * 2. Filtering old changes in the Subscriber
+ *
+ * However, only the watermark for `Commit` messages are exposed to
+ * subscribers, as that is the only semantically correct watermark to
+ * use for tracking a position in a replication stream.
+ */
+export type WatermarkedChange = [watermark: string, DownstreamChange];
+export type ChangeStream = {
+    /** The watermark at which the ChangeStream begins (i.e. inclusive). */
+    initialWatermark: string;
+    changes: Source<DownstreamChange>;
+    /**
+     * A Sink to push the {@link Commit} messages that have been successfully
+     * stored by the {@link Storer}.
+     */
+    acks: Sink<Commit>;
+};
+/** Encapsulates an upstream-specific implementation of a stream of Changes. */
+export interface ChangeSource {
+    /**
+     * Starts a stream of changes starting after the specific watermark,
+     * with a corresponding sink for upstream acknowledgements.
+     */
+    startStream(afterWatermark: string): Promise<ChangeStream>;
+}
+//# sourceMappingURL=change-streamer-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"change-streamer-service.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/change-streamer-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAC,IAAI,EAAE,MAAM,EAAC,MAAM,iCAAiC,CAAC;AAGlE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,MAAM,EAEX,KAAK,gBAAgB,EAGtB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAI5B;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,UAAU,EACd,QAAQ,EAAE,UAAU,EACpB,YAAY,EAAE,YAAY,EAC1B,iBAAiB,EAAE,iBAAiB,GACnC,OAAO,CAAC,qBAAqB,CAAC,CAOhC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAEtE,MAAM,MAAM,YAAY,GAAG;IACzB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;IAEzB,OAAO,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAElC;;;OAGG;IACH,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;CACpB,CAAC;AAEF,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5D"}

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

@@ -0,0 +1,212 @@
+import { LogContext } from '@rocicorp/logger';
+import { oneAfter } from '../../../../zero-cache/src/types/lexi-version.js';
+import { Subscription } from '../../../../zero-cache/src/types/subscription.js';
+import { RunningState } from '../running-state.js';
+import { ErrorType, } from './change-streamer.js';
+import { Forwarder } from './forwarder.js';
+import { initChangeStreamerSchema } from './schema/init.js';
+import { ensureReplicationConfig, } from './schema/tables.js';
+import { Storer } from './storer.js';
+import { Subscriber } from './subscriber.js';
+/**
+ * Performs initialization and schema migrations to initialize a ChangeStreamerImpl.
+ */
+export async function initializeStreamer(lc, changeDB, changeSource, replicationConfig) {
+    // Make sure the ChangeLog DB is set up.
+    await initChangeStreamerSchema(lc, changeDB);
+    await ensureReplicationConfig(lc, changeDB, replicationConfig);
+    const { replicaVersion } = replicationConfig;
+    return new ChangeStreamerImpl(lc, changeDB, replicaVersion, changeSource);
+}
+/**
+ * Upstream-agnostic dispatch of messages in a {@link ChangeStream} to a
+ * {@link Forwarder} and {@link Storer} to execute the forward-store-ack
+ * procedure described in {@link ChangeStreamer}.
+ *
+ * ### Subscriber Catchup
+ *
+ * Connecting clients first need to be "caught up" to the current watermark
+ * (from stored change log entries) before new entries are forwarded to
+ * them. This is non-trivial because the replication stream may be in the
+ * middle of a pending streamed Transaction for which some entries have
+ * already been forwarded but are not yet committed to the store.
+ *
+ *
+ * ```
+ * ------------------------------- - - - - - - - - - - - - - - - - - - -
+ * | Historic changes in storage |  Pending (streamed) tx  |   Next tx
+ * ------------------------------- - - - - - - - - - - - - - - - - - - -
+ *                                           Replication stream
+ *                                           >  >  >  >  >  >  >  >  >
+ *           ^  ---> required catchup --->   ^
+ * Subscriber watermark               Subscription begins
+ * ```
+ *
+ * Preemptively buffering the changes of every pending transaction
+ * would be wasteful and consume too much memory for large transactions.
+ *
+ * Instead, the streamer synchronously dispatches changes and subscriptions
+ * to the {@link Forwarder} and the {@link Storer} such that the two
+ * components are aligned as to where in the stream the subscription started.
+ * The two components then coordinate catchup and handoff via the
+ * {@link Subscriber} object with the following algorithm:
+ *
+ * * If the streamer is in the middle of a pending Transaction, the
+ *   Subscriber is "queued" on both the Forwarder and the Storer. In this
+ *   state, new changes are *not* forwarded to the Subscriber, and catchup
+ *   is not yet executed.
+ * * Once the commit message for the pending Transaction is processed
+ *   by the Storer, it begins catchup on the Subscriber (with a READONLY
+ *   snapshot so that it does not block subsequent storage operations).
+ *   This catchup is thus guaranteed to load the change log entries of
+ *   that last Transaction.
+ * * When the Forwarder processes that same commit message, it moves the
+ *   Subscriber from the "queued" to the "active" set of clients such that
+ *   the Subscriber begins receiving new changes, starting from the next
+ *   Transaction.
+ * * The Subscriber does not forward those changes, however, if its catchup
+ *   is not complete. Until then, it buffers the changes in memory.
+ * * Once catchup is complete, the buffered changes are immediately sent
+ *   and the Subscriber henceforth forwards changes as they are received.
+ *
+ * In the (common) case where the streamer is not in the middle of a pending
+ * transaction when a subscription begins, the Storer begins catchup
+ * immediately and the Forwarder directly adds the Subscriber to its active
+ * set. However, the Subscriber still buffers any forwarded messages until
+ * its catchup is complete.
+ *
+ * ### Watermarks and ordering
+ *
+ * The ChangeStreamerService depends on its {@link ChangeSource} to send
+ * changes in contiguous [`begin`, `data` ..., `data`, `commit`] sequences
+ * in commit order. This follows Postgres's Logical Replication Protocol
+ * Message Flow:
+ *
+ * https://www.postgresql.org/docs/16/protocol-logical-replication.html#PROTOCOL-LOGICAL-MESSAGES-FLOW
+ *
+ * > The logical replication protocol sends individual transactions one by one.
+ * > This means that all messages between a pair of Begin and Commit messages belong to the same transaction.
+ *
+ * In order to correctly replay (new) and filter (old) messages to subscribers
+ * at different points in the replication stream, these changes must be assigned
+ * watermarks such that they preserve the order in which they were received
+ * from the ChangeSource.
+ *
+ * A previous implementation incorrectly derived these watermarks from the Postgres
+ * Log Sequence Numbers (LSN) of each message. However, LSNs from concurrent,
+ * non-conflicting transactions can overlap, which can result in a `begin` message
+ * with an earlier LSN arriving after a `commit` message. For example, the
+ * changes for these transactions:
+ *
+ * ```
+ * LSN:   1     2     3  4    5   6   7     8   9      10
+ * tx1: begin  data     data     data     commit
+ * tx2:             begin    data    data      data  commit
+ * ```
+ *
+ * will arrive as:
+ *
+ * ```
+ * begin1, data2, data4, data6, commit8, begin3, data5, data7, data9, commit10
+ * ```
+ *
+ * Thus, LSN of non-commit messages are not suitable for tracking the sorting
+ * order of the replication stream.
+ *
+ * Instead, the ChangeStreamer uses the following algorithm for deterministic
+ * catchup and filtering of changes:
+ *
+ * * A `commit` message is assigned to a watermark corresponding to its LSN.
+ *   These are guaranteed to be in commit order by definition.
+ *
+ * * `begin` and `data` messages are assigned to the watermark of the
+ *   preceding `commit` (the previous transaction, or the replication
+ *   slot's starting LSN) plus 1. This guarantees that they will be sorted
+ *   after the previously commit transaction even if their LSNs came before it.
+ *   This is referred to as the `preCommitWatermark`.
+ *
+ * * In the ChangeLog DB, messages have a secondary sort column `pos`, which is
+ *   the position of the message within its transaction, with the `begin` message
+ *   starting at `0`. This guarantees that `begin` and `data` messages will be
+ *   fetched in the original ChangeSource order during catchup.
+ *
+ * `begin` and `data` messages share the same watermark, but this is sufficient for
+ * Subscriber filtering because subscribers only know about the `commit` watermarks
+ * exposed in the `Downstream` `Commit` message. The Subscriber object thus compares
+ * the internal watermarks of the incoming messages against the commit watermark of
+ * the caller, updating the watermark at every `Commit` message that is forwarded.
+ */
+class ChangeStreamerImpl {
+    id;
+    #lc;
+    #replicaVersion;
+    #source;
+    #storer;
+    #forwarder;
+    #state = new RunningState('ChangeStreamer');
+    #stream;
+    constructor(lc, changeDB, replicaVersion, source) {
+        this.id = `change-streamer`;
+        this.#lc = lc.withContext('component', 'change-streamer');
+        this.#replicaVersion = replicaVersion;
+        this.#source = source;
+        this.#storer = new Storer(lc, changeDB, commit => this.#stream?.acks.push(commit));
+        this.#forwarder = new Forwarder();
+    }
+    async run() {
+        this.#storer.run().catch(e => this.stop(e));
+        while (this.#state.shouldRun()) {
+            let err;
+            try {
+                const startAfter = await this.#storer.getLastStoredWatermark();
+                const stream = await this.#source.startStream(startAfter ?? this.#replicaVersion);
+                this.#stream = stream;
+                let preCommitWatermark = stream.initialWatermark;
+                for await (const change of stream.changes) {
+                    this.#state.resetBackoff();
+                    let watermark;
+                    if (change[0] !== 'commit') {
+                        watermark = preCommitWatermark;
+                    }
+                    else {
+                        watermark = change[2].watermark;
+                        preCommitWatermark = oneAfter(watermark); // For the next transaction.
+                    }
+                    this.#storer.store([watermark, change]);
+                    this.#forwarder.forward([watermark, change]);
+                }
+            }
+            catch (e) {
+                err = e;
+            }
+            finally {
+                this.#stream?.changes.cancel();
+                this.#stream = undefined;
+            }
+            await this.#state.backoff(this.#lc, err);
+        }
+        this.#lc.info?.('ChangeStreamer stopped');
+    }
+    subscribe(ctx) {
+        const { id, watermark } = ctx;
+        const downstream = Subscription.create({
+            cleanup: () => this.#forwarder.remove(subscriber),
+        });
+        const subscriber = new Subscriber(id, watermark, downstream);
+        if (ctx.replicaVersion !== this.#replicaVersion) {
+            subscriber.close(ErrorType.WrongReplicaVersion);
+        }
+        else {
+            this.#lc.debug?.(`adding subscriber ${subscriber.id}`);
+            this.#forwarder.add(subscriber);
+            this.#storer.catchup(subscriber);
+        }
+        return downstream;
+    }
+    async stop(err) {
+        this.#state.stop(this.#lc, err);
+        this.#stream?.changes.cancel();
+        await this.#storer.stop();
+    }
+}
+//# sourceMappingURL=change-streamer-service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"change-streamer-service.js","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/change-streamer-service.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,110 @@
+import type { Source } from '../../../../zero-cache/src/types/streams.js';
+import type { Service } from '../service.js';
+import type { Change, DataChange, MessageBegin, MessageCommit } from './schema/change.js';
+/**
+ * The ChangeStreamer is the component between replicators ("subscribers")
+ * and a canonical upstream source of changes (e.g. a Postgres logical
+ * replication slot). It facilitates multiple subscribers without incurring
+ * the associated upstream expense (e.g. PG replication slots are resource
+ * intensive) with a "forward-store-ack" procedure.
+ *
+ * * Changes from the upstream source are immediately **forwarded** to
+ *   connected subscribers to minimize latency.
+ *
+ * * They are then **stored** in a separate DB to facilitate catchup
+ *   of connecting subscribers that are behind.
+ *
+ * * **Acknowledgements** are sent upstream after they are successfully
+ *   stored.
+ *
+ * **Cleanup** (Not yet implemented)
+ *
+ * Unlike Postgres replication slots, in which the progress of a static
+ * subscriber is tracked in the replication slot, the ChangeStreamer
+ * supports a dynamic set of subscribers (i.e.. zero-caches) that can
+ * can continually change.
+ *
+ * However, it is not the case that the ChangeStreamer needs to support
+ * arbitrarily old subscribers. Because the replica is continually
+ * backed up to a global location and used to initialize new subscriber
+ * tasks, an initial subscription request from a subscriber constitutes
+ * a signal for how "behind" a new subscriber task can be. This is
+ * reflected in the {@link SubscriberContext}, which indicates whether
+ * the watermark corresponds to an "initial" watermark derived from the
+ * replica at task startup.
+ *
+ * The ChangeStreamer uses a combination of this signal with ACK
+ * responses from connected subscribers to determine the watermark up
+ * to which it is safe to purge old change log entries.
+ */
+export interface ChangeStreamer {
+    /**
+     * Subscribes to changes based on the supplied subscriber `ctx`,
+     * which indicates the watermark at which the subscriber is up to
+     * date.
+     */
+    subscribe(ctx: SubscriberContext): Source<Downstream>;
+}
+export type SubscriberContext = {
+    /**
+     * Subscriber id. This is only used for debugging.
+     */
+    id: string;
+    /**
+     * The ChangeStreamer will return an Error if the subscriber is
+     * on a different replica version (i.e. the initial snapshot associated
+     * with the replication slot).
+     */
+    replicaVersion: string;
+    /**
+     * The watermark up to which the subscriber is up to date.
+     * Only changes after the watermark will be streamed.
+     */
+    watermark: string;
+    /**
+     * Whether this is the first subscription request made by the task,
+     * i.e. indicating that the watermark comes from a restored replica
+     * backup. The ChangeStreamer uses this to determine which changes
+     * are safe to purge from the Storer.
+     */
+    initial: boolean;
+};
+export type ChangeEntry = {
+    change: Change;
+    /**
+     * Note that it is technically possible for multiple changes to have
+     * the same watermark, but that of a commit is guaranteed to be final,
+     * so subscribers should only store the watermark of commit changes.
+     */
+    watermark: string;
+};
+export declare const enum ErrorType {
+    Unknown = 0,
+    WrongReplicaVersion = 1,
+    WatermarkTooOld = 2
+}
+export type SubscriptionError = {
+    type: ErrorType;
+    message?: string | undefined;
+};
+export type Begin = ['begin', MessageBegin];
+export type Data = ['data', DataChange];
+export type Commit = ['commit', MessageCommit, {
+    watermark: string;
+}];
+export type Error = ['error', SubscriptionError];
+export type DownstreamChange = Begin | Data | Commit;
+/**
+ * A stream of transactions, each starting with a {@link MessageBegin},
+ * containing one or more {@link DataChange}s, and ending with a
+ * {@link MessageCommit}. The 'commit' tuple includes a `watermark` that
+ * should be stored with the committed data and used for resuming
+ * a subscription (e.g. in the {@link SubscriberContext}).
+ *
+ * A {@link SubscriptionError} indicates an unrecoverable error that requires
+ * manual intervention (e.g. configuration / operational error).
+ */
+export type Downstream = DownstreamChange | Error;
+export interface ChangeStreamerService extends ChangeStreamer, Service {
+}
+//# sourceMappingURL=change-streamer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"change-streamer.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/change-streamer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,iCAAiC,CAAC;AAC5D,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,YAAY,EACZ,aAAa,EACd,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IAEH,SAAS,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;CACvD;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,0BAAkB,SAAS;IACzB,OAAO,IAAA;IACP,mBAAmB,IAAA;IACnB,eAAe,IAAA;CAChB;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAC5C,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACxC,MAAM,MAAM,MAAM,GAAG,CAAC,QAAQ,EAAE,aAAa,EAAE;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC;AACpE,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,KAAK,CAAC;AAElD,MAAM,WAAW,qBAAsB,SAAQ,cAAc,EAAE,OAAO;CAAG"}