@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/telemetry/fields.js

@@ -0,0 +1,64 @@
+/**
+ * The privacy-safe field catalog (H17): what a log line or a span may say about a request. Paths
+ * go without their query or fragment; cookies, credentials and bodies never appear at all.
+ */
+/** Every field a request-log line carries; nothing outside it is ever written. */
+export const REQUEST_LOG_FIELDS = /* @__PURE__ */ Object.freeze([
+    "bytes",
+    "durationMs",
+    "kind",
+    "method",
+    "path",
+    "requestId",
+    "routeId",
+    "runtime",
+    "status",
+]);
+const SENSITIVE = /* @__PURE__ */ Object.freeze({
+    authorization: true,
+    cookie: true,
+    "proxy-authorization": true,
+    "set-cookie": true,
+    "x-api-key": true,
+    "x-auth-token": true,
+    "x-csrf-token": true,
+    "x-xsrf-token": true,
+});
+/* a name with a token, secret, API key, password or session as a whole dash-separated part */
+const SENSITIVE_PART = /(?:^|-)(?:token|secret|api-?key|password|session)(?:$|-)/i;
+/**
+ * A header whose value is a credential, a cookie or a session: never logged, never a span
+ * attribute. One definition for the request log, spans and curlLogger's redaction.
+ */
+export function isSensitiveHeader(name) {
+    return Object.hasOwn(SENSITIVE, name.toLowerCase()) || SENSITIVE_PART.test(name);
+}
+/** The path of `target` (a URL or a path) without its query or fragment; `/` when empty. */
+export function pathOf(target) {
+    let start = 0;
+    const scheme = target.indexOf("://");
+    if (scheme !== -1) {
+        const slash = target.indexOf("/", scheme + 3);
+        const end = target.search(/[?#]/);
+        if (slash === -1 || (end !== -1 && end < slash))
+            return "/";
+        start = slash;
+    }
+    const cut = target.slice(start).search(/[?#]/);
+    const path = cut === -1 ? target.slice(start) : target.slice(start, start + cut);
+    return path === "" ? "/" : path;
+}
+/**
+ * What a per-request logger binds: method, the path without its query, the route id, the request
+ * id when set, and the trace's ids when the request is traced (so a line joins its trace).
+ */
+export function requestBindings(method, path, routeId, { requestId, trace } = {}) {
+    const bindings = { method, path: pathOf(path), routeId };
+    if (requestId !== undefined)
+        bindings.requestId = requestId;
+    if (trace != null) {
+        bindings.trace_id = trace.traceId;
+        bindings.span_id = trace.spanId;
+    }
+    return bindings;
+}

package/dist/telemetry/log-format.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A log record as one line: JSON (pino's shape, for production and log shippers) or pretty (for a
+ * developer's terminal). A value JSON cannot hold (a BigInt, a cycle) never fails the line.
+ */
+export type LogFormat = "json" | "pretty";
+/** `record` as one line in `format`. */
+export declare function formatLine(format: LogFormat, record: Record<string, unknown>): string;

package/dist/telemetry/log-format.js

@@ -0,0 +1,43 @@
+/**
+ * A log record as one line: JSON (pino's shape, for production and log shippers) or pretty (for a
+ * developer's terminal). A value JSON cannot hold (a BigInt, a cycle) never fails the line.
+ */
+const NAMES = /* @__PURE__ */ Object.freeze({
+    10: "TRACE",
+    20: "DEBUG",
+    30: "INFO",
+    40: "WARN",
+    50: "ERROR",
+    60: "FATAL",
+});
+/** JSON.stringify that writes a BigInt as its digits and an object inside itself as "[Circular]". */
+function stringify(value) {
+    /* the objects enclosing the one being written: only a true cycle is cut, a shared object is written each time */
+    const ancestors = [];
+    return JSON.stringify(value, function (_key, item) {
+        if (typeof item === "bigint")
+            return item.toString();
+        if (typeof item !== "object" || item === null)
+            return item;
+        while (ancestors.length > 0 && ancestors.at(-1) !== this)
+            ancestors.pop();
+        if (ancestors.includes(item))
+            return "[Circular]";
+        ancestors.push(item);
+        return item;
+    });
+}
+function clock(time) {
+    return new Date(time).toISOString().slice(11, 23);
+}
+function pretty(record) {
+    const { level, msg, time, ...fields } = record;
+    const head = `${clock(time)} ${(NAMES[level] ?? String(level)).padEnd(5)} ${String(msg)}`;
+    const err = fields.err;
+    const rest = Object.keys(fields).length > 0 ? ` ${stringify(fields)}` : "";
+    return typeof err?.stack === "string" ? `${head}${rest}\n${err.stack}` : `${head}${rest}`;
+}
+/** `record` as one line in `format`. */
+export function formatLine(format, record) {
+    return format === "pretty" ? pretty(record) : stringify(record);
+}

package/dist/telemetry/logger.d.ts

@@ -0,0 +1,44 @@
+import { type LogFormat } from "./log-format.ts";
+export type LogLevel = "debug" | "error" | "fatal" | "info" | "silent" | "trace" | "warn";
+/** pino's numeric levels; `silent` is above every one. */
+export declare const LEVELS: Readonly<Record<LogLevel, number>>;
+type LogFn = {
+    (msg: string): void;
+    (fields: Record<string, unknown>, msg?: string): void;
+};
+export type Logger = {
+    readonly level: LogLevel;
+    /** A logger that writes `bindings` into every line, over this one's. */
+    child(bindings: Record<string, unknown>): Logger;
+    debug: LogFn;
+    error: LogFn;
+    fatal: LogFn;
+    info: LogFn;
+    trace: LogFn;
+    warn: LogFn;
+};
+export type CreateLoggerOptions = {
+    /** Fields every line carries. */
+    base?: Record<string, unknown>;
+    /** Default: `pretty` when NODE_ENV is development, else `json`. */
+    format?: LogFormat;
+    /** Default: `debug` in development, `error` in test (an incident is never swallowed), else `info`. */
+    level?: LogLevel;
+    /** Where a line goes. Default: the console on Workers, stdout on Node and Bun. */
+    write?: (line: string) => void;
+};
+/** NODE_ENV where the runtime has a process environment; undefined where it has none (Workers). */
+export declare function nodeEnv(): string | undefined;
+/**
+ * The default level and format for a NODE_ENV. Unset, unreadable or unknown takes production's:
+ * forgetting NODE_ENV must never turn on debug output.
+ */
+export declare function defaultsFor(env: string | undefined): {
+    format: LogFormat;
+    level: LogLevel;
+};
+/** A logger. Unset level and format follow NODE_ENV, read now (`defaultsFor`). */
+export declare function createLogger(options?: CreateLoggerOptions): Logger;
+/** The logger that writes nothing: what `app.logger(false)` sets. Its children are itself. */
+export declare const SILENT: Logger;
+export {};

package/dist/telemetry/logger.js

@@ -0,0 +1,136 @@
+/**
+ * The app logger (H17): pino-compatible levels and line shape, children that bind fields, and a
+ * sink. Every server-side line honey writes goes through one; `app.logger(value)` replaces the
+ * default, `app.logger(false)` silences it. Below the level nothing is built: no fields read, no
+ * clock read. A plain module: importing it registers nothing (H23).
+ */
+import { HoneyError } from "../errors/error.js";
+import { formatLine } from "./log-format.js";
+/** pino's numeric levels; `silent` is above every one. */
+export const LEVELS = /* @__PURE__ */ Object.freeze({
+    debug: 20,
+    error: 50,
+    fatal: 60,
+    info: 30,
+    silent: Number.POSITIVE_INFINITY,
+    trace: 10,
+    warn: 40,
+});
+/** NODE_ENV where the runtime has a process environment; undefined where it has none (Workers). */
+export function nodeEnv() {
+    return globalThis.process?.env?.NODE_ENV;
+}
+/**
+ * The default level and format for a NODE_ENV. Unset, unreadable or unknown takes production's:
+ * forgetting NODE_ENV must never turn on debug output.
+ */
+export function defaultsFor(env) {
+    if (env === "development")
+        return { format: "pretty", level: "debug" };
+    /* the runner sets NODE_ENV=test, not the author: a quiet test is worth having, a swallowed incident is not */
+    if (env === "test")
+        return { format: "json", level: "error" };
+    return { format: "json", level: "info" };
+}
+/**
+ * Whether this runtime is Workers, by the same mark `detectRuntime` reads (never by calling it: that one throws
+ * where it cannot tell, and a logger must not throw as it is made).
+ */
+function onWorkers() {
+    const agent = globalThis.navigator?.userAgent ?? "";
+    return agent.startsWith("Cloudflare-Workers") || agent.startsWith("workerd");
+}
+function defaultSink() {
+    /* the console is where a worker's logs go, and `nodejs_compat` gives it a process.stdout that they do not:
+       the sink follows the runtime, not whichever globals happen to exist (bit 22 a) */
+    // oxlint-disable-next-line no-console
+    if (onWorkers())
+        return (line) => console.log(line);
+    const stdout = globalThis.process?.stdout;
+    if (typeof stdout?.write === "function")
+        return (line) => void stdout.write(`${line}\n`);
+    /* a runtime with neither: the console is the one sink left */
+    // oxlint-disable-next-line no-console
+    return (line) => console.log(line);
+}
+/** `fields` with each Error written as its name, message, stack and cause instead of `{}`. */
+function withErrors(fields) {
+    let out = null;
+    for (const key in fields) {
+        const value = fields[key];
+        if (value instanceof Error) {
+            out ??= { ...fields };
+            out[key] = HoneyError.serialize(value);
+        }
+    }
+    return out ?? fields;
+}
+/* methods live on the prototype: a per-request child must not allocate a closure per level */
+class LoggerImpl {
+    level;
+    #base;
+    #format;
+    #threshold;
+    #write;
+    constructor(level, format, write, base) {
+        this.level = level;
+        this.#base = base;
+        this.#format = format;
+        this.#threshold = LEVELS[level];
+        this.#write = write;
+    }
+    child(bindings) {
+        return new LoggerImpl(this.level, this.#format, this.#write, { ...this.#base, ...bindings });
+    }
+    trace(first, msg) {
+        this.#emit(10, first, msg);
+    }
+    debug(first, msg) {
+        this.#emit(20, first, msg);
+    }
+    info(first, msg) {
+        this.#emit(30, first, msg);
+    }
+    warn(first, msg) {
+        this.#emit(40, first, msg);
+    }
+    error(first, msg) {
+        this.#emit(50, first, msg);
+    }
+    fatal(first, msg) {
+        this.#emit(60, first, msg);
+    }
+    #emit(level, first, msg) {
+        if (level < this.#threshold)
+            return;
+        try {
+            const record = typeof first === "string"
+                ? { ...this.#base, level, msg: first, time: Date.now() }
+                : { ...this.#base, ...withErrors(first), level, msg: msg ?? "", time: Date.now() };
+            this.#write(formatLine(this.#format, record));
+        }
+        catch {
+            /* a failing sink or a field that cannot be read: the logger is the last reporter, nothing is left to tell */
+        }
+    }
+}
+/** A logger. Unset level and format follow NODE_ENV, read now (`defaultsFor`). */
+export function createLogger(options = {}) {
+    const defaults = options.level === undefined || options.format === undefined ? defaultsFor(nodeEnv()) : null;
+    return new LoggerImpl(options.level ?? defaults.level, options.format ?? defaults.format, options.write ?? defaultSink(), options.base ?? {});
+}
+function noop() { }
+function silentChild() {
+    return SILENT;
+}
+/** The logger that writes nothing: what `app.logger(false)` sets. Its children are itself. */
+export const SILENT = /* @__PURE__ */ Object.freeze({
+    child: silentChild,
+    debug: noop,
+    error: noop,
+    fatal: noop,
+    info: noop,
+    level: "silent",
+    trace: noop,
+    warn: noop,
+});

package/dist/telemetry/otel-subpath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@lovrozagar/honey/telemetry`: `otelAdapter` and the types of the value `app.telemetry()` carries.
+ * A plain subpath for tree-shaking: honey imports no OpenTelemetry package.
+ */
+export { type OtelAdapterOptions, type OtelApi, otelAdapter } from "./otel.ts";
+export type { Attributes, AttributeValue, Span, SpanOptions, Telemetry, TelemetryErrorReport, Tracer, } from "./request-trace.ts";
+export type { RemoteContext } from "./traceparent.ts";

package/dist/telemetry/otel-subpath.js

@@ -0,0 +1,5 @@
+/**
+ * `@lovrozagar/honey/telemetry`: `otelAdapter` and the types of the value `app.telemetry()` carries.
+ * A plain subpath for tree-shaking: honey imports no OpenTelemetry package.
+ */
+export { otelAdapter } from "./otel.js";

package/dist/telemetry/otel.d.ts

@@ -1,61 +1,54 @@
-import type { HoneyError } from "../error.ts";
-type Span = {
-    addEvent(name: string, attributes?: Record<string, unknown>): void;
-    end(): void;
-    setAttribute(key: string, value: unknown): void;
+/**
+ * `otelAdapter(api, options)`: the Telemetry value `app.telemetry()` carries, over the app's own
+ * OpenTelemetry API. Pass the `@opentelemetry/api` module itself; honey imports no OpenTelemetry
+ * package, so there is one shared instance and nothing to load. Only `trace` and `context` are used:
+ * honey parses `traceparent` itself (the trust gate validates what it continues), so no propagator
+ * has to be registered. Every span's parent is passed explicitly; `run` makes the handler's span the
+ * active one only so the app's own instrumentation nests under it.
+ */
+import type { InboundTrust } from "../middleware/request-id.ts";
+import type { Attributes, Span, Telemetry, TelemetryErrorReport } from "./request-trace.ts";
+/** OpenTelemetry's `TraceState`, as its spans carry one. */
+type OtelTraceState = {
+    get(key: string): string | undefined;
+    serialize(): string;
+    set(key: string, value: string): OtelTraceState;
+    unset(key: string): OtelTraceState;
 };
-type Tracer = {
-    startSpan(name: string): Span;
+type OtelSpanContext = {
+    readonly isRemote?: boolean;
+    readonly spanId: string;
+    readonly traceFlags: number;
+    readonly traceId: string;
+    readonly traceState?: OtelTraceState;
 };
-type TelemetryAdapter = {
-    onError?(ctx: {
-        duration: number;
-        error: HoneyError;
-        method: string;
-        path: string;
-    }): void;
-    onHandler?(ctx: {
-        duration: number;
-        method: string;
-        path: string;
-        route?: string;
-        status: number;
-    }): void;
-    onMethodNotAllowed?(ctx: {
-        allowed: string[];
-        method: string;
-        path: string;
-        req: Request;
-    }): void;
-    onMiddleware?(ctx: {
-        duration: number;
-        error?: unknown;
-        name: string;
-    }): void;
-    onNotFound?(ctx: {
-        method: string;
-        path: string;
-        req: Request;
-    }): void;
-    onRequest?(ctx: {
-        env: unknown;
-        req: Request;
-    }): void;
-    onResponse?(ctx: {
-        duration: number;
-        req: Request;
-        status: number;
-    }): void;
-    onRoute?(ctx: {
-        method: string;
-        params: Record<string, string>;
-        path: string;
-        req: Request;
-        route?: string;
-    }): void;
+type OtelSpanOptions = {
+    readonly attributes?: Attributes;
+    readonly kind?: number;
+    readonly links?: {
+        readonly context: OtelSpanContext;
+    }[];
 };
-export declare function otelAdapter(options: {
-    tracer: Tracer;
-}): TelemetryAdapter;
+/** The part of `@opentelemetry/api` the adapter uses: pass the module itself. */
+export type OtelApi = {
+    readonly context: {
+        active(): unknown;
+        with<T>(context: unknown, fn: () => T): T;
+    };
+    readonly trace: {
+        deleteSpan(context: unknown): unknown;
+        getTracer(name: string): {
+            startSpan(name: string, options?: OtelSpanOptions, context?: unknown): Span;
+        };
+        setSpan(context: unknown, span: Span): unknown;
+        setSpanContext(context: unknown, spanContext: OtelSpanContext): unknown;
+    };
+};
+export type OtelAdapterOptions = {
+    /** fire-and-forget error reporting: never awaited, never shapes the answer */
+    onError?: (report: TelemetryErrorReport) => unknown;
+    /** continue an inbound `traceparent` from this hop (else it is only linked); default `false` */
+    trustInbound?: InboundTrust;
+};
+export declare function otelAdapter(api: OtelApi, options?: OtelAdapterOptions): Telemetry;
 export {};
-//# sourceMappingURL=otel.d.ts.map

package/dist/telemetry/otel.js

@@ -1,135 +1,59 @@
-/**
- * The request URL without its query string or fragment: queries carry tokens and session ids,
- * and attribute values are exported to whatever backend the tracer feeds.
- */
-function urlWithoutQuery(url) {
-    const q = url.indexOf("?");
-    const h = url.indexOf("#");
-    const end = q === -1 ? h : h === -1 ? q : Math.min(q, h);
-    return end === -1 ? url : url.slice(0, end);
+/** OpenTelemetry's `SpanKind`. */
+const KIND = { client: 2, internal: 0, server: 1 };
+/** W3C caps a tracestate at 32 members. */
+const MAX_MEMBERS = 32;
+/** A W3C tracestate: ordered members, an edited key moved to the front, immutable. */
+class TraceState {
+    #members;
+    constructor(members) {
+        this.#members = members;
+    }
+    /** From a header `parseTracestate` already validated. */
+    static parse(header) {
+        return new TraceState(header.split(",").map((member) => {
+            const eq = member.indexOf("=");
+            return [member.slice(0, eq), member.slice(eq + 1)];
+        }));
+    }
+    get(key) {
+        return this.#members.find(([k]) => k === key)?.[1];
+    }
+    set(key, value) {
+        return new TraceState([[key, value], ...this.#members.filter(([k]) => k !== key)].slice(0, MAX_MEMBERS));
+    }
+    unset(key) {
+        return new TraceState(this.#members.filter(([k]) => k !== key));
+    }
+    serialize() {
+        return this.#members.map(([k, v]) => `${k}=${v}`).join(",");
+    }
 }
-/** Path part of an absolute URL, without the query. */
-function pathOf(url) {
-    const bare = urlWithoutQuery(url);
-    const scheme = bare.indexOf("//");
-    const start = scheme === -1 ? 0 : bare.indexOf("/", scheme + 2);
-    return start === -1 ? "/" : bare.slice(start);
+function remoteContext(remote) {
+    const context = { isRemote: true, spanId: remote.spanId, traceFlags: remote.flags, traceId: remote.traceId };
+    return remote.state === undefined ? context : { ...context, traceState: TraceState.parse(remote.state) };
 }
-export function otelAdapter(options) {
-    const spans = new WeakMap();
-    return {
-        onError(ctx) {
-            try {
-                /*
-                 * onError doesn't receive req — error details are best captured
-                 * via a standalone span. Per-request root span is in onResponse.
-                 */
-                const span = options.tracer.startSpan("http.error");
-                span.setAttribute("error.key", ctx.error.errorKey);
-                span.setAttribute("error.status", ctx.error.status);
-                span.setAttribute("http.duration_ms", ctx.duration);
-                span.end();
-            }
-            catch {
-                /* swallow */
-            }
-        },
-        onHandler(ctx) {
-            try {
-                const span = options.tracer.startSpan("http.handler");
-                span.setAttribute("http.method", ctx.method);
-                /* the pattern, never the request path: one series per route, not per id */
-                if (ctx.route !== undefined && ctx.route !== "")
-                    span.setAttribute("http.route", ctx.route);
-                span.setAttribute("http.status_code", ctx.status);
-                span.setAttribute("http.duration_ms", ctx.duration);
-                span.end();
-            }
-            catch {
-                /* swallow */
-            }
-        },
-        onMethodNotAllowed(ctx) {
-            try {
-                const span = spans.get(ctx.req);
-                if (span) {
-                    span.addEvent("method_not_allowed", {
-                        "http.allowed_methods": ctx.allowed.join(", "),
-                        "http.method": ctx.method,
-                        "url.path": ctx.path,
-                    });
-                }
-            }
-            catch {
-                /* swallow */
-            }
-        },
-        onMiddleware(ctx) {
-            try {
-                const span = options.tracer.startSpan(`middleware.${ctx.name}`);
-                span.setAttribute("middleware.name", ctx.name);
-                span.setAttribute("middleware.duration_ms", ctx.duration);
-                if (ctx.error)
-                    span.addEvent("error");
-                span.end();
-            }
-            catch {
-                /* swallow */
-            }
-        },
-        onNotFound(ctx) {
-            try {
-                const span = spans.get(ctx.req);
-                if (span) {
-                    span.addEvent("not_found", {
-                        "http.method": ctx.method,
-                        "url.path": ctx.path,
-                    });
-                }
-            }
-            catch {
-                /* swallow */
-            }
-        },
-        onRequest(ctx) {
-            try {
-                const span = options.tracer.startSpan("http.request");
-                span.setAttribute("http.method", ctx.req.method);
-                span.setAttribute("http.url", urlWithoutQuery(ctx.req.url));
-                span.setAttribute("url.path", pathOf(ctx.req.url));
-                spans.set(ctx.req, span);
-            }
-            catch {
-                /* swallow */
-            }
-        },
-        onResponse(ctx) {
-            try {
-                const span = spans.get(ctx.req);
-                if (span) {
-                    span.setAttribute("http.status_code", ctx.status);
-                    span.setAttribute("http.duration_ms", ctx.duration);
-                    span.end();
-                    spans.delete(ctx.req);
-                }
-            }
-            catch {
-                /* swallow */
-            }
-        },
-        onRoute(ctx) {
-            try {
-                const span = spans.get(ctx.req);
-                if (span) {
-                    span.setAttribute("http.method", ctx.method);
-                    if (ctx.route !== undefined && ctx.route !== "")
-                        span.setAttribute("http.route", ctx.route);
-                }
-            }
-            catch {
-                /* swallow */
-            }
+function isSpan(parent) {
+    return typeof parent.spanContext === "function";
+}
+export function otelAdapter(api, options = {}) {
+    const otel = api.trace.getTracer("@lovrozagar/honey");
+    const tracer = {
+        run: (span, fn) => api.context.with(api.trace.setSpan(api.context.active(), span), fn),
+        startSpan(name, { attributes, kind, links, parent }) {
+            /* the parent is explicit: whatever span the ambient context holds is not it */
+            const base = api.trace.deleteSpan(api.context.active());
+            const context = parent === null
+                ? base
+                : isSpan(parent)
+                    ? api.trace.setSpan(base, parent)
+                    : api.trace.setSpanContext(base, remoteContext(parent));
+            const linked = links.map((link) => ({ context: remoteContext(link) }));
+            return otel.startSpan(name, { attributes, kind: KIND[kind], links: linked }, context);
         },
     };
+    return Object.freeze({
+        onError: options.onError ?? null,
+        tracer: Object.freeze(tracer),
+        trustInbound: options.trustInbound ?? false,
+    });
 }
-//# sourceMappingURL=otel.js.map

package/dist/telemetry/request-log.d.ts

@@ -0,0 +1,22 @@
+import type { FetchState } from "../routing/dispatch.ts";
+import type { AppSettings } from "../routing/settings.ts";
+import { detectRuntime } from "../runtime/detect-runtime.ts";
+import type { RequestTrace } from "./request-trace.ts";
+import type { BodyEnd } from "./span-lifecycle.ts";
+/**
+ * One observed request: what came in, when, the state routing records so the line can name the
+ * route, and its spans when the app has telemetry.
+ */
+export type Seen = {
+    readonly request: Request;
+    readonly started: number;
+    state: FetchState | null;
+    readonly trace: RequestTrace | undefined;
+};
+/** The runtime `globals` belong to, or `unknown` for one serve() does not know. */
+export declare function runtimeOf(globals?: Parameters<typeof detectRuntime>[0]): string;
+/**
+ * The request log's line for the request `response` answers: what the body observer calls once the
+ * body ended (`ended`) or was cancelled, with the bytes it carried.
+ */
+export declare function requestLine(s: AppSettings<unknown>, seen: Seen, response: Response): BodyEnd;