@beignet/core/dist/server/request-context.d.ts

Core framework primitives for Beignet

import type { ActivityActor, ActivityTenant } from "../ports/audit.js";
/**
 * Ambient correlation values for the request currently being handled.
 *
 * The server enters this context before user hooks run so instrumentation
 * sinks can correlate events recorded anywhere in the request lifecycle.
 * Identity values (`actor`, `tenant`) are refreshed by the server whenever
 * hooks finalize a new context, so wrappers such as `createAmbientAuditLog`
 * observe the elevated identity at record time.
 */
export interface ActiveRequestContext {
    requestId?: string;
    traceId?: string;
    spanId?: string;
    parentSpanId?: string;
    traceparent?: string;
    tracestate?: string;
    /**
     * Actor for the current request or service execution, when known.
     */
    actor?: ActivityActor;
    /**
     * Tenant scope for the current request or service execution, when known.
     */
    tenant?: ActivityTenant;
}
/**
 * Enter the ambient request context for the current async execution.
 */
export declare function enterActiveRequestContext(context: ActiveRequestContext): void;
/**
 * Clear the ambient request context for the current async execution.
 */
export declare function clearActiveRequestContext(): void;
/**
 * Run a function inside a scoped ambient request context frame.
 *
 * Internal to the server runtime — not part of the public package surface.
 * `server.runServiceContext(...)` uses this `AsyncLocalStorage.run` form
 * instead of `enterWith` because resuming an `enterWith` frame across
 * top-level await crashes Bun 1.3.x in plain scripts.
 */
export declare function runWithActiveRequestContext<T>(context: ActiveRequestContext, fn: () => T): T;
/**
 * Read the ambient request context, when one is active.
 */
export declare function getActiveRequestContext(): ActiveRequestContext | undefined;
/**
 * Read a normalized actor from an app context object, when present.
 */
export declare function readContextActor(ctx: unknown): ActivityActor | undefined;
/**
 * Read a normalized tenant from an app context object, when present.
 */
export declare function readContextTenant(ctx: unknown): ActivityTenant | undefined;
/**
 * Update identity fields on the active ambient request context in place.
 *
 * The server calls this after hooks finalize a new request context so the
 * elevated actor/tenant become visible to ambient consumers, including async
 * frames that captured the context object before the update. No-op when no
 * ambient context is active.
 */
export declare function setActiveRequestIdentity(identity: {
    actor?: ActivityActor;
    tenant?: ActivityTenant;
}): void;
/**
 * Fill missing correlation fields on an event from the ambient request
 * context.
 */
export declare function inheritActiveRequestContext<Event extends {
    requestId?: string;
    traceId?: string;
    spanId?: string;
    parentSpanId?: string;
    traceparent?: string;
    tracestate?: string;
}>(event: Event): Event;
//# sourceMappingURL=request-context.d.ts.map