@graphorin/server 0.6.0 → 0.7.0

package/src/errors/index.ts

@@ -0,0 +1,247 @@
+/**
+ * Typed error surface for `@graphorin/server`. Every server-side
+ * configuration / lifecycle / runtime failure that an operator must
+ * be able to reason about flows through one of the classes in this
+ * module so it carries a stable `kind` discriminator + `hint` field
+ * pointing the operator at the next remediation step.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Stable string discriminator for {@link GraphorinServerError}. Each
+ * value maps to a single failure scenario; never reuse a value for a
+ * different cause.
+ *
+ * @stable
+ */
+export type GraphorinServerErrorCode =
+  | 'config-invalid'
+  | 'pre-bind-pepper-missing'
+  | 'pre-bind-secret-unresolvable'
+  | 'pre-bind-encryption-peer-missing'
+  | 'pre-bind-encryption-required'
+  | 'migration-failed'
+  | 'shutdown-timeout'
+  | 'idempotency-conflict'
+  | 'idempotency-key-required'
+  | 'auth-required'
+  | 'auth-invalid'
+  | 'auth-revoked'
+  | 'auth-expired'
+  | 'auth-locked-out'
+  | 'auth-overloaded'
+  | 'scope-denied'
+  | 'csrf-denied'
+  | 'cors-denied'
+  | 'rate-limit-exceeded'
+  | 'route-handler-missing'
+  | 'agent-not-found'
+  | 'workflow-not-found'
+  | 'session-not-found'
+  | 'run-not-found'
+  | 'run-aborted'
+  | 'lifecycle-double-start'
+  | 'lifecycle-not-started';
+
+/**
+ * Base error class. Every server-emitted typed error inherits from
+ * here so middleware can pattern-match a single union.
+ *
+ * @stable
+ */
+export class GraphorinServerError extends Error {
+  readonly kind: GraphorinServerErrorCode;
+  readonly hint?: string;
+
+  constructor(
+    kind: GraphorinServerErrorCode,
+    message: string,
+    options?: { readonly cause?: unknown; readonly hint?: string },
+  ) {
+    super(
+      message,
+      options !== undefined && options.cause !== undefined ? { cause: options.cause } : undefined,
+    );
+    this.name = this.constructor.name;
+    this.kind = kind;
+    if (options?.hint !== undefined) this.hint = options.hint;
+  }
+}
+
+/** @stable */
+export class ConfigInvalidError extends GraphorinServerError {
+  readonly issues: ReadonlyArray<{
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+  }>;
+
+  constructor(
+    issues: ReadonlyArray<{
+      readonly path: ReadonlyArray<string | number>;
+      readonly message: string;
+    }>,
+    cause?: unknown,
+  ) {
+    super('config-invalid', `graphorin.config invalid: ${issues.length} issue(s)`, {
+      hint: 'Inspect the issues array; each entry pinpoints the offending path.',
+      ...(cause !== undefined ? { cause } : {}),
+    });
+    this.issues = Object.freeze(issues.slice());
+  }
+}
+
+/** @stable */
+export class PrebindPepperMissingError extends GraphorinServerError {
+  constructor() {
+    super(
+      'pre-bind-pepper-missing',
+      'auth.pepper SecretRef did not resolve to a non-empty pepper.',
+      {
+        hint: 'Run `graphorin doctor --check-secrets` (Phase 15) and verify the configured SecretRef.',
+      },
+    );
+  }
+}
+
+/** @stable */
+export class PrebindSecretUnresolvableError extends GraphorinServerError {
+  readonly path: ReadonlyArray<string | number>;
+  readonly raw: string;
+
+  constructor(path: ReadonlyArray<string | number>, raw: string, cause?: unknown) {
+    super(
+      'pre-bind-secret-unresolvable',
+      `Could not resolve SecretRef '${raw}' at config path ${path.join('.')}`,
+      {
+        hint: 'Run `graphorin doctor --check-secrets` (Phase 15) and verify the configured SecretRef.',
+        ...(cause !== undefined ? { cause } : {}),
+      },
+    );
+    this.path = Object.freeze(path.slice());
+    this.raw = raw;
+  }
+}
+
+/** @stable */
+export class PrebindEncryptionPeerMissingError extends GraphorinServerError {
+  constructor(cause?: unknown) {
+    super(
+      'pre-bind-encryption-peer-missing',
+      'storage.encryption.enabled = true but the cipher peer is not installed.',
+      {
+        hint: "Install the 'better-sqlite3-multiple-ciphers' peer (or set storage.encryption.enabled = false).",
+        ...(cause !== undefined ? { cause } : {}),
+      },
+    );
+  }
+}
+
+/** @stable */
+export class PrebindEncryptionRequiredError extends GraphorinServerError {
+  constructor(reason: string) {
+    super('pre-bind-encryption-required', reason, {
+      hint: 'Audit logs are mandatory-encrypted (DEC-124); enable storage.encryption or supply audit.encryption explicitly.',
+    });
+  }
+}
+
+/** @stable */
+export class MigrationFailedError extends GraphorinServerError {
+  constructor(message: string, cause?: unknown) {
+    super('migration-failed', message, {
+      hint: 'Inspect the underlying SQLite error and re-run `graphorin migrate`.',
+      ...(cause !== undefined ? { cause } : {}),
+    });
+  }
+}
+
+/** @stable */
+export class ShutdownTimeoutError extends GraphorinServerError {
+  readonly drainTimeoutMs: number;
+  readonly inflight: number;
+
+  constructor(drainTimeoutMs: number, inflight: number) {
+    super(
+      'shutdown-timeout',
+      `Drain timed out after ${drainTimeoutMs}ms with ${inflight} request(s) still in flight.`,
+      {
+        hint: 'Increase server.shutdown.drainTimeoutMs or fix slow handlers.',
+      },
+    );
+    this.drainTimeoutMs = drainTimeoutMs;
+    this.inflight = inflight;
+  }
+}
+
+/** @stable */
+export class IdempotencyConflictError extends GraphorinServerError {
+  constructor(key: string) {
+    super(
+      'idempotency-conflict',
+      `Idempotency-Key '${key}' was previously used with a different request body.`,
+      {
+        hint: 'Generate a fresh Idempotency-Key for the new payload.',
+      },
+    );
+  }
+}
+
+/** @stable */
+export class IdempotencyKeyRequiredError extends GraphorinServerError {
+  constructor() {
+    super(
+      'idempotency-key-required',
+      'Side-effecting endpoint requires an Idempotency-Key header.',
+      {
+        hint: "Set 'Idempotency-Key: <uuid>' on the request, or relax server.idempotency.requireKey to 'warn'.",
+      },
+    );
+  }
+}
+
+/** @stable */
+export class LifecycleDoubleStartError extends GraphorinServerError {
+  constructor() {
+    super('lifecycle-double-start', 'Server.start() invoked while the server is already started.', {
+      hint: 'Call stop() before re-starting the server.',
+    });
+  }
+}
+
+/** @stable */
+export class LifecycleNotStartedError extends GraphorinServerError {
+  constructor() {
+    super('lifecycle-not-started', 'Server.stop() invoked before start() resolved.', {
+      hint: 'Await start() before calling stop().',
+    });
+  }
+}
+
+/** @stable */
+export class RouteHandlerMissingError extends GraphorinServerError {
+  readonly id: string;
+  readonly kind_: 'agent' | 'workflow';
+
+  constructor(kind: 'agent' | 'workflow', id: string) {
+    super('route-handler-missing', `No ${kind} registered with id '${id}'.`, {
+      hint: `Register the ${kind} via createServer({ ${kind}s: { ... } }) or the AgentRegistry / WorkflowRegistry surface.`,
+    });
+    this.id = id;
+    this.kind_ = kind;
+  }
+}
+
+/** @stable */
+export class AgentNotFoundError extends RouteHandlerMissingError {
+  constructor(id: string) {
+    super('agent', id);
+  }
+}
+
+/** @stable */
+export class WorkflowNotFoundError extends RouteHandlerMissingError {
+  constructor(id: string) {
+    super('workflow', id);
+  }
+}

package/src/health/checks.ts

@@ -0,0 +1,322 @@
+/**
+ * Per-subsystem health checks aggregated by `/v1/health`. Every check
+ * resolves to `'ok' | 'warn' | 'fail'`; the aggregator promotes the
+ * worst status to the top-level rollup.
+ *
+ * The serialized shape is **flat**: each check carries its detail
+ * fields directly on the same object as the `status` discriminator
+ * - no nested `detail` wrapper - matching the documented response
+ * contract exactly.
+ *
+ * @packageDocumentation
+ */
+
+import type { GraphorinSqliteStore } from '@graphorin/store-sqlite';
+import { readWalSize } from '@graphorin/store-sqlite';
+import type { ConsolidatorDaemon } from '../consolidator/daemon.js';
+import type { TriggersDaemon } from '../triggers/daemon.js';
+import type { WorkflowTimerDaemon } from '../workflows/timer-daemon.js';
+
+/** @stable */
+export interface ReplayBufferProbe {
+  /** Total events buffered across all subjects. Aggregated by the caller. */
+  readonly eventsBuffered: number;
+  readonly subscribers?: number;
+  readonly subscriptions?: number;
+}
+
+/** @stable */
+export type HealthStatus = 'ok' | 'warn' | 'fail';
+
+/** @stable */
+export type HealthRollup = 'ok' | 'degraded' | 'failing';
+
+/**
+ * Common discriminator carried on every per-subsystem check entry.
+ * Concrete shapes extend this with subsystem-specific fields per the
+ * documented contract.
+ *
+ * @stable
+ */
+export interface BaseHealthCheck {
+  readonly status: HealthStatus;
+  readonly message?: string;
+}
+
+/** @stable */
+export interface StorageCheck extends BaseHealthCheck {
+  readonly walSizeBytes: number;
+  readonly warnThresholdBytes: number;
+  readonly lastCheckpointAt?: string;
+}
+
+/** @stable */
+export interface EmbedderCheck extends BaseHealthCheck {
+  readonly modelLoaded: boolean;
+  readonly model?: string;
+}
+
+/** @stable */
+export interface SecretsCheck extends BaseHealthCheck {
+  readonly activeStore: string;
+}
+
+/** @stable */
+export interface EncryptionCheck extends BaseHealthCheck {
+  readonly enabled: boolean;
+  readonly peerDepInstalled: boolean;
+}
+
+/** @stable */
+export interface ConsolidatorCheck extends BaseHealthCheck {
+  readonly tier: string;
+  readonly running: boolean;
+  readonly paused: boolean;
+  readonly queueDepth: number;
+  readonly dlqSize: number;
+  readonly budgetRemaining: {
+    readonly tokens: number;
+    readonly costUsd: number;
+  };
+}
+
+/** @stable */
+export interface TriggersCheck extends BaseHealthCheck {
+  readonly running: boolean;
+  readonly active: number;
+  readonly disabled: number;
+  readonly deferred: number;
+  readonly lastFireAt?: string;
+}
+
+/** @stable */
+export interface ReplayBufferCheck extends BaseHealthCheck {
+  readonly eventsBuffered: number;
+  readonly subscribers?: number;
+  readonly subscriptions?: number;
+}
+
+/** @stable */
+export type HealthCheck =
+  | StorageCheck
+  | EmbedderCheck
+  | SecretsCheck
+  | EncryptionCheck
+  | ConsolidatorCheck
+  | TriggersCheck
+  | WorkflowTimersCheck
+  | ReplayBufferCheck;
+
+/** W-032: durable-timer driver health. @stable */
+export interface WorkflowTimersCheck {
+  readonly status: HealthStatus;
+  readonly running: boolean;
+  readonly sweeps: number;
+  readonly fired: number;
+  readonly errors: number;
+  readonly lastSweepAt?: string;
+  readonly nextWakeAt?: string;
+  readonly message?: string;
+}
+
+/** @stable */
+export interface HealthChecks {
+  readonly storage?: StorageCheck;
+  readonly embedder?: EmbedderCheck;
+  readonly secrets?: SecretsCheck;
+  readonly encryption?: EncryptionCheck;
+  readonly consolidator?: ConsolidatorCheck;
+  readonly triggers?: TriggersCheck;
+  readonly workflowTimers?: WorkflowTimersCheck;
+  readonly replayBuffer?: ReplayBufferCheck;
+}
+
+/** @stable */
+export interface HealthSummary {
+  readonly status: HealthRollup;
+  readonly checks: HealthChecks;
+}
+
+/** @stable */
+export interface HealthCheckOptions {
+  readonly store?: GraphorinSqliteStore;
+  readonly triggers?: TriggersDaemon;
+  readonly workflowTimers?: WorkflowTimerDaemon;
+  readonly consolidator?: ConsolidatorDaemon;
+  readonly replayBuffer?: ReplayBufferProbe;
+  readonly secretsActive?: string;
+  readonly encryptionEnabled?: boolean;
+  readonly cipherPeerInstalled?: boolean;
+  readonly embedderModel?: string;
+  readonly embedderLoaded?: boolean;
+  /** Highest acceptable WAL size in bytes before warning. Default 50 MB. */
+  readonly walWarnThresholdBytes?: number;
+}
+
+const DEFAULT_WAL_WARN_THRESHOLD_BYTES = 50 * 1024 * 1024;
+
+/**
+ * Build the aggregate health summary from runtime probes.
+ *
+ * @stable
+ */
+export async function collectHealth(options: HealthCheckOptions): Promise<HealthSummary> {
+  const checks: {
+    -readonly [K in keyof HealthChecks]?: HealthChecks[K];
+  } = {};
+
+  if (options.store !== undefined) {
+    const walSize = readWalSizeSafely(options.store);
+    const threshold = options.walWarnThresholdBytes ?? DEFAULT_WAL_WARN_THRESHOLD_BYTES;
+    const status: HealthStatus = walSize > threshold ? 'warn' : 'ok';
+    checks.storage = {
+      status,
+      walSizeBytes: walSize,
+      warnThresholdBytes: threshold,
+    };
+  }
+
+  if (options.embedderLoaded !== undefined) {
+    checks.embedder = {
+      status: options.embedderLoaded ? 'ok' : 'warn',
+      modelLoaded: options.embedderLoaded,
+      ...(options.embedderModel !== undefined ? { model: options.embedderModel } : {}),
+    };
+  }
+
+  if (options.secretsActive !== undefined) {
+    checks.secrets = {
+      status: 'ok',
+      activeStore: options.secretsActive,
+    };
+  }
+
+  if (options.encryptionEnabled !== undefined) {
+    // IP-1: a server that is serving this health endpoint with
+    // encryption enabled has already opened the store WITH its key at
+    // boot (createServer threads the resolved passphrase into
+    // createSqliteStore and fails fast otherwise) - that successful
+    // keyed open is the factual basis of this check. 'fail' is
+    // reserved for an explicit negative cipher-peer probe; the old
+    // default blamed a missing peer dep on every encrypted boot.
+    const peerDepInstalled = options.cipherPeerInstalled ?? true;
+    checks.encryption = {
+      status: options.encryptionEnabled && peerDepInstalled === false ? 'fail' : 'ok',
+      enabled: options.encryptionEnabled,
+      peerDepInstalled,
+    };
+  }
+
+  if (options.consolidator !== undefined) {
+    try {
+      const status = await options.consolidator.status();
+      const overall: HealthStatus = status.dlqSize > 0 ? 'warn' : 'ok';
+      checks.consolidator = {
+        status: status.paused ? 'warn' : overall,
+        tier: status.tier,
+        running: status.running,
+        paused: status.paused,
+        queueDepth: status.queueDepth,
+        dlqSize: status.dlqSize,
+        budgetRemaining: {
+          tokens: status.budget.tokensRemaining,
+          costUsd: status.budget.costRemaining,
+        },
+      };
+    } catch (err) {
+      checks.consolidator = {
+        status: 'fail',
+        tier: 'unknown',
+        running: false,
+        paused: false,
+        queueDepth: 0,
+        dlqSize: 0,
+        budgetRemaining: { tokens: 0, costUsd: 0 },
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  if (options.triggers !== undefined) {
+    try {
+      const status = await options.triggers.status();
+      checks.triggers = {
+        status: 'ok',
+        running: status.running,
+        active: status.active,
+        disabled: status.disabled,
+        deferred: status.deferred,
+        ...(status.lastFireAt !== undefined ? { lastFireAt: status.lastFireAt } : {}),
+      };
+    } catch (err) {
+      checks.triggers = {
+        status: 'fail',
+        running: false,
+        active: 0,
+        disabled: 0,
+        deferred: 0,
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  if (options.workflowTimers !== undefined) {
+    try {
+      const status = await options.workflowTimers.status();
+      checks.workflowTimers = {
+        status: status.errors > 0 ? 'warn' : 'ok',
+        running: status.running,
+        sweeps: status.sweeps,
+        fired: status.fired,
+        errors: status.errors,
+        ...(status.lastSweepAt !== undefined ? { lastSweepAt: status.lastSweepAt } : {}),
+        ...(status.nextWakeAt !== undefined ? { nextWakeAt: status.nextWakeAt } : {}),
+      };
+    } catch (err) {
+      checks.workflowTimers = {
+        status: 'fail',
+        running: false,
+        sweeps: 0,
+        fired: 0,
+        errors: 0,
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  if (options.replayBuffer !== undefined) {
+    const probe = options.replayBuffer;
+    checks.replayBuffer = {
+      status: 'ok',
+      eventsBuffered: probe.eventsBuffered,
+      ...(probe.subscribers !== undefined ? { subscribers: probe.subscribers } : {}),
+      ...(probe.subscriptions !== undefined ? { subscriptions: probe.subscriptions } : {}),
+    };
+  }
+
+  const status = rollup(checks);
+  return Object.freeze({ status, checks: Object.freeze(checks) as HealthChecks });
+}
+
+/**
+ * Promote the worst per-check status to the rollup label.
+ *
+ * @stable
+ */
+export function rollup(checks: HealthChecks): HealthRollup {
+  let worst: HealthRollup = 'ok';
+  for (const value of Object.values(checks)) {
+    if (value === undefined) continue;
+    if (value.status === 'fail') return 'failing';
+    if (value.status === 'warn') worst = 'degraded';
+  }
+  return worst;
+}
+
+function readWalSizeSafely(store: GraphorinSqliteStore): number {
+  try {
+    return readWalSize(store.connection);
+  } catch {
+    return 0;
+  }
+}

package/src/health/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@graphorin/server/health` - Phase 14c health + Prometheus metrics
+ * surface. Phase 14a's `/v1/health` is superseded by the extended
+ * routes built here when consumers wire the additional probes.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  type BaseHealthCheck,
+  type ConsolidatorCheck,
+  collectHealth,
+  type EmbedderCheck,
+  type EncryptionCheck,
+  type HealthCheck,
+  type HealthCheckOptions,
+  type HealthChecks,
+  type HealthRollup,
+  type HealthStatus,
+  type HealthSummary,
+  type ReplayBufferCheck,
+  type ReplayBufferProbe,
+  rollup,
+  type SecretsCheck,
+  type StorageCheck,
+  type TriggersCheck,
+} from './checks.js';
+export {
+  createExtendedHealthRoutes,
+  createMetricsRoutes,
+  createSecretsHealthRoutes,
+  type HealthRouteOptions,
+  type MetricsRoutesOptions,
+} from './routes.js';