threadforge 0.1.0 → 0.2.1

package/dist/core/RequestContext.d.ts

@@ -0,0 +1,214 @@
+/**
+ * RequestContext
+ *
+ * Carries per-request state through the entire call chain using
+ * Node's AsyncLocalStorage. No manual threading needed — any
+ * async function called during request processing can access
+ * the current context.
+ *
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ HTTP request arrives at users service                      │
+ * │                                                            │
+ * │ RequestContext created:                                    │
+ * │   correlationId: "req_abc123"                              │
+ * │   traceId:       "trace_xyz789"   (from ForgeProxy)        │
+ * │   spanId:        "span_001"                                │
+ * │   auth:          { userId, tenantId, role }                │
+ * │   service:       "users"                                   │
+ * │   method:        "createUser"                              │
+ * │   startTime:     1707500000000                             │
+ * │   deadline:      1707500005000                             │
+ * │   baggage:       Map { custom key-value pairs }            │
+ * │                                                            │
+ * │ this.notifications.userCreated(user)                       │
+ * │   → Proxy reads current RequestContext                     │
+ * │   → Propagates correlationId + traceId + auth via IPC      │
+ * │   → Notifications service creates child span               │
+ * │   → Same correlationId, new spanId                         │
+ * │                                                            │
+ * │ All log lines include correlationId automatically          │
+ * │ All metrics include tenantId automatically                 │
+ * │ Prometheus histograms track per-tenant latency             │
+ * └─────────────────────────────────────────────────────────────┘
+ *
+ * Usage in service code (automatic — engineers don't touch this):
+ *
+ *   // The framework does this:
+ *   RequestContext.run(ctx, async () => {
+ *     await service.createUser(data);
+ *   });
+ *
+ *   // Any code inside that async tree can do:
+ *   const ctx = RequestContext.current();
+ *   ctx.correlationId  // always available
+ *   ctx.auth           // if authenticated
+ *   ctx.tenantId       // shortcut
+ *   ctx.addBaggage('paymentId', 'pay_123');
+ */
+interface AuthInfo {
+    userId?: string;
+    tenantId?: string;
+    projectId?: string;
+    project_id?: string;
+    role?: string;
+    [key: string]: unknown;
+}
+interface RequestContextOptions {
+    correlationId?: string | null;
+    traceId?: string;
+    parentSpanId?: string;
+    auth?: AuthInfo | null;
+    service?: string | null;
+    method?: string | null;
+    deadline?: number | null;
+    baggage?: Iterable<[string, string]> | null;
+}
+interface PropagationHeaders {
+    "x-correlation-id"?: string;
+    "x-request-id"?: string;
+    "x-trace-id"?: string;
+    "x-parent-span-id"?: string;
+    "x-forge-auth"?: string;
+    "x-forge-deadline"?: string;
+    "x-forge-baggage"?: string;
+    "x-forge-project"?: string;
+    traceparent?: string;
+    [key: string]: string | undefined;
+}
+interface IPCPropagationData {
+    __forge_correlation_id?: string;
+    __forge_trace_id?: string;
+    __forge_parent_span_id?: string;
+    __forge_auth?: unknown;
+    __forge_deadline?: unknown;
+    __forge_baggage?: unknown;
+    __forge_project?: unknown;
+    [key: string]: unknown;
+}
+type PropagationData = PropagationHeaders | IPCPropagationData;
+interface MetricLabels {
+    tenant_id?: string;
+    project_id?: string;
+    service?: string;
+    method?: string;
+}
+interface LogFields {
+    correlationId: string;
+    tenantId?: string;
+    userId?: string;
+    traceId?: string;
+}
+interface IPCPayload {
+    __forge_correlation_id: string;
+    __forge_trace_id: string;
+    __forge_parent_span_id: string;
+    __forge_auth: AuthInfo | null;
+    __forge_deadline: number | null;
+    __forge_baggage: [string, string][] | null;
+    __forge_project: string | null;
+}
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    operationName: string;
+    service: string | null;
+    startTimeUnixNano: number;
+    endTimeUnixNano: number;
+    durationMs: number;
+    status: "ok" | "error";
+    attributes: Record<string, string | number | boolean>;
+}
+export type TraceExporterFn = (spans: Span[]) => void | Promise<void>;
+/** Format spans as OTLP-compatible JSON (ResourceSpans structure) */
+export declare function formatOTLP(spans: Span[]): object;
+export declare class RequestContext {
+    correlationId: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    auth: AuthInfo | null;
+    service: string | null;
+    method: string | null;
+    startTime: number;
+    startEpoch: number;
+    deadline: number | null;
+    baggage: Map<string, string>;
+    spans: Span[];
+    _projectId?: string;
+    /** Configurable trace exporter — set via RequestContext.setTraceExporter() */
+    private static _traceExporter;
+    constructor(opts?: RequestContextOptions);
+    /** Shortcut for auth fields */
+    get userId(): string | null;
+    get tenantId(): string | null;
+    get projectId(): string | null;
+    get role(): string | null;
+    /** Elapsed time since this context was created */
+    get elapsed(): number;
+    /** Remaining time before deadline */
+    get remaining(): number;
+    get isExpired(): boolean;
+    /** Add custom baggage (propagated to downstream services) */
+    addBaggage(key: string, value: unknown): void;
+    /** Serialize for propagation over IPC/HTTP */
+    toHeaders(): Record<string, string>;
+    /** Serialize for IPC (colocated + cross-process) */
+    toIPC(): IPCPayload;
+    /** Sanitize an auth object — must be a plain object, strip dangerous keys */
+    static _sanitizeAuth(auth: unknown): AuthInfo | null;
+    /** Validate an absolute deadline value — must be a finite positive epoch ms, capped at 5 min */
+    static _sanitizeDeadline(value: unknown): number | null;
+    /** Validate baggage — max 32 entries and max 4KB serialized size */
+    static _sanitizeBaggage(baggage: unknown): [string, string][] | null;
+    /** Validate a relative deadline (remaining ms) — must be finite, non-negative, max 5 min */
+    static _sanitizeRelativeDeadline(value: unknown): number | null;
+    /** Reconstruct from IPC message or HTTP headers */
+    static fromPropagation(data: PropagationData): RequestContext;
+    /** Create a child context for a downstream call */
+    child(service: string, method: string): RequestContext;
+    /** Run a function within a request context */
+    static run<T>(ctx: RequestContext, fn: () => T): T;
+    /** Get the current request context (or null if none) */
+    static current(): RequestContext | null;
+    /** Labels for metrics (always includes tenant if available) */
+    toMetricLabels(): MetricLabels;
+    /** Labels for structured logging */
+    toLogFields(): LogFields;
+    /**
+     * Record a completed span on this request context.
+     * Spans are accumulated and flushed when end() is called or flushSpans() is invoked.
+     */
+    recordSpan(operationName: string, startTimeMs: number, endTimeMs: number, opts?: {
+        status?: "ok" | "error";
+        attributes?: Record<string, string | number | boolean>;
+        spanId?: string;
+        parentSpanId?: string | null;
+    }): Span;
+    /**
+     * Start a span and return a finish function.
+     * Usage: const finish = ctx.startSpan('doWork'); ... finish();
+     */
+    startSpan(operationName: string, attributes?: Record<string, string | number | boolean>): (status?: "ok" | "error", extraAttrs?: Record<string, string | number | boolean>) => Span;
+    /**
+     * Flush all accumulated spans to the configured trace exporter.
+     * Clears the spans array after flushing. Returns the flushed spans.
+     */
+    flushSpans(): Promise<Span[]>;
+    /**
+     * End this request context: record the root span and flush all spans.
+     * Call this when the request is complete.
+     */
+    end(status?: "ok" | "error"): Promise<Span[]>;
+    /** Set the global trace exporter function */
+    static setTraceExporter(fn: TraceExporterFn | null): void;
+    /** Get the current trace exporter */
+    static getTraceExporter(): TraceExporterFn | null;
+    /** Built-in console exporter for development */
+    static consoleExporter: TraceExporterFn;
+    static generateId(): string;
+    static generateTraceId(): string;
+    static generateSpanId(): string;
+}
+export {};
+//# sourceMappingURL=RequestContext.d.ts.map

package/dist/core/RequestContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestContext.d.ts","sourceRoot":"","sources":["../../src/core/RequestContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,UAAU,QAAQ;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,qBAAqB;IAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,UAAU,kBAAkB;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,UAAU,kBAAkB;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,KAAK,eAAe,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAE/D,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,SAAS;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC;IAC3C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAwCD,MAAM,WAAW,IAAI;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACvD;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AActE,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CA8ChD;AAED,qBAAa,cAAc;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,8EAA8E;IAC9E,OAAO,CAAC,MAAM,CAAC,cAAc,CAAgC;gBAEjD,IAAI,GAAE,qBAA0B;IAkB5C,+BAA+B;IAC/B,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAE1B;IACD,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IACD,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IACD,IAAI,IAAI,IAAI,MAAM,GAAG,IAAI,CAExB;IAED,kDAAkD;IAClD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,qCAAqC;IACrC,IAAI,SAAS,IAAI,MAAM,CAGtB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,6DAA6D;IAC7D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAmB7C,8CAA8C;IAC9C,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAgCnC,oDAAoD;IACpD,KAAK,IAAI,UAAU;IAYnB,6EAA6E;IAC7E,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI;IAWpD,gGAAgG;IAChG,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAavD,oEAAoE;IACpE,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,IAAI;IAQpE,4FAA4F;IAC5F,MAAM,CAAC,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAS/D,mDAAmD;IACnD,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc;IAoH7D,mDAAmD;IACnD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc;IAetD,8CAA8C;IAC9C,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIlD,wDAAwD;IACxD,MAAM,CAAC,OAAO,IAAI,cAAc,GAAG,IAAI;IAIvC,+DAA+D;IAC/D,cAAc,IAAI,YAAY;IAS9B,oCAAoC;IACpC,WAAW,IAAI,SAAS;IAUxB;;;OAGG;IACH,UAAU,CACR,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAO,GAC5I,IAAI;IAmBP;;;OAGG;IACH,SAAS,CACP,aAAa,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI;IAU5F;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAcnC;;;OAGG;IACG,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAmBnD,6CAA6C;IAC7C,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI;IAIzD,qCAAqC;IACrC,MAAM,CAAC,gBAAgB,IAAI,eAAe,GAAG,IAAI;IAIjD,gDAAgD;IAChD,MAAM,CAAC,eAAe,EAAE,eAAe,CAAoB;IAE3D,MAAM,CAAC,UAAU,IAAI,MAAM;IAO3B,MAAM,CAAC,eAAe,IAAI,MAAM;IAIhC,MAAM,CAAC,cAAc,IAAI,MAAM;CAIhC"}