@graphorin/server 0.6.0 → 0.7.0

package/src/lifecycle/pre-bind.ts

@@ -0,0 +1,138 @@
+/**
+ * Pre-bind validation. Runs *before* the HTTP listener attaches so a
+ * misconfigured server never accepts a single request.
+ *
+ * Steps (fail-fast on every failure):
+ *
+ *  1. Resolve every `*Ref` field on the config through the
+ *     `@graphorin/security` resolver registry. Missing ref → exit 1.
+ *  2. Confirm the server pepper resolved to non-empty bytes.
+ *  3. Confirm the encryption peer is loadable when
+ *     `storage.encryption.enabled === true` (or `audit.enabled === true`).
+ *  4. Run pending storage migrations - failures bubble up as
+ *     `MigrationFailedError`.
+ *
+ * The function is idempotent - calling it more than once for the
+ * same {@link createSqliteStore} handle re-validates the secrets but
+ * leaves the underlying database untouched.
+ *
+ * @packageDocumentation
+ */
+
+import type { SecretValue } from '@graphorin/security';
+
+import { resolveSecret } from '@graphorin/security/secrets';
+import type { GraphorinSqliteStore } from '@graphorin/store-sqlite';
+
+import type { ServerConfigSpec } from '../config.js';
+import {
+  MigrationFailedError,
+  PrebindEncryptionPeerMissingError,
+  PrebindEncryptionRequiredError,
+  PrebindPepperMissingError,
+  PrebindSecretUnresolvableError,
+} from '../errors/index.js';
+
+/**
+ * Result returned by {@link runPreBind}. Consumers (`createServer`,
+ * tests) consume the resolved pepper + encryption decision when
+ * wiring the rest of the server.
+ *
+ * @stable
+ */
+export interface PreBindResult {
+  readonly pepper?: SecretValue;
+  readonly auditPath?: string;
+  readonly auditPassphrase?: SecretValue;
+  readonly storagePassphrase?: SecretValue;
+}
+
+/**
+ * @stable
+ */
+export interface RunPreBindOptions {
+  readonly config: ServerConfigSpec;
+  readonly store: GraphorinSqliteStore;
+  /**
+   * Optional override for the cipher-peer probe. Tests inject a stub
+   * that signals "missing peer" without uninstalling the real one.
+   */
+  readonly probeCipherPeer?: () => Promise<void>;
+}
+
+async function resolveRef(path: ReadonlyArray<string | number>, raw: string): Promise<SecretValue> {
+  try {
+    return await resolveSecret(raw);
+  } catch (err) {
+    throw new PrebindSecretUnresolvableError(path, raw, err);
+  }
+}
+
+/**
+ * @stable
+ */
+export async function runPreBind(options: RunPreBindOptions): Promise<PreBindResult> {
+  const { config, store } = options;
+  const out: { -readonly [K in keyof PreBindResult]?: PreBindResult[K] } = {};
+
+  if (config.auth.kind === 'token') {
+    if (config.auth.pepperRef === undefined || config.auth.pepperRef.length === 0) {
+      throw new PrebindPepperMissingError();
+    }
+    const pepper = await resolveRef(['auth', 'pepperRef'], config.auth.pepperRef);
+    const buf = await pepper.useBuffer((b) => Buffer.from(b));
+    if (buf.length === 0) {
+      throw new PrebindPepperMissingError();
+    }
+    out.pepper = pepper;
+  }
+
+  if (config.storage.encryption.enabled) {
+    if (config.storage.encryption.passphraseRef === undefined) {
+      throw new PrebindEncryptionRequiredError(
+        'storage.encryption.enabled is true but no passphraseRef is configured.',
+      );
+    }
+    out.storagePassphrase = await resolveRef(
+      ['storage', 'encryption', 'passphraseRef'],
+      config.storage.encryption.passphraseRef,
+    );
+    if (options.probeCipherPeer !== undefined) {
+      try {
+        await options.probeCipherPeer();
+      } catch (err) {
+        throw new PrebindEncryptionPeerMissingError(err);
+      }
+    }
+  }
+
+  if (config.audit.enabled) {
+    const passphraseRef = config.audit.passphraseRef ?? config.storage.encryption.passphraseRef;
+    if (passphraseRef === undefined) {
+      throw new PrebindEncryptionRequiredError(
+        'audit.enabled is true but no audit.passphraseRef (or storage.encryption.passphraseRef) is configured. Audit logs are mandatory-encrypted (DEC-124).',
+      );
+    }
+    out.auditPath = config.audit.path ?? deriveAuditPath(config.storage.path);
+    out.auditPassphrase = await resolveRef(['audit', 'passphraseRef'], passphraseRef);
+  }
+
+  try {
+    await store.init();
+  } catch (err) {
+    throw new MigrationFailedError(`Storage migrations failed: ${describeError(err)}`, err);
+  }
+
+  return Object.freeze(out as PreBindResult);
+}
+
+function deriveAuditPath(storagePath: string): string {
+  const idx = storagePath.lastIndexOf('/');
+  if (idx < 0) return 'audit.db';
+  return `${storagePath.slice(0, idx)}/audit.db`;
+}
+
+function describeError(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/metrics/catalog.ts

@@ -0,0 +1,112 @@
+/**
+ * Canonical metric inventory for the standalone server. Every metric
+ * the framework emits is registered here in one place so the
+ * exposition output is deterministic across builds.
+ *
+ * Metric naming follows the documented `graphorin_*` prefix
+ * discipline; label cardinality is bounded by construction (no PII
+ * labels - see DEC-141 cross-cut).
+ *
+ * @packageDocumentation
+ */
+
+import { MetricRegistry } from './registry.js';
+
+/**
+ * @stable
+ */
+// IP-15: the catalog lists only metrics the server actually moves. Five
+// previously-registered series - `graphorin_tool_calls_total`,
+// `graphorin_provider_tokens_total`, `graphorin_provider_cost_usd_total`,
+// `graphorin_redaction_drops_total` and `graphorin_oauth_tokens_freshness_seconds`
+// - had no producer anywhere in the monorepo (per-tool and provider usage live
+// in the agent runtime, not the server; redaction drops in the observability
+// layer; OAuth freshness needs an MCP token store the server does not own). A
+// permanently-empty series is worse than an absent one for dashboards, so they
+// are dropped until a real producer exists rather than advertised inert.
+// W-051 update: tool/MCP telemetry NOW has a producer - the scrape-time
+// `metrics/tools-bridge.ts` sync lazily registers
+// `graphorin_tool_*` / `graphorin_mcp_*` series from the tools package's
+// live counter snapshot, so only series that actually moved ever appear
+// (consistent with IP-15: nothing advertised inert).
+export const SERVER_METRIC_NAMES = Object.freeze({
+  agentRunsTotal: 'graphorin_agent_runs_total',
+  agentRunDuration: 'graphorin_agent_run_duration_seconds',
+  storageWalSize: 'graphorin_storage_wal_size_bytes',
+  idempotencyCacheHitRatio: 'graphorin_idempotency_cache_hit_ratio',
+  triggersFiresTotal: 'graphorin_triggers_fires_total',
+  consolidatorQueueDepth: 'graphorin_consolidator_queue_depth',
+  consolidatorDlqSize: 'graphorin_consolidator_dlq_size',
+  consolidatorBudgetRemainingUsd: 'graphorin_consolidator_budget_remaining_usd',
+  consolidatorBudgetRemainingTokens: 'graphorin_consolidator_budget_remaining_tokens',
+  replayBufferEvents: 'graphorin_replay_buffer_events',
+  inflightRuns: 'graphorin_inflight_runs',
+  serverUptime: 'graphorin_server_uptime_seconds',
+  buildInfo: 'graphorin_build_info',
+} as const);
+
+/**
+ * Build a fully-registered {@link MetricRegistry} ready for the
+ * `/v1/metrics` exposition. The returned registry has every metric
+ * declared but no samples; the server runtime updates samples
+ * incrementally.
+ *
+ * @stable
+ */
+export function createServerMetricRegistry(): MetricRegistry {
+  const registry = new MetricRegistry();
+
+  registry.registerCounter(
+    SERVER_METRIC_NAMES.agentRunsTotal,
+    'Total agent runs by terminal status.',
+    ['status'],
+  );
+  registry.registerSummary(
+    SERVER_METRIC_NAMES.agentRunDuration,
+    'Agent run duration in seconds.',
+    [],
+  );
+  registry.registerGauge(SERVER_METRIC_NAMES.storageWalSize, 'Current SQLite WAL size in bytes.');
+  registry.registerGauge(
+    SERVER_METRIC_NAMES.idempotencyCacheHitRatio,
+    'Idempotency LRU cache hit ratio in [0, 1].',
+  );
+  registry.registerCounter(
+    SERVER_METRIC_NAMES.triggersFiresTotal,
+    'Total trigger fires by trigger id and outcome.',
+    ['trigger_id', 'status'],
+  );
+  registry.registerGauge(
+    SERVER_METRIC_NAMES.consolidatorQueueDepth,
+    'Pending consolidator items by phase.',
+    ['phase'],
+  );
+  registry.registerGauge(
+    SERVER_METRIC_NAMES.consolidatorDlqSize,
+    'Number of consolidator runs sitting in the dead-letter queue.',
+  );
+  registry.registerGauge(
+    SERVER_METRIC_NAMES.consolidatorBudgetRemainingUsd,
+    'Consolidator USD budget remaining for the current period.',
+  );
+  registry.registerGauge(
+    SERVER_METRIC_NAMES.consolidatorBudgetRemainingTokens,
+    'Consolidator token budget remaining for the current period.',
+  );
+  registry.registerGauge(
+    SERVER_METRIC_NAMES.replayBufferEvents,
+    'Number of events currently buffered for WebSocket replay.',
+  );
+  registry.registerGauge(
+    SERVER_METRIC_NAMES.inflightRuns,
+    'Number of in-flight agent / workflow runs.',
+  );
+  registry.registerGauge(SERVER_METRIC_NAMES.serverUptime, 'Server process uptime in seconds.');
+  registry.registerGauge(
+    SERVER_METRIC_NAMES.buildInfo,
+    'Static `1` gauge carrying graphorin build labels.',
+    ['version'],
+  );
+
+  return registry;
+}

package/src/metrics/index.ts

@@ -0,0 +1,12 @@
+/**
+ * `@graphorin/server/metrics` - Phase 14c Prometheus exposition layer.
+ *
+ * @packageDocumentation
+ */
+
+export { createServerMetricRegistry, SERVER_METRIC_NAMES } from './catalog.js';
+export {
+  type LabelSet,
+  type MetricKind,
+  MetricRegistry,
+} from './registry.js';

package/src/metrics/registry.ts

@@ -0,0 +1,337 @@
+/**
+ * Tiny Prometheus exposition layer. The framework intentionally does
+ * not pull in `prom-client` so the bundle stays lean and so the
+ * exposition is byte-stable across processes (`prom-client` adds
+ * default counters that drift between Node releases).
+ *
+ * The supported metric kinds are the three the runtime spec calls
+ * out: `counter`, `gauge`, and `summary` (with hard-coded p50/p95
+ * quantiles). Sample rendering follows Prometheus text exposition
+ * format v0.0.4 - every metric block is preceded by `# HELP` + `# TYPE`
+ * and labels are quoted-escaped per the spec.
+ *
+ * @packageDocumentation
+ */
+
+/** @stable */
+export type MetricKind = 'counter' | 'gauge' | 'summary';
+
+/** @stable */
+export type LabelSet = Readonly<Record<string, string | number | boolean>>;
+
+interface MetricDefinition {
+  readonly name: string;
+  readonly help: string;
+  readonly kind: MetricKind;
+  readonly labelNames: ReadonlyArray<string>;
+}
+
+interface CounterEntry {
+  readonly labels: LabelSet;
+  value: number;
+}
+
+interface GaugeEntry {
+  readonly labels: LabelSet;
+  value: number;
+}
+
+interface SummaryEntry {
+  readonly labels: LabelSet;
+  count: number;
+  sum: number;
+  /** Recent samples (capped) used to compute quantiles. */
+  samples: number[];
+}
+
+const SUMMARY_SAMPLE_CAP = 1024;
+const SUMMARY_QUANTILES = Object.freeze([0.5, 0.95]);
+
+/**
+ * Lightweight Prometheus registry. Each instance owns its metric
+ * catalogue + per-label samples; `render()` emits the canonical text
+ * exposition block.
+ *
+ * @stable
+ */
+export class MetricRegistry {
+  readonly #definitions = new Map<string, MetricDefinition>();
+  readonly #counters = new Map<string, Map<string, CounterEntry>>();
+  readonly #gauges = new Map<string, Map<string, GaugeEntry>>();
+  readonly #summaries = new Map<string, Map<string, SummaryEntry>>();
+
+  registerCounter(name: string, help: string, labelNames: ReadonlyArray<string> = []): void {
+    this.#register(name, help, 'counter', labelNames);
+    if (!this.#counters.has(name)) this.#counters.set(name, new Map());
+  }
+
+  registerGauge(name: string, help: string, labelNames: ReadonlyArray<string> = []): void {
+    this.#register(name, help, 'gauge', labelNames);
+    if (!this.#gauges.has(name)) this.#gauges.set(name, new Map());
+  }
+
+  registerSummary(name: string, help: string, labelNames: ReadonlyArray<string> = []): void {
+    this.#register(name, help, 'summary', labelNames);
+    if (!this.#summaries.has(name)) this.#summaries.set(name, new Map());
+  }
+
+  inc(name: string, labels: LabelSet = {}, by = 1): void {
+    this.#assertKind(name, 'counter');
+    assertLabelNames(labels);
+    const bucket = this.#counters.get(name);
+    if (bucket === undefined) {
+      throw new Error(`MetricRegistry.inc: counter '${name}' is not registered`);
+    }
+    const key = serializeLabelKey(labels);
+    const entry = bucket.get(key) ?? { labels: { ...labels }, value: 0 };
+    if (!Number.isFinite(by)) {
+      throw new Error(`MetricRegistry.inc(${name}): by must be finite`);
+    }
+    if (by < 0) {
+      throw new Error(`MetricRegistry.inc(${name}): counters never decrement`);
+    }
+    entry.value += by;
+    bucket.set(key, entry);
+  }
+
+  set(name: string, value: number, labels: LabelSet = {}): void {
+    this.#assertKind(name, 'gauge');
+    assertLabelNames(labels);
+    const bucket = this.#gauges.get(name);
+    if (bucket === undefined) {
+      throw new Error(`MetricRegistry.set: gauge '${name}' is not registered`);
+    }
+    const key = serializeLabelKey(labels);
+    bucket.set(key, { labels: { ...labels }, value });
+  }
+
+  observe(name: string, value: number, labels: LabelSet = {}): void {
+    this.#assertKind(name, 'summary');
+    assertLabelNames(labels);
+    const bucket = this.#summaries.get(name);
+    if (bucket === undefined) {
+      throw new Error(`MetricRegistry.observe: summary '${name}' is not registered`);
+    }
+    const key = serializeLabelKey(labels);
+    const entry = bucket.get(key) ?? { labels: { ...labels }, count: 0, sum: 0, samples: [] };
+    entry.count += 1;
+    entry.sum += value;
+    entry.samples.push(value);
+    if (entry.samples.length > SUMMARY_SAMPLE_CAP) {
+      entry.samples.shift();
+    }
+    bucket.set(key, entry);
+  }
+
+  reset(): void {
+    this.#counters.clear();
+    this.#gauges.clear();
+    this.#summaries.clear();
+    for (const [name, def] of this.#definitions) {
+      switch (def.kind) {
+        case 'counter':
+          this.#counters.set(name, new Map());
+          break;
+        case 'gauge':
+          this.#gauges.set(name, new Map());
+          break;
+        case 'summary':
+          this.#summaries.set(name, new Map());
+          break;
+      }
+    }
+  }
+
+  /**
+   * Render the current snapshot in Prometheus text exposition
+   * format (v0.0.4). Never throws - incomplete sample buckets are
+   * skipped instead of failing the scrape.
+   */
+  render(): string {
+    const lines: string[] = [];
+    for (const def of this.#definitions.values()) {
+      lines.push(`# HELP ${def.name} ${escapeHelp(def.help)}`);
+      lines.push(`# TYPE ${def.name} ${def.kind}`);
+      switch (def.kind) {
+        case 'counter': {
+          const bucket = this.#counters.get(def.name);
+          if (bucket !== undefined) {
+            for (const entry of bucket.values()) {
+              lines.push(formatSample(def.name, entry.labels, entry.value));
+            }
+          }
+          break;
+        }
+        case 'gauge': {
+          const bucket = this.#gauges.get(def.name);
+          if (bucket !== undefined) {
+            for (const entry of bucket.values()) {
+              lines.push(formatSample(def.name, entry.labels, entry.value));
+            }
+          }
+          break;
+        }
+        case 'summary': {
+          const bucket = this.#summaries.get(def.name);
+          if (bucket !== undefined) {
+            for (const entry of bucket.values()) {
+              for (const q of SUMMARY_QUANTILES) {
+                const value = computeQuantile(entry.samples, q);
+                if (value === undefined) continue;
+                lines.push(
+                  formatSample(def.name, { ...entry.labels, quantile: q.toString() }, value),
+                );
+              }
+              lines.push(formatSample(`${def.name}_sum`, entry.labels, entry.sum));
+              lines.push(formatSample(`${def.name}_count`, entry.labels, entry.count));
+            }
+          }
+          break;
+        }
+      }
+    }
+    return `${lines.join('\n')}\n`;
+  }
+
+  contentType(): string {
+    return 'text/plain; version=0.0.4; charset=utf-8';
+  }
+
+  /** Snapshot for tests / assertions. */
+  snapshot(): {
+    counters: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>>;
+    gauges: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>>;
+    summaries: Record<
+      string,
+      ReadonlyArray<{
+        labels: LabelSet;
+        count: number;
+        sum: number;
+        samples: ReadonlyArray<number>;
+      }>
+    >;
+  } {
+    const counters: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>> = {};
+    for (const [name, bucket] of this.#counters) {
+      counters[name] = [...bucket.values()].map((entry) => ({
+        labels: entry.labels,
+        value: entry.value,
+      }));
+    }
+    const gauges: Record<string, ReadonlyArray<{ labels: LabelSet; value: number }>> = {};
+    for (const [name, bucket] of this.#gauges) {
+      gauges[name] = [...bucket.values()].map((entry) => ({
+        labels: entry.labels,
+        value: entry.value,
+      }));
+    }
+    const summaries: Record<
+      string,
+      ReadonlyArray<{
+        labels: LabelSet;
+        count: number;
+        sum: number;
+        samples: ReadonlyArray<number>;
+      }>
+    > = {};
+    for (const [name, bucket] of this.#summaries) {
+      summaries[name] = [...bucket.values()].map((entry) => ({
+        labels: entry.labels,
+        count: entry.count,
+        sum: entry.sum,
+        samples: [...entry.samples],
+      }));
+    }
+    return { counters, gauges, summaries };
+  }
+
+  #register(name: string, help: string, kind: MetricKind, labelNames: ReadonlyArray<string>): void {
+    if (!METRIC_NAME_RE.test(name)) {
+      throw new Error(`MetricRegistry: invalid metric name '${name}'`);
+    }
+    const existing = this.#definitions.get(name);
+    if (existing !== undefined) {
+      if (existing.kind !== kind) {
+        throw new Error(
+          `MetricRegistry: metric '${name}' already registered as '${existing.kind}', cannot redefine as '${kind}'`,
+        );
+      }
+      return;
+    }
+    this.#definitions.set(name, {
+      name,
+      help,
+      kind,
+      labelNames: Object.freeze([...labelNames]),
+    });
+  }
+
+  #assertKind(name: string, kind: MetricKind): void {
+    const def = this.#definitions.get(name);
+    if (def === undefined) {
+      throw new Error(`MetricRegistry: unknown metric '${name}'`);
+    }
+    if (def.kind !== kind) {
+      throw new Error(`MetricRegistry: metric '${name}' is a ${def.kind}, not a ${kind}`);
+    }
+  }
+}
+
+const METRIC_NAME_RE = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+const LABEL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+function assertLabelNames(labels: LabelSet): void {
+  for (const key of Object.keys(labels)) {
+    if (!LABEL_NAME_RE.test(key)) {
+      throw new Error(`MetricRegistry: invalid label name '${key}'`);
+    }
+  }
+}
+
+function serializeLabelKey(labels: LabelSet): string {
+  const keys = Object.keys(labels).sort();
+  if (keys.length === 0) return '';
+  const parts: string[] = [];
+  for (const k of keys) parts.push(`${k}=${String(labels[k])}`);
+  return parts.join('|');
+}
+
+function formatSample(name: string, labels: LabelSet, value: number): string {
+  const labelStr = formatLabels(labels);
+  return `${name}${labelStr} ${formatNumber(value)}`;
+}
+
+function formatLabels(labels: LabelSet): string {
+  const keys = Object.keys(labels).sort();
+  if (keys.length === 0) return '';
+  const parts: string[] = [];
+  for (const k of keys) {
+    if (!LABEL_NAME_RE.test(k)) {
+      throw new Error(`MetricRegistry: invalid label name '${k}'`);
+    }
+    parts.push(`${k}="${escapeLabelValue(String(labels[k]))}"`);
+  }
+  return `{${parts.join(',')}}`;
+}
+
+function escapeLabelValue(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/"/g, '\\"');
+}
+
+function escapeHelp(help: string): string {
+  return help.replace(/\\/g, '\\\\').replace(/\n/g, '\\n');
+}
+
+function formatNumber(value: number): string {
+  if (Number.isNaN(value)) return 'NaN';
+  if (!Number.isFinite(value)) return value > 0 ? '+Inf' : '-Inf';
+  if (Number.isInteger(value)) return String(value);
+  return value.toString();
+}
+
+function computeQuantile(samples: ReadonlyArray<number>, q: number): number | undefined {
+  if (samples.length === 0) return undefined;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1));
+  return sorted[idx];
+}