threadforge 0.1.1 → 0.2.1

package/src/core/RequestContext.js

@@ -1,413 +0,0 @@
-/**
- * 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');
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-import { randomBytes } from "node:crypto";
-
-const _store = new AsyncLocalStorage();
-
-let _idCounter = 0;
-
-/** P15: Pre-generate a pool of random hex IDs to reduce per-request randomBytes calls */
-const ID_POOL_SIZE = 256;
-let _idPool = [];
-let _idIndex = 0;
-
-function _refillPool() {
-  const buf = randomBytes(16 * ID_POOL_SIZE);
-  _idPool = [];
-  for (let i = 0; i < ID_POOL_SIZE; i++) {
-    _idPool.push(buf.subarray(i * 16, (i + 1) * 16).toString('hex'));
-  }
-  _idIndex = 0;
-}
-
-function nextId() {
-  if (_idIndex >= _idPool.length * 0.75) {
-    _refillPool();
-  }
-  return _idPool[_idIndex++];
-}
-
-_refillPool();
-
-/** Regex for validating trace/span/correlation IDs */
-const ID_RE = /^[a-zA-Z0-9_:.\-]{1,128}$/;
-
-export class RequestContext {
-  /**
-   * @param {Object} opts
-   * @param {string} [opts.correlationId]  - Unique ID for this entire request chain
-   * @param {string} [opts.traceId]        - Distributed trace ID (from ForgeProxy)
-   * @param {string} [opts.parentSpanId]   - Parent span for distributed tracing
-   * @param {Object} [opts.auth]           - { userId, tenantId, role }
-   * @param {string} [opts.service]        - Current service name
-   * @param {string} [opts.method]         - Method being called
-   * @param {number} [opts.deadline]       - Absolute deadline (epoch ms)
-   */
-  constructor(opts = {}) {
-    this.correlationId = opts.correlationId ?? RequestContext.generateId();
-    this.traceId = opts.traceId ?? this.correlationId;
-    this.spanId = RequestContext.generateSpanId();
-    this.parentSpanId = opts.parentSpanId ?? null;
-
-    this.auth = opts.auth ?? null;
-    this.service = opts.service ?? null;
-    this.method = opts.method ?? null;
-
-    this.startTime = performance.now();
-    this.startEpoch = Date.now();
-    this.deadline = opts.deadline ?? null;
-
-    /** @type {Map<string, string>} Arbitrary key-value pairs carried across services */
-    this.baggage = new Map(opts.baggage ?? []);
-
-    /** @type {Array<{service, method, startTime, duration, error?}>} */
-    this.spans = [];
-  }
-
-  /** Shortcut for auth fields */
-  get userId() {
-    return this.auth?.userId ?? null;
-  }
-  get tenantId() {
-    return this.auth?.tenantId ?? null;
-  }
-  get projectId() {
-    return this.auth?.projectId ?? this.auth?.project_id ?? this._projectId ?? null;
-  }
-  get role() {
-    return this.auth?.role ?? null;
-  }
-
-  /** Elapsed time since this context was created */
-  get elapsed() {
-    return performance.now() - this.startTime;
-  }
-
-  /** Remaining time before deadline */
-  get remaining() {
-    if (!this.deadline) return Infinity;
-    return Math.max(0, this.deadline - Date.now());
-  }
-
-  get isExpired() {
-    return this.remaining <= 0;
-  }
-
-  /** Add custom baggage (propagated to downstream services) */
-  addBaggage(key, value) {
-    if (!/^[a-zA-Z0-9_-]+$/.test(key)) {
-      throw new Error(`Invalid baggage key: "${key}"`);
-    }
-    if (this.baggage.size >= 32 && !this.baggage.has(key)) {
-      throw new Error('Baggage limit exceeded: max 32 entries');
-    }
-    const strValue = String(value);
-    // Check total size using byte length for proper multi-byte character handling
-    let totalSize = Buffer.byteLength(key, 'utf8') + Buffer.byteLength(strValue, 'utf8');
-    for (const [k, v] of this.baggage) {
-      if (k !== key) totalSize += Buffer.byteLength(k, 'utf8') + Buffer.byteLength(v, 'utf8');
-    }
-    if (totalSize > 4096) {
-      throw new Error('Baggage size limit exceeded: max 4KB total');
-    }
-    this.baggage.set(key, strValue);
-  }
-
-  /** Record a child span (for tracing visualization) */
-  recordSpan(service, method, duration, error = null) {
-    this.spans.push({
-      service,
-      method,
-      spanId: RequestContext.generateSpanId(),
-      parentSpanId: this.spanId,
-      startTime: Date.now() - duration,
-      duration,
-      error: error?.message ?? null,
-    });
-  }
-
-  /** Serialize for propagation over IPC/HTTP */
-  toHeaders() {
-    const headers = {
-      "x-correlation-id": this.correlationId,
-      "x-trace-id": this.traceId,
-      "x-parent-span-id": this.spanId,
-    };
-
-    if (this.auth) {
-      headers["x-forge-auth"] = JSON.stringify(this.auth);
-    }
-
-    if (this.deadline) {
-      const remaining = Math.max(0, this.deadline - Date.now());
-      headers["x-forge-deadline"] = String(remaining);
-    }
-
-    if (this.baggage.size > 0) {
-      headers["x-forge-baggage"] = JSON.stringify([...this.baggage]);
-    }
-
-    if (this.projectId) {
-      headers["x-forge-project"] = this.projectId;
-    }
-
-    return headers;
-  }
-
-  /** Serialize for IPC (colocated + cross-process) */
-  toIPC() {
-    return {
-      __forge_correlation_id: this.correlationId,
-      __forge_trace_id: this.traceId,
-      __forge_parent_span_id: this.spanId,
-      __forge_auth: this.auth,
-      __forge_deadline: this.deadline,
-      __forge_baggage: this.baggage.size > 0 ? [...this.baggage] : null,
-      __forge_project: this.projectId,
-    };
-  }
-
-  /** Sanitize an auth object — must be a plain object, strip dangerous keys */
-  static _sanitizeAuth(auth) {
-    if (auth == null || typeof auth !== "object" || Array.isArray(auth)) return null;
-    const clean = Object.create(null);
-    for (const key of Object.keys(auth)) {
-      // H-SEC-3: Block all proto pollution keys consistently with body parser
-      if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
-      clean[key] = auth[key];
-    }
-    return clean;
-  }
-
-  /** Validate an absolute deadline value — must be a finite positive epoch ms, capped at 5 min */
-  static _sanitizeDeadline(value) {
-    if (value == null) return null;
-    const num = Number(value);
-    if (!Number.isFinite(num) || num <= 0) return null;
-    const now = Date.now();
-    // Reject past deadlines
-    if (num < now) return null;
-    // Cap at 5 minutes from now
-    const maxDeadline = now + 300000;
-    if (num > maxDeadline) return maxDeadline;
-    return num;
-  }
-
-  /** Validate baggage — max 32 entries and max 4KB serialized size */
-  static _sanitizeBaggage(baggage) {
-    if (!Array.isArray(baggage)) return null;
-    if (baggage.length > 32) return null;
-    const serialized = JSON.stringify(baggage);
-    if (Buffer.byteLength(serialized, 'utf8') > 4096) return null;
-    return baggage;
-  }
-
-  /** Validate a relative deadline (remaining ms) — must be finite, non-negative, max 5 min */
-  static _sanitizeRelativeDeadline(value) {
-    if (value == null) return null;
-    const num = Number(value);
-    if (!Number.isFinite(num) || num < 0) return null;
-    // Cap at 5 minutes (300000ms) to prevent unreasonable propagated deadlines
-    if (num > 300000) return null;
-    return num;
-  }
-
-  /** Reconstruct from IPC message or HTTP headers */
-  static fromPropagation(data) {
-    // From IPC payload
-    if (data.__forge_correlation_id) {
-      const rawTraceId = data.__forge_trace_id || '';
-      const rawParentSpanId = data.__forge_parent_span_id || '';
-      const traceId = (rawTraceId && ID_RE.test(rawTraceId)) ? rawTraceId : null;
-      const parentSpanId = (rawParentSpanId && ID_RE.test(rawParentSpanId)) ? rawParentSpanId : null;
-
-      const ctx = new RequestContext({
-        correlationId: data.__forge_correlation_id,
-        traceId: traceId ?? undefined,
-        parentSpanId: parentSpanId ?? undefined,
-        auth: RequestContext._sanitizeAuth(data.__forge_auth),
-        deadline: RequestContext._sanitizeDeadline(data.__forge_deadline),
-        baggage: RequestContext._sanitizeBaggage(data.__forge_baggage),
-      });
-      const ipcProject = data.__forge_project;
-      if (typeof ipcProject === 'string' && /^[a-zA-Z0-9_-]{1,64}$/.test(ipcProject)) {
-        ctx._projectId = ipcProject;
-      }
-      return ctx;
-    }
-
-    // From HTTP headers (ForgeProxy → service)
-    let auth = null;
-    if (data["x-forge-auth"]) {
-      try {
-        auth = RequestContext._sanitizeAuth(JSON.parse(data["x-forge-auth"]));
-      } catch {
-        auth = null;
-      }
-    }
-
-    let baggage = null;
-    if (data["x-forge-baggage"]) {
-      try {
-        const parsed = JSON.parse(data["x-forge-baggage"], (key, value) => {
-          if (key === '__proto__' || key === 'constructor' || key === 'prototype') return undefined;
-          return value;
-        });
-        // M7: Validate baggage size — max 32 entries and max 4KB serialized
-        if (Array.isArray(parsed)) {
-          if (parsed.length <= 32) {
-            const serialized = JSON.stringify(parsed);
-            if (Buffer.byteLength(serialized, 'utf8') <= 4096) {
-              baggage = parsed;
-            }
-          }
-        }
-      } catch {
-        baggage = null;
-      }
-    }
-
-    // x-forge-deadline is relative (remaining ms), convert to absolute local clock
-    let deadline = null;
-    const rawDeadline = data["x-forge-deadline"];
-    if (rawDeadline != null) {
-      const remaining = RequestContext._sanitizeRelativeDeadline(Number(rawDeadline));
-      if (remaining != null) {
-        deadline = Date.now() + remaining;
-      }
-    }
-
-    const rawCorrelationId = data["x-correlation-id"] ?? data["x-request-id"];
-    const correlationId = (typeof rawCorrelationId === 'string' && /^[a-zA-Z0-9_.\-]+$/.test(rawCorrelationId) && rawCorrelationId.length <= 128) ? rawCorrelationId : null;
-
-    const rawTraceId = data["x-trace-id"] || '';
-    const rawParentSpanId = data["x-parent-span-id"] || '';
-    const traceId = (rawTraceId && ID_RE.test(rawTraceId)) ? rawTraceId : null;
-    const parentSpanId = (rawParentSpanId && ID_RE.test(rawParentSpanId)) ? rawParentSpanId : null;
-
-    const ctx = new RequestContext({
-      correlationId,
-      traceId: traceId ?? undefined,
-      parentSpanId: parentSpanId ?? undefined,
-      auth,
-      deadline,
-      baggage,
-    });
-    const rawProject = data["x-forge-project"];
-    if (typeof rawProject === 'string' && /^[a-zA-Z0-9_-]{1,64}$/.test(rawProject)) {
-      ctx._projectId = rawProject;
-    }
-    return ctx;
-  }
-
-  /** Create a child context for a downstream call */
-  child(service, method) {
-    return new RequestContext({
-      correlationId: this.correlationId,
-      traceId: this.traceId,
-      parentSpanId: this.spanId,
-      auth: this.auth,
-      deadline: this.deadline,
-      baggage: [...this.baggage],
-      service,
-      method,
-    });
-  }
-
-  // ── Static: AsyncLocalStorage management ──
-
-  /** Run a function within a request context */
-  static run(ctx, fn) {
-    return _store.run(ctx, fn);
-  }
-
-  /** Enter a request context for the current async execution context.
-   *  Unlike run(), this persists through all subsequent async work
-   *  on this execution context (including post-next() middleware). */
-  static enterWith(ctx) {
-    _store.enterWith(ctx);
-  }
-
-  /** Get the current request context (or null if none) */
-  static current() {
-    return _store.getStore() ?? null;
-  }
-
-  /** Labels for metrics (always includes tenant if available) */
-  toMetricLabels() {
-    const labels = {};
-    if (this.tenantId) labels.tenant_id = this.tenantId;
-    if (this.projectId) labels.project_id = this.projectId;
-    if (this.service) labels.service = this.service;
-    if (this.method) labels.method = this.method;
-    return labels;
-  }
-
-  /** Labels for structured logging */
-  toLogFields() {
-    const fields = { correlationId: this.correlationId };
-    if (this.tenantId) fields.tenantId = this.tenantId;
-    if (this.userId) fields.userId = this.userId;
-    if (this.traceId !== this.correlationId) fields.traceId = this.traceId;
-    return fields;
-  }
-
-  static generateId() {
-    const workerId = typeof process !== 'undefined' ? process.env?.FORGE_WORKER_ID : undefined;
-    const safeWorkerId = workerId && /^[a-zA-Z0-9_-]+$/.test(workerId) ? workerId : '0';
-    const hex = nextId();
-    return `req_${safeWorkerId}_${(++_idCounter).toString(36)}_${hex.slice(0, 8)}`;
-  }
-
-  static generateSpanId() {
-    const hex = nextId();
-    return hex.slice(0, 16);
-  }
-}