@telorun/http-server 0.26.0 → 0.27.0

package/README.md

@@ -10,6 +10,7 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 - **Typed returns and catches** — render successful values and structured `InvokeError`s into status + headers + per-MIME bodies via CEL.
 - **OpenAPI operation metadata** — a route may declare `operationId`, `summary`, `description`, and `tags`; they are rendered into the generated OpenAPI document.
 - **Composable mounts** — attach `Telo.Mount` resources (HTTP APIs, MCP endpoints, custom mounts) under any path prefix.
+- **Browsable API docs** — `Http.Reference` renders the generated OpenAPI document as an interactive page under a prefix you choose, and a mount's `when:` leaves it out of a production deployment.
 - **Serve a frontend** — `Http.Static` serves a directory of assets (a built SPA, plain HTML) so one application delivers both its API and its UI.
 - **CORS and content-type parsers** — first-class manifest fields; no controller code needed.
 
@@ -19,6 +20,7 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 | --- | --- |
 | `Http.Server` | Long-lived HTTP listener that hosts mounts on configured paths and ports. |
 | `Http.Api` | Mountable router exposing route definitions with returns/catches rendering. |
+| `Http.Reference` | Mountable API reference: the server's OpenAPI document rendered as a browsable page, plus the document itself as JSON and YAML. |
 | `Http.Static` | Mountable static-file server for a directory of assets (built SPA, plain HTML, images). |
 
 ## Example
@@ -80,6 +82,7 @@ code: |
 ## Reference
 
 - [`Http.Server` / `Http.Api` returns & catches](docs/returns-and-catches.md) — outcome lists, MIME negotiation, stream mode.
+- [API reference docs](docs/api-reference.md) — `Http.Reference`, choosing its prefix, and leaving the docs out of production with `when:`.
 - [Serving static files & frontends](docs/static-files.md) — `Http.Static`, manifest-relative roots, SPA fallback, asset caching.
 - [Log events](docs/log-events.md) — the `event_name` and attributes every implementation of this kind emits, and how to turn request logging off.
 

package/dist/http-reference-controller.d.ts

@@ -0,0 +1,7 @@
+import { type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
+type HttpReferenceResource = RuntimeResource & {
+    title?: string;
+    theme?: string;
+};
+export declare function create(resource: HttpReferenceResource): Promise<ResourceInstance>;
+export {};

package/dist/http-reference-controller.js

@@ -0,0 +1,54 @@
+import apiReference from "@scalar/fastify-api-reference";
+import { normalizeMountPrefix } from "./mount-prefix.js";
+import { installSpecServerUrlRewrite, specServerUrlIsPerRequest } from "./openapi-spec-servers.js";
+/** Whether the server this mount was attached to registered an OpenAPI document.
+ *  The same test the reference renderer makes before it would fall back to
+ *  serving nothing. */
+function hasOpenApiDocument(app) {
+    return (app.hasPlugin("@fastify/swagger") &&
+        typeof app.swagger === "function");
+}
+/**
+ * The API reference: the server's OpenAPI document rendered as a browsable page,
+ * plus the document itself at `<prefix>/openapi.json` and `<prefix>/openapi.yaml`.
+ *
+ * A mount rather than a fixed `/reference` route on the server, so the prefix is
+ * the author's and the docs are one entry in `mounts:` — which is what lets a
+ * `when:` leave them out of a production deployment. The document itself is still
+ * the server's: `@fastify/swagger` collects a route's schema through an `onRoute`
+ * hook in the encapsulation context it was registered in, so it has to be at the
+ * root scope before any mount registers, and only the RENDERING can move here.
+ */
+class HttpReference {
+    title;
+    theme;
+    constructor(resource) {
+        this.title = resource.title;
+        this.theme = resource.theme;
+    }
+    async init() { }
+    register(app, prefix = "") {
+        const routePrefix = normalizeMountPrefix(prefix);
+        if (!hasOpenApiDocument(app)) {
+            throw new Error(`Http.Reference mounted at '${routePrefix}' has nothing to render: the Http.Server ` +
+                `it is mounted on declares no \`openapi:\` block, so no OpenAPI document is ` +
+                `collected. Add one to the server:\n\n` +
+                `  openapi:\n    info:\n      title: My API\n      version: 1.0.0`);
+        }
+        // Scalar drops a trailing slash from its route prefix, so a reference mounted
+        // at the root serves `/openapi.json` rather than `//openapi.json`.
+        const base = routePrefix === "/" ? "" : routePrefix;
+        if (specServerUrlIsPerRequest(app)) {
+            installSpecServerUrlRewrite(app, `${base}/openapi.json`);
+        }
+        const configuration = {};
+        if (this.title !== undefined)
+            configuration.pageTitle = this.title;
+        if (this.theme !== undefined)
+            configuration.theme = this.theme;
+        app.register(apiReference, { routePrefix, configuration });
+    }
+}
+export async function create(resource) {
+    return new HttpReference(resource);
+}

package/dist/http-server-controller.d.ts

@@ -21,6 +21,15 @@ type CorsOptions = {
     strictPreflight?: boolean;
     hideOptionsRoute?: boolean;
 };
+type HttpMount = {
+    path?: string;
+    mount?: Mountable;
+    logging?: {
+        level?: LevelName;
+    };
+    /** Expanded at startup (`x-telo-eval: compile`); `false` leaves the mount out. */
+    when?: boolean;
+};
 type HttpServerResource = RuntimeResource & {
     host?: string;
     port?: number;
@@ -39,13 +48,7 @@ type HttpServerResource = RuntimeResource & {
             version: string;
         };
     };
-    mounts?: Array<{
-        path?: string;
-        mount?: Mountable;
-        logging?: {
-            level?: LevelName;
-        };
-    }>;
+    mounts?: HttpMount[];
     notFoundHandler?: {
         invoke: KindRef<Invocable>;
         inputs?: Record<string, unknown>;

package/dist/http-server-controller.js

@@ -1,18 +1,23 @@
 import cors from "@fastify/cors";
 import { createFastifyTeloLogger, LISTEN_SUPERSEDED } from "./fastify-telo-logger.js";
 import swagger from "@fastify/swagger";
-import apiReference from "@scalar/fastify-api-reference";
 import { dispatchCatches, dispatchReturns, } from "@telorun/http-dispatch";
 import { isInvokeError, SEVERITY, severityForLevel, } from "@telorun/sdk";
 import addFormats from "ajv-formats";
-import Fastify from "fastify";
+import Fastify, { LogController, } from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
+import { publishSpecServerUrlPolicy } from "./openapi-spec-servers.js";
 class HttpServer {
     releaseHold = null;
     /** Whether a socket actually opened, so `http.server.stopped` is only emitted
      *  for a server that emitted `http.server.started`. */
     listening = false;
     pluginsInitialized = false;
+    /** Indices into `activeMounts()` already attached, so a later init pass
+     *  registers only what is still missing — see `init()`. */
+    attachedMounts = new Set();
+    notFoundHandlerInstalled = false;
+    excludedMountsLogged = false;
     app;
     host;
     port;
@@ -36,14 +41,24 @@ class HttpServer {
         // protocol/host (request.protocol/host) and the canonical client address
         // (request.ip). An explicit `trustProxy` (boolean / hop-count) wins; absent
         // it, the legacy `trustForwardedHeaders` boolean still applies.
-        const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
+        //
+        // The hop count is expressed as the predicate it means — trust the rightmost
+        // N entries of X-Forwarded-For — rather than handed to Fastify as a number:
+        // Fastify 5.12 stopped honouring the numeric form and now trusts NOTHING for
+        // it, which would turn this kind's documented hop-count option into a silent
+        // no-op. The spoofing hazard that motivated their change is the one the
+        // schema already states: only enable this behind a trusted proxy.
+        const configuredTrust = resource.trustProxy ?? this.trustForwardedHeaders;
+        const trustProxy = typeof configuredTrust === "number"
+            ? (address, hop) => hop < configuredTrust
+            : configuredTrust;
         // §13.3: replacement, not bridging — Fastify's Pino instance is swapped for
         // a Telo-backed adapter, so its records are Telo records at the source and
         // inherit the root `logging:` block's level, encoding, redaction, and sinks.
         //
         // The adapter is injected UNCONDITIONALLY. It used to be gated on `info`
         // being enabled, because that was what avoided building a per-request record
-        // at a raised threshold — but `disableRequestLogging` now removes that cost
+        // at a raised threshold — but disabled request logging now removes that cost
         // outright, so the gate's only remaining effect was to hand Fastify its null
         // logger at `level: warn` and silently drop every diagnostic it owns: the
         // error handler's own failures, reply-send failures, aborted-request hooks.
@@ -59,11 +74,25 @@ class HttpServer {
             // `onRequest` / `onResponse` instead (see `installRequestLogging`), so the
             // access record's shape is this KIND's contract rather than Pino's prose —
             // which is what lets a Rust or Go implementation emit the same thing.
-            disableRequestLogging: true,
+            // The top-level `disableRequestLogging` option is deprecated (FSTDEP023);
+            // the log controller carries the same switch.
+            logController: new LogController({ disableRequestLogging: true }),
             trustProxy,
             ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default] },
         });
     }
+    /**
+     * Registering plugins and routes: nothing observable, and nothing repeatable —
+     * a route registers exactly once.
+     *
+     * The multi-pass init loop calls `init()` AGAIN on a resource whose init threw,
+     * which is how a mount that was not yet injected gets its second chance. So
+     * this has to be RESUMABLE rather than merely re-runnable: each mount records
+     * that it attached, and a later pass registers only what is still missing.
+     * Re-running the whole set answered with Fastify's duplicate-route error and
+     * buried the reason the first pass failed; refusing to re-run at all would have
+     * made a first-pass failure permanent, which is the retry the loop exists for.
+     */
     async init() {
         if (!this.pluginsInitialized) {
             await this.setupPlugins();
@@ -93,7 +122,7 @@ class HttpServer {
      * scope, so it cannot quieten `/health` while leaving `/api` alone. This can.
      */
     mountLogFloors() {
-        return (this.resource.mounts ?? [])
+        return this.activeMounts()
             .flatMap((mount) => {
             const level = mount.logging?.level;
             if (!level)
@@ -102,6 +131,19 @@ class HttpServer {
         })
             .sort((a, b) => b.prefix.length - a.prefix.length);
     }
+    /**
+     * The mounts this server attaches, `when:`-gated ones dropped.
+     *
+     * `when` is a startup decision, not a per-request one: it resolves with the
+     * rest of the server's configuration, so an excluded mount registers no routes
+     * at all rather than answering 404 — which is what makes leaving the API
+     * reference out of a production deployment mean something. The referenced
+     * resource is still created and initialized: it is an ordinary ref slot, filled
+     * before this server ever runs.
+     */
+    activeMounts() {
+        return (this.resource.mounts ?? []).filter((mount) => mount.when !== false);
+    }
     installRequestLogging() {
         const log = this.ctx.log;
         const floors = this.mountLogFloors();
@@ -267,6 +309,12 @@ class HttpServer {
             // override; otherwise the URL is relative (`/`) so the doc is correct behind
             // any proxy/ingress/origin — the client resolves it against wherever the
             // reference was loaded.
+            //
+            // This registers the document and nothing that serves it: rendering it is
+            // Http.Reference's, mounted where the author wants it. Collection has to
+            // stay here because @fastify/swagger reads a route's schema through an
+            // `onRoute` hook in its own encapsulation context, so it must be at the
+            // root scope before any mount registers its routes.
             const servers = [{ url: this.resource.baseUrl ?? "/" }];
             await this.app.register(swagger, {
                 openapi: {
@@ -275,61 +323,43 @@ class HttpServer {
                     servers,
                 },
             });
-            const referencePrefix = "/reference";
             // `trustForwardedHeaders` (and no fixed baseUrl) upgrades the relative
             // default to absolute URLs built per-request from the now-trusted
-            // X-Forwarded-* headers, so the served spec advertises the real proxy URL.
-            if (this.trustForwardedHeaders && !this.resource.baseUrl) {
-                // Couples to the Scalar plugin's default spec endpoint
-                // (`<routePrefix>/openapi.json`); if it ever served the doc elsewhere the
-                // rewrite would no-op and the relative default would still apply. The
-                // `openapi-server-url` integration test guards this path.
-                const specPath = `${referencePrefix}/openapi.json`;
-                this.app.addHook("onSend", async (request, reply, payload) => {
-                    if (request.url.split("?")[0] !== specPath)
-                        return payload;
-                    const text = typeof payload === "string"
-                        ? payload
-                        : Buffer.isBuffer(payload)
-                            ? payload.toString("utf8")
-                            : null;
-                    if (text === null)
-                        return payload;
-                    try {
-                        const doc = JSON.parse(text);
-                        if (doc && typeof doc === "object" && Array.isArray(doc.servers)) {
-                            doc.servers = [{ url: `${request.protocol}://${request.host}` }];
-                            const out = JSON.stringify(doc);
-                            reply.header("content-length", Buffer.byteLength(out));
-                            return out;
-                        }
-                    }
-                    catch {
-                        // Not a JSON document we can rewrite — leave the response untouched.
-                    }
-                    return payload;
-                });
-            }
-            await this.app.register(apiReference, {
-                routePrefix: referencePrefix,
-            });
+            // X-Forwarded-* headers. The rewrite itself belongs to whichever mount
+            // serves the document, which is the only side that knows its path.
+            publishSpecServerUrlPolicy(this.app, this.trustForwardedHeaders && !this.resource.baseUrl);
         }
     }
     setupRoutes() {
         // const routesByName = new Map<string, HttpRouteResource>();
-        const mounts = this.resource.mounts || [];
+        const mounts = this.activeMounts();
+        if (!this.excludedMountsLogged) {
+            this.excludedMountsLogged = true;
+            for (const skipped of (this.resource.mounts ?? []).filter((mount) => mount.when === false)) {
+                // Said out loud: a route set that is absent because a condition excluded
+                // it is indistinguishable at request time from one that failed to
+                // register. Once, not once per init pass.
+                this.ctx.log.debug("Mount excluded by its `when` condition", { "http.route": skipped.path || "/" }, { eventName: "http.server.mount.excluded" });
+            }
+        }
         // const resolveSchema = createSchemaResolver(this.ctx);
-        for (const mount of mounts) {
+        for (let index = 0; index < mounts.length; index++) {
+            if (this.attachedMounts.has(index))
+                continue;
+            const mount = mounts[index];
             const prefix = mount.path || "";
             // `mount.mount` is the live Telo.Mount instance injected by the kernel at Phase 5
             // (x-telo-ref `Telo.Mount`) — a same-module or imported-library mount, uniformly.
             const api = mount.mount;
             if (!api || typeof api.register !== "function") {
+                // Thrown, not recorded: Phase-5 injection runs again before the next
+                // init pass, so a mount that is merely not created YET resolves then.
                 throw new Error(`Failed to mount at "${prefix}": mount target did not resolve to a Telo.Mount instance`);
             }
             api.register(this.app, prefix);
+            this.attachedMounts.add(index);
         }
-        if (this.resolvedNotFoundHandler) {
+        if (this.resolvedNotFoundHandler && !this.notFoundHandlerInstalled) {
             const handler = this.resolvedNotFoundHandler;
             this.app.setNotFoundHandler(async (request, reply) => {
                 const normalizedHeaders = {};
@@ -384,6 +414,7 @@ class HttpServer {
                 }
                 return reply.send(result?.body ?? result);
             });
+            this.notFoundHandlerInstalled = true;
         }
     }
     async run() {

package/dist/http-static-controller.js

@@ -2,17 +2,7 @@ import fastifyStatic from "@fastify/static";
 import { readFile } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-/** Collapse a mount prefix to a single leading slash with no trailing slash;
- *  an empty/`"/"` prefix becomes `"/"`. Unlike Http.Api (which returns `""` and
- *  concatenates the prefix onto each route path on the root app), this serves
- *  from an encapsulated `register({ prefix })`, which needs a non-empty prefix —
- *  hence root maps to `"/"`, not `""`. */
-function normalizeMountPrefix(prefix) {
-    const trimmed = prefix.replace(/\/+$/, "");
-    if (!trimmed)
-        return "/";
-    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-}
+import { normalizeMountPrefix } from "./mount-prefix.js";
 /** Serves a directory of static assets (a built SPA, plain HTML, images, …) as a
  *  Telo.Mount. Mirrors Http.Api's `register(app, prefix)` contract so it slots into
  *  Http.Server.mounts identically. Backed by @fastify/static, which handles MIME,

package/dist/mount-prefix.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Collapse a mount prefix to a single leading slash with no trailing slash; an
+ * empty/`"/"` prefix becomes `"/"`.
+ *
+ * Shared by the mounts that hand their prefix to a Fastify plugin — Http.Static's
+ * encapsulated `register({ prefix })` and Http.Reference's `routePrefix` — both of
+ * which need a non-empty prefix, hence root maps to `"/"`. Http.Api is the odd one
+ * out: it returns `""` and concatenates the prefix onto each route path on the
+ * root app, so it does not use this.
+ */
+export declare function normalizeMountPrefix(prefix: string): `/${string}`;

package/dist/mount-prefix.js

@@ -0,0 +1,16 @@
+/**
+ * Collapse a mount prefix to a single leading slash with no trailing slash; an
+ * empty/`"/"` prefix becomes `"/"`.
+ *
+ * Shared by the mounts that hand their prefix to a Fastify plugin — Http.Static's
+ * encapsulated `register({ prefix })` and Http.Reference's `routePrefix` — both of
+ * which need a non-empty prefix, hence root maps to `"/"`. Http.Api is the odd one
+ * out: it returns `""` and concatenates the prefix onto each route path on the
+ * root app, so it does not use this.
+ */
+export function normalizeMountPrefix(prefix) {
+    const trimmed = prefix.replace(/\/+$/, "");
+    if (!trimmed)
+        return "/";
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}

package/dist/openapi-spec-servers.d.ts

@@ -0,0 +1,16 @@
+import type { FastifyInstance } from "fastify";
+/** Declare whether the served document's server URL must be rebuilt per request
+ *  (a trusted proxy in front, and no fixed `baseUrl` to state instead). */
+export declare function publishSpecServerUrlPolicy(app: FastifyInstance, perRequest: boolean): void;
+/** The policy the server published, absent when it declared no `openapi:` block. */
+export declare function specServerUrlIsPerRequest(app: FastifyInstance): boolean;
+/**
+ * Rewrite the served document's `servers:` to the URL this request arrived on.
+ *
+ * The registered document declares a relative server URL (`/`), which is correct
+ * behind any origin because the client resolves it against wherever the reference
+ * was loaded. With a trusted proxy in front, the real URL is knowable per request
+ * from the now-trusted `X-Forwarded-*` headers, so the served document advertises
+ * it instead of leaving the client to infer it.
+ */
+export declare function installSpecServerUrlRewrite(app: FastifyInstance, specPath: string): void;

package/dist/openapi-spec-servers.js

@@ -0,0 +1,56 @@
+/**
+ * The `servers:` array of the OpenAPI document as it is SERVED, which neither
+ * half of the docs can decide alone.
+ *
+ * `Http.Server` owns the policy — it holds `baseUrl` and knows whether forwarded
+ * headers are trusted — while `Http.Reference` owns the route the document is
+ * served from, so the rewrite is installed by the mount and decided by the
+ * server. The server publishes its decision as a Fastify decorator rather than
+ * passing it down a ref: a mount is reached through `register(app, prefix)` and
+ * has no handle on the server resource.
+ */
+const SPEC_SERVER_URL_PER_REQUEST = "teloOpenapiSpecServerUrlPerRequest";
+/** Declare whether the served document's server URL must be rebuilt per request
+ *  (a trusted proxy in front, and no fixed `baseUrl` to state instead). */
+export function publishSpecServerUrlPolicy(app, perRequest) {
+    app.decorate(SPEC_SERVER_URL_PER_REQUEST, perRequest);
+}
+/** The policy the server published, absent when it declared no `openapi:` block. */
+export function specServerUrlIsPerRequest(app) {
+    return app[SPEC_SERVER_URL_PER_REQUEST] === true;
+}
+/**
+ * Rewrite the served document's `servers:` to the URL this request arrived on.
+ *
+ * The registered document declares a relative server URL (`/`), which is correct
+ * behind any origin because the client resolves it against wherever the reference
+ * was loaded. With a trusted proxy in front, the real URL is knowable per request
+ * from the now-trusted `X-Forwarded-*` headers, so the served document advertises
+ * it instead of leaving the client to infer it.
+ */
+export function installSpecServerUrlRewrite(app, specPath) {
+    app.addHook("onSend", async (request, reply, payload) => {
+        if (request.url.split("?")[0] !== specPath)
+            return payload;
+        const text = typeof payload === "string"
+            ? payload
+            : Buffer.isBuffer(payload)
+                ? payload.toString("utf8")
+                : null;
+        if (text === null)
+            return payload;
+        try {
+            const doc = JSON.parse(text);
+            if (doc && typeof doc === "object" && Array.isArray(doc.servers)) {
+                doc.servers = [{ url: `${request.protocol}://${request.host}` }];
+                const out = JSON.stringify(doc);
+                reply.header("content-length", Buffer.byteLength(out));
+                return out;
+            }
+        }
+        catch {
+            // Not a JSON document we can rewrite — leave the response untouched.
+        }
+        return payload;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -34,6 +34,11 @@
       "bun": "./src/http-api-controller.ts",
       "import": "./dist/http-api-controller.js"
     },
+    "./http-reference": {
+      "types": "./dist/http-reference-controller.d.ts",
+      "bun": "./src/http-reference-controller.ts",
+      "import": "./dist/http-reference-controller.js"
+    },
     "./http-static": {
       "types": "./dist/http-static-controller.d.ts",
       "bun": "./src/http-static-controller.ts",
@@ -48,14 +53,14 @@
     "@sinclair/typebox": "^0.34.48",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "fastify": "^5.7.2",
-    "@telorun/http-dispatch": "0.11.1"
+    "fastify": "^5.12.1",
+    "@telorun/http-dispatch": "0.11.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.75.0"
+    "@telorun/sdk": "0.79.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-reference-controller.ts

@@ -0,0 +1,69 @@
+import apiReference from "@scalar/fastify-api-reference";
+import { type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
+import { FastifyInstance } from "fastify";
+import { normalizeMountPrefix } from "./mount-prefix.js";
+import { installSpecServerUrlRewrite, specServerUrlIsPerRequest } from "./openapi-spec-servers.js";
+
+type HttpReferenceResource = RuntimeResource & {
+  title?: string;
+  theme?: string;
+};
+
+/** Whether the server this mount was attached to registered an OpenAPI document.
+ *  The same test the reference renderer makes before it would fall back to
+ *  serving nothing. */
+function hasOpenApiDocument(app: FastifyInstance): boolean {
+  return (
+    app.hasPlugin("@fastify/swagger") &&
+    typeof (app as unknown as { swagger?: unknown }).swagger === "function"
+  );
+}
+
+/**
+ * The API reference: the server's OpenAPI document rendered as a browsable page,
+ * plus the document itself at `<prefix>/openapi.json` and `<prefix>/openapi.yaml`.
+ *
+ * A mount rather than a fixed `/reference` route on the server, so the prefix is
+ * the author's and the docs are one entry in `mounts:` — which is what lets a
+ * `when:` leave them out of a production deployment. The document itself is still
+ * the server's: `@fastify/swagger` collects a route's schema through an `onRoute`
+ * hook in the encapsulation context it was registered in, so it has to be at the
+ * root scope before any mount registers, and only the RENDERING can move here.
+ */
+class HttpReference implements ResourceInstance {
+  private readonly title?: string;
+  private readonly theme?: string;
+
+  constructor(resource: HttpReferenceResource) {
+    this.title = resource.title;
+    this.theme = resource.theme;
+  }
+
+  async init() {}
+
+  register(app: FastifyInstance, prefix = ""): void {
+    const routePrefix = normalizeMountPrefix(prefix);
+    if (!hasOpenApiDocument(app)) {
+      throw new Error(
+        `Http.Reference mounted at '${routePrefix}' has nothing to render: the Http.Server ` +
+          `it is mounted on declares no \`openapi:\` block, so no OpenAPI document is ` +
+          `collected. Add one to the server:\n\n` +
+          `  openapi:\n    info:\n      title: My API\n      version: 1.0.0`,
+      );
+    }
+    // Scalar drops a trailing slash from its route prefix, so a reference mounted
+    // at the root serves `/openapi.json` rather than `//openapi.json`.
+    const base = routePrefix === "/" ? "" : routePrefix;
+    if (specServerUrlIsPerRequest(app)) {
+      installSpecServerUrlRewrite(app, `${base}/openapi.json`);
+    }
+    const configuration: Record<string, unknown> = {};
+    if (this.title !== undefined) configuration.pageTitle = this.title;
+    if (this.theme !== undefined) configuration.theme = this.theme;
+    app.register(apiReference, { routePrefix, configuration });
+  }
+}
+
+export async function create(resource: HttpReferenceResource): Promise<ResourceInstance> {
+  return new HttpReference(resource);
+}

package/src/http-server-controller.ts

@@ -1,7 +1,6 @@
 import cors from "@fastify/cors";
 import { createFastifyTeloLogger, LISTEN_SUPERSEDED } from "./fastify-telo-logger.js";
 import swagger from "@fastify/swagger";
-import apiReference from "@scalar/fastify-api-reference";
 import {
   CatchEntry,
   dispatchCatches,
@@ -20,8 +19,14 @@ import {
   type RuntimeResource,
 } from "@telorun/sdk";
 import addFormats from "ajv-formats";
-import Fastify, { FastifyInstance, type FastifyRequest } from "fastify";
+import Fastify, {
+  FastifyInstance,
+  LogController,
+  type FastifyRequest,
+  type FastifyServerOptions,
+} from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
+import { publishSpecServerUrlPolicy } from "./openapi-spec-servers.js";
 
 /** A mounted Telo.Mount instance (Http.Api, Mcp.HttpEndpoint, …). The kernel injects the
  *  live instance into a mount's `mount` slot (x-telo-ref `Telo.Mount`) — cross-module refs
@@ -45,6 +50,16 @@ type CorsOptions = {
   hideOptionsRoute?: boolean;
 };
 
+type HttpMount = {
+  path?: string;
+  // x-telo-ref `Telo.Mount`: Phase 5 replaces this slot with the live mounted
+  // instance (Http.Api, Mcp.HttpEndpoint, …), local or imported.
+  mount?: Mountable;
+  logging?: { level?: LevelName };
+  /** Expanded at startup (`x-telo-eval: compile`); `false` leaves the mount out. */
+  when?: boolean;
+};
+
 type HttpServerResource = RuntimeResource & {
   host?: string;
   port?: number;
@@ -59,13 +74,7 @@ type HttpServerResource = RuntimeResource & {
       version: string;
     };
   };
-  mounts?: Array<{
-    path?: string;
-    // x-telo-ref `Telo.Mount`: Phase 5 replaces this slot with the live mounted
-    // instance (Http.Api, Mcp.HttpEndpoint, …), local or imported.
-    mount?: Mountable;
-    logging?: { level?: LevelName };
-  }>;
+  mounts?: HttpMount[];
   notFoundHandler?: {
     invoke: KindRef<Invocable>;
     inputs?: Record<string, unknown>;
@@ -88,6 +97,11 @@ class HttpServer implements ResourceInstance {
    *  for a server that emitted `http.server.started`. */
   private listening = false;
   private pluginsInitialized = false;
+  /** Indices into `activeMounts()` already attached, so a later init pass
+   *  registers only what is still missing — see `init()`. */
+  private readonly attachedMounts = new Set<number>();
+  private notFoundHandlerInstalled = false;
+  private excludedMountsLogged = false;
   private readonly app: FastifyInstance;
   private readonly host: string;
   private readonly port: number;
@@ -117,14 +131,25 @@ class HttpServer implements ResourceInstance {
     // protocol/host (request.protocol/host) and the canonical client address
     // (request.ip). An explicit `trustProxy` (boolean / hop-count) wins; absent
     // it, the legacy `trustForwardedHeaders` boolean still applies.
-    const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
+    //
+    // The hop count is expressed as the predicate it means — trust the rightmost
+    // N entries of X-Forwarded-For — rather than handed to Fastify as a number:
+    // Fastify 5.12 stopped honouring the numeric form and now trusts NOTHING for
+    // it, which would turn this kind's documented hop-count option into a silent
+    // no-op. The spoofing hazard that motivated their change is the one the
+    // schema already states: only enable this behind a trusted proxy.
+    const configuredTrust = resource.trustProxy ?? this.trustForwardedHeaders;
+    const trustProxy: FastifyServerOptions["trustProxy"] =
+      typeof configuredTrust === "number"
+        ? (address, hop) => hop < configuredTrust
+        : configuredTrust;
     // §13.3: replacement, not bridging — Fastify's Pino instance is swapped for
     // a Telo-backed adapter, so its records are Telo records at the source and
     // inherit the root `logging:` block's level, encoding, redaction, and sinks.
     //
     // The adapter is injected UNCONDITIONALLY. It used to be gated on `info`
     // being enabled, because that was what avoided building a per-request record
-    // at a raised threshold — but `disableRequestLogging` now removes that cost
+    // at a raised threshold — but disabled request logging now removes that cost
     // outright, so the gate's only remaining effect was to hand Fastify its null
     // logger at `level: warn` and silently drop every diagnostic it owns: the
     // error handler's own failures, reply-send failures, aborted-request hooks.
@@ -140,12 +165,26 @@ class HttpServer implements ResourceInstance {
       // `onRequest` / `onResponse` instead (see `installRequestLogging`), so the
       // access record's shape is this KIND's contract rather than Pino's prose —
       // which is what lets a Rust or Go implementation emit the same thing.
-      disableRequestLogging: true,
+      // The top-level `disableRequestLogging` option is deprecated (FSTDEP023);
+      // the log controller carries the same switch.
+      logController: new LogController({ disableRequestLogging: true }),
       trustProxy,
       ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default as any] },
     });
   }
 
+  /**
+   * Registering plugins and routes: nothing observable, and nothing repeatable —
+   * a route registers exactly once.
+   *
+   * The multi-pass init loop calls `init()` AGAIN on a resource whose init threw,
+   * which is how a mount that was not yet injected gets its second chance. So
+   * this has to be RESUMABLE rather than merely re-runnable: each mount records
+   * that it attached, and a later pass registers only what is still missing.
+   * Re-running the whole set answered with Fastify's duplicate-route error and
+   * buried the reason the first pass failed; refusing to re-run at all would have
+   * made a first-pass failure permanent, which is the retry the loop exists for.
+   */
   async init() {
     if (!this.pluginsInitialized) {
       await this.setupPlugins();
@@ -176,7 +215,7 @@ class HttpServer implements ResourceInstance {
    * scope, so it cannot quieten `/health` while leaving `/api` alone. This can.
    */
   private mountLogFloors(): ReadonlyArray<{ prefix: string; floor: number }> {
-    return (this.resource.mounts ?? [])
+    return this.activeMounts()
       .flatMap((mount) => {
         const level = mount.logging?.level;
         if (!level) return [];
@@ -185,6 +224,20 @@ class HttpServer implements ResourceInstance {
       .sort((a, b) => b.prefix.length - a.prefix.length);
   }
 
+  /**
+   * The mounts this server attaches, `when:`-gated ones dropped.
+   *
+   * `when` is a startup decision, not a per-request one: it resolves with the
+   * rest of the server's configuration, so an excluded mount registers no routes
+   * at all rather than answering 404 — which is what makes leaving the API
+   * reference out of a production deployment mean something. The referenced
+   * resource is still created and initialized: it is an ordinary ref slot, filled
+   * before this server ever runs.
+   */
+  private activeMounts(): ReadonlyArray<HttpMount> {
+    return (this.resource.mounts ?? []).filter((mount) => mount.when !== false);
+  }
+
   private installRequestLogging() {
     const log = this.ctx.log;
     const floors = this.mountLogFloors();
@@ -367,6 +420,12 @@ class HttpServer implements ResourceInstance {
       // override; otherwise the URL is relative (`/`) so the doc is correct behind
       // any proxy/ingress/origin — the client resolves it against wherever the
       // reference was loaded.
+      //
+      // This registers the document and nothing that serves it: rendering it is
+      // Http.Reference's, mounted where the author wants it. Collection has to
+      // stay here because @fastify/swagger reads a route's schema through an
+      // `onRoute` hook in its own encapsulation context, so it must be at the
+      // root scope before any mount registers its routes.
       const servers = [{ url: this.resource.baseUrl ?? "/" }];
       await this.app.register(swagger, {
         openapi: {
@@ -375,63 +434,53 @@ class HttpServer implements ResourceInstance {
           servers,
         },
       });
-      const referencePrefix = "/reference";
       // `trustForwardedHeaders` (and no fixed baseUrl) upgrades the relative
       // default to absolute URLs built per-request from the now-trusted
-      // X-Forwarded-* headers, so the served spec advertises the real proxy URL.
-      if (this.trustForwardedHeaders && !this.resource.baseUrl) {
-        // Couples to the Scalar plugin's default spec endpoint
-        // (`<routePrefix>/openapi.json`); if it ever served the doc elsewhere the
-        // rewrite would no-op and the relative default would still apply. The
-        // `openapi-server-url` integration test guards this path.
-        const specPath = `${referencePrefix}/openapi.json`;
-        this.app.addHook("onSend", async (request, reply, payload) => {
-          if (request.url.split("?")[0] !== specPath) return payload;
-          const text =
-            typeof payload === "string"
-              ? payload
-              : Buffer.isBuffer(payload)
-                ? payload.toString("utf8")
-                : null;
-          if (text === null) return payload;
-          try {
-            const doc = JSON.parse(text);
-            if (doc && typeof doc === "object" && Array.isArray(doc.servers)) {
-              doc.servers = [{ url: `${request.protocol}://${request.host}` }];
-              const out = JSON.stringify(doc);
-              reply.header("content-length", Buffer.byteLength(out));
-              return out;
-            }
-          } catch {
-            // Not a JSON document we can rewrite — leave the response untouched.
-          }
-          return payload;
-        });
-      }
-      await this.app.register(apiReference, {
-        routePrefix: referencePrefix,
-      });
+      // X-Forwarded-* headers. The rewrite itself belongs to whichever mount
+      // serves the document, which is the only side that knows its path.
+      publishSpecServerUrlPolicy(
+        this.app,
+        this.trustForwardedHeaders && !this.resource.baseUrl,
+      );
     }
   }
 
   private setupRoutes(): void {
     // const routesByName = new Map<string, HttpRouteResource>();
-    const mounts = this.resource.mounts || [];
+    const mounts = this.activeMounts();
+    if (!this.excludedMountsLogged) {
+      this.excludedMountsLogged = true;
+      for (const skipped of (this.resource.mounts ?? []).filter((mount) => mount.when === false)) {
+        // Said out loud: a route set that is absent because a condition excluded
+        // it is indistinguishable at request time from one that failed to
+        // register. Once, not once per init pass.
+        this.ctx.log.debug(
+          "Mount excluded by its `when` condition",
+          { "http.route": skipped.path || "/" },
+          { eventName: "http.server.mount.excluded" },
+        );
+      }
+    }
     // const resolveSchema = createSchemaResolver(this.ctx);
-    for (const mount of mounts) {
+    for (let index = 0; index < mounts.length; index++) {
+      if (this.attachedMounts.has(index)) continue;
+      const mount = mounts[index];
       const prefix = mount.path || "";
       // `mount.mount` is the live Telo.Mount instance injected by the kernel at Phase 5
       // (x-telo-ref `Telo.Mount`) — a same-module or imported-library mount, uniformly.
       const api = mount.mount;
       if (!api || typeof api.register !== "function") {
+        // Thrown, not recorded: Phase-5 injection runs again before the next
+        // init pass, so a mount that is merely not created YET resolves then.
         throw new Error(
           `Failed to mount at "${prefix}": mount target did not resolve to a Telo.Mount instance`,
         );
       }
       api.register(this.app, prefix);
+      this.attachedMounts.add(index);
     }
 
-    if (this.resolvedNotFoundHandler) {
+    if (this.resolvedNotFoundHandler && !this.notFoundHandlerInstalled) {
       const handler = this.resolvedNotFoundHandler;
       this.app.setNotFoundHandler(async (request, reply) => {
         const normalizedHeaders: Record<string, any> = {};
@@ -511,6 +560,7 @@ class HttpServer implements ResourceInstance {
         }
         return reply.send(result?.body ?? result);
       });
+      this.notFoundHandlerInstalled = true;
     }
   }
 

package/src/http-static-controller.ts

@@ -4,6 +4,7 @@ import { FastifyInstance } from "fastify";
 import { readFile } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { normalizeMountPrefix } from "./mount-prefix.js";
 
 type HttpStaticResource = RuntimeResource & {
   root: string;
@@ -13,17 +14,6 @@ type HttpStaticResource = RuntimeResource & {
   immutable?: boolean;
 };
 
-/** Collapse a mount prefix to a single leading slash with no trailing slash;
- *  an empty/`"/"` prefix becomes `"/"`. Unlike Http.Api (which returns `""` and
- *  concatenates the prefix onto each route path on the root app), this serves
- *  from an encapsulated `register({ prefix })`, which needs a non-empty prefix —
- *  hence root maps to `"/"`, not `""`. */
-function normalizeMountPrefix(prefix: string): string {
-  const trimmed = prefix.replace(/\/+$/, "");
-  if (!trimmed) return "/";
-  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-}
-
 /** Serves a directory of static assets (a built SPA, plain HTML, images, …) as a
  *  Telo.Mount. Mirrors Http.Api's `register(app, prefix)` contract so it slots into
  *  Http.Server.mounts identically. Backed by @fastify/static, which handles MIME,

package/src/mount-prefix.ts

@@ -0,0 +1,15 @@
+/**
+ * Collapse a mount prefix to a single leading slash with no trailing slash; an
+ * empty/`"/"` prefix becomes `"/"`.
+ *
+ * Shared by the mounts that hand their prefix to a Fastify plugin — Http.Static's
+ * encapsulated `register({ prefix })` and Http.Reference's `routePrefix` — both of
+ * which need a non-empty prefix, hence root maps to `"/"`. Http.Api is the odd one
+ * out: it returns `""` and concatenates the prefix onto each route path on the
+ * root app, so it does not use this.
+ */
+export function normalizeMountPrefix(prefix: string): `/${string}` {
+  const trimmed = prefix.replace(/\/+$/, "");
+  if (!trimmed) return "/";
+  return trimmed.startsWith("/") ? (trimmed as `/${string}`) : `/${trimmed}`;
+}

package/src/openapi-spec-servers.ts

@@ -0,0 +1,59 @@
+import type { FastifyInstance } from "fastify";
+
+/**
+ * The `servers:` array of the OpenAPI document as it is SERVED, which neither
+ * half of the docs can decide alone.
+ *
+ * `Http.Server` owns the policy — it holds `baseUrl` and knows whether forwarded
+ * headers are trusted — while `Http.Reference` owns the route the document is
+ * served from, so the rewrite is installed by the mount and decided by the
+ * server. The server publishes its decision as a Fastify decorator rather than
+ * passing it down a ref: a mount is reached through `register(app, prefix)` and
+ * has no handle on the server resource.
+ */
+const SPEC_SERVER_URL_PER_REQUEST = "teloOpenapiSpecServerUrlPerRequest";
+
+/** Declare whether the served document's server URL must be rebuilt per request
+ *  (a trusted proxy in front, and no fixed `baseUrl` to state instead). */
+export function publishSpecServerUrlPolicy(app: FastifyInstance, perRequest: boolean): void {
+  app.decorate(SPEC_SERVER_URL_PER_REQUEST, perRequest);
+}
+
+/** The policy the server published, absent when it declared no `openapi:` block. */
+export function specServerUrlIsPerRequest(app: FastifyInstance): boolean {
+  return (app as unknown as Record<string, unknown>)[SPEC_SERVER_URL_PER_REQUEST] === true;
+}
+
+/**
+ * Rewrite the served document's `servers:` to the URL this request arrived on.
+ *
+ * The registered document declares a relative server URL (`/`), which is correct
+ * behind any origin because the client resolves it against wherever the reference
+ * was loaded. With a trusted proxy in front, the real URL is knowable per request
+ * from the now-trusted `X-Forwarded-*` headers, so the served document advertises
+ * it instead of leaving the client to infer it.
+ */
+export function installSpecServerUrlRewrite(app: FastifyInstance, specPath: string): void {
+  app.addHook("onSend", async (request, reply, payload) => {
+    if (request.url.split("?")[0] !== specPath) return payload;
+    const text =
+      typeof payload === "string"
+        ? payload
+        : Buffer.isBuffer(payload)
+          ? payload.toString("utf8")
+          : null;
+    if (text === null) return payload;
+    try {
+      const doc = JSON.parse(text);
+      if (doc && typeof doc === "object" && Array.isArray(doc.servers)) {
+        doc.servers = [{ url: `${request.protocol}://${request.host}` }];
+        const out = JSON.stringify(doc);
+        reply.header("content-length", Buffer.byteLength(out));
+        return out;
+      }
+    } catch {
+      // Not a JSON document we can rewrite — leave the response untouched.
+    }
+    return payload;
+  });
+}