@nimbus-sh/fabric 0.7.0 → 0.8.0

package/src/workerd-facet-host.ts

@@ -14,6 +14,8 @@
  */
 
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { StorageLedger, forgetFacetStorage } from '@nimbus-sh/core/runtime/storage-ledger.js';
+import type { SqlDatabase } from '@nimbus-sh/core/runtime/os-contracts.js';
 import {
   getCtxExports,
   stagedBootAssembler,
@@ -41,6 +43,7 @@ import {
   type ResidentDiskReader,
   type ResidentSupervisorProps,
 } from './process-fabric.js';
+import { supervisorLoaderKey } from './supervisor-props.js';
 
 // ── Loaded-worker entrypoint plumbing ───────────────────────────────────────
 
@@ -56,7 +59,7 @@ export interface NimbusCtxExports {
       key: string;
       name: string | null;
       depth: number;
-      supervisor: { doId: string; pid: number; writerId: string };
+      supervisor: ResidentSupervisorProps;
       stage?: unknown;
     };
   }) => LoadedWorkerEntrypointStub;
@@ -78,7 +81,7 @@ export function getNimbusCtxExports(): NimbusCtxExports {
  */
 export async function createLoadedWorkerEntrypoint(
   ctxExports: NimbusCtxExports,
-  supervisor: { doId: string; pid: number; writerId: string },
+  supervisor: ResidentSupervisorProps,
   stage: unknown,
   name: string | null = null,
 ): Promise<LoadedWorkerEntrypointStub> {
@@ -87,7 +90,9 @@ export async function createLoadedWorkerEntrypoint(
   }
   return await ctxExports.NimbusLoadedEntrypoint({
     props: {
-      key: `nimbus-process:${supervisor.doId}:${supervisor.pid}`,
+      // The entrypoint's loader outlives this instance, and a warm worker keeps
+      // the SUPERVISOR binding it was built with.
+      key: supervisorLoaderKey(`nimbus-process:${supervisor.doId}:${supervisor.pid}`, supervisor),
       name,
       depth: 0,
       supervisor,
@@ -262,26 +267,25 @@ interface SlotBook {
   next: number;
   /** Slot held by each live pid, so release can find it. */
   held: Map<number, number>;
+  /** Explicit (`app-slot-`) names this incarnation started a process under and has not released. */
+  live: Set<string>;
 }
 
 /**
  * Slot books, per hosting actor, because the facet index is per Durable
  * Object.
  *
- * Keyed weakly off `ctx`, and that is sound rather than lossy: a facet cannot
- * outlive the Durable Object hosting it, so a book that goes away with its
- * host describes nothing that still exists. A fresh incarnation restarts at
- * slot 0 and re-attaches to the SQLite a previous incarnation left there —
- * which is safe for the reason the store is sealed until it has reconciled.
- * Its persisted cursor is either datable against the current authority, in
- * which case the ACQUIRE delta brings it current, or it carries a different
- * 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.
+ * Keyed weakly off `ctx`, so a book describes one incarnation. A facet that
+ * is still running when that incarnation ends outlives it (measured: a timer
+ * or an outgoing call keeps it going), and a `get` of its name with a new
+ * class then resets the whole object. So a fresh incarnation's first get of
+ * each name ends whatever runs there first: a minted `proc-slot-` name is
+ * deleted, which also wipes the storage a previous incarnation left, and an
+ * explicit name is aborted, which keeps it.
  *
- * 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
+ * The book allocates 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>();
@@ -289,24 +293,28 @@ const slotBooks = new WeakMap<DurableObjectState, SlotBook>();
 function slotBook(ctx: DurableObjectState): SlotBook {
   let book = slotBooks.get(ctx);
   if (!book) {
-    book = { free: [], next: 0, held: new Map() };
+    book = { free: [], next: 0, held: new Map(), live: new Set() };
     slotBooks.set(ctx, book);
   }
   return book;
 }
 
-/** Take a slot for `pid`, reusing a returned one before minting a new name. */
-function acquireSlot(ctx: DurableObjectState, pid: number): number {
+/**
+ * Take a slot for `pid`, reusing a returned one before minting a new name.
+ * `minted` names may still hold storage a previous incarnation of this actor
+ * left there, so the caller deletes it before the first get.
+ */
+function acquireSlot(ctx: DurableObjectState, pid: number): { slot: number; minted: boolean } {
   const book = slotBook(ctx);
   const existing = book.held.get(pid);
-  if (existing !== undefined) return existing;
+  if (existing !== undefined) return { slot: existing, minted: false };
   const reused = book.free.length > 0;
   const slot = reused ? book.free.shift()! : book.next++;
   book.held.set(pid, slot);
   // 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;
+  return { slot, minted: !reused };
 }
 
 /** Return `pid`'s slot to the free list. */
@@ -320,14 +328,36 @@ function releaseSlot(ctx: DurableObjectState, pid: number): void {
 }
 
 /**
- * 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.
+ * Drop one facet's SQLite by name, and its row in the session's storage
+ * ledger (N18) in the same step: the only way a facet database is deleted.
+ * `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.
  */
+/** The session's storage ledger (N18), over this actor's SQL; null where it has none. */
+function sessionLedger(ctx: DurableObjectState): StorageLedger | null {
+  const sql = (ctx as { storage?: { sql?: SqlDatabase } }).storage?.sql;
+  return sql ? new StorageLedger(sql) : null;
+}
+
+const facetNames = new WeakMap<object, Map<number, string>>();
+
+function facetOfPid(ctx: DurableObjectState): Map<number, string> {
+  let names = facetNames.get(ctx);
+  if (!names) facetNames.set(ctx, names = new Map());
+  return names;
+}
+
+/** The facet a running resident process `pid` lives in on this actor, for its storage ledger row. */
+export function residentFacetOf(ctx: DurableObjectState, pid: number): string | undefined {
+  return facetNames.get(ctx)?.get(pid);
+}
+
 export function deleteFacetStorage(ctx: DurableObjectState, name: string): void {
   facetContainer(ctx).delete(name);
+  const sql = (ctx as { storage?: { sql?: SqlDatabase } }).storage?.sql;
+  if (sql) forgetFacetStorage(sql, name);
 }
 
 
@@ -416,8 +446,12 @@ function spawnResident(
         + `prefix, got '${explicit.name}'`,
     );
   }
-  const slot = explicit ? undefined : acquireSlot(ctx, params.pid);
+  const grant = explicit ? undefined : acquireSlot(ctx, params.pid);
+  const slot = grant?.slot;
   const name = explicit ? explicit.name : residentFacetName(slot!);
+  if (grant?.minted) {
+    try { deleteFacetStorage(ctx, name); } catch { /* nothing stored under this name */ }
+  }
   // 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 —
@@ -439,27 +473,40 @@ function spawnResident(
     evaluated = true;
     return { class: residentProcessClass(ctx, env, disk, supervisor, params) };
   };
+  const book = slotBook(ctx);
+  const ledger = sessionLedger(ctx);
   let facet: ResidentFacetStub;
   try {
+    // N18: the fill is admitted, and recorded under the facet's name, before
+    // the facet exists; a refusal leaves no facet.
+    if (ledger !== null && params.storageBytes !== undefined) ledger.fill(name, params.storageBytes);
+    // get() with a new class on a facet an earlier incarnation left running resets this object.
+    if (explicit && !book.live.has(name)) {
+      facets.abort(name, new Error('Nimbus: a new incarnation takes this facet name'));
+    }
     facet = facets.get(name, start);
   } catch (error) {
     if (slot !== undefined) releaseSlot(ctx, params.pid);
     throw withFacetBudgetNamed(facetNameCount(ctx), error);
   }
+  if (explicit) book.live.add(name);
+  facetOfPid(ctx).set(params.pid, name);
 
   let disposed = false;
   const release = async () => {
     if (disposed) return;
     disposed = true;
     released = true;
+    facetOfPid(ctx).delete(params.pid);
     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
     // 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 */ }
+      try { deleteFacetStorage(ctx, 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.
@@ -468,7 +515,11 @@ function spawnResident(
 
   let started: Promise<unknown>;
   try {
-    started = facet.startProcess(params.startArgs);
+    // The allowance the ledger admitted, for the facet's store to keep under.
+    const startArgs = ledger !== null && params.storageBytes !== undefined && params.startArgs !== null && typeof params.startArgs === 'object'
+      ? { ...(params.startArgs as Record<string, unknown>), storage: { facet: name, grant: params.storageBytes } }
+      : params.startArgs;
+    started = facet.startProcess(startArgs);
   } catch (error) {
     void release();
     throw withFacetBudgetNamed(facetNameCount(ctx), error);
@@ -477,7 +528,17 @@ function spawnResident(
   // 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) => {
+  started = started.then((payload) => {
+    // Once the facet is up (N18) its row is the cap its store keeps under
+    // (what it measures plus what it may still grow into), or what it
+    // measures if that is more (overshoot).
+    const { databaseSize: size, storageCap: cap } = (payload ?? {}) as { databaseSize?: unknown; storageCap?: unknown };
+    const measured = typeof size === 'number' && Number.isFinite(size) ? size : null;
+    const capped = typeof cap === 'number' && Number.isFinite(cap) ? cap : null;
+    const row = capped !== null ? Math.max(capped, measured ?? 0) : measured;
+    if (ledger !== null && row !== null) ledger.reportSize(name, row);
+    return payload;
+  }, async (error) => {
     throw withFacetBudgetNamed(await facetNameCountDurable(ctx), error);
   });
   // A caller reads whichever of `started` and the lifecycle it needs, so keep
@@ -516,11 +577,14 @@ 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(params.workerKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
+      .get(loaderKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
       .getDurableObjectClass(RESIDENT_PROCESS_CLASS);
-    recordLoaderId(ctx, params.workerKey);
+    recordLoaderId(ctx, loaderKey);
     return worker;
   } catch (error) {
     throw withDynamicWorkerCapNamed(ctx, error);
@@ -541,7 +605,7 @@ async function runOneShot<T>(
         + 'the Worker Loader binding; add it via worker_loaders in wrangler.jsonc.',
     );
   }
-  const supervisorRpc = supervisorEntrypoint();
+  const supervisorRpc = supervisorEntrypoint(undefined, supervisor.route?.supervisorEntrypoint);
   let supervisorBinding: unknown;
   let worker: LoadedWorkerStub | undefined;
   let entrypoint: LoadedWorkerEntrypointStub | undefined;
@@ -626,11 +690,9 @@ export async function residentWorkerConfig(
     ? await stagedBootAssembler()(env, boot.stage)
     : await residentLoaderConfig(boot.code, disk());
   assertModuleMapWithinCodeLimit(configModules(config));
-  const supervisorRpc = supervisorEntrypoint();
+  const supervisorRpc = supervisorEntrypoint(undefined, supervisor.route?.supervisorEntrypoint);
   if (!supervisorRpc) {
-    throw new Error(
-      `Nimbus: ctx.exports.${supervisorEntrypointName() ?? '<supervisor entrypoint>'} unavailable`,
-    );
+    throw new Error(`Nimbus: ctx.exports.${supervisor.route?.supervisorEntrypoint ?? supervisorEntrypointName() ?? '<supervisor entrypoint>'} unavailable`);
   }
   return { ...config, env: { SUPERVISOR: supervisorRpc({ props: supervisor }) } };
 }