@graphoria/server 0.3.0 → 0.5.0

package/src/observability/httpMetrics.ts

@@ -0,0 +1,37 @@
+import { incMetric, isMetricsEnabled, observeMetric } from "./metrics";
+
+/**
+ * Wraps a route handler so the request is counted and timed. The route label is
+ * the name of the mounted route, never the URL: a path carries identifiers, and
+ * one series per identifier is a cardinality leak.
+ */
+export const withHttpMetrics =
+  <Req extends Request, Args extends unknown[]>(
+    route: string,
+    handler: (req: Req, ...args: Args) => Response | undefined | Promise<Response | undefined>,
+  ) =>
+  async (req: Req, ...args: Args): Promise<Response | undefined> => {
+    if (!isMetricsEnabled()) return handler(req, ...args);
+
+    const startTime = Bun.nanoseconds();
+    const method = req.method;
+    const record = (status: string) => {
+      incMetric("graphoria_http_requests_total", { route, method, status });
+      observeMetric(
+        "graphoria_http_request_duration_seconds",
+        { route, method },
+        (Bun.nanoseconds() - startTime) / 1e9,
+      );
+    };
+
+    try {
+      const response = await handler(req, ...args);
+      // A websocket upgrade answers no request, so it is not counted as one.
+      if (response) record(String(response.status));
+      return response;
+    } catch (error) {
+      // What Bun answers when a route handler throws.
+      record("500");
+      throw error;
+    }
+  };

package/src/observability/httpTracing.ts

@@ -0,0 +1,48 @@
+import { isTracingEnabled, parseTraceparent, startSpan, withActiveSpan } from "./tracing";
+
+/**
+ * Wraps a route handler so the request roots a trace. The span is named for the
+ * mounted route, never the URL: a path carries identifiers and a query string
+ * carries caller data, and a span name is exported verbatim.
+ *
+ * An inbound `traceparent` is continued, so a gateway's span and this one join
+ * up. `parent: null` is deliberate — a request is a root, never a child of
+ * whatever context the server happened to be in.
+ */
+export const withHttpTracing =
+  <Req extends Request, Args extends unknown[]>(
+    route: string,
+    handler: (req: Req, ...args: Args) => Response | undefined | Promise<Response | undefined>,
+  ) =>
+  async (req: Req, ...args: Args): Promise<Response | undefined> => {
+    if (!isTracingEnabled()) return handler(req, ...args);
+
+    const url = new URL(req.url);
+    const span = startSpan(`${req.method} ${route}`, {
+      kind: "server",
+      parent: parseTraceparent(req.headers.get("traceparent")) ?? null,
+      attributes: {
+        "http.request.method": req.method,
+        "http.route": route,
+        "url.scheme": url.protocol.replace(":", ""),
+        "server.address": url.host,
+      },
+    });
+
+    return withActiveSpan(span, async () => {
+      try {
+        const response = await handler(req, ...args);
+        // A websocket upgrade answers no request, so it gets no span: leaving
+        // this one unended is what keeps it out of the export.
+        if (response) {
+          span?.setAttribute("http.response.status_code", response.status);
+          span?.end();
+        }
+        return response;
+      } catch (error) {
+        span?.recordError(error);
+        span?.end();
+        throw error;
+      }
+    });
+  };

package/src/observability/metrics.ts

@@ -0,0 +1,243 @@
+type MetricDefinition = {
+  type: "counter" | "histogram";
+  help: string;
+  /** Declared sorted, so a rendered series lists its labels in a stable order. */
+  labelNames: readonly string[];
+};
+
+const METRICS = {
+  graphoria_graphql_operations_total: {
+    type: "counter",
+    help: "GraphQL operations executed, by outcome.",
+    labelNames: ["operation", "outcome", "role", "type"],
+  },
+  graphoria_graphql_operation_duration_seconds: {
+    type: "histogram",
+    help: "Time spent handling a GraphQL operation, in seconds.",
+    labelNames: ["operation", "role", "type"],
+  },
+  graphoria_http_requests_total: {
+    type: "counter",
+    help: "HTTP requests answered by the GraphQL and REST routes, by status.",
+    labelNames: ["method", "route", "status"],
+  },
+  graphoria_http_request_duration_seconds: {
+    type: "histogram",
+    help: "Time spent answering an HTTP request, in seconds.",
+    labelNames: ["method", "route"],
+  },
+  graphoria_cron_runs_total: {
+    type: "counter",
+    help: "Cron ticks that ran to completion or threw, by job.",
+    labelNames: ["job", "outcome"],
+  },
+  graphoria_cron_run_duration_seconds: {
+    type: "histogram",
+    help: "Time spent in a cron tick, in seconds.",
+    labelNames: ["job"],
+  },
+  graphoria_queue_messages_published_total: {
+    type: "counter",
+    help: "Messages handed to a broker, by publisher and outcome.",
+    labelNames: ["broker", "outcome", "publisher"],
+  },
+  graphoria_queue_messages_consumed_total: {
+    type: "counter",
+    help: "Messages taken from a broker, by consumer and outcome.",
+    labelNames: ["broker", "consumer", "outcome", "queue"],
+  },
+  graphoria_rate_limit_rejections_total: {
+    type: "counter",
+    help: "Requests refused by the rate limiter, by the role the ceiling was read from.",
+    labelNames: ["role"],
+  },
+  graphoria_graphql_rejections_total: {
+    type: "counter",
+    help: "GraphQL operations rejected before execution.",
+    labelNames: ["reason"],
+  },
+} as const satisfies Record<string, MetricDefinition>;
+
+export type MetricName = keyof typeof METRICS;
+
+export type Labels = Record<string, string>;
+
+export type Registry = {
+  inc(metric: MetricName, labels: Labels, value?: number): void;
+  observe(metric: MetricName, labels: Labels, seconds: number): void;
+  render(): string;
+};
+
+export type RegistryOptions = {
+  /** Distinct values the caller-supplied `operation` label may take, per metric. */
+  maxOperationLabels?: number;
+};
+
+const BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10] as const;
+
+const SEPARATOR = "\u0000";
+
+const OVERFLOW_LABEL = "other";
+
+const DEFAULT_MAX_OPERATION_LABELS = 200;
+
+type HistogramSeries = { counts: number[]; sum: number; count: number };
+
+const escapeLabelValue = (value: string) =>
+  value.replaceAll("\\", "\\\\").replaceAll("\n", "\\n").replaceAll('"', '\\"');
+
+/**
+ * A metric store with no dependencies. The `operation` label is the only one a
+ * caller controls, so it is the only one capped: past the cap every new name
+ * collapses into `other` rather than minting a series the scrape has to carry
+ * forever.
+ */
+export const createRegistry = ({
+  maxOperationLabels = DEFAULT_MAX_OPERATION_LABELS,
+}: RegistryOptions = {}): Registry => {
+  const counters = new Map<MetricName, Map<string, number>>();
+  const histograms = new Map<MetricName, Map<string, HistogramSeries>>();
+  const knownOperations = new Map<MetricName, Set<string>>();
+
+  const boundOperation = (metric: MetricName, operation: string) => {
+    let known = knownOperations.get(metric);
+    if (!known) {
+      known = new Set();
+      knownOperations.set(metric, known);
+    }
+    if (known.has(operation)) return operation;
+    if (known.size >= maxOperationLabels) return OVERFLOW_LABEL;
+    known.add(operation);
+    return operation;
+  };
+
+  const keyOf = (metric: MetricName, labels: Labels) =>
+    METRICS[metric].labelNames
+      .map((name) => {
+        const value = labels[name] ?? "";
+        return name === "operation" ? boundOperation(metric, value) : value;
+      })
+      .join(SEPARATOR);
+
+  const renderLabels = (metric: MetricName, key: string, extra?: string) => {
+    const values = key.split(SEPARATOR);
+    const pairs = METRICS[metric].labelNames.map(
+      (name, index) => `${name}="${escapeLabelValue(values[index] ?? "")}"`,
+    );
+    if (extra) pairs.push(extra);
+    return pairs.length > 0 ? `{${pairs.join(",")}}` : "";
+  };
+
+  const seriesOf = <T>(store: Map<MetricName, Map<string, T>>, metric: MetricName) => {
+    let series = store.get(metric);
+    if (!series) {
+      series = new Map();
+      store.set(metric, series);
+    }
+    return series;
+  };
+
+  const renderHeader = (lines: string[], metric: MetricName) => {
+    const definition = METRICS[metric];
+    lines.push(`# HELP ${metric} ${definition.help}`, `# TYPE ${metric} ${definition.type}`);
+  };
+
+  return {
+    inc: (metric, labels, value = 1) => {
+      const series = seriesOf(counters, metric);
+      const key = keyOf(metric, labels);
+      series.set(key, (series.get(key) ?? 0) + value);
+    },
+
+    observe: (metric, labels, seconds) => {
+      const series = seriesOf(histograms, metric);
+      const key = keyOf(metric, labels);
+      let entry = series.get(key);
+      if (!entry) {
+        entry = { counts: new Array(BUCKETS.length).fill(0), sum: 0, count: 0 };
+        series.set(key, entry);
+      }
+      entry.sum += seconds;
+      entry.count += 1;
+      for (let index = 0; index < BUCKETS.length; index++) {
+        if (seconds <= BUCKETS[index]!) entry.counts[index]! += 1;
+      }
+    },
+
+    render: () => {
+      const lines: string[] = [];
+
+      for (const [metric, series] of counters) {
+        if (series.size === 0) continue;
+        renderHeader(lines, metric);
+        for (const [key, value] of series) {
+          lines.push(`${metric}${renderLabels(metric, key)} ${value}`);
+        }
+      }
+
+      for (const [metric, series] of histograms) {
+        if (series.size === 0) continue;
+        renderHeader(lines, metric);
+        for (const [key, entry] of series) {
+          for (let index = 0; index < BUCKETS.length; index++) {
+            lines.push(
+              `${metric}_bucket${renderLabels(metric, key, `le="${BUCKETS[index]}"`)} ${entry.counts[index]}`,
+            );
+          }
+          lines.push(
+            `${metric}_bucket${renderLabels(metric, key, 'le="+Inf"')} ${entry.count}`,
+            `${metric}_sum${renderLabels(metric, key)} ${entry.sum}`,
+            `${metric}_count${renderLabels(metric, key)} ${entry.count}`,
+          );
+        }
+      }
+
+      return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+    },
+  };
+};
+
+/**
+ * Off until boot turns it on, so an executor or a handler used outside a booted
+ * server records nothing. Every call site goes through the helpers below, whose
+ * first act is this check — a disabled process pays one branch and allocates
+ * nothing.
+ */
+let enabled = false;
+
+let options: RegistryOptions = {};
+
+let override: Registry | null = null;
+let instance: Registry | null = null;
+
+export const configureMetrics = (settings: { enabled: boolean } & RegistryOptions): void => {
+  enabled = settings.enabled;
+  options = { maxOperationLabels: settings.maxOperationLabels };
+  instance = null;
+};
+
+/** Test seam: pass `null` to drop the process registry and its recorded series. */
+export const setMetricsRegistry = (registry: Registry | null): void => {
+  override = registry;
+  instance = null;
+};
+
+const registry = (): Registry => {
+  if (override) return override;
+  if (!instance) instance = createRegistry(options);
+  return instance;
+};
+
+export const isMetricsEnabled = (): boolean => enabled;
+
+export const incMetric = (metric: MetricName, labels: Labels, value = 1): void => {
+  if (!enabled) return;
+  registry().inc(metric, labels, value);
+};
+
+export const observeMetric = (metric: MetricName, labels: Labels, seconds: number): void => {
+  if (!enabled) return;
+  registry().observe(metric, labels, seconds);
+};
+
+export const renderMetrics = (): string => registry().render();

package/src/observability/metricsRoute.ts

@@ -0,0 +1,33 @@
+import type { CapabilityGrant } from "../authentication/capabilities";
+
+import { S401 } from "../utils/responses";
+
+export type MetricsRouteOptions = {
+  path: string;
+  /** The header a scoped credential rides in — the admin-secret header. */
+  secretHeader: string;
+  authorize: (candidate: string | null) => CapabilityGrant | null;
+  render: () => string;
+};
+
+const CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+
+/**
+ * A scrape is gated because the exposition names operations, roles and
+ * databases. It is deliberately not rate limited: a scrape interval is fixed
+ * and counting it against a caller ceiling would drop samples.
+ */
+export const createMetricsRoute = ({
+  path,
+  secretHeader,
+  authorize,
+  render,
+}: MetricsRouteOptions) => ({
+  [path]: {
+    GET: (req: Request) => {
+      if (!authorize(req.headers.get(secretHeader))) return new S401({ error: "Unauthorized" });
+
+      return new Response(render(), { headers: { "content-type": CONTENT_TYPE } });
+    },
+  },
+});