@tier0/sdk-v2 0.9.9 → 0.10.0

package/dist/esm/data/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvD,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC","sourcesContent":["/**\n * `@tier0/sdk-v2/data` — server-only App data layer over Tier0 UNS collections.\n *\n *   import { createDataClient, defineCollection } from '@tier0/sdk-v2/data';\n *\n *   const data = createDataClient({ collections: [workOrders] });\n *   const open = await data.collection(workOrders).find({ status: 'OPEN' }, { limit: 50 }).toArray();\n *\n * Declarations are ensured in one batch on first access. Requires `zod` 4.\n * Client code imports declarations and types from `@tier0/sdk-v2/data/define`.\n */\nexport { createDataClient } from './client.js';\nexport { MAX_BATCH_QUERIES } from './client.js';\nexport type { BatchQueries, BatchResults, DataClient, DataClientConfig, SettledBatchResults, TransactAction, TransactResult, TransactResultItem, TransactStep } from './client.js';\nexport type { DataEnvironment, EnsureConflict, EnsureNote, EnsureResult, EnsureState, EnsureWarning, Logger } from './bootstrap.js';\nexport { MAX_ATOMIC_ITEMS, MAX_GET_IDS } from './collection.js';\nexport type { BatchQuery, BulkOperation, CappedCount, Collection, CollectionQueries, Cursor, DeepPartial, FoundPage, ValueCount, FindOneAndOptions, FindOptions, FindPageOptions, InsertOneOptions, Projection, Update, UpdateOptions, WithMeta } from './collection.js';\nexport { currentDataSubject, runAsApp, runWithRequestContext } from './context.js';\nexport { redactRestricted, SUBSCRIBE_IDLE_TIMEOUT_MS } from './subscribe.js';\nexport type { ChangeEvent, CollectionChange, RecordChange, SubscribeOptions, SubscriptionEvent } from './subscribe.js';\nexport { ACCESS_REASONS, DataError } from './error.js';\nexport * from './declarations.js';\nexport { toSortPairs } from './sort.js';\nexport type { Filter, Sort, SortDirection, SortPairs } from './sort.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvD,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC","sourcesContent":["/**\n * `@tier0/sdk-v2/data` — server-only App data layer over Tier0 UNS collections.\n *\n *   import { createDataClient, defineCollection } from '@tier0/sdk-v2/data';\n *\n *   const data = createDataClient({ collections: [workOrders] });\n *   const open = await data.collection(workOrders).find({ status: 'OPEN' }, { limit: 50 }).toArray();\n *\n * Declarations are ensured in one batch on first access. Requires `zod` 4.\n * Client code imports declarations and types from `@tier0/sdk-v2/data/define`.\n */\nexport { createDataClient } from './client.js';\nexport { MAX_BATCH_QUERIES } from './client.js';\nexport type { BatchQueries, BatchResults, DataClient, DataClientConfig, SettledBatchResults, TransactAction, TransactResult, TransactResultItem, TransactStep } from './client.js';\nexport type { DataEnvironment, EnsureConflict, EnsureNote, EnsureResult, EnsureState, EnsureWarning, Logger } from './bootstrap.js';\nexport { MAX_ATOMIC_ITEMS, MAX_GET_IDS } from './collection.js';\nexport type { BatchQuery, BulkOperation, CappedCount, Collection, CollectionQueries, Cursor, DeepPartial, FoundPage, ValueCount, FindOneAndOptions, FindOptions, FindPageOptions, InsertOneOptions, Projection, Update, UpdateOptions, WithMeta } from './collection.js';\nexport { runDetached, runWithAbortSignal } from './context.js';\nexport { SUBSCRIBE_IDLE_TIMEOUT_MS } from './subscribe.js';\nexport type { RecordChange, SubscribeOptions, SubscriptionEvent } from './subscribe.js';\nexport { createChangeRelay } from './relay.js';\nexport type { ChangeRelay, ChangeRelayOptions, ChangeRelaySource, ChangeRelayStatus, ChangeRelayStreamOptions, RelayedChange } from './relay.js';\nexport { ACCESS_REASONS, DataError } from './error.js';\nexport * from './declarations.js';\nexport { toSortPairs } from './sort.js';\nexport type { Filter, Sort, SortDirection, SortPairs } from './sort.js';\n"]}

package/dist/esm/data/relay.d.ts

@@ -0,0 +1,51 @@
+import type { RecordChange, SubscribeObserver, SubscribeOptions, SubscriptionEvent } from './subscribe.js';
+/** `idle`: no upstream; `connecting`: opening it; `ready`: it streams; `unavailable`: it cannot connect and keeps retrying. */
+export type ChangeRelayStatus = 'idle' | 'connecting' | 'ready' | 'unavailable';
+export interface ChangeRelayOptions {
+    /** Collections of the upstream; every declared collection by default. */
+    collections?: SubscribeOptions['collections'];
+    /** Changes kept for replay to reconnecting browsers. Default 1000. */
+    bufferSize?: number;
+    /** Close the upstream this long after the last browser left. Default 30 s. */
+    idleCloseMs?: number;
+    /** Wait before reopening a failed upstream; doubles per consecutive failure. Default 5 s. */
+    restartIntervalMs?: number;
+    /** Default 5 minutes. */
+    maxRestartIntervalMs?: number;
+    /** Default 15 s. */
+    heartbeatMs?: number;
+    /** A browser stream ends after this long (±10 %). Default 10 minutes. */
+    maxStreamMs?: number;
+    /** Status changes; `error` is the failure behind `unavailable`. */
+    onStatus?: (status: ChangeRelayStatus, error?: unknown) => void;
+    logger?: Pick<Console, 'warn'>;
+}
+export interface ChangeRelayStreamOptions {
+    /** Whether this browser gets the change; every change when absent. */
+    filter?: (change: RecordChange) => boolean;
+    /** The browser's `Last-Event-ID` header. */
+    lastEventId?: string | null;
+    /** Ends the stream, e.g. `request.signal`. */
+    signal?: AbortSignal;
+}
+/** The `data` of a `change` frame. `eventId` is the relay's position, not a UNS cursor. */
+export interface RelayedChange {
+    eventId: string;
+    collection: string;
+    change: 'record' | 'delete';
+    recordId: string;
+    revision: number;
+    occurredAt: number;
+}
+export interface ChangeRelay {
+    /** An SSE response for one browser. */
+    stream(options?: ChangeRelayStreamOptions): Response;
+    /** Open browser streams. */
+    readonly size: number;
+    readonly status: ChangeRelayStatus;
+}
+/** The upstream as the relay uses it: `data.subscribe` with its internal observer. */
+export interface ChangeRelaySource {
+    subscribe(options: SubscribeOptions, observer?: SubscribeObserver): AsyncIterable<SubscriptionEvent>;
+}
+export declare function createChangeRelay(data: ChangeRelaySource, options?: ChangeRelayOptions): ChangeRelay;

package/dist/esm/data/relay.js

@@ -0,0 +1,368 @@
+/**
+ * `createChangeRelay`: one `data.subscribe` per server process, fanned out to
+ * browsers as server-sent events on a route of the App.
+ *
+ *   const relay = createChangeRelay(data);
+ *   // GET /api/changes, after the App authenticated the visitor:
+ *   return relay.stream({
+ *     filter: (change) => canSee(visitor, change),
+ *     lastEventId: request.headers.get('Last-Event-ID'),
+ *     signal: request.signal,
+ *   });
+ *
+ * The upstream runs as the App and sees every change of the collections
+ * granted to it; `filter` decides, per browser, what that visitor may know
+ * about. It is called synchronously for every change, live or replayed, and
+ * a filter that throws drops the change. Events carry identities only
+ * (collection, record ID, revision, kind of change), never record data: the
+ * browser reads what it shows through the App's own API, which applies the
+ * App's rules.
+ *
+ * Browsers never open their own upstream: the Gateway limits open
+ * subscriptions per workspace, not per visitor.
+ *
+ * Positions: browsers never see UNS cursors. The relay numbers the changes it
+ * forwards `<epoch>.<seq>`; that is the SSE `id`. A browser gets a position
+ * (an id-only frame, repeated as its heartbeat) only once the upstream can
+ * deliver every change after it:
+ *
+ * - Cold start: until the upstream's first connection streams, browsers get
+ *   no position. Then each of them gets `reset` (`upstream-started`) with a
+ *   position, so a page that read its data before the upstream existed
+ *   reads it again.
+ * - The relay keeps the last UNS position. When the upstream fails, or closes
+ *   `idleCloseMs` after the last browser left, it reopens from that position
+ *   in the same epoch: nothing is missed and connected browsers get no reset.
+ * - Only a `reset` from the upstream (`CURSOR_EXPIRED`, `SCOPE_CHANGED`,
+ *   `COLLECTION_RECREATED`) starts a new epoch. Connected browsers then get
+ *   that `reset`, with a new position, once the upstream streams again.
+ *
+ * A reconnect's `Last-Event-ID` is looked up in the latest `bufferSize`
+ * changes of the current epoch: found, the changes after it are replayed;
+ * anything else (another epoch, too old, forged) answers that browser with
+ * `reset` (`unknown-event-id`). `reset` means the same as from
+ * `data.subscribe`: changes may have been missed, reload what is shown.
+ *
+ * When the upstream cannot connect (e.g. 429 over the subscription limit,
+ * `APP_NOT_READY`, or a failure that ends `data.subscribe`), the relay goes to
+ * status `unavailable`: `onStatus` hears it, `logger.warn` logs it once, and
+ * every browser stream gets `event: unavailable` with `{reason}`. The upstream
+ * keeps retrying; when it streams again the status is `ready`, and browsers
+ * that were waiting for a position get it as described above. A failure that
+ * ends `data.subscribe` reopens after `restartIntervalMs`, doubling per
+ * consecutive failure up to `maxRestartIntervalMs`.
+ *
+ * Every browser stream ends after `maxStreamMs` (±10 %), so the browser
+ * reconnects and the App's route authenticates it again. Reconnect timing is
+ * the browser client's: `openEventStream` (`@tier0/sdk-v2/event-stream`)
+ * handles platform errors, the App's sleep and hidden pages itself, so the
+ * relay sends no `retry:` field.
+ *
+ * Frames: `event: change` with `{eventId, collection, change, recordId,
+ * revision, occurredAt}` (`RelayedChange`), `event: reset` with `{reason}`,
+ * `event: unavailable` with `{reason}`, and every `heartbeatMs` an id-only
+ * frame with the current position (a `: heartbeat` comment while the browser
+ * has none), so an idle browser's resume point stays inside the buffer.
+ */
+import { randomUUID } from 'node:crypto';
+const DEFAULTS = {
+    bufferSize: 1000,
+    idleCloseMs: 30_000,
+    restartIntervalMs: 5_000,
+    maxRestartIntervalMs: 300_000,
+    heartbeatMs: 15_000,
+    maxStreamMs: 600_000,
+};
+function changeFrame(change, eventId) {
+    const { collection, change: kind, recordId, revision, occurredAt } = change;
+    const data = { eventId, collection, change: kind, recordId, revision, occurredAt };
+    return `event: change\nid: ${eventId}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+/** A reset that also moves the browser to `position`, so its next reconnect resumes there. */
+function resetFrame(reason, position) {
+    return `event: reset\nid: ${position}\ndata: ${JSON.stringify({ reason })}\n\n`;
+}
+function unavailableFrame(reason) {
+    return `event: unavailable\ndata: ${JSON.stringify({ reason })}\n\n`;
+}
+function reasonOf(error) {
+    const value = error;
+    return typeof value?.code === 'string' ? value.code : 'upstream-failed';
+}
+function newSession() {
+    return { epoch: randomUUID().slice(0, 8), seq: 0, buffer: [] };
+}
+export function createChangeRelay(data, options = {}) {
+    const { collections, onStatus, logger = console } = options;
+    const { bufferSize, idleCloseMs, restartIntervalMs, maxRestartIntervalMs, heartbeatMs, maxStreamMs } = { ...DEFAULTS, ...options };
+    const subscribers = new Set();
+    let session = newSession();
+    /** The last UNS position: the upstream reopens from it. */
+    let cursor;
+    /** The current upstream connection streams. */
+    let live = false;
+    let status = 'idle';
+    let unavailableReason = 'upstream-failed';
+    let upstream = null;
+    let startTimer;
+    let idleTimer;
+    let failures = 0;
+    const position = () => `${session.epoch}.${session.seq}`;
+    /** Every change after the current position will reach the browsers. */
+    const positionable = () => cursor !== undefined || live;
+    function setStatus(next, error) {
+        if (next === status)
+            return;
+        status = next;
+        if (next === 'unavailable') {
+            unavailableReason = reasonOf(error);
+            logger.warn(`[change-relay] upstream unavailable (${unavailableReason}); retrying:`, error instanceof Error ? error.message : error);
+            for (const subscriber of subscribers)
+                subscriber.send(unavailableFrame(unavailableReason));
+        }
+        try {
+            onStatus?.(next, error);
+        }
+        catch {
+            // A status listener cannot stop the relay.
+        }
+    }
+    /** Gives waiting browsers their reset and position, once the upstream can deliver what follows. */
+    function positionWaiting() {
+        if (!positionable())
+            return;
+        for (const subscriber of subscribers) {
+            if (subscriber.positioned)
+                continue;
+            subscriber.positioned = true;
+            subscriber.send(resetFrame(subscriber.resetReason, position()));
+        }
+    }
+    function forward(change) {
+        session.seq += 1;
+        session.buffer.push({ seq: session.seq, change });
+        if (session.buffer.length > bufferSize)
+            session.buffer.splice(0, session.buffer.length - bufferSize);
+        const chunk = changeFrame(change, position());
+        for (const subscriber of subscribers)
+            if (subscriber.positioned && subscriber.matches(change))
+                subscriber.send(chunk);
+    }
+    /** The upstream reset: a new epoch, and every browser reloads once the upstream streams again. */
+    function restartEpoch(reason) {
+        session = newSession();
+        cursor = undefined;
+        live = false;
+        for (const subscriber of subscribers) {
+            subscriber.positioned = false;
+            subscriber.resetReason = reason;
+        }
+    }
+    async function run(controller) {
+        const observer = {
+            connected() {
+                if (controller.signal.aborted)
+                    return;
+                live = true;
+                failures = 0;
+                setStatus('ready');
+                positionWaiting();
+            },
+            position(eventId) {
+                if (!controller.signal.aborted)
+                    cursor = eventId;
+            },
+            retrying(error) {
+                if (controller.signal.aborted)
+                    return;
+                live = false;
+                setStatus('unavailable', error);
+            },
+        };
+        live = false;
+        setStatus('connecting');
+        try {
+            const subscription = data.subscribe({
+                ...(collections ? { collections } : {}),
+                ...(cursor === undefined ? {} : { lastEventId: cursor }),
+                signal: controller.signal,
+            }, observer);
+            for await (const event of subscription) {
+                if (controller.signal.aborted)
+                    break;
+                if (event.type === 'reset')
+                    restartEpoch(event.reason);
+                else
+                    forward(event);
+            }
+        }
+        catch (error) {
+            if (!controller.signal.aborted) {
+                failures += 1;
+                live = false;
+                setStatus('unavailable', error);
+            }
+        }
+        finally {
+            if (upstream === controller)
+                upstream = null;
+            live = false;
+            // Reopens from the last UNS position: same epoch, nothing missed.
+            if (!controller.signal.aborted)
+                schedule();
+        }
+    }
+    function start() {
+        startTimer = undefined;
+        if (upstream || subscribers.size === 0)
+            return;
+        const controller = new AbortController();
+        upstream = controller;
+        // The upstream outlives the request that started it; data.subscribe never takes a request's signal.
+        void run(controller);
+    }
+    function schedule() {
+        if (upstream || startTimer !== undefined || subscribers.size === 0)
+            return;
+        const delay = failures === 0 ? 0 : Math.min(maxRestartIntervalMs, restartIntervalMs * 2 ** (failures - 1));
+        startTimer = setTimeout(start, delay);
+        startTimer.unref?.();
+    }
+    function join(subscriber) {
+        if (idleTimer !== undefined) {
+            clearTimeout(idleTimer);
+            idleTimer = undefined;
+        }
+        subscribers.add(subscriber);
+        schedule();
+    }
+    function release(subscriber) {
+        if (!subscribers.delete(subscriber) || subscribers.size > 0)
+            return;
+        if (startTimer !== undefined) {
+            clearTimeout(startTimer);
+            startTimer = undefined;
+        }
+        idleTimer = setTimeout(() => {
+            idleTimer = undefined;
+            // The epoch, buffer and UNS position stay: the next browser resumes in the same epoch.
+            upstream?.abort();
+            upstream = null;
+            live = false;
+            setStatus('idle');
+        }, idleCloseMs);
+        idleTimer.unref?.();
+    }
+    /** Replays after `lastEventId`; false when it is not a position of the current epoch's buffer. */
+    function catchUp(subscriber, lastEventId) {
+        if (!lastEventId)
+            return false;
+        const [epoch, seqText] = lastEventId.split('.');
+        const seq = Number(seqText);
+        const oldest = session.buffer[0]?.seq ?? session.seq + 1;
+        if (epoch !== session.epoch || !Number.isInteger(seq) || seq > session.seq || seq < oldest - 1)
+            return false;
+        for (const entry of session.buffer) {
+            if (entry.seq > seq && subscriber.matches(entry.change))
+                subscriber.send(changeFrame(entry.change, `${session.epoch}.${entry.seq}`));
+        }
+        return true;
+    }
+    return {
+        get size() {
+            return subscribers.size;
+        },
+        get status() {
+            return status;
+        },
+        stream({ filter, lastEventId, signal } = {}) {
+            const matches = (change) => {
+                if (!filter)
+                    return true;
+                try {
+                    return filter(change) === true;
+                }
+                catch (error) {
+                    logger.warn('[change-relay] filter failed; change dropped:', error instanceof Error ? error.message : error);
+                    return false;
+                }
+            };
+            const encoder = new TextEncoder();
+            let subscriber;
+            let heartbeat;
+            let expiry;
+            let close = () => undefined;
+            const body = new ReadableStream({
+                start(controller) {
+                    let closed = false;
+                    close = () => {
+                        if (closed)
+                            return;
+                        closed = true;
+                        clearInterval(heartbeat);
+                        clearTimeout(expiry);
+                        signal?.removeEventListener('abort', close);
+                        if (subscriber)
+                            release(subscriber);
+                        try {
+                            controller.close();
+                        }
+                        catch {
+                            // Already closed by the consumer.
+                        }
+                    };
+                    const send = (chunk) => {
+                        if (closed)
+                            return;
+                        try {
+                            controller.enqueue(encoder.encode(chunk));
+                        }
+                        catch {
+                            close();
+                        }
+                    };
+                    if (signal?.aborted) {
+                        closed = true;
+                        controller.close();
+                        return;
+                    }
+                    const current = { matches, send, positioned: false, resetReason: 'upstream-started' };
+                    subscriber = current;
+                    if (positionable()) {
+                        current.positioned = true;
+                        // A known position replays what followed; anything else reloads.
+                        if (catchUp(current, lastEventId ?? undefined))
+                            send(`id: ${position()}\n\n`);
+                        else if (lastEventId)
+                            send(resetFrame('unknown-event-id', position()));
+                        // A first connect: an id-only frame dispatches nothing and gives the browser its resume point.
+                        else
+                            send(`id: ${position()}\n\n`);
+                    }
+                    else if (lastEventId) {
+                        current.resetReason = 'unknown-event-id';
+                    }
+                    if (status === 'unavailable')
+                        send(unavailableFrame(unavailableReason));
+                    join(current);
+                    heartbeat = setInterval(() => send(current.positioned ? `id: ${position()}\n\n` : ': heartbeat\n\n'), heartbeatMs);
+                    heartbeat.unref?.();
+                    expiry = setTimeout(close, maxStreamMs * (0.9 + Math.random() * 0.2));
+                    expiry.unref?.();
+                    signal?.addEventListener('abort', close, { once: true });
+                },
+                cancel() {
+                    close();
+                },
+            });
+            return new Response(body, {
+                headers: {
+                    'Content-Type': 'text/event-stream; charset=utf-8',
+                    'Cache-Control': 'no-cache, no-transform',
+                    'X-Accel-Buffering': 'no',
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=relay.js.map

package/dist/esm/data/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../../src/data/relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2DzC,MAAM,QAAQ,GAAG;IACf,UAAU,EAAE,IAAI;IAChB,WAAW,EAAE,MAAM;IACnB,iBAAiB,EAAE,KAAK;IACxB,oBAAoB,EAAE,OAAO;IAC7B,WAAW,EAAE,MAAM;IACnB,WAAW,EAAE,OAAO;CACrB,CAAC;AAkBF,SAAS,WAAW,CAAC,MAAoB,EAAE,OAAe;IACxD,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IAC5E,MAAM,IAAI,GAAkB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IAClG,OAAO,sBAAsB,OAAO,WAAW,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;AAC5E,CAAC;AAED,8FAA8F;AAC9F,SAAS,UAAU,CAAC,MAAc,EAAE,QAAgB;IAClD,OAAO,qBAAqB,QAAQ,WAAW,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC;AAClF,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAc;IACtC,OAAO,6BAA6B,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC;AACvE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,MAAM,KAAK,GAAG,KAAuC,CAAC;IACtD,OAAO,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC;AAC1E,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAuB,EAAE,UAA8B,EAAE;IACzF,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5D,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC;IACnI,MAAM,WAAW,GAAG,IAAI,GAAG,EAAc,CAAC;IAC1C,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,IAAI,MAA0B,CAAC;IAC/B,+CAA+C;IAC/C,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,MAAM,GAAsB,MAAM,CAAC;IACvC,IAAI,iBAAiB,GAAG,iBAAiB,CAAC;IAC1C,IAAI,QAAQ,GAA2B,IAAI,CAAC;IAC5C,IAAI,UAAqD,CAAC;IAC1D,IAAI,SAAoD,CAAC;IACzD,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzD,uEAAuE;IACvE,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC;IAExD,SAAS,SAAS,CAAC,IAAuB,EAAE,KAAe;QACzD,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO;QAC5B,MAAM,GAAG,IAAI,CAAC;QACd,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;YAC3B,iBAAiB,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,wCAAwC,iBAAiB,cAAc,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YACrI,KAAK,MAAM,UAAU,IAAI,WAAW;gBAAE,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,CAAC;YACH,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,2CAA2C;QAC7C,CAAC;IACH,CAAC;IAED,mGAAmG;IACnG,SAAS,eAAe;QACtB,IAAI,CAAC,YAAY,EAAE;YAAE,OAAO;QAC5B,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACrC,IAAI,UAAU,CAAC,UAAU;gBAAE,SAAS;YACpC,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC;YAC7B,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,SAAS,OAAO,CAAC,MAAoB;QACnC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QAClD,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,UAAU;YAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;QACrG,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC9C,KAAK,MAAM,UAAU,IAAI,WAAW;YAAE,IAAI,UAAU,CAAC,UAAU,IAAI,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxH,CAAC;IAED,kGAAkG;IAClG,SAAS,YAAY,CAAC,MAAc;QAClC,OAAO,GAAG,UAAU,EAAE,CAAC;QACvB,MAAM,GAAG,SAAS,CAAC;QACnB,IAAI,GAAG,KAAK,CAAC;QACb,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACrC,UAAU,CAAC,UAAU,GAAG,KAAK,CAAC;YAC9B,UAAU,CAAC,WAAW,GAAG,MAAM,CAAC;QAClC,CAAC;IACH,CAAC;IAED,KAAK,UAAU,GAAG,CAAC,UAA2B;QAC5C,MAAM,QAAQ,GAAsB;YAClC,SAAS;gBACP,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;oBAAE,OAAO;gBACtC,IAAI,GAAG,IAAI,CAAC;gBACZ,QAAQ,GAAG,CAAC,CAAC;gBACb,SAAS,CAAC,OAAO,CAAC,CAAC;gBACnB,eAAe,EAAE,CAAC;YACpB,CAAC;YACD,QAAQ,CAAC,OAAO;gBACd,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO;oBAAE,MAAM,GAAG,OAAO,CAAC;YACnD,CAAC;YACD,QAAQ,CAAC,KAAK;gBACZ,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;oBAAE,OAAO;gBACtC,IAAI,GAAG,KAAK,CAAC;gBACb,SAAS,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;YAClC,CAAC;SACF,CAAC;QACF,IAAI,GAAG,KAAK,CAAC;QACb,SAAS,CAAC,YAAY,CAAC,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC;gBAClC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;gBACxD,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,EAAE,QAAQ,CAAC,CAAC;YACb,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;gBACvC,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;oBAAE,MAAM;gBACrC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;oBAAE,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;;oBAClD,OAAO,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC/B,QAAQ,IAAI,CAAC,CAAC;gBACd,IAAI,GAAG,KAAK,CAAC;gBACb,SAAS,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,QAAQ,KAAK,UAAU;gBAAE,QAAQ,GAAG,IAAI,CAAC;YAC7C,IAAI,GAAG,KAAK,CAAC;YACb,kEAAkE;YAClE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO;gBAAE,QAAQ,EAAE,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,SAAS,KAAK;QACZ,UAAU,GAAG,SAAS,CAAC;QACvB,IAAI,QAAQ,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAC/C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,QAAQ,GAAG,UAAU,CAAC;QACtB,oGAAoG;QACpG,KAAK,GAAG,CAAC,UAAU,CAAC,CAAC;IACvB,CAAC;IAED,SAAS,QAAQ;QACf,IAAI,QAAQ,IAAI,UAAU,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAC3E,MAAM,KAAK,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,iBAAiB,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3G,UAAU,GAAG,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACtC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;IACvB,CAAC;IAED,SAAS,IAAI,CAAC,UAAsB;QAClC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,YAAY,CAAC,SAAS,CAAC,CAAC;YACxB,SAAS,GAAG,SAAS,CAAC;QACxB,CAAC;QACD,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC5B,QAAQ,EAAE,CAAC;IACb,CAAC;IAED,SAAS,OAAO,CAAC,UAAsB;QACrC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,WAAW,CAAC,IAAI,GAAG,CAAC;YAAE,OAAO;QACpE,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,YAAY,CAAC,UAAU,CAAC,CAAC;YACzB,UAAU,GAAG,SAAS,CAAC;QACzB,CAAC;QACD,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAC1B,SAAS,GAAG,SAAS,CAAC;YACtB,uFAAuF;YACvF,QAAQ,EAAE,KAAK,EAAE,CAAC;YAClB,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,GAAG,KAAK,CAAC;YACb,SAAS,CAAC,MAAM,CAAC,CAAC;QACpB,CAAC,EAAE,WAAW,CAAC,CAAC;QAChB,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;IACtB,CAAC;IAED,kGAAkG;IAClG,SAAS,OAAO,CAAC,UAAsB,EAAE,WAA+B;QACtE,IAAI,CAAC,WAAW;YAAE,OAAO,KAAK,CAAC;QAC/B,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAChD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;QACzD,IAAI,KAAK,KAAK,OAAO,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,GAAG,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7G,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnC,IAAI,KAAK,CAAC,GAAG,GAAG,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;gBAAE,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACvI,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,IAAI,IAAI;YACN,OAAO,WAAW,CAAC,IAAI,CAAC;QAC1B,CAAC;QACD,IAAI,MAAM;YACR,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE;YACzC,MAAM,OAAO,GAAG,CAAC,MAAoB,EAAE,EAAE;gBACvC,IAAI,CAAC,MAAM;oBAAE,OAAO,IAAI,CAAC;gBACzB,IAAI,CAAC;oBACH,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;gBACjC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,CAAC,IAAI,CAAC,+CAA+C,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;oBAC7G,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC,CAAC;YACF,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;YAClC,IAAI,UAAkC,CAAC;YACvC,IAAI,SAAqD,CAAC;YAC1D,IAAI,MAAiD,CAAC;YACtD,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC,SAAiB,CAAC;YAEpC,MAAM,IAAI,GAAG,IAAI,cAAc,CAAa;gBAC1C,KAAK,CAAC,UAAU;oBACd,IAAI,MAAM,GAAG,KAAK,CAAC;oBACnB,KAAK,GAAG,GAAG,EAAE;wBACX,IAAI,MAAM;4BAAE,OAAO;wBACnB,MAAM,GAAG,IAAI,CAAC;wBACd,aAAa,CAAC,SAAS,CAAC,CAAC;wBACzB,YAAY,CAAC,MAAM,CAAC,CAAC;wBACrB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;wBAC5C,IAAI,UAAU;4BAAE,OAAO,CAAC,UAAU,CAAC,CAAC;wBACpC,IAAI,CAAC;4BACH,UAAU,CAAC,KAAK,EAAE,CAAC;wBACrB,CAAC;wBAAC,MAAM,CAAC;4BACP,kCAAkC;wBACpC,CAAC;oBACH,CAAC,CAAC;oBACF,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE;wBAC7B,IAAI,MAAM;4BAAE,OAAO;wBACnB,IAAI,CAAC;4BACH,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;wBAC5C,CAAC;wBAAC,MAAM,CAAC;4BACP,KAAK,EAAE,CAAC;wBACV,CAAC;oBACH,CAAC,CAAC;oBACF,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;wBACpB,MAAM,GAAG,IAAI,CAAC;wBACd,UAAU,CAAC,KAAK,EAAE,CAAC;wBACnB,OAAO;oBACT,CAAC;oBACD,MAAM,OAAO,GAAe,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;oBAClG,UAAU,GAAG,OAAO,CAAC;oBACrB,IAAI,YAAY,EAAE,EAAE,CAAC;wBACnB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;wBAC1B,iEAAiE;wBACjE,IAAI,OAAO,CAAC,OAAO,EAAE,WAAW,IAAI,SAAS,CAAC;4BAAE,IAAI,CAAC,OAAO,QAAQ,EAAE,MAAM,CAAC,CAAC;6BACzE,IAAI,WAAW;4BAAE,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;wBACvE,+FAA+F;;4BAC1F,IAAI,CAAC,OAAO,QAAQ,EAAE,MAAM,CAAC,CAAC;oBACrC,CAAC;yBAAM,IAAI,WAAW,EAAE,CAAC;wBACvB,OAAO,CAAC,WAAW,GAAG,kBAAkB,CAAC;oBAC3C,CAAC;oBACD,IAAI,MAAM,KAAK,aAAa;wBAAE,IAAI,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC;oBACxE,IAAI,CAAC,OAAO,CAAC,CAAC;oBACd,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,CAAC;oBACnH,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;oBACpB,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;oBACtE,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;oBACjB,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC3D,CAAC;gBACD,MAAM;oBACJ,KAAK,EAAE,CAAC;gBACV,CAAC;aACF,CAAC,CAAC;YAEH,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;gBACxB,OAAO,EAAE;oBACP,cAAc,EAAE,kCAAkC;oBAClD,eAAe,EAAE,wBAAwB;oBACzC,mBAAmB,EAAE,IAAI;iBAC1B;aACF,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * `createChangeRelay`: one `data.subscribe` per server process, fanned out to\n * browsers as server-sent events on a route of the App.\n *\n *   const relay = createChangeRelay(data);\n *   // GET /api/changes, after the App authenticated the visitor:\n *   return relay.stream({\n *     filter: (change) => canSee(visitor, change),\n *     lastEventId: request.headers.get('Last-Event-ID'),\n *     signal: request.signal,\n *   });\n *\n * The upstream runs as the App and sees every change of the collections\n * granted to it; `filter` decides, per browser, what that visitor may know\n * about. It is called synchronously for every change, live or replayed, and\n * a filter that throws drops the change. Events carry identities only\n * (collection, record ID, revision, kind of change), never record data: the\n * browser reads what it shows through the App's own API, which applies the\n * App's rules.\n *\n * Browsers never open their own upstream: the Gateway limits open\n * subscriptions per workspace, not per visitor.\n *\n * Positions: browsers never see UNS cursors. The relay numbers the changes it\n * forwards `<epoch>.<seq>`; that is the SSE `id`. A browser gets a position\n * (an id-only frame, repeated as its heartbeat) only once the upstream can\n * deliver every change after it:\n *\n * - Cold start: until the upstream's first connection streams, browsers get\n *   no position. Then each of them gets `reset` (`upstream-started`) with a\n *   position, so a page that read its data before the upstream existed\n *   reads it again.\n * - The relay keeps the last UNS position. When the upstream fails, or closes\n *   `idleCloseMs` after the last browser left, it reopens from that position\n *   in the same epoch: nothing is missed and connected browsers get no reset.\n * - Only a `reset` from the upstream (`CURSOR_EXPIRED`, `SCOPE_CHANGED`,\n *   `COLLECTION_RECREATED`) starts a new epoch. Connected browsers then get\n *   that `reset`, with a new position, once the upstream streams again.\n *\n * A reconnect's `Last-Event-ID` is looked up in the latest `bufferSize`\n * changes of the current epoch: found, the changes after it are replayed;\n * anything else (another epoch, too old, forged) answers that browser with\n * `reset` (`unknown-event-id`). `reset` means the same as from\n * `data.subscribe`: changes may have been missed, reload what is shown.\n *\n * When the upstream cannot connect (e.g. 429 over the subscription limit,\n * `APP_NOT_READY`, or a failure that ends `data.subscribe`), the relay goes to\n * status `unavailable`: `onStatus` hears it, `logger.warn` logs it once, and\n * every browser stream gets `event: unavailable` with `{reason}`. The upstream\n * keeps retrying; when it streams again the status is `ready`, and browsers\n * that were waiting for a position get it as described above. A failure that\n * ends `data.subscribe` reopens after `restartIntervalMs`, doubling per\n * consecutive failure up to `maxRestartIntervalMs`.\n *\n * Every browser stream ends after `maxStreamMs` (±10 %), so the browser\n * reconnects and the App's route authenticates it again. Reconnect timing is\n * the browser client's: `openEventStream` (`@tier0/sdk-v2/event-stream`)\n * handles platform errors, the App's sleep and hidden pages itself, so the\n * relay sends no `retry:` field.\n *\n * Frames: `event: change` with `{eventId, collection, change, recordId,\n * revision, occurredAt}` (`RelayedChange`), `event: reset` with `{reason}`,\n * `event: unavailable` with `{reason}`, and every `heartbeatMs` an id-only\n * frame with the current position (a `: heartbeat` comment while the browser\n * has none), so an idle browser's resume point stays inside the buffer.\n */\nimport { randomUUID } from 'node:crypto';\nimport type { DataError } from './error.js';\nimport type { RecordChange, SubscribeObserver, SubscribeOptions, SubscriptionEvent } from './subscribe.js';\n\n/** `idle`: no upstream; `connecting`: opening it; `ready`: it streams; `unavailable`: it cannot connect and keeps retrying. */\nexport type ChangeRelayStatus = 'idle' | 'connecting' | 'ready' | 'unavailable';\n\nexport interface ChangeRelayOptions {\n  /** Collections of the upstream; every declared collection by default. */\n  collections?: SubscribeOptions['collections'];\n  /** Changes kept for replay to reconnecting browsers. Default 1000. */\n  bufferSize?: number;\n  /** Close the upstream this long after the last browser left. Default 30 s. */\n  idleCloseMs?: number;\n  /** Wait before reopening a failed upstream; doubles per consecutive failure. Default 5 s. */\n  restartIntervalMs?: number;\n  /** Default 5 minutes. */\n  maxRestartIntervalMs?: number;\n  /** Default 15 s. */\n  heartbeatMs?: number;\n  /** A browser stream ends after this long (±10 %). Default 10 minutes. */\n  maxStreamMs?: number;\n  /** Status changes; `error` is the failure behind `unavailable`. */\n  onStatus?: (status: ChangeRelayStatus, error?: unknown) => void;\n  logger?: Pick<Console, 'warn'>;\n}\n\nexport interface ChangeRelayStreamOptions {\n  /** Whether this browser gets the change; every change when absent. */\n  filter?: (change: RecordChange) => boolean;\n  /** The browser's `Last-Event-ID` header. */\n  lastEventId?: string | null;\n  /** Ends the stream, e.g. `request.signal`. */\n  signal?: AbortSignal;\n}\n\n/** The `data` of a `change` frame. `eventId` is the relay's position, not a UNS cursor. */\nexport interface RelayedChange {\n  eventId: string;\n  collection: string;\n  change: 'record' | 'delete';\n  recordId: string;\n  revision: number;\n  occurredAt: number;\n}\n\nexport interface ChangeRelay {\n  /** An SSE response for one browser. */\n  stream(options?: ChangeRelayStreamOptions): Response;\n  /** Open browser streams. */\n  readonly size: number;\n  readonly status: ChangeRelayStatus;\n}\n\n/** The upstream as the relay uses it: `data.subscribe` with its internal observer. */\nexport interface ChangeRelaySource {\n  subscribe(options: SubscribeOptions, observer?: SubscribeObserver): AsyncIterable<SubscriptionEvent>;\n}\n\nconst DEFAULTS = {\n  bufferSize: 1000,\n  idleCloseMs: 30_000,\n  restartIntervalMs: 5_000,\n  maxRestartIntervalMs: 300_000,\n  heartbeatMs: 15_000,\n  maxStreamMs: 600_000,\n};\n\ninterface Subscriber {\n  matches(change: RecordChange): boolean;\n  send(chunk: string): void;\n  /** Has a position; until then it gets no change frames and, once positioned, a reset with `resetReason`. */\n  positioned: boolean;\n  resetReason: string;\n}\n\n/** One epoch's numbering of the changes the relay forwarded. */\ninterface Session {\n  epoch: string;\n  seq: number;\n  /** Latest forwarded changes, oldest first. */\n  buffer: { seq: number; change: RecordChange }[];\n}\n\nfunction changeFrame(change: RecordChange, eventId: string): string {\n  const { collection, change: kind, recordId, revision, occurredAt } = change;\n  const data: RelayedChange = { eventId, collection, change: kind, recordId, revision, occurredAt };\n  return `event: change\\nid: ${eventId}\\ndata: ${JSON.stringify(data)}\\n\\n`;\n}\n\n/** A reset that also moves the browser to `position`, so its next reconnect resumes there. */\nfunction resetFrame(reason: string, position: string): string {\n  return `event: reset\\nid: ${position}\\ndata: ${JSON.stringify({ reason })}\\n\\n`;\n}\n\nfunction unavailableFrame(reason: string): string {\n  return `event: unavailable\\ndata: ${JSON.stringify({ reason })}\\n\\n`;\n}\n\nfunction reasonOf(error: unknown): string {\n  const value = error as Partial<DataError> | undefined;\n  return typeof value?.code === 'string' ? value.code : 'upstream-failed';\n}\n\nfunction newSession(): Session {\n  return { epoch: randomUUID().slice(0, 8), seq: 0, buffer: [] };\n}\n\nexport function createChangeRelay(data: ChangeRelaySource, options: ChangeRelayOptions = {}): ChangeRelay {\n  const { collections, onStatus, logger = console } = options;\n  const { bufferSize, idleCloseMs, restartIntervalMs, maxRestartIntervalMs, heartbeatMs, maxStreamMs } = { ...DEFAULTS, ...options };\n  const subscribers = new Set<Subscriber>();\n  let session = newSession();\n  /** The last UNS position: the upstream reopens from it. */\n  let cursor: string | undefined;\n  /** The current upstream connection streams. */\n  let live = false;\n  let status: ChangeRelayStatus = 'idle';\n  let unavailableReason = 'upstream-failed';\n  let upstream: AbortController | null = null;\n  let startTimer: ReturnType<typeof setTimeout> | undefined;\n  let idleTimer: ReturnType<typeof setTimeout> | undefined;\n  let failures = 0;\n\n  const position = () => `${session.epoch}.${session.seq}`;\n  /** Every change after the current position will reach the browsers. */\n  const positionable = () => cursor !== undefined || live;\n\n  function setStatus(next: ChangeRelayStatus, error?: unknown) {\n    if (next === status) return;\n    status = next;\n    if (next === 'unavailable') {\n      unavailableReason = reasonOf(error);\n      logger.warn(`[change-relay] upstream unavailable (${unavailableReason}); retrying:`, error instanceof Error ? error.message : error);\n      for (const subscriber of subscribers) subscriber.send(unavailableFrame(unavailableReason));\n    }\n    try {\n      onStatus?.(next, error);\n    } catch {\n      // A status listener cannot stop the relay.\n    }\n  }\n\n  /** Gives waiting browsers their reset and position, once the upstream can deliver what follows. */\n  function positionWaiting() {\n    if (!positionable()) return;\n    for (const subscriber of subscribers) {\n      if (subscriber.positioned) continue;\n      subscriber.positioned = true;\n      subscriber.send(resetFrame(subscriber.resetReason, position()));\n    }\n  }\n\n  function forward(change: RecordChange) {\n    session.seq += 1;\n    session.buffer.push({ seq: session.seq, change });\n    if (session.buffer.length > bufferSize) session.buffer.splice(0, session.buffer.length - bufferSize);\n    const chunk = changeFrame(change, position());\n    for (const subscriber of subscribers) if (subscriber.positioned && subscriber.matches(change)) subscriber.send(chunk);\n  }\n\n  /** The upstream reset: a new epoch, and every browser reloads once the upstream streams again. */\n  function restartEpoch(reason: string) {\n    session = newSession();\n    cursor = undefined;\n    live = false;\n    for (const subscriber of subscribers) {\n      subscriber.positioned = false;\n      subscriber.resetReason = reason;\n    }\n  }\n\n  async function run(controller: AbortController) {\n    const observer: SubscribeObserver = {\n      connected() {\n        if (controller.signal.aborted) return;\n        live = true;\n        failures = 0;\n        setStatus('ready');\n        positionWaiting();\n      },\n      position(eventId) {\n        if (!controller.signal.aborted) cursor = eventId;\n      },\n      retrying(error) {\n        if (controller.signal.aborted) return;\n        live = false;\n        setStatus('unavailable', error);\n      },\n    };\n    live = false;\n    setStatus('connecting');\n    try {\n      const subscription = data.subscribe({\n        ...(collections ? { collections } : {}),\n        ...(cursor === undefined ? {} : { lastEventId: cursor }),\n        signal: controller.signal,\n      }, observer);\n      for await (const event of subscription) {\n        if (controller.signal.aborted) break;\n        if (event.type === 'reset') restartEpoch(event.reason);\n        else forward(event);\n      }\n    } catch (error) {\n      if (!controller.signal.aborted) {\n        failures += 1;\n        live = false;\n        setStatus('unavailable', error);\n      }\n    } finally {\n      if (upstream === controller) upstream = null;\n      live = false;\n      // Reopens from the last UNS position: same epoch, nothing missed.\n      if (!controller.signal.aborted) schedule();\n    }\n  }\n\n  function start() {\n    startTimer = undefined;\n    if (upstream || subscribers.size === 0) return;\n    const controller = new AbortController();\n    upstream = controller;\n    // The upstream outlives the request that started it; data.subscribe never takes a request's signal.\n    void run(controller);\n  }\n\n  function schedule() {\n    if (upstream || startTimer !== undefined || subscribers.size === 0) return;\n    const delay = failures === 0 ? 0 : Math.min(maxRestartIntervalMs, restartIntervalMs * 2 ** (failures - 1));\n    startTimer = setTimeout(start, delay);\n    startTimer.unref?.();\n  }\n\n  function join(subscriber: Subscriber) {\n    if (idleTimer !== undefined) {\n      clearTimeout(idleTimer);\n      idleTimer = undefined;\n    }\n    subscribers.add(subscriber);\n    schedule();\n  }\n\n  function release(subscriber: Subscriber) {\n    if (!subscribers.delete(subscriber) || subscribers.size > 0) return;\n    if (startTimer !== undefined) {\n      clearTimeout(startTimer);\n      startTimer = undefined;\n    }\n    idleTimer = setTimeout(() => {\n      idleTimer = undefined;\n      // The epoch, buffer and UNS position stay: the next browser resumes in the same epoch.\n      upstream?.abort();\n      upstream = null;\n      live = false;\n      setStatus('idle');\n    }, idleCloseMs);\n    idleTimer.unref?.();\n  }\n\n  /** Replays after `lastEventId`; false when it is not a position of the current epoch's buffer. */\n  function catchUp(subscriber: Subscriber, lastEventId: string | undefined): boolean {\n    if (!lastEventId) return false;\n    const [epoch, seqText] = lastEventId.split('.');\n    const seq = Number(seqText);\n    const oldest = session.buffer[0]?.seq ?? session.seq + 1;\n    if (epoch !== session.epoch || !Number.isInteger(seq) || seq > session.seq || seq < oldest - 1) return false;\n    for (const entry of session.buffer) {\n      if (entry.seq > seq && subscriber.matches(entry.change)) subscriber.send(changeFrame(entry.change, `${session.epoch}.${entry.seq}`));\n    }\n    return true;\n  }\n\n  return {\n    get size() {\n      return subscribers.size;\n    },\n    get status() {\n      return status;\n    },\n    stream({ filter, lastEventId, signal } = {}) {\n      const matches = (change: RecordChange) => {\n        if (!filter) return true;\n        try {\n          return filter(change) === true;\n        } catch (error) {\n          logger.warn('[change-relay] filter failed; change dropped:', error instanceof Error ? error.message : error);\n          return false;\n        }\n      };\n      const encoder = new TextEncoder();\n      let subscriber: Subscriber | undefined;\n      let heartbeat: ReturnType<typeof setInterval> | undefined;\n      let expiry: ReturnType<typeof setTimeout> | undefined;\n      let close = () => undefined as void;\n\n      const body = new ReadableStream<Uint8Array>({\n        start(controller) {\n          let closed = false;\n          close = () => {\n            if (closed) return;\n            closed = true;\n            clearInterval(heartbeat);\n            clearTimeout(expiry);\n            signal?.removeEventListener('abort', close);\n            if (subscriber) release(subscriber);\n            try {\n              controller.close();\n            } catch {\n              // Already closed by the consumer.\n            }\n          };\n          const send = (chunk: string) => {\n            if (closed) return;\n            try {\n              controller.enqueue(encoder.encode(chunk));\n            } catch {\n              close();\n            }\n          };\n          if (signal?.aborted) {\n            closed = true;\n            controller.close();\n            return;\n          }\n          const current: Subscriber = { matches, send, positioned: false, resetReason: 'upstream-started' };\n          subscriber = current;\n          if (positionable()) {\n            current.positioned = true;\n            // A known position replays what followed; anything else reloads.\n            if (catchUp(current, lastEventId ?? undefined)) send(`id: ${position()}\\n\\n`);\n            else if (lastEventId) send(resetFrame('unknown-event-id', position()));\n            // A first connect: an id-only frame dispatches nothing and gives the browser its resume point.\n            else send(`id: ${position()}\\n\\n`);\n          } else if (lastEventId) {\n            current.resetReason = 'unknown-event-id';\n          }\n          if (status === 'unavailable') send(unavailableFrame(unavailableReason));\n          join(current);\n          heartbeat = setInterval(() => send(current.positioned ? `id: ${position()}\\n\\n` : ': heartbeat\\n\\n'), heartbeatMs);\n          heartbeat.unref?.();\n          expiry = setTimeout(close, maxStreamMs * (0.9 + Math.random() * 0.2));\n          expiry.unref?.();\n          signal?.addEventListener('abort', close, { once: true });\n        },\n        cancel() {\n          close();\n        },\n      });\n\n      return new Response(body, {\n        headers: {\n          'Content-Type': 'text/event-stream; charset=utf-8',\n          'Cache-Control': 'no-cache, no-transform',\n          'X-Accel-Buffering': 'no',\n        },\n      });\n    },\n  };\n}\n"]}

package/dist/esm/data/subscribe.d.ts

@@ -23,9 +23,11 @@
  *   `delete` always passes, a late one too, and forgets the record's
  *   revision, since a record written again under the same ID may start
  *   over at revision 1.
- * - Changes in collections with employee data rules (`restricted`) come as
- *   collection-level notices unless `restricted: "record"` is asked for.
  * - Aborting `signal` or leaving the loop ends the iteration without error.
+ * - The stream runs as the App: it sees every change of the collections
+ *   granted to the App. A server opens one per process and fans it out to
+ *   browsers with `createChangeRelay`, filtering per browser by what the App
+ *   lets that visitor see.
  *
  * Events carry identities only, never record data; read the record to show it.
  */
@@ -40,62 +42,46 @@ export interface SubscribeOptions {
     collections?: readonly (CollectionTarget | string)[];
     /** Only changes of these record IDs (1–100, duplicates ignored), when exactly one collection is watched. */
     recordIds?: readonly string[];
-    /**
-     * How changes in collections with employee data rules arrive.
-     * `collection` (default): as a collection-level notice without record ID
-     * or revision, safe to forward to any employee. `record`: the full event,
-     * for server-side consumers that do not forward it to browsers, or that
-     * redact per recipient with `redactRestricted`.
-     */
-    restricted?: 'collection' | 'record';
     /** Resume after this event (e.g. a browser's `Last-Event-ID`). */
     lastEventId?: string;
     signal?: AbortSignal;
     /** Reconnect when nothing, not even a heartbeat, arrives for this long. */
     idleTimeoutMs?: number;
 }
-interface ChangeBase {
+/**
+ * One record committed (`record`) or deleted (`delete`) at `revision`. A
+ * `record` change is never at or below a revision already passed on for the
+ * same record since its last delete; a `delete` may be.
+ */
+export interface RecordChange {
     type: 'change';
     eventId: string;
     /** Alias of a declared collection, or the ID of an existing collection reference. */
     collection: string;
     collectionId: string;
     occurredAt: number;
-    /**
-     * The collection has employee data rules: whether an employee may see this
-     * record depends on who they are. Such changes arrive as `CollectionChange`
-     * unless the subscription asked for `restricted: "record"`.
-     */
-    restricted: boolean;
-}
-/**
- * One record committed (`record`) or deleted (`delete`) at `revision`. A
- * `record` change is never at or below a revision already passed on for the
- * same record since its last delete; a `delete` may be.
- */
-export interface RecordChange extends ChangeBase {
     change: 'record' | 'delete';
     recordId: string;
     revision: number;
 }
-/** Something in the collection changed; which record is not disclosed. Reload through the data rules. */
-export interface CollectionChange extends ChangeBase {
-    change: 'collection';
-}
-export type ChangeEvent = RecordChange | CollectionChange;
 /** `reason`: `CURSOR_EXPIRED`, `SCOPE_CHANGED` (from UNS) or `COLLECTION_RECREATED`. */
-export type SubscriptionEvent = ChangeEvent | {
+export type SubscriptionEvent = RecordChange | {
     type: 'reset';
     reason: string;
     message?: string;
 };
 /**
- * The event as an employee's browser may see it: a change in a collection
- * with employee data rules becomes a collection-level notice without record
- * ID or revision, so it does not reveal records the employee may not read.
- * Other events pass unchanged.
+ * What `data.subscribe` tells a server-side consumer about the upstream
+ * (`createChangeRelay` uses it; not part of the public API).
  */
-export declare function redactRestricted<E extends SubscriptionEvent>(event: E): E | CollectionChange;
+export interface SubscribeObserver {
+    /** A connection is streaming: its first frame (the connect heartbeat) arrived. */
+    connected?(): void;
+    /** The resume position moved: a heartbeat position or a change, dropped or not. */
+    position?(eventId: string): void;
+    /** An attempt failed and will be retried after a wait (e.g. 429 over the subscription limit, `APP_NOT_READY`). */
+    retrying?(error: DataError): void;
+}
 export interface SubscribeRuntime {
     openStream: DataOpenStream;
     ensure(targets: readonly CollectionTarget[]): Promise<EnsureState>;
@@ -103,7 +89,5 @@ export interface SubscribeRuntime {
     resolve(target: CollectionTarget): Promise<string>;
     lookup(target: CollectionTarget | string): CollectionTarget;
     declared: readonly CollectionTarget[];
-    subject(): string | undefined;
 }
-export declare function createSubscribe(runtime: SubscribeRuntime): (options?: SubscribeOptions) => AsyncGenerator<SubscriptionEvent, void, undefined>;
-export {};
+export declare function createSubscribe(runtime: SubscribeRuntime): (options?: SubscribeOptions, observer?: SubscribeObserver) => AsyncGenerator<SubscriptionEvent, void, undefined>;