@teamscala/service-boot 0.23.301 → 0.23.303

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.301",
+  "version": "0.23.303",
   "sideEffects": false,
   "files": [
     "src"

package/src/two-phase-boot.d.ts

@@ -12,7 +12,7 @@
  * built in the background and atomically swapped in. This eliminates the
  * ~25s channel outage window during scala-agents restart.
  */
-import { Hono } from "hono";
+import { Hono, type Context } from "hono";
 import type { ServiceInstallConfig } from "./load-service-install-row.ts";
 import { mountServerPackages } from "./mount-server-packages.ts";
 import type { PageServerDeps } from "./ui-service.ts";
@@ -28,6 +28,49 @@ export declare function getPageHandlerState(): {
     ready: boolean;
     hasHandler: boolean;
 };
+/**
+ * `/health` for a UI service — 200 ONLY once the full app can actually render
+ * a page, 503 before that.
+ *
+ * This endpoint is not decoration: it is the wake gate for every scale-to-zero
+ * app. `scala-activator` (`@teamscala/scale-to-zero`) holds the client's TCP
+ * connection through a cold wake and pipes it the instant `isHealthy(port)` —
+ * a plain `GET /health` — returns ok, which is what `scale-to-zero-apps-sleep-
+ * on-demand` means by "`/health`-gates the wake (the client never sees a boot
+ * 503)".
+ *
+ * It previously answered a flat `{status:"ok"}` as soon as the MINIMAL app was
+ * serving, because the readiness gate flips ready after phase 1 so the ORPC/MCP
+ * surface can accept traffic early. But phase 1 CANNOT render: the phase-1 page
+ * handler below returns 503 until `setPageHandler` runs at the phase-2 swap. So
+ * `/health` reported ready while every page 503'd, the activator believed the
+ * wake had landed, and it piped the customer's first request straight into that
+ * window — the customer got the 503.
+ *
+ * Measured 2026-07-31 on quiz-dev/sign-dev: the activator logged `awake` for
+ * scala-quiz at 05:58:25.446 and the app logged `GET / 503 3ms` at 05:58:25.452
+ * — 6ms later, and 1004ms BEFORE "Swapped from minimal app to full app". Nine
+ * such 503s on scala-quiz and two on scala-sign, every one 0-23ms (the
+ * placeholder, which does no render work). scala-public logged ZERO, which is
+ * the whole reason it looked healthy while the other two did not: the gap is a
+ * RACE whose width is the phase-1→phase-2 build time (1420ms cold, 137ms warm),
+ * not a config difference between the apps.
+ *
+ * Gating this on `fullAppReady` makes the signal honest for every consumer at
+ * once (the activator's wake gate, `poller-post-restart-health-gate`, any
+ * health-gated router) rather than teaching each one its own probe, and it is
+ * what `readiness-gated-boot` already requires: "/health returns 503 until
+ * ready, 200 after — so it is the real readiness signal", a service being
+ * "binary: fully-ready or cleanly-unavailable". A UI service that cannot render
+ * is not ready, per `liveness-by-capability-not-process-existence` — liveness is
+ * a probe of the capability being REQUESTED, never of process existence or of
+ * some other surface that happens to answer.
+ *
+ * The early readiness-gate flip is deliberately left alone: it gates the ORPC
+ * tool surface, which genuinely IS usable at phase 1. Only this endpoint, whose
+ * one consumer contract is "can you serve me a page", is moved to phase 2.
+ */
+export declare function healthHandler(c: Context): Response;
 export interface MinimalAppResult {
     app: Hono;
     mountRegistry: Awaited<ReturnType<typeof mountServerPackages>>;

package/src/two-phase-boot.ts

@@ -17,7 +17,7 @@ import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import { createTimer } from "@teamscala/timing/create-timer";
-import { Hono } from "hono";
+import { Hono, type Context } from "hono";
 import { compress } from "hono/compress";
 import { cors } from "hono/cors";
 import { timing } from "hono/timing";
@@ -77,6 +77,54 @@ export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
 	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
 }
 
+/**
+ * `/health` for a UI service — 200 ONLY once the full app can actually render
+ * a page, 503 before that.
+ *
+ * This endpoint is not decoration: it is the wake gate for every scale-to-zero
+ * app. `scala-activator` (`@teamscala/scale-to-zero`) holds the client's TCP
+ * connection through a cold wake and pipes it the instant `isHealthy(port)` —
+ * a plain `GET /health` — returns ok, which is what `scale-to-zero-apps-sleep-
+ * on-demand` means by "`/health`-gates the wake (the client never sees a boot
+ * 503)".
+ *
+ * It previously answered a flat `{status:"ok"}` as soon as the MINIMAL app was
+ * serving, because the readiness gate flips ready after phase 1 so the ORPC/MCP
+ * surface can accept traffic early. But phase 1 CANNOT render: the phase-1 page
+ * handler below returns 503 until `setPageHandler` runs at the phase-2 swap. So
+ * `/health` reported ready while every page 503'd, the activator believed the
+ * wake had landed, and it piped the customer's first request straight into that
+ * window — the customer got the 503.
+ *
+ * Measured 2026-07-31 on quiz-dev/sign-dev: the activator logged `awake` for
+ * scala-quiz at 05:58:25.446 and the app logged `GET / 503 3ms` at 05:58:25.452
+ * — 6ms later, and 1004ms BEFORE "Swapped from minimal app to full app". Nine
+ * such 503s on scala-quiz and two on scala-sign, every one 0-23ms (the
+ * placeholder, which does no render work). scala-public logged ZERO, which is
+ * the whole reason it looked healthy while the other two did not: the gap is a
+ * RACE whose width is the phase-1→phase-2 build time (1420ms cold, 137ms warm),
+ * not a config difference between the apps.
+ *
+ * Gating this on `fullAppReady` makes the signal honest for every consumer at
+ * once (the activator's wake gate, `poller-post-restart-health-gate`, any
+ * health-gated router) rather than teaching each one its own probe, and it is
+ * what `readiness-gated-boot` already requires: "/health returns 503 until
+ * ready, 200 after — so it is the real readiness signal", a service being
+ * "binary: fully-ready or cleanly-unavailable". A UI service that cannot render
+ * is not ready, per `liveness-by-capability-not-process-existence` — liveness is
+ * a probe of the capability being REQUESTED, never of process existence or of
+ * some other surface that happens to answer.
+ *
+ * The early readiness-gate flip is deliberately left alone: it gates the ORPC
+ * tool surface, which genuinely IS usable at phase 1. Only this endpoint, whose
+ * one consumer contract is "can you serve me a page", is moved to phase 2.
+ */
+export function healthHandler(c: Context): Response {
+	return fullAppReady
+		? c.json({ status: "ok" })
+		: c.json({ status: "starting" }, 503, { "Retry-After": "1" });
+}
+
 export interface MinimalAppResult {
 	app: Hono;
 	mountRegistry: Awaited<ReturnType<typeof mountServerPackages>>;
@@ -161,7 +209,7 @@ export async function buildMinimalApp(
 
 	// Core middleware
 	app.use("*", readinessGate);
-	app.get("/health", (c) => c.json({ status: "ok" }));
+	app.get("/health", healthHandler);
 	app.use("*", injectSecurityHeaders);
 	const cookieDomain = await getCookieDomain();
 	app.use(

package/src/two-phase-health-gate.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The wake gate for every scale-to-zero app: `/health` must not report ready
+ * while the service still 503s pages.
+ *
+ * Exercised through a real Hono request against the REAL exported handler, not
+ * asserted against source text — `proxy-is-not-behaviour`: a source grep proves
+ * a line exists, never that the endpoint answers 503. This test fails if anyone
+ * restores the flat `{status:"ok"}`, which is the regression it locks.
+ *
+ * THE MEASURED OUTAGE (2026-07-31, quiz-dev + sign-dev returning 503 to
+ * customers). `scala-activator` gates a cold wake on `isHealthy(port)` — a
+ * plain `GET /health` — then pipes the held client connection the moment it
+ * returns ok. `/health` answered ok as soon as the MINIMAL app served, but the
+ * phase-1 page handler returns 503 until the phase-2 swap, so the activator
+ * piped the customer's first request into that window:
+ *
+ *   05:58:25.446  activator: awake scala-quiz (4227ms)
+ *   05:58:25.452  scala-quiz: GET / 503 3ms      <- the customer's request
+ *   05:58:26.456  scala-quiz: Swapped from minimal app to full app
+ *
+ * Nine such 503s on scala-quiz, two on scala-sign, zero on scala-public — the
+ * gap is a race whose width is the phase-1→phase-2 build time (1420ms cold,
+ * 137ms warm), which is why one app looked healthy and the others did not.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { healthHandler, setPageHandler, getPageHandlerState } from "./two-phase-boot.ts";
+
+/** Mount the real handler exactly as buildMinimalApp does. */
+const app = new Hono().get("/health", healthHandler);
+
+/*
+ * Ordered, and deliberately so: `fullAppReady` is module state that only ever
+ * transitions false -> true (via setPageHandler at the phase-2 swap), so the
+ * pre-swap assertion has to run before the swap is simulated. There is no reset
+ * hook and adding one would exist only for tests.
+ */
+describe("/health is gated on page-serving readiness", () => {
+	test("before the phase-2 swap it reports 503, not ready", async () => {
+		expect(getPageHandlerState().ready).toBe(false);
+
+		const res = await app.request("/health");
+
+		// The activator treats any non-ok as "not awake yet" and keeps holding
+		// the client connection instead of piping it into a 503.
+		expect(res.status).toBe(503);
+		expect(res.ok).toBe(false);
+		expect(await res.json()).toEqual({ status: "starting" });
+		// Retry-After is the contract readiness-gated-boot specifies alongside
+		// the 503, so a caller backs off rather than hot-looping the wake.
+		expect(res.headers.get("Retry-After")).toBe("1");
+	});
+
+	test("after the phase-2 swap it reports 200 ok", async () => {
+		// Simulate the phase-2 swap: this is the real call ui-service.ts makes
+		// via buildFullApp, and it is what flips fullAppReady.
+		setPageHandler(() => async () => new Response("page"));
+		expect(getPageHandlerState().ready).toBe(true);
+
+		const res = await app.request("/health");
+
+		expect(res.status).toBe(200);
+		expect(res.ok).toBe(true);
+		expect(await res.json()).toEqual({ status: "ok" });
+	});
+});

package/src/ui-service.ts

@@ -78,7 +78,14 @@ export async function bootUiService(
 	// is unaffected by construction: it injects PORT and a Railway-only service
 	// has no declared port, so the env still wins there.
 	const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
-	const resolution = resolveServicePort(envPort, config.port);
+	// The APP binds its PRIVATE port (app_port) when present — for scale-to-zero
+	// services `port` is the ACTIVATOR's ingress (what callers resolve), not the
+	// app's bind. Falling back to `port` keeps RESIDENT + unmigrated services
+	// unchanged. Without this, a migrated row (port=activator) would make the app
+	// bind the activator's port → SO_REUSEPORT silent load-balancing (the
+	// service-ports-from-registry trap: clean boot, two owners in ss -ltnp).
+	const declaredAppPort = config.app_port ?? config.port;
+	const resolution = resolveServicePort(envPort, declaredAppPort);
 	if ("error" in resolution) {
 		throw new BootFatalError(
 			"ui-service.port-resolution",