@teamscala/service-boot 0.23.350 → 0.23.352

package/src/serve/serve.ts

@@ -1,148 +0,0 @@
-/**
- * @system runtime-serve
- * @status handwritten
- * @edit edit directly
- *
- * Listener primitives. Provides the Bun.serve production listener (serveStart)
- * and the WebSocket upgrade helper (upgradeWebSocket) that work identically
- * dev and prod.
- */
-
-import type { Hono } from "hono";
-import { createBunWebSocket } from "hono/bun";
-import { stampTransportIdentity } from "./stamp-transport-identity.ts";
-
-const _bunWs = createBunWebSocket();
-
-/**
- * Hono `upgradeWebSocket` helper bound to the same `createBunWebSocket()`
- * pair that drives Bun.serve.websocket. Use exclusively from this package so
- * the upgrade path and the message dispatch share state.
- */
-export const upgradeWebSocket = _bunWs.upgradeWebSocket;
-
-export interface ServeOptions {
-	/** TCP port to bind. */
-	port: number;
-	/** For logging only. */
-	serviceSlug: string;
-	/**
-	 * Optional logger; defaults to console.
-	 */
-	logger?: { info(msg: string): void; warn(msg: string): void };
-}
-
-export interface ServeHandle {
-	server: ReturnType<typeof Bun.serve>;
-	stop(): void;
-}
-
-/**
- * Create the fetch handler with transport-identity stamping. Used in direct
- * mode (mutable-ref mode uses fetchWithMutableApp, which also stamps via the
- * same stampTransportIdentity helper — one stamp point for every request).
- */
-function createFetchHandler(app: Hono) {
-	return async (
-		req: Request,
-		server: ReturnType<typeof Bun.serve>,
-	) => {
-		// app.fetch's second arg becomes c.env. Hono's bun WebSocket upgrade
-		// adapter checks `"server" in c.env` for the Bun server reference (WS
-		// upgrade throws TypeError without it). stampTransportIdentity handles
-		// the WS-upgrade no-clone rule + best-effort identity stamping internally.
-		return app.fetch(stampTransportIdentity(req, server), { server });
-	};
-}
-
-/**
- * Internal serve setup that's shared between both modes.
- */
-function serveStartInternal(
-	fetchHandler: (req: Request, server: ReturnType<typeof Bun.serve>) => Promise<Response>,
-	options: ServeOptions,
-	logger: { info(msg: string): void; warn(msg: string): void },
-	mode: "direct" | "mutable-ref",
-): ServeHandle {
-	const server = Bun.serve({
-		port: options.port,
-		// reusePort is deliberately NOT set. SO_REUSEPORT lets a second process
-		// bind a port this service already owns; the kernel then load-balances
-		// between them and BOTH look healthy while each receives a fraction of
-		// the traffic. That is the worst available failure mode — it presents as
-		// intermittent, unattributable errors in whichever service is unlucky,
-		// far from the process that actually took the port.
-		//
-		// It has now cost two incidents. mcp-ai-chat-system bound session-picker's
-		// 3021 and broke tool curation; scala-quiz did the same on 2026-07-31 and
-		// answered ~half of every session-daemon RPC with a 404. Neither failed at
-		// bind, because reusePort made a collision legal.
-		//
-		// Nothing here needs it: PM2 fork mode stops before it starts, dev runs one
-		// process per service (`readiness-gated-boot` — the boot window is handled
-		// by the in-process readiness gate, explicitly not blue/green), and each
-		// Railway container is alone. So the only thing reusePort can express on
-		// this platform is a mistake, and without it that mistake is an immediate,
-		// legible EADDRINUSE naming the port.
-		// Bun's default idleTimeout (~10s, swept on a coarse timer wheel)
-		// FIN-closes every pending connection in one ~2ms sweep once their
-		// handlers exceed it — packet-captured 2026-06-06: concurrent SSR
-		// requests all died at the same instant at 8.2-10.5s with clean
-		// server-side FINs while the renders completed and logged 200. THIS
-		// file is the serve path for kind:ui services (service-runtime's
-		// twin got the option first and the deploy changed nothing — the
-		// wrong twin). 120s bounds wedged connections without guillotining
-		// slow SSR.
-		idleTimeout: 120,
-		fetch: fetchHandler as never,
-		websocket: _bunWs.websocket,
-	});
-	// Export the actual listening port to process.env so loopback code reads the
-	// REAL port without a separate PORT injection. The central-tool-forwarder
-	// (chat tool dispatch) falls back to http://localhost:${PORT} for the
-	// co-located /mcp; without this export every chat tool call fails with
-	// "cannot resolve the /mcp base URL" (the highlight-ring end-to-end blocker,
-	// 2026-07-02). Respect Railway's $PORT when present.
-	if (!process.env.PORT) process.env.PORT = String(server.port);
-	logger.info(
-		`[runtime-serve:${options.serviceSlug}] Bun.serve listening on :${server.port} (${mode})`,
-	);
-	return {
-		server,
-		stop() {
-			server.stop(true);
-		},
-	};
-}
-
-/**
- * Start Bun.serve listening on the configured port. Used by:
- *   - bootUiService when running the production bundle (`bun dist/server/index.js`)
- *   - bootBackendService for non-UI services
- *
- * UI services in dev mode also call this — they run `bun src/index.ts`
- * directly under PM2 with the same Bun.serve listener.
- *
- * Two-phase boot variant: when useMutableRef is true, `app` is used as the
- * initial app for the mutable reference (minimal tool-only surface), and the
- * caller can swap to the full app later via swapApp().
- */
-export function serveStart(
-	app: Hono,
-	options: ServeOptions,
-	useMutableRef = false,
-): ServeHandle {
-	const log = options.logger ?? console;
-
-	// For two-phase boot: initialize the mutable app reference with the
-	// minimal tool-only app. The caller will swap to the full app later.
-	if (useMutableRef) {
-		const { initMutableAppRef, fetchWithMutableApp } = require("../mutable-app-ref");
-		initMutableAppRef(app, "minimal");
-		return serveStartInternal(fetchWithMutableApp, options, log, "mutable-ref");
-	}
-
-	// Direct mode: use the app directly
-	const fetchHandler = createFetchHandler(app);
-	return serveStartInternal(fetchHandler, options, log, "direct");
-}

package/src/serve/stamp-transport-identity.test.ts

@@ -1,24 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { summariseLocalCommand } from "./stamp-transport-identity.ts";
-
-describe("local command attribution", () => {
-	test("never copies command arguments into telemetry", () => {
-		const token = "operator-token-must-not-appear";
-		const summary = summariseLocalCommand([
-			"curl",
-			"-H",
-			`x-operator-spawn-token: ${token}`,
-			"http://127.0.0.1:3021/rpc/spawn",
-		]);
-		expect(summary).toBe("curl [arguments redacted]");
-		expect(summary).not.toContain(token);
-	});
-
-	test("keeps a lone executable name", () => {
-		expect(summariseLocalCommand(["scala-picker"])).toBe("scala-picker");
-	});
-
-	test("omits an empty command line", () => {
-		expect(summariseLocalCommand([])).toBeNull();
-	});
-});

package/src/serve/stamp-transport-identity.ts

@@ -1,109 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Stamp transport-derived identity onto a request — the single shared stamp
- * point used by BOTH serve paths (direct `createFetchHandler` + mutable-ref
- * `fetchWithMutableApp`), so every request on every UI service carries the
- * same identity regardless of boot mode.
- *
- * Two identity layers, both transport-derived (no-client-controlled-trust-
- * signals — never from a client-controllable header):
- *   1. `x-caller-remote-address` / `-port` — the unforgeable socket peer, from
- *      `Bun.serve.requestIP`. ALWAYS sanitised (any client-supplied spoof
- *      deleted) then set to the verified peer. The /mcp + fleet loopback gates
- *      read this.
- *   2. `x-caller-local-comm` / `-cmd` — for a LOOPBACK peer with no forwarding
- *      header (a local `fetch` carries no CF-Connecting-IP), the owning local
- *      PROCESS resolved via /proc (@teamscala/proc-walker). Names the daemon
- *      behind every local request on the access log — including an unidentified
- *      sweeper. Attribution only (trust stays transport-derived).
- *
- * Best-effort + never throws: a resolution miss returns the original request
- * unchanged (the request is always served; identity degrades to address-only).
- * WebSocket upgrades are returned untouched (Bun tracks upgrades by Request
- * identity — a clone can never upgrade).
- */
-
-import { CALLER_HEADERS } from "@teamscala/os/contracts/mcp";
-import { resolveSocketPeer } from "@teamscala/proc-walker/socket-peer";
-
-const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
-
-/**
- * Preserve useful process attribution without copying arbitrary argv into logs.
- * Arguments routinely contain bearer headers, inline scripts, URLs and secret
- * values. There is no complete flag-name redaction list, so the safe boundary
- * is structural: retain argv[0] and state that arguments were removed.
- */
-export function summariseLocalCommand(cmdline: readonly string[]): string | null {
-	const executable = cmdline[0]?.trim();
-	if (!executable) return null;
-	return cmdline.length > 1 ? `${executable} [arguments redacted]` : executable;
-}
-
-/**
- * Return a Request with transport-identity headers stamped, or the original
- * `req` when no stamping is needed/possible. Never throws.
- */
-export function stampTransportIdentity(
-	req: Request,
-	server: ReturnType<typeof Bun.serve>,
-): Request {
-	// WebSocket upgrade requests MUST NOT be cloned — Bun's server.upgrade()
-	// tracks pending upgrades by Request identity, so a cloned Request can
-	// never upgrade.
-	if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
-		return req;
-	}
-	try {
-		const peer = (
-			server as unknown as {
-				requestIP(r: Request): { port?: number; address?: string } | null;
-			}
-		).requestIP?.(req);
-		const port = peer?.port;
-		const address = peer?.address ?? null;
-		const needsPort =
-			typeof port === "number" && port > 0 && !req.headers.has(CALLER_HEADERS.REMOTE_PORT);
-		// Nothing to stamp when there is no peer address and no port to add.
-		if (!needsPort && address === null) return req;
-
-		const headers = new Headers(req.headers);
-		if (needsPort) headers.set(CALLER_HEADERS.REMOTE_PORT, String(port));
-		if (address) {
-			headers.delete(CALLER_HEADERS.REMOTE_ADDRESS);
-			headers.set(CALLER_HEADERS.REMOTE_ADDRESS, String(address));
-		}
-		// Local-caller attribution: loopback peer + no forwarding header => a
-		// direct local fetch whose owning process we can name via /proc.
-		if (
-			address &&
-			LOOPBACK.has(address) &&
-			!headers.has("cf-connecting-ip") &&
-			!headers.get("x-forwarded-for") &&
-			typeof port === "number" &&
-			port > 0
-		) {
-			const owner = resolveSocketPeer(port);
-			if (owner) {
-				headers.set(CALLER_HEADERS.LOCAL_COMM, owner.comm);
-				const cmd = summariseLocalCommand(owner.cmdline);
-				if (cmd) headers.set(CALLER_HEADERS.LOCAL_CMD, cmd);
-			}
-		}
-		return new Request(req.url, {
-			method: req.method,
-			headers,
-			body: req.body,
-			signal: req.signal,
-			// @ts-expect-error duplex is required by spec when body is a stream
-			duplex: "half",
-		});
-	} catch {
-		// A broken peer resolution must never block serving — degrade to the
-		// original request (identity is best-effort, the request always served).
-		return req;
-	}
-}