@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/dist/telemetry/request-log.js

@@ -0,0 +1,83 @@
+/**
+ * The request log (H17, off by default): one `info` line per request after its body ends, from the
+ * field catalog only, or `"aborted"` when the reader cancels first. The body observer
+ * (span-lifecycle.ts) calls the line when the body ended.
+ */
+import { isHoneyResponse, rawBodyOf } from "../response/builder.js";
+import { detectRuntime } from "../runtime/detect-runtime.js";
+import { pathOf } from "./fields.js";
+function header(response, name) {
+    if (!isHoneyResponse(response))
+        return response.headers.get(name) ?? undefined;
+    const value = response.plainHeaders[name];
+    return value === undefined ? undefined : String(value);
+}
+/** A media type's essence: `type/subtype`, lowercased, without parameters. */
+function essenceOf(value) {
+    const text = value ?? "";
+    const semi = text.indexOf(";");
+    return (semi === -1 ? text : text.slice(0, semi)).trim().toLowerCase();
+}
+function kindOf(response, raw) {
+    if (response.status === 101)
+        return "upgrade";
+    const essence = essenceOf(header(response, "content-type"));
+    if (essence === "text/event-stream")
+        return "sse";
+    if (raw === null)
+        return response.body === null ? "empty" : "stream";
+    if (essence === "application/json" || essence.endsWith("+json"))
+        return "json";
+    return essence.slice(0, essence.indexOf("/")) === "text" ? "text" : "binary";
+}
+/** The runtime `globals` belong to, or `unknown` for one serve() does not know. */
+export function runtimeOf(globals = globalThis) {
+    try {
+        return detectRuntime(globals);
+    }
+    catch {
+        /* not a runtime serve() knows: the line says so instead of failing the request */
+        return "unknown";
+    }
+}
+/** Write the line, unless `skip` says not to; a `skip` that throws is logged and the line still written. */
+function write(s, entry) {
+    const skip = s.requestLog?.skip;
+    let skipped = false;
+    if (skip !== undefined) {
+        try {
+            skipped = skip(entry);
+        }
+        catch (error) {
+            s.logger.error({ err: error }, "requestLog skip failed");
+        }
+    }
+    if (!skipped)
+        s.logger.info(entry, "request");
+}
+/**
+ * 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 function requestLine(s, seen, response) {
+    const { request, started } = seen;
+    const entry = {
+        durationMs: 0,
+        kind: kindOf(response, rawBodyOf(response)),
+        method: request.method,
+        path: pathOf(request.url),
+        routeId: seen.state?.plan.route.id ?? "",
+        runtime: runtimeOf(),
+        status: response.status,
+    };
+    const requestId = header(response, "x-request-id");
+    if (requestId !== undefined)
+        entry.requestId = requestId;
+    return (ended, bytes) => {
+        entry.durationMs = Math.round((performance.now() - started) * 1000) / 1000;
+        entry.status = ended ? response.status : "aborted";
+        if (bytes !== undefined)
+            entry.bytes = bytes;
+        write(s, entry);
+    };
+}

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

@@ -0,0 +1,123 @@
+/**
+ * The core tracing seam (H17, G1). With `app.telemetry(value)` set, each request gets a SERVER root
+ * span started before routing and renamed `{method} {route}` once routed, its parent the inbound
+ * trace when the hop is trusted (else only linked). Every middleware and the handler run in an
+ * onion of child spans under it: the parent is the span the request is in now (`current`, saved and
+ * restored around each), passed explicitly, never through an ambient context, so it holds on
+ * Workers. An error that surfaced gets an `http.error` span under the span it came from (the
+ * boundary records it, errors/on-error.ts). Spans carry no message, stack, query or input.
+ * A tracer that throws is a warn and never touches the answer; a root that does not record builds
+ * nothing below it.
+ */
+import type { RouteInfo } from "../context/context.ts";
+import { HoneyError } from "../errors/error.ts";
+import type { MaybePromise } from "../middleware/middleware.ts";
+import type { InboundTrust } from "../middleware/request-id.ts";
+import type { AppSettings } from "../routing/settings.ts";
+import { type RemoteContext } from "./traceparent.ts";
+export type AttributeValue = boolean | number | string;
+export type Attributes = Readonly<Record<string, AttributeValue>>;
+/**
+ * A span as honey uses one: the part of an OpenTelemetry span it calls, so an OTel span is one as
+ * it is. Its context gives ids only: an outbound call carries the tracestate honey validated on the
+ * way in, not entries a vendor SDK added to the span afterwards.
+ */
+export type Span = {
+    addEvent(name: string, attributes?: Attributes): unknown;
+    end(): void;
+    isRecording(): boolean;
+    setAttribute(key: string, value: AttributeValue): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    spanContext(): {
+        readonly spanId: string;
+        readonly traceFlags: number;
+        readonly traceId: string;
+    };
+    updateName(name: string): unknown;
+};
+export type SpanOptions = {
+    readonly attributes: Attributes;
+    readonly kind: "client" | "internal" | "server";
+    readonly links: readonly RemoteContext[];
+    /** explicit: the span it runs under, a remote one, or `null` for a new trace */
+    readonly parent: RemoteContext | Span | null;
+};
+export type Tracer = {
+    startSpan(name: string, options: SpanOptions): Span;
+    /** run `fn` with `span` as the ambient active span, so the app's own instrumentation nests under it */
+    run?<T>(span: Span, fn: () => T): T;
+};
+/** What `telemetry.onError` hears about a thrown error, once its answer is decided. */
+export type TelemetryErrorReport = {
+    /** the unknown 5xx's digest, as the client and the operator line have it */
+    readonly digest?: string;
+    readonly durationMs: number;
+    /** what was thrown */
+    readonly error: unknown;
+    /** what it answered as */
+    readonly honeyError: HoneyError;
+    readonly method: string;
+    /** without the query */
+    readonly path: string;
+    readonly routeId: string;
+    readonly spanId?: string;
+    readonly traceId?: string;
+};
+/** What `app.telemetry(value)` carries: `otelAdapter(api, options)` builds one. */
+export type Telemetry = {
+    /** fire-and-forget error reporting: never awaited, never shapes the answer */
+    readonly onError: ((report: TelemetryErrorReport) => unknown) | null;
+    readonly tracer: Tracer;
+    /** whether an inbound `traceparent` is continued (else only linked); default `false` */
+    readonly trustInbound: InboundTrust;
+};
+export declare const NO_LINKS: readonly RemoteContext[];
+/** An outbound call's trace: the headers that carry it, and its span's end. */
+export type Outbound = {
+    /** `null` when the request has no trace ids to pass on */
+    readonly traceparent: string | null;
+    /** the tracestate of a trace continued from a trusted hop */
+    readonly tracestate: string | undefined;
+    /** make the call inside the span, ending it with the answer's status or the failure */
+    send(call: () => Promise<Response> | Response): Promise<Response>;
+};
+/** One request's spans: the root, and where in the onion the request is now. */
+export declare class RequestTrace {
+    #private;
+    readonly recording: boolean;
+    readonly root: Span;
+    readonly started: number;
+    /** `started` is when the request came in; `state` the tracestate of a continued trace */
+    constructor(s: AppSettings<unknown>, tracer: Tracer, root: Span, { started, state }: {
+        readonly started: number;
+        readonly state: string | undefined;
+    });
+    /** The root's trace and span ids, or `null` when it has none. */
+    ids(): {
+        spanId: string;
+        traceId: string;
+    } | null;
+    /** An attribute on the root (`honey.request_id`), when it records. */
+    annotate(key: string, value: AttributeValue): void;
+    /**
+     * A CLIENT span for an outbound call under the current span, and the headers that carry it on.
+     * A root that does not record starts none and passes its own ids on, so the next hop drops too.
+     */
+    outbound(name: string, method: string): Outbound;
+    /** Name the root after the route it runs; a request no route serves keeps the method alone. */
+    routed(route: RouteInfo, method: string): void;
+    event(name: string, attributes?: Attributes): void;
+    /** Run `fn` inside a new span under the current one, which ends when `fn` settles. */
+    within(name: string, fn: (span: Span | null) => MaybePromise<Response>): MaybePromise<Response>;
+    /** `fn` with `span` active for the app's own instrumentation, when the tracer can do that. */
+    run(span: Span | null, fn: () => MaybePromise<Response>): MaybePromise<Response>;
+    /** An `http.error` span under the span the error left, ended at once. */
+    error(error: HoneyError, thrown: unknown, digest: string | undefined): void;
+    /** End the root once the answer's body ended (`ended`) or was cancelled. */
+    end(status: number, ended: boolean, bytes: number | undefined): void;
+    /** The request itself threw (no answer at all): the root ends failed. */
+    fail(thrown: unknown): void;
+}

package/dist/telemetry/request-trace.js

@@ -0,0 +1,199 @@
+import { HoneyError } from "../errors/error.js";
+import { formatTraceparent } from "./traceparent.js";
+/** OpenTelemetry's `SpanStatusCode.ERROR`. */
+const ERROR = 2;
+export const NO_LINKS = /* @__PURE__ */ Object.freeze([]);
+/** What was thrown, by its class alone: never its message. */
+function typeOf(thrown) {
+    return thrown instanceof Error ? thrown.constructor.name || thrown.name : typeof thrown;
+}
+/** A span's ids, or `null` for the all-zero ids of one that has none. */
+function idsOf(span) {
+    const { spanId, traceFlags, traceId } = span.spanContext();
+    return /^0+$/.test(traceId) ? null : { flags: traceFlags, spanId, traceId };
+}
+/** One request's spans: the root, and where in the onion the request is now. */
+export class RequestTrace {
+    #s;
+    #tracer;
+    /** the span the request is in now: what the next span runs under */
+    #current;
+    /** the span an error last left, until its http.error is recorded */
+    #failed = null;
+    recording;
+    root;
+    started;
+    /** the tracestate of a trace continued from a trusted hop */
+    #state;
+    /** `started` is when the request came in; `state` the tracestate of a continued trace */
+    constructor(s, tracer, root, { started, state }) {
+        this.#s = s;
+        this.#tracer = tracer;
+        this.root = root;
+        this.#current = root;
+        this.started = started;
+        this.#state = state;
+        this.recording = this.#safe(() => root.isRecording(), false);
+    }
+    /** Call the tracer; when it throws, warn and go on without it. */
+    #safe(call, fallback) {
+        try {
+            return call();
+        }
+        catch (error) {
+            this.#s.logger.warn({ err: HoneyError.serialize(error) }, "telemetry failed");
+            return fallback;
+        }
+    }
+    /** The root's trace and span ids, or `null` when it has none. */
+    ids() {
+        const ids = this.#safe(() => idsOf(this.root), null);
+        return ids === null ? null : { spanId: ids.spanId, traceId: ids.traceId };
+    }
+    /** An attribute on the root (`honey.request_id`), when it records. */
+    annotate(key, value) {
+        if (this.recording)
+            this.#safe(() => this.root.setAttribute(key, value), undefined);
+    }
+    /**
+     * A CLIENT span for an outbound call under the current span, and the headers that carry it on.
+     * A root that does not record starts none and passes its own ids on, so the next hop drops too.
+     */
+    outbound(name, method) {
+        const parent = this.#current;
+        const options = {
+            attributes: { "http.request.method": method },
+            kind: "client",
+            links: NO_LINKS,
+            parent,
+        };
+        const span = this.recording ? this.#safe(() => this.#tracer.startSpan(name, options), null) : null;
+        const ids = this.#safe(() => idsOf(span ?? this.root), null);
+        const settle = (status, thrown) => this.#safe(() => {
+            if (span === null)
+                return;
+            if (status === null) {
+                span.setStatus({ code: ERROR });
+                span.setAttribute("exception.type", typeOf(thrown));
+            }
+            else
+                span.setAttribute("http.response.status_code", status);
+            span.end();
+        }, undefined);
+        return {
+            async send(call) {
+                let response;
+                try {
+                    response = await call();
+                }
+                catch (thrown) {
+                    settle(null, thrown);
+                    throw thrown;
+                }
+                settle(response.status, undefined);
+                return response;
+            },
+            traceparent: ids === null ? null : formatTraceparent(ids),
+            tracestate: this.#state,
+        };
+    }
+    /** Name the root after the route it runs; a request no route serves keeps the method alone. */
+    routed(route, method) {
+        if (!this.recording || route.id === "")
+            return;
+        this.#safe(() => {
+            this.root.updateName(`${method} ${route.pattern}`);
+            this.root.setAttribute("http.route", route.pattern);
+            this.root.setAttribute("honey.route_id", route.id);
+        }, undefined);
+    }
+    event(name, attributes) {
+        if (this.recording)
+            this.#safe(() => this.root.addEvent(name, attributes), undefined);
+    }
+    /** Run `fn` inside a new span under the current one, which ends when `fn` settles. */
+    within(name, fn) {
+        if (!this.recording)
+            return fn(null);
+        const parent = this.#current;
+        const span = this.#safe(() => this.#tracer.startSpan(name, { attributes: {}, kind: "internal", links: NO_LINKS, parent }), null);
+        if (span === null)
+            return fn(null);
+        this.#current = span;
+        let out;
+        try {
+            out = fn(span);
+        }
+        catch (thrown) {
+            this.#close(span, parent, true, thrown);
+            throw thrown;
+        }
+        if (!(out instanceof Promise)) {
+            this.#close(span, parent, false, undefined);
+            return out;
+        }
+        return out.then((res) => {
+            this.#close(span, parent, false, undefined);
+            return res;
+        }, (thrown) => {
+            this.#close(span, parent, true, thrown);
+            throw thrown;
+        });
+    }
+    #close(span, parent, failed, thrown) {
+        this.#current = parent;
+        this.#safe(() => {
+            if (failed) {
+                this.#failed = span;
+                span.setStatus({ code: ERROR });
+                span.setAttribute("exception.type", typeOf(thrown));
+            }
+            span.end();
+        }, undefined);
+    }
+    /** `fn` with `span` active for the app's own instrumentation, when the tracer can do that. */
+    run(span, fn) {
+        const tracer = this.#tracer;
+        return span === null || tracer.run === undefined ? fn() : tracer.run(span, fn);
+    }
+    /** An `http.error` span under the span the error left, ended at once. */
+    error(error, thrown, digest) {
+        if (!this.recording)
+            return;
+        const parent = this.#failed ?? this.#current;
+        this.#failed = null;
+        const attributes = {
+            "exception.type": typeOf(thrown),
+            "honey.error_key": error.errorKey,
+            "http.response.status_code": error.status,
+        };
+        if (digest !== undefined)
+            attributes["honey.digest"] = digest;
+        this.#safe(() => this.#tracer.startSpan("http.error", { attributes, kind: "internal", links: NO_LINKS, parent }).end(), undefined);
+    }
+    /** End the root once the answer's body ended (`ended`) or was cancelled. */
+    end(status, ended, bytes) {
+        this.#safe(() => {
+            if (this.recording) {
+                this.root.setAttribute("http.response.status_code", status);
+                if (bytes !== undefined)
+                    this.root.setAttribute("http.response.body.size", bytes);
+                if (!ended)
+                    this.root.setAttribute("honey.outcome", "aborted");
+                if (status >= 500)
+                    this.root.setStatus({ code: ERROR });
+            }
+            this.root.end();
+        }, undefined);
+    }
+    /** The request itself threw (no answer at all): the root ends failed. */
+    fail(thrown) {
+        this.#safe(() => {
+            if (this.recording) {
+                this.root.setStatus({ code: ERROR });
+                this.root.setAttribute("exception.type", typeOf(thrown));
+            }
+            this.root.end();
+        }, undefined);
+    }
+}

package/dist/telemetry/span-lifecycle.d.ts

@@ -0,0 +1,11 @@
+import type { AppSettings } from "../routing/settings.ts";
+import { type Seen } from "./request-log.ts";
+import { RequestTrace, type Telemetry } from "./request-trace.ts";
+/** The root span of `request`, under or linked to its inbound trace as the hop is trusted. */
+export declare function startTrace(s: AppSettings<unknown>, telemetry: Telemetry, request: Request, env: unknown): RequestTrace;
+/** How a body ended: `ended` when it was read to its end (else cancelled or broken), and its bytes. */
+export type BodyEnd = (ended: boolean, bytes: number | undefined) => void;
+/** `response`, its body observed: `done` hears once how it ended, at once when it is not a stream. */
+export declare function observed(request: Request, response: Response, done: BodyEnd): Response;
+/** The answer to `seen`, observed for the request log and the root span, whichever are on. */
+export declare function observe(s: AppSettings<unknown>, seen: Seen, response: Response): Response;

package/dist/telemetry/span-lifecycle.js

@@ -0,0 +1,114 @@
+/**
+ * A request's root span from start to end (H17, F8). It starts before routing, under or linked to
+ * the inbound trace as the hop is trusted. The request is over when its answer's body ended, or
+ * was cancelled first. A
+ * buffered body, a bodiless answer, a HEAD and a 101 are over at once and handed back untouched. A
+ * streamed body is read through one pass-through that pulls only when its reader asks, so nothing
+ * is read ahead and nothing changes on the wire; it counts the bytes. Dispatch wraps the body once,
+ * for the request log and the root span together, and only when one of them is on.
+ */
+import { ipOf } from "../context/peer.js";
+import { HoneyError } from "../errors/error.js";
+import { isHoneyResponse, rawBodyOf } from "../response/builder.js";
+import { pathOf } from "./fields.js";
+import { requestLine } from "./request-log.js";
+import { NO_LINKS, RequestTrace } from "./request-trace.js";
+import { inboundTrace } from "./traceparent.js";
+const nothing = () => undefined;
+/** The root of a request whose tracer failed to start one: records nothing. */
+const UNRECORDED = /* @__PURE__ */ Object.freeze({
+    addEvent: nothing,
+    end: nothing,
+    isRecording: () => false,
+    setAttribute: nothing,
+    setStatus: nothing,
+    spanContext: () => ({ spanId: "0000000000000000", traceFlags: 0, traceId: "00000000000000000000000000000000" }),
+    updateName: nothing,
+});
+/** The root span of `request`, under or linked to its inbound trace as the hop is trusted. */
+export function startTrace(s, telemetry, request, env) {
+    const started = performance.now();
+    const peer = { env, req: request };
+    const source = {
+        get ip() {
+            return ipOf(peer);
+        },
+        req: request,
+    };
+    const inbound = inboundTrace(source, telemetry.trustInbound, (error) => s.logger.warn({ err: HoneyError.serialize(error) }, "telemetry trust check failed"));
+    const options = {
+        attributes: { "http.request.method": request.method, "url.path": pathOf(request.url) },
+        kind: "server",
+        links: inbound === null || inbound.continued ? NO_LINKS : [inbound.remote],
+        parent: inbound?.continued === true ? inbound.remote : null,
+    };
+    let root = UNRECORDED;
+    try {
+        root = telemetry.tracer.startSpan(request.method, options);
+    }
+    catch (error) {
+        s.logger.warn({ err: HoneyError.serialize(error) }, "telemetry failed");
+    }
+    const state = inbound?.continued === true ? inbound.remote.state : undefined;
+    return new RequestTrace(s, telemetry.tracer, root, { started, state });
+}
+// per-process-constant: text-codec
+const encoder = /* @__PURE__ */ new TextEncoder();
+function byteLength(raw) {
+    return typeof raw === "string" ? encoder.encode(raw).byteLength : raw.byteLength;
+}
+/** `body` read only on its reader's demand, its bytes counted; `done` hears once how it ended. */
+function counted(body, done) {
+    const reader = body.getReader();
+    let bytes = 0;
+    let settled = false;
+    const settle = (ended) => {
+        if (settled)
+            return;
+        settled = true;
+        done(ended, bytes);
+    };
+    return new ReadableStream({
+        cancel(reason) {
+            settle(false);
+            return reader.cancel(reason);
+        },
+        async pull(controller) {
+            const chunk = await reader.read().catch((error) => {
+                /* the body broke: the client got a cut stream, which the line records as aborted */
+                settle(false);
+                throw error;
+            });
+            if (chunk.done) {
+                /* before close(): a cancel racing the end has already settled it as aborted */
+                settle(true);
+                controller.close();
+                return;
+            }
+            bytes += chunk.value.byteLength;
+            controller.enqueue(chunk.value);
+        },
+    }, { highWaterMark: 0 });
+}
+/** `response`, its body observed: `done` hears once how it ended, at once when it is not a stream. */
+export function observed(request, response, done) {
+    const raw = rawBodyOf(response);
+    const body = raw === null && response.status !== 101 && request.method !== "HEAD" ? response.body : null;
+    if (body === null) {
+        done(true, raw === null || request.method === "HEAD" ? undefined : byteLength(raw));
+        return response;
+    }
+    const stream = counted(body, done);
+    if (isHoneyResponse(response))
+        return response.derive({ stream });
+    return new Response(stream, { headers: response.headers, status: response.status, statusText: response.statusText });
+}
+/** The answer to `seen`, observed for the request log and the root span, whichever are on. */
+export function observe(s, seen, response) {
+    const line = s.requestLog === null ? null : requestLine(s, seen, response);
+    const trace = seen.trace;
+    return observed(seen.request, response, (ended, bytes) => {
+        line?.(ended, bytes);
+        trace?.end(response.status, ended, bytes);
+    });
+}

package/dist/telemetry/traceparent.d.ts

@@ -0,0 +1,40 @@
+/**
+ * W3C trace context, level 1 (G1). `traceparent` parses strictly: lowercase hex, version `00` is
+ * exactly 55 chars, a later version is read by its first 55 chars when a dash or nothing follows,
+ * `ff` and all-zero ids are invalid. `tracestate` is kept only whole: every member valid, no key
+ * twice, at most 32 members and 512 chars. Whether an inbound trace is continued is the hop's trust
+ * (`InboundTrust`, b1): a trusted hop's valid trace is continued, an untrusted one's only linked, a
+ * malformed one ignored.
+ */
+import type { InboundTrust } from "../middleware/request-id.ts";
+/** A trace's ids as `traceparent` carries them. */
+export type TraceIds = {
+    readonly flags: number;
+    readonly spanId: string;
+    readonly traceId: string;
+};
+/** A span in another process: its ids and, on a continued trace, its `tracestate`. */
+export type RemoteContext = TraceIds & {
+    readonly state: string | undefined;
+};
+/** The inbound trace: continued (the remote is the root's parent) or linked; `null` when there is none. */
+export type Inbound = {
+    readonly continued: boolean;
+    readonly remote: RemoteContext;
+} | null;
+export declare function parseTraceparent(header: string | null): TraceIds | null;
+export declare function formatTraceparent(ids: TraceIds): string;
+/**
+ * The `tracestate` to carry on, normalized, or `undefined` when any of it is invalid. Deliberately
+ * stricter than OpenTelemetry, which drops bad members one by one: a failed parse must not
+ * propagate (W3C), and the trace still continues through `traceparent`.
+ */
+export declare function parseTracestate(header: string | null): string | undefined;
+/**
+ * The trace `source`'s request arrived in, as `trust` lets it count. The predicate runs only for a
+ * valid `traceparent`, and an untrusted hop's `tracestate` stays behind.
+ */
+export declare function inboundTrace(source: {
+    readonly ip: string | null;
+    readonly req: Request;
+}, trust: InboundTrust, report: (error: unknown) => void): Inbound;

package/dist/telemetry/traceparent.js

@@ -0,0 +1,73 @@
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const ZERO_TRACE = "00000000000000000000000000000000";
+const ZERO_SPAN = "0000000000000000";
+export function parseTraceparent(header) {
+    if (header === null || header.length < 55)
+        return null;
+    const version = header.slice(0, 2);
+    /* a later version may append fields after a dash; version 00 may not */
+    if (header.length > 55 && (version === "00" || header.charCodeAt(55) !== 45))
+        return null;
+    const match = TRACEPARENT.exec(header.slice(0, 55));
+    if (match === null || version === "ff")
+        return null;
+    const [, , traceId, spanId, flags] = match;
+    if (traceId === ZERO_TRACE || spanId === ZERO_SPAN)
+        return null;
+    return { flags: Number.parseInt(flags, 16), spanId, traceId };
+}
+export function formatTraceparent(ids) {
+    return `00-${ids.traceId}-${ids.spanId}-${(ids.flags & 0xff).toString(16).padStart(2, "0")}`;
+}
+/* a simple key, or a multi-tenant `tenant@system` key */
+const MEMBER_KEY = /^(?:[a-z][_0-9a-z*/-]{0,255}|[a-z0-9][_0-9a-z*/-]{0,240}@[a-z][_0-9a-z*/-]{0,13})$/;
+/* printable ASCII but `,` and `=`, not ending in a space */
+const MEMBER_VALUE = /^[\x20-\x2b\x2d-\x3c\x3e-\x7e]{0,255}[\x21-\x2b\x2d-\x3c\x3e-\x7e]$/;
+/**
+ * The `tracestate` to carry on, normalized, or `undefined` when any of it is invalid. Deliberately
+ * stricter than OpenTelemetry, which drops bad members one by one: a failed parse must not
+ * propagate (W3C), and the trace still continues through `traceparent`.
+ */
+export function parseTracestate(header) {
+    if (header === null || header.length > 512)
+        return undefined;
+    const kept = [];
+    const keys = new Set();
+    for (const raw of header.split(",")) {
+        const member = raw.trim();
+        if (member === "")
+            continue;
+        const eq = member.indexOf("=");
+        const key = member.slice(0, eq);
+        if (eq === -1 || !MEMBER_KEY.test(key) || !MEMBER_VALUE.test(member.slice(eq + 1)) || keys.has(key)) {
+            return undefined;
+        }
+        keys.add(key);
+        kept.push(member);
+    }
+    return kept.length === 0 || kept.length > 32 ? undefined : kept.join(",");
+}
+/** Does `trust` let this hop decide the trace? A predicate that throws does not: it is reported. */
+function trusted(trust, source, report) {
+    if (typeof trust !== "function")
+        return trust;
+    try {
+        return trust(source);
+    }
+    catch (error) {
+        report(error);
+        return false;
+    }
+}
+/**
+ * The trace `source`'s request arrived in, as `trust` lets it count. The predicate runs only for a
+ * valid `traceparent`, and an untrusted hop's `tracestate` stays behind.
+ */
+export function inboundTrace(source, trust, report) {
+    const ids = parseTraceparent(source.req.headers.get("traceparent"));
+    if (ids === null)
+        return null;
+    if (!trusted(trust, source, report))
+        return { continued: false, remote: { ...ids, state: undefined } };
+    return { continued: true, remote: { ...ids, state: parseTracestate(source.req.headers.get("tracestate")) } };
+}