@graphoria/server 0.3.0 → 0.5.0

package/src/databases/high-level-operations.ts

@@ -48,6 +48,44 @@ export const getDatabasesStructure = async (
     // do-not-serve list, so a name spelled in the wrong case served the table.
     const excluded = new Set((db.schema?.excludedTables ?? []).map((name) => name.toLowerCase()));
 
+    // Normalising the ancestor to introspected casing here is what lets the query
+    // builder match it with a plain === against the entity it resolves at runtime.
+    // Resolution is per-database by construction, so a cross-database ancestor
+    // cannot resolve — which is correct, nothing joins across connections.
+    const resolveAncestor = (ancestor: { schema: string; name: string; column: string }) => {
+      const ancestorTable = tables.find(
+        (a) =>
+          `${ancestor.schema}_${ancestor.name}`.toLowerCase() ===
+          `${a.schema}_${a.name}`.toLowerCase(),
+      );
+
+      if (!ancestorTable) {
+        throw new Error(
+          `Ancestor table ${ancestor.schema}_${ancestor.name} not found in database ${db.name}`,
+        );
+      }
+
+      // An excluded table can never appear in a query path, so the condition could
+      // only ever throw at request time. Fail at boot instead.
+      if (excluded.has(ancestorTable.schemaName.toLowerCase())) {
+        throw new Error(
+          `Ancestor table ${ancestor.schema}_${ancestor.name} is in excludedTables and can never be in a query path`,
+        );
+      }
+
+      const column = ancestorTable.columns.find(
+        (c) => c.name.toLowerCase() === ancestor.column.toLowerCase(),
+      );
+
+      if (!column) {
+        throw new Error(
+          `Ancestor column ${ancestor.column} not found in table ${ancestorTable.name}`,
+        );
+      }
+
+      return { schema: ancestorTable.schema, name: ancestorTable.name, column: column.name };
+    };
+
     tableNamesByDatabase[db.name] = tables.map((t) => t.schemaName);
 
     const tablesToAdd = tables
@@ -117,6 +155,10 @@ export const getDatabasesStructure = async (
                 };
               }),
               conditions: (fk.conditions ?? []).map((cond) => {
+                const ancestor = cond.ancestor
+                  ? { ancestor: resolveAncestor(cond.ancestor) }
+                  : undefined;
+
                 if (cond.source !== undefined) {
                   const sourceColumn = t.columns.find(
                     (col) => col.name.toLowerCase() === cond.source!.toLowerCase(),
@@ -126,7 +168,7 @@ export const getDatabasesStructure = async (
                     throw new Error(`Condition column ${cond.source} not found in table ${t.name}`);
                   }
 
-                  return { ...cond, source: sourceColumn.name };
+                  return { ...cond, ...ancestor, source: sourceColumn.name };
                 }
 
                 const targetColumn = toTable.columns.find(
@@ -139,7 +181,7 @@ export const getDatabasesStructure = async (
                   );
                 }
 
-                return { ...cond, target: targetColumn.name };
+                return { ...cond, ...ancestor, target: targetColumn.name };
               }),
             };
           });

package/src/index.ts

@@ -4,8 +4,10 @@ import { serve } from "bun";
 import { isString } from "es-toolkit";
 
 import type { BunRequest } from "bun";
+import type { Capability } from "./authentication/capabilities";
 import type { Configuration } from "./types/configuration";
 import type { Env } from "./types/env";
+import type { SessionContext } from "./utils/sessionVariables";
 
 import { createTokenService } from "./authentication";
 import { analyzeConfiguration, loadConfiguration } from "./configuration";
@@ -14,14 +16,21 @@ import { websocketHandlerFactory } from "./configuration/gql/handleGraphQLSubscr
 import { consoleRoutesFactory } from "./console/api";
 import { createAuthTables, verifyAuthTablesExist } from "./databases";
 import { createMCPRoutes } from "./ai";
+import { createCapabilityAuthorizer } from "./authentication/capabilities";
 import { getAgent, instantiateAI } from "./singletons/ai";
 import { getTokenService, setTokenService } from "./singletons/authentication";
 import { instantiateCronJobs } from "./singletons/cron";
-import { disconnectDatabases, instantiateDatabasesConnections } from "./singletons/databases";
+import {
+  databasesConnections,
+  disconnectDatabases,
+  instantiateDatabasesConnections,
+  pingConnection,
+} from "./singletons/databases";
 import { getCacheRedisClient } from "./singletons/cache/redisClient";
 import { env } from "./singletons/env";
 import { setQueryTimeoutMs } from "./singletons/queryTimeout";
-import { instantiateQueues } from "./singletons/queues";
+import { setSlowQueryMs } from "./logging/slowQuery";
+import { instantiateQueues, queueManager } from "./singletons/queues";
 import { ConfigurationZod } from "./types/zod/configuration";
 import {
   createMemoryRateLimitStore,
@@ -32,6 +41,13 @@ import {
 import { S200, S400, S401, S404, S429 } from "./utils/responses";
 import { writeSchema } from "./utils/writeSchema";
 import { logger, configureLogging } from "./logging";
+import { actorFromSession, audit } from "./logging/audit";
+import { createHealthRoutes } from "./observability/health";
+import { configureMetrics, renderMetrics } from "./observability/metrics";
+import { configureTracing } from "./observability/tracing";
+import { withHttpMetrics } from "./observability/httpMetrics";
+import { withHttpTracing } from "./observability/httpTracing";
+import { createMetricsRoute } from "./observability/metricsRoute";
 
 // Re-export for consumers
 export { configureLogging };
@@ -42,6 +58,8 @@ type RouteHandler =
 
 type RoutesMap = Record<string, RouteHandler | Record<string, RouteHandler>>;
 
+const HEALTH_CHECK_TIMEOUT_MS = 2000;
+
 const renderPlayground = async (filepath: string, replacements: Record<string, string>) => {
   const path = join(import.meta.dir, filepath);
   const content = await Bun.file(path).text();
@@ -67,6 +85,8 @@ const generatePrefixes = (options: Env) => ({
   rest: options.prefix + options.restApiPrefix,
   openapi: options.prefix + options.openApiEndpoint,
   console: options.prefix + options.console.endpoint,
+  health: options.prefix + "/health",
+  metrics: options.prefix + options.metrics.endpoint,
 });
 
 /**
@@ -88,6 +108,18 @@ const bootAnalyzedConfiguration = async (env: Env) => {
   }
 
   setQueryTimeoutMs(env.queryTimeoutMs);
+  setSlowQueryMs(env.slowQueryMs);
+  configureMetrics({
+    enabled: env.metrics.enabled,
+    maxOperationLabels: env.metrics.maxOperationLabels,
+  });
+  configureTracing({
+    enabled: env.tracing.enabled,
+    endpoint: env.tracing.endpoint,
+    headers: env.tracing.headers,
+    serviceName: env.tracing.serviceName,
+    sampleRatio: env.tracing.sampleRatio,
+  });
 
   if (env.queryTimeoutMs === 0) {
     logger("graphoria").warn(
@@ -244,24 +276,52 @@ const createGraphQLServer = async (env: Env) => {
         : createMemoryRateLimitStore(),
   });
 
-  // Helper to get role-based handlers
-  const getRoleHandlers = async (req: Request, server?: Bun.Server<unknown>) => {
-    const session = await getTokenService().verifyTokenAndGetSession(
-      req.headers.get(env.authorizationHeader),
-      req.headers.get(env.admin.header),
-    );
+  const authorizeCapability = createCapabilityAuthorizer(env);
+
+  // Helper to get role-based handlers. A route that names a capability also
+  // accepts that capability's scoped credential in the admin-secret header;
+  // it stands in for the superadmin role on that route and nowhere else.
+  const getRoleHandlers = async (
+    req: Request,
+    server?: Bun.Server<unknown>,
+    capability?: Capability,
+  ) => {
+    const adminSecretHeader = req.headers.get(env.admin.header);
+    const grant = capability ? authorizeCapability(adminSecretHeader, capability) : null;
+
+    const session: SessionContext =
+      grant && !grant.superset
+        ? { sub: capability, role: env.superadmin.role, authMethod: "admin_secret" }
+        : await getTokenService().verifyTokenAndGetSession(
+            req.headers.get(env.authorizationHeader),
+            adminSecretHeader,
+          );
+
+    const ip = resolveClientAddress(req, server, env.rateLimit.trustProxy);
 
     // The limit needs the role, and the role costs a token verification plus a
     // revocation lookup — so it is spent here, once, rather than again inside a
     // wrapper.
-    const limit = await rateLimiter?.check(
-      session,
-      resolveClientAddress(req, server, env.rateLimit.trustProxy),
-    );
+    const limit = await rateLimiter?.check(session, ip);
+
+    const scope: Capability | "all" | undefined = grant
+      ? grant.superset
+        ? "all"
+        : capability
+      : undefined;
+
+    if (session.authMethod === "admin_secret") {
+      audit().emit({
+        action: "admin_secret.used",
+        actor: { type: "admin_secret", ...(scope ? { scope } : {}), ip },
+        target: { kind: "endpoint", method: req.method, path: new URL(req.url).pathname },
+      });
+    }
 
     return {
       role: session.role!,
       session,
+      scope,
       limit,
       ...analyzedConfiguration.roles[session.role!].handlers,
     };
@@ -298,6 +358,51 @@ const createGraphQLServer = async (env: Env) => {
   routes[prefixes.graphiql] = () => html(graphiqlFile);
   routes[prefixes.scalar] = () => html(scalarFile);
 
+  // Probes for an orchestrator: no auth, no rate limit. Redis is a dependency
+  // only where something reads it — the token repository or the redis cache.
+  const redisInUse = projectConfiguration.auth?.enabled || env.cache.store === "redis";
+  Object.assign(
+    routes,
+    createHealthRoutes({
+      basePath: prefixes.health,
+      timeoutMs: HEALTH_CHECK_TIMEOUT_MS,
+      checks: () => [
+        ...analyzedConfiguration.databases.map((database) => ({
+          kind: "database",
+          name: database.name,
+          probe: async () => {
+            const connection = databasesConnections[database.name];
+            if (!connection) return false;
+            await pingConnection(connection, database.type);
+            return true;
+          },
+        })),
+        ...(redisInUse
+          ? [{ kind: "redis", probe: async () => (await getCacheRedisClient().ping()) === "PONG" }]
+          : []),
+        ...(queueManager?.connections() ?? []).map(({ type, name, connected }) => ({
+          kind: type,
+          name,
+          probe: () => connected,
+        })),
+      ],
+    }),
+  );
+
+  // Prometheus exposition, opt-in via METRICS_ENABLED. Gated: the series name
+  // operations, roles and databases.
+  if (env.metrics.enabled) {
+    Object.assign(
+      routes,
+      createMetricsRoute({
+        path: prefixes.metrics,
+        secretHeader: env.admin.header,
+        authorize: (candidate) => authorizeCapability(candidate, "metrics"),
+        render: renderMetrics,
+      }),
+    );
+  }
+
   // Console (admin UI + status APIs), opt-in via CONSOLE_ENABLED
   if (env.console.enabled) {
     const consoleHandler = () => html(consoleHtml);
@@ -320,51 +425,60 @@ const createGraphQLServer = async (env: Env) => {
   // GraphQL endpoint
   routes[prefixes.graphql] = {
     ...(env.enableCors ? { OPTIONS: () => new S200(null) } : {}),
-    GET: withRateLimit(async (req: Request, server: Bun.Server<unknown>) => {
-      try {
-        if (req.headers.get("upgrade") === "websocket") {
-          const success = server.upgrade(req, {
-            data: {},
-          });
-          return success ? undefined : new Response("WebSocket upgrade error", { status: 400 });
-        }
-        return new S404({ error: "Not Found" });
-      } catch (error) {
-        return new S400({ errors: [{ message: (error as Error)?.message }] });
-      }
-    }),
-    POST: async (req: BunRequest, server: Bun.Server<unknown>) => {
-      try {
-        const { gql, session, limit } = await getRoleHandlers(req, server);
-        if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
-
-        const { query, variables } = await req.json();
-
-        if (gql.isIntrospectionQuery(query)) return new S200(gql.introspectionResult);
-
-        if (gql.isNoDataQuery(query)) return new S200(gql.noDataResult);
-
-        const { hasErrors, validationErrors } = gql.hasErrors(query, { variables });
-
-        if (hasErrors)
-          return new S400({
-            errors: validationErrors.map((error) => ({
-              message: error.message,
-              locations: error.locations,
-            })),
-          });
-
-        return new S200(await gql.handler(query, variables, req, session));
-      } catch (error) {
-        const message = (error as Error)?.message;
-
-        if (message === "Invalid username or password") {
-          return new S401({ errors: [{ message }] });
-        } else {
-          return new S400({ errors: [{ message }] });
+    GET: withHttpTracing(
+      "graphql",
+      withHttpMetrics(
+        "graphql",
+        withRateLimit(async (req: Request, server: Bun.Server<unknown>) => {
+          try {
+            if (req.headers.get("upgrade") === "websocket") {
+              const success = server.upgrade(req, {
+                data: {},
+              });
+              return success ? undefined : new Response("WebSocket upgrade error", { status: 400 });
+            }
+            return new S404({ error: "Not Found" });
+          } catch (error) {
+            return new S400({ errors: [{ message: (error as Error)?.message }] });
+          }
+        }),
+      ),
+    ),
+    POST: withHttpTracing(
+      "graphql",
+      withHttpMetrics("graphql", async (req: BunRequest, server: Bun.Server<unknown>) => {
+        try {
+          const { gql, session, limit } = await getRoleHandlers(req, server);
+          if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
+
+          const { query, variables } = await req.json();
+
+          if (gql.isIntrospectionQuery(query)) return new S200(gql.introspectionResult);
+
+          if (gql.isNoDataQuery(query)) return new S200(gql.noDataResult);
+
+          const { hasErrors, validationErrors } = gql.hasErrors(query, { variables });
+
+          if (hasErrors)
+            return new S400({
+              errors: validationErrors.map((error) => ({
+                message: error.message,
+                locations: error.locations,
+              })),
+            });
+
+          return new S200(await gql.handler(query, variables, req, session));
+        } catch (error) {
+          const message = (error as Error)?.message;
+
+          if (message === "Invalid username or password") {
+            return new S401({ errors: [{ message }] });
+          } else {
+            return new S400({ errors: [{ message }] });
+          }
         }
-      }
-    },
+      }),
+    ),
   };
 
   const aiEnabled = projectConfiguration.ai?.enabled ?? false;
@@ -380,7 +494,7 @@ const createGraphQLServer = async (env: Env) => {
         name: projectConfiguration.name,
         version: projectConfiguration.version,
         maxQueryDepth: env.ai?.mcp?.maxQueryDepth ?? env.maxQueryDepth,
-        adminSecret: env.admin.secret,
+        authorize: authorizeCapability,
         adminSecretHeader: env.admin.header,
       });
 
@@ -395,7 +509,7 @@ const createGraphQLServer = async (env: Env) => {
         ...(env.enableCors ? { OPTIONS: () => new S200(null) } : {}),
         POST: async (req: BunRequest, server: Bun.Server<unknown>) => {
           try {
-            const { role, limit } = await getRoleHandlers(req, server);
+            const { role, session, scope, limit } = await getRoleHandlers(req, server, "ai");
             if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
             if (role !== env.superadmin.role) return new S404({ error: "Not Found" });
 
@@ -405,6 +519,13 @@ const createGraphQLServer = async (env: Env) => {
                 errors: [{ message: "`prompt` (string) is required" }],
               });
 
+            audit().emit({
+              action: "ai.ask",
+              actor: { ...actorFromSession(session), ...(scope ? { scope } : {}) },
+              target: { kind: "ai", via: "rest" },
+              prompt,
+            });
+
             return new S200({ answer: await getAgent()(prompt) });
           } catch (error) {
             return new S400({ errors: [{ message: (error as Error)?.message }] });
@@ -415,26 +536,29 @@ const createGraphQLServer = async (env: Env) => {
   }
 
   // REST API endpoint
-  routes[`${prefixes.rest}/*`] = async (req: BunRequest, server: Bun.Server<unknown>) => {
-    if (req.method === "OPTIONS" && env.enableCors) return new S200(null);
+  routes[`${prefixes.rest}/*`] = withHttpTracing(
+    "rest",
+    withHttpMetrics("rest", async (req: BunRequest, server: Bun.Server<unknown>) => {
+      if (req.method === "OPTIONS" && env.enableCors) return new S200(null);
 
-    try {
-      const { rest, session, limit } = await getRoleHandlers(req, server);
-      if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
-
-      const urlParsed = new URL(req.url);
+      try {
+        const { rest, session, limit } = await getRoleHandlers(req, server);
+        if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
 
-      return await rest.handler(
-        urlParsed,
-        urlParsed.pathname.replace(prefixes.rest, ""),
-        req.method,
-        req,
-        session,
-      );
-    } catch {
-      return new S400({ errors: [{ message: "Bad request" }] });
-    }
-  };
+        const urlParsed = new URL(req.url);
+
+        return await rest.handler(
+          urlParsed,
+          urlParsed.pathname.replace(prefixes.rest, ""),
+          req.method,
+          req,
+          session,
+        );
+      } catch {
+        return new S400({ errors: [{ message: "Bad request" }] });
+      }
+    }),
+  );
 
   // Create WebSocket handler
   const websocketHandler = websocketHandlerFactory(analyzedConfiguration.roles);

package/src/logging/audit.ts

@@ -0,0 +1,86 @@
+import type { Logger } from "pino";
+import type { Capability } from "../authentication/capabilities";
+import type { SessionContext } from "../utils/sessionVariables";
+
+import { logger } from "./index";
+
+export type AuditActor = {
+  type: "admin_secret" | "console" | "token" | "credentials" | "anonymous";
+  sub?: string;
+  role?: string;
+  /** Which credential was presented at a scoped surface: `all` is the admin secret. */
+  scope?: Capability | "all";
+  ip?: string | undefined;
+};
+
+export type AuditEvent = {
+  action: string;
+  actor: AuditActor;
+  target: Record<string, unknown>;
+  outcome?: "success" | "failure";
+  [key: string]: unknown;
+};
+
+export type AuditLog = {
+  emit(event: AuditEvent): void;
+};
+
+const REDACTED_KEYS = new Set([
+  "password",
+  "secret",
+  "secrets",
+  "token",
+  "access_token",
+  "refresh_token",
+  "authorization",
+  "cookie",
+]);
+
+const redact = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(redact);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      REDACTED_KEYS.has(key) ? "[REDACTED]" : redact(entry),
+    ]),
+  );
+};
+
+export const actorFromSession = (session: SessionContext | undefined): AuditActor => {
+  if (!session) return { type: "anonymous" };
+  const type =
+    session.authMethod === "admin_secret" ? "admin_secret" : session.jti ? "token" : "anonymous";
+  return {
+    type,
+    ...(session.sub !== undefined ? { sub: session.sub } : {}),
+    ...(session.role !== undefined ? { role: session.role } : {}),
+  };
+};
+
+export const createAuditLog = (base: Logger): AuditLog => {
+  // An audit record has to survive LOG_LEVEL=warn: the level is pinned here,
+  // independent of whatever the root logger was configured with.
+  const log = base.child({});
+  log.level = "info";
+
+  return {
+    emit: (event) => {
+      log.info(redact(event) as object, event.action);
+    },
+  };
+};
+
+let override: AuditLog | null = null;
+let instance: AuditLog | null = null;
+
+/** Test seam: pass `null` to restore the default log. */
+export const setAuditLog = (log: AuditLog | null): void => {
+  override = log;
+};
+
+export const audit = (): AuditLog => {
+  if (override) return override;
+  if (!instance) instance = createAuditLog(logger("audit"));
+  return instance;
+};

package/src/logging/slowQuery.ts

@@ -0,0 +1,59 @@
+import type { Logger } from "pino";
+
+import { logger } from "./index";
+
+/** The GraphQL operation a statement was generated for. Names only, never values. */
+export type QuerySource = {
+  operation: {
+    type: "query" | "mutation" | "subscription";
+    name: string | null;
+    fields: string[];
+  };
+  role?: string | undefined;
+};
+
+export type SlowQueryRecord = {
+  durationMs: number;
+  dbType: string;
+  dbName: string;
+  sql?: string;
+  procedure?: string;
+  outcome: "success" | "error";
+} & Partial<QuerySource>;
+
+export type SlowQueryLog = {
+  emit(record: SlowQueryRecord & { thresholdMs: number }): void;
+};
+
+/**
+ * Resolved from `SLOW_QUERY_MS` at boot. `0` — also the value before boot sets
+ * it — reports nothing, so an executor used outside a booted server stays quiet.
+ */
+let thresholdMs = 0;
+
+export const setSlowQueryMs = (ms: number): void => {
+  thresholdMs = ms;
+};
+
+export const createSlowQueryLog = (base: Logger): SlowQueryLog => ({
+  emit: (record) => base.warn(record, "slow query"),
+});
+
+let override: SlowQueryLog | null = null;
+let instance: SlowQueryLog | null = null;
+
+/** Test seam: pass `null` to restore the default log. */
+export const setSlowQueryLog = (log: SlowQueryLog | null): void => {
+  override = log;
+};
+
+const slowQueryLog = (): SlowQueryLog => {
+  if (override) return override;
+  if (!instance) instance = createSlowQueryLog(logger("slow-query"));
+  return instance;
+};
+
+export const reportQueryDuration = (record: SlowQueryRecord): void => {
+  if (thresholdMs === 0 || record.durationMs <= thresholdMs) return;
+  slowQueryLog().emit({ ...record, thresholdMs });
+};

package/src/observability/health.ts

@@ -0,0 +1,67 @@
+import { logger } from "../logging";
+import { S200, S503 } from "../utils/responses";
+
+export type HealthCheck = {
+  kind: string;
+  name?: string;
+  probe: () => Promise<boolean> | boolean;
+};
+
+export type HealthRoutesOptions = {
+  basePath: string;
+  /** Read on every readiness request, so a check can follow state that changes after boot. */
+  checks: () => HealthCheck[];
+  timeoutMs: number;
+};
+
+const runCheck = async ({ probe }: HealthCheck, timeoutMs: number) => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(probe),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`no answer within ${timeoutMs}ms`)), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * Unauthenticated probes for an orchestrator. Liveness touches nothing, so a
+ * dependency outage never gets the process restarted; readiness pings every
+ * dependency and answers 503 while one is down. The body names each check and
+ * whether it passed — the reason stays in the log, because a driver error can
+ * carry a host and port.
+ */
+export const createHealthRoutes = ({ basePath, checks, timeoutMs }: HealthRoutesOptions) => {
+  const log = logger("health");
+
+  const live = () => new S200({ status: "ok" });
+
+  const ready = async () => {
+    const results = await Promise.all(
+      checks().map(async (check) => {
+        let ok = false;
+        try {
+          ok = (await runCheck(check, timeoutMs)) === true;
+          if (!ok) log.warn({ kind: check.kind, name: check.name }, "readiness check failed");
+        } catch (error) {
+          log.warn({ kind: check.kind, name: check.name, err: error }, "readiness check failed");
+        }
+        return { kind: check.kind, ...(check.name ? { name: check.name } : {}), ok };
+      }),
+    );
+
+    const healthy = results.every((result) => result.ok);
+    const body = { status: healthy ? "ok" : "unavailable", checks: results };
+
+    return healthy ? new S200(body) : new S503(body);
+  };
+
+  return {
+    [`${basePath}/live`]: live,
+    [`${basePath}/ready`]: ready,
+  };
+};