@absolutejs/sync 1.7.6 → 1.7.8

package/dist/engine/mutation.d.ts

@@ -45,6 +45,28 @@ export type MutationActions = {
     delete: (table: string, row: unknown) => Promise<void>;
     /** Escape hatch: emit a change you persisted yourself (no writer call). */
     change: <T>(collection: string, change: RowChange<T>) => Promise<void>;
+    /**
+     * Wall-clock timestamp the handler should use instead of `Date.now()`.
+     * Returns a `number` (ms since epoch).
+     *
+     * Why an injected clock? Two forward-looking reasons:
+     *
+     *   1. **Replay / rebase determinism.** When the engine re-runs a
+     *      mutation against an updated state (Replicache-style mutator
+     *      replay), `actions.now()` returns the ORIGINAL call's timestamp
+     *      instead of the current wall clock. `Date.now()` would silently
+     *      diverge between client-optimistic and server-canonical runs;
+     *      `actions.now()` doesn't.
+     *
+     *   2. **Test determinism.** Test harnesses can pin time by passing a
+     *      custom `now()` through {@link MutationActions} — the handler
+     *      observes whatever the test wants.
+     *
+     * If the engine doesn't override it (the common case today), it just
+     * returns `Date.now()`. Use it everywhere you'd reach for
+     * `Date.now()` inside a mutation handler.
+     */
+    now: () => number;
 };
 export type MutationHandler<Args, Ctx, Result> = (args: Args, ctx: Ctx, actions: MutationActions) => Promise<Result> | Result;
 export type MutationDefinition<Args = unknown, Ctx = CollectionContext, Result = unknown> = {

package/dist/engine/sandbox.d.ts

@@ -91,6 +91,66 @@ export type HandlerMetricsRecord = {
  * crashes must NOT also crash the caller's mutation path).
  */
 export type HandlerMetricsHook = (record: HandlerMetricsRecord) => void | Promise<void>;
+/**
+ * Per-host configuration for an entry in {@link BridgeFetchConfig}.
+ * Auth is computed on the host side per call; the secret never enters
+ * the sandbox's JSC heap.
+ */
+export type BridgeFetchEndpoint = {
+    /**
+     * Header values to add to every request to this host. Static — read
+     * once at engine construction. Use {@link authorization} for tokens
+     * that need to be computed per call.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Compute the `Authorization` header value on each call. Synchronous
+     * or async. Throwing rejects the in-sandbox call without revealing
+     * the underlying error (the sandbox sees a generic
+     * "authorization callback failed").
+     */
+    authorization?: () => string | Promise<string>;
+};
+/**
+ * `actions.fetch(url, init)` allowlist + auth-injection config keyed by
+ * hostname. A request whose URL parses to a hostname NOT in this map is
+ * rejected before any network call. A request whose hostname IS in the
+ * map gets the configured static headers + the computed authorization
+ * stitched in on the host side. The sandbox source never sees the auth
+ * value.
+ *
+ * Hostname keys are exact (`'api.example.com'`). The special key `'*'`
+ * is a wildcard (use sparingly — it disables allowlisting).
+ *
+ * ```ts
+ * createSyncEngine({
+ *   bridgeFetch: {
+ *     'api.stripe.com': {
+ *       authorization: () => `Bearer ${process.env.STRIPE_KEY}`,
+ *     },
+ *     'api.openai.com': {
+ *       authorization: () => `Bearer ${process.env.OPENAI_KEY}`,
+ *       headers: { 'OpenAI-Beta': 'assistants=v2' },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export type BridgeFetchConfig = Record<string, BridgeFetchEndpoint>;
+/**
+ * Response shape `actions.fetch` resolves to inside the sandbox. The
+ * body is materialised as text on the host (so it crosses the JSC
+ * boundary as a structured-cloned string). Users parse it themselves
+ * with `JSON.parse(res.body)` for JSON responses.
+ */
+export type BridgeFetchResponse = {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+};
 /** Per-mutation sandbox configuration. */
 export type SandboxConfig = {
     /** Heap memory cap (MB). Default 32. */
@@ -129,15 +189,16 @@ export type SandboxConfig = {
  */
 export declare const makeSandboxedHandler: (source: string, config?: SandboxConfig, 
 /**
- * Optional hook + tagging. When `onMetrics` is supplied, every call
- * uses `callable.callWithMetrics` (slightly costlier) and fires the
- * hook on completion. Without it, the cheap `callable.call` path is
- * used and nothing changes vs the pre-1.7.6 contract.
- *
- * `mutationName` only matters when `onMetrics` is set — it's the
- * `mutationName` field of the emitted record.
+ * Engine-level extras the per-mutation config doesn't carry:
+ *  - `metricsHook` enables per-call telemetry via
+ *    `callable.callWithMetrics` (small cost; off without the hook).
+ *  - `bridgeFetch` enables `actions.fetch(url, init)` inside the
+ *    sandbox with host-side allowlist + auth injection.
  */
-metricsHook?: {
-    mutationName: string;
-    onMetrics: HandlerMetricsHook;
+engineExtras?: {
+    metricsHook?: {
+        mutationName: string;
+        onMetrics: HandlerMetricsHook;
+    };
+    bridgeFetch?: BridgeFetchConfig;
 }) => ((args: unknown, ctx: unknown, actions: MutationActions) => Promise<unknown>);

package/dist/engine/syncEngine.d.ts

@@ -2,7 +2,7 @@ import type { CollectionContext, CollectionDefinition, JoinCollectionDefinition
 import type { GraphCollectionDefinition } from './graph';
 import type { MutationDefinition, TableWriter, TransactionRunner } from './mutation';
 import type { ReactiveQueryDefinition, TableReader } from './reactive';
-import { type HandlerMetricsHook } from './sandbox';
+import { type BridgeFetchConfig, type HandlerMetricsHook } from './sandbox';
 import type { PermissionsDefinition, TablePermissions } from './permissions';
 import type { SearchCollectionDefinition } from './search';
 import type { ScheduleDefinition } from './schedule';
@@ -326,6 +326,21 @@ export type SyncEngineOptions = {
      * @see {@link HandlerMetricsRecord}
      */
     handlerMetrics?: HandlerMetricsHook;
+    /**
+     * Allowlist + auth-injection map for `actions.fetch(url, init)` calls
+     * issued from inside a `sandboxedHandler`. Each entry is keyed by
+     * hostname (`'api.stripe.com'`); the value's `authorization` is a
+     * sync or async callback computed on the host so the secret never
+     * crosses into the JSC sandbox. Requests to non-allowlisted hosts
+     * are rejected before any network call.
+     *
+     * Without this set, `actions.fetch` throws "no bridgeFetch config."
+     * Plain (non-sandboxed) handlers don't use this — they can just call
+     * `fetch` directly since they run in the host process.
+     *
+     * @see {@link BridgeFetchConfig}
+     */
+    bridgeFetch?: BridgeFetchConfig;
 };
 /**
  * The Tier 3 sync engine: a registry of collections plus the view syncer. It is

package/dist/index.js

@@ -737,12 +737,14 @@ var wrap = (source) => `
 			insert: (table, data) => __dispatch(__callId, 'insert', table, data),
 			update: (table, data) => __dispatch(__callId, 'update', table, data),
 			delete: (table, row) => __dispatch(__callId, 'delete', table, row),
-			change: (collection, change) => __dispatch(__callId, 'change', collection, change)
+			change: (collection, change) => __dispatch(__callId, 'change', collection, change),
+			now: () => __dispatch(__callId, 'now'),
+			fetch: (url, init) => __dispatch(__callId, 'fetch', url, init)
 		};
 		return userFn(args, ctx, actions);
 	}
 `;
-var compile = async (source, config) => {
+var compile = async (source, config, bridgeFetch) => {
   const { createIsolate, Reference } = await loadIsolatedJsc();
   const isolate = await createIsolate({
     backend: config.backend ?? "auto",
@@ -764,6 +766,10 @@ var compile = async (source, config) => {
         return a.delete(rest[0], rest[1]);
       case "change":
         return a.change(rest[0], rest[1]);
+      case "now":
+        return a.now();
+      case "fetch":
+        return runBridgeFetch(bridgeFetch, rest[0], rest[1]);
       default:
         throw new Error(`unknown sandbox action op: ${String(op)}`);
     }
@@ -779,8 +785,57 @@ var compile = async (source, config) => {
     timeoutMs: config.timeout ?? 5000
   };
 };
-var makeSandboxedHandler = (source, config = {}, metricsHook) => {
+var runBridgeFetch = async (config, url, init) => {
+  if (config === undefined) {
+    throw new Error("actions.fetch called but the engine has no `bridgeFetch` config \u2014 " + "pass `bridgeFetch: { ... }` to createSyncEngine.");
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`actions.fetch: invalid URL "${String(url)}"`);
+  }
+  const endpoint = config[parsed.hostname] ?? (Object.prototype.hasOwnProperty.call(config, "*") ? config["*"] : undefined);
+  if (endpoint === undefined) {
+    throw new Error(`actions.fetch: hostname "${parsed.hostname}" is not allowlisted in bridgeFetch config`);
+  }
+  const headers = { ...endpoint.headers ?? {} };
+  if (init?.headers !== undefined) {
+    const incoming = init.headers;
+    for (const [name, value] of Object.entries(incoming)) {
+      if (name.toLowerCase() === "authorization")
+        continue;
+      headers[name] = value;
+    }
+  }
+  if (endpoint.authorization !== undefined) {
+    let auth;
+    try {
+      auth = await endpoint.authorization();
+    } catch {
+      throw new Error("actions.fetch: authorization callback failed");
+    }
+    headers.Authorization = auth;
+  }
+  const response = await fetch(url, { ...init, headers });
+  const responseHeaders = {};
+  response.headers.forEach((value, name) => {
+    responseHeaders[name] = value;
+  });
+  const body = await response.text();
+  return {
+    body,
+    headers: responseHeaders,
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    url: response.url
+  };
+};
+var makeSandboxedHandler = (source, config = {}, engineExtras) => {
   let pending;
+  const metricsHook = engineExtras?.metricsHook;
+  const bridgeFetch = engineExtras?.bridgeFetch;
   const getCompiled = async () => {
     if (pending !== undefined) {
       const compiled = await pending;
@@ -788,7 +843,7 @@ var makeSandboxedHandler = (source, config = {}, metricsHook) => {
         return compiled;
       pending = undefined;
     }
-    pending = compile(source, config);
+    pending = compile(source, config, bridgeFetch);
     return pending;
   };
   return async (args, ctx, actions) => {
@@ -1286,7 +1341,8 @@ var createSyncEngine = (options = {}) => {
         }
         await writerFor(table).delete(row, ctx, tx);
         buffered.push({ table, change: { op: "delete", row } });
-      }
+      },
+      now: () => Date.now()
     };
     return { actions, buffered };
   };
@@ -1843,9 +1899,12 @@ var createSyncEngine = (options = {}) => {
       }
       mutations.set(mutation.name, mutation);
       if (mutation.sandboxedHandler !== undefined) {
-        sandboxRunners.set(mutation.name, makeSandboxedHandler(mutation.sandboxedHandler, mutation.sandbox, options.handlerMetrics === undefined ? undefined : {
-          mutationName: mutation.name,
-          onMetrics: options.handlerMetrics
+        sandboxRunners.set(mutation.name, makeSandboxedHandler(mutation.sandboxedHandler, mutation.sandbox, {
+          bridgeFetch: options.bridgeFetch,
+          metricsHook: options.handlerMetrics === undefined ? undefined : {
+            mutationName: mutation.name,
+            onMetrics: options.handlerMetrics
+          }
         }));
       }
     },
@@ -2370,5 +2429,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=9570274420A04D4164756E2164756E21
+//# debugId=29525303DD4B75D864756E2164756E21
 //# sourceMappingURL=index.js.map