brass-runtime 1.16.0 → 1.16.1

package/dist/chunk-DNFO2EIZ.mjs

@@ -0,0 +1,777 @@
+import {
+  exemplarFromTraceContext,
+  injectTraceContext,
+  logEffect,
+  makeObservability,
+  makeRequestObservabilityContext,
+  normalizeHttpRoute,
+  sanitizeHttpTarget,
+  spanEvent,
+  validateHttpObservabilityOptions,
+  withSpan
+} from "./chunk-MT3OWDPC.mjs";
+import {
+  getHttpRequestPolicy,
+  httpErrorStatus,
+  isRetryableHttpError
+} from "./chunk-PWC3RBQE.mjs";
+import {
+  getCurrentFiber
+} from "./chunk-GYM3LLGS.mjs";
+import {
+  asyncFail,
+  asyncFlatMap,
+  asyncFold,
+  asyncSucceed,
+  asyncSync
+} from "./chunk-36I3M4UC.mjs";
+
+// src/observability/http.ts
+var DEFAULT_DURATION_BUCKETS = [1, 5, 10, 25, 50, 100, 250, 500, 1e3, 2500, 5e3, 1e4];
+var POLICY_LABEL_NAMES = {
+  preset: "policy",
+  lane: "lane",
+  poolKey: "pool_key",
+  dedupKey: "dedup_key",
+  priority: "priority",
+  retry: "retry"
+};
+var HTTP_OBSERVABILITY_CONTRACT = Object.freeze({
+  metrics: Object.freeze({
+    requestsTotal: "brass_http_client_requests_total",
+    durationMs: "brass_http_client_duration_ms",
+    inFlight: "brass_http_client_in_flight",
+    adaptiveLimiterLimit: "brass_http_adaptive_limiter_limit",
+    adaptiveLimiterInFlight: "brass_http_adaptive_limiter_in_flight",
+    adaptiveLimiterQueueDepth: "brass_http_adaptive_limiter_queue_depth",
+    adaptiveLimiterStateCount: "brass_http_adaptive_limiter_state_count",
+    adaptiveLimiterUtilization: "brass_http_adaptive_limiter_utilization",
+    adaptiveLimiterErrorRate: "brass_http_adaptive_limiter_error_rate",
+    adaptiveLimiterRequestsPerSecond: "brass_http_adaptive_limiter_requests_per_second",
+    adaptiveLimiterCompletionsPerSecond: "brass_http_adaptive_limiter_completions_per_second",
+    adaptiveLimiterRejectionRate: "brass_http_adaptive_limiter_rejection_rate"
+  }),
+  labels: Object.freeze({
+    method: "method",
+    host: "host",
+    route: "route",
+    outcome: "outcome",
+    status: "status",
+    adaptiveLimiterKey: "key",
+    lane: "lane",
+    poolKey: "pool_key",
+    dedupKey: "dedup_key",
+    priority: "priority",
+    retry: "retry",
+    policy: "policy"
+  }),
+  spanAttributes: Object.freeze({
+    method: "http.request.method",
+    url: "url.full",
+    route: "http.route",
+    host: "server.address",
+    durationMs: "http.duration_ms",
+    outcome: "http.outcome",
+    statusCode: "http.status_code",
+    retryable: "http.retryable",
+    policyLane: "http.request.policy.lane",
+    policyPreset: "http.request.policy.preset",
+    policyPoolKey: "http.request.policy.pool_key",
+    policyDedupKey: "http.request.policy.dedup_key",
+    policyPriority: "http.request.policy.priority",
+    policyRetry: "http.request.policy.retry"
+  }),
+  logMessages: Object.freeze({
+    request: "http.client.request",
+    response: "http.client.response",
+    error: "http.client.error"
+  }),
+  logFields: Object.freeze({
+    method: "method",
+    url: "url",
+    host: "host",
+    route: "route",
+    status: "status",
+    outcome: "outcome",
+    durationMs: "durationMs",
+    retryable: "retryable",
+    policy: "policy"
+  })
+});
+function withHttpObservability(options) {
+  if (!isObservabilityInstance(options)) {
+    validateHttpObservabilityOptions(options ?? {});
+  }
+  const resolved = resolveHttpObservabilityOptions(options);
+  return (next) => {
+    return (req) => {
+      const run = asyncFlatMap(
+        beginHttpObservation(req, resolved),
+        (state) => asyncFlatMap(
+          logHttpRequest(req, resolved),
+          () => asyncFlatMap(
+            prepareHttpRequest(req, resolved),
+            (wireReq) => asyncFold(
+              next(wireReq),
+              (error) => {
+                const finish = state.finishWithError(error);
+                const adaptiveLimiterAttrs = observeAdaptiveLimiter(wireReq, next, resolved);
+                return asyncFlatMap(
+                  spanEvent("http.client.error", {
+                    ...finish.spanAttributes,
+                    ...adaptiveLimiterAttrs,
+                    "error.type": error._tag
+                  }),
+                  () => asyncFlatMap(logHttpError(req, error, finish, resolved), () => asyncFail(error))
+                );
+              },
+              (res) => {
+                const finish = state.finishWithResponse(res);
+                const adaptiveLimiterAttrs = observeAdaptiveLimiter(wireReq, next, resolved);
+                return asyncFlatMap(
+                  spanEvent("http.client.response", {
+                    ...finish.spanAttributes,
+                    ...adaptiveLimiterAttrs
+                  }),
+                  () => asyncFlatMap(logHttpResponse(req, res, finish, resolved), () => asyncSucceed(res))
+                );
+              }
+            )
+          )
+        )
+      );
+      if (resolved.spans === false) return run;
+      return withSpan(spanName(req, resolved.spans), run, spanStartAttributes(req, resolved));
+    };
+  };
+}
+var makeHttpObservabilityMiddleware = withHttpObservability;
+function beginHttpObservation(req, options) {
+  return asyncSync(() => {
+    const startedAt = options.clock();
+    let finished = false;
+    const inFlight = options.metrics?.gauge("brass_http_client_in_flight", requestBaseLabels(req, options));
+    inFlight?.increment();
+    const finish = (outcome, status, extra = {}) => {
+      const durationMs = Math.max(0, options.clock() - startedAt);
+      const labels = requestFinishLabels(req, outcome, status, options);
+      if (!finished) {
+        finished = true;
+        if (inFlight && inFlight.value() > 0) inFlight.decrement();
+        options.metrics?.counter("brass_http_client_requests_total", labels).increment();
+        options.metrics?.histogram("brass_http_client_duration_ms", [...options.durationBuckets ?? DEFAULT_DURATION_BUCKETS], labels).observe(durationMs, currentTraceExemplar(durationMs, startedAt + durationMs));
+      }
+      return {
+        durationMs,
+        outcome,
+        labels,
+        spanAttributes: {
+          "http.duration_ms": durationMs,
+          "http.outcome": outcome,
+          ...status ? { "http.status_code": Number(status) } : {},
+          ...status ? { "http.response.status_code": Number(status) } : {},
+          ...extra
+        }
+      };
+    };
+    const fiber = getCurrentFiber();
+    fiber?.addFinalizer?.(() => {
+      finish("abort", void 0, { "http.cancelled": true });
+    });
+    return {
+      finishWithResponse: (res) => finish(httpStatusOutcome(res.status), String(res.status)),
+      finishWithError: (error) => {
+        const status = httpErrorStatus(error);
+        return finish(httpErrorOutcome(error), status !== void 0 ? String(status) : void 0, {
+          "error.type": error._tag,
+          "http.retryable": isRetryableHttpError(error)
+        });
+      }
+    };
+  });
+}
+function prepareHttpRequest(req, options) {
+  if (!options.injectTraceHeaders) return asyncSucceed(req);
+  return asyncSync(() => injectCurrentTraceContext(req));
+}
+function logHttpRequest(req, options) {
+  const level = options.logs === false ? false : options.logs.requestLevel ?? false;
+  if (!level) return asyncSucceed(void 0);
+  return logEffect(level, "http.client.request", requestLogFields(req, options));
+}
+function logHttpResponse(req, res, finish, options) {
+  const configured = options.logs === false ? false : options.logs.responseLevel ?? false;
+  const level = configured || (finish.outcome === "error" ? options.logs !== false ? options.logs.errorLevel ?? "warn" : false : false);
+  if (!level) return asyncSucceed(void 0);
+  return logEffect(level, "http.client.response", {
+    ...requestLogFields(req, options),
+    status: res.status,
+    statusText: res.statusText,
+    outcome: finish.outcome,
+    durationMs: finish.durationMs
+  });
+}
+function logHttpError(req, error, finish, options) {
+  const level = options.logs === false ? false : options.logs.errorLevel ?? "error";
+  if (!level) return asyncSucceed(void 0);
+  const status = httpErrorStatus(error);
+  const statusText = httpErrorStatusText(error);
+  return logEffect(level, "http.client.error", {
+    ...requestLogFields(req, options),
+    outcome: finish.outcome,
+    durationMs: finish.durationMs,
+    ...status !== void 0 ? { status } : {},
+    ...statusText ? { statusText } : {},
+    retryable: isRetryableHttpError(error),
+    errorTag: error._tag,
+    message: httpErrorMessage(error)
+  });
+}
+function resolveHttpObservabilityOptions(options) {
+  const maybeObservability = isObservabilityInstance(options) ? options : void 0;
+  const raw = maybeObservability ? { metrics: maybeObservability.metrics } : options;
+  return {
+    metrics: raw?.metrics === false ? void 0 : raw?.metrics,
+    logs: raw?.logs ?? {},
+    spans: raw?.spans ?? {},
+    adaptiveLimiter: resolveAdaptiveLimiterObservabilityOptions(raw?.adaptiveLimiter),
+    policy: resolveHttpPolicyObservabilityOptions(raw?.policy),
+    injectTraceHeaders: raw?.injectTraceHeaders ?? true,
+    includeHostLabel: raw?.includeHostLabel ?? true,
+    route: raw?.route,
+    clock: raw?.clock ?? Date.now,
+    durationBuckets: raw?.durationBuckets
+  };
+}
+function isObservabilityInstance(options) {
+  return Boolean(
+    options && typeof options === "object" && "eventBus" in options && "prometheus" in options
+  );
+}
+function resolveAdaptiveLimiterObservabilityOptions(options) {
+  if (options === false) return { enabled: false, includeKeyLabel: false };
+  if (options === true || options === void 0) return { enabled: true, includeKeyLabel: false };
+  return {
+    enabled: options.enabled ?? true,
+    includeKeyLabel: options.includeKeyLabel ?? false
+  };
+}
+function resolveHttpPolicyObservabilityOptions(options) {
+  if (options === false) return { enabled: false, labelKeys: [] };
+  if (options === true || options === void 0) return { enabled: true, labelKeys: [] };
+  return {
+    enabled: options.enabled ?? true,
+    labelKeys: options.labelKeys ?? []
+  };
+}
+function observeAdaptiveLimiter(req, next, options) {
+  if (!options.adaptiveLimiter.enabled) return {};
+  const limiter = adaptiveLimiterOf(next);
+  if (!limiter || !options.metrics && options.spans === false) return {};
+  const stats = limiter.stats();
+  const labels = adaptiveLimiterLabels(req, stats, options);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_limit", stats.limit, labels);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_in_flight", stats.inFlight, labels);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_queue_depth", stats.queueDepth, labels);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_state_count", stats.stateCount, labels);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_utilization", stats.utilization, labels);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_error_rate", stats.errorRate, labels);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_requests_per_second", stats.requestsPerSecond, labels);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_completions_per_second", stats.completionsPerSecond, labels);
+  setGauge(options.metrics, "brass_http_adaptive_limiter_rejection_rate", stats.rejectionRate, labels);
+  return compactSpanAttributes({
+    "http.adaptive_limiter.limit": stats.limit,
+    "http.adaptive_limiter.in_flight": stats.inFlight,
+    "http.adaptive_limiter.queue_depth": stats.queueDepth,
+    "http.adaptive_limiter.state_count": stats.stateCount,
+    "http.adaptive_limiter.utilization": stats.utilization,
+    "http.adaptive_limiter.error_rate": stats.errorRate,
+    "http.adaptive_limiter.requests_per_second": stats.requestsPerSecond,
+    "http.adaptive_limiter.completions_per_second": stats.completionsPerSecond,
+    "http.adaptive_limiter.rejection_rate": stats.rejectionRate
+  });
+}
+function adaptiveLimiterOf(next) {
+  const limiter = next.adaptiveLimiter;
+  return limiter && typeof limiter.stats === "function" ? limiter : void 0;
+}
+function adaptiveLimiterLabels(req, stats, options) {
+  const key = options.adaptiveLimiter.includeKeyLabel ? inferAdaptiveLimiterKey(req, stats) : void 0;
+  return compactLabels({
+    ...requestBaseLabels(req, options),
+    key
+  });
+}
+function inferAdaptiveLimiterKey(req, stats) {
+  const policy = getHttpRequestPolicy(req);
+  if (policy.poolKey) return policy.poolKey;
+  const host = requestHost(req);
+  if (host) return host;
+  return stats.keys?.length === 1 ? stats.keys[0] : void 0;
+}
+function setGauge(metrics, name, value, labels) {
+  if (!metrics || value === void 0 || !Number.isFinite(value)) return;
+  metrics.gauge(name, labels).set(value);
+}
+function compactSpanAttributes(attrs) {
+  const out = {};
+  for (const [key, value] of Object.entries(attrs)) {
+    if (typeof value === "number") {
+      if (Number.isFinite(value)) out[key] = value;
+    } else if (value !== void 0) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function spanName(req, options) {
+  if (options && options.name) {
+    return typeof options.name === "function" ? options.name(req) : options.name;
+  }
+  return `HTTP ${req.method}`;
+}
+function spanStartAttributes(req, options) {
+  const spanOptions = options.spans === false ? {} : options.spans.attributes;
+  const custom = typeof spanOptions === "function" ? spanOptions(req) : spanOptions ?? {};
+  const host = requestHost(req);
+  const route = requestRoute(req, options);
+  const sanitizedUrl = sanitizeUrl(req.url);
+  const scheme = urlScheme(req.url);
+  const path = urlPath(req.url);
+  return {
+    "span.kind": "client",
+    "http.method": req.method,
+    "http.request.method": req.method,
+    "http.url": sanitizedUrl,
+    "url.full": sanitizedUrl,
+    ...scheme ? { "url.scheme": scheme } : {},
+    ...path ? { "url.path": path } : {},
+    ...host ? { "server.address": host } : {},
+    ...route ? { "http.route": route } : {},
+    ...requestPolicySpanAttributes(req, options),
+    ...custom
+  };
+}
+function requestBaseLabels(req, options) {
+  const route = requestRoute(req, options);
+  return compactLabels({
+    method: req.method,
+    ...options.includeHostLabel ? { host: requestHost(req) } : {},
+    ...route ? { route } : {},
+    ...requestPolicyMetricLabels(req, options)
+  });
+}
+function requestFinishLabels(req, outcome, status, options) {
+  return {
+    ...requestBaseLabels(req, options),
+    outcome,
+    status: status ?? "none"
+  };
+}
+function requestLogFields(req, options) {
+  const host = requestHost(req);
+  const route = requestRoute(req, options);
+  const policy = requestPolicyLogFields(req, options);
+  return {
+    method: req.method,
+    url: sanitizeUrl(req.url),
+    ...host ? { host } : {},
+    ...route ? { route } : {},
+    ...policy ? { policy } : {}
+  };
+}
+function requestPolicyLogFields(req, options) {
+  if (!options.policy.enabled) return void 0;
+  const policy = getHttpRequestPolicy(req);
+  const fields = {
+    ...policy.preset ? { preset: policy.preset } : {},
+    ...policy.lane ? { lane: policy.lane } : {},
+    ...policy.poolKey ? { poolKey: policy.poolKey } : {},
+    ...policy.dedupKey ? { dedupKey: policy.dedupKey } : {},
+    ...policy.priority !== void 0 ? { priority: policy.priority } : {},
+    ...policy.retry !== void 0 ? { retry: retryPolicyLogValue(policy.retry) } : {}
+  };
+  return Object.keys(fields).length > 0 ? fields : void 0;
+}
+function requestPolicySpanAttributes(req, options) {
+  if (!options.policy.enabled) return {};
+  const policy = getHttpRequestPolicy(req);
+  return {
+    ...compactSpanAttributes({
+      "http.request.policy.lane": policy.lane,
+      "http.request.policy.preset": policy.preset,
+      "http.request.policy.pool_key": policy.poolKey,
+      "http.request.policy.dedup_key": policy.dedupKey,
+      "http.request.policy.priority": policy.priority
+    }),
+    ...retryPolicySpanAttributes(policy.retry)
+  };
+}
+function requestPolicyMetricLabels(req, options) {
+  if (!options.policy.enabled || options.policy.labelKeys.length === 0) return {};
+  const policy = getHttpRequestPolicy(req);
+  const values = {
+    preset: policy.preset,
+    lane: policy.lane,
+    poolKey: policy.poolKey,
+    dedupKey: policy.dedupKey,
+    priority: policy.priority !== void 0 ? String(policy.priority) : void 0,
+    retry: retryPolicyMetricValue(policy.retry)
+  };
+  const labels = {};
+  for (const key of options.policy.labelKeys) {
+    labels[POLICY_LABEL_NAMES[key]] = values[key];
+  }
+  return compactLabels(labels);
+}
+function retryPolicyLogValue(retry) {
+  if (retry === false) return "disabled";
+  return {
+    mode: "override",
+    ...retry.maxRetries !== void 0 ? { maxRetries: retry.maxRetries } : {},
+    ...retry.baseDelayMs !== void 0 ? { baseDelayMs: retry.baseDelayMs } : {},
+    ...retry.maxDelayMs !== void 0 ? { maxDelayMs: retry.maxDelayMs } : {},
+    ...retry.schedule ? { schedule: "custom" } : {},
+    ...retry.retryOnStatus ? { retryOnStatus: "custom" } : {}
+  };
+}
+function retryPolicySpanAttributes(retry) {
+  if (retry === void 0) return {};
+  if (retry === false) return { "http.request.policy.retry": "disabled" };
+  return compactSpanAttributes({
+    "http.request.policy.retry": "override",
+    "http.request.policy.retry.max_retries": retry.maxRetries,
+    "http.request.policy.retry.base_delay_ms": retry.baseDelayMs,
+    "http.request.policy.retry.max_delay_ms": retry.maxDelayMs,
+    "http.request.policy.retry.custom_schedule": retry.schedule ? true : void 0,
+    "http.request.policy.retry.custom_status": retry.retryOnStatus ? true : void 0
+  });
+}
+function retryPolicyMetricValue(retry) {
+  if (retry === void 0) return void 0;
+  return retry === false ? "disabled" : "override";
+}
+function requestRoute(req, options) {
+  if (typeof options.route === "function") return options.route(req);
+  return options.route;
+}
+function httpStatusOutcome(status) {
+  return status >= 400 ? "error" : "success";
+}
+function httpErrorOutcome(error) {
+  switch (error._tag) {
+    case "Abort":
+      return "abort";
+    case "BadUrl":
+      return "bad_url";
+    case "FetchError":
+      return "fetch_error";
+    case "Timeout":
+      return "timeout";
+    case "PoolRejected":
+      return "pool_rejected";
+    case "PoolTimeout":
+      return "pool_timeout";
+    case "PoolClosed":
+      return "pool_closed";
+    case "BatchSplitError":
+      return "batch_split_error";
+  }
+}
+function httpErrorMessage(error) {
+  return "message" in error ? error.message : void 0;
+}
+function httpErrorStatusText(error) {
+  return error._tag === "FetchError" ? error.statusText : void 0;
+}
+function injectCurrentTraceContext(req) {
+  const fiber = getCurrentFiber();
+  const trace = fiber?.fiberContext?.trace;
+  if (!trace?.traceId || !trace?.spanId) return req;
+  return {
+    ...req,
+    headers: injectTraceContext(req.headers, trace)
+  };
+}
+function currentTraceExemplar(value, timestamp) {
+  const fiber = getCurrentFiber();
+  return exemplarFromTraceContext(fiber?.fiberContext?.trace, value, timestamp);
+}
+function requestHost(req) {
+  if (!isAbsoluteUrl(req.url)) return void 0;
+  try {
+    return new URL(req.url).host;
+  } catch {
+    return void 0;
+  }
+}
+function urlScheme(url) {
+  if (url.startsWith("https://")) return "https";
+  if (url.startsWith("http://")) return "http";
+  if (!isAbsoluteUrl(url)) return void 0;
+  try {
+    return new URL(url).protocol.replace(/:$/, "");
+  } catch {
+    return void 0;
+  }
+}
+function urlPath(url) {
+  if (!isAbsoluteUrl(url)) {
+    const path = stripQueryAndHash(url);
+    return path.startsWith("/") ? path : void 0;
+  }
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return void 0;
+  }
+}
+function sanitizeUrl(url) {
+  if (!isAbsoluteUrl(url)) return stripQueryAndHash(url);
+  try {
+    const parsed = new URL(url);
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    const [withoutHash] = url.split("#", 1);
+    const [withoutQuery] = withoutHash.split("?", 1);
+    return withoutQuery;
+  }
+}
+function isAbsoluteUrl(url) {
+  const schemeIdx = url.indexOf("://");
+  if (schemeIdx <= 0) return false;
+  const firstSlash = url.indexOf("/");
+  return firstSlash === -1 || schemeIdx < firstSlash;
+}
+function stripQueryAndHash(url) {
+  const hashIdx = url.indexOf("#");
+  const queryIdx = url.indexOf("?");
+  let end = url.length;
+  if (hashIdx >= 0) end = Math.min(end, hashIdx);
+  if (queryIdx >= 0) end = Math.min(end, queryIdx);
+  return url.slice(0, end);
+}
+function compactLabels(labels) {
+  const out = {};
+  for (const [key, value] of Object.entries(labels)) {
+    if (value !== void 0 && value !== "") out[key] = value;
+  }
+  return out;
+}
+
+// src/observability/adapters.ts
+function makeFetchRequestObservabilityContext(observability, request, input = {}) {
+  return makeRequestObservabilityContext(observability, {
+    headers: request.headers,
+    method: request.method,
+    target: sanitizeHttpTarget(request.url),
+    route: input.route ?? normalizeHttpRoute(urlPathname(request.url)),
+    ...input
+  });
+}
+function makeNodeRequestObservabilityContext(observability, request, input = {}) {
+  return makeRequestObservabilityContext(observability, {
+    headers: request.headers,
+    method: request.method,
+    target: sanitizeHttpTarget(request.url),
+    route: input.route ?? normalizeHttpRoute(request.url),
+    ...input
+  });
+}
+function makeExpressRequestObservabilityContext(observability, request, input = {}) {
+  return makeRequestObservabilityContext(observability, {
+    headers: request.headers,
+    method: request.method,
+    target: sanitizeHttpTarget(request.originalUrl ?? request.url),
+    route: input.route ?? request.route?.path ?? normalizeHttpRoute(request.path ?? request.url),
+    ...input
+  });
+}
+function makeFastifyRequestObservabilityContext(observability, request, input = {}) {
+  return makeRequestObservabilityContext(observability, {
+    headers: request.headers,
+    method: request.method,
+    target: sanitizeHttpTarget(request.url),
+    route: input.route ?? request.routeOptions?.url ?? request.routerPath ?? normalizeHttpRoute(request.url),
+    ...input
+  });
+}
+function withFetchRequestObservability(observability, handler, input = {}) {
+  return async (request) => handler(makeFetchRequestObservabilityContext(observability, request, input), request);
+}
+function withNodeRequestObservability(observability, handler, input = {}) {
+  return async (request) => handler(makeNodeRequestObservabilityContext(observability, request, input), request);
+}
+function urlPathname(url) {
+  if (!url) return void 0;
+  try {
+    return new URL(url, "http://local").pathname;
+  } catch {
+    return url;
+  }
+}
+
+// src/observability/config.ts
+function makeNoopObservability() {
+  return makeObservability({
+    metrics: false,
+    logs: false,
+    traces: false,
+    autoStart: false
+  });
+}
+function makeObservabilityPreset(preset, overrides = {}) {
+  if (preset === "disabled") return makeNoopObservability();
+  return makeObservability(mergeObservabilityOptions(observabilityOptionsForPreset(preset), overrides));
+}
+function makeObservabilityFromEnv(env = readProcessEnv(), overrides = {}) {
+  const preset = env.BRASS_OBSERVABILITY === "disabled" ? "disabled" : parsePreset(env.BRASS_OBSERVABILITY_PRESET ?? env.NODE_ENV);
+  if (preset === "disabled") return makeNoopObservability();
+  return makeObservability(mergeObservabilityOptions(observabilityOptionsFromEnv(env, preset), overrides));
+}
+function observabilityOptionsForPreset(preset) {
+  switch (preset) {
+    case "production":
+      return {
+        logs: { minLevel: "info" },
+        sampling: { ratio: 1, respectRemoteSampled: true, forceSampleOnError: true },
+        redaction: {},
+        cardinality: { maxValuesPerLabel: 100 },
+        otlp: {
+          timeoutMs: 1e4,
+          retry: { attempts: 3, initialDelayMs: 100, maxDelayMs: 2e3 },
+          pipeline: {
+            maxQueueSize: 1e4,
+            batchSize: 512,
+            dropPolicy: "drop-oldest",
+            shutdownTimeoutMs: 1e4
+          }
+        },
+        flushIntervalMs: 1e4,
+        autoStart: true
+      };
+    case "test":
+      return {
+        logs: false,
+        sampling: 1,
+        redaction: {},
+        otlp: {
+          timeoutMs: 1e3,
+          retry: { attempts: 1 },
+          pipeline: { maxQueueSize: 1e3, batchSize: 256, shutdownTimeoutMs: 1e3 }
+        },
+        autoStart: false
+      };
+    case "development":
+      return {
+        logs: { minLevel: "debug" },
+        sampling: 1,
+        redaction: {},
+        cardinality: { maxValuesPerLabel: 100 },
+        autoStart: false
+      };
+  }
+}
+function observabilityOptionsFromEnv(env = readProcessEnv(), preset = parsePreset(env.BRASS_OBSERVABILITY_PRESET ?? env.NODE_ENV)) {
+  const base = observabilityOptionsForPreset(preset);
+  const serviceName = env.OTEL_SERVICE_NAME ?? env.BRASS_SERVICE_NAME;
+  const serviceVersion = env.OTEL_SERVICE_VERSION ?? env.BRASS_SERVICE_VERSION;
+  const endpoint = trimTrailingSlash(env.OTEL_EXPORTER_OTLP_ENDPOINT);
+  const metricsUrl = env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT ?? (endpoint ? `${endpoint}/v1/metrics` : void 0);
+  const tracesUrl = env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? (endpoint ? `${endpoint}/v1/traces` : void 0);
+  const logsUrl = env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT ?? (endpoint ? `${endpoint}/v1/logs` : void 0);
+  const headers = parseHeaders(env.OTEL_EXPORTER_OTLP_HEADERS);
+  const flushIntervalMs = parsePositiveInt(env.BRASS_OBSERVABILITY_FLUSH_INTERVAL_MS);
+  const timeoutMs = parsePositiveInt(env.BRASS_OBSERVABILITY_EXPORT_TIMEOUT_MS);
+  const sampleRatio = parseRatio(env.BRASS_TRACE_SAMPLE_RATIO ?? env.OTEL_TRACES_SAMPLER_ARG);
+  const minLevel = env.BRASS_OBSERVABILITY_LOG_LEVEL;
+  const otlp = {
+    ...base.otlp ?? {},
+    ...metricsUrl ? { metricsUrl } : {},
+    ...tracesUrl ? { tracesUrl } : {},
+    ...logsUrl ? { logsUrl } : {},
+    ...headers ? { headers } : {},
+    ...timeoutMs ? { timeoutMs } : {}
+  };
+  return mergeObservabilityOptions(base, {
+    ...serviceName ? { serviceName } : {},
+    ...serviceVersion ? { serviceVersion } : {},
+    ...Object.keys(otlp).length > 0 ? { otlp } : {},
+    ...flushIntervalMs ? { flushIntervalMs, autoStart: true } : {},
+    ...sampleRatio !== void 0 ? { sampling: { ratio: sampleRatio, respectRemoteSampled: true, forceSampleOnError: true } } : {},
+    ...minLevel === "debug" || minLevel === "info" || minLevel === "warn" || minLevel === "error" ? { logs: { minLevel } } : {}
+  });
+}
+function mergeObservabilityOptions(base, overrides) {
+  return {
+    ...base,
+    ...overrides,
+    metrics: overrides.metrics ?? base.metrics,
+    logs: overrides.logs ?? base.logs,
+    otlp: {
+      ...base.otlp ?? {},
+      ...overrides.otlp ?? {},
+      retry: overrides.otlp?.retry ?? base.otlp?.retry,
+      pipeline: {
+        ...base.otlp?.pipeline ?? {},
+        ...overrides.otlp?.pipeline ?? {}
+      }
+    }
+  };
+}
+function parsePreset(value) {
+  if (value === "production" || value === "prod") return "production";
+  if (value === "test") return "test";
+  return "development";
+}
+function parseHeaders(value) {
+  if (!value) return void 0;
+  const out = {};
+  for (const part of value.split(",")) {
+    const index = part.indexOf("=");
+    if (index <= 0) continue;
+    const key = part.slice(0, index).trim();
+    const headerValue = part.slice(index + 1).trim();
+    if (key) out[key] = headerValue;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function parsePositiveInt(value) {
+  if (!value) return void 0;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+function parseRatio(value) {
+  if (!value) return void 0;
+  const parsed = Number.parseFloat(value);
+  if (!Number.isFinite(parsed)) return void 0;
+  return Math.max(0, Math.min(1, parsed));
+}
+function trimTrailingSlash(value) {
+  if (!value) return void 0;
+  let out = value;
+  while (out.endsWith("/")) out = out.slice(0, -1);
+  return out || void 0;
+}
+function readProcessEnv() {
+  return typeof process !== "undefined" ? process.env : {};
+}
+
+export {
+  HTTP_OBSERVABILITY_CONTRACT,
+  withHttpObservability,
+  makeHttpObservabilityMiddleware,
+  makeFetchRequestObservabilityContext,
+  makeNodeRequestObservabilityContext,
+  makeExpressRequestObservabilityContext,
+  makeFastifyRequestObservabilityContext,
+  withFetchRequestObservability,
+  withNodeRequestObservability,
+  makeNoopObservability,
+  makeObservabilityPreset,
+  makeObservabilityFromEnv,
+  observabilityOptionsForPreset,
+  observabilityOptionsFromEnv
+};