@telorun/http-server 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @telorun/http-server
 
+## 0.16.0
+
+### Minor Changes
+
+- c1fef72: Implement the structured logging specification (`kernel/specs/logging.md`).
+
+  Records carry an OTel severity number, a message, structured attributes, the
+  emitting resource's identity, its import-alias scope, and the active dispatch
+  span's trace and span ids — all attached automatically. Controllers emit through
+  the new ambient `ctx.log`.
+
+  Logging is configured by a `logging:` block on the root `Telo.Application`:
+  `level`, `attributes`, `redact`, `sampling`, and a `sinks:` list of ref-or-inline
+  entries. `Telo.ConsoleSink` and `Telo.FileSink` are kernel built-ins resolvable
+  without an import; omitting `sinks:` yields exactly one console sink, so the
+  zero-config case stays "pretty on a terminal, JSON when piped". An `imports:`
+  entry may carry its own `logging:` block to raise verbosity for that dependency's
+  subtree; config cascades and may be narrowed at each hop. There is no
+  `TELO_LOG_*` variable and no logging CLI flag — a level derived from the host
+  environment goes through a `variables:` entry read with `!cel`.
+
+  New `Telo.Sink` capability and `Telo.LogSink` abstract, so the sink set is open
+  to the ecosystem: a third party ships a sink by publishing a module whose kind
+  extends `Telo.LogSink`. The new `std/otlp` module does exactly that.
+
+  Behaviour changes:
+
+  - The CLI now honours `NO_COLOR` and implements the spec's full color-precedence
+    order. `FORCE_COLOR=0` disables color rather than enabling it.
+  - `TracePayload.spanId` / `parentSpanId` on the debug wire are now 16-character
+    lowercase hex strings rather than numeric counters, matching the ids log
+    records carry. The internal counter is unchanged; hex is rendered only at the
+    encoding boundary and is salted per process so two services in one distributed
+    trace cannot mint the same id.
+  - `Http.Server`'s `logger:` field now means "enable request logging" rather than
+    being a raw Fastify passthrough. Fastify's Pino instance is replaced with a
+    Telo-backed adapter, so request records inherit the root `logging:` block's
+    level, encoding, redaction, and sinks.
+  - The kernel no longer writes diagnostics to `process.stderr` or `console.*`;
+    everything routes through the logger. The ad-hoc `TELO_BUNDLE_DEBUG` env var is
+    replaced by ordinary trace-level records.
+  - `on_full: block` and invalid redaction paths are now caught by `telo check`
+    (static analysis), not only at boot — `on_full: block` is unimplementable on a
+    single-threaded runtime and a bad redaction path would otherwise silently fail
+    to redact. Both remain enforced at runtime as a backstop.
+
+  Two pre-existing bugs fixed along the way:
+
+  - A CEL expression feeding **any** enum-constrained field produced a spurious
+    `SCHEMA_VIOLATION`, because the placeholder substituted for the expression
+    satisfied `type` but violated `enum`. Fixed in both the analyzer and the
+    kernel.
+  - `teardownResources` aborted the whole cascade on the first throwing resource,
+    with no aggregation and no reporting. Failures are now collected into
+    `ERR_TEARDOWN_FAILED` so one bad teardown cannot skip the rest — including the
+    log sinks, which are pinned to tear down last.
+  - The inline `imports:` desugaring silently dropped unknown entry fields, so a
+    per-import `logging:` block never reached the import controller.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
+## 0.15.2
+
+### Patch Changes
+
+- a33b8cc: Log mid-stream failures server-side. When a `mode: stream` route's stream throws
+  after the response headers are flushed, the failure can't reach Fastify's error
+  handler or a `catches:` entry, so it was previously silent for the operator (it
+  was only emitted as an `Http.Api.streamFailed` event, which nothing logs unless a
+  debug consumer is attached). The stream-error hook now also logs on the server's
+  request logger (the one `Http.Server.logger` configures) at `error` level with
+  the error, route, status, and MIME. Client-facing behaviour is unchanged.
+  - @telorun/http-dispatch@0.4.1
+
 ## 0.15.1
 
 ### Patch Changes

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

@@ -0,0 +1,29 @@
+import { pinoLevelForSeverity, severityForPinoLevel, type Logger } from "@telorun/sdk";
+/**
+ * A Telo-backed logger injected into Fastify — `kernel/specs/logging.md` §13.3.
+ *
+ * Replacement, not bridging. Fastify accepts an injected logger satisfying a
+ * small interface, so its records are Telo records **from the moment they are
+ * created**: no format to translate, no second pipeline, and no possibility of
+ * the two diverging. Bridging — intercepting the stream Pino writes and
+ * re-parsing it — is strictly worse and is reserved for libraries that offer no
+ * injection point.
+ *
+ * This also removes the duplication where a mid-stream failure was both logged
+ * to Pino and separately re-emitted as an event for debug tooling: with the
+ * adapter in place, one record reaches every sink, including the debug wire.
+ */
+/** The subset of Pino's interface Fastify actually calls. */
+export interface FastifyLogger {
+    level: string;
+    fatal(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    trace(...args: unknown[]): void;
+    silent(...args: unknown[]): void;
+    child(bindings: Record<string, unknown>): FastifyLogger;
+}
+export declare function createFastifyTeloLogger(log: Logger): FastifyLogger;
+export { pinoLevelForSeverity, severityForPinoLevel };

package/dist/fastify-telo-logger.js

@@ -0,0 +1,109 @@
+import { pinoLevelForSeverity, SEVERITY, severityForPinoLevel, severityText, } from "@telorun/sdk";
+export function createFastifyTeloLogger(log) {
+    const emit = (severity, args) => {
+        if (!log.enabled(severity))
+            return;
+        const { message, attributes, error } = splitPinoArgs(args);
+        log.log(severity, message, attributes, error === undefined ? undefined : { error });
+    };
+    return {
+        // Fastify reads `level` to decide whether to build a request-log object at
+        // all. Reporting the most verbose level Telo would accept keeps that gate
+        // aligned with the pipeline's own, which is the real threshold.
+        get level() {
+            for (const severity of [SEVERITY.trace, SEVERITY.debug, SEVERITY.info, SEVERITY.warn]) {
+                if (log.enabled(severity))
+                    return severityText(severity).toLowerCase();
+            }
+            return log.enabled(SEVERITY.error) ? "error" : "silent";
+        },
+        set level(_value) {
+            // Fastify may try to set a level; the manifest is the only configuration
+            // source (D6), so this is deliberately inert.
+        },
+        fatal: (...args) => emit(SEVERITY.fatal, args),
+        error: (...args) => emit(SEVERITY.error, args),
+        warn: (...args) => emit(SEVERITY.warn, args),
+        info: (...args) => emit(SEVERITY.info, args),
+        debug: (...args) => emit(SEVERITY.debug, args),
+        trace: (...args) => emit(SEVERITY.trace, args),
+        silent: () => { },
+        // Fastify's per-request child logger maps onto §8.3's bound attributes.
+        child: (bindings) => createFastifyTeloLogger(log.with(normalizeBindings(bindings))),
+    };
+}
+/**
+ * Pino's call shapes are `(msg)`, `(obj)`, `(obj, msg)`, and `(msg, ...interp)`.
+ * Telo requires a string message with structured data in attributes, so the
+ * object half becomes attributes and the string half the message.
+ */
+function splitPinoArgs(args) {
+    const [first, second] = args;
+    if (typeof first === "string") {
+        return { message: interpolate(first, args.slice(1)), attributes: undefined, error: undefined };
+    }
+    if (first && typeof first === "object") {
+        const bag = { ...first };
+        // Pino puts the error under `err`; Telo has a dedicated top-level field for
+        // it, so it is lifted out of the attributes rather than serialized twice.
+        const error = bag["err"];
+        delete bag["err"];
+        const message = typeof second === "string" ? interpolate(second, args.slice(2)) : "";
+        return { message, attributes: normalizeBindings(bag), error };
+    }
+    return { message: first === undefined ? "" : String(first), attributes: undefined, error: undefined };
+}
+/** Pino's printf-style interpolation, limited to the specifiers it documents. */
+function interpolate(template, values) {
+    if (values.length === 0)
+        return template;
+    let index = 0;
+    return template.replace(/%[sdjoO%]/g, (token) => {
+        if (token === "%%")
+            return "%";
+        if (index >= values.length)
+            return token;
+        const value = values[index++];
+        return typeof value === "string" ? value : safeStringify(value);
+    });
+}
+function normalizeBindings(bindings) {
+    const out = {};
+    for (const [key, value] of Object.entries(bindings)) {
+        // Fastify binds `req`/`res` objects that are not attribute values; their
+        // useful fields are already carried as OTel semantic conventions below.
+        if (key === "req" || key === "res") {
+            Object.assign(out, httpAttributes(value));
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/** §6.2: where a standard OTel semantic convention exists, use it rather than a
+ *  Telo-specific spelling. */
+function httpAttributes(value) {
+    if (!value || typeof value !== "object")
+        return {};
+    const source = value;
+    const out = {};
+    if (typeof source["method"] === "string")
+        out["http.request.method"] = source["method"];
+    if (typeof source["url"] === "string")
+        out["url.path"] = source["url"];
+    if (typeof source["statusCode"] === "number") {
+        out["http.response.status_code"] = source["statusCode"];
+    }
+    // Headers are NOT captured: §14.4 requires explicit configuration naming the
+    // headers, matching OTel's Opt-In requirement level.
+    return out;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export { pinoLevelForSeverity, severityForPinoLevel };

package/dist/http-api-controller.js

@@ -165,15 +165,28 @@ export class HttpServerApi {
                     return dispatchCatches(route.catches, { code: err.code, message: err.message, data: err.data }, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink);
                 }
                 await span.settle("ok");
-                return dispatchReturns(route.returns, result, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink, (err, errCtx) => this.ctx.emitEvent("Http.Api.streamFailed", {
-                    path: route.request.path,
-                    method: route.request.method,
-                    status: errCtx.status,
-                    mime: errCtx.mime,
-                    error: err instanceof Error
-                        ? { message: err.message, stack: err.stack, code: err.code }
-                        : { message: String(err) },
-                }));
+                return dispatchReturns(route.returns, result, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink, (err, errCtx) => {
+                    // Headers are already flushed, so this failure can't reach Fastify's
+                    // error handler (which logs pre-stream throws) — log it here, on the
+                    // same request logger `logger:` configures, so a mid-stream failure
+                    // isn't silent server-side. The event below stays for debug tooling.
+                    reply.log.error({
+                        err,
+                        path: route.request.path,
+                        method: route.request.method,
+                        status: errCtx.status,
+                        mime: errCtx.mime,
+                    }, "Http.Api stream failed after response headers were flushed");
+                    return this.ctx.emitEvent("Http.Api.streamFailed", {
+                        path: route.request.path,
+                        method: route.request.method,
+                        status: errCtx.status,
+                        mime: errCtx.mime,
+                        error: err instanceof Error
+                            ? { message: err.message, stack: err.stack, code: err.code }
+                            : { message: String(err) },
+                    });
+                });
             },
         });
     }

package/dist/http-server-controller.js

@@ -1,4 +1,5 @@
 import cors from "@fastify/cors";
+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";
@@ -34,7 +35,12 @@ class HttpServer {
         // it, the legacy `trustForwardedHeaders` boolean still applies.
         const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
         this.app = Fastify({
-            logger: resource.logger,
+            // §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,
             trustProxy,
             ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default] },
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.15.1",
+  "version": "0.16.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.38.0"
+    "@telorun/sdk": "0.50.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/fastify-telo-logger.ts

@@ -0,0 +1,150 @@
+import {
+  pinoLevelForSeverity,
+  SEVERITY,
+  severityForPinoLevel,
+  severityText,
+  type LogAttributesInput,
+  type Logger,
+} from "@telorun/sdk";
+
+/**
+ * A Telo-backed logger injected into Fastify — `kernel/specs/logging.md` §13.3.
+ *
+ * Replacement, not bridging. Fastify accepts an injected logger satisfying a
+ * small interface, so its records are Telo records **from the moment they are
+ * created**: no format to translate, no second pipeline, and no possibility of
+ * the two diverging. Bridging — intercepting the stream Pino writes and
+ * re-parsing it — is strictly worse and is reserved for libraries that offer no
+ * injection point.
+ *
+ * This also removes the duplication where a mid-stream failure was both logged
+ * to Pino and separately re-emitted as an event for debug tooling: with the
+ * adapter in place, one record reaches every sink, including the debug wire.
+ */
+
+/** The subset of Pino's interface Fastify actually calls. */
+export interface FastifyLogger {
+  level: string;
+  fatal(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+  trace(...args: unknown[]): void;
+  silent(...args: unknown[]): void;
+  child(bindings: Record<string, unknown>): FastifyLogger;
+}
+
+export function createFastifyTeloLogger(log: Logger): FastifyLogger {
+  const emit = (severity: number, args: unknown[]): void => {
+    if (!log.enabled(severity)) return;
+    const { message, attributes, error } = splitPinoArgs(args);
+    log.log(severity, message, attributes, error === undefined ? undefined : { error });
+  };
+
+  return {
+    // Fastify reads `level` to decide whether to build a request-log object at
+    // all. Reporting the most verbose level Telo would accept keeps that gate
+    // aligned with the pipeline's own, which is the real threshold.
+    get level(): string {
+      for (const severity of [SEVERITY.trace, SEVERITY.debug, SEVERITY.info, SEVERITY.warn]) {
+        if (log.enabled(severity)) return severityText(severity).toLowerCase();
+      }
+      return log.enabled(SEVERITY.error) ? "error" : "silent";
+    },
+    set level(_value: string) {
+      // Fastify may try to set a level; the manifest is the only configuration
+      // source (D6), so this is deliberately inert.
+    },
+    fatal: (...args) => emit(SEVERITY.fatal, args),
+    error: (...args) => emit(SEVERITY.error, args),
+    warn: (...args) => emit(SEVERITY.warn, args),
+    info: (...args) => emit(SEVERITY.info, args),
+    debug: (...args) => emit(SEVERITY.debug, args),
+    trace: (...args) => emit(SEVERITY.trace, args),
+    silent: () => {},
+    // Fastify's per-request child logger maps onto §8.3's bound attributes.
+    child: (bindings) => createFastifyTeloLogger(log.with(normalizeBindings(bindings))),
+  };
+}
+
+/**
+ * Pino's call shapes are `(msg)`, `(obj)`, `(obj, msg)`, and `(msg, ...interp)`.
+ * Telo requires a string message with structured data in attributes, so the
+ * object half becomes attributes and the string half the message.
+ */
+function splitPinoArgs(args: unknown[]): {
+  message: string;
+  attributes: LogAttributesInput | undefined;
+  error: unknown;
+} {
+  const [first, second] = args;
+
+  if (typeof first === "string") {
+    return { message: interpolate(first, args.slice(1)), attributes: undefined, error: undefined };
+  }
+
+  if (first && typeof first === "object") {
+    const bag = { ...(first as Record<string, unknown>) };
+    // Pino puts the error under `err`; Telo has a dedicated top-level field for
+    // it, so it is lifted out of the attributes rather than serialized twice.
+    const error = bag["err"];
+    delete bag["err"];
+    const message = typeof second === "string" ? interpolate(second, args.slice(2)) : "";
+    return { message, attributes: normalizeBindings(bag), error };
+  }
+
+  return { message: first === undefined ? "" : String(first), attributes: undefined, error: undefined };
+}
+
+/** Pino's printf-style interpolation, limited to the specifiers it documents. */
+function interpolate(template: string, values: unknown[]): string {
+  if (values.length === 0) return template;
+  let index = 0;
+  return template.replace(/%[sdjoO%]/g, (token) => {
+    if (token === "%%") return "%";
+    if (index >= values.length) return token;
+    const value = values[index++];
+    return typeof value === "string" ? value : safeStringify(value);
+  });
+}
+
+function normalizeBindings(bindings: Record<string, unknown>): LogAttributesInput {
+  const out: LogAttributesInput = {};
+  for (const [key, value] of Object.entries(bindings)) {
+    // Fastify binds `req`/`res` objects that are not attribute values; their
+    // useful fields are already carried as OTel semantic conventions below.
+    if (key === "req" || key === "res") {
+      Object.assign(out, httpAttributes(value));
+      continue;
+    }
+    out[key] = value as never;
+  }
+  return out;
+}
+
+/** §6.2: where a standard OTel semantic convention exists, use it rather than a
+ *  Telo-specific spelling. */
+function httpAttributes(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object") return {};
+  const source = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  if (typeof source["method"] === "string") out["http.request.method"] = source["method"];
+  if (typeof source["url"] === "string") out["url.path"] = source["url"];
+  if (typeof source["statusCode"] === "number") {
+    out["http.response.status_code"] = source["statusCode"];
+  }
+  // Headers are NOT captured: §14.4 requires explicit configuration naming the
+  // headers, matching OTel's Opt-In requirement level.
+  return out;
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export { pinoLevelForSeverity, severityForPinoLevel };

package/src/http-api-controller.ts

@@ -222,8 +222,22 @@ export class HttpServerApi implements ResourceInstance {
           this.ctx.moduleContext,
           this.ctx.validateSchema.bind(this.ctx),
           sink,
-          (err, errCtx) =>
-            this.ctx.emitEvent("Http.Api.streamFailed", {
+          (err, errCtx) => {
+            // Headers are already flushed, so this failure can't reach Fastify's
+            // error handler (which logs pre-stream throws) — log it here, on the
+            // same request logger `logger:` configures, so a mid-stream failure
+            // isn't silent server-side. The event below stays for debug tooling.
+            reply.log.error(
+              {
+                err,
+                path: route.request.path,
+                method: route.request.method,
+                status: errCtx.status,
+                mime: errCtx.mime,
+              },
+              "Http.Api stream failed after response headers were flushed",
+            );
+            return this.ctx.emitEvent("Http.Api.streamFailed", {
               path: route.request.path,
               method: route.request.method,
               status: errCtx.status,
@@ -232,7 +246,8 @@ export class HttpServerApi implements ResourceInstance {
                 err instanceof Error
                   ? { message: err.message, stack: err.stack, code: (err as { code?: string }).code }
                   : { message: String(err) },
-            }),
+            });
+          },
         );
       },
     });

package/src/http-server-controller.ts

@@ -1,4 +1,5 @@
 import cors from "@fastify/cors";
+import { createFastifyTeloLogger } from "./fastify-telo-logger.js";
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
 import {
@@ -112,7 +113,12 @@ class HttpServer implements ResourceInstance {
     // it, the legacy `trustForwardedHeaders` boolean still applies.
     const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
     this.app = Fastify({
-      logger: resource.logger,
+      // §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,
       trustProxy,
       ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default as any] },
     });