orez-sync-cf-host 0.5.19 → 0.5.20

package/README.md

@@ -24,12 +24,33 @@ paths.
 Transaction-query `ILIKE` folding is ASCII-only on Durable Object SQLite;
 non-ASCII case pairs can diverge from PostgreSQL.
 
-### Bun query compiler
+### Query compiler runtimes
 
-Wrangler loads the engine's `.wasm` import as a precompiled
-`WebAssembly.Module`. Bun consumers of `createQueryCompiler` must register the
-package loader so the same import has the same value without changing the
-compiler code:
+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
@@ -38,7 +59,29 @@ 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 naming this preload when Bun resolves the `.wasm` import as a pathname.
+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
 

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/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>;