@nylorun/runtime 0.15.2-beta → 0.17.0-beta

package/dist/execution/memory.js

@@ -1,4 +1,4 @@
-import { WAKE_REASONS, sessionKey, } from "./types.js";
+import { DEFAULT_STOP_GRACE_MS, WAKE_REASONS, sessionKey, settleWithin, } from "./types.js";
 /**
  * In-process `DurableExecution`. Not durable: wakes, timers and sweeps live in
  * memory. It keeps the seam's ordering guarantees within one process, which is
@@ -11,18 +11,21 @@ export class MemoryExecution {
     seen = new Map();
     timers = new Map();
     sweeps = new Map();
+    sandboxes = new Map();
     delayed = new Set();
     inflight = new Set();
     sweepIntervalMs;
     retryDelayMs;
     maxAttempts;
     dedupeRetentionMs;
+    stopGraceMs;
     onError;
     constructor(options = {}) {
         this.sweepIntervalMs = options.sweepIntervalMs ?? 5000;
         this.retryDelayMs = options.retryDelayMs ?? 50;
         this.maxAttempts = options.maxAttempts ?? 5;
         this.dedupeRetentionMs = options.dedupeRetentionMs ?? 24 * 60 * 60_000;
+        this.stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS;
         this.onError =
             options.onError ??
                 ((error) => queueMicrotask(() => {
@@ -46,6 +49,66 @@ export class MemoryExecution {
     async deliver(tenantId, actionId) {
         this.enqueue("deliver", tenantId, actionId);
     }
+    async sandbox(tenantId, sandboxId, signal) {
+        const key = `${tenantId}\u0000${sandboxId}`;
+        let state = this.sandboxes.get(key);
+        if (!state)
+            this.sandboxes.set(key, (state = { tenantId, sandboxId, tail: Promise.resolve(), pending: [], attempts: 0, timers: new Map() }));
+        if (signal.kind === "arm")
+            this.armSandbox(state, signal.timer, signal.at);
+        else
+            this.runSandbox(state, "reconcile");
+    }
+    armSandbox(state, timer, at) {
+        const existing = state.timers.get(timer);
+        if (existing?.handle)
+            clearTimeout(existing.handle);
+        const entry = { at };
+        state.timers.set(timer, entry);
+        if (!this.handlers)
+            return;
+        entry.handle = setTimeout(() => {
+            if (state.timers.get(timer) !== entry)
+                return;
+            state.timers.delete(timer);
+            this.runSandbox(state, timer === "retry" ? "reconcile" : timer);
+        }, Math.max(0, at - Date.now()));
+    }
+    runSandbox(state, trigger) {
+        const handlers = this.handlers;
+        if (!handlers) {
+            state.pending.push(trigger);
+            return;
+        }
+        const run = state.tail.then(async () => {
+            if (!this.handlers)
+                return;
+            if (!handlers.sandbox) {
+                this.onError(new Error("WorkerHandlers.sandbox is required for sandbox reconciles"));
+                return;
+            }
+            const controller = new AbortController();
+            try {
+                const result = await handlers.sandbox(state.tenantId, state.sandboxId, trigger, controller.signal);
+                state.attempts = 0;
+                for (const item of result.arm ?? [])
+                    this.armSandbox(state, item.timer, item.at);
+                if (result.retryAfterMs !== undefined)
+                    this.armSandbox(state, "retry", Date.now() + Math.max(0, result.retryAfterMs));
+            }
+            catch (error) {
+                state.attempts += 1;
+                if (state.attempts >= this.maxAttempts) {
+                    state.attempts = 0;
+                    this.onError(error);
+                }
+                else
+                    this.armSandbox(state, "retry", Date.now() + this.retryDelayMs * 2 ** (state.attempts - 1));
+            }
+        });
+        state.tail = run.catch(() => undefined);
+        this.track(state.tail);
+    }
     async timer(tenantId, key, at) {
         const id = `${tenantId}\u0000${key}`;
         const existing = this.timers.get(id);
@@ -81,6 +144,12 @@ export class MemoryExecution {
             this.armTimer(id, timer);
         for (const [tenantId, sweep] of this.sweeps)
             this.scheduleSweep(tenantId, sweep, 0);
+        for (const state of this.sandboxes.values()) {
+            for (const [timer, entry] of state.timers)
+                this.armSandbox(state, timer, entry.at);
+            for (const trigger of state.pending.splice(0))
+                this.runSandbox(state, trigger);
+        }
     }
     async stop() {
         this.handlers = undefined;
@@ -93,10 +162,15 @@ export class MemoryExecution {
         for (const sweep of this.sweeps.values())
             if (sweep.handle)
                 clearTimeout(sweep.handle);
+        for (const state of this.sandboxes.values())
+            for (const entry of state.timers.values())
+                if (entry.handle)
+                    clearTimeout(entry.handle);
         for (const state of this.keys.values())
             state.controller?.abort();
-        while (this.inflight.size > 0)
-            await Promise.allSettled(this.inflight);
+        // Bounded: a handler that ignores its abort is abandoned and runs on unwaited. An
+        // abandoned advance's lease lapses and the next advance takes the session over (§11.4).
+        await settleWithin(this.inflight, this.stopGraceMs);
     }
     /**
      * Resolves once no advance or delivery is running or queued and no busy or

package/dist/execution/types.d.ts

@@ -37,6 +37,13 @@
  * - **Retry after `retry`.** A delivery that returns `retry` is run again for
  *   the same key after `retryAfterMs`. This is how an Action endpoint that is
  *   down or busy is retried; the handler throws only on infrastructure errors.
+ * - **One reconcile per sandbox at a time** (F7.2). `sandbox` runs
+ *   `WorkerHandlers.sandbox` for the key `<tenantId>:<sandboxId>` at least once
+ *   after a `reconcile` resolves, never overlapping another run for the key. A
+ *   run that answers `retryAfterMs` runs again after it (one pending retry per
+ *   key: a later one replaces it), and each timer it answers is armed. `arm`
+ *   sets one of the sandbox's timers (`idle`, `ttl`): setting it again replaces
+ *   the earlier time, and the run it causes is told which timer fired.
  */
 /** Why a session is woken (§12.3, "Where wakes come from"). */
 export type WakeReason = 
@@ -69,6 +76,28 @@ export type AdvanceResult = {
     status: "busy";
     retryAfterMs: number;
 };
+/** A pod sandbox's timers. */
+export type SandboxTimer = "idle" | "ttl";
+/** What `DurableExecution.sandbox` asks for: a reconcile, or a timer. */
+export type SandboxSignal = {
+    kind: "reconcile";
+} | {
+    kind: "arm";
+    timer: SandboxTimer;
+    at: number;
+};
+/** Why `WorkerHandlers.sandbox` runs. */
+export type SandboxTrigger = "reconcile" | SandboxTimer;
+/** What a sandbox reconcile asks for next. */
+export interface SandboxResult {
+    /** Run again this soon. */
+    retryAfterMs?: number;
+    /** Timers to set, at ms since the epoch. */
+    arm?: readonly {
+        timer: SandboxTimer;
+        at: number;
+    }[];
+}
 export type DeliverResult = {
     status: "done";
 }
@@ -94,6 +123,11 @@ export interface WorkerHandlers {
      * stops. Throw only on infrastructure errors. Required when `deliver` is used.
      */
     deliver?(tenantId: string, actionId: string, signal: AbortSignal): Promise<DeliverResult>;
+    /**
+     * Reconciles one pod sandbox (F7.2), serialized per sandbox. Throw only on infrastructure
+     * errors. Required when `sandbox` is used.
+     */
+    sandbox?(tenantId: string, sandboxId: string, trigger: SandboxTrigger, signal: AbortSignal): Promise<SandboxResult>;
 }
 export interface DurableExecution {
     /** At-least-once. `dedupeKey` merges repeated wakes for the same cause. */
@@ -110,13 +144,22 @@ export interface DurableExecution {
      * after the transaction that made the Action pending commits.
      */
     deliver(tenantId: string, actionId: string): Promise<void>;
+    /**
+     * A pod sandbox's reconcile, or one of its timers (F7.2): see "One reconcile per sandbox
+     * at a time". Absent where pods are not supported.
+     */
+    sandbox?(tenantId: string, sandboxId: string, signal: SandboxSignal): Promise<void>;
     /** Arms the Tenant's self-re-arming sweep. Idempotent. */
     armSweep(tenantId: string): Promise<void>;
     /** Stops re-arming the Tenant's sweep (Tenant deleted). A pass already running finishes. */
     disarmSweep(tenantId: string): Promise<void>;
     /** Starts delivering to `handlers` (serving the Worker endpoint, for Restate). */
     start(handlers: WorkerHandlers): Promise<void>;
-    /** Stops delivering, aborts running advances' signals and waits for them. */
+    /**
+     * Stops delivering, aborts running advances' signals and waits for them, up to the
+     * implementation's stop grace (`DEFAULT_STOP_GRACE_MS`). Handlers still running then are
+     * abandoned: their sessions' leases lapse and the next advance takes over (§11.4).
+     */
     stop(): Promise<void>;
     /**
      * Resolves when the backing service answers, rejects otherwise (readiness,
@@ -155,3 +198,13 @@ export declare function parseSessionKey(key: string): {
     tenantId: string;
     sessionId: string;
 };
+/**
+ * Default time `DurableExecution.stop` waits for running handlers after aborting them: the
+ * advance grace period (`DEFAULT_ADVANCE_GRACE_MS` in `tenant/worker.ts`).
+ */
+export declare const DEFAULT_STOP_GRACE_MS = 30000;
+/**
+ * Waits until `inflight` is empty (it shrinks as its promises settle and may grow meanwhile),
+ * for at most `graceMs`. Resolves to how many were still running when the grace ran out.
+ */
+export declare function settleWithin(inflight: ReadonlySet<Promise<unknown>>, graceMs: number): Promise<number>;

package/dist/execution/types.js

@@ -37,6 +37,13 @@
  * - **Retry after `retry`.** A delivery that returns `retry` is run again for
  *   the same key after `retryAfterMs`. This is how an Action endpoint that is
  *   down or busy is retried; the handler throws only on infrastructure errors.
+ * - **One reconcile per sandbox at a time** (F7.2). `sandbox` runs
+ *   `WorkerHandlers.sandbox` for the key `<tenantId>:<sandboxId>` at least once
+ *   after a `reconcile` resolves, never overlapping another run for the key. A
+ *   run that answers `retryAfterMs` runs again after it (one pending retry per
+ *   key: a later one replaces it), and each timer it answers is armed. `arm`
+ *   sets one of the sandbox's timers (`idle`, `ttl`): setting it again replaces
+ *   the earlier time, and the run it causes is told which timer fired.
  */
 export const WAKE_REASONS = [
     "message",
@@ -59,3 +66,27 @@ export function parseSessionKey(key) {
         throw new Error(`Invalid session key: ${key}`);
     return { tenantId: key.slice(0, at), sessionId: key.slice(at + 1) };
 }
+/**
+ * Default time `DurableExecution.stop` waits for running handlers after aborting them: the
+ * advance grace period (`DEFAULT_ADVANCE_GRACE_MS` in `tenant/worker.ts`).
+ */
+export const DEFAULT_STOP_GRACE_MS = 30_000;
+/**
+ * Waits until `inflight` is empty (it shrinks as its promises settle and may grow meanwhile),
+ * for at most `graceMs`. Resolves to how many were still running when the grace ran out.
+ */
+export async function settleWithin(inflight, graceMs) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("expired"), Math.max(0, graceMs));
+    });
+    try {
+        while (inflight.size > 0)
+            if ((await Promise.race([Promise.allSettled(inflight), expired])) === "expired")
+                break;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return inflight.size;
+}

package/dist/gates/contract.d.ts

@@ -3,20 +3,24 @@
  * it is not in the published OpenAPI documents.
  *
  * `POST /nylorun/v1/model-calls`
- * - Headers: `Authorization: Bearer <NYLORUN_GATES_TOKEN>`, `Idempotency-Key: <effect id>`,
- *   and optionally `Nylorun-Tenant: <tenant id>`, which must then be the database's one
- *   Tenant (a call naming another is refused).
- * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`.
+ * - Headers: `Authorization: Bearer <run token>` (F5, `tenant/run-token.ts`), `Idempotency-Key:
+ *   <effect id>`, and optionally `Nylorun-Tenant: <tenant id>`, which must then be the token's
+ *   Tenant. Core's credential (`NYLORUN_GATES_TOKEN`) is refused: only a run calls the model.
+ * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`. It names no session, turn or agent:
+ *   the gate takes them from the token, and refuses a body that names them.
  * - `200 {outcome}` once the call has finished, whether the outcome is a candidate or a
- *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing or wrong
- *   token, `400 invalid_request` for a malformed Tenant header or a bad body, `409
- *   gate_conflict` when a different request already runs under the same key.
+ *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing, malformed,
+ *   expired or foreign token, `409 run_stale` when the token's lease is no longer the
+ *   session's (a cancel, a new turn, a takeover), `400 invalid_request` for a malformed Tenant
+ *   header or a bad body, `409 gate_conflict` when a different request already runs under the
+ *   same key.
  * - With an `Idempotency-Key` the call outlives its client (P1.2): a re-send with the same key
  *   and body joins it, or gets its outcome for 30 minutes. Without one, a client that goes
  *   away aborts the call.
  *
  * `POST /nylorun/v1/model-calls/{key}/cancel` (same headers): aborts the keyed call; `204`
- * whether or not it exists.
+ * whether or not it exists, `403 gate_forbidden` when it is another session's call. The token
+ * need not be live: a user cancel makes it stale, and still stops its call.
  */
 import { z } from "zod";
 import type { ModelGateOutcome } from "./model-gate.js";
@@ -26,9 +30,6 @@ export declare const TENANT_HEADER = "nylorun-tenant";
 /** Largest request body the gate reads: one `ModelCall` with its whole projected history. */
 export declare const MAX_MODEL_CALL_BYTES: number;
 export declare const ModelCallBodySchema: z.ZodObject<{
-    sessionId: z.ZodString;
-    turnId: z.ZodString;
-    agentId: z.ZodString;
     effectId: z.ZodString;
     invocationId: z.ZodString;
     call: z.ZodObject<{
@@ -37,7 +38,7 @@ export declare const ModelCallBodySchema: z.ZodObject<{
             name: z.ZodString;
         }, z.core.$loose>>;
     }, z.core.$loose>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export type ModelCallBody = z.infer<typeof ModelCallBodySchema>;
 export interface ModelCallResponse {
     readonly outcome: ModelGateOutcome;
@@ -45,7 +46,7 @@ export interface ModelCallResponse {
 /** An error answer: `{error: {code, message}}`. */
 export interface GateErrorBody {
     readonly error: {
-        readonly code: "gate_unauthorized" | "invalid_request" | "gate_conflict";
+        readonly code: "gate_unauthorized" | "gate_forbidden" | "run_stale" | "invalid_request" | "gate_conflict";
         readonly message: string;
     };
 }

package/dist/gates/contract.js

@@ -3,20 +3,24 @@
  * it is not in the published OpenAPI documents.
  *
  * `POST /nylorun/v1/model-calls`
- * - Headers: `Authorization: Bearer <NYLORUN_GATES_TOKEN>`, `Idempotency-Key: <effect id>`,
- *   and optionally `Nylorun-Tenant: <tenant id>`, which must then be the database's one
- *   Tenant (a call naming another is refused).
- * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`.
+ * - Headers: `Authorization: Bearer <run token>` (F5, `tenant/run-token.ts`), `Idempotency-Key:
+ *   <effect id>`, and optionally `Nylorun-Tenant: <tenant id>`, which must then be the token's
+ *   Tenant. Core's credential (`NYLORUN_GATES_TOKEN`) is refused: only a run calls the model.
+ * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`. It names no session, turn or agent:
+ *   the gate takes them from the token, and refuses a body that names them.
  * - `200 {outcome}` once the call has finished, whether the outcome is a candidate or a
- *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing or wrong
- *   token, `400 invalid_request` for a malformed Tenant header or a bad body, `409
- *   gate_conflict` when a different request already runs under the same key.
+ *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing, malformed,
+ *   expired or foreign token, `409 run_stale` when the token's lease is no longer the
+ *   session's (a cancel, a new turn, a takeover), `400 invalid_request` for a malformed Tenant
+ *   header or a bad body, `409 gate_conflict` when a different request already runs under the
+ *   same key.
  * - With an `Idempotency-Key` the call outlives its client (P1.2): a re-send with the same key
  *   and body joins it, or gets its outcome for 30 minutes. Without one, a client that goes
  *   away aborts the call.
  *
  * `POST /nylorun/v1/model-calls/{key}/cancel` (same headers): aborts the keyed call; `204`
- * whether or not it exists.
+ * whether or not it exists, `403 gate_forbidden` when it is another session's call. The token
+ * need not be live: a user cancel makes it stale, and still stops its call.
  */
 import { z } from "zod";
 export const MODEL_CALLS_PATH = "/nylorun/v1/model-calls";
@@ -24,10 +28,7 @@ export const MODEL_CALLS_PATH = "/nylorun/v1/model-calls";
 export const TENANT_HEADER = "nylorun-tenant";
 /** Largest request body the gate reads: one `ModelCall` with its whole projected history. */
 export const MAX_MODEL_CALL_BYTES = 32 * 1024 * 1024;
-export const ModelCallBodySchema = z.object({
-    sessionId: z.string().min(1),
-    turnId: z.string().min(1),
-    agentId: z.string().min(1),
+export const ModelCallBodySchema = z.strictObject({
     effectId: z.string().min(1),
     invocationId: z.string().min(1),
     call: z.looseObject({

package/dist/gates/egress.d.ts

@@ -0,0 +1,72 @@
+import { type Server } from "node:http";
+import { type Socket } from "node:net";
+import type { EgressTokenVerdict } from "../sandbox/egress-token.js";
+import type { SessionStore } from "../store/types.js";
+import type { Logger } from "../tenant/types.js";
+/**
+ * What egress-gate reads of a sandbox: its current host epoch, the pod that joined at it, and
+ * its spec's `network.allow`; `undefined` when it is gone, deleted, lost, expired or not a pod.
+ */
+export interface EgressSandboxes {
+    live(sandboxId: string): Promise<{
+        readonly epoch: number;
+        readonly podUid?: string;
+        readonly allow: readonly string[];
+    } | undefined>;
+}
+/** Ports a tunnel may open. */
+export declare const EGRESS_PORTS: readonly number[];
+/** Tunnels one sandbox may hold open at once. */
+export declare const EGRESS_MAX_PER_SANDBOX = 64;
+/** A tunnel with no traffic either way for this long is closed. */
+export declare const EGRESS_IDLE_MS: number;
+/** How long a sandbox's epoch and allowlist are reused before they are read again. */
+export declare const EGRESS_CACHE_MS = 5000;
+/** How long the gate waits for the upstream connection. */
+export declare const EGRESS_CONNECT_TIMEOUT_MS = 10000;
+export interface StartEgressGateOptions {
+    readonly listen: {
+        readonly host: string;
+        readonly port: number;
+    };
+    readonly logger: Logger;
+    /** Verifies a presented egress token (`verifyEgressToken` over the Tenant's keys). */
+    verify(raw: string): Promise<EgressTokenVerdict>;
+    readonly sandboxes: EgressSandboxes;
+    readonly idleMs?: number;
+    readonly maxPerSandbox?: number;
+    readonly cacheMs?: number;
+    readonly connectTimeoutMs?: number;
+    /** Tests replace name resolution. */
+    readonly lookup?: (host: string) => Promise<readonly {
+        address: string;
+        family: number;
+    }[]>;
+    /** Tests replace which resolved addresses are refused. Default `isEgressBlocked`. */
+    readonly blocked?: (address: string) => boolean;
+    /** Tests replace how the checked address is dialled. */
+    readonly dial?: (address: string, port: number) => Socket;
+}
+export interface EgressGate {
+    /** Where the gate listens, e.g. `http://0.0.0.0:4200`. */
+    readonly url: string;
+    readonly server: Server;
+    close(): Promise<void>;
+}
+/**
+ * True when a tunnel must not reach `address`: private, loopback, link-local (169.254.169.254, the
+ * cloud metadata address, included), unspecified, multicast, reserved, or an IPv6 form that
+ * embeds an IPv4 address.
+ */
+export declare function isEgressBlocked(address: string): boolean;
+/** Whether `host` (a lowercase name) matches one of `allow`'s names or `*.suffix` patterns. */
+export declare function egressAllows(host: string, allow: readonly string[]): boolean;
+/** The egress token in a `Proxy-Authorization` header, or `undefined`. */
+export declare function proxyToken(header: string | undefined): string | undefined;
+export declare function startEgressGate(options: StartEgressGateOptions): Promise<EgressGate>;
+/**
+ * `EgressSandboxes` over the Tenant's `sandbox_resources` (one indexed read): a pod sandbox's
+ * host epoch, the pod that joined at it and its spec's allowlist; nothing for a virtual
+ * sandbox, or one deleted, lost or expired, as `staleHost` judges a host token.
+ */
+export declare function storeEgressSandboxes(store: SessionStore): EgressSandboxes;