@vivero/stoma 0.1.0-rc.10

package/dist/observability/metrics.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Pluggable metrics collection for the gateway pipeline.
+ *
+ * Defines the {@link MetricsCollector} interface and provides an
+ * {@link InMemoryMetricsCollector} for testing and development.
+ * The {@link toPrometheusText} function serializes a snapshot to
+ * Prometheus text exposition format.
+ *
+ * @module metrics
+ */
+/** A single tagged metric data point. */
+interface TaggedValue {
+    value: number;
+    tags?: Record<string, string>;
+}
+/** A histogram data point with accumulated values. */
+interface HistogramEntry {
+    values: number[];
+    tags?: Record<string, string>;
+}
+/** Point-in-time snapshot of all collected metrics. */
+interface MetricsSnapshot {
+    counters: Record<string, TaggedValue[]>;
+    histograms: Record<string, HistogramEntry[]>;
+    gauges: Record<string, TaggedValue[]>;
+}
+/**
+ * Pluggable metrics collector interface.
+ *
+ * Implementations can ship metrics to Prometheus, Datadog, CloudWatch,
+ * or any other backend. The gateway pipeline records request counts,
+ * latencies, and error rates through this interface.
+ */
+interface MetricsCollector {
+    /** Increment a counter by `value` (default 1). */
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    /** Record a histogram observation. */
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+    /** Set a gauge to an absolute value. */
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    /** Return a point-in-time snapshot of all metrics. */
+    snapshot(): MetricsSnapshot;
+    /** Reset all metrics to zero. */
+    reset(): void;
+}
+/**
+ * In-memory metrics collector for testing, development, and admin API.
+ *
+ * Accumulates counters, histograms, and gauges in plain arrays/maps.
+ * Not intended for high-throughput production use - prefer shipping
+ * metrics to a dedicated backend for production workloads.
+ */
+declare class InMemoryMetricsCollector implements MetricsCollector {
+    private counters;
+    private histograms;
+    private gauges;
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    snapshot(): MetricsSnapshot;
+    reset(): void;
+}
+/**
+ * Serialize a metrics snapshot to Prometheus text exposition format.
+ *
+ * Produces lines like:
+ * ```
+ * gateway_requests_total{method="GET",status="200"} 42
+ * gateway_request_duration_ms_sum{method="GET"} 1234
+ * gateway_request_duration_ms_count{method="GET"} 10
+ * ```
+ *
+ * @param snapshot - The metrics snapshot to serialize.
+ * @returns Prometheus text exposition format string.
+ */
+declare function toPrometheusText(snapshot: MetricsSnapshot): string;
+
+export { type HistogramEntry, InMemoryMetricsCollector, type MetricsCollector, type MetricsSnapshot, type TaggedValue, toPrometheusText };

package/dist/observability/metrics.js

@@ -0,0 +1,107 @@
+function tagKey(tags) {
+  if (!tags || Object.keys(tags).length === 0) return "";
+  return Object.entries(tags).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${v}`).join(",");
+}
+class InMemoryMetricsCollector {
+  counters = /* @__PURE__ */ new Map();
+  histograms = /* @__PURE__ */ new Map();
+  gauges = /* @__PURE__ */ new Map();
+  increment(name, value = 1, tags) {
+    const key = tagKey(tags);
+    let metricMap = this.counters.get(name);
+    if (!metricMap) {
+      metricMap = /* @__PURE__ */ new Map();
+      this.counters.set(name, metricMap);
+    }
+    const existing = metricMap.get(key);
+    if (existing) {
+      existing.value += value;
+    } else {
+      metricMap.set(key, { value, tags });
+    }
+  }
+  histogram(name, value, tags) {
+    const key = tagKey(tags);
+    let metricMap = this.histograms.get(name);
+    if (!metricMap) {
+      metricMap = /* @__PURE__ */ new Map();
+      this.histograms.set(name, metricMap);
+    }
+    const existing = metricMap.get(key);
+    if (existing) {
+      existing.values.push(value);
+    } else {
+      metricMap.set(key, { values: [value], tags });
+    }
+  }
+  gauge(name, value, tags) {
+    const key = tagKey(tags);
+    let metricMap = this.gauges.get(name);
+    if (!metricMap) {
+      metricMap = /* @__PURE__ */ new Map();
+      this.gauges.set(name, metricMap);
+    }
+    metricMap.set(key, { value, tags });
+  }
+  snapshot() {
+    const snap = {
+      counters: {},
+      histograms: {},
+      gauges: {}
+    };
+    for (const [name, metricMap] of this.counters) {
+      snap.counters[name] = Array.from(metricMap.values());
+    }
+    for (const [name, metricMap] of this.histograms) {
+      snap.histograms[name] = Array.from(metricMap.values());
+    }
+    for (const [name, metricMap] of this.gauges) {
+      snap.gauges[name] = Array.from(metricMap.values());
+    }
+    return snap;
+  }
+  reset() {
+    this.counters.clear();
+    this.histograms.clear();
+    this.gauges.clear();
+  }
+}
+function toPrometheusText(snapshot) {
+  const lines = [];
+  for (const [name, entries] of Object.entries(snapshot.counters)) {
+    lines.push(`# TYPE ${name} counter`);
+    for (const entry of entries) {
+      lines.push(`${name}${formatLabels(entry.tags)} ${entry.value}`);
+    }
+  }
+  for (const [name, entries] of Object.entries(snapshot.histograms)) {
+    lines.push(`# TYPE ${name} histogram`);
+    for (const entry of entries) {
+      const labels = formatLabels(entry.tags);
+      const sum = entry.values.reduce((a, b) => a + b, 0);
+      const count = entry.values.length;
+      lines.push(`${name}_sum${labels} ${sum}`);
+      lines.push(`${name}_count${labels} ${count}`);
+    }
+  }
+  for (const [name, entries] of Object.entries(snapshot.gauges)) {
+    lines.push(`# TYPE ${name} gauge`);
+    for (const entry of entries) {
+      lines.push(`${name}${formatLabels(entry.tags)} ${entry.value}`);
+    }
+  }
+  return lines.join("\n");
+}
+function escapeLabelValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function formatLabels(tags) {
+  if (!tags || Object.keys(tags).length === 0) return "";
+  const parts = Object.entries(tags).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}="${escapeLabelValue(v)}"`);
+  return `{${parts.join(",")}}`;
+}
+export {
+  InMemoryMetricsCollector,
+  toPrometheusText
+};
+//# sourceMappingURL=metrics.js.map

package/dist/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/observability/metrics.ts"],"sourcesContent":["/**\n * Pluggable metrics collection for the gateway pipeline.\n *\n * Defines the {@link MetricsCollector} interface and provides an\n * {@link InMemoryMetricsCollector} for testing and development.\n * The {@link toPrometheusText} function serializes a snapshot to\n * Prometheus text exposition format.\n *\n * @module metrics\n */\n\n/** A single tagged metric data point. */\nexport interface TaggedValue {\n  value: number;\n  tags?: Record<string, string>;\n}\n\n/** A histogram data point with accumulated values. */\nexport interface HistogramEntry {\n  values: number[];\n  tags?: Record<string, string>;\n}\n\n/** Point-in-time snapshot of all collected metrics. */\nexport interface MetricsSnapshot {\n  counters: Record<string, TaggedValue[]>;\n  histograms: Record<string, HistogramEntry[]>;\n  gauges: Record<string, TaggedValue[]>;\n}\n\n/**\n * Pluggable metrics collector interface.\n *\n * Implementations can ship metrics to Prometheus, Datadog, CloudWatch,\n * or any other backend. The gateway pipeline records request counts,\n * latencies, and error rates through this interface.\n */\nexport interface MetricsCollector {\n  /** Increment a counter by `value` (default 1). */\n  increment(name: string, value?: number, tags?: Record<string, string>): void;\n  /** Record a histogram observation. */\n  histogram(name: string, value: number, tags?: Record<string, string>): void;\n  /** Set a gauge to an absolute value. */\n  gauge(name: string, value: number, tags?: Record<string, string>): void;\n  /** Return a point-in-time snapshot of all metrics. */\n  snapshot(): MetricsSnapshot;\n  /** Reset all metrics to zero. */\n  reset(): void;\n}\n\n/**\n * Serialize a tag map to a stable sorted key for deduplication.\n * Tags are sorted alphabetically to ensure consistent keys.\n */\nfunction tagKey(tags?: Record<string, string>): string {\n  if (!tags || Object.keys(tags).length === 0) return \"\";\n  return Object.entries(tags)\n    .sort(([a], [b]) => a.localeCompare(b))\n    .map(([k, v]) => `${k}=${v}`)\n    .join(\",\");\n}\n\n/**\n * In-memory metrics collector for testing, development, and admin API.\n *\n * Accumulates counters, histograms, and gauges in plain arrays/maps.\n * Not intended for high-throughput production use - prefer shipping\n * metrics to a dedicated backend for production workloads.\n */\nexport class InMemoryMetricsCollector implements MetricsCollector {\n  private counters = new Map<string, Map<string, TaggedValue>>();\n  private histograms = new Map<string, Map<string, HistogramEntry>>();\n  private gauges = new Map<string, Map<string, TaggedValue>>();\n\n  increment(name: string, value = 1, tags?: Record<string, string>): void {\n    const key = tagKey(tags);\n    let metricMap = this.counters.get(name);\n    if (!metricMap) {\n      metricMap = new Map();\n      this.counters.set(name, metricMap);\n    }\n    const existing = metricMap.get(key);\n    if (existing) {\n      existing.value += value;\n    } else {\n      metricMap.set(key, { value, tags });\n    }\n  }\n\n  histogram(name: string, value: number, tags?: Record<string, string>): void {\n    const key = tagKey(tags);\n    let metricMap = this.histograms.get(name);\n    if (!metricMap) {\n      metricMap = new Map();\n      this.histograms.set(name, metricMap);\n    }\n    const existing = metricMap.get(key);\n    if (existing) {\n      existing.values.push(value);\n    } else {\n      metricMap.set(key, { values: [value], tags });\n    }\n  }\n\n  gauge(name: string, value: number, tags?: Record<string, string>): void {\n    const key = tagKey(tags);\n    let metricMap = this.gauges.get(name);\n    if (!metricMap) {\n      metricMap = new Map();\n      this.gauges.set(name, metricMap);\n    }\n    metricMap.set(key, { value, tags });\n  }\n\n  snapshot(): MetricsSnapshot {\n    const snap: MetricsSnapshot = {\n      counters: {},\n      histograms: {},\n      gauges: {},\n    };\n\n    for (const [name, metricMap] of this.counters) {\n      snap.counters[name] = Array.from(metricMap.values());\n    }\n    for (const [name, metricMap] of this.histograms) {\n      snap.histograms[name] = Array.from(metricMap.values());\n    }\n    for (const [name, metricMap] of this.gauges) {\n      snap.gauges[name] = Array.from(metricMap.values());\n    }\n\n    return snap;\n  }\n\n  reset(): void {\n    this.counters.clear();\n    this.histograms.clear();\n    this.gauges.clear();\n  }\n}\n\n/**\n * Serialize a metrics snapshot to Prometheus text exposition format.\n *\n * Produces lines like:\n * ```\n * gateway_requests_total{method=\"GET\",status=\"200\"} 42\n * gateway_request_duration_ms_sum{method=\"GET\"} 1234\n * gateway_request_duration_ms_count{method=\"GET\"} 10\n * ```\n *\n * @param snapshot - The metrics snapshot to serialize.\n * @returns Prometheus text exposition format string.\n */\nexport function toPrometheusText(snapshot: MetricsSnapshot): string {\n  const lines: string[] = [];\n\n  // Counters\n  for (const [name, entries] of Object.entries(snapshot.counters)) {\n    lines.push(`# TYPE ${name} counter`);\n    for (const entry of entries) {\n      lines.push(`${name}${formatLabels(entry.tags)} ${entry.value}`);\n    }\n  }\n\n  // Histograms - emit sum and count\n  for (const [name, entries] of Object.entries(snapshot.histograms)) {\n    lines.push(`# TYPE ${name} histogram`);\n    for (const entry of entries) {\n      const labels = formatLabels(entry.tags);\n      const sum = entry.values.reduce((a, b) => a + b, 0);\n      const count = entry.values.length;\n      lines.push(`${name}_sum${labels} ${sum}`);\n      lines.push(`${name}_count${labels} ${count}`);\n    }\n  }\n\n  // Gauges\n  for (const [name, entries] of Object.entries(snapshot.gauges)) {\n    lines.push(`# TYPE ${name} gauge`);\n    for (const entry of entries) {\n      lines.push(`${name}${formatLabels(entry.tags)} ${entry.value}`);\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n\n/** Escape a label value per Prometheus exposition format spec. */\nfunction escapeLabelValue(value: string): string {\n  return value\n    .replace(/\\\\/g, \"\\\\\\\\\")\n    .replace(/\"/g, '\\\\\"')\n    .replace(/\\n/g, \"\\\\n\");\n}\n\nfunction formatLabels(tags?: Record<string, string>): string {\n  if (!tags || Object.keys(tags).length === 0) return \"\";\n  const parts = Object.entries(tags)\n    .sort(([a], [b]) => a.localeCompare(b))\n    .map(([k, v]) => `${k}=\"${escapeLabelValue(v)}\"`);\n  return `{${parts.join(\",\")}}`;\n}\n"],"mappings":"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","names":[]}

package/dist/observability/tracing.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Lightweight OpenTelemetry-compatible tracing for edge runtimes.
+ *
+ * Provides span creation, OTLP/HTTP JSON export via `fetch()`, and
+ * head-based sampling - all without any runtime dependencies beyond
+ * the Web Platform APIs available in Cloudflare Workers.
+ *
+ * Follows the OTel data model but uses own lightweight types to avoid
+ * pulling in `@opentelemetry/api` (which is not edge-compatible).
+ *
+ * @module tracing
+ */
+type SpanKind = "SERVER" | "CLIENT" | "INTERNAL";
+type SpanStatusCode = "UNSET" | "OK" | "ERROR";
+/** An immutable representation of a completed span. */
+interface ReadableSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    startTimeMs: number;
+    endTimeMs: number;
+    attributes: Record<string, string | number | boolean>;
+    status: {
+        code: SpanStatusCode;
+        message?: string;
+    };
+    events: SpanEvent[];
+}
+/** A timestamped event recorded during a span's lifetime. */
+interface SpanEvent {
+    name: string;
+    timeMs: number;
+    attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Pluggable span exporter interface.
+ *
+ * Implementations ship completed spans to a backend (OTLP collector,
+ * console, or any custom destination). Export is expected to be called
+ * via `waitUntil()` so it does not block the response.
+ */
+interface SpanExporter {
+    export(spans: ReadableSpan[]): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+/** Configuration for gateway-level tracing. */
+interface TracingConfig {
+    exporter: SpanExporter;
+    serviceName?: string;
+    serviceVersion?: string;
+    /** Head-based sampling rate [0.0, 1.0]. Default: 1.0 */
+    sampleRate?: number;
+}
+/**
+ * OTel semantic convention attribute keys (HTTP subset).
+ *
+ * Uses the stable HTTP semconv names from the OpenTelemetry specification.
+ * @see https://opentelemetry.io/docs/specs/semconv/http/
+ */
+declare const SemConv: {
+    readonly HTTP_METHOD: "http.request.method";
+    readonly HTTP_ROUTE: "http.route";
+    readonly HTTP_STATUS_CODE: "http.response.status_code";
+    readonly URL_PATH: "url.path";
+    readonly SERVER_ADDRESS: "server.address";
+};
+/**
+ * Mutable span builder - accumulates attributes, events, and status
+ * during a request lifecycle. Call {@link end} to produce an immutable
+ * {@link ReadableSpan}.
+ */
+declare class SpanBuilder {
+    readonly name: string;
+    readonly kind: SpanKind;
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string | undefined;
+    readonly startTimeMs: number;
+    private _attributes;
+    private _events;
+    private _status;
+    private _endTimeMs?;
+    constructor(name: string, kind: SpanKind, traceId: string, spanId: string, parentSpanId?: string | undefined, startTimeMs?: number);
+    /** Set a single attribute. Chainable. */
+    setAttribute(key: string, value: string | number | boolean): this;
+    /** Record a timestamped event with optional attributes. Chainable. */
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;
+    /** Set the span status. Chainable. */
+    setStatus(code: SpanStatusCode, message?: string): this;
+    /**
+     * Finalize the span and return an immutable {@link ReadableSpan}.
+     *
+     * Sets `endTimeMs` on first call; subsequent calls return the same
+     * snapshot with defensive copies of mutable fields.
+     */
+    end(): ReadableSpan;
+}
+/**
+ * OTLP/HTTP JSON span exporter.
+ *
+ * Ships spans to an OpenTelemetry Collector (or compatible endpoint)
+ * using `fetch()` with the OTLP JSON encoding. Designed for edge
+ * runtimes - no gRPC, no protobuf, no Node.js dependencies.
+ *
+ * Export calls should be dispatched via `waitUntil()` so they do not
+ * block the response path.
+ */
+declare class OTLPSpanExporter implements SpanExporter {
+    private readonly endpoint;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly serviceName;
+    private readonly serviceVersion?;
+    constructor(config: {
+        endpoint: string;
+        headers?: Record<string, string>;
+        timeoutMs?: number;
+        serviceName?: string;
+        serviceVersion?: string;
+    });
+    export(spans: ReadableSpan[]): Promise<void>;
+}
+/**
+ * Console span exporter for development and debugging.
+ *
+ * Logs each span to `console.debug()` with a compact one-line format
+ * showing name, kind, duration, trace/span IDs, and status.
+ */
+declare class ConsoleSpanExporter implements SpanExporter {
+    export(spans: ReadableSpan[]): Promise<void>;
+}
+/**
+ * Determine whether a request should be sampled based on the configured rate.
+ *
+ * @param sampleRate - Sampling probability in [0.0, 1.0].
+ * @returns `true` if the request should be traced.
+ */
+declare function shouldSample(sampleRate: number): boolean;
+/**
+ * Generate a 16-character lowercase hex span ID (8 random bytes).
+ *
+ * Uses `crypto.getRandomValues()` which is available in all edge runtimes
+ * (Cloudflare Workers, Deno, Bun, Node 19+).
+ */
+declare function generateOtelSpanId(): string;
+
+export { ConsoleSpanExporter, OTLPSpanExporter, type ReadableSpan, SemConv, SpanBuilder, type SpanEvent, type SpanExporter, type SpanKind, type SpanStatusCode, type TracingConfig, generateOtelSpanId, shouldSample };

package/dist/observability/tracing.js

@@ -0,0 +1,191 @@
+const SemConv = {
+  HTTP_METHOD: "http.request.method",
+  HTTP_ROUTE: "http.route",
+  HTTP_STATUS_CODE: "http.response.status_code",
+  URL_PATH: "url.path",
+  SERVER_ADDRESS: "server.address"
+};
+class SpanBuilder {
+  constructor(name, kind, traceId, spanId, parentSpanId, startTimeMs = Date.now()) {
+    this.name = name;
+    this.kind = kind;
+    this.traceId = traceId;
+    this.spanId = spanId;
+    this.parentSpanId = parentSpanId;
+    this.startTimeMs = startTimeMs;
+  }
+  _attributes = {};
+  _events = [];
+  _status = {
+    code: "UNSET"
+  };
+  _endTimeMs;
+  /** Set a single attribute. Chainable. */
+  setAttribute(key, value) {
+    this._attributes[key] = value;
+    return this;
+  }
+  /** Record a timestamped event with optional attributes. Chainable. */
+  addEvent(name, attributes) {
+    this._events.push({ name, timeMs: Date.now(), attributes });
+    return this;
+  }
+  /** Set the span status. Chainable. */
+  setStatus(code, message) {
+    this._status = { code, message };
+    return this;
+  }
+  /**
+   * Finalize the span and return an immutable {@link ReadableSpan}.
+   *
+   * Sets `endTimeMs` on first call; subsequent calls return the same
+   * snapshot with defensive copies of mutable fields.
+   */
+  end() {
+    this._endTimeMs = this._endTimeMs ?? Date.now();
+    return {
+      traceId: this.traceId,
+      spanId: this.spanId,
+      parentSpanId: this.parentSpanId,
+      name: this.name,
+      kind: this.kind,
+      startTimeMs: this.startTimeMs,
+      endTimeMs: this._endTimeMs,
+      attributes: { ...this._attributes },
+      status: { ...this._status },
+      events: [...this._events]
+    };
+  }
+}
+const SPAN_KIND_MAP = {
+  INTERNAL: 1,
+  // SPAN_KIND_INTERNAL
+  SERVER: 2,
+  // SPAN_KIND_SERVER
+  CLIENT: 3
+  // SPAN_KIND_CLIENT
+};
+const STATUS_CODE_MAP = {
+  UNSET: 0,
+  // STATUS_CODE_UNSET
+  OK: 1,
+  // STATUS_CODE_OK
+  ERROR: 2
+  // STATUS_CODE_ERROR
+};
+function toOtlpAttributeValue(value) {
+  if (typeof value === "string") return { stringValue: value };
+  if (typeof value === "boolean") return { boolValue: value };
+  if (Number.isInteger(value)) return { intValue: value };
+  return { doubleValue: value };
+}
+function toOtlpAttributes(attrs) {
+  return Object.entries(attrs).map(([key, value]) => ({
+    key,
+    value: toOtlpAttributeValue(value)
+  }));
+}
+function msToNanos(ms) {
+  return String(ms * 1e6);
+}
+function toOtlpPayload(spans, serviceName, serviceVersion) {
+  const resourceAttributes = [{ key: "service.name", value: { stringValue: serviceName } }];
+  if (serviceVersion) {
+    resourceAttributes.push({
+      key: "service.version",
+      value: { stringValue: serviceVersion }
+    });
+  }
+  const otlpSpans = spans.map((span) => {
+    const otlpSpan = {
+      traceId: span.traceId,
+      spanId: span.spanId,
+      name: span.name,
+      kind: SPAN_KIND_MAP[span.kind],
+      startTimeUnixNano: msToNanos(span.startTimeMs),
+      endTimeUnixNano: msToNanos(span.endTimeMs),
+      attributes: toOtlpAttributes(span.attributes),
+      status: {
+        code: STATUS_CODE_MAP[span.status.code],
+        ...span.status.message ? { message: span.status.message } : {}
+      },
+      events: span.events.map((event) => ({
+        name: event.name,
+        timeUnixNano: msToNanos(event.timeMs),
+        ...event.attributes ? { attributes: toOtlpAttributes(event.attributes) } : {}
+      }))
+    };
+    if (span.parentSpanId) {
+      otlpSpan.parentSpanId = span.parentSpanId;
+    }
+    return otlpSpan;
+  });
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: resourceAttributes },
+        scopeSpans: [
+          {
+            scope: { name: "stoma-gateway" },
+            spans: otlpSpans
+          }
+        ]
+      }
+    ]
+  };
+}
+class OTLPSpanExporter {
+  endpoint;
+  headers;
+  timeoutMs;
+  serviceName;
+  serviceVersion;
+  constructor(config) {
+    this.endpoint = config.endpoint;
+    this.headers = config.headers ?? {};
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+    this.serviceName = config.serviceName ?? "stoma-gateway";
+    this.serviceVersion = config.serviceVersion;
+  }
+  async export(spans) {
+    if (spans.length === 0) return;
+    const payload = toOtlpPayload(spans, this.serviceName, this.serviceVersion);
+    await fetch(this.endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...this.headers
+      },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+  }
+}
+class ConsoleSpanExporter {
+  async export(spans) {
+    for (const span of spans) {
+      console.debug(
+        `[trace] ${span.name} ${span.kind} ${span.endTimeMs - span.startTimeMs}ms trace=${span.traceId} span=${span.spanId}` + (span.parentSpanId ? ` parent=${span.parentSpanId}` : "") + ` status=${span.status.code}`
+      );
+    }
+  }
+}
+function shouldSample(sampleRate) {
+  if (sampleRate >= 1) return true;
+  if (sampleRate <= 0) return false;
+  return Math.random() < sampleRate;
+}
+function generateOtelSpanId() {
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+export {
+  ConsoleSpanExporter,
+  OTLPSpanExporter,
+  SemConv,
+  SpanBuilder,
+  generateOtelSpanId,
+  shouldSample
+};
+//# sourceMappingURL=tracing.js.map

package/dist/observability/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/observability/tracing.ts"],"sourcesContent":["/**\n * Lightweight OpenTelemetry-compatible tracing for edge runtimes.\n *\n * Provides span creation, OTLP/HTTP JSON export via `fetch()`, and\n * head-based sampling - all without any runtime dependencies beyond\n * the Web Platform APIs available in Cloudflare Workers.\n *\n * Follows the OTel data model but uses own lightweight types to avoid\n * pulling in `@opentelemetry/api` (which is not edge-compatible).\n *\n * @module tracing\n */\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type SpanKind = \"SERVER\" | \"CLIENT\" | \"INTERNAL\";\nexport type SpanStatusCode = \"UNSET\" | \"OK\" | \"ERROR\";\n\n/** An immutable representation of a completed span. */\nexport interface ReadableSpan {\n  traceId: string;\n  spanId: string;\n  parentSpanId?: string;\n  name: string;\n  kind: SpanKind;\n  startTimeMs: number;\n  endTimeMs: number;\n  attributes: Record<string, string | number | boolean>;\n  status: { code: SpanStatusCode; message?: string };\n  events: SpanEvent[];\n}\n\n/** A timestamped event recorded during a span's lifetime. */\nexport interface SpanEvent {\n  name: string;\n  timeMs: number;\n  attributes?: Record<string, string | number | boolean>;\n}\n\n/**\n * Pluggable span exporter interface.\n *\n * Implementations ship completed spans to a backend (OTLP collector,\n * console, or any custom destination). Export is expected to be called\n * via `waitUntil()` so it does not block the response.\n */\nexport interface SpanExporter {\n  export(spans: ReadableSpan[]): Promise<void>;\n  shutdown?(): Promise<void>;\n}\n\n/** Configuration for gateway-level tracing. */\nexport interface TracingConfig {\n  exporter: SpanExporter;\n  serviceName?: string;\n  serviceVersion?: string;\n  /** Head-based sampling rate [0.0, 1.0]. Default: 1.0 */\n  sampleRate?: number;\n}\n\n// ---------------------------------------------------------------------------\n// Semantic Conventions (HTTP subset)\n// ---------------------------------------------------------------------------\n\n/**\n * OTel semantic convention attribute keys (HTTP subset).\n *\n * Uses the stable HTTP semconv names from the OpenTelemetry specification.\n * @see https://opentelemetry.io/docs/specs/semconv/http/\n */\nexport const SemConv = {\n  HTTP_METHOD: \"http.request.method\",\n  HTTP_ROUTE: \"http.route\",\n  HTTP_STATUS_CODE: \"http.response.status_code\",\n  URL_PATH: \"url.path\",\n  SERVER_ADDRESS: \"server.address\",\n} as const;\n\n// ---------------------------------------------------------------------------\n// SpanBuilder\n// ---------------------------------------------------------------------------\n\n/**\n * Mutable span builder - accumulates attributes, events, and status\n * during a request lifecycle. Call {@link end} to produce an immutable\n * {@link ReadableSpan}.\n */\nexport class SpanBuilder {\n  private _attributes: Record<string, string | number | boolean> = {};\n  private _events: SpanEvent[] = [];\n  private _status: { code: SpanStatusCode; message?: string } = {\n    code: \"UNSET\",\n  };\n  private _endTimeMs?: number;\n\n  constructor(\n    public readonly name: string,\n    public readonly kind: SpanKind,\n    public readonly traceId: string,\n    public readonly spanId: string,\n    public readonly parentSpanId?: string,\n    public readonly startTimeMs: number = Date.now()\n  ) {}\n\n  /** Set a single attribute. Chainable. */\n  setAttribute(key: string, value: string | number | boolean): this {\n    this._attributes[key] = value;\n    return this;\n  }\n\n  /** Record a timestamped event with optional attributes. Chainable. */\n  addEvent(\n    name: string,\n    attributes?: Record<string, string | number | boolean>\n  ): this {\n    this._events.push({ name, timeMs: Date.now(), attributes });\n    return this;\n  }\n\n  /** Set the span status. Chainable. */\n  setStatus(code: SpanStatusCode, message?: string): this {\n    this._status = { code, message };\n    return this;\n  }\n\n  /**\n   * Finalize the span and return an immutable {@link ReadableSpan}.\n   *\n   * Sets `endTimeMs` on first call; subsequent calls return the same\n   * snapshot with defensive copies of mutable fields.\n   */\n  end(): ReadableSpan {\n    this._endTimeMs = this._endTimeMs ?? Date.now();\n    return {\n      traceId: this.traceId,\n      spanId: this.spanId,\n      parentSpanId: this.parentSpanId,\n      name: this.name,\n      kind: this.kind,\n      startTimeMs: this.startTimeMs,\n      endTimeMs: this._endTimeMs,\n      attributes: { ...this._attributes },\n      status: { ...this._status },\n      events: [...this._events],\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------\n// OTLP JSON helpers\n// ---------------------------------------------------------------------------\n\n/** Map SpanKind to OTLP numeric kind. */\nconst SPAN_KIND_MAP: Record<SpanKind, number> = {\n  INTERNAL: 1, // SPAN_KIND_INTERNAL\n  SERVER: 2, // SPAN_KIND_SERVER\n  CLIENT: 3, // SPAN_KIND_CLIENT\n};\n\n/** Map SpanStatusCode to OTLP numeric status code. */\nconst STATUS_CODE_MAP: Record<SpanStatusCode, number> = {\n  UNSET: 0, // STATUS_CODE_UNSET\n  OK: 1, // STATUS_CODE_OK\n  ERROR: 2, // STATUS_CODE_ERROR\n};\n\n/**\n * Convert an attribute value to the OTLP `AnyValue` wire format.\n *\n * @returns Object with exactly one of `stringValue`, `intValue`, or `boolValue`.\n */\nfunction toOtlpAttributeValue(\n  value: string | number | boolean\n): Record<string, string | number | boolean> {\n  if (typeof value === \"string\") return { stringValue: value };\n  if (typeof value === \"boolean\") return { boolValue: value };\n  // OTLP distinguishes int vs double; we use intValue for integers.\n  if (Number.isInteger(value)) return { intValue: value };\n  return { doubleValue: value };\n}\n\n/** Convert a flat attributes map to the OTLP `KeyValue[]` format. */\nfunction toOtlpAttributes(\n  attrs: Record<string, string | number | boolean>\n): Array<{ key: string; value: Record<string, string | number | boolean> }> {\n  return Object.entries(attrs).map(([key, value]) => ({\n    key,\n    value: toOtlpAttributeValue(value),\n  }));\n}\n\n/** Milliseconds to nanoseconds, returned as a string (OTLP convention). */\nfunction msToNanos(ms: number): string {\n  // Avoid BigInt for maximum runtime compatibility; ms precision is\n  // sufficient and fits safely in a JS number when multiplied by 1e6.\n  return String(ms * 1_000_000);\n}\n\n/**\n * Convert an array of {@link ReadableSpan} to the OTLP JSON wire format.\n *\n * Produces the `ExportTraceServiceRequest` structure:\n * `{ resourceSpans: [{ resource, scopeSpans: [{ scope, spans }] }] }`\n *\n * @see https://opentelemetry.io/docs/specs/otlp/#otlphttp-request\n */\nfunction toOtlpPayload(\n  spans: ReadableSpan[],\n  serviceName: string,\n  serviceVersion?: string\n): object {\n  const resourceAttributes: Array<{\n    key: string;\n    value: Record<string, string | number | boolean>;\n  }> = [{ key: \"service.name\", value: { stringValue: serviceName } }];\n\n  if (serviceVersion) {\n    resourceAttributes.push({\n      key: \"service.version\",\n      value: { stringValue: serviceVersion },\n    });\n  }\n\n  const otlpSpans = spans.map((span) => {\n    const otlpSpan: Record<string, unknown> = {\n      traceId: span.traceId,\n      spanId: span.spanId,\n      name: span.name,\n      kind: SPAN_KIND_MAP[span.kind],\n      startTimeUnixNano: msToNanos(span.startTimeMs),\n      endTimeUnixNano: msToNanos(span.endTimeMs),\n      attributes: toOtlpAttributes(span.attributes),\n      status: {\n        code: STATUS_CODE_MAP[span.status.code],\n        ...(span.status.message ? { message: span.status.message } : {}),\n      },\n      events: span.events.map((event) => ({\n        name: event.name,\n        timeUnixNano: msToNanos(event.timeMs),\n        ...(event.attributes\n          ? { attributes: toOtlpAttributes(event.attributes) }\n          : {}),\n      })),\n    };\n\n    if (span.parentSpanId) {\n      otlpSpan.parentSpanId = span.parentSpanId;\n    }\n\n    return otlpSpan;\n  });\n\n  return {\n    resourceSpans: [\n      {\n        resource: { attributes: resourceAttributes },\n        scopeSpans: [\n          {\n            scope: { name: \"stoma-gateway\" },\n            spans: otlpSpans,\n          },\n        ],\n      },\n    ],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Built-in Exporters\n// ---------------------------------------------------------------------------\n\n/**\n * OTLP/HTTP JSON span exporter.\n *\n * Ships spans to an OpenTelemetry Collector (or compatible endpoint)\n * using `fetch()` with the OTLP JSON encoding. Designed for edge\n * runtimes - no gRPC, no protobuf, no Node.js dependencies.\n *\n * Export calls should be dispatched via `waitUntil()` so they do not\n * block the response path.\n */\nexport class OTLPSpanExporter implements SpanExporter {\n  private readonly endpoint: string;\n  private readonly headers: Record<string, string>;\n  private readonly timeoutMs: number;\n  private readonly serviceName: string;\n  private readonly serviceVersion?: string;\n\n  constructor(config: {\n    endpoint: string;\n    headers?: Record<string, string>;\n    timeoutMs?: number;\n    serviceName?: string;\n    serviceVersion?: string;\n  }) {\n    this.endpoint = config.endpoint;\n    this.headers = config.headers ?? {};\n    this.timeoutMs = config.timeoutMs ?? 10_000;\n    this.serviceName = config.serviceName ?? \"stoma-gateway\";\n    this.serviceVersion = config.serviceVersion;\n  }\n\n  async export(spans: ReadableSpan[]): Promise<void> {\n    if (spans.length === 0) return;\n\n    const payload = toOtlpPayload(spans, this.serviceName, this.serviceVersion);\n\n    await fetch(this.endpoint, {\n      method: \"POST\",\n      headers: {\n        \"content-type\": \"application/json\",\n        ...this.headers,\n      },\n      body: JSON.stringify(payload),\n      signal: AbortSignal.timeout(this.timeoutMs),\n    });\n  }\n}\n\n/**\n * Console span exporter for development and debugging.\n *\n * Logs each span to `console.debug()` with a compact one-line format\n * showing name, kind, duration, trace/span IDs, and status.\n */\nexport class ConsoleSpanExporter implements SpanExporter {\n  async export(spans: ReadableSpan[]): Promise<void> {\n    for (const span of spans) {\n      console.debug(\n        `[trace] ${span.name} ${span.kind} ${span.endTimeMs - span.startTimeMs}ms` +\n          ` trace=${span.traceId} span=${span.spanId}` +\n          (span.parentSpanId ? ` parent=${span.parentSpanId}` : \"\") +\n          ` status=${span.status.code}`\n      );\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Sampling\n// ---------------------------------------------------------------------------\n\n/**\n * Determine whether a request should be sampled based on the configured rate.\n *\n * @param sampleRate - Sampling probability in [0.0, 1.0].\n * @returns `true` if the request should be traced.\n */\nexport function shouldSample(sampleRate: number): boolean {\n  if (sampleRate >= 1.0) return true;\n  if (sampleRate <= 0.0) return false;\n  return Math.random() < sampleRate;\n}\n\n// ---------------------------------------------------------------------------\n// ID Generation\n// ---------------------------------------------------------------------------\n\n/**\n * Generate a 16-character lowercase hex span ID (8 random bytes).\n *\n * Uses `crypto.getRandomValues()` which is available in all edge runtimes\n * (Cloudflare Workers, Deno, Bun, Node 19+).\n */\nexport function generateOtelSpanId(): string {\n  const bytes = new Uint8Array(8);\n  crypto.getRandomValues(bytes);\n  return Array.from(bytes, (b) => b.toString(16).padStart(2, \"0\")).join(\"\");\n}\n"],"mappings":"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","names":[]}

package/dist/policies/auth/api-key-auth.d.ts

@@ -0,0 +1,64 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface ApiKeyAuthConfig extends PolicyConfig {
+    /** Header name to read the API key from. Default: "X-API-Key" */
+    headerName?: string;
+    /** Query parameter name as fallback. Default: undefined (disabled) */
+    queryParam?: string;
+    /** Validator function - return true if the key is valid */
+    validate: (key: string) => boolean | Promise<boolean>;
+    /**
+     * After successful validation, derive an identity string from the key
+     * and set it as a request header for upstream consumption.
+     *
+     * @example
+     * ```ts
+     * apiKeyAuth({
+     *   validate: (key) => keys.has(key),
+     *   forwardKeyIdentity: {
+     *     headerName: "x-api-client",
+     *     identityFn: (key) => keyToClientMap.get(key) ?? "unknown",
+     *   },
+     * });
+     * ```
+     */
+    forwardKeyIdentity?: {
+        /** Header name to set on the request. */
+        headerName: string;
+        /** Derive an identity string from the validated key. Can be async. */
+        identityFn: (key: string) => string | Promise<string>;
+    };
+}
+/**
+ * Validate API keys from headers or query parameters.
+ *
+ * Checks the `X-API-Key` header by default, with an optional query parameter
+ * fallback. The `validate` function can be async to support remote key lookups.
+ *
+ * @param config - API key settings with a required `validate` function.
+ * @returns A {@link Policy} at priority 10.
+ *
+ * @example
+ * ```ts
+ * // Static key validation
+ * apiKeyAuth({
+ *   validate: (key) => key === env.API_KEY,
+ * });
+ *
+ * // Async validation with query parameter fallback
+ * apiKeyAuth({
+ *   headerName: "Authorization",
+ *   queryParam: "api_key",
+ *   validate: async (key) => {
+ *     const result = await kv.get(`api-key:${key}`);
+ *     return result !== null;
+ *   },
+ * });
+ * ```
+ */
+declare const apiKeyAuth: (config: ApiKeyAuthConfig) => Policy;
+
+export { type ApiKeyAuthConfig, apiKeyAuth };