@graphoria/server 0.4.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

@@ -20,11 +20,17 @@ 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,
@@ -36,6 +42,12 @@ 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 };
@@ -46,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();
@@ -71,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,
 });
 
 /**
@@ -92,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(
@@ -330,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);
@@ -352,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,
-            })),
-          });
+    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;
+          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 }] });
+          if (message === "Invalid username or password") {
+            return new S401({ errors: [{ message }] });
+          } else {
+            return new S400({ errors: [{ message }] });
+          }
         }
-      }
-    },
+      }),
+    ),
   };
 
   const aiEnabled = projectConfiguration.ai?.enabled ?? false;
@@ -454,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);
-
-    try {
-      const { rest, session, limit } = await getRoleHandlers(req, server);
-      if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
+  routes[`${prefixes.rest}/*`] = withHttpTracing(
+    "rest",
+    withHttpMetrics("rest", async (req: BunRequest, server: Bun.Server<unknown>) => {
+      if (req.method === "OPTIONS" && env.enableCors) return new S200(null);
 
-      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/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,
+  };
+};

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;
+      }
+    });
+  };