orez-sync-cf-host 0.11.0 → 0.11.1

package/dist/host.js

@@ -1,13 +1,19 @@
 import { DurableObject } from 'cloudflare:workers';
+import { createSocketHost } from 'orez-lite/realtime';
 import { createSyncExecutor } from 'orez-sync-executor/core';
 import { validatePullCaps, validateSyncHostConfig } from './config.js';
 import { createQueryCompiler } from './query-compiler.js';
 import { resolveQueryPatch } from './query-patch.js';
 import { decodeSqlParams, SqlStorageDirect, SqlStorageMutatorTransaction, SqlStorageSyncDb, } from './sql-storage-adapter.js';
-import { engine_apply_snapshot_changes, engine_apply_snapshot_page, engine_apply_upstream, engine_begin_snapshot_generation, engine_finalize, engine_finalize_snapshot_generation, engine_handle_pull, engine_handle_query_pull, engine_init_query_schema, engine_init_schema, engine_invalidate, engine_memory_bytes, engine_preflight, engine_prune, engine_push_validate, engine_read_snapshot_progress, engine_state, engine_version, } from './wasm.js';
+import { engine_authorize_realtime_subscription, engine_apply_snapshot_changes, engine_apply_snapshot_page, engine_apply_upstream, engine_begin_snapshot_generation, engine_finalize, engine_finalize_snapshot_generation, engine_handle_pull, engine_handle_query_pull, engine_init_query_schema, engine_init_schema, engine_invalidate, engine_memory_bytes, engine_preflight, engine_prune, engine_push_validate, engine_read_snapshot_progress, engine_state, engine_version, } from './wasm.js';
 import { IngestBreakerError, IngestCircuitBreaker, retryDelayMs, shouldRetryDelegatedPush, } from './write-safeguards.js';
 const NAMESPACE_HEADER = 'x-orez-sync-namespace';
 const UPSTREAM_PATH_HEADER = 'x-orez-sync-upstream-path';
+// A websocket upgrade is a GET, so the authenticated identity cannot ride the
+// body the way /pull and /push carry their claims. It rides a private header
+// the worker always deletes from the incoming request before setting its own,
+// so a client cannot present one.
+const IDENTITY_HEADER = 'x-orez-sync-identity';
 const DEFAULT_SNAPSHOT_PAGE_ROWS = 2_000;
 const MIN_SNAPSHOT_PAGE_ROWS = 100;
 const DEFAULT_CAPS = {
@@ -176,9 +182,19 @@ export function createSyncWorker(config) {
                 return new Response('orez sync-cf-host', { status: 200 });
             const route = routeAfterNamespace(new URL(request.url).pathname);
             const isAdmin = route.startsWith('/admin/');
+            let wakeUserID = null;
             if (route === '/wake') {
-                if (!(await config.authorizeWake(request, env))) {
+                const wake = await config.authorizeWake(request, env);
+                if (!wake)
                     return json({ error: 'missing wake capability' }, 401);
+                if (typeof wake === 'object')
+                    wakeUserID = wake.userID;
+                // A namespace that streams fields authorizes every subscription against
+                // this userID, so a capability that does not carry one cannot open the
+                // socket. Failing here names the cause; accepting it would produce a
+                // wake-only socket whose subscriptions silently never deliver.
+                if (config.streamingManifest && !wakeUserID) {
+                    return json({ error: 'wake capability must identify a user' }, 401);
                 }
             }
             else if (route === '/notify') {
@@ -196,8 +212,16 @@ export function createSyncWorker(config) {
             const headers = new Headers(request.headers);
             headers.delete(NAMESPACE_HEADER);
             headers.delete(UPSTREAM_PATH_HEADER);
+            headers.delete(IDENTITY_HEADER);
             let forwardedBody = null;
-            if (!isAdmin && route !== '/wake' && route !== '/notify') {
+            // /wake and /realtime/produce are both websocket upgrades, which cannot
+            // carry an Authorization header from a browser and have no body to put
+            // claims in. Each has its own capability check above and in the DO, so
+            // neither passes through the bearer-token gate below.
+            if (!isAdmin &&
+                route !== '/wake' &&
+                route !== '/notify' &&
+                route !== '/realtime/produce') {
                 const claims = await config.authenticate(request, env);
                 if (!claims || typeof claims.userID !== 'string' || claims.userID.length === 0) {
                     return json({ error: 'missing authentication' }, 401);
@@ -215,6 +239,13 @@ export function createSyncWorker(config) {
                     }
                 }
             }
+            // Only the userID travels, because it is the only part the DO must be
+            // unable to doubt. The socket also carries a clientID and clientGroupID,
+            // but those are the client's own assertion and the engine checks the
+            // group against this userID before it will read a single row, so there is
+            // nothing gained by moving them here.
+            if (wakeUserID)
+                headers.set(IDENTITY_HEADER, encodeURIComponent(wakeUserID));
             headers.set(NAMESPACE_HEADER, await namespaceHash(namespace));
             if (config.upstream) {
                 const namespacePath = typeof config.upstream.namespacePath === 'function'
@@ -268,6 +299,14 @@ export function createSyncDurableObject(config) {
         #wakeOrigins = new Set();
         #wakeRecipients = new Set();
         #wakePromise = null;
+        // Streaming fields. Null when the namespace configures no manifest, which
+        // is every wake-only deployment: no hub is built and nothing below runs.
+        #realtime = null;
+        #realtimeConnections = new Map();
+        // Resolves once the sockets from a previous incarnation have been replayed
+        // into this hub. Held as a promise rather than a flag so frames arriving
+        // during the replay wait for it instead of racing past into an empty hub.
+        #realtimeReady = null;
         #ingestPromise = null;
         #queryPullLocks = new Map();
         #recordingIngestBillable = false;
@@ -388,6 +427,14 @@ export function createSyncDurableObject(config) {
                 this.#wakeOrigins.clear();
                 this.#wakeRecipients.clear();
                 this.#wakePromise = null;
+                // Real hibernation reconstructs the object, so the hub and every
+                // connection handle are gone while the sockets stay open. Modelling
+                // that here is what makes rehydration reachable from a test: leaving
+                // the hub in place would make the simulation pass for a reason the
+                // real runtime never gives it.
+                this.#realtime = null;
+                this.#realtimeConnections.clear();
+                this.#realtimeReady = null;
             }
             this.#lastRequestAt = now;
         }
@@ -1268,17 +1315,117 @@ export function createSyncDurableObject(config) {
                 return json({ error: errorMessage(error) }, status);
             }
         }
+        // The hub for this incarnation, built on first use. Null unless the
+        // namespace configures a manifest, so a wake-only deployment never pays for
+        // one and every realtime path below is skipped.
+        #realtimeHost() {
+            const manifest = config.streamingManifest;
+            if (!manifest)
+                return null;
+            if (this.#realtime)
+                return this.#realtime;
+            this.#realtime = createSocketHost({
+                manifest,
+                // Answered from this object's own SQLite, which is the same durable
+                // membership the client's query pull reads. A field is streamed to a
+                // client exactly when the row carrying it is already being synced to
+                // that client, so streaming can never widen what somebody can see.
+                authorizeSubscribe: (identity, topic) => {
+                    const result = this.#wasm(() => engine_authorize_realtime_subscription(this.#engineDb, config.schema, identity.clientGroupID, identity.userID, topic.table, topic.key));
+                    if (result.authorized)
+                        return { status: 'active' };
+                    // the group is this user's, but the row is not in its membership
+                    // yet. That is the optimistic-row race, not a denial: the client
+                    // holds a row from its own unacked mutation, and retries after the
+                    // pull that records it.
+                    if (result.ownsGroup)
+                        return { status: 'pending' };
+                    return { status: 'denied', reason: 'row is not in this client group' };
+                },
+            });
+            return this.#realtime;
+        }
+        // Replay the sockets that outlived the previous incarnation. Every open
+        // socket is replayed, not just the one that woke us: a producer's frames
+        // must reach every subscriber of a topic, so restoring only the socket that
+        // happened to send first would silently drop the rest.
+        #realtimeRehydrate(host) {
+            if (this.#realtimeReady)
+                return this.#realtimeReady;
+            this.#realtimeReady = (async () => {
+                const subscribers = [];
+                for (const socket of this.ctx.getWebSockets()) {
+                    if (this.#realtimeConnections.has(socket))
+                        continue;
+                    const attachment = socketAttachment(socket);
+                    if (!attachment)
+                        continue;
+                    if (attachment.producerID) {
+                        // Generations are ephemeral by design, so nothing is restored here
+                        // beyond the channel itself; the producer opens a new generation
+                        // and the durable row covers the gap either way.
+                        this.#realtimeConnections.set(socket, host.acceptProducer(socket, attachment.producerID));
+                        continue;
+                    }
+                    if (!attachment.identity)
+                        continue;
+                    subscribers.push({
+                        socket,
+                        identity: attachment.identity,
+                        connectionID: attachment.identity.clientID,
+                        topics: attachment.topics ?? [],
+                    });
+                }
+                const restored = await host.rehydrate(subscribers);
+                subscribers.forEach((entry, index) => {
+                    this.#realtimeConnections.set(entry.socket, restored[index]);
+                });
+            })();
+            return this.#realtimeReady;
+        }
+        // A socket's topics are the only realtime state that must survive an
+        // eviction, so they are rewritten whenever they change rather than on a
+        // timer: an eviction is not announced.
+        #realtimePersist(socket, connection) {
+            const attachment = socketAttachment(socket);
+            if (!attachment)
+                return;
+            socket.serializeAttachment({
+                ...attachment,
+                topics: [...connection.topics()],
+            });
+        }
         #wake(request) {
             if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
                 return json({ error: 'websocket upgrade required' }, 426);
             }
-            const clientID = new URL(request.url).searchParams.get('clientID');
+            const params = new URL(request.url).searchParams;
+            const clientID = params.get('clientID');
             if (!clientID)
                 return json({ error: 'clientID is required' }, 400);
             const pair = new WebSocketPair();
             const [client, server] = Object.values(pair);
-            server.serializeAttachment({ clientID });
+            // The userID is the worker's, taken from the authenticated request. The
+            // group is the client's own claim, and stays a claim: every subscription
+            // is checked against this userID before a row is read, so asserting
+            // someone else's group buys nothing.
+            const encodedUserID = request.headers.get(IDENTITY_HEADER);
+            const clientGroupID = params.get('clientGroupID');
+            const identity = encodedUserID && clientGroupID
+                ? {
+                    userID: decodeURIComponent(encodedUserID),
+                    clientID,
+                    clientGroupID,
+                }
+                : undefined;
+            server.serializeAttachment({ clientID, identity });
             this.ctx.acceptWebSocket(server, [`client:${clientID}`]);
+            if (identity) {
+                const host = this.#realtimeHost();
+                if (host) {
+                    this.#realtimeConnections.set(server, host.acceptSubscriber(server, identity, clientID));
+                }
+            }
             // The alarm is only a safety net for an actively connected consumer.
             // A namespace with no wake socket has nobody to notify; its next pull or
             // push ingests synchronously. Arming from construction made every
@@ -1453,6 +1600,9 @@ export function createSyncDurableObject(config) {
                 return this.#admin(route, request, upstreamPath);
             if (route === '/wake' && request.method === 'GET')
                 return this.#wake(request);
+            if (route === '/realtime/produce' && request.method === 'GET') {
+                return this.#realtimeProduce(request, this.env);
+            }
             if (route === '/notify' && request.method === 'POST') {
                 try {
                     const applied = await this.#ingest(upstreamPath);
@@ -1504,9 +1654,49 @@ export function createSyncDurableObject(config) {
                 }
             }
         }
-        webSocketMessage(socket, message) {
-            if (message === 'ping')
+        // A producer channel. Publishing is a far stronger capability than waking,
+        // so it needs its own authorization and gets no default: a namespace that
+        // configures no authorizeProduce cannot be published to at all.
+        async #realtimeProduce(request, env) {
+            if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
+                return json({ error: 'websocket upgrade required' }, 426);
+            }
+            const host = this.#realtimeHost();
+            if (!host)
+                return json({ error: 'namespace streams no fields' }, 404);
+            if (!config.authorizeProduce || !(await config.authorizeProduce(request, env))) {
+                return json({ error: 'forbidden' }, 403);
+            }
+            const producerID = new URL(request.url).searchParams.get('producerID') ?? crypto.randomUUID();
+            const pair = new WebSocketPair();
+            const [client, server] = Object.values(pair);
+            server.serializeAttachment({
+                clientID: producerID,
+                producerID,
+            });
+            this.ctx.acceptWebSocket(server, [`producer:${producerID}`]);
+            this.#realtimeConnections.set(server, host.acceptProducer(server, producerID));
+            return new Response(null, { status: 101, webSocket: client });
+        }
+        async webSocketMessage(socket, message) {
+            if (message === 'ping') {
                 socket.send('pong');
+                return;
+            }
+            const host = this.#realtimeHost();
+            if (!host || typeof message !== 'string')
+                return;
+            // A cold start left the hub empty while the socket stayed open, so the
+            // subscriptions have to be replayed before this frame is applied.
+            await this.#realtimeRehydrate(host);
+            const connection = this.#realtimeConnections.get(socket);
+            if (!connection)
+                return;
+            connection.handleMessage(message);
+            // The hub may authorize asynchronously, so the topic set this frame
+            // changed is not final until that settles.
+            await Promise.resolve();
+            this.#realtimePersist(socket, connection);
         }
         webSocketClose(socket, code, reason, _wasClean) {
             // The peer already closed, so echo the close to release the socket — but
@@ -1515,10 +1705,22 @@ export function createSyncDurableObject(config) {
             // closes with 1001/1005. An uncaught throw here aborts the DO, so only
             // echo an application-permitted code and otherwise close cleanly.
             const echoable = code === 1000 || (code >= 3000 && code <= 4999);
+            this.#realtimeDrop(socket);
             socketCloseQuietly(socket, echoable ? code : 1000, echoable ? reason : '');
         }
         webSocketError(socket, _error) {
+            this.#realtimeDrop(socket);
             socketCloseQuietly(socket, 1011, 'wake socket error');
         }
+        // Release whatever the socket held: a subscriber's topics, or a producer's
+        // generations. Dropping a producer reveals the durable row to everyone
+        // watching it, so a crashed producer cannot strand a stale overlay.
+        #realtimeDrop(socket) {
+            const connection = this.#realtimeConnections.get(socket);
+            if (!connection)
+                return;
+            this.#realtimeConnections.delete(socket);
+            connection.close();
+        }
     };
 }

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { QueryResolution, QueryResolutionRequest } from './query-patch.js';
 import type { TransactionQueryBudget } from './transaction-query.js';
 import type { Schema } from '@rocicorp/zero';
+import type { StreamingManifest } from 'orez-lite/realtime';
 import type { ExecResult, MutatorRegistry, NormalizedClaims, SqlStatementMetadata, VisibilityConfig } from 'orez-sync-executor';
 export { visibility, type VisibilityExpression, type VisibilityFilter, type VisibilityOperand, type VisibilityValue, } from './visibility.js';
 export type { VisibilityConfig } from 'orez-sync-executor';
@@ -90,8 +91,20 @@ export type SyncHostConfig<Env extends SyncHostEnv = SyncHostEnv, S extends Sche
     authorize(request: Request, claims: NormalizedClaims, namespace: string, env: Env): boolean | Promise<boolean>;
     /** Authorize the advisory wake socket before selecting a namespace DO.
      * Browser clients should present a short-lived, namespace-scoped capability
-     * in the query string because WebSocket cannot set request headers. */
-    authorizeWake(request: Request, env: Env): boolean | Promise<boolean>;
+     * in the query string because WebSocket cannot set request headers.
+     *
+     * Return `{ userID }` instead of `true` to also identify the socket, which is
+     * what a namespace serving `streamingManifest` must do: field subscriptions
+     * ride this socket and are authorized against that userID. Returning bare
+     * `true` there is refused rather than quietly downgraded to a wake-only
+     * socket, because the failure would otherwise look like streaming that just
+     * never arrives. The capability is the only credential available here, so the
+     * userID belongs inside it. */
+    authorizeWake(request: Request, env: Env): boolean | {
+        userID: string;
+    } | Promise<boolean | {
+        userID: string;
+    }>;
     /** Authorize upstream service notifications before selecting a namespace DO. */
     authorizeNotify(request: Request, env: Env): boolean | Promise<boolean>;
     /** Resolve the first path component or another consumer-defined namespace. */
@@ -102,6 +115,27 @@ export type SyncHostConfig<Env extends SyncHostEnv = SyncHostEnv, S extends Sche
     queryAware?: boolean | ((claims: NormalizedClaims) => boolean);
     /** Resolve every named query in one desired-query patch, in one call. */
     resolveQueries?: QueryResolver;
+    /**
+     * Streaming fields for this namespace: which columns may carry a live,
+     * uncommitted value, and their publish mode and rate bounds.
+     *
+     * Supplied as a live object rather than data because a field's `validate` is
+     * a function; there is nothing to serialize into a deploy bundle, and the
+     * application's own module is where it belongs. Absent means the namespace
+     * serves no field subscriptions and rejects producer frames.
+     *
+     * See docs/streaming-fields.md.
+     */
+    streamingManifest?: StreamingManifest;
+    /**
+     * Authorize a producer socket, which may publish a value into any streaming
+     * field for any row. That is a much stronger capability than the wake socket
+     * or an ordinary client's, so it has no default: leaving this unset means the
+     * namespace accepts no producers, and every `/realtime/produce` upgrade is
+     * refused. Producers are server-side callers (an AI generation worker, a job
+     * runner), so a service binding or a shared secret is the usual check.
+     */
+    authorizeProduce?: (request: Request, env: Env) => boolean | Promise<boolean>;
     /** Server-owned invalidation epoch for permission/schema transforms. */
     queryTransformVersion?: number | ((claims: NormalizedClaims) => number);
     /** Enable consumer visibility from the first request. Defaults to false for harnesses. */

package/dist/wasm.d.ts

@@ -3,6 +3,7 @@ export declare const engine_apply_snapshot_changes: (db: any, schema: any, gener
 export declare const engine_apply_snapshot_page: (db: any, schema: any, generation: string, table: string, rows: any, next_cursor?: string | null | undefined) => any;
 export declare const engine_apply_upstream: (db: any, schema: any, batch: any) => any;
 export declare const engine_assemble_push_response: (results: any) => any;
+export declare const engine_authorize_realtime_subscription: (db: any, schema: any, client_group_id: string, user_id: string, table: string, pk: any) => any;
 export declare const engine_begin_snapshot_generation: (db: any, schema: any, start_watermark: string) => any;
 export declare const engine_compile_query: (schema: any, ast: any, format: any) => any;
 export declare const engine_finalize: (db: any, client_group_id: string, client_id: string, mutation_id: string) => void;

package/dist/wasm.js

@@ -20,6 +20,7 @@ export const engine_apply_snapshot_changes = withWasm(generated.engine_apply_sna
 export const engine_apply_snapshot_page = withWasm(generated.engine_apply_snapshot_page);
 export const engine_apply_upstream = withWasm(generated.engine_apply_upstream);
 export const engine_assemble_push_response = withWasm(generated.engine_assemble_push_response);
+export const engine_authorize_realtime_subscription = withWasm(generated.engine_authorize_realtime_subscription);
 export const engine_begin_snapshot_generation = withWasm(generated.engine_begin_snapshot_generation);
 export const engine_compile_query = withWasm(generated.engine_compile_query);
 export const engine_finalize = withWasm(generated.engine_finalize);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez-sync-cf-host",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "type": "module",
   "exports": {
     ".": {
@@ -60,7 +60,7 @@
     "typecheck": "bun run build:dist:platform && tsc --noEmit"
   },
   "dependencies": {
-    "orez-sync-executor": "0.11.0"
+    "orez-sync-executor": "0.11.1"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "4.20260617.1",