orez-sync-cf-host 0.10.7 → 0.11.0

package/dist/host.js

@@ -2,6 +2,7 @@ import { DurableObject } from 'cloudflare:workers';
 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 { IngestBreakerError, IngestCircuitBreaker, retryDelayMs, shouldRetryDelegatedPush, } from './write-safeguards.js';
@@ -344,7 +345,7 @@ export function createSyncDurableObject(config) {
                         this.#ingestBreaker.restore(ingestBreakerReason, Number(this.#controlGet('ingestBreakerRetryAt')), Number(this.#controlGet('ingestBreakerTrips')));
                     }
                     this.#wasm(() => engine_init_schema(this.#engineDb, config.schema));
-                    if (config.queryAware || config.resolveQuery)
+                    if (config.queryAware || config.resolveQueries)
                         this.#wasm(() => engine_init_query_schema(this.#engineDb));
                 });
             });
@@ -952,7 +953,7 @@ export function createSyncDurableObject(config) {
                 const queryAware = this.#queryAwareOverride() ??
                     (typeof config.queryAware === 'function'
                         ? config.queryAware(claims)
-                        : (config.queryAware ?? Boolean(config.resolveQuery)));
+                        : (config.queryAware ?? Boolean(config.resolveQueries)));
                 const transformVersion = queryAware
                     ? typeof config.queryTransformVersion === 'function'
                         ? config.queryTransformVersion(claims)
@@ -961,7 +962,16 @@ export function createSyncDurableObject(config) {
                 if (!Number.isSafeInteger(transformVersion) || transformVersion < 0) {
                     throw new TypeError('queryTransformVersion must be a non-negative safe integer');
                 }
-                const releaseQueryPull = queryAware && config.resolveQuery
+                // The group lock exists to keep two desired-query patches from being
+                // applied out of arrival order when one of them is slow to resolve.
+                // A pull carrying no patch applies nothing, and it reads membership
+                // inside transactionSync, which is already atomic against whichever
+                // patch commits around it. Holding the lock for those pulls only makes
+                // an unchanged warm pull wait out somebody else's query-resolution round
+                // trip to the application, which is the head-of-line blocking behind
+                // the pull tail: a client polls far more often than it changes what it
+                // wants, so almost every pull in flight is patch-free.
+                const releaseQueryPull = queryAware && config.resolveQueries && body.queries
                     ? await this.#acquireQueryPullLock(typeof body.clientGroupID === 'string' ? body.clientGroupID : '')
                     : null;
                 let response;
@@ -969,43 +979,12 @@ export function createSyncDurableObject(config) {
                     if (queryAware && body.queries) {
                         const queries = body.queries;
                         if (Array.isArray(queries.patch)) {
-                            const patch = [];
-                            for (const operation of queries.patch) {
-                                if (!operation || typeof operation !== 'object') {
-                                    patch.push(operation);
-                                    continue;
-                                }
-                                const op = operation;
-                                if (op.op === 'put') {
-                                    if (!config.resolveQuery || typeof op.name !== 'string') {
-                                        throw requestError('query put requires a server-resolved named query');
-                                    }
-                                    if (!Array.isArray(op.args)) {
-                                        throw requestError('named query args must be an array');
-                                    }
-                                    const args = op.args;
-                                    let ast;
-                                    try {
-                                        // resolveQuery may be async and needs `env` (a consumer can
-                                        // delegate the transform to its app's real synced-queries
-                                        // endpoint over an app service binding — authenticate runs in the
-                                        // worker isolate, but the query loop runs here in the DO, so the
-                                        // binding must come from the DO's own env, not a shared global).
-                                        ast = await config.resolveQuery(op.name, args, claims, this.env);
-                                    }
-                                    catch (error) {
-                                        throw requestError(`unknown or unsupported named query: ${op.name}`);
-                                    }
-                                    patch.push({
-                                        op: 'put',
-                                        hash: op.hash,
-                                        ast,
-                                        transformVersion,
-                                    });
-                                }
-                                else
-                                    patch.push(operation);
-                            }
+                            // resolveQueries may be async and needs `env` (a consumer can
+                            // delegate the transform to its app's real synced-queries
+                            // endpoint over an app service binding — authenticate runs in the
+                            // worker isolate, but the query loop runs here in the DO, so the
+                            // binding must come from the DO's own env, not a shared global).
+                            const patch = await resolveQueryPatch(queries.patch, (requests) => config.resolveQueries(requests, claims, this.env), transformVersion, requestError);
                             body = { ...body, queries: { ...queries, patch } };
                         }
                     }

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { createSyncDurableObject, createSyncWorker } from './host.js';
 export { createQueryCompiler } from './query-compiler.js';
+export { resolveQueryPatch } from './query-patch.js';
 export { visibility } from './types.js';
 export { DEFAULT_TRANSACTION_QUERY_BUDGET, TransactionQueryBudgetError, executeTransactionQueryPlan, executeTransactionQueryPlanAsync, } from './transaction-query.js';
-export type { PullCaps, QueryResolver, SyncHostConfig, SyncHostEnv, ServiceBinding, SyncSql, UpstreamConfig, VisibilityConfig, VisibilityExpression, VisibilityFilter, VisibilityOperand, VisibilityValue, } from './types.js';
+export type { PullCaps, QueryResolution, QueryResolutionRequest, QueryResolver, SyncHostConfig, SyncHostEnv, ServiceBinding, SyncSql, UpstreamConfig, VisibilityConfig, VisibilityExpression, VisibilityFilter, VisibilityOperand, VisibilityValue, } from './types.js';
 export type { SyncDurableObjectConstructor } from './host.js';
 export type { CompiledTransactionQueryNode, CompiledTransactionQueryPlan, CompiledTransactionQueryRelationship, TransactionQueryBinding, TransactionQueryBudget, TransactionQueryColumn, TransactionQueryColumnType, TransactionQueryExecutionOptions, TransactionQueryWireValue, } from './transaction-query.js';
 export type { TransactionQueryCompiler } from './query-compiler.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createSyncDurableObject, createSyncWorker } from './host.js';
 export { createQueryCompiler } from './query-compiler.js';
+export { resolveQueryPatch } from './query-patch.js';
 export { visibility } from './types.js';
 export { DEFAULT_TRANSACTION_QUERY_BUDGET, TransactionQueryBudgetError, executeTransactionQueryPlan, executeTransactionQueryPlanAsync, } from './transaction-query.js';

package/dist/query-patch.d.ts

@@ -0,0 +1,29 @@
+import type { JsonValue } from 'orez-sync-executor';
+export type QueryResolutionRequest = {
+    readonly name: string;
+    readonly args: readonly JsonValue[];
+};
+/**
+ * One resolved query, positionally matched to the request at the same index.
+ *
+ * An `error` fails only its own query rather than the whole patch, so a client
+ * that registers one unknown query alongside nine good ones is told which one
+ * is unknown.
+ */
+export type QueryResolution = {
+    readonly ast: JsonValue;
+} | {
+    readonly error: string;
+};
+/**
+ * Turn a client's desired-query patch into the resolved patch sync-core takes.
+ *
+ * Both hosts share this because both must agree on exactly one thing: how many
+ * times a consumer's resolver is called for one patch. Resolving per query made
+ * a pull cost one application round trip per registered query, each one
+ * re-authenticating, so a screen mounting eleven views paid eleven of them in
+ * series. Everything else here exists to make the single call safe: the patch
+ * keeps its order, duplicate (name, args) pairs collapse to one request and fan
+ * back out, and a resolver error names the query it came from.
+ */
+export declare function resolveQueryPatch(patch: readonly unknown[], resolve: (requests: readonly QueryResolutionRequest[]) => readonly QueryResolution[] | Promise<readonly QueryResolution[]>, transformVersion: number, fail: (message: string) => Error): Promise<unknown[]>;

package/dist/query-patch.js

@@ -0,0 +1,54 @@
+/**
+ * Turn a client's desired-query patch into the resolved patch sync-core takes.
+ *
+ * Both hosts share this because both must agree on exactly one thing: how many
+ * times a consumer's resolver is called for one patch. Resolving per query made
+ * a pull cost one application round trip per registered query, each one
+ * re-authenticating, so a screen mounting eleven views paid eleven of them in
+ * series. Everything else here exists to make the single call safe: the patch
+ * keeps its order, duplicate (name, args) pairs collapse to one request and fan
+ * back out, and a resolver error names the query it came from.
+ */
+export async function resolveQueryPatch(patch, resolve, transformVersion, fail) {
+    const puts = [];
+    const requests = [];
+    const requestByKey = new Map();
+    patch.forEach((operation, index) => {
+        if (!operation || typeof operation !== 'object')
+            return;
+        const op = operation;
+        if (op.op !== 'put')
+            return;
+        if (typeof op.name !== 'string') {
+            throw fail('query put requires a server-resolved named query');
+        }
+        if (!Array.isArray(op.args))
+            throw fail('named query args must be an array');
+        const key = JSON.stringify([op.name, op.args]);
+        if (!requestByKey.has(key)) {
+            requestByKey.set(key, requests.length);
+            requests.push({ name: op.name, args: op.args });
+        }
+        puts.push({ index, key, name: op.name, hash: op.hash });
+    });
+    if (puts.length === 0)
+        return [...patch];
+    const resolved = await resolve(requests);
+    if (resolved.length !== requests.length) {
+        throw new Error(`query resolver returned ${resolved.length} results for ${requests.length} queries`);
+    }
+    const result = [...patch];
+    for (const put of puts) {
+        const resolution = resolved[requestByKey.get(put.key)];
+        if (!resolution || 'error' in resolution) {
+            throw fail(`unknown or unsupported named query: ${put.name}`);
+        }
+        result[put.index] = {
+            op: 'put',
+            hash: put.hash,
+            ast: resolution.ast,
+            transformVersion,
+        };
+    }
+    return result;
+}

package/dist/types.d.ts

@@ -1,13 +1,28 @@
+import type { QueryResolution, QueryResolutionRequest } from './query-patch.js';
 import type { TransactionQueryBudget } from './transaction-query.js';
 import type { Schema } from '@rocicorp/zero';
-import type { ExecResult, JsonValue, MutatorRegistry, NormalizedClaims, SqlStatementMetadata, VisibilityConfig } from 'orez-sync-executor';
+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';
+export type { QueryResolution, QueryResolutionRequest } from './query-patch.js';
 export interface SyncSql {
     exec(sql: string, params?: readonly unknown[], metadata?: SqlStatementMetadata): ExecResult;
     query<Row extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Row[];
 }
-export type QueryResolver = (name: string, args: readonly JsonValue[], claims: NormalizedClaims, env: SyncHostEnv) => JsonValue | Promise<JsonValue>;
+/**
+ * Resolve a whole desired-query patch in one call.
+ *
+ * This is a batch contract because it is nearly always a network call: a
+ * consumer delegates the transform to its application, which authenticates and
+ * answers over a service binding. Resolving one query per call made a pull's
+ * cost linear in the number of queries a screen registers, and each round trip
+ * re-authenticated. Measured against production with a captured mobile client's
+ * desired-query set: an 11-query pull took 23.3 s against 2.0 s for the same
+ * pull carrying no queries.
+ *
+ * Implementations must return exactly one entry per request, in request order.
+ */
+export type QueryResolver = (requests: readonly QueryResolutionRequest[], claims: NormalizedClaims, env: SyncHostEnv) => readonly QueryResolution[] | Promise<readonly QueryResolution[]>;
 export type PullCaps = {
     maxChangeRows: number;
     maxChangeBytes: number;
@@ -85,7 +100,8 @@ export type SyncHostConfig<Env extends SyncHostEnv = SyncHostEnv, S extends Sche
     /** Enable desired-query pulls for this namespace and resolve named queries
      * into validated Zero ASTs before they reach sync-core. */
     queryAware?: boolean | ((claims: NormalizedClaims) => boolean);
-    resolveQuery?: QueryResolver;
+    /** Resolve every named query in one desired-query patch, in one call. */
+    resolveQueries?: QueryResolver;
     /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez-sync-cf-host",
-  "version": "0.10.7",
+  "version": "0.11.0",
   "type": "module",
   "exports": {
     ".": {
@@ -19,6 +19,10 @@
       "types": "./dist/query-compiler.d.ts",
       "import": "./dist/query-compiler.js"
     },
+    "./query-patch": {
+      "types": "./dist/query-patch.d.ts",
+      "import": "./dist/query-patch.js"
+    },
     "./transaction-query": {
       "types": "./dist/transaction-query.d.ts",
       "import": "./dist/transaction-query.js"
@@ -56,7 +60,7 @@
     "typecheck": "bun run build:dist:platform && tsc --noEmit"
   },
   "dependencies": {
-    "orez-sync-executor": "0.10.7"
+    "orez-sync-executor": "0.11.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "4.20260617.1",