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

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

@@ -0,0 +1,446 @@
+/**
+ * The `subscribe` API (protocol v7+) merges the previous `/snapshot` and
+ * `/changes` connections into a single bidirectional WebSocket, so that the
+ * replication-manager that reserves change-log entries for a soon-to-be
+ * subscriber is the same replication-manager that serves the subscription.
+ *
+ * The connection is driven by an upstream (view-syncer → replication-manager)
+ * application message that selects the flow:
+ *
+ * - **Fresh startup:** the view-syncer sends `['reserve-snapshot', {taskID}]`.
+ *   The change-streamer opens a snapshot reservation (pinning the change log)
+ *   and replies downstream with a single `['reserved', …]` message telling the
+ *   view-syncer where to restore the backup from and the watermark from which
+ *   catchup is possible. Once the backup is restored, the view-syncer sends
+ *   `['start-subscription', ctx]`, which transitions the same connection into
+ *   the subscription phase (change stream downstream). The reservation is
+ *   released only after the subscriber is registered, so there is never a gap
+ *   in which the change-streamer does not know the client's watermark.
+ *
+ * - **Reconnect (replica already valid):** the view-syncer sends
+ *   `['start-subscription', ctx]` immediately, with no reservation.
+ *
+ * The reservation status uses a distinct `'reserved'` tag (rather than the
+ * change stream's `'status'`) so the downstream union is unambiguous under
+ * passthrough parsing.
+ */
+import * as v from '../../../../shared/src/valita.ts';
+declare const snapshotStatusSchema: v.ObjectType<Omit<{
+    tag: v.Type<"status">;
+    backupURL: v.Type<string>;
+    replicaVersion: v.Type<string>;
+    minWatermark: v.Type<string>;
+    replicaSize: v.Optional<number>;
+}, "tag"> & {
+    tag: v.Type<"snapshot">;
+}, undefined>;
+export type SnapshotStatus = v.Infer<typeof snapshotStatusSchema>;
+export declare const reserveSnapshotMessageSchema: v.TupleType<[v.Type<"reserve-snapshot">, v.ObjectType<{
+    taskID: v.Type<string>;
+}, undefined>]>;
+/**
+ * The subscription-initialization context, sent in the `start-subscription`
+ * message. Equivalent to the previous URL-encoded `SubscriberContext`, minus
+ * the fields that are now implicit on the merged connection:
+ * - `protocolVersion` comes from the request path.
+ * - `wsBatched` is always on (the transport batches internally).
+ *
+ * Parsed in `passthrough` mode so a forthcoming, orthogonal change can add
+ * arbitrary table/column/backfill state without a protocol bump.
+ */
+export declare const subscribeContextSchema: v.ObjectType<{
+    /** Task ID, links the subscription to a preceding snapshot reservation. */
+    taskID: v.Type<string>;
+    /** Subscriber id (debugging only). */
+    id: v.Type<string>;
+    /** 'serving' (user-facing) or 'backup' (in-RM replicator). */
+    mode: v.UnionType<[v.Type<"serving">, v.Type<"backup">]>;
+    /** The replica version the subscriber restored / is running. */
+    replicaVersion: v.Type<string>;
+    /** The watermark up to which the subscriber is up to date. */
+    watermark: v.Type<string>;
+    /**
+     * The subscriber's pending backfills (and their progress) as of its
+     * `watermark`. This should be considered non-optional as of protocol v8;
+     * it is only absent from v7 subscribers.
+     */
+    backfills: v.Optional<{
+        table: {
+            schema: string;
+            name: string;
+            metadata: {
+                [x: string]: import("../../../../shared/src/bigint-json.ts").JSONValue;
+                rowKey: Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>;
+            } | null;
+        };
+        columns: Record<string, {
+            id: Record<string, import("../change-source/protocol/current.ts").JSONValue | undefined>;
+            progress?: {
+                [x: string]: string | number;
+                progressMark: string;
+                timeline?: string | undefined;
+            } | undefined;
+        }>;
+    }[]>;
+}, undefined>;
+export type SubscribeContext = v.Infer<typeof subscribeContextSchema>;
+export declare const startSubscriptionMessageSchema: v.TupleType<[v.Type<"start-subscription">, v.ObjectType<{
+    /** Task ID, links the subscription to a preceding snapshot reservation. */
+    taskID: v.Type<string>;
+    /** Subscriber id (debugging only). */
+    id: v.Type<string>;
+    /** 'serving' (user-facing) or 'backup' (in-RM replicator). */
+    mode: v.UnionType<[v.Type<"serving">, v.Type<"backup">]>;
+    /** The replica version the subscriber restored / is running. */
+    replicaVersion: v.Type<string>;
+    /** The watermark up to which the subscriber is up to date. */
+    watermark: v.Type<string>;
+    /**
+     * The subscriber's pending backfills (and their progress) as of its
+     * `watermark`. This should be considered non-optional as of protocol v8;
+     * it is only absent from v7 subscribers.
+     */
+    backfills: v.Optional<{
+        table: {
+            schema: string;
+            name: string;
+            metadata: {
+                [x: string]: import("../../../../shared/src/bigint-json.ts").JSONValue;
+                rowKey: Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>;
+            } | null;
+        };
+        columns: Record<string, {
+            id: Record<string, import("../change-source/protocol/current.ts").JSONValue | undefined>;
+            progress?: {
+                [x: string]: string | number;
+                progressMark: string;
+                timeline?: string | undefined;
+            } | undefined;
+        }>;
+    }[]>;
+}, undefined>]>;
+export declare const subscribeUpstreamSchema: v.UnionType<[v.TupleType<[v.Type<"reserve-snapshot">, v.ObjectType<{
+    taskID: v.Type<string>;
+}, undefined>]>, v.TupleType<[v.Type<"start-subscription">, v.ObjectType<{
+    /** Task ID, links the subscription to a preceding snapshot reservation. */
+    taskID: v.Type<string>;
+    /** Subscriber id (debugging only). */
+    id: v.Type<string>;
+    /** 'serving' (user-facing) or 'backup' (in-RM replicator). */
+    mode: v.UnionType<[v.Type<"serving">, v.Type<"backup">]>;
+    /** The replica version the subscriber restored / is running. */
+    replicaVersion: v.Type<string>;
+    /** The watermark up to which the subscriber is up to date. */
+    watermark: v.Type<string>;
+    /**
+     * The subscriber's pending backfills (and their progress) as of its
+     * `watermark`. This should be considered non-optional as of protocol v8;
+     * it is only absent from v7 subscribers.
+     */
+    backfills: v.Optional<{
+        table: {
+            schema: string;
+            name: string;
+            metadata: {
+                [x: string]: import("../../../../shared/src/bigint-json.ts").JSONValue;
+                rowKey: Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>;
+            } | null;
+        };
+        columns: Record<string, {
+            id: Record<string, import("../change-source/protocol/current.ts").JSONValue | undefined>;
+            progress?: {
+                [x: string]: string | number;
+                progressMark: string;
+                timeline?: string | undefined;
+            } | undefined;
+        }>;
+    }[]>;
+}, undefined>]>]>;
+export type SubscribeUpstream = v.Infer<typeof subscribeUpstreamSchema>;
+/**
+ * The reservation confirmation. Carries the same payload as the legacy
+ * `/snapshot` status (`backupURL`, `replicaVersion`, `minWatermark`,
+ * `replicaSize?`) but under a distinct `'reserved'` tag so it does not collide
+ * with the change stream's `['status', …]` message.
+ */
+export declare const reservedMessageSchema: v.TupleType<[v.Type<"reserved">, v.ObjectType<Omit<{
+    tag: v.Type<"status">;
+    backupURL: v.Type<string>;
+    replicaVersion: v.Type<string>;
+    minWatermark: v.Type<string>;
+    replicaSize: v.Optional<number>;
+}, "tag"> & {
+    tag: v.Type<"snapshot">;
+}, undefined>]>;
+export type ReservedMessage = v.Infer<typeof reservedMessageSchema>;
+export declare const subscribeDownstreamSchema: v.UnionType<[v.TupleType<[v.Type<"reserved">, v.ObjectType<Omit<{
+    tag: v.Type<"status">;
+    backupURL: v.Type<string>;
+    replicaVersion: v.Type<string>;
+    minWatermark: v.Type<string>;
+    replicaSize: v.Optional<number>;
+}, "tag"> & {
+    tag: v.Type<"snapshot">;
+}, undefined>]>, v.UnionType<[v.TupleType<[v.Type<"status">, v.ObjectType<{
+    tag: v.Type<"status">;
+    lagReport: v.Optional<{
+        lastTimings?: {
+            sendTimeMs: number;
+            commitTimeMs: number;
+            receiveTimeMs: number;
+        } | undefined;
+        nextSendTimeMs: number;
+    }>;
+}, undefined>]>, v.UnionType<[v.TupleType<[v.Type<"begin">, v.ObjectType<{
+    tag: v.Type<"begin">;
+    json: v.Optional<"p" | "s">;
+    skipAck: v.Optional<boolean>;
+}, undefined>, v.ObjectType<{
+    commitWatermark: v.Type<string>;
+}, undefined>]>, v.TupleType<[v.Type<"data">, v.UnionType<[v.UnionType<[v.ObjectType<{
+    tag: v.Type<"insert">;
+    relation: v.Type<{
+        schema: string;
+        name: string;
+        keyColumns?: string[] | undefined;
+        replicaIdentity?: "default" | "full" | "index" | "nothing" | undefined;
+        rowKey: {
+            columns: string[];
+            type?: "default" | "full" | "index" | "nothing" | undefined;
+        };
+    }>;
+    new: v.Type<Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"update">;
+    relation: v.Type<{
+        schema: string;
+        name: string;
+        keyColumns?: string[] | undefined;
+        replicaIdentity?: "default" | "full" | "index" | "nothing" | undefined;
+        rowKey: {
+            columns: string[];
+            type?: "default" | "full" | "index" | "nothing" | undefined;
+        };
+    }>;
+    key: v.Type<Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue> | null>;
+    new: v.Type<Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"delete">;
+    relation: v.Type<{
+        schema: string;
+        name: string;
+        keyColumns?: string[] | undefined;
+        replicaIdentity?: "default" | "full" | "index" | "nothing" | undefined;
+        rowKey: {
+            columns: string[];
+            type?: "default" | "full" | "index" | "nothing" | undefined;
+        };
+    }>;
+    key: v.Type<Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"truncate">;
+    relations: v.ArrayType<v.Type<{
+        schema: string;
+        name: string;
+        keyColumns?: string[] | undefined;
+        replicaIdentity?: "default" | "full" | "index" | "nothing" | undefined;
+        rowKey: {
+            columns: string[];
+            type?: "default" | "full" | "index" | "nothing" | undefined;
+        };
+    }>>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"backfill">;
+    relation: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+        rowKey: v.ObjectType<{
+            columns: v.ArrayType<v.Type<string>>;
+            type: v.Optional<"default" | "full" | "index" | "nothing">;
+        }, undefined>;
+    }, undefined>;
+    columns: v.ArrayType<v.Type<string>>;
+    watermark: v.Type<string>;
+    rowValues: v.ArrayType<v.ArrayType<v.Type<import("../../../../shared/src/bigint-json.ts").JSONValue>>>;
+    progressMarks: v.Optional<{
+        previous?: {
+            [x: string]: string | number;
+            progressMark: string;
+            timeline?: string | undefined;
+        } | undefined;
+        current: {
+            [x: string]: string | number;
+            progressMark: string;
+            timeline?: string | undefined;
+        };
+    }>;
+    status: v.Optional<{
+        rows: number;
+        totalRows: number;
+        totalBytes?: number | undefined;
+    }>;
+}, undefined>]>, v.UnionType<[v.ObjectType<{
+    tag: v.Type<"create-table">;
+    spec: v.ObjectType<Omit<{
+        name: v.Type<string>;
+        columns: v.Type<Record<string, {
+            pos: number;
+            dataType: string;
+            pgTypeClass?: "b" | "c" | "d" | "e" | "m" | "p" | "r" | undefined;
+            elemPgTypeClass?: "b" | "c" | "d" | "e" | "m" | "p" | "r" | null | undefined;
+            characterMaximumLength?: number | null | undefined;
+            notNull?: boolean | null | undefined;
+            dflt?: string | null | undefined;
+        }>>;
+        primaryKey: v.Optional<string[]>;
+    }, "schema"> & {
+        schema: v.Type<string>;
+    }, undefined>;
+    metadata: v.Optional<{
+        [x: string]: import("../../../../shared/src/bigint-json.ts").JSONValue;
+        rowKey: Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>;
+    }>;
+    backfill: v.Optional<Record<string, Record<string, import("../change-source/protocol/current.ts").JSONValue | undefined>>>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"rename-table">;
+    old: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+    }, undefined>;
+    new: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+    }, undefined>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"update-table-metadata">;
+    table: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+    }, undefined>;
+    old: v.ObjectType<{
+        rowKey: v.Type<Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>>;
+    }, v.Type<import("../../../../shared/src/bigint-json.ts").JSONValue>>;
+    new: v.ObjectType<{
+        rowKey: v.Type<Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>>;
+    }, v.Type<import("../../../../shared/src/bigint-json.ts").JSONValue>>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"add-column">;
+    table: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+    }, undefined>;
+    column: v.ObjectType<{
+        name: v.Type<string>;
+        spec: v.ObjectType<{
+            pos: v.Type<number>;
+            dataType: v.Type<string>;
+            pgTypeClass: v.Optional<"b" | "c" | "d" | "e" | "m" | "p" | "r">;
+            elemPgTypeClass: v.Optional<"b" | "c" | "d" | "e" | "m" | "p" | "r" | null>;
+            characterMaximumLength: v.Optional<number | null>;
+            notNull: v.Optional<boolean | null>;
+            dflt: v.Optional<string | null>;
+        }, undefined>;
+    }, undefined>;
+    tableMetadata: v.Optional<{
+        [x: string]: import("../../../../shared/src/bigint-json.ts").JSONValue;
+        rowKey: Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>;
+    }>;
+    backfill: v.Optional<Record<string, import("../change-source/protocol/current.ts").JSONValue | undefined>>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"update-column">;
+    table: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+    }, undefined>;
+    old: v.ObjectType<{
+        name: v.Type<string>;
+        spec: v.ObjectType<{
+            pos: v.Type<number>;
+            dataType: v.Type<string>;
+            pgTypeClass: v.Optional<"b" | "c" | "d" | "e" | "m" | "p" | "r">;
+            elemPgTypeClass: v.Optional<"b" | "c" | "d" | "e" | "m" | "p" | "r" | null>;
+            characterMaximumLength: v.Optional<number | null>;
+            notNull: v.Optional<boolean | null>;
+            dflt: v.Optional<string | null>;
+        }, undefined>;
+    }, undefined>;
+    new: v.ObjectType<{
+        name: v.Type<string>;
+        spec: v.ObjectType<{
+            pos: v.Type<number>;
+            dataType: v.Type<string>;
+            pgTypeClass: v.Optional<"b" | "c" | "d" | "e" | "m" | "p" | "r">;
+            elemPgTypeClass: v.Optional<"b" | "c" | "d" | "e" | "m" | "p" | "r" | null>;
+            characterMaximumLength: v.Optional<number | null>;
+            notNull: v.Optional<boolean | null>;
+            dflt: v.Optional<string | null>;
+        }, undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"drop-column">;
+    table: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+    }, undefined>;
+    column: v.Type<string>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"drop-table">;
+    id: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+    }, undefined>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"create-index">;
+    spec: v.ObjectType<Omit<{
+        name: v.Type<string>;
+        tableName: v.Type<string>;
+        unique: v.Type<boolean>;
+        columns: v.Type<Record<string, "ASC" | "DESC">>;
+        predicate: v.Optional<import("../../db/specs.ts").IndexPredicate>;
+    }, "schema"> & {
+        schema: v.Type<string>;
+    }, undefined>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"drop-index">;
+    id: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+    }, undefined>;
+}, undefined>, v.ObjectType<{
+    tag: v.Type<"backfill-completed">;
+    relation: v.ObjectType<{
+        schema: v.Type<string>;
+        name: v.Type<string>;
+        rowKey: v.ObjectType<{
+            columns: v.ArrayType<v.Type<string>>;
+            type: v.Optional<"default" | "full" | "index" | "nothing">;
+        }, undefined>;
+    }, undefined>;
+    columns: v.ArrayType<v.Type<string>>;
+    watermark: v.Type<string>;
+    progressMarks: v.Optional<{
+        previous?: {
+            [x: string]: string | number;
+            progressMark: string;
+            timeline?: string | undefined;
+        } | undefined;
+    }>;
+    status: v.Optional<{
+        rows: number;
+        totalRows: number;
+        totalBytes?: number | undefined;
+    }>;
+}, undefined>]>]>]>, v.TupleType<[v.Type<"commit">, v.ObjectType<{
+    tag: v.Type<"commit">;
+    commitTimeMs: v.Optional<number>;
+}, undefined>, v.ObjectType<{
+    watermark: v.Type<string>;
+}, undefined>]>, v.TupleType<[v.Type<"rollback">, v.ObjectType<{
+    tag: v.Type<"rollback">;
+}, undefined>]>]>, v.TupleType<[v.Type<"error">, v.ObjectType<{
+    type: v.Type<number>;
+    message: v.Optional<string>;
+}, undefined>]>]>]>;
+export type SubscribeDownstream = v.Infer<typeof subscribeDownstreamSchema>;
+export {};
+//# sourceMappingURL=subscribe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/subscribe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,CAAC,MAAM,kCAAkC,CAAC;AAKtD,QAAA,MAAM,oBAAoB;;;;;;;;aAExB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,eAAO,MAAM,4BAA4B;;eAGvC,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB;IACjC,2EAA2E;;IAE3E,sCAAsC;;IAEtC,8DAA8D;;IAE9D,gEAAgE;;IAEhE,8DAA8D;;IAE9D;;;;OAIG;;;;;;;;;;;;;;;;;;;aAEH,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,8BAA8B;IApBzC,2EAA2E;;IAE3E,sCAAsC;;IAEtC,8DAA8D;;IAE9D,gEAAgE;;IAEhE,8DAA8D;;IAE9D;;;;OAIG;;;;;;;;;;;;;;;;;;;eASH,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;IAzBlC,2EAA2E;;IAE3E,sCAAsC;;IAEtC,8DAA8D;;IAE9D,gEAAgE;;IAEhE,8DAA8D;;IAE9D;;;;OAIG;;;;;;;;;;;;;;;;;;;iBAcJ,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;eAGhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAGrC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

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

@@ -0,0 +1,76 @@
+import { valita_exports } from "../../../../shared/src/valita.js";
+import { backfillRequestSchema } from "../change-source/protocol/current/upstream.js";
+import "../change-source/protocol/current.js";
+import { downstreamSchema } from "./change-streamer.js";
+import { statusSchema } from "./snapshot-message.js";
+//#region ../zero-cache/src/services/change-streamer/subscribe.ts
+/**
+* The `subscribe` API (protocol v7+) merges the previous `/snapshot` and
+* `/changes` connections into a single bidirectional WebSocket, so that the
+* replication-manager that reserves change-log entries for a soon-to-be
+* subscriber is the same replication-manager that serves the subscription.
+*
+* The connection is driven by an upstream (view-syncer → replication-manager)
+* application message that selects the flow:
+*
+* - **Fresh startup:** the view-syncer sends `['reserve-snapshot', {taskID}]`.
+*   The change-streamer opens a snapshot reservation (pinning the change log)
+*   and replies downstream with a single `['reserved', …]` message telling the
+*   view-syncer where to restore the backup from and the watermark from which
+*   catchup is possible. Once the backup is restored, the view-syncer sends
+*   `['start-subscription', ctx]`, which transitions the same connection into
+*   the subscription phase (change stream downstream). The reservation is
+*   released only after the subscriber is registered, so there is never a gap
+*   in which the change-streamer does not know the client's watermark.
+*
+* - **Reconnect (replica already valid):** the view-syncer sends
+*   `['start-subscription', ctx]` immediately, with no reservation.
+*
+* The reservation status uses a distinct `'reserved'` tag (rather than the
+* change stream's `'status'`) so the downstream union is unambiguous under
+* passthrough parsing.
+*/
+var snapshotStatusSchema = statusSchema.extend({ tag: valita_exports.literal("snapshot") });
+var reserveSnapshotMessageSchema = valita_exports.tuple([valita_exports.literal("reserve-snapshot"), valita_exports.object({ taskID: valita_exports.string() })]);
+/**
+* The subscription-initialization context, sent in the `start-subscription`
+* message. Equivalent to the previous URL-encoded `SubscriberContext`, minus
+* the fields that are now implicit on the merged connection:
+* - `protocolVersion` comes from the request path.
+* - `wsBatched` is always on (the transport batches internally).
+*
+* Parsed in `passthrough` mode so a forthcoming, orthogonal change can add
+* arbitrary table/column/backfill state without a protocol bump.
+*/
+var subscribeContextSchema = valita_exports.object({
+	/** Task ID, links the subscription to a preceding snapshot reservation. */
+	taskID: valita_exports.string(),
+	/** Subscriber id (debugging only). */
+	id: valita_exports.string(),
+	/** 'serving' (user-facing) or 'backup' (in-RM replicator). */
+	mode: valita_exports.union(valita_exports.literal("serving"), valita_exports.literal("backup")),
+	/** The replica version the subscriber restored / is running. */
+	replicaVersion: valita_exports.string(),
+	/** The watermark up to which the subscriber is up to date. */
+	watermark: valita_exports.string(),
+	/**
+	* The subscriber's pending backfills (and their progress) as of its
+	* `watermark`. This should be considered non-optional as of protocol v8;
+	* it is only absent from v7 subscribers.
+	*/
+	backfills: valita_exports.array(backfillRequestSchema).optional()
+});
+var startSubscriptionMessageSchema = valita_exports.tuple([valita_exports.literal("start-subscription"), subscribeContextSchema]);
+var subscribeUpstreamSchema = valita_exports.union(reserveSnapshotMessageSchema, startSubscriptionMessageSchema);
+/**
+* The reservation confirmation. Carries the same payload as the legacy
+* `/snapshot` status (`backupURL`, `replicaVersion`, `minWatermark`,
+* `replicaSize?`) but under a distinct `'reserved'` tag so it does not collide
+* with the change stream's `['status', …]` message.
+*/
+var reservedMessageSchema = valita_exports.tuple([valita_exports.literal("reserved"), snapshotStatusSchema]);
+var subscribeDownstreamSchema = valita_exports.union(reservedMessageSchema, downstreamSchema);
+//#endregion
+export { subscribeDownstreamSchema, subscribeUpstreamSchema };
+
+//# sourceMappingURL=subscribe.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe.js","names":[],"sources":["../../../../../../zero-cache/src/services/change-streamer/subscribe.ts"],"sourcesContent":["/**\n * The `subscribe` API (protocol v7+) merges the previous `/snapshot` and\n * `/changes` connections into a single bidirectional WebSocket, so that the\n * replication-manager that reserves change-log entries for a soon-to-be\n * subscriber is the same replication-manager that serves the subscription.\n *\n * The connection is driven by an upstream (view-syncer → replication-manager)\n * application message that selects the flow:\n *\n * - **Fresh startup:** the view-syncer sends `['reserve-snapshot', {taskID}]`.\n *   The change-streamer opens a snapshot reservation (pinning the change log)\n *   and replies downstream with a single `['reserved', …]` message telling the\n *   view-syncer where to restore the backup from and the watermark from which\n *   catchup is possible. Once the backup is restored, the view-syncer sends\n *   `['start-subscription', ctx]`, which transitions the same connection into\n *   the subscription phase (change stream downstream). The reservation is\n *   released only after the subscriber is registered, so there is never a gap\n *   in which the change-streamer does not know the client's watermark.\n *\n * - **Reconnect (replica already valid):** the view-syncer sends\n *   `['start-subscription', ctx]` immediately, with no reservation.\n *\n * The reservation status uses a distinct `'reserved'` tag (rather than the\n * change stream's `'status'`) so the downstream union is unambiguous under\n * passthrough parsing.\n */\n\nimport * as v from '../../../../shared/src/valita.ts';\nimport {backfillRequestSchema} from '../change-source/protocol/current.ts';\nimport {downstreamSchema} from './change-streamer.ts';\nimport {statusSchema} from './snapshot-message.ts';\n\nconst snapshotStatusSchema = statusSchema.extend({\n  tag: v.literal('snapshot'), // Replace tag: 'status' with tag: 'snapshot'\n});\n\nexport type SnapshotStatus = v.Infer<typeof snapshotStatusSchema>;\n\n// ---------------------------------------------------------------------------\n// Upstream (view-syncer → replication-manager) — application control messages.\n// ---------------------------------------------------------------------------\n\nexport const reserveSnapshotMessageSchema = v.tuple([\n  v.literal('reserve-snapshot'),\n  v.object({taskID: v.string()}),\n]);\n\n/**\n * The subscription-initialization context, sent in the `start-subscription`\n * message. Equivalent to the previous URL-encoded `SubscriberContext`, minus\n * the fields that are now implicit on the merged connection:\n * - `protocolVersion` comes from the request path.\n * - `wsBatched` is always on (the transport batches internally).\n *\n * Parsed in `passthrough` mode so a forthcoming, orthogonal change can add\n * arbitrary table/column/backfill state without a protocol bump.\n */\nexport const subscribeContextSchema = v.object({\n  /** Task ID, links the subscription to a preceding snapshot reservation. */\n  taskID: v.string(),\n  /** Subscriber id (debugging only). */\n  id: v.string(),\n  /** 'serving' (user-facing) or 'backup' (in-RM replicator). */\n  mode: v.union(v.literal('serving'), v.literal('backup')),\n  /** The replica version the subscriber restored / is running. */\n  replicaVersion: v.string(),\n  /** The watermark up to which the subscriber is up to date. */\n  watermark: v.string(),\n  /**\n   * The subscriber's pending backfills (and their progress) as of its\n   * `watermark`. This should be considered non-optional as of protocol v8;\n   * it is only absent from v7 subscribers.\n   */\n  backfills: v.array(backfillRequestSchema).optional(),\n});\n\nexport type SubscribeContext = v.Infer<typeof subscribeContextSchema>;\n\nexport const startSubscriptionMessageSchema = v.tuple([\n  v.literal('start-subscription'),\n  subscribeContextSchema,\n]);\n\nexport const subscribeUpstreamSchema = v.union(\n  reserveSnapshotMessageSchema,\n  startSubscriptionMessageSchema,\n);\n\nexport type SubscribeUpstream = v.Infer<typeof subscribeUpstreamSchema>;\n\n// ---------------------------------------------------------------------------\n// Downstream (replication-manager → view-syncer).\n// ---------------------------------------------------------------------------\n\n/**\n * The reservation confirmation. Carries the same payload as the legacy\n * `/snapshot` status (`backupURL`, `replicaVersion`, `minWatermark`,\n * `replicaSize?`) but under a distinct `'reserved'` tag so it does not collide\n * with the change stream's `['status', …]` message.\n */\nexport const reservedMessageSchema = v.tuple([\n  v.literal('reserved'),\n  snapshotStatusSchema,\n]);\n\nexport type ReservedMessage = v.Infer<typeof reservedMessageSchema>;\n\nexport const subscribeDownstreamSchema = v.union(\n  reservedMessageSchema,\n  downstreamSchema,\n);\n\nexport type SubscribeDownstream = v.Infer<typeof subscribeDownstreamSchema>;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAM,uBAAuB,aAAa,OAAO,EAC/C,KAAK,eAAE,QAAQ,UAAU,EAC3B,CAAC;AAQD,IAAa,+BAA+B,eAAE,MAAM,CAClD,eAAE,QAAQ,kBAAkB,GAC5B,eAAE,OAAO,EAAC,QAAQ,eAAE,OAAO,EAAC,CAAC,CAC/B,CAAC;;;;;;;;;;;AAYD,IAAa,yBAAyB,eAAE,OAAO;;CAE7C,QAAQ,eAAE,OAAO;;CAEjB,IAAI,eAAE,OAAO;;CAEb,MAAM,eAAE,MAAM,eAAE,QAAQ,SAAS,GAAG,eAAE,QAAQ,QAAQ,CAAC;;CAEvD,gBAAgB,eAAE,OAAO;;CAEzB,WAAW,eAAE,OAAO;;;;;;CAMpB,WAAW,eAAE,MAAM,qBAAqB,EAAE,SAAS;AACrD,CAAC;AAID,IAAa,iCAAiC,eAAE,MAAM,CACpD,eAAE,QAAQ,oBAAoB,GAC9B,sBACF,CAAC;AAED,IAAa,0BAA0B,eAAE,MACvC,8BACA,8BACF;;;;;;;AAcA,IAAa,wBAAwB,eAAE,MAAM,CAC3C,eAAE,QAAQ,UAAU,GACpB,oBACF,CAAC;AAID,IAAa,4BAA4B,eAAE,MACzC,uBACA,gBACF"}

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

@@ -1,18 +1,39 @@
 import type { Enum } from '../../../../shared/src/enum.ts';
 import type { Subscription } from '../../types/subscription.ts';
 import type { ReplicatorMode } from '../replicator/replicator.ts';
+import type { BackfillState } from './backfill-state.ts';
+import type { PreSerializedBatch } from './broadcast.ts';
 import type { ChangeTag, Status, WatermarkedChange } from './change-streamer.ts';
 import type * as ErrorType from './error-type-enum.ts';
 type ErrorType = Enum<typeof ErrorType>;
 export type SubscriberOptions = {
     backlogHighWaterBytes?: number | undefined;
     backlogLowWaterRatio?: number | undefined;
+    wsBatched?: boolean | undefined;
     /**
      * Called whenever the subscriber's acked watermark advances, i.e. when it
      * has confirmed that a commit was durably applied to its replica. The ACK
      * therefore lags the subscriber's replica rather than leading it.
      */
     onAck?: ((watermark: string) => void) | undefined;
+    /**
+     * The subscriber's pending backfills (protocol v8+), which are tracked
+     * over the changes sent to the subscriber.
+     */
+    backfills?: BackfillState | undefined;
+    /**
+     * Called once the subscriber has been sent all changes up to the head of
+     * the stream, i.e. its catchup and backlog have been flushed. From this
+     * point on, the subscriber's tracked {@link backfills} reflect the same
+     * position in the stream as that of the change-streamer.
+     */
+    onAligned?: ((subscriber: Subscriber) => void) | undefined;
+    /**
+     * Called when a `backfill` or `backfill-completed` message is ignored for
+     * some of the subscriber's pending backfill columns, after the subscriber
+     * is aligned.
+     */
+    onBackfillIgnored?: ((columns: string[]) => void) | undefined;
 };
 export type BacklogFullWait = {
     readonly promise: Promise<void>;
@@ -37,7 +58,17 @@ export declare class Subscriber {
     #private;
     readonly id: string;
     readonly mode: ReplicatorMode;
-    constructor(protocolVersion: number, id: string, mode: ReplicatorMode, watermark: string, downstream: Subscription<string>, latestStatus: () => Status, options?: SubscriberOptions);
+    constructor(protocolVersion: number, id: string, mode: ReplicatorMode, watermark: string, downstream: Subscription<string | PreSerializedBatch>, latestStatus: () => Status, options?: SubscriberOptions);
+    /**
+     * The subscriber's tracked pending backfills, or `undefined` if the
+     * subscriber does not report them (i.e. protocol < v8).
+     */
+    get backfills(): BackfillState | undefined;
+    /**
+     * Whether the subscriber has been sent all changes up to the head of the
+     * stream (see {@link SubscriberOptions.onAligned}).
+     */
+    get aligned(): boolean;
     get watermark(): string;
     get acked(): string;
     /**
@@ -60,6 +91,7 @@ export declare class Subscriber {
      */
     whenBacklogFull(): BacklogFullWait;
     send(change: WatermarkedChange): Promise<void>;
+    sendBatch(changes: readonly WatermarkedChange[], preSerialized?: PreSerializedBatch | undefined): Promise<void>;
     sendStatus(status: Status): void;
     /** catchup() is called on ChangeEntries loaded from the store. */
     catchup(change: WatermarkedChange): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"subscriber.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/subscriber.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,gCAAgC,CAAC;AAKzD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EACV,SAAS,EAET,MAAM,EACN,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAEvD,KAAK,SAAS,GAAG,IAAI,CAAC,OAAO,SAAS,CAAC,CAAC;AAKxC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qBAAqB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1C;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,IAAI,IAAI,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,UAAU;;IAErB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAgB9B,YACE,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,EAChC,YAAY,EAAE,MAAM,MAAM,EAC1B,OAAO,GAAE,iBAAsB,EAehC;IAED,IAAI,SAAS,WAEZ;IAED,IAAI,KAAK,WAER;IAED;;;;;OAKG;IACH,IAAI,WAAW,YAId;IAED;;;OAGG;IACH,YAAY,YAEX;IAED;;;;;OAKG;IACH,eAAe,IAAI,eAAe,CAYjC;IAED,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa7C;IAeD,UAAU,CAAC,MAAM,EAAE,MAAM,QAIxB;IAED,kEAAkE;IAC5D,OAAO,CAAC,MAAM,EAAE,iBAAiB,iBAGtC;IAED;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAc3B;IA2DD;;OAEG;IACH,IAAI,UAAU,WAEb;IAED;;;OAGG;IACH,IAAI,YAAY,WAEf;IAED;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,SAAK,GAAG,IAAI,CAMpD;IAED,QAAQ,IAAI,eAAe,CAyB1B;IAKD,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,QAKlD;IAED;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,aAAa,UAW9D;IAED,eAAe,CAAC,GAAG,EAAE,SAAS,WAO7B;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,QAElB;IAED,KAAK,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,QAkBxC;CA0FF"}
+{"version":3,"file":"subscriber.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/change-streamer/subscriber.ts"],"names":[],"mappings":"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"}