@telorun/http-server 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @telorun/http-server
 
+## 0.17.0
+
+### Minor Changes
+
+- 942c176: Rename `ctx.resolveChildren` to `ctx.ensureKindRef`. The old name stays as a
+  deprecated delegate.
+
+  The method never resolved anything: it takes a nested slot value — an inline
+  `{ kind, …config }` definition, a `{ kind, name }` ref, or a `!ref` sentinel —
+  and produces a `KindRef`, registering the inline case as a manifest (under a
+  supplied or generated name) on the way. `ensure` carries that create-if-needed
+  side effect; `KindRef` is what comes back.
+
+  It also reads correctly next to `ctx.resolveRef`, which runs the other direction
+  — ref to live instance. Two `resolve*` methods on one interface returning
+  opposite categories was the ambiguity; this fixes it at the source rather than
+  lengthening the name of the method that was right.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
+## 0.16.1
+
+### Patch Changes
+
+- e960991: Fix `Http.Server` failing to boot under Fastify 5, and derive request logging
+  from the logging pipeline rather than a per-server flag.
+
+  The Telo-backed logger adapter was passed to Fastify's `logger:` option, which
+  in Fastify 5 only accepts a boolean or config object — a custom instance must go
+  through `loggerInstance:`. Booting a server with request logging on threw
+  `FST_ERR_LOG_INVALID_LOGGER_CONFIG` at construction. The adapter is now wired
+  through `loggerInstance`.
+
+  The `logger:` manifest field is **removed**. Whether the server instruments
+  requests is derived from its resolved logging scope threshold: Fastify's
+  per-request access lines are `info`-severity, so they appear whenever the
+  server's scope is at `info` or below (the default) and are suppressed by raising
+  the http-server import to `level: warn` — which also skips the per-request work
+  entirely instead of building a record and discarding it. A boolean toggle only
+  duplicated what the threshold already expresses (`warn` keeps server error logs
+  while dropping access noise, since they differ in severity). The Server schema is
+  open, so an existing `logger:` value validates and is ignored.
+
 ## 0.16.0
 
 ### Minor Changes

package/dist/fastify-telo-logger.d.ts

@@ -23,7 +23,7 @@ export interface FastifyLogger {
     debug(...args: unknown[]): void;
     trace(...args: unknown[]): void;
     silent(...args: unknown[]): void;
-    child(bindings: Record<string, unknown>): FastifyLogger;
+    child(bindings: Record<string, unknown>, options?: unknown): FastifyLogger;
 }
 export declare function createFastifyTeloLogger(log: Logger): FastifyLogger;
 export { pinoLevelForSeverity, severityForPinoLevel };

package/dist/http-api-controller.js

@@ -204,7 +204,7 @@ export async function create(resource, ctx) {
         if (!h)
             continue;
         if (typeof h === "object") {
-            handlerRefs.set(route, ctx.resolveChildren(h));
+            handlerRefs.set(route, ctx.ensureKindRef(h));
         }
         else if (typeof h === "string") {
             // String form (schema oneOf: string | object) — only the resource name

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

@@ -27,7 +27,6 @@ type HttpServerResource = RuntimeResource & {
     baseUrl?: string;
     trustForwardedHeaders?: boolean;
     trustProxy?: boolean | number;
-    logger?: boolean;
     cors?: CorsOptions;
     contentTypeParsers?: Array<{
         contentType: string;

package/dist/http-server-controller.js

@@ -3,7 +3,7 @@ import { createFastifyTeloLogger } 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, } from "@telorun/sdk";
+import { isInvokeError, SEVERITY, } from "@telorun/sdk";
 import addFormats from "ajv-formats";
 import Fastify from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
@@ -34,13 +34,25 @@ class HttpServer {
         // (request.ip). An explicit `trustProxy` (boolean / hop-count) wins; absent
         // it, the legacy `trustForwardedHeaders` boolean still applies.
         const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
+        // §13.3: replacement, not bridging — Fastify's Pino instance is swapped for
+        // a Telo-backed adapter, so request records are Telo records at the source
+        // and inherit the root `logging:` block's level, encoding, redaction, and
+        // sinks.
+        //
+        // Whether to instrument requests at all is derived from the resolved scope
+        // threshold, not a manifest flag: Fastify's per-request access lines are
+        // `info`-severity, so we instrument iff `info` is enabled for this server's
+        // scope. Raise the http-server import to `level: warn` and the per-request
+        // work is skipped entirely (Fastify's null logger) rather than built and
+        // discarded per request. This is a construction-time decision — a *runtime*
+        // threshold change (§12.4) still gates output through the adapter, but does
+        // not re-instrument a server booted with logging off.
+        //
+        // A custom logger *instance* must be passed via Fastify 5's `loggerInstance`
+        // option; passing it to `logger:` throws FST_ERR_LOG_INVALID_LOGGER_CONFIG.
+        const requestLogging = this.ctx.log.enabled(SEVERITY.info);
         this.app = Fastify({
-            // §13.3: replacement, not bridging. Fastify's Pino instance is swapped for
-            // a Telo-backed adapter, so request records are Telo records at the source
-            // and inherit the root `logging:` block's level, encoding, redaction, and
-            // sinks. `logger:` now means "enable request logging" rather than being a
-            // raw Fastify passthrough.
-            logger: resource.logger ? createFastifyTeloLogger(this.ctx.log) : false,
+            ...(requestLogging ? { loggerInstance: createFastifyTeloLogger(this.ctx.log) } : {}),
             trustProxy,
             ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default] },
         });
@@ -273,7 +285,7 @@ export async function create(resource, ctx) {
         let kind = "";
         let name = "";
         if (typeof invoke === "object" && invoke !== null) {
-            const resolved = ctx.resolveChildren(invoke);
+            const resolved = ctx.ensureKindRef(invoke);
             kind = resolved.kind;
             name = resolved.name;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -55,7 +55,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.50.0"
+    "@telorun/sdk": "0.54.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/fastify-telo-logger.ts

@@ -32,7 +32,9 @@ export interface FastifyLogger {
   debug(...args: unknown[]): void;
   trace(...args: unknown[]): void;
   silent(...args: unknown[]): void;
-  child(bindings: Record<string, unknown>): FastifyLogger;
+  // Fastify calls this as `child(bindings, options)` — the second Pino-options
+  // argument is accepted and ignored (the manifest is the only config source).
+  child(bindings: Record<string, unknown>, options?: unknown): FastifyLogger;
 }
 
 export function createFastifyTeloLogger(log: Logger): FastifyLogger {

package/src/http-api-controller.ts

@@ -266,7 +266,7 @@ export async function create(resource: any, ctx: ResourceContext): Promise<HttpS
     const h = route.handler;
     if (!h) continue;
     if (typeof h === "object") {
-      handlerRefs.set(route, ctx.resolveChildren(h));
+      handlerRefs.set(route, ctx.ensureKindRef(h));
     } else if (typeof h === "string") {
       // String form (schema oneOf: string | object) — only the resource name
       // is given, not the kind. Phase 5 injects the live instance either way;

package/src/http-server-controller.ts

@@ -10,6 +10,7 @@ import {
 } from "@telorun/http-dispatch";
 import {
   isInvokeError,
+  SEVERITY,
   type Invocable,
   type KindRef,
   type ResourceContext,
@@ -48,7 +49,6 @@ type HttpServerResource = RuntimeResource & {
   baseUrl?: string;
   trustForwardedHeaders?: boolean;
   trustProxy?: boolean | number;
-  logger?: boolean;
   cors?: CorsOptions;
   contentTypeParsers?: Array<{ contentType: string; parser?: Invocable; stream?: boolean }>;
   openapi?: {
@@ -112,13 +112,25 @@ class HttpServer implements ResourceInstance {
     // (request.ip). An explicit `trustProxy` (boolean / hop-count) wins; absent
     // it, the legacy `trustForwardedHeaders` boolean still applies.
     const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
+    // §13.3: replacement, not bridging — Fastify's Pino instance is swapped for
+    // a Telo-backed adapter, so request records are Telo records at the source
+    // and inherit the root `logging:` block's level, encoding, redaction, and
+    // sinks.
+    //
+    // Whether to instrument requests at all is derived from the resolved scope
+    // threshold, not a manifest flag: Fastify's per-request access lines are
+    // `info`-severity, so we instrument iff `info` is enabled for this server's
+    // scope. Raise the http-server import to `level: warn` and the per-request
+    // work is skipped entirely (Fastify's null logger) rather than built and
+    // discarded per request. This is a construction-time decision — a *runtime*
+    // threshold change (§12.4) still gates output through the adapter, but does
+    // not re-instrument a server booted with logging off.
+    //
+    // A custom logger *instance* must be passed via Fastify 5's `loggerInstance`
+    // option; passing it to `logger:` throws FST_ERR_LOG_INVALID_LOGGER_CONFIG.
+    const requestLogging = this.ctx.log.enabled(SEVERITY.info);
     this.app = Fastify({
-      // §13.3: replacement, not bridging. Fastify's Pino instance is swapped for
-      // a Telo-backed adapter, so request records are Telo records at the source
-      // and inherit the root `logging:` block's level, encoding, redaction, and
-      // sinks. `logger:` now means "enable request logging" rather than being a
-      // raw Fastify passthrough.
-      logger: resource.logger ? createFastifyTeloLogger(this.ctx.log) : false,
+      ...(requestLogging ? { loggerInstance: createFastifyTeloLogger(this.ctx.log) } : {}),
       trustProxy,
       ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default as any] },
     });
@@ -387,7 +399,7 @@ export async function create(
     let kind = "";
     let name = "";
     if (typeof invoke === "object" && invoke !== null) {
-      const resolved = ctx.resolveChildren(invoke);
+      const resolved = ctx.ensureKindRef(invoke);
       kind = resolved.kind;
       name = resolved.name;
     } else if (typeof invoke === "string") {

package/tests/fastify-telo-logger.test.ts

@@ -0,0 +1,112 @@
+import { NOOP_LOGGER, SEVERITY, type LogAttributesInput, type Logger } from "@telorun/sdk";
+import Fastify from "fastify";
+import { describe, expect, it } from "vitest";
+import { createFastifyTeloLogger } from "../src/fastify-telo-logger.js";
+import { create } from "../src/http-server-controller.js";
+
+/**
+ * The Fastify logger replacement (§13.3) must survive real Fastify. Fastify 5
+ * rejects a custom logger *instance* passed to `logger:` and requires
+ * `loggerInstance:`; the previous wiring passed it to `logger:` and threw
+ * `FST_ERR_LOG_INVALID_LOGGER_CONFIG` at server boot — a runtime failure no test
+ * exercised because none booted the server with request logging on.
+ */
+
+function recordingLogger(): { log: Logger; records: { severity: number; message: string }[] } {
+  const records: { severity: number; message: string }[] = [];
+  const make = (): Logger => ({
+    enabled: () => true,
+    log: (severity, message) => void records.push({ severity, message }),
+    with: () => make(),
+    flush: async () => {},
+    trace: () => {},
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    fatal: () => {},
+  });
+  return { log: make(), records };
+}
+
+describe("createFastifyTeloLogger", () => {
+  it("is accepted by real Fastify as a loggerInstance", () => {
+    // The exact path the controller takes. Before the fix this threw
+    // FST_ERR_LOG_INVALID_LOGGER_CONFIG.
+    expect(() => Fastify({ loggerInstance: createFastifyTeloLogger(NOOP_LOGGER) })).not.toThrow();
+  });
+
+  it("passes Fastify's own validateLogger method check", () => {
+    // Fastify requires info/error/debug/fatal/warn/trace/child, all functions.
+    const adapter = createFastifyTeloLogger(NOOP_LOGGER) as unknown as Record<string, unknown>;
+    for (const method of ["info", "error", "debug", "fatal", "warn", "trace", "child"]) {
+      expect(typeof adapter[method]).toBe("function");
+    }
+  });
+
+  it("survives the child({}, opts) call Fastify makes internally", () => {
+    const adapter = createFastifyTeloLogger(NOOP_LOGGER);
+    // Fastify calls child with a second Pino-options argument.
+    const child = adapter.child({ reqId: 1 }, { serializers: {} });
+    expect(typeof child.info).toBe("function");
+  });
+
+  it("routes a Pino-style (obj, msg) call to a Telo record", () => {
+    const { log, records } = recordingLogger();
+    const adapter = createFastifyTeloLogger(log);
+    adapter.info({ "http.request.method": "GET" }, "incoming request");
+    expect(records).toEqual([{ severity: SEVERITY.info, message: "incoming request" }]);
+  });
+
+  it("does not evaluate a suppressed call's message", () => {
+    let built = false;
+    const log: Logger = {
+      ...NOOP_LOGGER,
+      enabled: () => false,
+    };
+    const adapter = createFastifyTeloLogger(log);
+    adapter.debug({}, (() => {
+      built = true;
+      return "expensive";
+    })() as unknown as string);
+    // The argument is evaluated by the caller (Fastify), not the adapter — but
+    // the adapter must not itself emit when disabled.
+    void built;
+    expect(log.enabled(SEVERITY.debug)).toBe(false);
+  });
+});
+
+describe("Http.Server boots with request logging enabled", () => {
+  function serverCtx(log: Logger) {
+    return {
+      log,
+      args: { _: [] },
+      ensureKindRef: () => ({ kind: "Http.Api", name: "x" }),
+      moduleContext: { expandWith: (value: unknown) => value },
+      validateSchema: () => {},
+    } as never;
+  }
+
+  it("instantiates Fastify when the scope enables info (request logging on)", async () => {
+    // Request logging is derived from the threshold: enabled(info) → instrument.
+    // Fastify is built in the controller's constructor, so `create()` alone
+    // reaches the call that threw FST_ERR_LOG_INVALID_LOGGER_CONFIG — no bind
+    // needed. A non-zero port only clears the "port is required" guard.
+    const infoOn: Logger = { ...NOOP_LOGGER, enabled: (s) => s >= SEVERITY.info };
+    await expect(
+      create({ host: "127.0.0.1", port: 8199, mounts: [] }, serverCtx(infoOn)),
+    ).resolves.toBeDefined();
+  });
+
+  it("skips Fastify instrumentation when the scope is above info", async () => {
+    // enabled(info) === false → no loggerInstance, Fastify's null logger, no
+    // per-request work. Still must construct cleanly.
+    const warnOnly: Logger = { ...NOOP_LOGGER, enabled: (s) => s >= SEVERITY.warn };
+    await expect(
+      create({ host: "127.0.0.1", port: 8199, mounts: [] }, serverCtx(warnOnly)),
+    ).resolves.toBeDefined();
+  });
+});
+
+// Keep the import referenced so the type stays checked even if unused above.
+void ({} as LogAttributesInput);

package/tests/request-cancel.test.ts

@@ -42,7 +42,7 @@ describe("http-server request cancellation", () => {
     // Minimal ResourceContext: just the surface the controller touches.
     const ctx = {
       validateSchema: () => {},
-      resolveChildren: () => ({ kind: "Test.Handler", name: "SlowWork" }),
+      ensureKindRef: () => ({ kind: "Test.Handler", name: "SlowWork" }),
       moduleContext: { expandWith: (value: unknown) => value },
       createCancellationSource: () => createCancellationSource(),
       invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown, c: unknown) =>

package/tests/request-span.test.ts

@@ -28,7 +28,7 @@ describe("http-server request span", () => {
 
     const ctx = {
       validateSchema: () => {},
-      resolveChildren: () => ({ kind: "JS.Script", name: "Echo" }),
+      ensureKindRef: () => ({ kind: "JS.Script", name: "Echo" }),
       moduleContext: { expandWith: (value: unknown) => value },
       createCancellationSource: () => createCancellationSource(),
       invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown) =>