orez-sync-cf-host 0.12.14 → 0.12.15

package/README.md

@@ -168,7 +168,12 @@ channel disconnects, it retries in the background while the safety poll
 continues to provide convergence.
 
 `/admin/status` reports a boot ID, hibernation simulation count, connected wake
-sockets, durable database size, engine watermark/floor, and aggregate counters.
+sockets, durable database size, engine watermark/floor, aggregate counters, and
+the most recent coalesced wake batch. That wake record includes the sorted
+upstream table names which caused the batch plus its socket, recipient, timing,
+and frame counts. Local-only pushes have no upstream table attribution and
+therefore report an empty table list. The same fields are emitted in the
+structured `sync_wake` log.
 After the configured idle gap (5 seconds in the harness deployment), the local
 deterministic model resets in-memory state and changes boot ID while retaining
 SQLite state and sockets. This models the harness idle-teardown pattern; it

package/dist/host.d.ts

@@ -6,7 +6,9 @@ import type { Schema } from '@rocicorp/zero';
  * Durable Object receives normalized claims inside the binding request body so
  * observability systems cannot record them as request-header metadata.
  */
-export declare function createSyncWorker<Env extends SyncHostEnv, S extends Schema = Schema>(config: SyncHostConfig<Env, S>): ExportedHandler<Env>;
+export declare function createSyncWorker<Env extends SyncHostEnv, S extends Schema = Schema>(config: SyncHostConfig<Env, S>): ExportedHandler<Env> & {
+    notify(env: Env, namespace: string): Promise<Response>;
+};
 export interface SyncDurableObjectConstructor<Env extends SyncHostEnv> {
     new (ctx: DurableObjectState, env: Env): DurableObject<Env>;
 }

package/dist/host.js

@@ -9,6 +9,8 @@ import { engine_authorize_realtime_subscription, engine_apply_snapshot_changes,
 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';
+const NOTIFY_IF_SUBSCRIBED_HEADER = 'x-orez-notify-if-subscribed';
+const WAKE_SUBSCRIBER_TAG = 'orez:wake-subscriber';
 // 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,
@@ -16,6 +18,15 @@ const UPSTREAM_PATH_HEADER = 'x-orez-sync-upstream-path';
 const IDENTITY_HEADER = 'x-orez-sync-identity';
 const DEFAULT_SNAPSHOT_PAGE_ROWS = 2_000;
 const MIN_SNAPSHOT_PAGE_ROWS = 100;
+function upstreamBatchTables(batch) {
+    const tables = new Set();
+    for (const change of batch.changes) {
+        if (typeof change?.tableName === 'string' && change.tableName.length > 0) {
+            tables.add(change.tableName);
+        }
+    }
+    return tables;
+}
 function freshCounters() {
     return {
         pulls: 0,
@@ -171,6 +182,17 @@ function socketCloseQuietly(socket, code, reason) {
 export function createSyncWorker(config) {
     validateSyncHostConfig(config);
     const allowedOrigins = new Set(config.allowedOrigins ?? []);
+    const upstreamPath = (namespace) => {
+        if (!config.upstream)
+            return null;
+        const path = typeof config.upstream.namespacePath === 'function'
+            ? config.upstream.namespacePath(namespace)
+            : config.upstream.namespacePath;
+        if (!path.startsWith('/')) {
+            throw new Error('upstream namespacePath must be an absolute path');
+        }
+        return path.replace(/\/$/, '');
+    };
     const corsHeaders = (origin) => ({
         'access-control-allow-origin': origin,
         vary: 'origin',
@@ -266,6 +288,7 @@ export function createSyncWorker(config) {
                 headers.delete(NAMESPACE_HEADER);
                 headers.delete(UPSTREAM_PATH_HEADER);
                 headers.delete(IDENTITY_HEADER);
+                headers.delete(NOTIFY_IF_SUBSCRIBED_HEADER);
                 let forwardedBody = null;
                 // /wake and /realtime/produce are both websocket upgrades and have no
                 // body to put claims in. wake authentication is normalized from its
@@ -302,14 +325,13 @@ export function createSyncWorker(config) {
                 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'
-                        ? config.upstream.namespacePath(namespace)
-                        : config.upstream.namespacePath;
-                    if (!namespacePath.startsWith('/')) {
-                        return json({ error: 'upstream namespacePath must be an absolute path' }, 500);
-                    }
-                    headers.set(UPSTREAM_PATH_HEADER, namespacePath.replace(/\/$/, ''));
+                try {
+                    const path = upstreamPath(namespace);
+                    if (path !== null)
+                        headers.set(UPSTREAM_PATH_HEADER, path);
+                }
+                catch (error) {
+                    return errorResponse(error);
                 }
                 const forwarded = forwardedBody
                     ? jsonBodyRequest(request, headers, forwardedBody)
@@ -319,6 +341,23 @@ export function createSyncWorker(config) {
             };
             return withCors(await handle());
         },
+        async notify(env, namespace) {
+            if (!namespace)
+                throw new TypeError('sync notification namespace is required');
+            const path = upstreamPath(namespace);
+            if (path === null)
+                throw new Error('sync notifications require an upstream feed');
+            const headers = new Headers({
+                [NAMESPACE_HEADER]: await namespaceHash(namespace),
+                [UPSTREAM_PATH_HEADER]: path,
+                [NOTIFY_IF_SUBSCRIBED_HEADER]: '1',
+            });
+            const request = new Request('https://orez-sync.internal/namespace/notify', {
+                method: 'POST',
+                headers,
+            });
+            return env.SYNC_DO.get(env.SYNC_DO.idFromName(namespace)).fetch(request);
+        },
     };
 }
 /** Create the namespace Durable Object class for one bundled consumer config. */
@@ -352,6 +391,7 @@ export function createSyncDurableObject(config) {
         #executor;
         #executorBeforeCommitFault = null;
         #bootID = crypto.randomUUID();
+        #initialized = false;
         #initSkipped = false;
         #lastRequestAt = 0;
         #hibernations = 0;
@@ -361,7 +401,9 @@ export function createSyncDurableObject(config) {
         #pulling = new Set();
         #wakeOrigins = new Set();
         #wakeRecipients = new Set();
+        #wakeTables = new Set();
         #wakePromise = null;
+        #lastWake = 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;
@@ -445,39 +487,42 @@ export function createSyncDurableObject(config) {
                     schema: config.schema,
                 })
                 : null;
-            ctx.blockConcurrencyWhile(async () => {
-                ctx.storage.transactionSync(() => {
-                    this.#directSql.exec(`CREATE TABLE IF NOT EXISTS _zsync_host_control (
-            key TEXT PRIMARY KEY,
-            value TEXT NOT NULL
-          )`);
-                    // one durable fingerprint gates the whole schema pass. hibernation
-                    // reconstructs this object every few idle minutes, and re-running
-                    // consumer DDL plus both engine inits against an already-current
-                    // database costs ~1.5k billable reads per wake. everything the pass
-                    // depends on is in the fingerprint, so a build that changes any DDL
-                    // surface re-runs it exactly once per namespace.
-                    const initFingerprint = JSON.stringify([
-                        config.hostVersion,
-                        this.#wasm(() => engine_schema_revision()),
-                        config.schema,
-                        config.initialize.toString(),
-                    ]);
-                    this.#initSkipped = this.#controlGet('initFingerprint') === initFingerprint;
-                    if (!this.#initSkipped) {
-                        config.initialize(this.#directSql);
-                        this.#directSql.exec("INSERT OR IGNORE INTO _zsync_host_control (key, value) VALUES ('writerEnabled', '1')");
-                        this.#wasm(() => engine_init_schema(this.#engineDb, config.schema));
-                        this.#wasm(() => engine_init_query_schema(this.#engineDb));
-                        this.#controlSet('initFingerprint', initFingerprint);
-                    }
-                    const ingestBreakerReason = this.#controlGet('ingestBreakerReason');
-                    if (ingestBreakerReason === 'ingestBudgetExceeded' ||
-                        ingestBreakerReason === 'ingestCursorStalled') {
-                        this.#ingestBreaker.restore(ingestBreakerReason, Number(this.#controlGet('ingestBreakerRetryAt')), Number(this.#controlGet('ingestBreakerTrips')));
-                    }
-                });
+        }
+        #initialize() {
+            if (this.#initialized)
+                return;
+            this.ctx.storage.transactionSync(() => {
+                this.#directSql.exec(`CREATE TABLE IF NOT EXISTS _zsync_host_control (
+          key TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        )`);
+                // one durable fingerprint gates the whole schema pass. hibernation
+                // reconstructs this object every few idle minutes, and re-running
+                // consumer DDL plus both engine inits against an already-current
+                // database costs ~1.5k billable reads per wake. everything the pass
+                // depends on is in the fingerprint, so a build that changes any DDL
+                // surface re-runs it exactly once per namespace.
+                const initFingerprint = JSON.stringify([
+                    config.hostVersion,
+                    this.#wasm(() => engine_schema_revision()),
+                    config.schema,
+                    config.initialize.toString(),
+                ]);
+                this.#initSkipped = this.#controlGet('initFingerprint') === initFingerprint;
+                if (!this.#initSkipped) {
+                    config.initialize(this.#directSql);
+                    this.#directSql.exec("INSERT OR IGNORE INTO _zsync_host_control (key, value) VALUES ('writerEnabled', '1')");
+                    this.#wasm(() => engine_init_schema(this.#engineDb, config.schema));
+                    this.#wasm(() => engine_init_query_schema(this.#engineDb));
+                    this.#controlSet('initFingerprint', initFingerprint);
+                }
+                const ingestBreakerReason = this.#controlGet('ingestBreakerReason');
+                if (ingestBreakerReason === 'ingestBudgetExceeded' ||
+                    ingestBreakerReason === 'ingestCursorStalled') {
+                    this.#ingestBreaker.restore(ingestBreakerReason, Number(this.#controlGet('ingestBreakerRetryAt')), Number(this.#controlGet('ingestBreakerTrips')));
+                }
             });
+            this.#initialized = true;
         }
         #armUpstreamAlarm() {
             if (!config.upstream)
@@ -501,7 +546,9 @@ export function createSyncDurableObject(config) {
                 this.#pulling.clear();
                 this.#wakeOrigins.clear();
                 this.#wakeRecipients.clear();
+                this.#wakeTables.clear();
                 this.#wakePromise = null;
+                this.#lastWake = 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
@@ -759,6 +806,7 @@ export function createSyncDurableObject(config) {
                 let pendingPage = null;
                 let snapshotPageLimit = DEFAULT_SNAPSHOT_PAGE_ROWS;
                 let snapshotCompleted = false;
+                const changedTables = new Set();
                 for (;;) {
                     if (progress?.state === 'paging') {
                         const activeProgress = progress;
@@ -781,6 +829,7 @@ export function createSyncDurableObject(config) {
                             }, () => this.ctx.storage.transactionSync(() => this.#wasm(() => engine_apply_snapshot_page(this.#engineDb, config.schema, activeProgress.generation, table, pageToApply.rows, pageToApply.nextCursor))));
                             total += pageToApply.rows.length;
                             this.#recordIngestLogicalRows(pageToApply.rows.length);
+                            changedTables.add(table);
                             progress = nextProgress;
                             pendingPage = null;
                         }
@@ -818,6 +867,8 @@ export function createSyncDurableObject(config) {
                         if (!Number.isSafeInteger(batch.watermark) || !Array.isArray(batch.changes)) {
                             throw new Error('invalid upstream changes response');
                         }
+                        for (const table of upstreamBatchTables(batch))
+                            changedTables.add(table);
                         this.#resetSnapshotBillingWindow();
                         const result = this.#withIngestBilling({
                             phase: 'snapshot_catchup',
@@ -884,6 +935,8 @@ export function createSyncDurableObject(config) {
                     if (!Number.isSafeInteger(batch.watermark) || !Array.isArray(batch.changes)) {
                         throw new Error('invalid upstream changes response');
                     }
+                    for (const table of upstreamBatchTables(batch))
+                        changedTables.add(table);
                     const result = this.#withIngestBilling({
                         phase: 'changes',
                         cursor,
@@ -921,7 +974,7 @@ export function createSyncDurableObject(config) {
                 this.#recoverIngestBreaker();
                 const endingWatermark = this.#engineState().watermark;
                 if (snapshotCompleted || total > 0 || endingWatermark !== startingWatermark) {
-                    await this.#enqueueWake('__upstream__');
+                    await this.#enqueueWake('__upstream__', changedTables);
                 }
                 return total;
             })().finally(() => {
@@ -978,9 +1031,11 @@ export function createSyncDurableObject(config) {
                 ...fields,
             }));
         }
-        #enqueueWake(originClientID) {
+        #enqueueWake(originClientID, tables = []) {
             this.#wakeOrigins.add(originClientID);
-            for (const socket of this.ctx.getWebSockets()) {
+            for (const table of tables)
+                this.#wakeTables.add(table);
+            for (const socket of this.ctx.getWebSockets(WAKE_SUBSCRIBER_TAG)) {
                 const attachment = socketAttachment(socket);
                 if (!attachment ||
                     attachment.clientID === originClientID ||
@@ -1001,9 +1056,11 @@ export function createSyncDurableObject(config) {
                     this.#wakeOrigins = new Set();
                     const recipients = this.#wakeRecipients;
                     this.#wakeRecipients = new Set();
+                    const tables = [...this.#wakeTables].sort();
+                    this.#wakeTables = new Set();
                     this.#counters.wakeBatches++;
                     let sent = 0;
-                    const sockets = this.ctx.getWebSockets();
+                    const sockets = this.ctx.getWebSockets(WAKE_SUBSCRIBER_TAG);
                     for (const socket of recipients) {
                         try {
                             socket.send('wake');
@@ -1015,15 +1072,21 @@ export function createSyncDurableObject(config) {
                             // a race here is advisory and carries no correctness weight.
                         }
                     }
-                    console.log(JSON.stringify({
-                        event: 'sync_wake',
-                        hostVersion: config.hostVersion,
+                    const wakeStatus = {
+                        at: Date.now(),
+                        tables,
                         socketCount: sockets.length,
                         originCount: origins.size,
                         sent,
                         eligibleRecipients: recipients.size,
                         coalesceMs: fanoutStarted - queuedAt,
                         fanoutMs: performance.now() - fanoutStarted,
+                    };
+                    this.#lastWake = wakeStatus;
+                    console.log(JSON.stringify({
+                        event: 'sync_wake',
+                        hostVersion: config.hostVersion,
+                        ...wakeStatus,
                     }));
                 })().finally(() => {
                     this.#wakePromise = null;
@@ -1439,7 +1502,7 @@ export function createSyncDurableObject(config) {
                 clientID,
                 identity,
             });
-            this.ctx.acceptWebSocket(server, [`client:${clientID}`]);
+            this.ctx.acceptWebSocket(server, [WAKE_SUBSCRIBER_TAG, `client:${clientID}`]);
             if (identity) {
                 const host = this.#realtimeHost();
                 if (host) {
@@ -1474,7 +1537,7 @@ export function createSyncDurableObject(config) {
                     idleTeardownMs,
                     hibernations: this.#hibernations,
                     databaseSizeBytes: this.ctx.storage.sql.databaseSize,
-                    connectedWakeSockets: this.ctx.getWebSockets().length,
+                    connectedWakeSockets: this.ctx.getWebSockets(WAKE_SUBSCRIBER_TAG).length,
                     upstreamAlarmAt,
                     writerEnabled: this.#writerEnabled(),
                     wasmMemoryBytes: engine_memory_bytes(),
@@ -1485,6 +1548,7 @@ export function createSyncDurableObject(config) {
                     sqlBillingSinceBoot: this.#sqlBilling,
                     counters: this.#counters,
                     ingestBreaker: this.#ingestBreaker.status(),
+                    lastWake: this.#lastWake,
                 }));
             }
             if (route === '/admin/sql') {
@@ -1609,8 +1673,20 @@ export function createSyncDurableObject(config) {
             return json({ error: 'not found' }, 404);
         }
         async fetch(request) {
-            this.#simulateIdleTeardown(Date.now());
             const route = routeAfterNamespace(new URL(request.url).pathname);
+            if (route === '/notify' &&
+                request.method === 'POST' &&
+                request.headers.get(NOTIFY_IF_SUBSCRIBED_HEADER) === '1' &&
+                this.ctx.getWebSockets(WAKE_SUBSCRIBER_TAG).length === 0) {
+                return json({
+                    ok: true,
+                    applied: 0,
+                    skipped: 'no-wake-subscribers',
+                    rowsWritten: this.#sqlBilling.rowsWritten,
+                });
+            }
+            this.#initialize();
+            this.#simulateIdleTeardown(Date.now());
             const namespace = request.headers.get(NAMESPACE_HEADER) ?? 'unknown';
             const upstreamPath = this.#rememberUpstreamPath(request);
             if (route.startsWith('/admin/'))
@@ -1622,7 +1698,7 @@ export function createSyncDurableObject(config) {
             }
             if (route === '/notify' && request.method === 'POST') {
                 try {
-                    const applied = await this.#ingest(upstreamPath);
+                    const applied = await this.#ingestAfterCurrent(upstreamPath);
                     return json({ ok: true, applied });
                 }
                 catch (error) {
@@ -1652,8 +1728,9 @@ export function createSyncDurableObject(config) {
             return json({ error: 'not found' }, 404);
         }
         async alarm() {
-            if (this.ctx.getWebSockets().length === 0)
+            if (this.ctx.getWebSockets(WAKE_SUBSCRIBER_TAG).length === 0)
                 return;
+            this.#initialize();
             try {
                 await this.#ingest();
             }
@@ -1665,7 +1742,7 @@ export function createSyncDurableObject(config) {
                 }));
             }
             finally {
-                if (this.ctx.getWebSockets().length > 0) {
+                if (this.ctx.getWebSockets(WAKE_SUBSCRIBER_TAG).length > 0) {
                     const retryAfterMs = this.#ingestBreaker.status().retryAfterMs;
                     await this.ctx.storage.setAlarm(Date.now() + Math.max(upstreamIntervalMs, retryAfterMs));
                 }
@@ -1700,6 +1777,7 @@ export function createSyncDurableObject(config) {
                 socket.send('pong');
                 return;
             }
+            this.#initialize();
             const host = this.#realtimeHost();
             if (!host || typeof message !== 'string')
                 return;

package/dist/sql-storage-adapter.js

@@ -1,6 +1,6 @@
+import { trackBillableCursorRows } from 'orez-sync-executor/sql-billing';
 import { encodeSqlValue } from 'orez-sync-executor/sqlite';
 import { executeTransactionQueryPlan } from './transaction-query.js';
-import { trackBillableCursorRows } from './write-safeguards.js';
 // Match transaction control only as the statement itself. CREATE TRIGGER uses
 // `... BEGIN ... END` for its body, which is valid DO SQL and not a transaction.
 const TX_SQL = /^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)(?=\s|;|$)/i;

package/dist/write-safeguards.d.ts

@@ -39,16 +39,5 @@ export declare class IngestCircuitBreaker {
     restore(reason: IngestBreakerReason, retryAt: number, consecutiveTrips: number): void;
     reopen(): void;
 }
-type BillableCursor = {
-    rowsRead?: number;
-    rowsWritten?: number;
-    next?: (...args: unknown[]) => unknown;
-    one?: (...args: unknown[]) => unknown;
-    toArray?: (...args: unknown[]) => unknown;
-    raw?: (...args: unknown[]) => unknown;
-    [Symbol.iterator]?: () => Iterator<unknown>;
-};
-export declare function trackBillableCursorRows<Cursor extends BillableCursor>(cursor: Cursor, recordWritten: (rows: number) => void, recordRead?: (rows: number) => void): Cursor;
 export declare function retryDelayMs(attempt: number, initialBackoffMs: number, maxBackoffMs: number): number;
 export declare function shouldRetryDelegatedPush(responseStatus: number | null, attempt: number, maxAttempts: number): boolean;
-export {};

package/dist/write-safeguards.js

@@ -122,65 +122,6 @@ export class IngestCircuitBreaker {
         this.recovered();
     }
 }
-export function trackBillableCursorRows(cursor, recordWritten, recordRead = () => { }) {
-    if (!cursor || typeof cursor !== 'object')
-        return cursor;
-    let accountedWritten = 0;
-    let accountedRead = 0;
-    const account = () => {
-        const written = Number(cursor.rowsWritten ?? 0);
-        if (Number.isSafeInteger(written) && written > accountedWritten) {
-            recordWritten(written - accountedWritten);
-            accountedWritten = written;
-        }
-        const read = Number(cursor.rowsRead ?? 0);
-        if (Number.isSafeInteger(read) && read > accountedRead) {
-            recordRead(read - accountedRead);
-            accountedRead = read;
-        }
-    };
-    const wrapIterator = (iterator) => {
-        const next = iterator.next.bind(iterator);
-        return {
-            next(...args) {
-                try {
-                    return next(...args);
-                }
-                finally {
-                    account();
-                }
-            },
-            [Symbol.iterator]() {
-                return this;
-            },
-        };
-    };
-    let proxy;
-    proxy = new Proxy(cursor, {
-        get(target, property) {
-            const value = Reflect.get(target, property, target);
-            if (property === Symbol.iterator)
-                return () => proxy;
-            if ((property === 'next' || property === 'one' || property === 'toArray') &&
-                typeof value === 'function') {
-                return (...args) => {
-                    try {
-                        return Reflect.apply(value, target, args);
-                    }
-                    finally {
-                        account();
-                    }
-                };
-            }
-            if (property === 'raw' && typeof value === 'function') {
-                return (...args) => wrapIterator(Reflect.apply(value, target, args));
-            }
-            return typeof value === 'function' ? value.bind(target) : value;
-        },
-    });
-    account();
-    return proxy;
-}
 export function retryDelayMs(attempt, initialBackoffMs, maxBackoffMs) {
     return Math.min(maxBackoffMs, initialBackoffMs * 2 ** Math.max(0, attempt - 1));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez-sync-cf-host",
-  "version": "0.12.14",
+  "version": "0.12.15",
   "description": "Internal orez Cloudflare sync host. Do not import directly: consumers use orez-lite/cloudflare/sync.",
   "type": "module",
   "exports": {
@@ -58,7 +58,7 @@
     "test:large-data": "bun run build:dist && bun large-data-test.mjs"
   },
   "dependencies": {
-    "orez-sync-executor": "0.12.14"
+    "orez-sync-executor": "0.12.15"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "4.20260617.1",