/**
 * Context Propagation for Distributed Tracing
 *
 * Implements W3C Trace Context and B3 propagation formats for
 * cross-service trace correlation in the Vorion security platform.
 *
 * Supports:
 * - W3C Trace Context (traceparent, tracestate)
 * - B3 propagation (single and multi-header)
 * - HTTP header injection/extraction
 * - gRPC metadata propagation
 *
 * @packageDocumentation
 */
import { type Context, type SpanContext } from '@opentelemetry/api';
/**
 * HTTP headers carrier type
 */
export type HttpHeaders = Record<string, string | string[] | undefined>;
/**
 * gRPC metadata carrier type
 */
export type GrpcMetadata = Map<string, string | string[]>;
/**
 * Carrier type for context propagation
 */
export type PropagationCarrier = HttpHeaders | GrpcMetadata | Record<string, string>;
/**
 * Propagation format options
 */
export type PropagationFormat = 'w3c' | 'b3' | 'b3-multi' | 'composite';
export declare function initializePropagation(format?: PropagationFormat): void;
/**
 * Extract context from HTTP headers
 *
 * @param headers - HTTP headers containing trace context
 * @param parentContext - Parent context (default: ROOT_CONTEXT)
 * @returns Extracted context
 *
 * @example
 * ```typescript
 * // In a Fastify route handler
 * const ctx = extractContextFromHeaders(request.headers);
 * await context.with(ctx, async () => {
 *   await processRequest(request);
 * });
 * ```
 */
export declare function extractContextFromHeaders(headers: HttpHeaders, parentContext?: Context): Context;
/**
 * Inject context into HTTP headers
 *
 * @param headers - Headers object to inject into
 * @param ctx - Context to inject (default: active context)
 * @returns Headers with trace context injected
 *
 * @example
 * ```typescript
 * const headers = injectContextToHeaders({
 *   'Content-Type': 'application/json',
 * });
 * await fetch(url, { headers });
 * ```
 */
export declare function injectContextToHeaders(headers?: Record<string, string>, ctx?: Context): Record<string, string>;
/**
 * Extract context from gRPC metadata
 *
 * @param metadata - gRPC metadata containing trace context
 * @param parentContext - Parent context (default: ROOT_CONTEXT)
 * @returns Extracted context
 */
export declare function extractContextFromGrpcMetadata(metadata: GrpcMetadata, parentContext?: Context): Context;
/**
 * Inject context into gRPC metadata
 *
 * @param metadata - Metadata object to inject into
 * @param ctx - Context to inject (default: active context)
 * @returns Metadata with trace context injected
 */
export declare function injectContextToGrpcMetadata(metadata?: GrpcMetadata, ctx?: Context): GrpcMetadata;
/**
 * W3C Trace Context header names
 */
export declare const W3CHeaders: {
    readonly TRACEPARENT: "traceparent";
    readonly TRACESTATE: "tracestate";
};
/**
 * B3 header names (single header format)
 */
export declare const B3SingleHeader: {
    readonly B3: "b3";
};
/**
 * B3 header names (multi-header format)
 */
export declare const B3MultiHeaders: {
    readonly TRACE_ID: "x-b3-traceid";
    readonly SPAN_ID: "x-b3-spanid";
    readonly PARENT_SPAN_ID: "x-b3-parentspanid";
    readonly SAMPLED: "x-b3-sampled";
    readonly FLAGS: "x-b3-flags";
};
/**
 * Parse W3C traceparent header
 *
 * Format: {version}-{trace-id}-{parent-id}-{trace-flags}
 * Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
 */
export declare function parseTraceparent(header: string): SpanContext | null;
/**
 * Build W3C traceparent header
 *
 * @param traceId - 32 character hex trace ID
 * @param spanId - 16 character hex span ID
 * @param sampled - Whether the trace is sampled
 * @returns Traceparent header value
 */
export declare function buildTraceparent(traceId: string, spanId: string, sampled?: boolean): string;
/**
 * Parse B3 single header
 *
 * Format: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
 * or: {TraceId}-{SpanId}-{SamplingState}
 */
export declare function parseB3SingleHeader(header: string): SpanContext | null;
/**
 * Build B3 single header
 *
 * @param traceId - Trace ID
 * @param spanId - Span ID
 * @param sampled - Whether the trace is sampled
 * @param parentSpanId - Optional parent span ID
 * @returns B3 header value
 */
export declare function buildB3SingleHeader(traceId: string, spanId: string, sampled?: boolean, parentSpanId?: string): string;
/**
 * Get trace context from active span
 *
 * @returns Trace context object or null if no active span
 */
export declare function getTraceContext(): {
    traceId: string;
    spanId: string;
    parentSpanId?: string;
    sampled: boolean;
    traceparent: string;
} | null;
/**
 * Create a context with a remote span context
 *
 * @param spanContext - Remote span context
 * @param parentContext - Parent context (default: ROOT_CONTEXT)
 * @returns Context with remote span
 */
export declare function createContextWithRemoteSpan(spanContext: SpanContext, parentContext?: Context): Context;
/**
 * Propagation context for queue jobs
 */
export interface QueuePropagationContext {
    traceparent: string;
    tracestate?: string;
    b3?: string;
}
/**
 * Extract propagation context for queue job serialization
 *
 * @returns Propagation context or null if no active span
 */
export declare function extractQueuePropagationContext(): QueuePropagationContext | null;
/**
 * Inject propagation context into queue job data
 *
 * @param data - Job data object
 * @returns Job data with propagation context
 */
export declare function injectPropagationToJobData<T extends Record<string, unknown>>(data: T): T & {
    _propagation?: QueuePropagationContext;
};
/**
 * Extract context from queue job data
 *
 * @param data - Job data object
 * @returns Context or ROOT_CONTEXT if no propagation data
 */
export declare function extractContextFromJobData(data: Record<string, unknown>): Context;
/**
 * Run a function with context from job data
 *
 * @param data - Job data containing propagation context
 * @param fn - Function to run within the context
 * @returns Result of the function
 */
export declare function runWithJobContext<T>(data: Record<string, unknown>, fn: () => Promise<T>): Promise<T>;
/**
 * HTTP client request configuration with trace context
 */
export interface TracedRequestConfig {
    url: string;
    method: string;
    headers: Record<string, string>;
}
/**
 * Add trace context to HTTP request configuration
 *
 * @param config - Request configuration
 * @returns Configuration with trace headers
 */
export declare function addTraceToRequest(config: TracedRequestConfig): TracedRequestConfig;
/**
 * Vorion-specific baggage keys for context propagation
 */
export declare const VorionBaggageKeys: {
    readonly TENANT_ID: "vorion.tenant.id";
    readonly ENTITY_ID: "vorion.entity.id";
    readonly INTENT_ID: "vorion.intent.id";
    readonly SECURITY_CONTEXT: "vorion.security.context";
    readonly REQUEST_ID: "vorion.request.id";
};
//# sourceMappingURL=propagation.d.ts.map