@nimbus-sh/core 0.1.0

package/src/_shared/retry.ts

@@ -0,0 +1,202 @@
+/**
+ * retry.ts — small, dependency-free retry helper for flaky HTTP GETs.
+ *
+ * The npm path (resolver packument fetches + tarball fetches) talks to
+ * registry.npmjs.org via Cloudflare's edge. Either hop can produce a
+ * transient 5xx — we've seen HTTP 503 on a single tarball out of 456
+ * kill a whole install. npm's client retries 5xx by default; we didn't,
+ * until this file. Any single transient failure across hundreds of
+ * packages = whole install dead.
+ *
+ * Scope:
+ *   - Retries on 5xx (500/502/503/504 especially) and network errors
+ *     (fetch rejection, AbortError timeout, etc.).
+ *   - Does NOT retry on 4xx (those are hard: 404 means the package or
+ *     version genuinely doesn't exist; retrying is wrong and wastes time).
+ *   - Budget: 3 retries with jittered exponential backoff (500/1500/4500 ms
+ *     ±25% jitter). Worst-case added latency per package ≈ 6.5 s in the
+ *     fully-degraded path. Tighter than npm's ~5×60s because dev iteration
+ *     speed matters more than absolute resilience here.
+ *
+ * Facet tasks are serialized via fn.toString() and cannot import this
+ * helper. resolve-one-facet.ts and install-batch-facet.ts therefore keep
+ * equivalent retry loops inside their isolated function bodies.
+ */
+
+import { disposeRpcResource } from './rpc-dispose.js';
+
+/** Default retry count AFTER the first attempt (3 = up to 4 total attempts). */
+export const DEFAULT_RETRIES = 3;
+
+/** Base backoff delays in ms. Index = retry attempt (0-indexed). */
+export const BACKOFF_MS: readonly number[] = [500, 1500, 4500];
+
+/** Jitter ±25% of the base delay, uniformly distributed. */
+export function jittered(baseMs: number): number {
+  const span = baseMs * 0.25;
+  // Math.random is fine here — cryptographic randomness is not required;
+  // the goal is to break up synchronized retries across concurrent fetches
+  // after a shared upstream hiccup.
+  return Math.max(0, Math.round(baseMs + (Math.random() * 2 - 1) * span));
+}
+
+/** True if an HTTP status should trigger a retry. */
+export function isRetriableStatus(status: number): boolean {
+  // 5xx only. 429 (Too Many Requests) is arguably retriable too, but
+  // registry.npmjs.org is fronted by Cloudflare which generally rate-
+  // limits per-IP silently rather than with 429, and if we ever DO see
+  // 429 the right handling is Retry-After header honor, which we don't
+  // implement here. Keep the surface minimal.
+  return status >= 500 && status <= 599;
+}
+
+/**
+ * Signature of a fetch-compatible callable. Lets callers inject a proxy
+ * (e.g. the Nimbus supervisor-fetch RPC) without forcing global fetch.
+ */
+export type FetchCallable = (url: string, init?: RequestInit) => Promise<Response>;
+
+export interface RetryableFetchOptions {
+  /**
+   * Retries AFTER the initial attempt. Default DEFAULT_RETRIES (3).
+   * 0 = behave as a plain fetch.
+   */
+  retries?: number;
+  /**
+   * Fetch implementation. Defaults to globalThis.fetch. Pass a proxy
+   * fetch (e.g. env.SUPERVISOR-backed fetchFn) to route through it while
+   * keeping the retry semantics.
+   */
+  fetchImpl?: FetchCallable;
+  /**
+   * Human-readable name for the resource (used only in log messages).
+   * Typically "<pkg>@<version>" for npm or the URL.
+   */
+  name?: string;
+  /**
+   * Per-attempt timeout in ms. A fresh AbortController is used per attempt
+   * so a slow-to-fail upstream doesn't eat the whole retry budget on a
+   * single hang. Merges with any caller-provided `init.signal` (both are
+   * honored: whichever aborts first wins).
+   *
+   * Default: undefined (no timeout; caller is responsible for its own
+   * signal if it wants one).
+   */
+  perAttemptTimeoutMs?: number;
+  /**
+   * Optional logger called on each retry decision. Signature:
+   *   onRetry(attempt /* 1-indexed *\/, totalRetries, delayMs, reason)
+   *
+   * Caller uses this to surface visible progress ("retry 1/3 after 500ms
+   * (HTTP 503)") rather than have the whole install silently hang for
+   * several seconds.
+   */
+  onRetry?: (attempt: number, totalRetries: number, delayMs: number, reason: string) => void;
+}
+
+/**
+ * fetch() wrapper with 5xx + network-error retry and jittered backoff.
+ *
+ * On a 4xx response, returns the Response object as-is (caller decides
+ * whether that's an error). On a 5xx or network-level failure, retries
+ * up to `retries` times with BACKOFF_MS[attempt] ± 25% jitter.
+ *
+ * When retries are exhausted, either:
+ *   - Returns the last (5xx) Response, so the caller can read .status for
+ *     error reporting, OR
+ *   - Re-throws the last network error (caller never sees a Response).
+ *
+ * Callers that previously did `if (!resp.ok) throw ...` retain that shape;
+ * the only change is that transient failures are recovered before the
+ * throw instead of killing the whole install on the first hiccup.
+ */
+export async function retryableFetch(
+  url: string,
+  init?: RequestInit,
+  opts?: RetryableFetchOptions,
+): Promise<Response> {
+  const totalRetries = Math.max(0, opts?.retries ?? DEFAULT_RETRIES);
+  const name = opts?.name ?? url;
+  const doFetch: FetchCallable = opts?.fetchImpl ?? (globalThis.fetch.bind(globalThis) as FetchCallable);
+  let lastError: unknown;
+  let lastResp: Response | undefined;
+
+  for (let attempt = 0; attempt <= totalRetries; attempt++) {
+    // Per-attempt timeout via a fresh AbortController so a single slow
+    // response can't consume the whole retry budget. We merge the caller's
+    // signal (if any) by forwarding its abort to ours.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let attemptInit: RequestInit | undefined = init;
+    const perAttemptMs = opts?.perAttemptTimeoutMs;
+    let localController: AbortController | undefined;
+    if (perAttemptMs && perAttemptMs > 0) {
+      localController = new AbortController();
+      timer = setTimeout(() => localController!.abort(), perAttemptMs);
+      const callerSignal = init?.signal;
+      if (callerSignal) {
+        if (callerSignal.aborted) localController.abort();
+        else callerSignal.addEventListener('abort', () => localController!.abort(), { once: true });
+      }
+      attemptInit = { ...(init ?? {}), signal: localController.signal };
+    }
+    try {
+      const resp = await doFetch(url, attemptInit);
+      if (timer) clearTimeout(timer);
+      if (resp.ok || !isRetriableStatus(resp.status)) {
+        // Success or 4xx — don't retry. Return as-is; caller checks .ok.
+        return resp;
+      }
+      // 5xx: drain the body to release the underlying stream.
+      try { await resp.body?.cancel(); } catch { /* best-effort */ }
+      lastResp = resp;
+      lastError = undefined;
+      if (attempt === totalRetries) {
+        // Out of retries — return the 5xx Response so the caller can
+        // surface the final status. Caller (e.g. npm-resolver.ts) is
+        // responsible for disposing the stub via Symbol.dispose after
+        // reading status. (Matches the previous !resp.ok throw shape if
+        // the caller checks .ok next.)
+        return resp;
+      }
+      // We're going to retry — dispose the stub NOW so it doesn't leak.
+      //
+      // When `doFetch` is the supervisor's fetch-proxy entrypoint
+      // (src/nimbus-session.ts:1729-1747), `resp` is an RPC stub returned
+      // from `entrypoint.fetch(...)`. Workerd auto-disposes such stubs
+      // only at the end of the enclosing event-handler context — which
+      // for `npm install` means "until the whole install completes".
+      // Cancelling `resp.body` (above) releases the underlying stream
+      // but does NOT release the stub itself. Across an install with N
+      // retries fired, that's N leaked stubs accumulating alongside the
+      // resolver's own per-packument stubs (already disposed in
+      // npm-resolver.ts:307-317). Each leaked stub keeps its server-side
+      // counterpart pinned until the deferred-destruction queue runs at
+      // request end, contributing to the queueState != ACTIVE fatal
+      // documented in WORKERD-CRASH.md.
+      //
+      // Same disposer pattern as src/npm-resolver.ts:312-316.
+      disposeRpcResource(resp);
+      const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
+      opts?.onRetry?.(attempt + 1, totalRetries, delayMs, `HTTP ${resp.status}`);
+      await new Promise<void>((r) => setTimeout(r, delayMs));
+    } catch (e: any) {
+      if (timer) clearTimeout(timer);
+      // Network-level failure (fetch rejection, timeout via AbortError,
+      // DNS, connection reset). Retry the same way as a 5xx.
+      lastError = e;
+      lastResp = undefined;
+      if (attempt === totalRetries) {
+        throw e;
+      }
+      const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
+      const reason = e?.name === 'AbortError' ? 'timeout' : (e?.message || String(e));
+      opts?.onRetry?.(attempt + 1, totalRetries, delayMs, reason);
+      await new Promise<void>((r) => setTimeout(r, delayMs));
+    }
+  }
+
+  // Unreachable: the loop either returns (on success / non-retriable /
+  // final 5xx) or throws (on final network error).
+  if (lastResp) return lastResp;
+  throw lastError ?? new Error(`retryableFetch: exhausted for ${name}`);
+}

package/src/_shared/rpc-dispose.ts

@@ -0,0 +1,31 @@
+type DisposableSymbolConstructor = SymbolConstructor & { readonly dispose?: symbol };
+
+export function disposeRpcResource(value: unknown): boolean {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return false;
+  const disposerKey = (Symbol as DisposableSymbolConstructor).dispose;
+  if (!disposerKey) return false;
+  const disposer = Reflect.get(value, disposerKey);
+  if (typeof disposer !== 'function') return false;
+  try {
+    Reflect.apply(disposer, value, []);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function disposeRpcResources(values: Iterable<unknown>): void {
+  for (const value of values) disposeRpcResource(value);
+}
+
+export async function useRpcResource<T, R>(
+  promise: Promise<T>,
+  use: (value: T) => R | Promise<R>,
+): Promise<R> {
+  const value = await promise;
+  try {
+    return await use(value);
+  } finally {
+    disposeRpcResource(value);
+  }
+}

package/src/_shared/terminal.ts

@@ -0,0 +1,3 @@
+export function normalizeTerminalNewlines(text: string): string {
+  return text.replace(/\r?\n/g, '\r\n');
+}

package/src/_shared/typescript-specifiers.ts

@@ -0,0 +1,86 @@
+/**
+ * typescript-specifiers.ts — the one definition of how a module specifier
+ * reaches a TypeScript source, shared by the install-time prefetch resolver
+ * and the `require()` inside a running facet.
+ *
+ * TypeScript's `"moduleResolution": "NodeNext"` requires authors to write the
+ * OUTPUT extension in a specifier that names a TypeScript source:
+ *
+ *     // packages/cli/bin/cli.ts
+ *     import '../src/program.js';        // means ../src/program.ts
+ *
+ * That is not one project's quirk, it is what every modern TS project on
+ * NodeNext looks like. Real bun resolves it; node does not.
+ *
+ * SCOPE — this resolver serves node as well, so the rule is deliberately a
+ * FALLBACK rather than a reordering: these candidates are probed only after
+ * every candidate node itself would try has missed, and they only ever name a
+ * TypeScript source. The inputs whose resolution changes are therefore exactly
+ * the inputs that resolve to nothing today, where node's own answer is
+ * "Cannot find module". No module graph that resolves now resolves
+ * differently, so nothing about node's semantics moves — while the TypeScript
+ * projects Nimbus already transforms and runs become resolvable.
+ *
+ * The one bun behaviour deliberately NOT adopted is its probe ORDER. Bun tries
+ * `.tsx, .ts, .jsx, .js`, so for `./m` with both `m.ts` and `m.js` present bun
+ * answers `m.ts` and node answers `m.js`. Preferring the TypeScript file there
+ * would change a specifier that already resolves, which is the one thing this
+ * scoping promises not to do.
+ *
+ * Mapping measured against bun 1.3.1, not recalled:
+ *   ./m.js   → m.ts, m.tsx      (and m.js itself still wins when it exists)
+ *   ./m.mjs  → m.mts
+ *   ./m.cjs  → nothing; bun does not map it to m.cts
+ *   ./m      → m.ts, m.tsx
+ *
+ * `getTypescriptSpecifiersJS()` emits the same mapping for the facet shim.
+ * The two bodies are checked against each other mechanically —
+ * tests/unit/typescript-specifier-resolution.mjs evaluates the emitted one and
+ * compares it to this one over the whole table — because a "keep in sync"
+ * comment has never once caught a drift.
+ */
+
+/** Files that are already a TypeScript source, or can never name one. */
+const NON_MAPPING_EXTENSION = /\.(ts|tsx|mts|cts|json|node|cjs)$/;
+
+/**
+ * TypeScript sources a specifier may name once every path node itself would
+ * take has missed. Empty when the specifier cannot name one.
+ */
+export function typescriptFallbackCandidates(base: string): string[] {
+  if (NON_MAPPING_EXTENSION.test(base)) return [];
+  if (base.endsWith('.mjs')) return [base.slice(0, -4) + '.mts'];
+  if (base.endsWith('.js')) {
+    const stem = base.slice(0, -3);
+    return [stem + '.ts', stem + '.tsx'];
+  }
+  return [base + '.ts', base + '.tsx'];
+}
+
+/** Directory entry points, probed after node's `index.{js,cjs,mjs,json}`. */
+export const TYPESCRIPT_INDEX_CANDIDATES = ['/index.ts', '/index.tsx'] as const;
+
+/**
+ * The same mapping as raw JS, for embedding in the facet shim.
+ *
+ * The regex and the index list are interpolated from the definitions above so
+ * only the four-branch body is written twice, and the equivalence of the two
+ * bodies is asserted over the whole table by the unit test rather than
+ * asserted by a comment.
+ */
+export function getTypescriptSpecifiersJS(): string {
+  return `
+// ── typescript-specifiers (mirrors src/_shared/typescript-specifiers.ts) ──
+const __NON_MAPPING_EXTENSION = ${NON_MAPPING_EXTENSION.toString()};
+const __TYPESCRIPT_INDEX_CANDIDATES = ${JSON.stringify([...TYPESCRIPT_INDEX_CANDIDATES])};
+function __typescriptFallbackCandidates(base) {
+  if (__NON_MAPPING_EXTENSION.test(base)) return [];
+  if (base.endsWith(".mjs")) return [base.slice(0, -4) + ".mts"];
+  if (base.endsWith(".js")) {
+    const stem = base.slice(0, -3);
+    return [stem + ".ts", stem + ".tsx"];
+  }
+  return [base + ".ts", base + ".tsx"];
+}
+`;
+}

package/src/_shared/untrusted-request.ts

@@ -0,0 +1,75 @@
+/**
+ * The trust boundary between Nimbus and code running inside a session.
+ *
+ * Everything a session serves — port previews (both the `<port>--<sid>` host
+ * form and the `/s/<sid>/port/<n>/` path form), the Vite preview, the wrangler
+ * worker preview — is UNTRUSTED: it is whatever the user (or an agent acting
+ * for them) installed and ran. Nimbus's own credentials must never cross into
+ * it, so requests are sanitized here, once, by every caller that hands a
+ * Request to user code.
+ *
+ * Platform cookies are matched by NAMESPACE, not by an enumerated list. An
+ * explicit list is drift-prone in the way that matters most: it silently fails
+ * open. It also cannot work across layers — `NIMBUS_TOKEN_COOKIE` lives in
+ * this package, `nimbus_agent_oauth` in the session layer, and embedder
+ * cookies like `__Host-nimbus_demo_auth` in the app, which this package must
+ * not import. A namespace rule covers all three and any cookie added later.
+ */
+
+/** Cookie-name prefixes reserved for Nimbus and its embedders. */
+const PLATFORM_COOKIE_PREFIXES = ['nimbus_', '__Host-nimbus', '__Secure-nimbus'];
+
+/** True if `name` is a Nimbus/embedder platform cookie (never for user code). */
+export function isPlatformCookie(name: string): boolean {
+  return PLATFORM_COOKIE_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+
+/**
+ * Strip Nimbus credentials and internal routing headers from `headers`,
+ * in place. Cookies the user's own app set are preserved — only the platform
+ * namespace is removed.
+ */
+export function sanitizeUntrustedHeaders(headers: Headers): void {
+  for (const name of [...headers.keys()]) {
+    if (name.toLowerCase().startsWith('x-nimbus-')) headers.delete(name);
+  }
+  // Both carry credentials and neither is meaningful to a sandboxed server.
+  headers.delete('Authorization');
+  headers.delete('Proxy-Authorization');
+
+  const cookie = headers.get('Cookie');
+  if (!cookie) return;
+  const remaining = cookie
+    .split(';')
+    .map((entry) => entry.trim())
+    .filter((entry) => {
+      if (!entry) return false;
+      const separator = entry.indexOf('=');
+      const name = separator === -1 ? entry : entry.slice(0, separator).trim();
+      return !isPlatformCookie(name);
+    });
+  if (remaining.length > 0) headers.set('Cookie', remaining.join('; '));
+  else headers.delete('Cookie');
+}
+
+/**
+ * Clone `request` with credentials stripped, for callers that hand a whole
+ * Request to user code. Returns the original when there is nothing to remove,
+ * so the common case allocates nothing. WebSocket upgrades are passed through
+ * untouched: reconstructing them drops the `webSocket` handshake, and the
+ * upgrade itself is already authenticated upstream.
+ */
+export function sanitizeUntrustedRequest(request: Request): Request {
+  if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') return request;
+
+  const headers = new Headers(request.headers);
+  sanitizeUntrustedHeaders(headers);
+
+  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+  return new Request(request.url, {
+    method: request.method,
+    headers,
+    ...(hasBody ? { body: request.body, duplex: 'half' } as RequestInit : {}),
+    redirect: request.redirect,
+  });
+}