@nimbus-sh/fabric 0.8.0 → 0.10.0

package/src/timers.ts

@@ -58,9 +58,12 @@ export const TIMER_REASONS_KEY = 'w1_next_alarm_reasons';
  * The host instance carrying the per-instance timer chain. The field lives on
  * the embedder's DO instance so one chain serializes every timer-map
  * read-modify-write for that instance (see {@link Timers.schedule}).
+ * `_timerEpoch` counts {@link Timers.reset}s: a schedule or dispatch writes
+ * only while the epoch it was requested in is still current.
  */
 export interface TimerHost {
   _timerChain?: Promise<unknown>;
+  _timerEpoch?: number;
 }
 
 /**
@@ -159,6 +162,7 @@ export class Timers {
       arms.push({ reason, whenMs });
       return Promise.resolve(true);
     }
+    const epoch = host._timerEpoch ?? 0;
     // Serialize every read-modify-write of the reasons map through one
     // per-instance chain: two schedulers firing back-to-back from one activity
     // hook would otherwise interleave their get→put cycles and silently drop
@@ -170,15 +174,20 @@ export class Timers {
         const existing = (await ctx.storage.get(TIMER_REASONS_KEY)) as
           | Record<string, number>
           | undefined;
+        // Requested before a reset: it belongs to the timers the reset voided.
+        if ((host._timerEpoch ?? 0) !== epoch) return false;
         const map: Record<string, number> = { ...(existing || {}) };
         // Earliest-deadline-first: only update if new request is sooner or
         // this reason has no pending entry.
+        let written: Promise<unknown> | undefined;
         if (!(reason in map) || whenMs < map[reason]) {
           map[reason] = whenMs;
-          await ctx.storage.put(TIMER_REASONS_KEY, map);
+          written = ctx.storage.put(TIMER_REASONS_KEY, map);
         }
-        const earliest = Math.min(...Object.values(map));
-        setAlarmFn.call(ctx.storage, earliest);
+        // Issued in the turn the epoch was checked in: a reset after this
+        // point wipes and disarms after these, never before.
+        setAlarmFn.call(ctx.storage, Math.min(...Object.values(map)));
+        await written;
         return true;
       } catch (e) {
         console.warn('[nimbus/W1] timers.schedule threw:', errorText(e));
@@ -190,6 +199,18 @@ export class Timers {
     return chained;
   }
 
+  /**
+   * Void every timer of this instance: a schedule or dispatch already
+   * requested — still queued on the chain, or a dispatch whose handlers are
+   * running — writes no reason and arms no alarm from here on. For a
+   * deliberate end of the actor's state (a session destroy): call it before
+   * wiping storage and deleting the alarm, so nothing in flight writes the
+   * map back or re-arms after the wipe. Requests made after it proceed.
+   */
+  reset(): void {
+    this.host._timerEpoch = (this.host._timerEpoch ?? 0) + 1;
+  }
+
   /**
    * Multi-reason timer dispatcher. Called from the DO's `alarm()` handler
    * with the embedder's handler map.
@@ -216,19 +237,28 @@ export class Timers {
     alarmInfo?: TimerAlarmInfo,
   ): Promise<void> {
     const { host, ctx } = this;
+    const epoch = host._timerEpoch ?? 0;
+    const current = (): boolean => (host._timerEpoch ?? 0) === epoch;
     // Same serialization as schedule: the dispatcher's read→handlers→write
     // cycle must not interleave with an activity-hook schedule.
     const chained = (host._timerChain ?? Promise.resolve()).then(
-      () => dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo),
-      () => dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo),
+      () => dispatchBody(ctx, current, handlers, onLegacyAlarm, alarmInfo),
+      () => dispatchBody(ctx, current, handlers, onLegacyAlarm, alarmInfo),
     );
     host._timerChain = chained;
     return chained;
   }
 }
 
+/**
+ * One dispatch. `current` answers whether the epoch it was requested in still
+ * stands: once a reset voids it, no further handler runs and nothing is
+ * written or armed — the reset's caller is wiping this state, and a write
+ * after the wipe would outlive it.
+ */
 async function dispatchBody(
   ctx: TimerContext,
+  current: () => boolean,
   handlers: TimerHandlers,
   onLegacyAlarm?: () => void,
   alarmInfo?: TimerAlarmInfo,
@@ -242,6 +272,7 @@ async function dispatchBody(
     const existing = (await ctx?.storage?.get?.(TIMER_REASONS_KEY)) as
       | Record<string, number>
       | undefined;
+    if (!current()) return;
     const map: Record<string, number> = { ...(existing || {}) };
     const hadMap = Object.keys(map).length > 0;
     if (!hadMap) {
@@ -255,6 +286,7 @@ async function dispatchBody(
         if (when <= now) fired.push(reason);
       }
       for (const reason of fired) {
+        if (!current()) return;
         delete map[reason];
         const handler = handlers[reason];
         // Unknown reasons silently dropped (forward-compat).
@@ -269,20 +301,24 @@ async function dispatchBody(
         }
       }
     }
+    // A reset while the handlers ran: the map read above is gone, and
+    // writing it back — or arming for it — would revive what was ended.
+    if (!current()) return;
     // Fold the in-dispatch arms, earliest-deadline-first per reason.
     for (const arm of arms) {
       if (!(arm.reason in map) || arm.whenMs < map[arm.reason]) {
         map[arm.reason] = arm.whenMs;
       }
     }
-    // Re-arm or clear.
+    // Re-arm or clear, issued in the turn the epoch was checked in: a reset
+    // after this point wipes and disarms after these, never before.
     const setAlarmFn = ctx?.storage?.setAlarm;
     if (Object.keys(map).length > 0) {
-      await ctx.storage.put(TIMER_REASONS_KEY, map);
-      const earliest = Math.min(...Object.values(map));
+      const written = ctx.storage.put(TIMER_REASONS_KEY, map);
       if (typeof setAlarmFn === 'function') {
-        setAlarmFn.call(ctx.storage, earliest);
+        setAlarmFn.call(ctx.storage, Math.min(...Object.values(map)));
       }
+      await written;
     } else if (hadMap) {
       try { await ctx.storage.delete(TIMER_REASONS_KEY); } catch {}
       // No remaining reasons → no setAlarm call → DO becomes

package/src/vendor/types.ts

@@ -9,12 +9,18 @@ export interface TextModule { text: string }
 export interface DataModule { data: ArrayBuffer }
 export interface JsonModule { json: unknown }
 /**
- * A compiled WebAssembly module, importable from a facet by module name.
- * Nimbus ships these on every path — sql.js for node:sqlite, the interpreter
- * images for python and ruby — so the omission here was the type lagging the
- * API, not a kind the loader lacks.
+ * A WebAssembly module, importable from a facet by module name. Nimbus ships
+ * these on every path — sql.js for node:sqlite, the interpreter images for
+ * python and ruby — so the omission here was the type lagging the API, not a
+ * kind the loader lacks. The loader takes either the bytes, which it
+ * compiles, or a module the caller holds compiled already, whose compiled
+ * code the dynamic worker then shares (workerd src/workerd/api/
+ * worker-loader.c++, extractWasmModuleContent). A module handed over this
+ * way should be described with describeHostWasm (host-wasm.ts): the
+ * code-size budget and the loader cache key cannot read a Module's size or
+ * identity from JS.
  */
-export interface WasmModule { wasm: ArrayBuffer }
+export interface WasmModule { wasm: ArrayBuffer | WebAssembly.Module }
 
 /** Plain string = type inferred from file extension (.js or .py). */
 export type ModuleContent =

package/src/workerd-facet-host.ts

@@ -28,7 +28,6 @@ import {
   facetNameCount,
   facetNameCountDurable,
   recordFacetNameMinted,
-  recordLoaderId,
   withDynamicWorkerCapNamed,
   withFacetBudgetNamed,
 } from './budgets.js';
@@ -121,9 +120,10 @@ interface FacetContainer {
   abort(name: string, reason?: unknown): void;
   delete(name: string): void;
   /**
-   * Present on deployed Cloudflare workerd, absent from the pinned
-   * `@cloudflare/workers-types` and from local workerd ≤ 1.20260603.1 — see
-   * {@link cloneStorage}, the one way the fabric calls it.
+   * Declared by `@cloudflare/workers-types` 5 and present in workerd
+   * ≥ 1.20260926.1 and in production; an embedder's older local workerd
+   * (≤ 1.20260603.1) lacks it — see {@link cloneStorage}, the one way the
+   * fabric calls it.
    */
   clone?(src: string, dst: string): void;
 }
@@ -212,7 +212,7 @@ export async function cloneStorage(
   if (typeof facets.clone !== 'function') {
     throw new Error(
       'Nimbus: ctx.facets.clone is unavailable in this runtime; the reflink image '
-        + 'path needs deployed Cloudflare workerd (local workerd <= 1.20260603.1 lacks it)',
+        + 'path needs workerd 1.20260926.1 or later, or deployed Cloudflare workerd',
     );
   }
   const { src, dst } = clone;
@@ -471,10 +471,13 @@ function spawnResident(
       );
     }
     evaluated = true;
-    return { class: residentProcessClass(ctx, env, disk, supervisor, params) };
+    return { class: residentProcessClass(env, disk, supervisor, params, loaderKey) };
   };
   const book = slotBook(ctx);
   const ledger = sessionLedger(ctx);
+  // A warm worker keeps the SUPERVISOR binding it was built with, and the
+  // loader outlives this instance.
+  const loaderKey = supervisorLoaderKey(params.workerKey, supervisor);
   let facet: ResidentFacetStub;
   try {
     // N18: the fill is admitted, and recorded under the facet's name, before
@@ -490,6 +493,12 @@ function spawnResident(
     throw withFacetBudgetNamed(facetNameCount(ctx), error);
   }
   if (explicit) book.live.add(name);
+  // The facet's worker is one Dynamic Worker in flight for as long as the
+  // process is resident, not only while a call is open: its WebSockets and
+  // streamed responses outlive the calls the ledger could bracket, and a
+  // request can reach it at any moment. Held from here to `release`, so no
+  // fan-out spends the slot a running process needs.
+  const endResidency = beginLoaderFetch(ctx, loaderKey);
   facetOfPid(ctx).set(params.pid, name);
 
   let disposed = false;
@@ -498,6 +507,7 @@ function spawnResident(
     disposed = true;
     released = true;
     facetOfPid(ctx).delete(params.pid);
+    endResidency();
     try { facets.abort(name, new Error('Nimbus: resident process released')); } catch { /* already gone */ }
     if (explicit) book.live.delete(name);
     // The two release classes: an ephemeral facet's SQLite is slot-reuse
@@ -564,11 +574,11 @@ function spawnResident(
  * the hosting DO's heap.
  */
 function residentProcessClass(
-  ctx: DurableObjectState,
   env: ResidentFacetEnv,
   disk: () => ResidentDiskReader,
   supervisor: ResidentSupervisorProps,
   params: ProcessHostParams,
+  loaderKey: string,
 ): unknown {
   const loader = env.LOADER;
   if (!loader || typeof loader.get !== 'function') {
@@ -577,18 +587,9 @@ function residentProcessClass(
         + 'the Worker Loader binding; add it via worker_loaders in wrangler.jsonc.',
     );
   }
-  // A warm worker keeps the SUPERVISOR binding it was built with, and the
-  // loader outlives this instance.
-  const loaderKey = supervisorLoaderKey(params.workerKey, supervisor);
-  try {
-    const worker = loader
-      .get(loaderKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
-      .getDurableObjectClass(RESIDENT_PROCESS_CLASS);
-    recordLoaderId(ctx, loaderKey);
-    return worker;
-  } catch (error) {
-    throw withDynamicWorkerCapNamed(ctx, error);
-  }
+  return loader
+    .get(loaderKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
+    .getDurableObjectClass(RESIDENT_PROCESS_CLASS);
 }
 
 async function runOneShot<T>(
@@ -638,22 +639,26 @@ async function runOneShot<T>(
       throw new Error('Nimbus: one-shot runtime entrypoint has no fetch method');
     }
     params.onLoaded?.();
-    // The unkeyed worker is a live dynamic worker for exactly this call, so
-    // the run is a Loader fetch on the hosting actor's ledger — bracketed,
-    // never wrapped: see beginLoaderFetch for the measured DO-poisoning
-    // hazard, and the pipelined-`fetch.call` note above for its sibling.
-    const endFetch = beginLoaderFetch(ctx);
-    let response: Response;
+    // The unkeyed worker is one distinct dynamic worker in flight until its
+    // response is consumed (the body streams from it), keyed by this run's
+    // writer id — bracketed, never wrapped: see beginLoaderFetch for the
+    // measured DO-poisoning hazard, and the pipelined-`fetch.call` note above
+    // for its sibling.
+    const endFetch = beginLoaderFetch(ctx, `one-shot:${params.writerId}`);
     try {
-      response = await ep.fetch(params.request);
+      const response = await ep.fetch(params.request);
+      try {
+        return await consume(response);
+      } finally {
+        disposeRpcResource(response);
+      }
+    } catch (error) {
+      // A limit refusal pauses the ledger's admissions (beginLoaderFetchWhenFree).
+      endFetch(error);
+      throw error;
     } finally {
       endFetch();
     }
-    try {
-      return await consume(response);
-    } finally {
-      disposeRpcResource(response);
-    }
   } catch (error) {
     throw withDynamicWorkerCapNamed(ctx, error);
   } finally {