orez-sync-cf-host 0.5.18 → 0.5.20

package/README.md

@@ -17,6 +17,72 @@ Every SQL cursor is materialized before an await. Mutators may await only their
 `context.defer`, which runs only after commit. Application failures use the
 required second transaction to advance the LMID marker.
 
+The root `orez/cf-do` executor and this host consume the same `post-commit`
+module, so transaction retries discard effects from abandoned attempts in both
+paths.
+
+Transaction-query `ILIKE` folding is ASCII-only on Durable Object SQLite;
+non-ASCII case pairs can diverge from PostgreSQL.
+
+### Query compiler runtimes
+
+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 |
+
+The Vite plugin also keeps `orez-sync-cf-host` inside Vite's SSR pipeline.
+
+Wrangler consumers map the bare address rather than a filesystem glob. The
+`.wasm` suffix is part of the public subpath because extension-keyed bundlers
+classify the original import address:
+
+```toml
+[[rules]]
+type = "CompiledWasm"
+globs = ["orez-sync-cf-host/wasm-module.wasm"]
+fallthrough = true
+```
+
+Bun consumers register the preload in `bunfig.toml`:
+
+```toml
+# bunfig.toml
+preload = ["orez-sync-cf-host/bun-wasm-loader"]
+```
+
+For a single command, use
+`bun --preload orez-sync-cf-host/bun-wasm-loader <command>`. The compiler throws
+an error pointing to this runtime matrix if a loader is missing.
+
+Direct Node consumers on Node 22.15 or newer preload the synchronous module
+hook. `NODE_OPTIONS` also carries the hook into test-runner child processes:
+
+```sh
+NODE_OPTIONS=--import=orez-sync-cf-host/node-wasm-loader node app.js
+```
+
+Node-targeted Vite consumers add the plugin once and leave it active in serve
+and build:
+
+```ts
+import { orezSyncCfHostWasm } from 'orez-sync-cf-host/vite-wasm-loader'
+
+export default {
+  plugins: [orezSyncCfHostWasm()],
+}
+```
+
+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.
+
 ## Wake channel and eviction
 
 `GET /<namespace>/wake?clientID=<id>&wakeToken=<capability>` upgrades to a
@@ -50,6 +116,8 @@ every socket attempt, including reconnects, so short-lived tokens are never
 reused after the wake connection drops:
 
 ```ts
+import { ensureHttpPullTransport } from 'orez/zero-http'
+
 ensureHttpPullTransport({
   origin: syncOrigin,
   pullIntervalMs: 5_000,
@@ -105,6 +173,24 @@ service or operator capability. Both `authorizeWake` and `authorizeNotify` run
 before `idFromName`, so rejected requests cannot instantiate namespace Durable
 Objects.
 
+### Consumer routing traps
+
+If an outer application router has its own namespace gate, let only `/wake` and
+`/notify` pass that outer gate. The sync worker's required `authorizeWake` and
+`authorizeNotify` callbacks then enforce the real capability checks. Do not
+bypass pull, push, or admin routes, and do not replace either callback with an
+unconditional allow.
+
+A delegated push must terminate at the application worker whose registry owns
+the named mutator. Routing it to a sync host, control-plane worker, or another
+application server with a different registry produces an authoritative error
+such as `could not find mutator <name>`. The optimistic client write may appear
+briefly, then disappear on reload and never reach peers. Route client pushes to
+the sync host only when its `mutateBinding` and `mutateUrl` delegate to the
+owning application's mutate endpoint. Preview and browser-local transports must
+stay pointed at their in-process project server unless they provide the same
+delegated route.
+
 `POST /admin/writer` with `{ "enabled": false }` durably stops pushes for that
 namespace. A stopped writer consumes and discards the request body, returns 503,
 and performs no engine or application write. Canary rollback drills must stop
@@ -119,12 +205,36 @@ not mutate a production route. These controls are mechanisms, not authorization
 to perform a production cutover.
 
 `POST /admin/resnapshot` is available only when the consumer configured an
-upstream data service. It reads that namespace's authoritative `/snapshot`,
-atomically replaces the derived application tables, then consumes `/changes`
-until caught up. Engine metadata, client last-mutation IDs, operator controls,
-and the authoritative upstream database are preserved. The JSON response
-includes before/after upstream watermarks and the number of snapshot plus
-catch-up rows applied.
+upstream data service. It reads each modeled source table through bounded
+keyset pages and commits them to a staged generation. Progress is durable, so a
+restart resumes at the recorded table and cursor. The host then catches up
+concurrent `/changes`, atomically swaps the generation into place, and bumps the
+engine epoch. Every client performs one expected full resync after cutover.
+Engine metadata, client last-mutation IDs, operator controls, and the
+authoritative upstream database are preserved. The legacy single-response
+`/snapshot` endpoint remains for small datasets and older harnesses.
+
+## Delegated service addresses
+
+`mutateBinding` selects the service binding that owns the application's mutate
+endpoint and defaults to `upstream.binding`. Set `mutateOrigin` to an exact
+absolute HTTP(S) origin when that worker's routing depends on the request
+origin. `upstream.namespacePath` may return `/` for a root-mounted data feed;
+internally that root is an empty path, while `null` alone means no upstream path
+is configured.
+
+A successful delegated mutation response has a hard causality contract: its
+committed application effects must already be readable from the configured
+upstream `/changes` feed before the application worker returns. The sync host
+then ingests through those effects, journals the acknowledged LMID after them,
+and only then returns the push response. This keeps every capped change-log
+prefix ordered so an acknowledgement cannot reach a client before its effects.
+Chat and Soot use an application-to-data service path that provides this
+ordering today. A future topology that cannot provide it must extend the
+delegated response with an upstream watermark receipt and make the host ingest
+through that receipt before finalization. Do not add a second best-effort path.
+The ordering does not add another ingest round: delegated pushes already waited
+for post-mutation ingest before returning, and now finalize after that wait.
 
 ## Counter and HTTP wire representation
 
@@ -212,4 +322,4 @@ absent when the cleanup command was run (Cloudflare returned error 10090), so no
 old probe service remains to receive traffic.
 
 The rust toolchain is pinned at the workspace root in
-[rust-toolchain.toml](/Users/n8/.worktrees/orez-rust-sync/rust-toolchain.toml).
+[`rust-toolchain.toml`](../../rust-toolchain.toml).

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

@@ -0,0 +1 @@
+export {};

package/dist/bun-wasm-loader.js

@@ -0,0 +1,20 @@
+import { Buffer } from 'node:buffer';
+import { fileURLToPath } from 'node:url';
+import { file, plugin } from 'bun';
+const wasmModuleID = 'orez-sync-cf-host/wasm-module.wasm';
+const wasmModulePath = fileURLToPath(import.meta.resolve(wasmModuleID));
+plugin({
+    name: 'orez-sync-cf-host-wasm',
+    setup(build) {
+        build.onResolve({ filter: /^orez-sync-cf-host\/wasm-module\.wasm$/ }, () => ({
+            path: wasmModulePath,
+        }));
+        build.onLoad({ filter: /sync_wasm_bg\.wasm$/ }, async ({ path }) => {
+            const bytes = Buffer.from(await file(path).arrayBuffer()).toString('base64');
+            return {
+                contents: `export default new WebAssembly.Module(Uint8Array.fromBase64('${bytes}'))`,
+                loader: 'js',
+            };
+        });
+    },
+});

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { PullCaps, SyncHostConfig, SyncHostEnv } from './types.js';
+export declare function validatePullCaps(caps: PullCaps): PullCaps;
+export declare function validateSyncHostConfig<Env extends SyncHostEnv>(config: SyncHostConfig<Env>): SyncHostConfig<Env>;

package/dist/config.js

@@ -0,0 +1,93 @@
+export function validatePullCaps(caps) {
+    if (!Number.isSafeInteger(caps.maxChangeRows) || caps.maxChangeRows < 1) {
+        throw new TypeError('caps.maxChangeRows must be a positive safe integer');
+    }
+    return caps;
+}
+export function validateSyncHostConfig(config) {
+    if (typeof config.authorizeWake !== 'function') {
+        throw new TypeError('sync host config authorizeWake is required');
+    }
+    if (typeof config.authorizeNotify !== 'function') {
+        throw new TypeError('sync host config authorizeNotify is required');
+    }
+    const hasMutators = config.mutators !== undefined;
+    const hasDelegate = config.mutateUrl !== undefined;
+    if (hasMutators === hasDelegate) {
+        throw new TypeError('sync host config requires exactly one of mutators or mutateUrl');
+    }
+    if (hasDelegate && !config.upstream) {
+        throw new TypeError('sync host config mutateUrl requires upstream');
+    }
+    if (config.mutateBinding !== undefined && !hasDelegate) {
+        throw new TypeError('sync host config mutateBinding requires mutateUrl');
+    }
+    if (config.mutateOrigin !== undefined && !hasDelegate) {
+        throw new TypeError('sync host config mutateOrigin requires mutateUrl');
+    }
+    if (config.delegatedPushRetry !== undefined && !hasDelegate) {
+        throw new TypeError('sync host config delegatedPushRetry requires mutateUrl');
+    }
+    if (config.mutateBinding !== undefined && !config.mutateBinding) {
+        throw new TypeError('sync host config mutateBinding must not be empty');
+    }
+    if (hasMutators && config.upstream) {
+        throw new TypeError('sync host config cannot combine local mutators with upstream ingest');
+    }
+    if (config.mutateUrl && !config.mutateUrl.startsWith('/')) {
+        throw new TypeError('mutateUrl must be an absolute path');
+    }
+    if (config.mutateOrigin !== undefined) {
+        let origin;
+        try {
+            origin = new URL(config.mutateOrigin);
+        }
+        catch {
+            throw new TypeError('mutateOrigin must be an absolute http(s) origin');
+        }
+        if ((origin.protocol !== 'http:' && origin.protocol !== 'https:') ||
+            origin.origin !== config.mutateOrigin) {
+            throw new TypeError('mutateOrigin must be an absolute http(s) origin');
+        }
+    }
+    if (config.upstream) {
+        if (!config.upstream.binding)
+            throw new TypeError('upstream.binding is required');
+        const limit = config.upstream.changeLimit ?? 1_000;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 10_000) {
+            throw new TypeError('upstream.changeLimit must be a safe integer in 1..10000');
+        }
+        const interval = config.upstream.intervalMs ?? 15_000;
+        if (!Number.isSafeInteger(interval) || interval < 1_000) {
+            throw new TypeError('upstream.intervalMs must be a safe integer >= 1000');
+        }
+        for (const [name, value] of Object.entries({
+            ingestBudgetRows: config.upstream.ingestBudgetRows ?? 150_000,
+            ingestBudgetWindowMs: config.upstream.ingestBudgetWindowMs ?? 300_000,
+            ingestBackoffMs: config.upstream.ingestBackoffMs ?? 1_000,
+            ingestMaxBackoffMs: config.upstream.ingestMaxBackoffMs ?? 60_000,
+        })) {
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new TypeError(`upstream.${name} must be a positive safe integer`);
+        }
+    }
+    if (config.delegatedPushRetry) {
+        for (const [name, value] of Object.entries({
+            maxAttempts: config.delegatedPushRetry.maxAttempts ?? 3,
+            initialBackoffMs: config.delegatedPushRetry.initialBackoffMs ?? 100,
+            maxBackoffMs: config.delegatedPushRetry.maxBackoffMs ?? 1_000,
+            timeoutMs: config.delegatedPushRetry.timeoutMs ?? 5_000,
+        })) {
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new TypeError(`delegatedPushRetry.${name} must be a positive safe integer`);
+        }
+    }
+    if (config.transactionQueryBudget) {
+        for (const [name, value] of Object.entries(config.transactionQueryBudget)) {
+            if (!Number.isSafeInteger(value) || Number(value) < 1) {
+                throw new TypeError(`transactionQueryBudget.${name} must be a positive safe integer`);
+            }
+        }
+    }
+    return config;
+}

package/{src → dist}/generated/sync_wasm.d.ts

@@ -37,7 +37,7 @@ export function engine_begin_snapshot_generation(db: any, schema: any, start_wat
  * Compile a validated Zero query AST for a consumer mutator's transactional
  * `tx.run(...)`. Execution remains in the host-owned application transaction.
  */
-export function engine_compile_query(schema: any, ast: any): any;
+export function engine_compile_query(schema: any, ast: any, format: any): any;
 
 export function engine_finalize(db: any, client_group_id: string, client_id: string, mutation_id: string): void;
 
@@ -109,7 +109,7 @@ export interface InitOutput {
     readonly engine_apply_upstream_snapshot: (a: any, b: any, c: any) => [number, number, number];
     readonly engine_assemble_push_response: (a: any) => [number, number, number];
     readonly engine_begin_snapshot_generation: (a: any, b: any, c: number, d: number) => [number, number, number];
-    readonly engine_compile_query: (a: any, b: any) => [number, number, number];
+    readonly engine_compile_query: (a: any, b: any, c: any) => [number, number, number];
     readonly engine_finalize: (a: any, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     readonly engine_finalize_snapshot_generation: (a: any, b: any, c: number, d: number, e: number, f: number) => [number, number, number];
     readonly engine_handle_pull: (a: any, b: any, c: any, d: any, e: number, f: number, g: any, h: number, i: number) => [number, number, number];

package/{src → dist}/generated/sync_wasm.js

@@ -111,10 +111,11 @@ export function engine_begin_snapshot_generation(db, schema, start_watermark) {
  * `tx.run(...)`. Execution remains in the host-owned application transaction.
  * @param {any} schema
  * @param {any} ast
+ * @param {any} format
  * @returns {any}
  */
-export function engine_compile_query(schema, ast) {
-    const ret = wasm.engine_compile_query(schema, ast);
+export function engine_compile_query(schema, ast, format) {
+    const ret = wasm.engine_compile_query(schema, ast, format);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }

package/dist/host.d.ts

@@ -0,0 +1,12 @@
+import { DurableObject } from 'cloudflare:workers';
+import type { SyncHostConfig, SyncHostEnv } from './types.js';
+/**
+ * Create the consumer-facing Worker router. Authentication happens here; the
+ * Durable Object receives only normalized claims over a binding-private header.
+ */
+export declare function createSyncWorker<Env extends SyncHostEnv>(config: SyncHostConfig<Env>): ExportedHandler<Env>;
+export interface SyncDurableObjectConstructor<Env extends SyncHostEnv> {
+    new (ctx: DurableObjectState, env: Env): DurableObject<Env>;
+}
+/** Create the namespace Durable Object class for one bundled consumer config. */
+export declare function createSyncDurableObject<Env extends SyncHostEnv>(config: SyncHostConfig<Env>): SyncDurableObjectConstructor<Env>;