@rocicorp/zero 1.11.0-canary.4 → 1.11.0-canary.40

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

@@ -0,0 +1,485 @@
+/**
+ * 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>;
+/**
+ * The state of the replica on the subscriber's disk, if any. This allows the
+ * replication-manager to distinguish a subscriber that is replacing its
+ * replica (i.e. one that was serving, see `RestoreAdmission`) from one that
+ * is restoring onto an empty disk.
+ */
+export declare const localReplicaSchema: v.ObjectType<{
+    replicaVersion: v.Type<string>;
+    watermark: v.Type<string>;
+}, undefined>;
+export type LocalReplica = v.Infer<typeof localReplicaSchema>;
+export declare const reserveSnapshotMessageSchema: v.TupleType<[v.Type<"reserve-snapshot">, v.ObjectType<{
+    taskID: v.Type<string>;
+    localReplica: v.Optional<{
+        replicaVersion: string;
+        watermark: 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;
+        }>;
+    }[]>;
+    /** See `SubscriberContext.drainable`. */
+    drainable: v.Optional<boolean>;
+    /** See `SubscriberContext.switchover`. */
+    switchover: v.Optional<boolean>;
+}, 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;
+        }>;
+    }[]>;
+    /** See `SubscriberContext.drainable`. */
+    drainable: v.Optional<boolean>;
+    /** See `SubscriberContext.switchover`. */
+    switchover: v.Optional<boolean>;
+}, undefined>]>;
+export declare const subscribeUpstreamSchema: v.UnionType<[v.TupleType<[v.Type<"reserve-snapshot">, v.ObjectType<{
+    taskID: v.Type<string>;
+    localReplica: v.Optional<{
+        replicaVersion: string;
+        watermark: 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;
+        }>;
+    }[]>;
+    /** See `SubscriberContext.drainable`. */
+    drainable: v.Optional<boolean>;
+    /** See `SubscriberContext.switchover`. */
+    switchover: v.Optional<boolean>;
+}, 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;
+    }>;
+    draining: v.Optional<boolean>;
+    restore: v.Optional<{
+        state: "queued";
+        position: number;
+    } | {
+        state: "granted";
+    }>;
+}, 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.UnionType<[v.Type<null>, v.Type<Record<string, import("../../../../shared/src/bigint-json.ts").JSONValue>>]>;
+    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>;
+    replicaVersion: 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;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;aAG7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,4BAA4B;;;;;;eAMvC,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB;IACjC,2EAA2E;;IAE3E,sCAAsC;;IAEtC,8DAA8D;;IAE9D,gEAAgE;;IAEhE,8DAA8D;;IAE9D;;;;OAIG;;;;;;;;;;;;;;;;;;;IAEH,yCAAyC;;IAEzC,0CAA0C;;aAE1C,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,8BAA8B;IAxBzC,2EAA2E;;IAE3E,sCAAsC;;IAEtC,8DAA8D;;IAE9D,gEAAgE;;IAEhE,8DAA8D;;IAE9D;;;;OAIG;;;;;;;;;;;;;;;;;;;IAEH,yCAAyC;;IAEzC,0CAA0C;;eAS1C,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;IA7BlC,2EAA2E;;IAE3E,sCAAsC;;IAEtC,8DAA8D;;IAE9D,gEAAgE;;IAEhE,8DAA8D;;IAE9D;;;;OAIG;;;;;;;;;;;;;;;;;;;IAEH,yCAAyC;;IAEzC,0CAA0C;;iBAc3C,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,93 @@
+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") });
+/**
+* The state of the replica on the subscriber's disk, if any. This allows the
+* replication-manager to distinguish a subscriber that is replacing its
+* replica (i.e. one that was serving, see `RestoreAdmission`) from one that
+* is restoring onto an empty disk.
+*/
+var localReplicaSchema = valita_exports.object({
+	replicaVersion: valita_exports.string(),
+	watermark: valita_exports.string()
+});
+var reserveSnapshotMessageSchema = valita_exports.tuple([valita_exports.literal("reserve-snapshot"), valita_exports.object({
+	taskID: valita_exports.string(),
+	localReplica: localReplicaSchema.optional()
+})]);
+/**
+* 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(),
+	/** See `SubscriberContext.drainable`. */
+	drainable: valita_exports.boolean().optional(),
+	/** See `SubscriberContext.switchover`. */
+	switchover: valita_exports.boolean().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\n/**\n * The state of the replica on the subscriber's disk, if any. This allows the\n * replication-manager to distinguish a subscriber that is replacing its\n * replica (i.e. one that was serving, see `RestoreAdmission`) from one that\n * is restoring onto an empty disk.\n */\nexport const localReplicaSchema = v.object({\n  replicaVersion: v.string(),\n  watermark: v.string(),\n});\n\nexport type LocalReplica = v.Infer<typeof localReplicaSchema>;\n\nexport const reserveSnapshotMessageSchema = v.tuple([\n  v.literal('reserve-snapshot'),\n  v.object({\n    taskID: v.string(),\n    localReplica: localReplicaSchema.optional(),\n  }),\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  /** See `SubscriberContext.drainable`. */\n  drainable: v.boolean().optional(),\n  /** See `SubscriberContext.switchover`. */\n  switchover: v.boolean().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;;;;;;;AAcD,IAAa,qBAAqB,eAAE,OAAO;CACzC,gBAAgB,eAAE,OAAO;CACzB,WAAW,eAAE,OAAO;AACtB,CAAC;AAID,IAAa,+BAA+B,eAAE,MAAM,CAClD,eAAE,QAAQ,kBAAkB,GAC5B,eAAE,OAAO;CACP,QAAQ,eAAE,OAAO;CACjB,cAAc,mBAAmB,SAAS;AAC5C,CAAC,CACH,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;;CAEnD,WAAW,eAAE,QAAQ,EAAE,SAAS;;CAEhC,YAAY,eAAE,QAAQ,EAAE,SAAS;AACnC,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"}