@teamscala/service-boot 0.23.284

package/src/ui-service.ts

@@ -0,0 +1,171 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Boots a `kind: "ui"` service. Reads the service_install registry row and
+ * orchestrates a fixed pipeline of single-purpose stages onto one Hono app
+ * served by @teamscala/service-runtime/serve (one Bun.serve in dev and prod).
+ */
+
+import { recordEvent } from "@teamscala/event-log/record-event";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { BootFatalError } from "@teamscala/os/errors/boot-error";
+import { Hono } from "hono";
+import type { ServiceInstallConfig } from "./load-service-install-row.ts";
+import { setReady } from "./readiness-gate.ts";
+import { serveStart } from "./serve/serve";
+import { buildMinimalApp, buildFullApp, swapToFullApp } from "./two-phase-boot.ts";
+
+export interface ResolvedBlock {
+	slug: string;
+	packagePath: string;
+}
+
+export interface UiServiceBootResult {
+	kind: "ui";
+	blocks: ResolvedBlock[];
+	routes: string[];
+	port: number;
+	app: Hono;
+}
+
+/**
+ * Page-server symbols injected by the caller. service-boot is tier 4
+ * (server) and must not import from tier 2 (`@teamscala/service-runtime`)
+ * per `installer-and-runtime` Rule 1. The runtime's bin entrypoint
+ * boot pipeline imports these from `page-server/` (same package —
+ * legal) and passes them down here.
+ */
+export interface PageServerDeps {
+	createPageHandler: import("./types.ts").CreatePageHandler;
+}
+
+/**
+ * Boots a UI service using two-phase boot for fast availability.
+ *
+ * Phase 1 (fast): Build and serve minimal tool-only app (ORPC, data routes,
+ * auth gates). This becomes available within ~10s, enabling the MCP tool
+ * surface to accept requests immediately after restart.
+ *
+ * Phase 2 (background): Build full app (pages, hydration) and atomically swap
+ * it in. The readiness gate flips to ready after Phase 1, not Phase 2.
+ *
+ * The interim mitigation (503 + gateway retry + circuit breaker) remains in
+ * place and is NOT undone.
+ */
+export async function bootUiService(
+	config: ServiceInstallConfig,
+	serviceSlug: string,
+	deps: PageServerDeps,
+	databaseUrl: string,
+): Promise<UiServiceBootResult> {
+	const log = getAppLogger();
+	const startTime = Date.now();
+
+	// Phase 1: Build minimal tool-only app
+	const minimalAppResult = await buildMinimalApp(config, serviceSlug, databaseUrl);
+
+	// Get port from config
+	const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
+	const port = requireValidPort(
+		envPort && Number.isFinite(envPort) && envPort > 0 ? envPort : config.port,
+		serviceSlug,
+	);
+
+	// Start serving with the minimal app (useMutableRef=true)
+	try {
+		serveStart(minimalAppResult.app, {
+			port,
+			serviceSlug,
+		}, true); // useMutableRef=true
+	} catch (err) {
+		throw new BootFatalError(
+			"ui-service.server-bind",
+			serviceSlug,
+			`Bun.serve failed to bind on port ${port}. Error: ${err instanceof Error ? err.message : err}`,
+			err,
+		);
+	}
+
+	const minimalReadyTime = Date.now();
+	const minimalDuration = minimalReadyTime - startTime;
+	log.info(
+		`[ui-service-boot:${serviceSlug}] Minimal app serving on port ${port} in ${minimalDuration}ms`,
+	);
+
+	// FLIP READY SWITCH: minimal app is ready, MCP tools can connect
+	setReady();
+	log.info(
+		`[ui-service-boot:${serviceSlug}] Ready gate flipped - MCP tools can now connect (full app building in background)`,
+	);
+
+	// Phase 2: Build full app in background (non-blocking)
+	;(async () => {
+		try {
+			const fullAppResult = await buildFullApp(minimalAppResult, deps);
+			const fullBuildTime = Date.now();
+			const fullDuration = fullBuildTime - startTime;
+
+			// Swap the app reference atomically
+			swapToFullApp(fullAppResult.app, serviceSlug);
+
+			log.info(
+				`[ui-service-boot:${serviceSlug}] Full app swapped in after ${fullDuration}ms (${fullDuration - minimalDuration}ms after minimal app)`,
+			);
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			log.error(
+				`[ui-service-boot:${serviceSlug}] Failed to build full app, continuing with minimal app: ${reason}`,
+			);
+			// NO-SILENT-REVERTS — surface the failed client build to OBSERVABILITY
+			// (event-log → GlitchTip, per event-log-is-the-only-durable-event-log).
+			// The minimal-app fallback keeps serving SSR from the LAST-successful
+			// manifest (now a tombstone, see build-client-assets.ts), so the page
+			// looks "up" while the client bundle is stale. Without this signal the
+			// failure is buried in boot stderr and a published fix that reached
+			// node_modules but failed to bundle ships invisibly stale (the
+			// scala-agents 2026-07-18 incident: ui-foundation@3.4.5 installed but
+			// served pre-fix bytes across restarts while node_modules was
+			// mid-install). The boot.client-build-failed event routes into
+			// event-log's 7-day retention → surfaces in GlitchTip as an incident
+			// trail the operator actually watches.
+			recordEvent({
+				kind: "boot.client-build-failed",
+				payload: {
+					service: serviceSlug,
+					reason: reason.slice(0, 2000),
+					at: new Date().toISOString(),
+				},
+			});
+			// Continue with minimal app - better than crashing
+		}
+	})();
+
+	// Return result compatible with the existing UiServiceBootResult interface
+	// Note: blocks/routes will be empty initially since they're built in the background.
+	// The service is operational for MCP tools.
+	return {
+		kind: "ui",
+		blocks: [], // Will be populated when full app builds
+		routes: [], // Will be populated when full app builds
+		port,
+		app: minimalAppResult.app,
+	};
+}
+
+function requireValidPort(port: unknown, serviceSlug: string): number {
+	if (
+		typeof port !== "number" ||
+		!Number.isFinite(port) ||
+		port <= 0 ||
+		port > 65535
+	) {
+		throw new BootFatalError(
+			"ui-service.port-validation",
+			serviceSlug,
+			`service_install row has invalid port "${port}" (must be a number 1-65535). Fix the service_install row before boot.`,
+		);
+	}
+	return port;
+}

package/src/ws-boot-self-test.ts

@@ -0,0 +1,114 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Post-listen WebSocket self-test. Runs after serveStart binds the port.
+ * For each declared websocket_routes path, opens a synthetic WebSocket
+ * connection and asserts 101 upgrade. Non-101 → BootFatalError.
+ *
+ * This catches the class of bugs where:
+ * - WS route registered after ORPC catch-all (order-dependent 404)
+ * - fetchWithPeerPort clones the Request on WS upgrade (breaks Bun.upgrade identity)
+ * - websocket_routes config row is stale / missing a handler
+ *
+ * Runs synchronously after serveStart so the boot aborts before the service
+ * reports healthy.
+ */
+
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { BootFatalError } from "@teamscala/os/errors/boot-error";
+
+const CONNECT_TIMEOUT_MS = 5_000;
+const WS_CLOSE_DELAY_MS = 500;
+
+interface WsSelfTestResult {
+	path: string;
+	ok: boolean;
+	reason?: string;
+}
+
+function connectWs(url: string): Promise<WsSelfTestResult> {
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			resolve({
+				path: new URL(url).pathname,
+				ok: false,
+				reason: "connection timed out",
+			});
+		}, CONNECT_TIMEOUT_MS);
+
+		try {
+			const ws = new WebSocket(url);
+			ws.addEventListener("open", () => {
+				clearTimeout(timer);
+				setTimeout(() => {
+					try {
+						ws.close();
+					} catch {}
+				}, WS_CLOSE_DELAY_MS);
+				resolve({ path: new URL(url).pathname, ok: true });
+			});
+			ws.addEventListener("error", () => {
+				clearTimeout(timer);
+				resolve({
+					path: new URL(url).pathname,
+					ok: false,
+					reason: "WebSocket error event",
+				});
+			});
+			ws.addEventListener("close", (evt) => {
+				clearTimeout(timer);
+				if (evt.code !== 1000 && evt.code !== 1005) {
+					resolve({
+						path: new URL(url).pathname,
+						ok: false,
+						reason: `closed unexpectedly: code=${evt.code} reason="${evt.reason}"`,
+					});
+				}
+			});
+		} catch (err) {
+			clearTimeout(timer);
+			resolve({
+				path: new URL(url).pathname,
+				ok: false,
+				reason: `exception: ${err instanceof Error ? err.message : err}`,
+			});
+		}
+	});
+}
+
+export async function runWsBootSelfTest(
+	config: ServiceInstallConfig,
+	serviceSlug: string,
+	port: number,
+): Promise<void> {
+	const log = getAppLogger();
+	const routes = config.websocket_routes ?? [];
+	if (routes.length === 0) return;
+
+	const results: WsSelfTestResult[] = [];
+	for (const route of routes) {
+		const typedRoute = route as { path: string };
+		const url = `ws://127.0.0.1:${port}${typedRoute.path}`;
+		const result = await connectWs(url);
+		results.push(result);
+	}
+
+	const failures = results.filter((r) => !r.ok);
+	if (failures.length === 0) {
+		log.info(
+			`[scala-install:${serviceSlug}] WS boot self-test: ${results.length}/${results.length} route(s) OK`,
+		);
+		return;
+	}
+
+	const details = failures.map((f) => `  ${f.path}: ${f.reason}`).join("\n");
+	throw new BootFatalError(
+		"ws-boot-self-test",
+		serviceSlug,
+		`WebSocket self-test failed for ${failures.length}/${results.length} route(s). ` +
+			`The server is listening but WS upgrade did not succeed:\n${details}`,
+	);
+}