@absolutejs/sync 1.11.0 → 1.12.1

package/dist/engine/sandbox.d.ts

@@ -171,6 +171,52 @@ export type SandboxConfig = {
      * reachable (e.g. CI with a known image).
      */
     backend?: 'auto' | 'ffi' | 'worker';
+    /**
+     * **Escape hatch.** Map of host functions the sandboxed handler may
+     * call as `unsafeHost.fnName(...args)`. The name is deliberately
+     * loud: anyone reading the source must see immediately that a
+     * sandboxed mutation is reaching through to non-deterministic host
+     * code (third-party API, queue push, email send, anything that
+     * touches the outside world).
+     *
+     * Without this option, the sandbox is hermetic — only `args`,
+     * `ctx`, and `actions` are reachable. Declare an entry here, name
+     * it visibly (e.g. `chargeStripe`, `sendSlackPing`), and the engine
+     * exposes it on the sandbox-side `unsafeHost` Proxy. The fn runs on
+     * the host; its return value is structured-cloned back across the
+     * isolate boundary; thrown errors propagate into the sandbox as
+     * normal JS errors the handler can catch.
+     *
+     * The deterministic-mutation guarantees stop at the call site —
+     * retries WILL re-fire these host fns (they're outside the
+     * transaction). Treat them as side effects and either make them
+     * idempotent or pair them with explicit compensation in the
+     * handler. Convex's actions are the same model; this is the same
+     * trade.
+     *
+     * @example
+     * ```ts
+     * defineMutation({
+     *   name: 'payments:checkout',
+     *   sandboxedHandler: `async (args, ctx, actions, unsafeHost) => {
+     *     const order = await actions.insert('orders', { ...args, status: 'pending' });
+     *     const receipt = await unsafeHost.chargeStripe({
+     *       amount: order.amount,
+     *       token: args.token,
+     *     });
+     *     await actions.update('orders', { id: order.id, status: 'paid', receipt });
+     *     return order;
+     *   }`,
+     *   sandbox: {
+     *     unsafeHost: {
+     *       chargeStripe: ({ amount, token }) =>
+     *         stripe.charges.create({ amount, source: token }),
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    unsafeHost?: Record<string, (...args: any[]) => unknown | Promise<unknown>>;
 };
 /**
  * Build a lazy runner for one mutation's sandboxed source. The first call

package/dist/index.js

@@ -179,7 +179,8 @@ var sync = ({
     headers: {
       "cache-control": "no-cache, no-transform",
       connection: "keep-alive",
-      "content-type": "text/event-stream"
+      "content-type": "text/event-stream",
+      "x-accel-buffering": "no"
     }
   });
 });
@@ -740,7 +741,7 @@ var wrap = (source) => `
 		const userFn = (${source});
 		if (typeof userFn !== 'function') {
 			throw new Error(
-				'sandboxedHandler must evaluate to (args, ctx, actions) => result; got ' +
+				'sandboxedHandler must evaluate to (args, ctx, actions, unsafeHost) => result; got ' +
 					typeof userFn
 			);
 		}
@@ -752,12 +753,24 @@ var wrap = (source) => `
 			now: () => __dispatch(__callId, 'now'),
 			fetch: (url, init) => __dispatch(__callId, 'fetch', url, init)
 		};
-		return userFn(args, ctx, actions);
+		// Escape hatch \u2014 host fns the mutation explicitly opted in to.
+		// The Proxy means every property access is a host call; the
+		// engine throws if the property name isn't declared in the
+		// mutation's sandbox.unsafeHost map.
+		const unsafeHost = new Proxy({}, {
+			get: (_target, fnName) => {
+				if (typeof fnName !== 'string') return undefined;
+				return (...callArgs) =>
+					__dispatch(__callId, 'unsafeHost', fnName, callArgs);
+			}
+		});
+		return userFn(args, ctx, actions, unsafeHost);
 	}
 `;
 var compile = async (source, config, bridgeFetch) => {
   const { Reference, createIsolatedRunner, resolveIsolatePolicy } = await loadIsolatedJsc();
   const callMap = new Map;
+  const unsafeHost = config.unsafeHost;
   const dispatch = new Reference((callId, op, ...rest) => {
     const a = callMap.get(callId);
     if (a === undefined) {
@@ -776,6 +789,14 @@ var compile = async (source, config, bridgeFetch) => {
         return a.now();
       case "fetch":
         return runBridgeFetch(bridgeFetch, rest[0], rest[1]);
+      case "unsafeHost": {
+        const fnName = rest[0];
+        const callArgs = rest[1] ?? [];
+        if (unsafeHost === undefined || typeof unsafeHost[fnName] !== "function") {
+          throw new Error(`sandboxedHandler called unsafeHost.${fnName}() but it was not declared in the mutation's sandbox.unsafeHost config. Declare it (and only the host fns you intend to expose) to opt in to the escape hatch.`);
+        }
+        return unsafeHost[fnName](...callArgs);
+      }
       default:
         throw new Error(`unknown sandbox action op: ${String(op)}`);
     }
@@ -2478,7 +2499,8 @@ var syncCdc = ({
       headers: {
         "cache-control": "no-cache, no-transform",
         connection: "keep-alive",
-        "content-type": "text/event-stream"
+        "content-type": "text/event-stream",
+        "x-accel-buffering": "no"
       }
     });
   });
@@ -2593,7 +2615,8 @@ data: ${JSON.stringify(event)}
       headers: {
         "cache-control": "no-cache, no-transform",
         connection: "keep-alive",
-        "content-type": "text/event-stream"
+        "content-type": "text/event-stream",
+        "x-accel-buffering": "no"
       }
     });
   });
@@ -2675,5 +2698,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=FFB4969DBBAB620C64756E2164756E21
+//# debugId=D6679B754081BCC764756E2164756E21
 //# sourceMappingURL=index.js.map