@graphorin/server 0.6.1 → 0.7.0

package/src/health/routes.ts

@@ -0,0 +1,154 @@
+/**
+ * Health-family REST routes.
+ *
+ *   GET    /health                       (unauthenticated; liveness)
+ *   GET    /health/secrets               (admin scope)
+ *   GET    /metrics                      (Prometheus exposition)
+ *
+ * `/health` returns 200 even when the rollup is `'degraded'`; only
+ * `'failing'` short-circuits with 503 so liveness probes do not flap
+ * on minor degradations (e.g. WAL above the warn threshold).
+ *
+ * @packageDocumentation
+ */
+
+import { getSecretsStoreStatus } from '@graphorin/security/secrets';
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+
+import type { ServerVariables } from '../internal/context.js';
+import type { MetricRegistry } from '../metrics/registry.js';
+import { createScopeMiddleware } from '../middleware/scope.js';
+import { collectHealth, type HealthCheckOptions } from './checks.js';
+
+/**
+ * @stable
+ */
+export interface HealthRouteOptions {
+  readonly version: string;
+  readonly startedAt: number;
+  readonly now?: () => number;
+  readonly probes: () => HealthCheckOptions | Promise<HealthCheckOptions>;
+}
+
+/**
+ * Public health route (anonymous; mounted before auth middleware).
+ * Returns the rollup + per-check breakdown; HTTP 200 even when the
+ * rollup is `'degraded'` so liveness probes do not flap on minor
+ * degradations. Only `'failing'` short-circuits with 503.
+ *
+ * @stable
+ */
+export function createExtendedHealthRoutes(
+  options: HealthRouteOptions,
+): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+  const now = options.now ?? Date.now;
+
+  app.get('/', async (c) => {
+    const probes = await options.probes();
+    const summary = await collectHealth(probes);
+    const body = {
+      status: summary.status,
+      version: options.version,
+      uptimeSeconds: Math.max(0, Math.floor((now() - options.startedAt) / 1000)),
+      checks: summary.checks,
+    };
+    if (summary.status === 'failing') {
+      return c.json(body, 503);
+    }
+    return c.json(body, 200);
+  });
+
+  return app;
+}
+
+/**
+ * Authed health route. Mounted at `${base}/health/secrets` AFTER the
+ * auth middleware so the scope check has a verified token to inspect.
+ * Returns the active secrets store + fallback chain + downgrade
+ * reason per the secrets capability matrix.
+ *
+ * @stable
+ */
+export function createSecretsHealthRoutes(): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  app.get('/', createScopeMiddleware('secrets:read'), (c) => {
+    const status = getSecretsStoreStatus();
+    if (status === undefined) {
+      return c.json(
+        {
+          active: 'unknown',
+          fallbackChain: [] as ReadonlyArray<string>,
+          strictMode: false,
+          headlessReasons: [] as ReadonlyArray<string>,
+          message: 'Secrets store has not been activated yet.',
+        },
+        200,
+      );
+    }
+    return c.json(
+      {
+        active: status.active,
+        fallbackChain: [...status.fallbackChain],
+        ...(status.downgradedFrom !== undefined ? { downgradedFrom: status.downgradedFrom } : {}),
+        ...(status.downgradeReason !== undefined
+          ? { downgradeReason: status.downgradeReason }
+          : {}),
+        strictMode: status.strictMode,
+        headlessReasons: [...status.headlessReasons],
+      },
+      200,
+    );
+  });
+
+  return app;
+}
+
+/**
+ * @stable
+ */
+export interface MetricsRoutesOptions {
+  readonly registry: MetricRegistry;
+  readonly requireAuth?: boolean;
+  /**
+   * Optional refresh callback invoked before every scrape. Use it to
+   * sample live signals (WAL size, in-flight runs, daemon status,
+   * replay buffer occupancy) into the registry so the scraped output
+   * reflects the moment of the request.
+   *
+   * Refresh failures are swallowed - a broken probe never blocks a
+   * Prometheus scrape - and surfaced through the optional `onError`
+   * sink.
+   */
+  readonly refresh?: () => void | Promise<void>;
+  readonly onError?: (err: unknown) => void;
+}
+
+/**
+ * @stable
+ */
+export function createMetricsRoutes(
+  options: MetricsRoutesOptions,
+): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+  const handler = async (c: Context<{ Variables: ServerVariables }>) => {
+    if (options.refresh !== undefined) {
+      try {
+        await options.refresh();
+      } catch (err) {
+        options.onError?.(err);
+      }
+    }
+    const body = options.registry.render();
+    c.header('Content-Type', options.registry.contentType());
+    return c.body(body, 200);
+  };
+  if (options.requireAuth === true) {
+    app.get('/', createScopeMiddleware('admin:metrics:read'), handler);
+  } else {
+    app.get('/', handler);
+  }
+  return app;
+}

package/src/index.ts

@@ -0,0 +1,243 @@
+/**
+ * `@graphorin/server` - standalone server runtime for the Graphorin
+ * framework.
+ *
+ * Phase 14a entry point. Ships:
+ *
+ * - {@link createServer} - the single programmatic entry that wires
+ *   the Hono app, the auth + scope + idempotency + audit middleware
+ *   stack, REST endpoints (agents / workflows / sessions / memory /
+ *   skills / mcp / tokens / audit / health), the lifecycle hooks
+ *   (`beforeStart` / `onReady` / `beforeShutdown` / `onError`), the
+ *   pre-bind secrets-resolution + storage-migration runner, and the
+ *   graceful SIGTERM drain.
+ * - {@link defineConfig} + {@link parseServerConfig} - typed
+ *   configuration loader with a Zod-validated schema; missing fields
+ *   fall back to documented production-ready defaults.
+ * - {@link AgentRegistry} + {@link WorkflowRegistry} - read/write
+ *   registries the route handlers consult to look up user-defined
+ *   agents / workflows.
+ * - {@link RunStateTracker} - in-memory bookkeeping for in-flight
+ *   runs (run id, status, AbortController). Phase 14b/c promote the
+ *   tracker to a SQLite-backed durable variant.
+ * - The full middleware factory suite - re-exported from
+ *   `@graphorin/server/middleware` so operators can compose a custom
+ *   Hono app on top of the same primitives.
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export {
+  type CreateServerOptions,
+  createServer,
+  ensureStoreAuditBinding,
+  type GraphorinServer,
+  type TriggersDaemonInput,
+  type WorkflowTimersInput,
+} from './app.js';
+export {
+  createDeliveryCommentarySanitizer,
+  DEFAULT_APPLY_TO_EVENTS,
+  DEFAULT_DELIVERY_COMMENTARY_PATTERNS,
+  type DeliveryCommentaryConfig,
+  type DeliveryCommentaryDecision,
+  type DeliveryCommentaryPattern,
+  type DeliveryCommentaryPolicy,
+  type DeliveryCommentaryReason,
+  type DeliveryCommentarySanitizer,
+  type DeliveryCommentarySink,
+  type DeliveryCommentaryTransport,
+} from './commentary/index.js';
+export {
+  type DeliveryCommentaryPolicyConfig,
+  defineConfig,
+  type IdempotencyRequireKeyMode,
+  parseServerConfig,
+  type SecretRefString,
+  type SecretsSource,
+  type ServerConfigInput,
+  ServerConfigSchema,
+  type ServerConfigSpec,
+} from './config.js';
+export {
+  type ConsolidatorDaemon,
+  type ConsolidatorLike,
+  type ConsolidatorStatusLike,
+  type CreateConsolidatorDaemonOptions,
+  createConsolidatorDaemon,
+} from './consolidator/index.js';
+export * from './errors/index.js';
+export {
+  type BaseHealthCheck,
+  type ConsolidatorCheck,
+  collectHealth,
+  createExtendedHealthRoutes,
+  createMetricsRoutes,
+  createSecretsHealthRoutes,
+  type EmbedderCheck,
+  type EncryptionCheck,
+  type HealthCheck,
+  type HealthCheckOptions,
+  type HealthChecks,
+  type HealthRollup,
+  type HealthRouteOptions,
+  type HealthStatus,
+  type HealthSummary,
+  type MetricsRoutesOptions,
+  type ReplayBufferCheck,
+  type ReplayBufferProbe,
+  rollup,
+  type SecretsCheck,
+  type StorageCheck,
+  type TriggersCheck,
+} from './health/index.js';
+export type { RequestToken, ServerRequestState, ServerVariables } from './internal/context.js';
+export {
+  type BeforeShutdownContext,
+  type BeforeStartContext,
+  type LifecycleHooks,
+  type OnErrorContext,
+  type OnReadyContext,
+  type PreBindResult,
+  type RunPreBindOptions,
+  runPreBind,
+} from './lifecycle/index.js';
+export {
+  createServerMetricRegistry,
+  type LabelSet,
+  type MetricKind,
+  MetricRegistry,
+  SERVER_METRIC_NAMES,
+} from './metrics/index.js';
+export { syncToolCounters } from './metrics/tools-bridge.js';
+export {
+  type AuditErrorSink,
+  type AuditMiddlewareOptions,
+  type AuthMiddlewareOptions,
+  createAuditMiddleware,
+  createAuthMiddleware,
+  createCorsMiddleware,
+  createCsrfMiddleware,
+  createIdempotencyMiddleware,
+  createRateLimitMiddleware,
+  createRequestStateMiddleware,
+  createScopeMiddleware,
+  HTTP_REQUEST_AUDIT_ACTION,
+  type IdempotencyMiddlewareOptions,
+  type RequestStateMiddlewareOptions,
+  type ScopeRequirement,
+} from './middleware/index.js';
+export {
+  type AgentRegistration,
+  AgentRegistry,
+  type AgentSummary,
+  type ServerAgentLike,
+  type ServerWorkflowLike,
+  type WorkflowRegistration,
+  WorkflowRegistry,
+  type WorkflowSummary,
+} from './registry/index.js';
+export {
+  createReplayRoutes,
+  type ReplayApi,
+  type ReplayMode,
+  type ReplayResponse,
+  type ReplayRoutesDeps,
+} from './replay/index.js';
+export {
+  type AgentRoutesDeps,
+  type AuditApi,
+  type AuditRoutesDeps,
+  type AuthRoutesDeps,
+  createAgentRoutes,
+  createAuditRoutes,
+  createAuthRoutes,
+  createHealthRoutes,
+  createMcpRoutes,
+  createMemoryRoutes,
+  createRunRoutes,
+  createSessionRoutes,
+  createSkillsRoutes,
+  createTokensRoutes,
+  createWorkflowRoutes,
+  type HealthRoutesDeps,
+  type McpApi,
+  type McpRoutesDeps,
+  type MemoryApi,
+  type MemoryRoutesDeps,
+  type SessionApi,
+  type SessionRoutesDeps,
+  type SkillsApi,
+  type SkillsRoutesDeps,
+  type TokensRoutesDeps,
+  type WorkflowRoutesDeps,
+} from './routes/index.js';
+export {
+  createConsoleRetentionLog,
+  type RetentionConfig,
+  type RetentionLog,
+  type RetentionLogLevel,
+  type RetentionStoreLike,
+  type ScheduleRetentionOptions,
+  scheduleRetentionSweeps,
+} from './runtime/retention.js';
+export {
+  type RunDescriptor,
+  type RunHandle,
+  type RunStateSnapshot,
+  RunStateTracker,
+  type RunStatus,
+} from './runtime/run-state.js';
+export { createSseRoutes, type SseRoutesDeps } from './sse/index.js';
+export {
+  bridgeToolAuditToAudit,
+  type ToolAuditBridge,
+  type ToolEventsAuditPolicy,
+  toolAuditEventToAuditInput,
+} from './tools-audit-bridge.js';
+export {
+  type CreateTriggersDaemonOptions,
+  createTriggersDaemon,
+  createTriggersRoutes,
+  defaultCatchupPolicy,
+  type TriggersDaemon,
+  type TriggersDaemonMetrics,
+  type TriggersDaemonStatus,
+  type TriggersRoutesDeps,
+} from './triggers/index.js';
+export {
+  type CreateWorkflowTimerDaemonOptions,
+  createWorkflowTimerDaemon,
+  type WorkflowTimerDaemon,
+  type WorkflowTimerDaemonStatus,
+  type WorkflowTimerDriverLike,
+} from './workflows/timer-daemon.js';
+export {
+  type BareEventFrame,
+  createReplayBuffer,
+  createWsDispatcher,
+  createWsTicketStore,
+  createWsUpgradeEvents,
+  type ParsedSubject,
+  type ReplayBuffer,
+  type ReplayBufferOptions,
+  type ReplayBufferSlice,
+  requiredScopeFor,
+  type SubscribeResult,
+  tryParseSubject,
+  type WsDispatcher,
+  type WsDispatcherOptions,
+  type WsDispatcherWarning,
+  type WsSubscriberHandle,
+  type WsSubscriptionSnapshot,
+  type WsTicket,
+  type WsTicketConsumeResult,
+  type WsTicketStore,
+  type WsTicketStoreOptions,
+  type WsUpgradeOptions,
+} from './ws/index.js';

package/src/internal/context.ts

@@ -0,0 +1,77 @@
+/**
+ * Per-request context shape stored on the Hono `c.var` slot. Consumers
+ * (route handlers, audit middleware, idempotency middleware) read these
+ * fields through type-safe accessors defined in this module.
+ *
+ * @packageDocumentation
+ */
+
+import type { ParsedScope, VerifiedToken } from '@graphorin/security/auth';
+
+/**
+ * Discriminator for the request authentication state.
+ *
+ * @stable
+ */
+export type AuthState =
+  | { readonly kind: 'unauthenticated' }
+  | {
+      readonly kind: 'token';
+      readonly token: VerifiedToken;
+      readonly grantedScopes: ReadonlyArray<ParsedScope>;
+    }
+  // IP-13: authentication is disabled server-wide (`auth.kind = 'none'`,
+  // the documented trusted-loopback / single-operator mode). There is no
+  // token, but the request is fully authorized - `grantedScopes` carries
+  // `admin:*` so every scope check passes uniformly.
+  | {
+      readonly kind: 'anonymous';
+      readonly grantedScopes: ReadonlyArray<ParsedScope>;
+    };
+
+/**
+ * Request-scoped variables surfaced through `c.var` in Hono. The
+ * server's middleware populates these fields incrementally; route
+ * handlers consume them through `getRequestState`.
+ *
+ * @stable
+ */
+export interface ServerRequestState {
+  readonly requestId: string;
+  readonly receivedAt: number;
+  readonly clientIp: string | undefined;
+  readonly auth: AuthState;
+  readonly idempotencyKey?: string;
+  readonly idempotencyReplay?: boolean;
+}
+
+/**
+ * Convenience snapshot of the verified token surfaced on `c.var.token`
+ * once the auth middleware has resolved the bearer credential. Mirrors
+ * the contract documented in the runtime architecture (Phase 14a §
+ * Authentication / authorization middleware: "populates `c.var.token:
+ * { id, label, scopes, env }`").
+ *
+ * Read this through `getRequestToken` so consumers do not have
+ * to remember the variable key.
+ *
+ * @stable
+ */
+export interface RequestToken {
+  readonly id: string;
+  readonly label: string | undefined;
+  readonly scopes: ReadonlyArray<ParsedScope>;
+  readonly env: string;
+  readonly expiresAt: number | undefined;
+}
+
+/**
+ * Hono variable map. Exported so consumers can type their own
+ * middleware against the same surface.
+ *
+ * @stable
+ */
+export interface ServerVariables extends Record<string, unknown> {
+  readonly state: ServerRequestState;
+  readonly token?: RequestToken;
+}

package/src/internal/ids.ts

@@ -0,0 +1,17 @@
+/**
+ * Tiny id helpers shared across middleware + routes.
+ *
+ * @internal
+ */
+
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Generate an opaque per-request id. UUID v4 keeps the surface area
+ * minimal - operators that already pin a different scheme (Datadog
+ * trace ids, AWS request ids, …) can override the generator on
+ * `createServer({ requestIdGenerator })`.
+ */
+export function newRequestId(): string {
+  return randomUUID();
+}

package/src/internal/json.ts

@@ -0,0 +1,47 @@
+/**
+ * Helpers for the strict JSON contract every REST endpoint speaks.
+ *
+ * @internal
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Stable, recursive JSON canonicalisation: object keys sorted
+ * lexicographically, arrays preserved as-is. Used by the idempotency
+ * middleware so two semantically-identical bodies produce the same
+ * fingerprint.
+ */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+function canonicalize(value: unknown): unknown {
+  if (value === null) return null;
+  if (typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  );
+  const out: Record<string, unknown> = {};
+  for (const [key, val] of entries) out[key] = canonicalize(val);
+  return out;
+}
+
+/**
+ * SHA-256 hex digest of the supplied bytes. Returns the lowercase
+ * hex string so it can be compared against the persisted fingerprint
+ * without further normalisation.
+ */
+export function sha256Hex(input: string | Uint8Array): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+/**
+ * SHA-256 fingerprint of a (method, path, body) tuple. The body is
+ * canonicalised before hashing so trivial whitespace differences do
+ * not register as a payload mismatch.
+ */
+export function fingerprintRequest(method: string, path: string, body: unknown): string {
+  return sha256Hex(`${method.toUpperCase()} ${path}\n${canonicalJson(body)}`);
+}

package/src/internal/wire-error.ts

@@ -0,0 +1,44 @@
+/**
+ * W-052: machine-readable error envelope for the server boundary.
+ *
+ * The packages disagree on the error discriminator by history:
+ * `@graphorin/agent` / `@graphorin/workflow` use `code`,
+ * `@graphorin/tools` / `@graphorin/memory` / `@graphorin/provider` /
+ * the server's own errors use `kind`. Renaming either family is a
+ * breaking change to no benefit - NORMALIZATION IS THE SERVER
+ * BOUNDARY'S JOB. Every wire payload that reports a failure funnels
+ * through {@link toWireError}, so clients branch on one stable `code`
+ * field (e.g. retry `checkpoint-version-conflict`, abandon
+ * `node-execution-failed`) instead of parsing English prose.
+ *
+ * @packageDocumentation
+ */
+
+/** Normalized error envelope for wire payloads. */
+export interface WireError {
+  /** `err.code` if a string, else `err.kind` if a string, else `'unknown'`. */
+  readonly code: string;
+  readonly message: string;
+  /** Operator hint when the source error carries one (`WorkflowError.hint`). */
+  readonly hint?: string;
+}
+
+/** Normalize any thrown value into the wire envelope (W-052). */
+export function toWireError(err: unknown): WireError {
+  if (err !== null && typeof err === 'object') {
+    const rec = err as { code?: unknown; kind?: unknown; message?: unknown; hint?: unknown };
+    const code =
+      typeof rec.code === 'string' && rec.code.length > 0
+        ? rec.code
+        : typeof rec.kind === 'string' && rec.kind.length > 0
+          ? rec.kind
+          : 'unknown';
+    const message = typeof rec.message === 'string' ? rec.message : String(err);
+    return {
+      code,
+      message,
+      ...(typeof rec.hint === 'string' && rec.hint.length > 0 ? { hint: rec.hint } : {}),
+    };
+  }
+  return { code: 'unknown', message: String(err) };
+}

package/src/lifecycle/hooks.ts

@@ -0,0 +1,66 @@
+/**
+ * Lifecycle hook contract used by `createServer({...})`. Hooks fire
+ * in the documented order:
+ *
+ *   beforeStart -> pre-bind -> migrations -> bind -> onReady
+ *
+ * On shutdown:
+ *
+ *   SIGTERM -> beforeShutdown -> drain -> onError? -> exit
+ *
+ * @packageDocumentation
+ */
+
+import type { ServerConfigSpec } from '../config.js';
+
+/**
+ * Snapshot passed to {@link LifecycleHooks.beforeStart}.
+ *
+ * @stable
+ */
+export interface BeforeStartContext {
+  readonly config: ServerConfigSpec;
+}
+
+/**
+ * Snapshot passed to {@link LifecycleHooks.onReady}.
+ *
+ * @stable
+ */
+export interface OnReadyContext {
+  readonly config: ServerConfigSpec;
+  readonly listeningOn: { readonly host: string; readonly port: number };
+}
+
+/**
+ * Snapshot passed to {@link LifecycleHooks.beforeShutdown}.
+ *
+ * @stable
+ */
+export interface BeforeShutdownContext {
+  readonly config: ServerConfigSpec;
+  readonly inflight: number;
+  readonly drainTimeoutMs: number;
+}
+
+/**
+ * Snapshot passed to {@link LifecycleHooks.onError}. Errors raised
+ * outside the request hot path (lifecycle, audit append, etc.) flow
+ * here so operators can fan them into Sentry / Datadog / etc.
+ *
+ * @stable
+ */
+export interface OnErrorContext {
+  readonly error: unknown;
+  readonly phase: 'beforeStart' | 'onReady' | 'beforeShutdown' | 'request' | 'background';
+}
+
+/**
+ * @stable
+ */
+export interface LifecycleHooks {
+  readonly beforeStart?: (ctx: BeforeStartContext) => void | Promise<void>;
+  readonly onReady?: (ctx: OnReadyContext) => void | Promise<void>;
+  readonly beforeShutdown?: (ctx: BeforeShutdownContext) => void | Promise<void>;
+  readonly onError?: (ctx: OnErrorContext) => void | Promise<void>;
+}

package/src/lifecycle/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Public lifecycle surface for `@graphorin/server`. Re-exports the
+ * hook contract + the pre-bind helper so consumers can wire bespoke
+ * lifecycles around the standard server.
+ *
+ * @packageDocumentation
+ */
+
+export type {
+  BeforeShutdownContext,
+  BeforeStartContext,
+  LifecycleHooks,
+  OnErrorContext,
+  OnReadyContext,
+} from './hooks.js';
+export { type PreBindResult, type RunPreBindOptions, runPreBind } from './pre-bind.js';