@beignet/core/dist/server/instrumentation.d.ts

Core framework primitives for Beignet

import { type HttpContractConfig } from "../contracts/index.js";
import type { AnyPorts } from "../ports/index.js";
import { type ProviderInstrumentationEventInput } from "../providers/instrumentation.js";
import { type TraceContext } from "../tracing/index.js";
import type { HttpRequestLike, HttpResponseLike, ServerHook } from "./http.js";
/**
 * Options for the server-owned request instrumentation pipeline.
 *
 * The server resolves request IDs and W3C trace context before user hooks and
 * context creation run, writes them to response headers, and records request
 * and error events into the resolved provider instrumentation port
 * (`ports.instrumentation`, then `ports.devtools`) after responses are sent.
 *
 * Pass `instrumentation: false` to `createServer(...)` to disable headers and
 * event recording entirely.
 */
export interface ServerInstrumentationOptions<Ctx = unknown> {
    /**
     * Request/response header used for the request correlation ID.
     *
     * Pass `false` to avoid reading or writing a request ID header.
     *
     * @default "x-request-id"
     */
    requestIdHeader?: string | false;
    /**
     * W3C trace context header used to correlate events with distributed
     * traces.
     *
     * Pass `false` to avoid reading or writing a trace context header.
     *
     * @default "traceparent"
     */
    traceContextHeader?: string | false;
    /**
     * Request path prefixes that should not record instrumentation events.
     * Ambient correlation still runs, and enabled response headers are written.
     *
     * Defaults to the devtools dashboard prefix so its polling traffic does not
     * fill the event timeline.
     *
     * @default ["/api/devtools"]
     */
    ignorePaths?: readonly string[];
    /**
     * Apply a custom redactor to events produced by the server. Sink-level
     * redaction (such as the devtools redactor) still runs when events are
     * stored.
     */
    redact?: (event: ProviderInstrumentationEventInput) => ProviderInstrumentationEventInput;
    /**
     * Decide whether to capture a completed request event.
     */
    shouldCapture?: (args: {
        req: HttpRequestLike;
        ctx?: Ctx;
        contract: HttpContractConfig;
        response: HttpResponseLike;
        error?: unknown;
    }) => boolean;
}
/**
 * Correlation values resolved by the server for one request or service
 * context.
 */
export interface RequestCorrelation {
    /**
     * Request correlation ID.
     */
    requestId: string;
    /**
     * W3C trace context.
     */
    trace: TraceContext;
}
/**
 * Internal runtime created by `createServer(...)` from its `instrumentation`
 * option.
 */
export interface ServerInstrumentationRuntime<Ctx> {
    /**
     * Resolve the instrumentation sink once final ports are known.
     */
    attachPorts(ports: AnyPorts): void;
    /**
     * Resolve (and cache per request) the request ID and trace context.
     */
    prepareRequest(req: HttpRequestLike): RequestCorrelation;
    /**
     * Create fresh correlation values for a service context.
     */
    createServiceCorrelation(): RequestCorrelation;
    /**
     * Pipeline hook installed before user hooks. It always owns ambient
     * correlation; response headers and event recording remain configurable.
     */
    hook: ServerHook<Ctx, AnyPorts>;
}
/**
 * Create the server-owned instrumentation runtime for `createServer(...)`.
 *
 * Correlation values (request ID and trace context) are always resolved so
 * context factories receive stable `requestId`/`trace` arguments, even when
 * instrumentation is disabled. Headers and event recording only run when
 * instrumentation is enabled.
 */
export declare function createServerInstrumentation<Ctx>(options: ServerInstrumentationOptions<Ctx> | false | undefined): ServerInstrumentationRuntime<Ctx>;
//# sourceMappingURL=instrumentation.d.ts.map