orez-sync-cf-host 0.14.0 → 0.14.1

package/README.md

@@ -20,6 +20,17 @@ belong in
 `ctx.defer`, which runs only after commit. Application failures use the
 required second transaction to advance the LMID marker.
 
+The Worker emits structured `sync_worker_stage` logs around `authenticate` and
+the namespace Durable Object `fetch`. Successful requests are sampled at 1%.
+Errors are always logged, and a stage still waiting after five seconds emits an
+unsampled `waiting` event before the request can be terminated externally. A
+slow stage that later completes also logs its final duration. The event carries
+request kind, host version, duration, outcome, response status, and the existing
+hashed namespace once forwarding begins. Healthy requests pay
+one random comparison per request plus one timer arm, timer cancellation, and
+one clock read per measured stage. The sampled completion reads the clock once
+more. No extra fetch, storage operation, or await is added.
+
 Every pull is query-driven. Set `config.queries` to the same registry used by
 the client. The host resolves desired named queries in-process and passes
 authenticated claims as their context, so permission scoping remains inside the
@@ -34,13 +45,14 @@ non-ASCII case pairs can diverge from PostgreSQL.
 Every runtime uses the same `orez-sync-cf-host/wasm-module.wasm` import and the same
 `initSync` path. Configure the loader that matches the host:
 
-| Host                         | Configuration                                                                                         | Module value                                                 |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| Workerd / Wrangler           | Map the package's `wasm-module.wasm` export as a compiled Wasm module; do not install the Vite plugin | Cloudflare `CompiledWasm`                                    |
-| Bun                          | Preload `orez-sync-cf-host/bun-wasm-loader`                                                           | `WebAssembly.Module` compiled by the Bun loader              |
-| Vite serve / SSR development | Add `orezSyncCfHostWasm()` from `orez-sync-cf-host/vite-wasm-loader`                                  | `WebAssembly.Module` built from package bytes by Vite        |
-| Direct Node >= 22.15         | Preload `orez-sync-cf-host/node-wasm-loader` with `NODE_OPTIONS=--import`                             | `WebAssembly.Module` compiled by the Node loader             |
-| Node production bundle       | Keep the same Vite plugin active for the production SSR build                                         | `WebAssembly.Module` built from bytes embedded in the bundle |
+| Host                         | Configuration                                                                                                                                   | Module value                                                 |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Workerd / Wrangler           | Map the package's `wasm-module.wasm` export as a compiled Wasm module                                                                           | Cloudflare `CompiledWasm`                                    |
+| Workerd build through Vite   | Add `orezSyncCfHostWasm({ runtime: 'workerd' })`, preload the Node or Bun loader during the build, and map the export as a compiled Wasm module | Cloudflare `CompiledWasm`                                    |
+| Bun                          | Preload `orez-sync-cf-host/bun-wasm-loader`                                                                                                     | `WebAssembly.Module` compiled by the Bun loader              |
+| Vite serve / SSR development | Add `orezSyncCfHostWasm()` from `orez-sync-cf-host/vite-wasm-loader`                                                                            | `WebAssembly.Module` built from package bytes by Vite        |
+| Direct Node >= 22.15         | Preload `orez-sync-cf-host/node-wasm-loader` with `NODE_OPTIONS=--import`                                                                       | `WebAssembly.Module` compiled by the Node loader             |
+| Node production bundle       | Keep the same Vite plugin active for the production SSR build                                                                                   | `WebAssembly.Module` built from bytes embedded in the bundle |
 
 The Vite plugin also keeps `orez-sync-cf-host` inside Vite's SSR pipeline.
 
@@ -84,9 +96,12 @@ export default {
 }
 ```
 
-If one Vite config targets both Node and Workerd, include this plugin only for
-the Node target. The Workerd target uses the `CompiledWasm` mapping above and
-must not run the Vite loader.
+If one Vite config targets both Node and Workerd, pass `runtime: 'workerd'` for
+the Workerd build. Serve mode still embeds the module for Vite's Node SSR
+runtime. Build mode preserves the Wasm import for the platform's `CompiledWasm`
+mapping instead of embedding bytes that Workerd cannot compile. Because Vite
+imports the generated server chunks while rendering static routes, start that
+build with the Node or Bun loader shown above.
 
 ## Wake channel and eviction
 

package/dist/host.js

@@ -18,6 +18,8 @@ const WAKE_SUBSCRIBER_TAG = 'orez:wake-subscriber';
 const IDENTITY_HEADER = 'x-orez-sync-identity';
 const DEFAULT_SNAPSHOT_PAGE_ROWS = 2_000;
 const MIN_SNAPSHOT_PAGE_ROWS = 100;
+const WORKER_STAGE_TELEMETRY_SAMPLE_RATE = 0.01;
+const WORKER_STAGE_WAITING_MS = 5_000;
 function upstreamBatchTables(batch) {
     const tables = new Set();
     for (const change of batch.changes) {
@@ -165,6 +167,42 @@ async function namespaceHash(namespace) {
     const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(namespace));
     return Array.from(new Uint8Array(bytes).slice(0, 8), (byte) => byte.toString(16).padStart(2, '0')).join('');
 }
+async function timeWorkerStage(fields, work) {
+    const started = performance.now();
+    let waited = false;
+    const emit = (outcome, value) => {
+        try {
+            console.log(JSON.stringify({
+                event: 'sync_worker_stage',
+                hostVersion: fields.hostVersion,
+                requestKind: fields.requestKind,
+                stage: fields.stage,
+                outcome,
+                durationMs: Math.round((performance.now() - started) * 1_000) / 1_000,
+                namespaceHash: fields.namespaceHash,
+                status: value instanceof Response ? value.status : null,
+                sampleRate: outcome === 'success' && !waited ? WORKER_STAGE_TELEMETRY_SAMPLE_RATE : 1,
+            }));
+        }
+        catch { }
+    };
+    const waitingTimer = setTimeout(() => {
+        waited = true;
+        emit('waiting');
+    }, WORKER_STAGE_WAITING_MS);
+    try {
+        const value = await work();
+        clearTimeout(waitingTimer);
+        if (fields.sampled || waited)
+            emit('success', value);
+        return value;
+    }
+    catch (error) {
+        clearTimeout(waitingTimer);
+        emit('error');
+        throw error;
+    }
+}
 function socketAttachment(socket) {
     const value = socket.deserializeAttachment();
     return value && typeof value.clientID === 'string' ? value : null;
@@ -239,6 +277,8 @@ export function createSyncWorker(config) {
                 if (!namespace)
                     return new Response('orez sync-cf-host', { status: 200 });
                 const route = routeAfterNamespace(new URL(request.url).pathname);
+                const requestKind = route.startsWith('/') ? route.slice(1) : route;
+                const sampled = Math.random() < WORKER_STAGE_TELEMETRY_SAMPLE_RATE;
                 const isAdmin = route.startsWith('/admin/');
                 let wakeUserID = null;
                 if (route === '/wake') {
@@ -313,7 +353,13 @@ export function createSyncWorker(config) {
                     // the callback attached survives to the wire.
                     let claims;
                     try {
-                        claims = await config.authenticate(request, env);
+                        claims = await timeWorkerStage({
+                            hostVersion: config.hostVersion,
+                            requestKind,
+                            stage: 'authenticate',
+                            namespaceHash: null,
+                            sampled,
+                        }, () => config.authenticate(request, env));
                     }
                     catch (error) {
                         return errorResponse(error);
@@ -343,7 +389,8 @@ export function createSyncWorker(config) {
                 // nothing gained by moving them here.
                 if (wakeUserID)
                     headers.set(IDENTITY_HEADER, encodeURIComponent(wakeUserID));
-                headers.set(NAMESPACE_HEADER, await namespaceHash(namespace));
+                const hashedNamespace = await namespaceHash(namespace);
+                headers.set(NAMESPACE_HEADER, hashedNamespace);
                 try {
                     const path = upstreamPath(namespace);
                     if (path !== null)
@@ -356,7 +403,13 @@ export function createSyncWorker(config) {
                     ? jsonBodyRequest(request, headers, forwardedBody)
                     : new Request(request, { headers });
                 const id = env.SYNC_DO.idFromName(namespace);
-                return env.SYNC_DO.get(id).fetch(forwarded);
+                return timeWorkerStage({
+                    hostVersion: config.hostVersion,
+                    requestKind,
+                    stage: 'sync_do_forward',
+                    namespaceHash: hashedNamespace,
+                    sampled,
+                }, () => env.SYNC_DO.get(id).fetch(forwarded));
             };
             return withCors(await handle());
         },
@@ -1011,20 +1064,39 @@ export function createSyncDurableObject(config) {
             let lastError = null;
             for (let attempt = 1; attempt <= delegateMaxAttempts; attempt++) {
                 let response = null;
+                const attemptTimeoutMs = provisioning
+                    ? Math.max(delegateTimeoutMs, 25_000)
+                    : delegateTimeoutMs;
+                // ask the signal, not the rejection: this signal aborts for exactly one
+                // reason, so `aborted` names a timeout without depending on how the
+                // runtime shapes its DOMException.
+                const timeout = AbortSignal.timeout(attemptTimeoutMs);
                 try {
                     response = await binding.fetch(endpoint.toString(), {
                         method: 'POST',
                         headers,
                         body,
-                        signal: AbortSignal.timeout(provisioning ? Math.max(delegateTimeoutMs, 25_000) : delegateTimeoutMs),
+                        signal: timeout,
                     });
                 }
                 catch (error) {
                     lastError = error;
                 }
-                if (!shouldRetryDelegatedPush(response?.status ?? null, attempt, delegateMaxAttempts)) {
+                const timedOut = response === null && timeout.aborted;
+                if (!shouldRetryDelegatedPush(response?.status ?? null, attempt, delegateMaxAttempts, timedOut)) {
                     if (response)
                         return response;
+                    // the retry log below is the only place a delegated push failure was
+                    // ever named, and a terminal failure skips it. log here too, or the
+                    // host answers 500 and says nothing about why.
+                    console.warn(JSON.stringify({
+                        event: 'sync_delegated_push_failed',
+                        attempt,
+                        maxAttempts: delegateMaxAttempts,
+                        timedOut,
+                        timeoutMs: attemptTimeoutMs,
+                        error: errorMessage(lastError),
+                    }));
                     throw lastError;
                 }
                 await response?.body?.cancel();

package/dist/vite-wasm-loader.d.ts

@@ -1,7 +1,8 @@
 import type { Plugin } from 'vite';
 type OrezSyncCfHostWasmOptions = {
     noExternal?: string[];
+    runtime?: 'node' | 'workerd';
 };
-/** load the sync engine for Vite's Node serve, SSR, and production build paths. */
+/** load the sync engine into a Vite SSR graph for Node or Workerd. */
 export declare function orezSyncCfHostWasm(options?: OrezSyncCfHostWasmOptions): Plugin[];
 export {};

package/dist/vite-wasm-loader.js

@@ -1,15 +1,23 @@
 import { readFile } from 'node:fs/promises';
 const wasmModuleID = 'orez-sync-cf-host/wasm-module.wasm';
 const resolvedWasmModuleID = `\0${wasmModuleID}`;
-/** load the sync engine for Vite's Node serve, SSR, and production build paths. */
+/** load the sync engine into a Vite SSR graph for Node or Workerd. */
 export function orezSyncCfHostWasm(options = {}) {
     const noExternal = ['orez-sync-cf-host', ...(options.noExternal ?? [])];
+    let command = 'serve';
     return [
         {
             name: 'orez-sync-cf-host-wasm',
             enforce: 'pre',
+            configResolved(config) {
+                command = config.command;
+            },
             resolveId(source) {
-                return source === wasmModuleID ? resolvedWasmModuleID : null;
+                if (source !== wasmModuleID)
+                    return null;
+                return options.runtime === 'workerd' && command === 'build'
+                    ? { id: wasmModuleID, external: true }
+                    : resolvedWasmModuleID;
             },
             async load(id) {
                 if (id !== resolvedWasmModuleID)

package/dist/write-safeguards.d.ts

@@ -40,4 +40,18 @@ export declare class IngestCircuitBreaker {
     reopen(): void;
 }
 export declare function retryDelayMs(attempt: number, initialBackoffMs: number, maxBackoffMs: number): number;
-export declare function shouldRetryDelegatedPush(responseStatus: number | null, attempt: number, maxAttempts: number): boolean;
+/**
+ * A timeout is terminal, every other transport failure is retryable.
+ *
+ * Retrying a 429 or a transient 5xx is cheap: the app answered in
+ * milliseconds and the second attempt usually lands. Retrying a TIMEOUT is
+ * not. The work was killed mid-flight, so the retry repeats its full cost and
+ * the caller's total budget becomes `maxAttempts * timeoutMs`. The client is
+ * what that total has to fit inside: orez-lite's browser transport aborts any
+ * push whose response headers miss its own 60s deadline, and any push failure
+ * closes its socket, so a doubled budget turns one slow mutation into a full
+ * sync teardown. Contrast ran 30s x 2 attempts against that 60s deadline and
+ * on 2026-08-15 a real user's connection was torn down 19 times in 40 minutes,
+ * once every ~68s, on a push the host answered at ~60.2s.
+ */
+export declare function shouldRetryDelegatedPush(responseStatus: number | null, attempt: number, maxAttempts: number, timedOut: boolean): boolean;

package/dist/write-safeguards.js

@@ -125,8 +125,24 @@ export class IngestCircuitBreaker {
 export function retryDelayMs(attempt, initialBackoffMs, maxBackoffMs) {
     return Math.min(maxBackoffMs, initialBackoffMs * 2 ** Math.max(0, attempt - 1));
 }
-export function shouldRetryDelegatedPush(responseStatus, attempt, maxAttempts) {
+/**
+ * A timeout is terminal, every other transport failure is retryable.
+ *
+ * Retrying a 429 or a transient 5xx is cheap: the app answered in
+ * milliseconds and the second attempt usually lands. Retrying a TIMEOUT is
+ * not. The work was killed mid-flight, so the retry repeats its full cost and
+ * the caller's total budget becomes `maxAttempts * timeoutMs`. The client is
+ * what that total has to fit inside: orez-lite's browser transport aborts any
+ * push whose response headers miss its own 60s deadline, and any push failure
+ * closes its socket, so a doubled budget turns one slow mutation into a full
+ * sync teardown. Contrast ran 30s x 2 attempts against that 60s deadline and
+ * on 2026-08-15 a real user's connection was torn down 19 times in 40 minutes,
+ * once every ~68s, on a push the host answered at ~60.2s.
+ */
+export function shouldRetryDelegatedPush(responseStatus, attempt, maxAttempts, timedOut) {
     if (attempt >= maxAttempts)
         return false;
+    if (timedOut)
+        return false;
     return responseStatus === null || responseStatus === 429 || responseStatus >= 500;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez-sync-cf-host",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "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.14.0"
+    "orez-sync-executor": "0.14.1"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "4.20260617.1",