@nimbus-sh/fabric 0.1.0 → 0.3.0

package/src/workerd-facet-host.ts

@@ -13,20 +13,25 @@
  * `HostedProcess` and never imports this file.
  */
 
-import { disposeRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 import {
   getCtxExports,
+  stagedBootAssembler,
   supervisorEntrypoint,
   supervisorEntrypointName,
-} from './ctx-exports.js';
+} from './composition.js';
 import {
+  assertModuleMapWithinCodeLimit,
   beginLoaderFetch,
+  facetNameCount,
+  facetNameCountDurable,
+  recordFacetNameMinted,
   recordLoaderId,
   withDynamicWorkerCapNamed,
-} from './loader-ledger.js';
+  withFacetBudgetNamed,
+} from './budgets.js';
 import {
   RESIDENT_PROCESS_CLASS,
-  requireStagedBootAssembler,
   residentLoaderConfig,
   type HostedProcess,
   type OneShotCodeSpec,
@@ -91,71 +96,6 @@ export async function createLoadedWorkerEntrypoint(
   });
 }
 
-/**
- * Total bytes a dynamic Worker's module map may carry, across every member of
- * it. A hard platform limit, not a policy knob: 62 MiB lands and 64 MiB is
- * refused with "Dynamic Worker code size (N bytes) exceeds the maximum allowed
- * size of 67108864 bytes", confirmed at five sizes with two trials each. The
- * budget is shared, so a ruby process is already 34.3 MiB down before its disk
- * is counted.
- */
-export const DYNAMIC_WORKER_CODE_LIMIT_BYTES = 67_108_864;
-
-/**
- * Refuse a module map over {@link DYNAMIC_WORKER_CODE_LIMIT_BYTES}, naming
- * the largest members. The platform's own refusal reports one number for a
- * budget shared across every member of the map, which tells the operator
- * nothing about WHAT to shrink — so every fabric seam that assembles a map
- * runs this before the loader sees it.
- *
- * Costed to its two paths. Under the ceiling: one length read per member —
- * UTF-16 code units for text, which equal UTF-8 bytes for the ASCII module
- * text the generators emit and undercount otherwise; the platform's own
- * refusal still backstops the exotic case, because this check exists to name
- * members, not to be the ceiling. Over it: exact UTF-8 sizes, computed only
- * then, sorted so the biggest lever is first.
- */
-export function assertModuleMapWithinCodeLimit(modules: Record<string, unknown>): void {
-  let estimate = 0;
-  for (const content of Object.values(modules)) {
-    estimate += memberBytes(content, null);
-  }
-  if (estimate <= DYNAMIC_WORKER_CODE_LIMIT_BYTES) return;
-
-  const encoder = new TextEncoder();
-  const sized = Object.entries(modules)
-    .map(([name, content]) => ({ name, bytes: memberBytes(content, encoder) }))
-    .sort((a, b) => b.bytes - a.bytes);
-  const total = sized.reduce((sum, member) => sum + member.bytes, 0);
-  const top = sized.slice(0, 5)
-    .map(({ name, bytes }) => `'${name}' (${bytes.toLocaleString('en-US')} bytes)`)
-    .join(', ');
-  throw new Error(
-    `Nimbus: dynamic-worker module map is ${total.toLocaleString('en-US')} bytes, over the `
-      + `${DYNAMIC_WORKER_CODE_LIMIT_BYTES.toLocaleString('en-US')}-byte platform ceiling shared by `
-      + `every member. Largest members: ${top}`,
-  );
-}
-
-/**
- * Bytes one module-map member carries, across the loader's content kinds
- * (plain string, `{ js | cjs | py | text }`, `{ wasm | data }`). With an
- * encoder, text is measured exactly; without one, by code-unit length.
- */
-function memberBytes(content: unknown, encoder: TextEncoder | null): number {
-  const textBytes = (text: string): number =>
-    encoder ? encoder.encode(text).byteLength : text.length;
-  if (typeof content === 'string') return textBytes(content);
-  if (content !== null && typeof content === 'object') {
-    for (const value of Object.values(content)) {
-      if (typeof value === 'string') return textBytes(value);
-      if (value instanceof ArrayBuffer) return value.byteLength;
-      if (ArrayBuffer.isView(value)) return value.byteLength;
-    }
-  }
-  return 0;
-}
-
 // ── Facet plumbing ──────────────────────────────────────────────────────────
 
 /** The subset of a facet stub a resident process exposes to whoever opened it. */
@@ -178,7 +118,7 @@ interface FacetContainer {
   /**
    * Present on deployed Cloudflare workerd, absent from the pinned
    * `@cloudflare/workers-types` and from local workerd ≤ 1.20260603.1 — see
-   * {@link cloneFacetStorage}, the one way the fabric calls it.
+   * {@link cloneStorage}, the one way the fabric calls it.
    */
   clone?(src: string, dst: string): void;
 }
@@ -196,14 +136,19 @@ interface LoadedWorkerStub {
  * Durable Object class, so a resident process can be re-entered; `load` is
  * unkeyed and yields a stateless entrypoint, which is all a program that ends
  * with its call can ever need.
+ *
+ * `get` stays wide on purpose: the platform passes a null id for the unkeyed
+ * call and answers the callback with the code object or a promise of it, so a
+ * narrower declaration would refuse the real binding. The fabric itself always
+ * passes a string id and a promise callback.
  */
 interface WorkerLoaderBinding {
-  get(id: string, code: () => Promise<unknown>): { getDurableObjectClass(name: string): unknown };
+  get(id: string | null, code: () => unknown): { getDurableObjectClass(name: string): unknown };
   load(code: unknown): LoadedWorkerStub;
 }
 
 /**
- * The bindings `openResidentFacet` needs off whichever DO is hosting. A
+ * The bindings `processes` needs off whichever DO is hosting. A
  * staged boot's assembler may read more off the same env (Nimbus's reads
  * ASSETS); the env travels to it whole, so nothing further is named here.
  */
@@ -250,7 +195,7 @@ function facetContainer(ctx: DurableObjectState): FacetContainer {
  * storage budget grants no copy-on-write credit — crossing it resets the
  * object rather than raising an error.
  */
-export async function cloneFacetStorage(
+export async function cloneStorage(
   ctx: DurableObjectState,
   clone: {
     src: string;
@@ -283,7 +228,7 @@ export async function cloneFacetStorage(
 }
 
 /**
- * The facet name for a slot. Reused, and that is the entire point.
+ * The facet name for an ephemeral slot. Reused, and that is the entire point.
  *
  * A Durable Object admits 65,536 facets over its LIFETIME: the IDs are
  * append-only and are never reclaimed, so the bound is on facets ever CREATED,
@@ -295,21 +240,19 @@ export async function cloneFacetStorage(
  * Reusing a NAME costs no new ID. So the name comes from a free list and the
  * pid stays what it always was: the process identity in the ProcessTable. The
  * two were only ever conflated because one of them happened to be handy.
+ *
+ * The book shares the facet-ID space with one other namespace: durable
+ * applications, which mint `app-slot-<n>` names of their own (one ID per app,
+ * ever). The prefixes are disjoint BY CONSTRUCTION, and that disjointness is
+ * load-bearing — a proc-slot name reissued onto a durable app's retained
+ * storage would boot the wrong process into someone else's disk.
  */
 export function residentFacetName(slot: number): string {
   return `proc-slot-${slot}`;
 }
 
-/**
- * Facet IDs a Durable Object is granted over its LIFETIME. Append-only and
- * never reclaimed, so crossing it is unrecoverable for the object — which is
- * why the ledger below counts consumption durably instead of leaving the
- * bound as prose the slot book merely respects.
- */
-export const FACET_ID_LIFETIME_BUDGET = 65_536;
-
-/** Where the ledger persists the count of facet names ever minted. */
-export const FACET_NAME_HIGH_WATER_KEY = 'fabric_facet_name_high_water';
+/** The prefix every durable application's facet name carries. */
+export const DURABLE_FACET_NAME_PREFIX = 'app-slot-';
 
 /** One hosting actor's slot book. */
 interface SlotBook {
@@ -319,16 +262,6 @@ interface SlotBook {
   next: number;
   /** Slot held by each live pid, so release can find it. */
   held: Map<number, number>;
-  /**
-   * The durable high-water of names ever minted, as an adopt-then-advance
-   * chain. It starts as the read of {@link FACET_NAME_HIGH_WATER_KEY} and
-   * every later link writes only a LARGER count — a fresh incarnation restarts
-   * `next` at zero, and a write that had not adopted first would clobber the
-   * lifetime count down to this incarnation's. The chain never rejects.
-   */
-  ledger: Promise<number>;
-  /** The largest count the chain has adopted or written, for sync reads. */
-  ledgerKnown: number;
 }
 
 /**
@@ -345,52 +278,23 @@ interface SlotBook {
  * VFS epoch, in which case `invalidatedSince` can only answer poison and the
  * whole store is dropped. A process therefore cannot boot onto a previous
  * tenant's filesystem even when release never ran.
+ *
+ * The book names only the `proc-slot-` space. Durable `app-slot-` names are
+ * allocated against DO storage instead (their owner survives a reset), so a
+ * fresh incarnation's `next` starting at 0 can never collide with them even
+ * before the durable ledger is adopted.
  */
 const slotBooks = new WeakMap<DurableObjectState, SlotBook>();
 
 function slotBook(ctx: DurableObjectState): SlotBook {
   let book = slotBooks.get(ctx);
   if (!book) {
-    const created: SlotBook = {
-      free: [],
-      next: 0,
-      held: new Map(),
-      ledger: Promise.resolve(0),
-      ledgerKnown: 0,
-    };
-    created.ledger = Promise.resolve(ctx.storage.get(FACET_NAME_HIGH_WATER_KEY))
-      .then((value) => (typeof value === 'number' ? value : 0))
-      .catch(() => 0)
-      .then((adopted) => {
-        created.ledgerKnown = Math.max(created.ledgerKnown, adopted);
-        return adopted;
-      });
-    book = created;
+    book = { free: [], next: 0, held: new Map() };
     slotBooks.set(ctx, book);
   }
   return book;
 }
 
-/**
- * The lifetime facet-ID ledger: how many facet names this fabric has ever
- * minted on the Durable Object, against the 65,536 the platform will ever
- * grant it. `consumed` only ever counts FIRST uses — a reused name, in this
- * incarnation or any earlier one, cost no new ID, which is the slot book's
- * whole reason to exist. Surfaced so an operator can see proximity to a wall
- * whose crossing is unrecoverable, instead of discovering it from the
- * platform's opaque failure.
- */
-export async function facetIdBudget(
-  ctx: DurableObjectState,
-): Promise<{ consumed: number; budget: number }> {
-  const book = slotBook(ctx);
-  const durable = await book.ledger;
-  return {
-    consumed: Math.max(durable, book.next),
-    budget: FACET_ID_LIFETIME_BUDGET,
-  };
-}
-
 /** Take a slot for `pid`, reusing a returned one before minting a new name. */
 function acquireSlot(ctx: DurableObjectState, pid: number): number {
   const book = slotBook(ctx);
@@ -399,49 +303,12 @@ function acquireSlot(ctx: DurableObjectState, pid: number): number {
   const reused = book.free.length > 0;
   const slot = reused ? book.free.shift()! : book.next++;
   book.held.set(pid, slot);
-  if (!reused) recordNameMinted(ctx, book);
+  // A fresh name is a permanently consumed facet ID; the durable count lives
+  // in the budgets ledger (see budgets.ts).
+  if (!reused) recordFacetNameMinted(ctx, book.next);
   return slot;
 }
 
-/**
- * Advance the durable ledger to this incarnation's name count, if it is a new
- * lifetime high. Chained behind adoption so the comparison is always against
- * the real persisted value; a failed write leaves the old link's count and the
- * next mint tries again — the ledger may transiently undercount, never over.
- */
-function recordNameMinted(ctx: DurableObjectState, book: SlotBook): void {
-  const count = book.next;
-  book.ledger = book.ledger.then(async (durable) => {
-    if (count <= durable) return durable;
-    try {
-      await ctx.storage.put(FACET_NAME_HIGH_WATER_KEY, count);
-    } catch {
-      return durable;
-    }
-    book.ledgerKnown = Math.max(book.ledgerKnown, count);
-    return count;
-  });
-}
-
-/**
- * Name the facet-ID budget on a creation failure at the wall; below it, hand
- * the error back untouched. Exhaustion is the one failure here the platform
- * reports opaquely AND that no teardown, retry or reset can undo, so the
- * ledger — the only witness to the real cause — does the naming. Not a
- * threshold: the comparison is against the budget itself.
- */
-function withFacetBudgetNamed(consumed: number, error: unknown): unknown {
-  if (consumed < FACET_ID_LIFETIME_BUDGET) return error;
-  const platform = error instanceof Error ? error.message : String(error);
-  return new Error(
-    `Nimbus: facet creation failed with this Durable Object's `
-      + `${FACET_ID_LIFETIME_BUDGET.toLocaleString('en-US')} facet-ID lifetime budget consumed `
-      + `(${consumed} facet names ever created). Facet IDs are append-only and never reclaimed, `
-      + `so this failure is permanent for the object: ${platform}`,
-    { cause: error },
-  );
-}
-
 /** Return `pid`'s slot to the free list. */
 function releaseSlot(ctx: DurableObjectState, pid: number): void {
   const book = slotBook(ctx);
@@ -452,29 +319,83 @@ function releaseSlot(ctx: DurableObjectState, pid: number): void {
   book.free.sort((a, b) => a - b);
 }
 
+/**
+ * Drop one facet's SQLite by name — the ONLY call site that may delete facet
+ * storage. `spawnResident` releases ephemeral processes with abort+delete
+ * (storage is slot-reuse hygiene) and durable ones with abort alone (the
+ * storage IS the durable application's state); explicit removal arrives here
+ * through the coordinator's durable-slot book, owner-checked.
+ */
+export function deleteFacetStorage(ctx: DurableObjectState, name: string): void {
+  facetContainer(ctx).delete(name);
+}
+
+
 
 /**
- * What `openResidentFacet` hands back: a running process, minus its placement.
+ * What `processes(ctx, env).spawn` hands back: a running process, minus its placement.
  *
- * `slot` rides along because the caller's `describe` needs the facet's real
- * name and the slot is not derivable from the pid — that indirection is the
- * whole point of the free list. Reading it back out of the book later would
- * also race the release that empties it.
+ * `name` is the facet's real name and `slot` its ephemeral book entry (absent
+ * for a durable spawn, whose name its coordinator allocated out of storage).
+ * Both ride along because the caller's `describe` needs them and neither is
+ * derivable from the pid — reading a slot back out of the book would race the
+ * release that empties it.
  */
-export type ResidentFacet = Omit<HostedProcess, 'describe'> & { slot: number };
+export type ResidentFacet = Omit<HostedProcess, 'describe'> & { name: string; slot?: number };
 
 /**
- * Open a resident process as a facet of the actor whose `ctx` and `env` are
- * given, and start its runner.
+ * The process surface of one hosting actor: how a resident process comes
+ * into existence on workerd, and how a one-shot program runs to completion.
  *
- * This is the ONE way a resident process comes into existence, and every
+ * `spawn` is the ONE way a resident process comes into existence, and every
  * substrate goes through it: the facet host calls it with the coordinator's
  * own `ctx`, the peer host calls it — over one RPC — with a sibling session
  * DO's. Everything a substrate could plausibly want to special-case is a
  * PARAMETER here rather than a branch: which actor hosts the child, and how
  * the boot spec's by-path members are read.
  */
-export function openResidentFacet(
+export function processes(ctx: DurableObjectState, env: ResidentFacetEnv): Processes {
+  return new Processes(ctx, env);
+}
+
+export class Processes {
+  constructor(
+    private readonly ctx: DurableObjectState,
+    private readonly env: ResidentFacetEnv,
+  ) {}
+
+  /** Open a resident process as a facet of this actor, and start its runner. */
+  spawn(
+    disk: () => ResidentDiskReader,
+    supervisor: ResidentSupervisorProps,
+    params: ProcessHostParams,
+  ): ResidentFacet {
+    return spawnResident(this.ctx, this.env, disk, supervisor, params);
+  }
+
+  /**
+   * Run one program to completion as an UNKEYED dynamic worker.
+   *
+   * Unkeyed is the whole difference from `spawn`: nothing can re-resolve this
+   * worker into a later request's context, so it can never be a routeable
+   * target and never has to be released by name. It exists for the duration
+   * of one call and its stubs are dropped as that call unwinds.
+   *
+   * Shared by both substrates on purpose. `peer` places processes that have a
+   * residency to place; a one-shot has none, and shipping its fully-inline
+   * map across a sibling hop would meet the 32 MiB RPC ceiling that by-path
+   * boot specs exist to avoid — for a run that gains nothing by moving.
+   */
+  run<T>(
+    supervisor: ResidentSupervisorProps,
+    params: OneShotParams,
+    consume: (response: Response) => Promise<T>,
+  ): Promise<T> {
+    return runOneShot(this.ctx, this.env, supervisor, params, consume);
+  }
+}
+
+function spawnResident(
   ctx: DurableObjectState,
   env: ResidentFacetEnv,
   disk: () => ResidentDiskReader,
@@ -482,9 +403,21 @@ export function openResidentFacet(
   params: ProcessHostParams,
 ): ResidentFacet {
   const facets = facetContainer(ctx);
-  const book = slotBook(ctx);
-  const slot = acquireSlot(ctx, params.pid);
-  const name = residentFacetName(slot);
+  // An explicit name is the durable path: the caller allocated an
+  // `app-slot-<n>` identity out of DO storage and this facet keeps its SQLite
+  // across aborts. Anything else takes the in-memory book — and that book's
+  // `proc-slot-` names must never be minted for it, or an ephemeral release's
+  // delete would wipe the app's storage and a reused slot would land a new
+  // process on someone else's disk.
+  const explicit = params.facet;
+  if (explicit && !explicit.name.startsWith(DURABLE_FACET_NAME_PREFIX)) {
+    throw new Error(
+      `Nimbus: an explicit facet name must carry the '${DURABLE_FACET_NAME_PREFIX}' `
+        + `prefix, got '${explicit.name}'`,
+    );
+  }
+  const slot = explicit ? undefined : acquireSlot(ctx, params.pid);
+  const name = explicit ? explicit.name : residentFacetName(slot!);
   // The start callback is the ONLY way this facet is ever created, and it
   // fires AT MOST ONCE. Every later use goes through the stub below, so the
   // callback running a second time means the facet was released or died —
@@ -510,8 +443,8 @@ export function openResidentFacet(
   try {
     facet = facets.get(name, start);
   } catch (error) {
-    releaseSlot(ctx, params.pid);
-    throw withFacetBudgetNamed(Math.max(book.ledgerKnown, book.next), error);
+    if (slot !== undefined) releaseSlot(ctx, params.pid);
+    throw withFacetBudgetNamed(facetNameCount(ctx), error);
   }
 
   let disposed = false;
@@ -520,10 +453,17 @@ export function openResidentFacet(
     disposed = true;
     released = true;
     try { facets.abort(name, new Error('Nimbus: resident process released')); } catch { /* already gone */ }
-    try { facets.delete(name); } catch { /* already gone */ }
+    // The two release classes: an ephemeral facet's SQLite is slot-reuse
+    // hygiene — the name is handed out again, so the store must not be — and
+    // a durable one's is the application itself: abort ends the process, the
+    // data stays for the next boot, and only removeDurableApp's explicit
+    // deleteFacetStorage call ever drops it.
+    if (!explicit?.durable) {
+      try { facets.delete(name); } catch { /* already gone */ }
+    }
     // Only after the facet is gone. A slot handed out while its previous
     // tenant were still being torn down would have two processes on one name.
-    releaseSlot(ctx, params.pid);
+    if (slot !== undefined) releaseSlot(ctx, params.pid);
   };
 
   let started: Promise<unknown>;
@@ -531,15 +471,14 @@ export function openResidentFacet(
     started = facet.startProcess(params.startArgs);
   } catch (error) {
     void release();
-    throw withFacetBudgetNamed(Math.max(book.ledgerKnown, book.next), error);
+    throw withFacetBudgetNamed(facetNameCount(ctx), error);
   }
   // The rejection that carries the platform's failure at ID exhaustion is
   // this one, and it is annotated AFTER awaiting the ledger — the first
   // failure of a fresh incarnation must compare against the persisted count,
   // not the zero its adoption read has not yet replaced.
   started = started.catch(async (error) => {
-    const durable = await book.ledger;
-    throw withFacetBudgetNamed(Math.max(durable, book.next), error);
+    throw withFacetBudgetNamed(await facetNameCountDurable(ctx), error);
   });
   // A caller reads whichever of `started` and the lifecycle it needs, so keep
   // the runtime from reporting the other as an unhandled rejection.
@@ -552,6 +491,7 @@ export function openResidentFacet(
     handleHttpRequest: (request: Request) => facet.handleHttpRequest(request),
     handleWebSocketRequest: (request: Request) => facet.fetch(request),
     release,
+    name,
     slot,
   };
 }
@@ -587,20 +527,7 @@ function residentProcessClass(
   }
 }
 
-/**
- * Run one program to completion as an UNKEYED dynamic worker.
- *
- * Unkeyed is the whole difference from `openResidentFacet`: nothing can
- * re-resolve this worker into a later request's context, so it can never be a
- * routeable target and never has to be released by name. It exists for the
- * duration of one call and its stubs are dropped as that call unwinds.
- *
- * Shared by both substrates on purpose. `peer` places processes that have a
- * residency to place; a one-shot has none, and shipping its fully-inline map
- * across a sibling hop would meet the 32 MiB RPC ceiling that by-path boot
- * specs exist to avoid — for a run that gains nothing by moving.
- */
-export async function runOneShotWorker<T>(
+async function runOneShot<T>(
   ctx: DurableObjectState,
   env: ResidentFacetEnv,
   supervisor: ResidentSupervisorProps,
@@ -672,18 +599,33 @@ export async function runOneShotWorker<T>(
   }
 }
 
-async function residentWorkerConfig(
+/**
+ * The WorkerCode the loader callback returns for one resident boot: the
+ * module map from {@link residentLoaderConfig} (or the staged assembler),
+ * plus the isolate's env and network posture.
+ *
+ * A `code` boot with an explicit `env` — defined, even as `{}` — is the
+ * embedder's whole statement about the isolate: the env rides through
+ * exactly as minted (loopback stubs by reference), and the composed supervisor
+ * entrypoint is not consulted at all, so no SUPERVISOR binding appears.
+ * Without one, the default holds: inherited network plus a SUPERVISOR
+ * minted from the composed entrypoint for the coordinator's identity.
+ */
+export async function residentWorkerConfig(
   env: ResidentFacetEnv,
   disk: () => ResidentDiskReader,
   supervisor: ResidentSupervisorProps,
   boot: ResidentBootSpec,
 ): Promise<Record<string, unknown>> {
+  if (boot.kind === 'code' && boot.code.env !== undefined) {
+    const isolated = await residentLoaderConfig(boot.code, disk());
+    assertModuleMapWithinCodeLimit(configModules(isolated));
+    return isolated;
+  }
   const config = boot.kind === 'staged'
-    ? await requireStagedBootAssembler()(env, boot.stage)
+    ? await stagedBootAssembler()(env, boot.stage)
     : await residentLoaderConfig(boot.code, disk());
-  assertModuleMapWithinCodeLimit(
-    (config as { modules?: Record<string, unknown> }).modules ?? {},
-  );
+  assertModuleMapWithinCodeLimit(configModules(config));
   const supervisorRpc = supervisorEntrypoint();
   if (!supervisorRpc) {
     throw new Error(
@@ -692,3 +634,12 @@ async function residentWorkerConfig(
   }
   return { ...config, env: { SUPERVISOR: supervisorRpc({ props: supervisor }) } };
 }
+
+/** The module map a loader config assembled, or empty when it named none. */
+function configModules(config: object): Record<string, unknown> {
+  const modules: unknown = 'modules' in config ? config.modules : undefined;
+  if (typeof modules !== 'object' || modules === null) return {};
+  // Loader configs only ever carry a module map under this key.
+  const map: Record<string, unknown> = modules as Record<string, unknown>;
+  return map;
+}