@warpgogol/werkstatt-shared 0.2.0

package/src/observability/metric-registry.ts

@@ -0,0 +1,184 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Closed metric catalog for the Warpgogol observability port (RFC-0337). Every metric emitted anywhere in the ecosystem MUST be declared here.</purpose>
+<non-goals>
+  <item>Do not import node: modules — must be Workers-compatible.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0337: initial implementation with smoke metric only. RFC-0340/0341/0343 append entries.</item>
+  <item>RFC-0807: add back prefix metrics for service health monitoring.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type WarpgogolMetricKind = "counter" | "gauge" | "histogram";
+
+export interface WarpgogolMetricSpec {
+  name: string;
+  kind: WarpgogolMetricKind;
+  help: string;
+  labelKeys: readonly string[];
+  unit?: string;
+  buckets?: readonly number[];
+}
+
+export const METRIC_NAME_PATTERN = /^warpgogol_(factory|probe|delivery|workers|back)_[a-z0-9_]+$/;
+
+export const FORBIDDEN_LABEL_KEYS: readonly string[] = [
+  "user_id",
+  "session_id",
+  "request_id",
+  "run_id",
+  "url",
+  "path",
+  "email",
+];
+
+export const WARPGOGOL_METRIC_REGISTRY: readonly WarpgogolMetricSpec[] = [
+  {
+    name: "warpgogol_factory_smoke_total",
+    kind: "counter",
+    help: "Smoke-test counter emitted by observability.factory.smoke to verify the OTLP pipe end-to-end (RFC-0340).",
+    labelKeys: [],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_factory_command_runs_total",
+    kind: "counter",
+    help: "Total kernel command executions by command name and outcome (RFC-0340).",
+    labelKeys: ["command", "status", "site_id"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_factory_command_duration_seconds",
+    kind: "histogram",
+    help: "Kernel command execution duration in seconds (RFC-0340).",
+    labelKeys: ["command", "site_id"],
+    unit: "s",
+    buckets: [0.5, 1, 2, 5, 10, 30, 60, 120, 300, 600],
+  },
+  {
+    name: "warpgogol_factory_diagnostics_total",
+    kind: "counter",
+    help: "Total diagnostics emitted by kernel commands by severity (RFC-0340).",
+    labelKeys: ["command", "severity", "site_id"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_probe_up",
+    kind: "gauge",
+    help: "1 = site route is up (status 2xx/3xx AND sentinel ok); else 0 (RFC-0341).",
+    labelKeys: ["site_id", "route"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_probe_ttfb_seconds",
+    kind: "gauge",
+    help: "Last observed time-to-first-byte in seconds (RFC-0341).",
+    labelKeys: ["site_id", "route"],
+    unit: "s",
+  },
+  {
+    name: "warpgogol_probe_http_status_class_total",
+    kind: "counter",
+    help: "Total probe requests by HTTP status class (RFC-0341).",
+    labelKeys: ["site_id", "route", "status_class"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_probe_content_ok",
+    kind: "gauge",
+    help: "1 = content sentinel matched; 0 = sentinel failed (RFC-0341).",
+    labelKeys: ["site_id", "route"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_probe_cert_expiry_days",
+    kind: "gauge",
+    help: "Days until TLS certificate expiry (RFC-0341).",
+    labelKeys: ["site_id"],
+    unit: "d",
+  },
+  {
+    name: "warpgogol_probe_deep_ok",
+    kind: "gauge",
+    help: "Phase 2 deep probe result: 1 = ok, 0 = failed (RFC-0341 Phase 2).",
+    labelKeys: ["site_id"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_delivery_requests_total",
+    kind: "counter",
+    help: "Total HTTP requests served by Cloudflare per site, cache status, and status class (RFC-0343).",
+    labelKeys: ["site_id", "cache_status", "status_class"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_delivery_bytes_total",
+    kind: "counter",
+    help: "Total bytes served by Cloudflare per site (RFC-0343).",
+    labelKeys: ["site_id"],
+    unit: "By",
+  },
+  {
+    name: "warpgogol_workers_requests_total",
+    kind: "counter",
+    help: "Total Cloudflare Worker invocations per site (RFC-0343).",
+    labelKeys: ["site_id"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_workers_errors_total",
+    kind: "counter",
+    help: "Total Cloudflare Worker errors per site (RFC-0343).",
+    labelKeys: ["site_id"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_back_requests_total",
+    kind: "counter",
+    help: "Total HTTP requests served by backend services (RFC-0807).",
+    labelKeys: ["service", "status_class"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_back_up",
+    kind: "gauge",
+    help: "1 = service self-reports healthy; 0 = unhealthy (RFC-0807).",
+    labelKeys: ["service"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_back_last_run_total",
+    kind: "counter",
+    help: "Total scheduled runs by outcome (success/failure) (RFC-0807).",
+    labelKeys: ["service", "status"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_back_last_error_total",
+    kind: "counter",
+    help: "Total errors encountered by the service (RFC-0807).",
+    labelKeys: ["service"],
+    unit: "1",
+  },
+  {
+    name: "warpgogol_back_queue_depth",
+    kind: "gauge",
+    help: "Current queue depth (items pending processing) (RFC-0807).",
+    labelKeys: ["service"],
+    unit: "1",
+  },
+];
+
+export function findMetricSpec(name: string): WarpgogolMetricSpec | undefined {
+  return WARPGOGOL_METRIC_REGISTRY.find((spec) => spec.name === name);
+}
+
+export function isMetricNameValid(name: string): boolean {
+  return METRIC_NAME_PATTERN.test(name);
+}
+
+export function isLabelKeyForbidden(key: string): boolean {
+  return FORBIDDEN_LABEL_KEYS.includes(key);
+}

package/src/observability/otlp-converter.ts

@@ -0,0 +1,125 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Pure conversion from accumulated metric points to OTLP metric points (RFC-0337). Extracted from pusher.ts for testability without HTTP I/O.</purpose>
+<non-goals>
+  <item>Do not import node: modules — must be Workers-compatible.</item>
+  <item>Do not perform HTTP — that lives in pusher.ts.</item>
+  <item>Do not validate metric names/labels — pusher.ts validates at accumulation time.</item>
+</non-goals>
+@ai-invariant: Histogram bucket boundaries are inclusive — a value exactly on a bound goes into the lower bucket (value <= bounds[i]).
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Extract pure OTLP conversion pipeline from pusher.ts flush() for interface-level testability.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { findMetricSpec } from "./metric-registry.ts";
+import {
+  nowUnixNano,
+  type OtlpGaugePoint,
+  type OtlpHistogramPoint,
+  type OtlpMetricPoint,
+  type OtlpSumPoint,
+  type UnixNanoString,
+} from "./otlp-json.ts";
+import type { OtlpKeyValue } from "./conventions.ts";
+
+export interface AccumulatedPoint {
+  name: string;
+  labels: Record<string, string>;
+  value: number;
+  kind: "counter" | "gauge" | "histogram";
+}
+
+function labelsToAttributes(labels: Record<string, string>): OtlpKeyValue[] {
+  return Object.entries(labels).map(([key, value]) => ({
+    key,
+    value: { stringValue: value },
+  }));
+}
+
+export function convertAccumulatedToOtlp(
+  points: readonly AccumulatedPoint[],
+  startTimeNano: UnixNanoString,
+): OtlpMetricPoint[] {
+  const byName = new Map<string, AccumulatedPoint[]>();
+  for (const pt of points) {
+    const existing = byName.get(pt.name);
+    if (existing) {
+      existing.push(pt);
+    } else {
+      byName.set(pt.name, [pt]);
+    }
+  }
+
+  const otlpPoints: OtlpMetricPoint[] = [];
+
+  for (const [name, group] of byName) {
+    const spec = findMetricSpec(name);
+    if (!spec) continue;
+
+    if (spec.kind === "counter") {
+      const sumPoints: OtlpSumPoint[] = group.map((pt) => ({
+        asDouble: pt.value,
+        startTimeUnixNano: startTimeNano,
+        timeUnixNano: nowUnixNano(),
+        attributes: labelsToAttributes(pt.labels),
+      }));
+      otlpPoints.push({
+        name,
+        kind: "sum",
+        unit: spec.unit,
+        isMonotonic: true,
+        sumPoints,
+      });
+    } else if (spec.kind === "gauge") {
+      const gaugePoints: OtlpGaugePoint[] = group.map((pt) => ({
+        asDouble: pt.value,
+        timeUnixNano: nowUnixNano(),
+        attributes: labelsToAttributes(pt.labels),
+      }));
+      otlpPoints.push({
+        name,
+        kind: "gauge",
+        unit: spec.unit,
+        gaugePoints,
+      });
+    } else if (spec.kind === "histogram") {
+      const bounds = spec.buckets ?? [];
+      const bucketCounts = new Array(bounds.length + 1).fill(0) as number[];
+      let sum = 0;
+      for (const pt of group) {
+        sum += pt.value;
+        let placed = false;
+        for (let i = 0; i < bounds.length; i++) {
+          if (pt.value <= bounds[i]!) {
+            bucketCounts[i]!++;
+            placed = true;
+            break;
+          }
+        }
+        if (!placed) {
+          bucketCounts[bucketCounts.length - 1]!++;
+        }
+      }
+      const histogramPoints: OtlpHistogramPoint[] = [
+        {
+          startTimeUnixNano: startTimeNano,
+          timeUnixNano: nowUnixNano() as UnixNanoString,
+          count: String(group.length),
+          sum,
+          bucketCounts: bucketCounts.map(String),
+          explicitBounds: [...bounds],
+        },
+      ];
+      otlpPoints.push({
+        name,
+        kind: "histogram",
+        unit: spec.unit,
+        histogramPoints,
+      });
+    }
+  }
+
+  return otlpPoints;
+}

package/src/observability/otlp-json.ts

@@ -0,0 +1,135 @@
+/*
+<MODULE_CONTRACT>
+<purpose>OTLP/HTTP JSON envelope encoding for metrics (RFC-0337). Produces the exact wire format consumed by SigNoz.</purpose>
+<non-goals>
+  <item>Do not import node: modules — must be Workers-compatible.</item>
+  <item>Do not perform HTTP — that lives in pusher.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0337: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { OtlpKeyValue } from "./conventions.ts";
+
+export type UnixNanoString = string;
+
+export function nowUnixNano(): UnixNanoString {
+  return String(Date.now() * 1_000_000);
+}
+
+export interface OtlpGaugePoint {
+  asDouble: number;
+  timeUnixNano: UnixNanoString;
+  attributes?: OtlpKeyValue[];
+}
+
+export interface OtlpSumPoint {
+  asDouble: number;
+  startTimeUnixNano: UnixNanoString;
+  timeUnixNano: UnixNanoString;
+  attributes?: OtlpKeyValue[];
+}
+
+export interface OtlpHistogramPoint {
+  startTimeUnixNano: UnixNanoString;
+  timeUnixNano: UnixNanoString;
+  count: string;
+  sum: number;
+  bucketCounts: string[];
+  explicitBounds: number[];
+  attributes?: OtlpKeyValue[];
+}
+
+export interface OtlpMetricPoint {
+  name: string;
+  kind: "gauge" | "sum" | "histogram";
+  unit?: string;
+  isMonotonic?: boolean;
+  gaugePoints?: OtlpGaugePoint[];
+  sumPoints?: OtlpSumPoint[];
+  histogramPoints?: OtlpHistogramPoint[];
+  buckets?: readonly number[];
+}
+
+export interface OtlpMetricsEnvelope {
+  resourceMetrics: Array<{
+    resource: { attributes: OtlpKeyValue[] };
+    scopeMetrics: Array<{
+      scope: { name: string; version: string };
+      metrics: unknown[];
+    }>;
+  }>;
+}
+
+export function encodeOtlpMetrics(
+  resourceAttributes: OtlpKeyValue[],
+  points: OtlpMetricPoint[],
+  scopeName: string,
+  scopeVersion: string,
+): OtlpMetricsEnvelope {
+  const metrics: unknown[] = [];
+
+  for (const point of points) {
+    if (point.kind === "gauge" && point.gaugePoints) {
+      metrics.push({
+        name: point.name,
+        ...(point.unit ? { unit: point.unit } : {}),
+        gauge: {
+          dataPoints: point.gaugePoints.map((dp) => ({
+            asDouble: dp.asDouble,
+            timeUnixNano: dp.timeUnixNano,
+            ...(dp.attributes ? { attributes: dp.attributes } : {}),
+          })),
+        },
+      });
+    } else if (point.kind === "sum" && point.sumPoints) {
+      metrics.push({
+        name: point.name,
+        ...(point.unit ? { unit: point.unit } : {}),
+        sum: {
+          aggregationTemporality: 1,
+          isMonotonic: point.isMonotonic ?? true,
+          dataPoints: point.sumPoints.map((dp) => ({
+            asDouble: dp.asDouble,
+            startTimeUnixNano: dp.startTimeUnixNano,
+            timeUnixNano: dp.timeUnixNano,
+            ...(dp.attributes ? { attributes: dp.attributes } : {}),
+          })),
+        },
+      });
+    } else if (point.kind === "histogram" && point.histogramPoints) {
+      metrics.push({
+        name: point.name,
+        ...(point.unit ? { unit: point.unit } : {}),
+        histogram: {
+          aggregationTemporality: 1,
+          dataPoints: point.histogramPoints.map((dp) => ({
+            startTimeUnixNano: dp.startTimeUnixNano,
+            timeUnixNano: dp.timeUnixNano,
+            count: dp.count,
+            sum: dp.sum,
+            bucketCounts: dp.bucketCounts,
+            explicitBounds: dp.explicitBounds,
+            ...(dp.attributes ? { attributes: dp.attributes } : {}),
+          })),
+        },
+      });
+    }
+  }
+
+  return {
+    resourceMetrics: [
+      {
+        resource: { attributes: resourceAttributes },
+        scopeMetrics: [
+          {
+            scope: { name: scopeName, version: scopeVersion },
+            metrics,
+          },
+        ],
+      },
+    ],
+  };
+}

package/src/observability/otlp-transport.ts

@@ -0,0 +1,68 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  OTLP transport port — abstracts the HTTP POST delivery of OTLP JSON.
+  Extracted from pusher.ts so the transport can be mocked in tests
+  without touching the network.
+</purpose>
+<non-goals>
+  <item>Do not accumulate or convert metrics — that stays in pusher.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Architecture review 2026-07-14: extract OtlpTransport port from pusher.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface OtlpTransport {
+  send(body: string, signal?: AbortSignal): Promise<{ delivered: boolean; reason?: string }>;
+}
+
+export interface OtlpHttpTransportOptions {
+  endpoint: string;
+  token: string;
+  timeoutMs?: number;
+}
+
+export function createOtlpHttpTransport(options: OtlpHttpTransportOptions): OtlpTransport {
+  const url = `${options.endpoint.replace(/\/$/, "")}/v1/metrics`;
+  const timeoutMs = options.timeoutMs ?? 2000;
+
+  return {
+    async send(body, signal) {
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+        // If caller provided a signal, link it
+        if (signal) {
+          signal.addEventListener("abort", () => controller.abort(), { once: true });
+        }
+
+        try {
+          const response = await fetch(url, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${options.token}`,
+            },
+            body,
+            signal: controller.signal,
+          });
+          if (!response.ok) {
+            return {
+              delivered: false,
+              reason: `HTTP ${response.status} ${response.statusText}`,
+            };
+          }
+          return { delivered: true };
+        } finally {
+          clearTimeout(timer);
+        }
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { delivered: false, reason };
+      }
+    },
+  };
+}

package/src/observability/pusher.ts

@@ -0,0 +1,142 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Minimal OTLP/HTTP JSON push client for metrics (RFC-0337). Zero-dependency, Workers-compatible, fire-and-forget.</purpose>
+<non-goals>
+  <item>Do not import node: modules — must be Workers-compatible.</item>
+  <item>Do not retry — one flush = at most one HTTP request.</item>
+  <item>Do not throw from flush — always resolve with delivery status.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0337: initial implementation.</item>
+  <item>Deepening: extract OTLP conversion to otlp-converter.ts pure function.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { buildResourceAttributes, type WarpgogolResourceInput } from "./conventions.ts";
+import { findMetricSpec, isLabelKeyForbidden, isMetricNameValid } from "./metric-registry.ts";
+import { encodeOtlpMetrics, nowUnixNano } from "./otlp-json.ts";
+import { convertAccumulatedToOtlp, type AccumulatedPoint } from "./otlp-converter.ts";
+import type { OtlpTransport } from "./otlp-transport.ts";
+import { createOtlpHttpTransport } from "./otlp-transport.ts";
+import type { MetricsPusherEnv } from "./env-resolver.ts";
+import { resolvePusherEnv, detectEnvironment } from "./env-resolver.ts";
+
+export type { MetricsPusherEnv } from "./env-resolver.ts";
+
+export interface MetricsPusher {
+  counterAdd(name: string, value: number, labels?: Record<string, string>): void;
+  gaugeSet(name: string, value: number, labels?: Record<string, string>): void;
+  histogramRecord(name: string, value: number, labels?: Record<string, string>): void;
+  flush(): Promise<{ delivered: boolean; reason?: string }>;
+}
+
+const SCOPE_NAME = "@warpgogol/werkstatt-shared/observability";
+const SCOPE_VERSION = "1";
+const DEFAULT_TIMEOUT_MS = 2000;
+
+export function createMetricsPusher(
+  resource: WarpgogolResourceInput,
+  env?: MetricsPusherEnv,
+  options?: { timeoutMs?: number },
+): MetricsPusher | null {
+  const resolved = resolvePusherEnv(env);
+  if (!resolved.endpoint || !resolved.token) {
+    return null;
+  }
+
+  const endpoint = resolved.endpoint;
+  const token = resolved.token;
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const environment = resource.environment ?? detectEnvironment();
+  const layer = resource.layer;
+
+  const resourceInput: WarpgogolResourceInput = {
+    ...resource,
+    environment,
+    layer,
+  };
+
+  const points: AccumulatedPoint[] = [];
+  const startTimeNano = nowUnixNano();
+  let _droppedCount = 0;
+
+  const isStrict = environment === "development" || environment === "ci";
+
+  function validateMetric(name: string, labels: Record<string, string>): void {
+    if (!isMetricNameValid(name)) {
+      const msg = `[observability] metric name "${name}" does not match the naming grammar`;
+      if (isStrict) throw new Error(msg);
+      _droppedCount++;
+      return;
+    }
+    const spec = findMetricSpec(name);
+    if (!spec) {
+      const msg = `[observability] metric name "${name}" is not declared in WARPGOGOL_METRIC_REGISTRY`;
+      if (isStrict) throw new Error(msg);
+      _droppedCount++;
+      return;
+    }
+    for (const key of Object.keys(labels)) {
+      if (isLabelKeyForbidden(key)) {
+        const msg = `[observability] label key "${key}" is forbidden for metric "${name}"`;
+        if (isStrict) throw new Error(msg);
+        _droppedCount++;
+        return;
+      }
+      if (!spec.labelKeys.includes(key)) {
+        const msg = `[observability] label key "${key}" is not declared for metric "${name}"`;
+        if (isStrict) throw new Error(msg);
+        _droppedCount++;
+        return;
+      }
+    }
+  }
+
+  function addPoint(
+    name: string,
+    value: number,
+    labels: Record<string, string>,
+    kind: AccumulatedPoint["kind"],
+  ): void {
+    try {
+      validateMetric(name, labels);
+    } catch {
+      return;
+    }
+    points.push({ name, labels, value, kind });
+  }
+
+  const transport: OtlpTransport = createOtlpHttpTransport({ endpoint, token, timeoutMs });
+
+  const pusher: MetricsPusher = {
+    counterAdd(name, value, labels = {}) {
+      addPoint(name, value, labels, "counter");
+    },
+    gaugeSet(name, value, labels = {}) {
+      addPoint(name, value, labels, "gauge");
+    },
+    histogramRecord(name, value, labels = {}) {
+      addPoint(name, value, labels, "histogram");
+    },
+    async flush() {
+      if (points.length === 0) {
+        return { delivered: true };
+      }
+
+      const resourceAttrs = buildResourceAttributes(resourceInput);
+
+      const otlpPoints = convertAccumulatedToOtlp(points, startTimeNano);
+
+      if (otlpPoints.length === 0) {
+        return { delivered: true };
+      }
+
+      const body = encodeOtlpMetrics(resourceAttrs, otlpPoints, SCOPE_NAME, SCOPE_VERSION);
+
+      return transport.send(JSON.stringify(body));
+    },
+  };
+
+  return pusher;
+}

package/src/observability/redact.ts

@@ -0,0 +1,27 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/observability/src/redact.ts as an authored observability authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not import node: modules — must be Workers-compatible.</item>
+  <item>Do not redact at the collector level — this is a convenience for emitters.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0337: initial implementation.</item>
+  <item>Fix 2026-07-11: only trim the URL root slash so redaction is idempotent for multi-slash paths.</item>
+</CHANGE_SUMMARY>
+*/
+
+export function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    parsed.search = "";
+    parsed.hostname = parsed.hostname.toLowerCase();
+    const redacted = parsed.toString();
+    if (parsed.pathname === "/") return redacted.replace(/\/$/, "");
+    return redacted;
+  } catch {
+    return url;
+  }
+}