@nimbus-sh/core 0.1.0

package/src/runtime/process-table.ts

@@ -0,0 +1,225 @@
+import { CRED_SESSION_USER, type VfsCred } from './os-contracts.js';
+
+/**
+ * ProcessTable — PID allocation and process lifecycle state.
+ *
+ * Each `node script.js` invocation gets a PID. The supervisor uses this
+ * to route signals (kill) and track running processes. Owned by
+ * SessionProcessSupervisor; callers go through that facade.
+ */
+
+export type ProcessState = 'running' | 'exited' | 'killed';
+
+export interface ProcessEntry {
+  pid: number;
+  command: string;       // e.g. "node hello.js" or "node -e ..."
+  argv: string[];
+  cwd: string;
+  state: ProcessState;
+  exitCode: number | null;
+  startTime: number;
+  endTime: number | null;
+  cred: VfsCred;
+  /** Spawning process, when the spawn declared one. Roots have none. */
+  parentPid?: number;
+  /** Explicit long-running flag set when a command is handed to a
+   *  long-lived Worker Loader or shell execution path. */
+  longRunning?: boolean;
+  /** Output is owned by a process-terminal attachment, not the parent shell. */
+  attachedTty?: boolean;
+}
+
+export interface ProcessTableSpawnOptions {
+  cred?: VfsCred;
+  parentPid?: number;
+}
+
+function immutableCred(cred: VfsCred): VfsCred {
+  return Object.freeze({
+    uid: cred.uid,
+    gid: cred.gid,
+    groups: Object.freeze([...cred.groups]),
+    umask: cred.umask,
+  });
+}
+
+/**
+ * Pid-space stride per DO instance generation. Pids are allocated as
+ * `generation * PID_GEN_STRIDE + seq`, so pid-keyed state that OUTLIVES an
+ * instance reset — hibernatable process-terminal WebSocket attachments,
+ * persisted w9_proc_logs rows, named Worker Loader isolate keys, and
+ * still-running facets from the previous instance — can never collide with
+ * (or bleed into) a pid allocated by the next instance. A pid at or below
+ * the current base is by construction from a PREVIOUS generation.
+ */
+export const PID_GEN_STRIDE = 1_000_000;
+
+export class ProcessTable {
+  private nextPid = 1;
+  private base = 0;
+  private processes = new Map<number, ProcessEntry>();
+
+  /**
+   * Move the pid space onto this instance generation's range. Called once at
+   * DO boot (before any event runs) with `isolateGen * PID_GEN_STRIDE`.
+   * Monotonic and idempotent — never moves pids backwards.
+   */
+  setPidBase(base: number): void {
+    if (!Number.isFinite(base) || base <= this.base) return;
+    this.base = base;
+    this.nextPid = Math.max(this.nextPid, base + 1);
+  }
+
+  /** The current generation's pid floor: pids <= base are prior-generation. */
+  get pidBase(): number {
+    return this.base;
+  }
+
+  /** Allocate a PID and register a new process. */
+  spawn(
+    command: string,
+    argv: string[],
+    cwd: string,
+    options: ProcessTableSpawnOptions = {},
+  ): ProcessEntry {
+    const inheritedCred = options.parentPid === undefined
+      ? CRED_SESSION_USER
+      : this.credOf(options.parentPid);
+    const pid = this.nextPid++;
+    const entry: ProcessEntry = {
+      pid,
+      command,
+      argv,
+      cwd,
+      state: 'running',
+      exitCode: null,
+      startTime: Date.now(),
+      endTime: null,
+      cred: immutableCred(options.cred ?? inheritedCred),
+      parentPid: options.parentPid,
+    };
+    this.processes.set(pid, entry);
+    return entry;
+  }
+
+  credOf(pid: number): VfsCred {
+    const entry = this.processes.get(pid);
+    if (!entry) throw new Error(`process pid ${pid} does not exist`);
+    return immutableCred(entry.cred);
+  }
+
+  cred(pid: number): VfsCred {
+    return this.credOf(pid);
+  }
+
+  setUmask(pid: number, umask: number): number {
+    const entry = this.processes.get(pid);
+    if (!entry) throw new Error(`process pid ${pid} does not exist`);
+    if (!Number.isInteger(umask) || umask < 0 || umask > 0o777) {
+      throw new Error(`invalid umask ${umask}`);
+    }
+    const previous = entry.cred.umask;
+    entry.cred = immutableCred({ ...entry.cred, umask });
+    return previous;
+  }
+
+  /** child-process isolation: mark an existing entry as long-running. Idempotent. */
+  setLongRunning(pid: number): void {
+    const entry = this.processes.get(pid);
+    if (entry) entry.longRunning = true;
+  }
+
+  /** Mark an existing entry as an attached terminal process. Idempotent. */
+  setAttachedTty(pid: number): void {
+    const entry = this.processes.get(pid);
+    if (entry) entry.attachedTty = true;
+  }
+
+  /**
+   * Mark a process as exited.
+   *
+   * Once a process reaches a terminal state (`killed` or `exited`),
+   * subsequent exit() calls
+   * are no-ops — the first terminal state wins.
+   *
+   * Without this guard, a `kill <pid>` (which sets state='killed',
+   * exitCode=137) followed by the facet's own crash-catch (which calls
+   * exit(pid, 1)) clobbers the kill signal with an exited/1 reading.
+   * `ps` then disagrees with the ring-buffer footer that still says
+   * "[process killed: killed]".
+   */
+  exit(pid: number, exitCode: number): void {
+    const entry = this.processes.get(pid);
+    if (!entry) return;
+    if (entry.state !== 'running') return; // first terminal state wins
+    entry.state = 'exited';
+    entry.exitCode = exitCode;
+    entry.endTime = Date.now();
+  }
+
+  /** Mark a process as killed. */
+  kill(pid: number): boolean {
+    const entry = this.processes.get(pid);
+    if (!entry || entry.state !== 'running') return false;
+    entry.state = 'killed';
+    entry.exitCode = 137; // SIGKILL
+    entry.endTime = Date.now();
+    return true;
+  }
+
+  get(pid: number): ProcessEntry | undefined {
+    return this.processes.get(pid);
+  }
+
+  getRunning(): ProcessEntry[] {
+    return [...this.processes.values()].filter(p => p.state === 'running');
+  }
+
+  getAll(): ProcessEntry[] {
+    return [...this.processes.values()];
+  }
+
+  /**
+   * Every process spawned under `pid`, transitively, oldest first.
+   *
+   * Output attribution needs this: a command's console output can land in a
+   * child's log ring (an npm bin, a facet-backed runtime) rather than on the
+   * caller's streams, and a start-time window is not a safe substitute when
+   * several commands run concurrently in one session.
+   */
+  descendantsOf(pid: number): ProcessEntry[] {
+    const found: ProcessEntry[] = [];
+    const frontier = new Set<number>([pid]);
+    for (const entry of [...this.processes.values()].sort((a, b) => a.startTime - b.startTime)) {
+      if (entry.parentPid !== undefined && frontier.has(entry.parentPid)) {
+        frontier.add(entry.pid);
+        found.push(entry);
+      }
+    }
+    return found;
+  }
+
+  /** Clean up exited processes older than maxAge ms. */
+  reap(maxAge = 60_000): number {
+    const now = Date.now();
+    let reaped = 0;
+    for (const [pid, entry] of this.processes) {
+      if (entry.state !== 'running' && entry.endTime && now - entry.endTime > maxAge) {
+        this.processes.delete(pid);
+        reaped++;
+      }
+    }
+    return reaped;
+  }
+
+  get stats() {
+    const all = [...this.processes.values()];
+    return {
+      total: all.length,
+      running: all.filter(p => p.state === 'running').length,
+      exited: all.filter(p => p.state === 'exited').length,
+      killed: all.filter(p => p.state === 'killed').length,
+      nextPid: this.nextPid,
+    };
+  }
+}

package/src/runtime/project-detect.ts

@@ -0,0 +1,42 @@
+/**
+ * project-detect.ts — small, dependency-free project-type detectors.
+ *
+ * Lives in its own module so unit tests + diag endpoints can import the
+ * detection helpers without pulling in nimbus-session.ts (which depends
+ * on `cloudflare:workers` and won't load under Bun).
+ *
+ * Currently exports detectCloudflareWorkersProject — added in W10 as the
+ * canonical "is this a Cloudflare Workers project?" check. Future waves
+ * can add detectVite, detectNext, etc. here.
+ */
+
+/**
+ * W10: detect whether the project at `<root>` is a Cloudflare Workers
+ * project. Returns true if any of the standard markers are present:
+ *   - <root>/wrangler.jsonc
+ *   - <root>/wrangler.json
+ *   - <root>/wrangler.toml
+ *   - <root>/package.json with `wrangler` in deps or devDeps
+ */
+export function detectCloudflareWorkersProject(vfs: any, root: string): boolean {
+  const r = String(root).replace(/^\/+/, '').replace(/\/+$/, '');
+  for (const f of ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml']) {
+    try {
+      if (vfs.exists((r ? r + '/' : '') + f)) return true;
+    } catch {}
+  }
+  try {
+    const pkgPath = (r ? r + '/' : '') + 'package.json';
+    if (vfs.exists(pkgPath)) {
+      const text = vfs.readFileString(pkgPath);
+      const pkg = JSON.parse(text);
+      if (pkg && typeof pkg === 'object') {
+        if (pkg.devDependencies && typeof pkg.devDependencies === 'object' && 'wrangler' in pkg.devDependencies) return true;
+        if (pkg.dependencies && typeof pkg.dependencies === 'object' && 'wrangler' in pkg.dependencies) return true;
+      }
+    }
+  } catch {
+    // Malformed package.json or any other read error: not a CF Workers project per this signal.
+  }
+  return false;
+}

package/src/runtime/python-server-adapter.ts

@@ -0,0 +1,133 @@
+/**
+ * python-server-adapter.ts — the bridge between a blocking-server API and a
+ * request-driven host.
+ *
+ * THIS IS NOT A WORKAROUND, AND DELETING IT BREAKS EVERY PYTHON SERVER.
+ *
+ * `socketserver.BaseServer.serve_forever()` does not return. That is fine on a
+ * machine where the process owns its own lifetime, and impossible here: a
+ * request context is torn down when its response is sent, so a program still
+ * sitting inside serve_forever when the invocation ends is a program that
+ * stops existing. The server has to be reachable AFTER the call that started
+ * it returned.
+ *
+ * Every language needs an answer to this and each one looks different enough
+ * to be mistaken for a language-specific hack. Ruby's answer is a Fiber that
+ * parks in accept and is resumed per request (ruby-runner.ts). Python's is
+ * here: serve_forever registers the server and returns immediately, the program
+ * runs to completion, and each inbound request re-enters the interpreter and
+ * dispatches one request into the registered object. The server's state lives
+ * on the Python heap between entries, which is exactly what a reactor build
+ * gives us — no suspended stack is involved, and none is needed.
+ *
+ * It is worth being explicit about what this file is NOT, because its
+ * predecessor bundled both and was deleted for it. The old python-socket-shim
+ * also reimplemented `socket` itself, because Pyodide had no working socket
+ * layer and could not block on a host promise. That half is gone for good: this
+ * interpreter has real sockets over nimbus-net.c and real OpenSSL, so
+ * connect/send/recv are the standard library's. A proof that one half is
+ * obsolete says nothing about the other.
+ */
+
+/** Injected into __main__ before the user's program runs. */
+export const PYTHON_SERVER_ADAPTER = String.raw`
+import sys
+
+_nimbus_servers = {}
+
+
+def _nimbus_patch_socketserver():
+    """Make serve_forever() return, and remember the server so the host can
+    drive it. Idempotent: the marker keeps a second injection from stacking
+    another wrapper on the first."""
+    try:
+        import socketserver as _socketserver
+    except Exception:
+        return
+    if getattr(_socketserver.BaseServer.serve_forever, "_nimbus_request_driven", False):
+        return
+
+    _orig_shutdown = _socketserver.BaseServer.shutdown
+
+    def _serve_forever(self, poll_interval=0.5):
+        sock = getattr(self, "socket", None)
+        if sock is not None:
+            try:
+                _nimbus_servers[int(sock.getsockname()[1])] = self
+                # The loop did not end, so the host owns this server's lifetime
+                # from here. Anything the program does on the way out of the
+                # block it started the server in is cleanup after a loop it
+                # believes returned, and must not take the listener down.
+                self._nimbus_adopted = True
+            except Exception:
+                pass
+        # Callers block on this event to know the loop has stopped. It never
+        # ran, so it is already true.
+        shut_down = getattr(self, "_BaseServer__is_shut_down", None)
+        if shut_down is not None:
+            shut_down.set()
+        return None
+
+    def _shutdown(self):
+        # The explicit "stop serving" call, and the only thing that hands the
+        # server back to the program. A later server_close() then really closes.
+        self._nimbus_adopted = False
+        return _orig_shutdown(self)
+
+    def _wrap_server_close(original):
+        def _server_close(self):
+            # python -m http.server runs its server inside a with-block, so the
+            # close arrives the instant serve_forever returns. Honouring it shut
+            # the listening socket before the first request could reach it.
+            if getattr(self, "_nimbus_adopted", False):
+                return None
+            sock = getattr(self, "socket", None)
+            if sock is not None:
+                try:
+                    _nimbus_servers.pop(int(sock.getsockname()[1]), None)
+                except Exception:
+                    pass
+            return original(self)
+        return _server_close
+
+    def _process_request_sync(self, request, client_address):
+        # ThreadingMixIn would hand the request to a thread that will never be
+        # scheduled. One request per host entry, inline.
+        try:
+            self.finish_request(request, client_address)
+            self.shutdown_request(request)
+        except Exception:
+            self.handle_error(request, client_address)
+            self.shutdown_request(request)
+
+    _serve_forever._nimbus_request_driven = True
+    _socketserver.BaseServer.serve_forever = _serve_forever
+    _socketserver.BaseServer.shutdown = _shutdown
+    # Both, because TCPServer defines its own server_close and every server
+    # anyone runs here derives from it — patching only the base class left the
+    # one that actually closes the socket untouched.
+    for _cls in (_socketserver.BaseServer, _socketserver.TCPServer):
+        _cls.server_close = _wrap_server_close(_cls.__dict__["server_close"])
+    try:
+        _socketserver.ThreadingMixIn.process_request = _process_request_sync
+    except Exception:
+        pass
+
+
+def _nimbus_serve_one(port):
+    """Handle exactly one queued connection. The host calls this per inbound
+    request, after the kernel has already queued the connection — so the
+    accept() inside never waits on anything."""
+    server = _nimbus_servers.get(int(port))
+    if server is None:
+        return False
+    server._handle_request_noblock()
+    return True
+
+
+def _nimbus_listening_ports():
+    return sorted(_nimbus_servers.keys())
+
+
+_nimbus_patch_socketserver()
+`;