@vivero/stoma 0.1.0-rc.10

package/dist/policies/observability/metrics-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/observability/metrics-reporter.ts"],"sourcesContent":["/**\n * Metrics reporter policy - records request counts, latencies, and errors.\n *\n * Plugs into any {@link MetricsCollector} implementation and records\n * standard gateway metrics per request. Runs at priority 1 (just after\n * request-log at 0). Merges any custom tags from `assignMetrics`.\n *\n * @module metrics-reporter\n */\nimport type { MetricsCollector } from \"../../observability/metrics\";\nimport { definePolicy, Priority, safeCall } from \"../sdk\";\nimport type { PolicyConfig } from \"../types\";\n\nexport interface MetricsReporterConfig extends PolicyConfig {\n  /** The metrics collector to record to. */\n  collector: MetricsCollector;\n}\n\n/**\n * Record standard gateway metrics for every request.\n *\n * Metrics recorded:\n * - `gateway_requests_total` (counter) - total requests, tagged by method/path/status/gateway\n * - `gateway_request_duration_ms` (histogram) - end-to-end request duration\n * - `gateway_request_errors_total` (counter) - requests with status >= 400\n * - `gateway_policy_duration_ms` (histogram) - per-policy timing when available\n *\n * @param config - Must include a {@link MetricsCollector} instance.\n * @returns A {@link Policy} at priority 1.\n */\nexport const metricsReporter =\n  /*#__PURE__*/ definePolicy<MetricsReporterConfig>({\n    name: \"metrics-reporter\",\n    priority: Priority.METRICS,\n    httpOnly: true,\n    handler: async (c, next, { config, debug, gateway }) => {\n      const startTime = Date.now();\n\n      await next();\n\n      // Collector failures must never crash the request pipeline\n      await safeCall(\n        async () => {\n          const dynamicTagsRaw = c.get(\"_metricsTags\") as\n            | Record<string, unknown>\n            | undefined;\n          const dynamicTags: Record<string, string> = {};\n          if (dynamicTagsRaw) {\n            for (const [key, value] of Object.entries(dynamicTagsRaw)) {\n              if (typeof value === \"string\") {\n                dynamicTags[key] = value;\n              }\n            }\n          }\n\n          const url = new URL(c.req.url);\n          const tags: Record<string, string> = {\n            ...dynamicTags,\n            method: c.req.method,\n            path: gateway?.routePath ?? url.pathname,\n            status: String(c.res.status),\n            gateway: gateway?.gatewayName ?? \"unknown\",\n          };\n\n          // Total requests counter\n          config.collector.increment(\"gateway_requests_total\", 1, tags);\n\n          // Request duration histogram\n          const duration = Date.now() - startTime;\n          config.collector.histogram(\n            \"gateway_request_duration_ms\",\n            duration,\n            tags\n          );\n\n          // Error counter (4xx and 5xx)\n          if (c.res.status >= 400) {\n            config.collector.increment(\"gateway_request_errors_total\", 1, tags);\n          }\n\n          // Per-policy timing (if available from pipeline instrumentation)\n          const timings = c.get(\"_policyTimings\") as\n            | Array<{ name: string; durationMs: number }>\n            | undefined;\n          if (timings) {\n            for (const t of timings) {\n              config.collector.histogram(\n                \"gateway_policy_duration_ms\",\n                t.durationMs,\n                {\n                  ...dynamicTags,\n                  policy: t.name,\n                  gateway: gateway?.gatewayName ?? \"unknown\",\n                }\n              );\n            }\n          }\n        },\n        undefined,\n        debug,\n        \"collector\"\n      );\n    },\n  });\n"],"mappings":"AAUA,SAAS,cAAc,UAAU,gBAAgB;AAoB1C,MAAM,kBACG,6BAAoC;AAAA,EAChD,MAAM;AAAA,EACN,UAAU,SAAS;AAAA,EACnB,UAAU;AAAA,EACV,SAAS,OAAO,GAAG,MAAM,EAAE,QAAQ,OAAO,QAAQ,MAAM;AACtD,UAAM,YAAY,KAAK,IAAI;AAE3B,UAAM,KAAK;AAGX,UAAM;AAAA,MACJ,YAAY;AACV,cAAM,iBAAiB,EAAE,IAAI,cAAc;AAG3C,cAAM,cAAsC,CAAC;AAC7C,YAAI,gBAAgB;AAClB,qBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,cAAc,GAAG;AACzD,gBAAI,OAAO,UAAU,UAAU;AAC7B,0BAAY,GAAG,IAAI;AAAA,YACrB;AAAA,UACF;AAAA,QACF;AAEA,cAAM,MAAM,IAAI,IAAI,EAAE,IAAI,GAAG;AAC7B,cAAM,OAA+B;AAAA,UACnC,GAAG;AAAA,UACH,QAAQ,EAAE,IAAI;AAAA,UACd,MAAM,SAAS,aAAa,IAAI;AAAA,UAChC,QAAQ,OAAO,EAAE,IAAI,MAAM;AAAA,UAC3B,SAAS,SAAS,eAAe;AAAA,QACnC;AAGA,eAAO,UAAU,UAAU,0BAA0B,GAAG,IAAI;AAG5D,cAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,eAAO,UAAU;AAAA,UACf;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAGA,YAAI,EAAE,IAAI,UAAU,KAAK;AACvB,iBAAO,UAAU,UAAU,gCAAgC,GAAG,IAAI;AAAA,QACpE;AAGA,cAAM,UAAU,EAAE,IAAI,gBAAgB;AAGtC,YAAI,SAAS;AACX,qBAAW,KAAK,SAAS;AACvB,mBAAO,UAAU;AAAA,cACf;AAAA,cACA,EAAE;AAAA,cACF;AAAA,gBACE,GAAG;AAAA,gBACH,QAAQ,EAAE;AAAA,gBACV,SAAS,SAAS,eAAe;AAAA,cACnC;AAAA,YACF;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF,CAAC;","names":[]}

package/dist/policies/observability/request-log.d.ts

@@ -0,0 +1,135 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface RequestLogConfig extends PolicyConfig {
+    /** Additional fields to extract from the request */
+    extractFields?: (c: unknown) => Record<string, unknown>;
+    /** Custom log sink - defaults to console.log with structured JSON */
+    sink?: (entry: LogEntry) => void | Promise<void>;
+    /** Ordered list of headers to inspect for the client IP. Default: `["cf-connecting-ip", "x-forwarded-for"]`. */
+    ipHeaders?: string[];
+    /** Log request body (opt-in). Default: `false`. */
+    logRequestBody?: boolean;
+    /** Log response body (opt-in). Default: `false`. */
+    logResponseBody?: boolean;
+    /** Maximum body size in bytes to capture. Default: `8192`. */
+    maxBodyLength?: number;
+    /** JSON field paths to redact from logged bodies (e.g., `["password", "*.secret"]`). */
+    redactPaths?: string[];
+}
+/** Structured log entry emitted for each request/response pair. */
+interface LogEntry {
+    /** ISO 8601 timestamp when the log was emitted. */
+    timestamp: string;
+    /** Unique request ID for distributed tracing. */
+    requestId: string;
+    /** HTTP method (e.g. `"GET"`, `"POST"`). */
+    method: string;
+    /** URL pathname (without query string). */
+    path: string;
+    /** HTTP response status code. */
+    statusCode: number;
+    /** End-to-end request duration in milliseconds. */
+    durationMs: number;
+    /** Client IP from `CF-Connecting-IP` or `X-Forwarded-For`. */
+    clientIp: string;
+    /** Client User-Agent header value. */
+    userAgent: string;
+    /** Gateway name from config. */
+    gatewayName: string;
+    /** Matched route path pattern. */
+    routePath: string;
+    /** Upstream target identifier (e.g. origin URL, service binding name, or `"handler"`). */
+    upstream: string;
+    /** W3C Trace Context - 32-hex trace ID. */
+    traceId?: string;
+    /** W3C Trace Context - 16-hex span ID for this gateway request. */
+    spanId?: string;
+    /** Captured request body (when `logRequestBody` is enabled). */
+    requestBody?: unknown;
+    /** Captured response body (when `logResponseBody` is enabled). */
+    responseBody?: unknown;
+    /** Custom fields from `extractFields` callback. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Emit structured JSON logs for every request/response pair.
+ *
+ * Captures method, path, status, duration, client IP, user agent, and
+ * gateway context (request ID, gateway name, route path). Runs at priority 0
+ * so it wraps the entire pipeline and measures end-to-end latency.
+ *
+ * By default, logs are written to `console.log` as JSON lines. Provide a
+ * custom `sink` to route logs to an external service (e.g., Logflare,
+ * Datadog, or a Durable Object buffer).
+ *
+ * ## Data boundary: request logs vs analytics
+ *
+ * Request logs and analytics (`@vivero/stoma-analytics`) serve
+ * different purposes and deliberately carry different fields.
+ *
+ * **Request logs** (this policy) are for **debugging and operational triage**.
+ * Fields are high-cardinality — grep-friendly, not GROUP BY-friendly:
+ *
+ * | Field        | Why it's here                                          |
+ * |--------------|--------------------------------------------------------|
+ * | requestId    | Unique per request — grep to find a single transaction |
+ * | path         | Actual URL e.g. /users/42 (high cardinality)           |
+ * | clientIp     | PII, high cardinality — abuse investigation only       |
+ * | userAgent    | High cardinality — debug specific client issues         |
+ * | spanId       | Distributed tracing span correlation                   |
+ * | requestBody  | Deep debugging (opt-in, redactable)                    |
+ * | responseBody | Deep debugging (opt-in, redactable)                    |
+ *
+ * **Overlapping fields** (appear in both logs and analytics):
+ *
+ * | Field       | Why both need it                                       |
+ * |-------------|--------------------------------------------------------|
+ * | timestamp   | Time-series bucketing (analytics) / grep by time (logs)|
+ * | gatewayName | GROUP BY gateway (analytics) / filter logs by gateway  |
+ * | routePath   | GROUP BY route pattern (analytics) / filter by route   |
+ * | method      | GROUP BY method (analytics) / filter logs by method    |
+ * | statusCode  | Error rate dashboards (analytics) / grep errors (logs) |
+ * | durationMs  | AVG/P99 latency (analytics) / slow request triage      |
+ * | traceId     | Dashboard anomaly drill-down → find matching log lines |
+ *
+ * **Analytics-only fields** (NOT in request logs):
+ *
+ * | Field        | Why only analytics                                    |
+ * |--------------|-------------------------------------------------------|
+ * | responseSize | SUM bandwidth, detect payload bloat — aggregate only   |
+ * | dimensions   | Extensible low-cardinality facets for GROUP BY         |
+ *
+ * @param config - Custom field extraction, body logging, and sink. All fields optional.
+ * @returns A {@link Policy} at priority 0 (runs first, wraps everything).
+ *
+ * @example
+ * ```ts
+ * import { createGateway } from "@vivero/stoma";
+ * import { requestLog } from "@vivero/stoma/policies";
+ *
+ * // Default structured JSON logging to console
+ * createGateway({
+ *   policies: [requestLog()],
+ *   routes: [...],
+ * });
+ *
+ * // With body logging and redaction
+ * requestLog({
+ *   logRequestBody: true,
+ *   logResponseBody: true,
+ *   redactPaths: ["password", "*.secret", "auth.token"],
+ *   sink: async (entry) => {
+ *     await fetch("https://logs.example.com/ingest", {
+ *       method: "POST",
+ *       body: JSON.stringify(entry),
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare const requestLog: (config?: RequestLogConfig | undefined) => Policy;
+
+export { type LogEntry, type RequestLogConfig, requestLog };

package/dist/policies/observability/request-log.js

@@ -0,0 +1,134 @@
+import { extractClientIp } from "../../utils/ip";
+import { redactFields } from "../../utils/redact";
+import { definePolicy, Priority, safeCall } from "../sdk";
+const DEFAULT_MAX_BODY_LENGTH = 8192;
+const requestLog = /* @__PURE__ */ definePolicy({
+  name: "request-log",
+  priority: Priority.OBSERVABILITY,
+  httpOnly: true,
+  handler: async (c, next, { config, debug, gateway }) => {
+    const sink = config.sink ?? defaultSink;
+    const maxBodyLength = config.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH;
+    const startTime = Date.now();
+    let requestBody;
+    if (config.logRequestBody) {
+      requestBody = await captureRequestBody(
+        c.req.raw,
+        maxBodyLength,
+        config.redactPaths
+      );
+    }
+    await next();
+    const url = new URL(c.req.url);
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId: gateway?.requestId ?? c.res.headers.get("x-request-id") ?? "unknown",
+      method: c.req.method,
+      path: url.pathname,
+      statusCode: c.res.status,
+      durationMs: Date.now() - startTime,
+      clientIp: extractClientIp(c.req.raw.headers, {
+        ipHeaders: config.ipHeaders,
+        fallbackAddress: getRemoteAddress(c)
+      }),
+      userAgent: c.req.header("user-agent") ?? "unknown",
+      gatewayName: gateway?.gatewayName ?? "unknown",
+      routePath: gateway?.routePath ?? url.pathname,
+      upstream: c.get("_upstreamTarget") ?? "unknown",
+      traceId: gateway?.traceId,
+      spanId: gateway?.spanId
+    };
+    if (requestBody !== void 0) {
+      entry.requestBody = requestBody;
+    }
+    if (config.logResponseBody) {
+      const responseBody = await captureResponseBody(
+        c,
+        maxBodyLength,
+        config.redactPaths
+      );
+      if (responseBody !== void 0) {
+        entry.responseBody = responseBody;
+      }
+    }
+    if (config.extractFields) {
+      try {
+        entry.extra = config.extractFields(c);
+      } catch {
+      }
+    }
+    await safeCall(
+      () => Promise.resolve(sink(entry)),
+      void 0,
+      debug,
+      "sink()"
+    );
+  }
+});
+async function captureRequestBody(req, maxLength, redactPaths) {
+  try {
+    const cloned = req.clone();
+    const text = await cloned.text();
+    if (!text) return void 0;
+    const truncated = text.length > maxLength ? `${text.slice(0, maxLength)}...[truncated]` : text;
+    const contentType = req.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      try {
+        let parsed = JSON.parse(
+          truncated.endsWith("...[truncated]") ? text.slice(0, maxLength) : text
+        );
+        if (redactPaths?.length) {
+          parsed = redactFields(parsed, { paths: redactPaths });
+        }
+        return parsed;
+      } catch {
+        return truncated;
+      }
+    }
+    return truncated;
+  } catch {
+    return void 0;
+  }
+}
+async function captureResponseBody(c, maxLength, redactPaths) {
+  try {
+    const cloned = c.res.clone();
+    const text = await cloned.text();
+    if (!text) return void 0;
+    const truncated = text.length > maxLength ? `${text.slice(0, maxLength)}...[truncated]` : text;
+    const contentType = c.res.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      try {
+        let parsed = JSON.parse(
+          truncated.endsWith("...[truncated]") ? text.slice(0, maxLength) : text
+        );
+        if (redactPaths?.length) {
+          parsed = redactFields(parsed, { paths: redactPaths });
+        }
+        return parsed;
+      } catch {
+        return truncated;
+      }
+    }
+    return truncated;
+  } catch {
+    return void 0;
+  }
+}
+function getRemoteAddress(c) {
+  try {
+    const env = c.env;
+    const incoming = env?.incoming;
+    const addr = incoming?.socket?.remoteAddress;
+    if (typeof addr === "string" && addr) return addr;
+  } catch {
+  }
+  return void 0;
+}
+function defaultSink(entry) {
+  console.log(JSON.stringify(entry));
+}
+export {
+  requestLog
+};
+//# sourceMappingURL=request-log.js.map

package/dist/policies/observability/request-log.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/observability/request-log.ts"],"sourcesContent":["/**\n * Request logging policy - structured JSON logs for every request.\n *\n * @module request-log\n */\nimport { extractClientIp } from \"../../utils/ip\";\nimport { redactFields } from \"../../utils/redact\";\nimport { definePolicy, Priority, safeCall } from \"../sdk\";\nimport type { PolicyConfig } from \"../types\";\n\nexport interface RequestLogConfig extends PolicyConfig {\n  /** Additional fields to extract from the request */\n  extractFields?: (c: unknown) => Record<string, unknown>;\n  /** Custom log sink - defaults to console.log with structured JSON */\n  sink?: (entry: LogEntry) => void | Promise<void>;\n  /** Ordered list of headers to inspect for the client IP. Default: `[\"cf-connecting-ip\", \"x-forwarded-for\"]`. */\n  ipHeaders?: string[];\n  /** Log request body (opt-in). Default: `false`. */\n  logRequestBody?: boolean;\n  /** Log response body (opt-in). Default: `false`. */\n  logResponseBody?: boolean;\n  /** Maximum body size in bytes to capture. Default: `8192`. */\n  maxBodyLength?: number;\n  /** JSON field paths to redact from logged bodies (e.g., `[\"password\", \"*.secret\"]`). */\n  redactPaths?: string[];\n}\n\n/** Structured log entry emitted for each request/response pair. */\nexport interface LogEntry {\n  /** ISO 8601 timestamp when the log was emitted. */\n  timestamp: string;\n  /** Unique request ID for distributed tracing. */\n  requestId: string;\n  /** HTTP method (e.g. `\"GET\"`, `\"POST\"`). */\n  method: string;\n  /** URL pathname (without query string). */\n  path: string;\n  /** HTTP response status code. */\n  statusCode: number;\n  /** End-to-end request duration in milliseconds. */\n  durationMs: number;\n  /** Client IP from `CF-Connecting-IP` or `X-Forwarded-For`. */\n  clientIp: string;\n  /** Client User-Agent header value. */\n  userAgent: string;\n  /** Gateway name from config. */\n  gatewayName: string;\n  /** Matched route path pattern. */\n  routePath: string;\n  /** Upstream target identifier (e.g. origin URL, service binding name, or `\"handler\"`). */\n  upstream: string;\n  /** W3C Trace Context - 32-hex trace ID. */\n  traceId?: string;\n  /** W3C Trace Context - 16-hex span ID for this gateway request. */\n  spanId?: string;\n  /** Captured request body (when `logRequestBody` is enabled). */\n  requestBody?: unknown;\n  /** Captured response body (when `logResponseBody` is enabled). */\n  responseBody?: unknown;\n  /** Custom fields from `extractFields` callback. */\n  extra?: Record<string, unknown>;\n}\n\nconst DEFAULT_MAX_BODY_LENGTH = 8192;\n\n/**\n * Emit structured JSON logs for every request/response pair.\n *\n * Captures method, path, status, duration, client IP, user agent, and\n * gateway context (request ID, gateway name, route path). Runs at priority 0\n * so it wraps the entire pipeline and measures end-to-end latency.\n *\n * By default, logs are written to `console.log` as JSON lines. Provide a\n * custom `sink` to route logs to an external service (e.g., Logflare,\n * Datadog, or a Durable Object buffer).\n *\n * ## Data boundary: request logs vs analytics\n *\n * Request logs and analytics (`@vivero/stoma-analytics`) serve\n * different purposes and deliberately carry different fields.\n *\n * **Request logs** (this policy) are for **debugging and operational triage**.\n * Fields are high-cardinality — grep-friendly, not GROUP BY-friendly:\n *\n * | Field        | Why it's here                                          |\n * |--------------|--------------------------------------------------------|\n * | requestId    | Unique per request — grep to find a single transaction |\n * | path         | Actual URL e.g. /users/42 (high cardinality)           |\n * | clientIp     | PII, high cardinality — abuse investigation only       |\n * | userAgent    | High cardinality — debug specific client issues         |\n * | spanId       | Distributed tracing span correlation                   |\n * | requestBody  | Deep debugging (opt-in, redactable)                    |\n * | responseBody | Deep debugging (opt-in, redactable)                    |\n *\n * **Overlapping fields** (appear in both logs and analytics):\n *\n * | Field       | Why both need it                                       |\n * |-------------|--------------------------------------------------------|\n * | timestamp   | Time-series bucketing (analytics) / grep by time (logs)|\n * | gatewayName | GROUP BY gateway (analytics) / filter logs by gateway  |\n * | routePath   | GROUP BY route pattern (analytics) / filter by route   |\n * | method      | GROUP BY method (analytics) / filter logs by method    |\n * | statusCode  | Error rate dashboards (analytics) / grep errors (logs) |\n * | durationMs  | AVG/P99 latency (analytics) / slow request triage      |\n * | traceId     | Dashboard anomaly drill-down → find matching log lines |\n *\n * **Analytics-only fields** (NOT in request logs):\n *\n * | Field        | Why only analytics                                    |\n * |--------------|-------------------------------------------------------|\n * | responseSize | SUM bandwidth, detect payload bloat — aggregate only   |\n * | dimensions   | Extensible low-cardinality facets for GROUP BY         |\n *\n * @param config - Custom field extraction, body logging, and sink. All fields optional.\n * @returns A {@link Policy} at priority 0 (runs first, wraps everything).\n *\n * @example\n * ```ts\n * import { createGateway } from \"@vivero/stoma\";\n * import { requestLog } from \"@vivero/stoma/policies\";\n *\n * // Default structured JSON logging to console\n * createGateway({\n *   policies: [requestLog()],\n *   routes: [...],\n * });\n *\n * // With body logging and redaction\n * requestLog({\n *   logRequestBody: true,\n *   logResponseBody: true,\n *   redactPaths: [\"password\", \"*.secret\", \"auth.token\"],\n *   sink: async (entry) => {\n *     await fetch(\"https://logs.example.com/ingest\", {\n *       method: \"POST\",\n *       body: JSON.stringify(entry),\n *     });\n *   },\n * });\n * ```\n */\nexport const requestLog = /*#__PURE__*/ definePolicy<RequestLogConfig>({\n  name: \"request-log\",\n  priority: Priority.OBSERVABILITY,\n  httpOnly: true,\n  handler: async (c, next, { config, debug, gateway }) => {\n    const sink = config.sink ?? defaultSink;\n    const maxBodyLength = config.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH;\n    const startTime = Date.now();\n\n    // Capture request body before downstream consumes it\n    let requestBody: unknown;\n    if (config.logRequestBody) {\n      requestBody = await captureRequestBody(\n        c.req.raw,\n        maxBodyLength,\n        config.redactPaths\n      );\n    }\n\n    // Let downstream run\n    await next();\n\n    // Build log entry from gateway context and response\n    const url = new URL(c.req.url);\n\n    const entry: LogEntry = {\n      timestamp: new Date().toISOString(),\n      requestId:\n        gateway?.requestId ?? c.res.headers.get(\"x-request-id\") ?? \"unknown\",\n      method: c.req.method,\n      path: url.pathname,\n      statusCode: c.res.status,\n      durationMs: Date.now() - startTime,\n      clientIp: extractClientIp(c.req.raw.headers, {\n        ipHeaders: config.ipHeaders,\n        fallbackAddress: getRemoteAddress(c),\n      }),\n      userAgent: c.req.header(\"user-agent\") ?? \"unknown\",\n      gatewayName: gateway?.gatewayName ?? \"unknown\",\n      routePath: gateway?.routePath ?? url.pathname,\n      upstream: (c.get(\"_upstreamTarget\") as string | undefined) ?? \"unknown\",\n      traceId: gateway?.traceId,\n      spanId: gateway?.spanId,\n    };\n\n    if (requestBody !== undefined) {\n      entry.requestBody = requestBody;\n    }\n\n    // Capture response body after downstream\n    if (config.logResponseBody) {\n      const responseBody = await captureResponseBody(\n        c,\n        maxBodyLength,\n        config.redactPaths\n      );\n      if (responseBody !== undefined) {\n        entry.responseBody = responseBody;\n      }\n    }\n\n    // Extract custom fields\n    if (config.extractFields) {\n      try {\n        entry.extra = config.extractFields(c);\n      } catch {\n        // Don't let field extraction break the request\n      }\n    }\n\n    // Sink failure must never crash the request pipeline\n    await safeCall(\n      () => Promise.resolve(sink(entry)),\n      undefined,\n      debug,\n      \"sink()\"\n    );\n  },\n});\n\n/**\n * Capture and optionally redact the request body.\n * Clones the request to avoid consuming the body stream.\n */\nasync function captureRequestBody(\n  req: Request,\n  maxLength: number,\n  redactPaths?: string[]\n): Promise<unknown> {\n  try {\n    // Clone so the original body stream stays available for downstream\n    const cloned = req.clone();\n    const text = await cloned.text();\n    if (!text) return undefined;\n\n    const truncated =\n      text.length > maxLength\n        ? `${text.slice(0, maxLength)}...[truncated]`\n        : text;\n\n    const contentType = req.headers.get(\"content-type\") ?? \"\";\n    if (contentType.includes(\"application/json\")) {\n      try {\n        let parsed: unknown = JSON.parse(\n          truncated.endsWith(\"...[truncated]\") ? text.slice(0, maxLength) : text\n        );\n        if (redactPaths?.length) {\n          parsed = redactFields(parsed, { paths: redactPaths });\n        }\n        return parsed;\n      } catch {\n        // Invalid JSON - return as string\n        return truncated;\n      }\n    }\n\n    return truncated;\n  } catch {\n    // Never break the request pipeline\n    return undefined;\n  }\n}\n\n/**\n * Capture and optionally redact the response body.\n * Clones the response to avoid consuming the body.\n */\nasync function captureResponseBody(\n  c: { res: Response },\n  maxLength: number,\n  redactPaths?: string[]\n): Promise<unknown> {\n  try {\n    // Clone the response so the original body remains consumable\n    const cloned = c.res.clone();\n    const text = await cloned.text();\n    if (!text) return undefined;\n\n    const truncated =\n      text.length > maxLength\n        ? `${text.slice(0, maxLength)}...[truncated]`\n        : text;\n\n    const contentType = c.res.headers.get(\"content-type\") ?? \"\";\n    if (contentType.includes(\"application/json\")) {\n      try {\n        let parsed: unknown = JSON.parse(\n          truncated.endsWith(\"...[truncated]\") ? text.slice(0, maxLength) : text\n        );\n        if (redactPaths?.length) {\n          parsed = redactFields(parsed, { paths: redactPaths });\n        }\n        return parsed;\n      } catch {\n        return truncated;\n      }\n    }\n\n    return truncated;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Try to extract the remote address from the Hono env.\n *\n * `@hono/node-server` stores the Node.js `IncomingMessage` as `c.env.incoming`,\n * giving access to `socket.remoteAddress`. This is a duck-typed check so the\n * gateway library doesn't depend on any specific runtime adapter.\n */\nfunction getRemoteAddress(c: { env?: unknown }): string | undefined {\n  try {\n    const env = c.env as Record<string, unknown> | undefined;\n    // @hono/node-server: env.incoming is a Node IncomingMessage\n    const incoming = env?.incoming as\n      | { socket?: { remoteAddress?: string } }\n      | undefined;\n    const addr = incoming?.socket?.remoteAddress;\n    if (typeof addr === \"string\" && addr) return addr;\n  } catch {\n    // Never break logging\n  }\n  return undefined;\n}\n\nfunction defaultSink(entry: LogEntry): void {\n  console.log(JSON.stringify(entry));\n}\n"],"mappings":"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","names":[]}

package/dist/policies/observability/server-timing.d.ts

@@ -0,0 +1,35 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import { Context } from 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+/** Visibility mode controlling when timing headers are emitted. */
+type ServerTimingVisibility = "always" | "debug-only" | "conditional";
+interface ServerTimingConfig extends PolicyConfig {
+    /** Emit the `Server-Timing` header with per-policy breakdown. Default: `true`. */
+    serverTimingHeader?: boolean;
+    /** Emit the `X-Response-Time` header with total gateway time. Default: `true`. */
+    responseTimeHeader?: boolean;
+    /** Number of decimal places for duration values. Default: `1`. */
+    precision?: number;
+    /** Add a `total` entry to `Server-Timing`. Default: `true`. */
+    includeTotal?: boolean;
+    /** Optional function to generate a description for each timing entry. */
+    descriptionFn?: (name: string) => string;
+    /** Controls when timing headers are emitted. Default: `"debug-only"`. */
+    visibility?: ServerTimingVisibility;
+    /** Required when `visibility` is `"conditional"`. Called per-request to decide. */
+    visibilityFn?: (c: Context) => boolean | Promise<boolean>;
+}
+/**
+ * Emit W3C `Server-Timing` and `X-Response-Time` response headers.
+ *
+ * Reads per-policy timing data from the pipeline instrumentation and
+ * formats it as standard headers visible in browser DevTools.
+ *
+ * @param config - Optional configuration for headers, precision, and visibility.
+ * @returns A {@link Policy} at priority 1 (METRICS).
+ */
+declare const serverTiming: (config?: ServerTimingConfig | undefined) => Policy;
+
+export { type ServerTimingConfig, type ServerTimingVisibility, serverTiming };

package/dist/policies/observability/server-timing.js

@@ -0,0 +1,89 @@
+import { GatewayError } from "../../core/errors";
+import { escapeHeaderValue } from "../../utils/headers";
+import { toSelfTimes } from "../../utils/timing";
+import { definePolicy, isDebugRequested, Priority } from "../sdk";
+function sanitizeMetricName(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function formatEntry(name, durationMs, precision, descriptionFn) {
+  const sanitized = sanitizeMetricName(name);
+  const dur = durationMs.toFixed(precision);
+  const desc = descriptionFn?.(name);
+  if (desc) {
+    return `${sanitized};dur=${dur};desc="${escapeHeaderValue(desc)}"`;
+  }
+  return `${sanitized};dur=${dur}`;
+}
+const serverTiming = /* @__PURE__ */ definePolicy({
+  name: "server-timing",
+  priority: Priority.METRICS,
+  httpOnly: true,
+  defaults: {
+    serverTimingHeader: true,
+    responseTimeHeader: true,
+    precision: 1,
+    includeTotal: true,
+    visibility: "debug-only"
+  },
+  validate: (config) => {
+    if (config.visibility === "conditional" && typeof config.visibilityFn !== "function") {
+      throw new GatewayError(
+        500,
+        "config-error",
+        'serverTiming: visibility "conditional" requires a visibilityFn'
+      );
+    }
+  },
+  handler: async (c, next, { config, debug }) => {
+    const startTime = Date.now();
+    await next();
+    let visible;
+    switch (config.visibility) {
+      case "always":
+        visible = true;
+        break;
+      case "conditional":
+        visible = await config.visibilityFn(c);
+        break;
+      default:
+        visible = isDebugRequested(c);
+        break;
+    }
+    if (!visible) {
+      debug("skipping - visibility check failed");
+      return;
+    }
+    const totalMs = Date.now() - startTime;
+    const precision = config.precision;
+    const rawTimings = c.get("_policyTimings");
+    const selfTimings = rawTimings ? toSelfTimes(rawTimings) : void 0;
+    if (config.serverTimingHeader) {
+      const entries = [];
+      if (config.includeTotal) {
+        entries.push(
+          formatEntry("total", totalMs, precision, config.descriptionFn)
+        );
+      }
+      if (selfTimings) {
+        for (const t of selfTimings) {
+          entries.push(
+            formatEntry(t.name, t.durationMs, precision, config.descriptionFn)
+          );
+        }
+      }
+      if (entries.length > 0) {
+        c.res.headers.set("server-timing", entries.join(", "));
+        debug("Server-Timing: %s", entries.join(", "));
+      }
+    }
+    if (config.responseTimeHeader) {
+      const value = `${totalMs.toFixed(precision)}ms`;
+      c.res.headers.set("x-response-time", value);
+      debug("X-Response-Time: %s", value);
+    }
+  }
+});
+export {
+  serverTiming
+};
+//# sourceMappingURL=server-timing.js.map

package/dist/policies/observability/server-timing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/observability/server-timing.ts"],"sourcesContent":["/**\n * Server-Timing policy - surfaces per-policy timing as W3C Server-Timing headers.\n *\n * Reads the `_policyTimings` context key populated by the pipeline and\n * emits standard `Server-Timing` and `X-Response-Time` response headers.\n * Browser DevTools display `Server-Timing` entries natively.\n *\n * Visibility modes control when headers are emitted:\n * - `\"always\"` - every response (dev, internal APIs)\n * - `\"debug-only\"` - only when the client sent `x-stoma-debug` (safe for production)\n * - `\"conditional\"` - user-provided predicate function\n *\n * @module server-timing\n */\nimport type { Context } from \"hono\";\nimport { GatewayError } from \"../../core/errors\";\nimport { escapeHeaderValue } from \"../../utils/headers\";\nimport { toSelfTimes } from \"../../utils/timing\";\nimport { definePolicy, isDebugRequested, Priority } from \"../sdk\";\nimport type { PolicyConfig } from \"../types\";\n\n/** Visibility mode controlling when timing headers are emitted. */\nexport type ServerTimingVisibility = \"always\" | \"debug-only\" | \"conditional\";\n\nexport interface ServerTimingConfig extends PolicyConfig {\n  /** Emit the `Server-Timing` header with per-policy breakdown. Default: `true`. */\n  serverTimingHeader?: boolean;\n  /** Emit the `X-Response-Time` header with total gateway time. Default: `true`. */\n  responseTimeHeader?: boolean;\n  /** Number of decimal places for duration values. Default: `1`. */\n  precision?: number;\n  /** Add a `total` entry to `Server-Timing`. Default: `true`. */\n  includeTotal?: boolean;\n  /** Optional function to generate a description for each timing entry. */\n  descriptionFn?: (name: string) => string;\n  /** Controls when timing headers are emitted. Default: `\"debug-only\"`. */\n  visibility?: ServerTimingVisibility;\n  /** Required when `visibility` is `\"conditional\"`. Called per-request to decide. */\n  visibilityFn?: (c: Context) => boolean | Promise<boolean>;\n}\n\n// -- helpers (file-private) ---------------------------------------------------\n\n/** Strip characters outside the Server-Timing token charset. */\nfunction sanitizeMetricName(name: string): string {\n  return name.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n}\n\n/** Build a single Server-Timing entry string. */\nfunction formatEntry(\n  name: string,\n  durationMs: number,\n  precision: number,\n  descriptionFn?: (name: string) => string\n): string {\n  const sanitized = sanitizeMetricName(name);\n  const dur = durationMs.toFixed(precision);\n  const desc = descriptionFn?.(name);\n  if (desc) {\n    return `${sanitized};dur=${dur};desc=\"${escapeHeaderValue(desc)}\"`;\n  }\n  return `${sanitized};dur=${dur}`;\n}\n\n// -- policy -------------------------------------------------------------------\n\n/**\n * Emit W3C `Server-Timing` and `X-Response-Time` response headers.\n *\n * Reads per-policy timing data from the pipeline instrumentation and\n * formats it as standard headers visible in browser DevTools.\n *\n * @param config - Optional configuration for headers, precision, and visibility.\n * @returns A {@link Policy} at priority 1 (METRICS).\n */\nexport const serverTiming = /*#__PURE__*/ definePolicy<ServerTimingConfig>({\n  name: \"server-timing\",\n  priority: Priority.METRICS,\n  httpOnly: true,\n  defaults: {\n    serverTimingHeader: true,\n    responseTimeHeader: true,\n    precision: 1,\n    includeTotal: true,\n    visibility: \"debug-only\",\n  },\n  validate: (config) => {\n    if (\n      config.visibility === \"conditional\" &&\n      typeof config.visibilityFn !== \"function\"\n    ) {\n      throw new GatewayError(\n        500,\n        \"config-error\",\n        'serverTiming: visibility \"conditional\" requires a visibilityFn'\n      );\n    }\n  },\n  handler: async (c, next, { config, debug }) => {\n    const startTime = Date.now();\n\n    await next();\n\n    // Evaluate visibility\n    let visible: boolean;\n    switch (config.visibility) {\n      case \"always\":\n        visible = true;\n        break;\n      case \"conditional\":\n        visible = await config.visibilityFn!(c);\n        break;\n      default:\n        visible = isDebugRequested(c);\n        break;\n    }\n\n    if (!visible) {\n      debug(\"skipping - visibility check failed\");\n      return;\n    }\n\n    const totalMs = Date.now() - startTime;\n    const precision = config.precision!;\n\n    // Read per-policy timings accumulated by policiesToMiddleware().\n    // These are inclusive (onion-model) - convert to self-time for the header.\n    const rawTimings = c.get(\"_policyTimings\") as\n      | Array<{ name: string; durationMs: number }>\n      | undefined;\n    const selfTimings = rawTimings ? toSelfTimes(rawTimings) : undefined;\n\n    // Server-Timing header\n    if (config.serverTimingHeader) {\n      const entries: string[] = [];\n\n      if (config.includeTotal) {\n        entries.push(\n          formatEntry(\"total\", totalMs, precision, config.descriptionFn)\n        );\n      }\n\n      if (selfTimings) {\n        for (const t of selfTimings) {\n          entries.push(\n            formatEntry(t.name, t.durationMs, precision, config.descriptionFn)\n          );\n        }\n      }\n\n      if (entries.length > 0) {\n        c.res.headers.set(\"server-timing\", entries.join(\", \"));\n        debug(\"Server-Timing: %s\", entries.join(\", \"));\n      }\n    }\n\n    // X-Response-Time header\n    if (config.responseTimeHeader) {\n      const value = `${totalMs.toFixed(precision)}ms`;\n      c.res.headers.set(\"x-response-time\", value);\n      debug(\"X-Response-Time: %s\", value);\n    }\n  },\n});\n"],"mappings":"AAeA,SAAS,oBAAoB;AAC7B,SAAS,yBAAyB;AAClC,SAAS,mBAAmB;AAC5B,SAAS,cAAc,kBAAkB,gBAAgB;AA0BzD,SAAS,mBAAmB,MAAsB;AAChD,SAAO,KAAK,QAAQ,mBAAmB,GAAG;AAC5C;AAGA,SAAS,YACP,MACA,YACA,WACA,eACQ;AACR,QAAM,YAAY,mBAAmB,IAAI;AACzC,QAAM,MAAM,WAAW,QAAQ,SAAS;AACxC,QAAM,OAAO,gBAAgB,IAAI;AACjC,MAAI,MAAM;AACR,WAAO,GAAG,SAAS,QAAQ,GAAG,UAAU,kBAAkB,IAAI,CAAC;AAAA,EACjE;AACA,SAAO,GAAG,SAAS,QAAQ,GAAG;AAChC;AAaO,MAAM,eAA6B,6BAAiC;AAAA,EACzE,MAAM;AAAA,EACN,UAAU,SAAS;AAAA,EACnB,UAAU;AAAA,EACV,UAAU;AAAA,IACR,oBAAoB;AAAA,IACpB,oBAAoB;AAAA,IACpB,WAAW;AAAA,IACX,cAAc;AAAA,IACd,YAAY;AAAA,EACd;AAAA,EACA,UAAU,CAAC,WAAW;AACpB,QACE,OAAO,eAAe,iBACtB,OAAO,OAAO,iBAAiB,YAC/B;AACA,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EACA,SAAS,OAAO,GAAG,MAAM,EAAE,QAAQ,MAAM,MAAM;AAC7C,UAAM,YAAY,KAAK,IAAI;AAE3B,UAAM,KAAK;AAGX,QAAI;AACJ,YAAQ,OAAO,YAAY;AAAA,MACzB,KAAK;AACH,kBAAU;AACV;AAAA,MACF,KAAK;AACH,kBAAU,MAAM,OAAO,aAAc,CAAC;AACtC;AAAA,MACF;AACE,kBAAU,iBAAiB,CAAC;AAC5B;AAAA,IACJ;AAEA,QAAI,CAAC,SAAS;AACZ,YAAM,oCAAoC;AAC1C;AAAA,IACF;AAEA,UAAM,UAAU,KAAK,IAAI,IAAI;AAC7B,UAAM,YAAY,OAAO;AAIzB,UAAM,aAAa,EAAE,IAAI,gBAAgB;AAGzC,UAAM,cAAc,aAAa,YAAY,UAAU,IAAI;AAG3D,QAAI,OAAO,oBAAoB;AAC7B,YAAM,UAAoB,CAAC;AAE3B,UAAI,OAAO,cAAc;AACvB,gBAAQ;AAAA,UACN,YAAY,SAAS,SAAS,WAAW,OAAO,aAAa;AAAA,QAC/D;AAAA,MACF;AAEA,UAAI,aAAa;AACf,mBAAW,KAAK,aAAa;AAC3B,kBAAQ;AAAA,YACN,YAAY,EAAE,MAAM,EAAE,YAAY,WAAW,OAAO,aAAa;AAAA,UACnE;AAAA,QACF;AAAA,MACF;AAEA,UAAI,QAAQ,SAAS,GAAG;AACtB,UAAE,IAAI,QAAQ,IAAI,iBAAiB,QAAQ,KAAK,IAAI,CAAC;AACrD,cAAM,qBAAqB,QAAQ,KAAK,IAAI,CAAC;AAAA,MAC/C;AAAA,IACF;AAGA,QAAI,OAAO,oBAAoB;AAC7B,YAAM,QAAQ,GAAG,QAAQ,QAAQ,SAAS,CAAC;AAC3C,QAAE,IAAI,QAAQ,IAAI,mBAAmB,KAAK;AAC1C,YAAM,uBAAuB,KAAK;AAAA,IACpC;AAAA,EACF;AACF,CAAC;","names":[]}

package/dist/policies/proxy.d.ts

@@ -0,0 +1,59 @@
+import { g as PolicyConfig, P as Policy } from '../protocol-2fD3DJrL.js';
+import 'hono';
+import './sdk/trace.js';
+import '@vivero/stoma-core';
+
+/**
+ * Proxy policy - per-route header manipulation and timeout control.
+ *
+ * @module proxy
+ */
+
+interface ProxyPolicyConfig extends PolicyConfig {
+    /** Headers to add to the proxied request */
+    headers?: Record<string, string>;
+    /** Headers to strip from the proxied request */
+    stripHeaders?: string[];
+    /** Timeout in milliseconds. Default: 30000. */
+    timeout?: number;
+    /**
+     * Whether to preserve the inbound Host header when proxying to URL upstreams.
+     * Default: false (Host is rewritten to the upstream target host).
+     */
+    preserveHost?: boolean;
+}
+/**
+ * Apply additional header manipulation and timeout control to the upstream call.
+ *
+ * Use this when you need per-route header injection, header stripping, or
+ * a custom timeout that wraps the upstream dispatch. The core proxy
+ * forwarding (URL, Service Binding, Handler) is handled by the gateway's
+ * upstream handler - this policy layers on top of it.
+ *
+ * `preserveHost` applies to URL upstreams, instructing the upstream handler
+ * not to rewrite the Host header to the target host.
+ *
+ * Handles Cloudflare Workers' immutable `Request.headers` by cloning the
+ * request when header modifications are needed.
+ *
+ * @param config - Headers to add/strip, timeout, and host preservation. All fields optional.
+ * @returns A {@link Policy} at priority 95 (runs late, just before the upstream call).
+ *
+ * @example
+ * ```ts
+ * import { proxy } from "@vivero/stoma/policies";
+ *
+ * // Add an internal auth header and strip cookies for the upstream
+ * proxy({
+ *   headers: { "x-internal-key": "secret-123" },
+ *   stripHeaders: ["cookie", "x-forwarded-for"],
+ *   timeout: 10_000,
+ * });
+ *
+ * // Preserve the original Host header for virtual-host routing
+ * proxy({ preserveHost: true });
+ * ```
+ */
+declare function proxy(config?: ProxyPolicyConfig): Policy;
+
+export { type ProxyPolicyConfig, proxy };

package/dist/policies/proxy.js

@@ -0,0 +1,47 @@
+import { withModifiedHeaders } from "../utils/headers";
+import { Priority, withSkip } from "./sdk";
+function proxy(config) {
+  const timeout = config?.timeout ?? 3e4;
+  const handler = async (c, next) => {
+    if (config?.preserveHost) {
+      c.set("_preserveHost", true);
+    }
+    if (config?.stripHeaders || config?.headers) {
+      const stripHeaders = config?.stripHeaders;
+      const headersToSet = config?.headers;
+      withModifiedHeaders(c, (headers) => {
+        if (stripHeaders) {
+          for (const header of stripHeaders) {
+            headers.delete(header);
+          }
+        }
+        if (headersToSet) {
+          for (const [key, value] of Object.entries(headersToSet)) {
+            headers.set(key, value);
+          }
+        }
+      });
+    }
+    if (timeout > 0) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      try {
+        await next();
+      } finally {
+        clearTimeout(timer);
+      }
+    } else {
+      await next();
+    }
+  };
+  return {
+    name: "proxy",
+    priority: Priority.PROXY,
+    handler: withSkip(config?.skip, handler),
+    httpOnly: true
+  };
+}
+export {
+  proxy
+};
+//# sourceMappingURL=proxy.js.map

package/dist/policies/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/policies/proxy.ts"],"sourcesContent":["/**\n * Proxy policy - per-route header manipulation and timeout control.\n *\n * @module proxy\n */\n\nimport { withModifiedHeaders } from \"../utils/headers\";\nimport { Priority, withSkip } from \"./sdk\";\nimport type { Policy, PolicyConfig } from \"./types\";\n\nexport interface ProxyPolicyConfig extends PolicyConfig {\n  /** Headers to add to the proxied request */\n  headers?: Record<string, string>;\n  /** Headers to strip from the proxied request */\n  stripHeaders?: string[];\n  /** Timeout in milliseconds. Default: 30000. */\n  timeout?: number;\n  /**\n   * Whether to preserve the inbound Host header when proxying to URL upstreams.\n   * Default: false (Host is rewritten to the upstream target host).\n   */\n  preserveHost?: boolean;\n}\n\n/**\n * Apply additional header manipulation and timeout control to the upstream call.\n *\n * Use this when you need per-route header injection, header stripping, or\n * a custom timeout that wraps the upstream dispatch. The core proxy\n * forwarding (URL, Service Binding, Handler) is handled by the gateway's\n * upstream handler - this policy layers on top of it.\n *\n * `preserveHost` applies to URL upstreams, instructing the upstream handler\n * not to rewrite the Host header to the target host.\n *\n * Handles Cloudflare Workers' immutable `Request.headers` by cloning the\n * request when header modifications are needed.\n *\n * @param config - Headers to add/strip, timeout, and host preservation. All fields optional.\n * @returns A {@link Policy} at priority 95 (runs late, just before the upstream call).\n *\n * @example\n * ```ts\n * import { proxy } from \"@vivero/stoma/policies\";\n *\n * // Add an internal auth header and strip cookies for the upstream\n * proxy({\n *   headers: { \"x-internal-key\": \"secret-123\" },\n *   stripHeaders: [\"cookie\", \"x-forwarded-for\"],\n *   timeout: 10_000,\n * });\n *\n * // Preserve the original Host header for virtual-host routing\n * proxy({ preserveHost: true });\n * ```\n */\nexport function proxy(config?: ProxyPolicyConfig): Policy {\n  const timeout = config?.timeout ?? 30_000;\n\n  const handler: import(\"hono\").MiddlewareHandler = async (c, next) => {\n    if (config?.preserveHost) {\n      c.set(\"_preserveHost\", true);\n    }\n\n    // Workers runtime has immutable Request.headers - clone into mutable copy\n    if (config?.stripHeaders || config?.headers) {\n      const stripHeaders = config?.stripHeaders;\n      const headersToSet = config?.headers;\n      withModifiedHeaders(c, (headers) => {\n        if (stripHeaders) {\n          for (const header of stripHeaders) {\n            headers.delete(header);\n          }\n        }\n\n        if (headersToSet) {\n          for (const [key, value] of Object.entries(headersToSet)) {\n            headers.set(key, value);\n          }\n        }\n      });\n    }\n\n    // Apply timeout via AbortSignal\n    if (timeout > 0) {\n      const controller = new AbortController();\n      const timer = setTimeout(() => controller.abort(), timeout);\n      try {\n        await next();\n      } finally {\n        clearTimeout(timer);\n      }\n    } else {\n      await next();\n    }\n  };\n\n  return {\n    name: \"proxy\",\n    priority: Priority.PROXY,\n    handler: withSkip(config?.skip, handler),\n    httpOnly: true,\n  };\n}\n"],"mappings":"AAMA,SAAS,2BAA2B;AACpC,SAAS,UAAU,gBAAgB;AAiD5B,SAAS,MAAM,QAAoC;AACxD,QAAM,UAAU,QAAQ,WAAW;AAEnC,QAAM,UAA4C,OAAO,GAAG,SAAS;AACnE,QAAI,QAAQ,cAAc;AACxB,QAAE,IAAI,iBAAiB,IAAI;AAAA,IAC7B;AAGA,QAAI,QAAQ,gBAAgB,QAAQ,SAAS;AAC3C,YAAM,eAAe,QAAQ;AAC7B,YAAM,eAAe,QAAQ;AAC7B,0BAAoB,GAAG,CAAC,YAAY;AAClC,YAAI,cAAc;AAChB,qBAAW,UAAU,cAAc;AACjC,oBAAQ,OAAO,MAAM;AAAA,UACvB;AAAA,QACF;AAEA,YAAI,cAAc;AAChB,qBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,YAAY,GAAG;AACvD,oBAAQ,IAAI,KAAK,KAAK;AAAA,UACxB;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH;AAGA,QAAI,UAAU,GAAG;AACf,YAAM,aAAa,IAAI,gBAAgB;AACvC,YAAM,QAAQ,WAAW,MAAM,WAAW,MAAM,GAAG,OAAO;AAC1D,UAAI;AACF,cAAM,KAAK;AAAA,MACb,UAAE;AACA,qBAAa,KAAK;AAAA,MACpB;AAAA,IACF,OAAO;AACL,YAAM,KAAK;AAAA,IACb;AAAA,EACF;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU,SAAS;AAAA,IACnB,SAAS,SAAS,QAAQ,MAAM,OAAO;AAAA,IACvC,UAAU;AAAA,EACZ;AACF;","names":[]}

package/dist/policies/resilience/circuit-breaker.d.ts

@@ -0,0 +1,4 @@
+import 'hono';
+export { v as CircuitBreakerConfig, a as CircuitBreakerSnapshot, b as CircuitBreakerStore, c as CircuitState, e as InMemoryCircuitBreakerStore, s as circuitBreaker } from '../../protocol-2fD3DJrL.js';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';