@nimbus-sh/worker 0.6.0 → 0.8.0

package/dist/session/programmatic.js

@@ -5,23 +5,29 @@
  * Durable Object exposes a typed, programmatic sandbox surface without
  * duplicating the interactive terminal boot path.
  */
-import { ensureRuntimesProgrammatic, installRuntimeProgrammatic, listAvailableRuntimes, } from '../runtime/package-manager.js';
-import { listInstalledRuntimes, } from '@nimbus-sh/core/runtime/installed-runtimes.js';
+/**
+ * session/programmatic.ts - public sandbox RPC helpers.
+ *
+ * These helpers are called by NimbusSession one-line delegators so the
+ * Durable Object exposes a typed, programmatic sandbox surface without
+ * duplicating the interactive terminal boot path.
+ */
+import { ensureRuntimesProgrammatic, installRuntimeProgrammatic } from '../runtime/package-manager.js';
 import { PID_GEN_STRIDE } from '@nimbus-sh/core/runtime/process-table.js';
 import { notifyTerminalEvent } from '../runtime/process-logs-api.js';
 import { SessionProcessSupervisor } from '@nimbus-sh/core/runtime/session-process-supervisor.js';
 import { PortRegistry, createPortCapability } from '@nimbus-sh/core/runtime/port-registry.js';
-import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
-import { endProcessInput, resizeProcess, signalProcess, writeProcessInput, } from '@nimbus-sh/core/runtime/process-input-routing.js';
+import { CRED_KERNEL, requireVfsCred } from '@nimbus-sh/core/runtime/os-contracts.js';
+import { endProcessInput, resizeProcess, signalProcess, writeProcessInput } from '@nimbus-sh/core/runtime/process-input-routing.js';
 import { z } from 'zod/v4';
 import { SESSION_DESTROYED_KEY, SHELL_STATE_KEY_PREFIX, VITE_CONFIG_KEY } from './keys.js';
-import { clearPortCapability, isValidAppName, persistPortCapability, PortRecordSchema, portRecordKey, readPortReservation, readPortReservationByName, readPortReservationByOwner, reservePort, restorePortCapability, rotatePortCapability, } from './port-capability.js';
-import { PORT_CAPABILITY_KEY_PREFIX } from './keys.js';
+import { clearPortCapability, isValidAppName, persistPortCapability, portRecordKey, readPortReservation, readPortReservationByName, readPortReservationByOwner, reservePort, restorePortCapability, rotatePortCapability } from './port-capability.js';
 import { bindPublicPortCapability, unbindPublicPortCapability } from '../router/public-directory.js';
-import { buildPreviewHost, buildPublicPreviewHost, isPreviewHostSafeSid, readPreviewHostSuffix, } from '../_shared/preview-host.js';
+import { buildPreviewHost, buildPublicPreviewHost, isPreviewHostSafeSid, readPreviewHostSuffix } from '../_shared/preview-host.js';
 import { RESTART_POLICY_ENV } from '../facets/manager.js';
 import { GENERATION_KEY, assumeGeneration, generation } from '@nimbus-sh/fabric/generation.js';
 import { HeadlessTerminal, Shell } from '@nimbus-sh/core/substrate/lifo/index.js';
+import { textSink } from '@nimbus-sh/core/_shared/bytes.js';
 const ShellIdSchema = z.string().min(1).max(160).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
 const ShellStateSchema = z.object({
     cwd: z.string().startsWith('/'),
@@ -113,35 +119,6 @@ const ProcessLogsOptionsSchema = z.object({
     lines: z.number().int().nonnegative().optional(),
     bytes: z.number().int().nonnegative().optional(),
 }).strict();
-function makeHeadlessWebSocket() {
-    const listeners = new Map();
-    const state = { readyState: 1 };
-    const ws = {
-        get readyState() { return state.readyState; },
-        send(_data) { },
-        close() {
-            state.readyState = 3;
-            for (const cb of listeners.get('close') ?? []) {
-                try {
-                    cb();
-                }
-                catch { }
-            }
-        },
-        accept() { },
-        addEventListener(type, cb) {
-            const set = listeners.get(type) ?? new Set();
-            set.add(cb);
-            listeners.set(type, set);
-        },
-        removeEventListener(type, cb) {
-            listeners.get(type)?.delete(cb);
-        },
-        serializeAttachment(_value) { },
-        deserializeAttachment() { return { kind: 'programmatic' }; },
-    };
-    return ws;
-}
 function getHome(self) {
     try {
         const envHome = self.shell?.env?.HOME;
@@ -164,23 +141,14 @@ function runtimeDeps(self) {
     if (!self._cpRegistry)
         throw new Error('Nimbus shell registry did not initialize');
     return {
-        env: self.env,
-        vfs: self.sqliteFs,
+        runtimes: self.runtimeManager,
+        vfs: self.sqliteFs.as(CRED_KERNEL),
         registry: self._cpRegistry,
         getHome: () => getHome(self),
     };
 }
 export async function ensureProgrammaticReady(self, options = {}) {
-    if (!self.shell) {
-        await self.initSession(makeHeadlessWebSocket());
-        // A programmatic boot owns no terminal socket, which is what
-        // 'drained' reports to the diagnostics and the recovery ring.
-        self._b4Phase = 'drained';
-    }
-    else {
-        self.ensureSqliteFs();
-        self.ensureFacetManager();
-    }
+    await self.ensureRuntimeReady();
     const preinstall = Array.from(new Set(options.preinstall ?? []))
         .map((s) => String(s).trim())
         .filter(Boolean);
@@ -218,14 +186,13 @@ function startShellJob(self, command, options, job, scoped) {
         catch { /* already settled */ }
     });
     const emit = (stream, sink) => (data) => {
-        const text = String(data);
         if (job.background) {
             try {
-                self.processes.appendOutput(pid, stream, text);
+                self.processes.appendOutputBytes(pid, stream, data);
             }
             catch { /* ring gone */ }
         }
-        sink?.(text);
+        sink?.(data);
     };
     const run = shell.execute(line, {
         // A named shell already holds its own cwd and env; passing them again
@@ -261,7 +228,20 @@ function startShellJob(self, command, options, job, scoped) {
         }
         catch { } } };
 }
+/**
+ * The shell, process table and VFS all key on absolute POSIX paths. A
+ * relative `cwd` arriving here means a caller skipped its own boundary
+ * normalization (the SDK resolves it); handed to the shell it degrades to
+ * silently wrong cwd semantics and ENOENT writes. Name the field and fail.
+ */
+function assertAbsoluteExecCwd(options) {
+    const cwd = options.cwd;
+    if (cwd !== undefined && (typeof cwd !== 'string' || !cwd.startsWith('/'))) {
+        throw new Error(`cwd must be an absolute POSIX path starting with '/', got ${JSON.stringify(cwd)}`);
+    }
+}
 export async function rpcExec(self, command, options = {}) {
+    assertAbsoluteExecCwd(options);
     await ensureProgrammaticReady(self, options);
     return withShellState(self, options, false, (scoped) => execOnShell(self, command, options, scoped));
 }
@@ -273,8 +253,8 @@ async function execOnShell(self, command, options, scoped) {
     let timedOut = false;
     const job = startShellJob(self, command, options, {
         background: false,
-        onStdout: (d) => stdout.push(d),
-        onStderr: (d) => stderr.push(d),
+        onStdout: textSink((d) => stdout.push(d)),
+        onStderr: textSink((d) => stderr.push(d)),
     }, scoped);
     let result;
     try {
@@ -353,6 +333,7 @@ function collectJobOutput(self, pid) {
  * process surface (`listProcesses`, `processLogs`, `killProcess`).
  */
 export async function rpcStartProcess(self, command, options = {}) {
+    assertAbsoluteExecCwd(options);
     await ensureProgrammaticReady(self, options);
     if (options.restart !== undefined && options.restart !== 'never' && options.restart !== 'on-failure') {
         throw new Error(`startProcess: restart must be 'never' or 'on-failure', got ${String(options.restart)}`);
@@ -408,7 +389,15 @@ async function startOnShell(self, command, options, scoped) {
  * the handoff, the facet is the live process, and it reports its own exit.
  */
 function finishBackgroundJob(self, pid, command, exitCode) {
-    if (exitCode === 0 && self.facetManager?.hasResidentProcess(pid))
+    // The shell line returned, but the pid may still be serving: a resident
+    // facet the node runner handed off under this pid, or an in-process dev
+    // server a builtin (`vite`) adopted this pid for and registered a port
+    // under. Either way the process is alive — marking it exited would put a
+    // dead pid on a live port, and the app verbs identify a server by the pid
+    // serving its port.
+    const stillServing = self.facetManager?.hasResidentProcess(pid) === true
+        || self.portRegistry.getAll().some((live) => live.pid === pid);
+    if (exitCode === 0 && stillServing)
         return;
     self.processes.exit(pid, exitCode);
     if (!self.processes.getExit(pid))
@@ -447,8 +436,8 @@ export async function rpcEnsureRuntimes(self, specs, options = {}) {
 export async function rpcListRuntimes(self) {
     await ensureProgrammaticReady(self);
     return {
-        installed: listInstalledRuntimes(self.sqliteFs, getHome(self)),
-        available: await listAvailableRuntimes(self.env),
+        installed: self.runtimeManager.list(),
+        available: await self.runtimeManager.available(),
     };
 }
 export async function rpcListProcesses(self) {
@@ -528,12 +517,9 @@ export async function rpcProcessLogs(self, pid, options = {}) {
 }
 export async function rpcListPorts(self) {
     await ensureProgrammaticReady(self);
-    const entries = self.portRegistry.getAll();
-    // Persisted at the moment the embedder is told the value, not at
-    // registration: a capability nobody has been handed does not need to
-    // survive anything.
-    await Promise.all(entries.map((entry) => persistPortCapability(self, entry.port, entry.capability)));
-    return entries.map(serializePort);
+    // The composed manager's copy is the one implementation — persistence
+    // at tell-time included.
+    return self.ensureFacetManager().apps.listPorts();
 }
 /**
  * Browser-facing URL for an application, built inside the session: the
@@ -612,8 +598,9 @@ export async function rpcExposeApp(self, target, options = {}) {
         throw new Error(`${describeTarget(target)} has not bound a port yet — expose it once it is listening`);
     }
     if (resolved.owner === null) {
-        throw new Error(`${describeTarget(target)} has no launch record to bind an identity to — `
-            + 'only journalled residents carry one; use ports.expose for a bare port');
+        // Every running process has an identity, so this is only a port nothing
+        // serves and no reservation names.
+        throw new Error(`nothing is serving ${describeTarget(target)} — start the server, then expose it`);
     }
     const exposed = await applyExposure(self, resolved.port, resolved.owner, options);
     const live = self.portRegistry.get(resolved.port);
@@ -791,7 +778,23 @@ export async function rpcRemoveApp(self, target) {
     if (resolved.owner === null) {
         throw new Error(`${describeTarget(target)} names no application — nothing to remove`);
     }
-    return rpcRemoveDurableApp(self, resolved.owner);
+    const owner = resolved.owner;
+    // The manager's removal kills what the journal knows. A server nothing
+    // journalled — the dev servers above all — is found the way every verb
+    // finds it, by the identity of the pid serving a port, and ended through
+    // the session's own kill, which is the one that also stops an in-process
+    // dev server rather than only marking its pid dead.
+    const fm = self.facetManager;
+    let killed = 0;
+    for (const live of self.portRegistry.getAll()) {
+        const identity = await fm.residentIdentity(live.pid);
+        if (identity === null || identity.ephemeral || identity.owner !== owner)
+            continue;
+        if ((await rpcKillProcess(self, live.pid)).ok)
+            killed += 1;
+    }
+    const durable = await rpcRemoveDurableApp(self, owner);
+    return { ...durable, removed: durable.removed || killed > 0 };
 }
 function describeTarget(target) {
     if (typeof target === 'number')
@@ -873,7 +876,7 @@ async function resolveAppTarget(self, target) {
     if ('pid' in target) {
         const asPid = await byPid(Number(target.pid));
         if (asPid === null) {
-            throw new Error(`pid ${target.pid} has no launch record — only journalled residents carry one`);
+            throw new Error(`pid ${target.pid} is not running and has no launch record`);
         }
         return asPid;
     }
@@ -898,32 +901,10 @@ async function resolveAppTarget(self, target) {
  */
 export async function rpcEnsureDurableApp(self, input) {
     await ensureProgrammaticReady(self);
-    const owner = input.owner;
-    if (typeof owner !== 'string' || owner.length === 0) {
-        throw new Error('ensureDurableApp: owner must be a non-empty string');
-    }
-    const occupied = new Set(self.portRegistry.getAll().map((entry) => entry.port));
-    const port = await reservePort(self.ctx, {
-        owner,
-        preferredPort: input.preferredPort,
-        occupiedPorts: occupied,
-        // Minted here, not at boot: the URL is built from this capability, and
-        // re-drive re-adopts it out of the same row.
-        capability: createPortCapability(),
-        ...(input.visibility !== undefined ? { visibility: input.visibility } : {}),
-    });
-    const record = await readPortReservation(self.ctx, port);
-    if (record?.visibility === 'public' && record.capability !== null) {
-        // The URL is built on this capability before the app has ever run:
-        // publish it to the directory now, loudly refusing a deployment whose
-        // binding is missing rather than minting an unroutable URL.
-        await bindPublicPortCapability(self, record.capability, port);
-    }
-    return {
-        port,
-        capability: record?.capability ?? null,
-        visibility: record?.visibility ?? 'scoped',
-    };
+    // The composed manager owns the durable-app verbs — one implementation,
+    // capability minted there so a URL handed out before boot is the one the
+    // eventual binding re-adopts.
+    return self.ensureFacetManager().apps.ensureDurableApp(input);
 }
 export async function rpcUnexposePort(self, port) {
     await ensureProgrammaticReady(self);
@@ -946,26 +927,8 @@ export async function rpcUnexposePort(self, port) {
  */
 export async function rpcRemoveDurableApp(self, owner) {
     await ensureProgrammaticReady(self);
-    if (typeof owner !== 'string' || owner.length === 0) {
-        throw new Error('removeDurableApp: owner must be a non-empty string');
-    }
-    // Which durable address is being released — the reservation's row names it
-    // before the manager retires it.
-    const rows = await self.ctx.storage.list({ prefix: PORT_CAPABILITY_KEY_PREFIX });
-    let port = null;
-    for (const [key, record] of rows) {
-        const parsed = PortRecordSchema.safeParse(record);
-        if (!parsed.success || parsed.data.owner !== owner)
-            continue;
-        const n = Number(key.slice(PORT_CAPABILITY_KEY_PREFIX.length));
-        if (Number.isInteger(n) && n > 0) {
-            port = n;
-            break;
-        }
-    }
-    self.ensureFacetManager();
-    const removed = await self.facetManager.removeDurableApp(owner);
-    return { owner, removed, port };
+    // The composed manager owns the durable-app verbs — validation included.
+    return self.ensureFacetManager().apps.removeDurableApp(owner);
 }
 /**
  * Route an embedder request that carries a port capability. The embedder has
@@ -983,10 +946,34 @@ export async function rpcRouteCapabilityPort(self, port, capability, request, pa
     const routed = await self.portRegistry.routeCapabilityRequest(Number(port), String(capability), request, pathname);
     return routed ?? new Response('Not found', { status: 404 });
 }
-export async function rpcDeleteFile(self, path, options = {}) {
+/**
+ * `spawnWorker` for a colocated embedder holding the DO stub: boot the
+ * embedder's own Worker-class program — its main module, inline modules and
+ * content-addressed text/wasm modules — as one of this session's resident
+ * processes, and answer with the pid, the runner's boot payload and the
+ * process's facet (`fetch`/`connect`, bound to the resident handle; no
+ * release — `killProcess(pid)` ends it). Deliberately absent from the remote
+ * HTTP dispatcher: the facet is a live handle, and a remote token holder is
+ * not the embedder.
+ */
+export async function rpcSpawnWorker(self, workerCode, command, cwd, opts = {}) {
+    await ensureProgrammaticReady(self);
+    if (typeof workerCode !== 'string' || workerCode.length === 0) {
+        throw new Error('spawnWorker: workerCode must be a non-empty string');
+    }
+    self.ensureFacetManager();
+    return self.facetManager.spawnWorker(workerCode, String(command), String(cwd), opts);
+}
+/**
+ * `files.delete`. Absent a `cred` this acts as CRED_KERNEL — what it has
+ * always done, and the embedder's trusted surface: only a caller holding the
+ * DO binding reaches it. A `cred` binds the removal to that identity instead,
+ * the same view `SqliteVFS.as(cred)` gives in-process.
+ */
+export async function rpcDeleteFile(self, path, options = {}, cred) {
     await ensureProgrammaticReady(self);
     const p = String(path).replace(/^\/+/, '');
-    const vfs = self.sqliteFs.as(CRED_KERNEL);
+    const vfs = self.sqliteFs.as(cred === undefined ? CRED_KERNEL : requireVfsCred(cred, 'files.delete'));
     if (!vfs.exists(p))
         return;
     if (vfs.isDirectory(p)) {
@@ -1212,10 +1199,17 @@ function resetInMemorySessionState(self) {
     self.shell = null;
     self.shellProcessPid = null;
     self.terminal = null;
-    self.facetManager = null;
+    self.facetManagerComposed = null;
     self.facetProcessManager = null;
     self.esbuildService = null;
     self.viteDevServer = null;
+    // The installer's pre-bundler and the dev server's on-demand path share
+    // this pool; it goes when both of them go.
+    try {
+        self.bundlePool?.dispose();
+    }
+    catch { }
+    self.bundlePool = null;
     self.cirrusReal = null;
     self._cirrusHmrWsClients = null;
     self.nimbusWrangler = null;

package/dist/session/routes.d.ts

@@ -25,24 +25,22 @@
  */
 type RoutesHost = any;
 /**
- * Route a request to whatever is listening on a session port.
- *
- * The one implementation behind every port-addressed surface: `/port/<n>/`,
- * `/preview/?port=N`, and the `<port>--<sid>` preview hostname, which the
- * router forwards as `/port/<n>/`. They differ only in how the port and the
- * inner path are spelled, so they must not differ in what answers.
- *
- * `mountBase` is the public URL prefix the served app is mounted at for THIS
- * request — '' for a root-mounted `<port>--<sid>` host, '/s/<sid>/preview' for
- * the preview path. The in-process Cirrus dev server rewrites base-relative
- * URLs (module URLs, <base href>, BASE_URL, router basename), so it is handed
- * the base directly: the generic port proxy strips the Nimbus base header at
- * the untrusted-code boundary and cannot carry it, and a plain user server on
- * any other port is mounted at root and needs no rewriting.
+ * Restore the dev server a previous isolate left behind.
+ *
+ * Hibernation takes the ViteDevServer and the whole port registry with it;
+ * only the `vite-config` blob survives in DO storage. Restoring it is the
+ * first thing every route that can reach that server does, so a woken session
+ * serves on all of them rather than on whichever one happened to carry the
+ * restore.
+ *
+ * `onlyPort` scopes the restore to a config that would listen there: a
+ * request for a port nothing ever persisted stays an honest 502, and a port
+ * something else already holds is left alone.
+ *
+ * Idempotent, and silent on failure — a session with no dev server to restore
+ * is the normal case, not an error.
  */
-export declare function routeToSessionPort(self: RoutesHost, port: number, request: Request, innerPath: string, mountBase: string, capability?: string): Promise<Response>;
-/** Route a capability-authenticated embedder request to a guest HTTP server. */
-export declare function routeCapabilityPort(self: RoutesHost, port: number, capability: string, request: Request, innerPath: string): Promise<Response>;
+export declare function restorePersistedDevServer(self: RoutesHost, onlyPort?: number): Promise<void>;
 /**
  * The name-addressed door: `/app/<name>/…` — what the scoped `<name>--<sid>`
  * host is forwarded as, and reachable in path form as `/s/<sid>/app/<name>/`.
@@ -52,6 +50,21 @@ export declare function routeCapabilityPort(self: RoutesHost, port: number, capa
  * nothing holds is a 404, never a guess.
  */
 export declare function routeToSessionApp(self: RoutesHost, name: string, request: Request, innerPath: string, capability?: string): Promise<Response>;
+/**
+ * Accept a Vite HMR WebSocket for the running cirrus-real facet and wire it
+ * into the facet's HMR bridge.
+ *
+ * Handled in the DO, never through the port-registry proxy: that proxy moves a
+ * Request/Response over RPC and drops the `webSocket` handshake, so a HMR
+ * upgrade routed through it hangs. This is the ONE place a preview HMR socket
+ * is accepted — shared by the `/preview/` path and the `<port>--<sid>` host's
+ * `/port/N` route, so HMR works the same on both.
+ *
+ * ctx.acceptWebSocket (hibernatable) is required because HMR messages arrive
+ * from a DIFFERENT request context (the facet's long-poll RPC), and workerd
+ * forbids cross-request I/O on a `server.accept()`'d socket.
+ */
+export declare function acceptCirrusHmrWs(self: RoutesHost, request: Request): Response;
 export declare function handleFetch(self: RoutesHost, request: Request): Promise<Response>;
 export {};
 //# sourceMappingURL=routes.d.ts.map

package/dist/session/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/session/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAyDH,KAAK,UAAU,GAAG,GAAG,CAAC;AA2HtB;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,QAAQ,CAAC,CAyDnB;AA2BD,gFAAgF;AAChF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAeD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,QAAQ,CAAC,CAMnB;AA4FD,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmhCvF"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/session/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAkEH,KAAK,UAAU,GAAG,GAAG,CAAC;AAyBtB;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFlG;AAeD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,QAAQ,CAAC,CAMnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,QAAQ,CAiB9E;AAmDD,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CA0hCvF"}