@graphoria/server 0.3.0 → 0.5.0

package/src/configuration/gql/handleGraphQLRequestFactory.ts

@@ -12,11 +12,12 @@ import type { SessionContext } from "../../utils/sessionVariables";
 
 import { analyzeQuery } from "../../analyzeQuery";
 import { checkQueryCost } from "../../analyzeQuery/costLimit";
-import { depthLimitRule } from "../../analyzeQuery/depthLimit";
+import { depthLimitRule, isDepthLimitError } from "../../analyzeQuery/depthLimit";
 import { resolveVariableRef, resolveVariables } from "../../analyzeQuery/resolveVariables";
 import { callStoredProcedure, executeQueryJSON, generateSQL } from "../../databases";
 import { proxyRemoteField } from "../../remoteSchemas/proxy";
 import { getAgent } from "../../singletons/ai";
+import { actorFromSession, audit } from "../../logging/audit";
 import { databasesConnections, repositoryMap } from "../../singletons/databases";
 import { env } from "../../singletons/env";
 import { queueManager } from "../../singletons/queues";
@@ -24,6 +25,8 @@ import { EntitySource } from "../../types/resolver";
 import { filterResultBySelection } from "../../utils/selection";
 import { handleAuthMeQuery, handleAuthMutation } from "./gqlAuthOperations";
 import { logger } from "../../logging";
+import { incMetric, isMetricsEnabled, observeMetric } from "../../observability/metrics";
+import { startSpan, withActiveSpan } from "../../observability/tracing";
 
 // Handle GraphQL query
 export const handleGraphQLRequestFactory = (
@@ -44,7 +47,7 @@ export const handleGraphQLRequestFactory = (
       ) => Promise<{ data: object }>
     >
   > = {
-    [EntitySource.QUEUE_PUBLISHER]: async (field, variables) => {
+    [EntitySource.QUEUE_PUBLISHER]: async (field, variables, _queryAnalysis, _req, session) => {
       const data = resolveVariableRef(variables, field.arguments?.data);
 
       const publisher = entities.queuesMap[field.name];
@@ -53,6 +56,12 @@ export const handleGraphQLRequestFactory = (
         throw new Error(`Queue publisher not found: ${field.name}`);
       }
 
+      audit().emit({
+        action: "queue.publish",
+        actor: actorFromSession(session),
+        target: { kind: "publisher", name: publisher.resolverName },
+      });
+
       return {
         data: {
           [field.alias || field.name]: await queueManager?.sendMessage(
@@ -100,7 +109,7 @@ export const handleGraphQLRequestFactory = (
       };
     },
 
-    [EntitySource.STORED_PROCEDURE]: async (field, variables, queryAnalysis) => {
+    [EntitySource.STORED_PROCEDURE]: async (field, variables, queryAnalysis, _req, session) => {
       const sp = entities.mutationsMap[field.name];
 
       if (!sp) {
@@ -116,8 +125,15 @@ export const handleGraphQLRequestFactory = (
 
       const result = await callStoredProcedure(
         sp,
-        queryAnalysis.operations[0].variables ?? [],
         argumentsReplaced as Record<string, string | number | boolean | null>,
+        {
+          operation: {
+            type: "mutation",
+            name: queryAnalysis.operations[0]?.name ?? null,
+            fields: [field.name],
+          },
+          role: session?.role,
+        },
       );
 
       return {
@@ -230,6 +246,7 @@ export const handleGraphQLRequestFactory = (
     ) => {
       const enforceDepthLimit = options?.enforceDepthLimit ?? true;
       const enforceCostLimit = options?.enforceCostLimit ?? true;
+      let costRejected = false;
       const entry = getCacheEntry(query);
       // Unparseable queries aren't cached; let parse surface the syntax error
       const document = entry?.document ?? parse(query);
@@ -257,7 +274,20 @@ export const handleGraphQLRequestFactory = (
           env.maxQueryCost,
         );
 
-        if (costError) validationErrors = [costError];
+        if (costError) {
+          validationErrors = [costError];
+          costRejected = true;
+        }
+      }
+
+      if (validationErrors.length > 0) {
+        incMetric("graphoria_graphql_rejections_total", {
+          reason: costRejected
+            ? "cost"
+            : validationErrors.some(isDepthLimitError)
+              ? "depth"
+              : "validation",
+        });
       }
 
       return {
@@ -289,180 +319,243 @@ export const handleGraphQLRequestFactory = (
       const startTime = Bun.nanoseconds();
 
       // Reuse cached analysis on repeated identical queries
+      const analyzeSpan = startSpan("graphoria.analyze");
       const entry = isString(query) ? getCacheEntry(query) : undefined;
       let queryAnalysis: AnalysisResult;
       if (entry?.analysis) {
         queryAnalysis = entry.analysis;
+        analyzeSpan?.setAttribute("graphoria.analysis.cached", true);
       } else {
         queryAnalysis = isString(query) ? analyzeQuery(query, entities, gqlEntities.schema) : query;
         if (entry) entry.analysis = queryAnalysis;
+        analyzeSpan?.setAttribute("graphoria.analysis.cached", false);
       }
+      analyzeSpan?.end();
 
       if (queryAnalysis.operations.length === 0) {
         return { data: {} };
       }
 
       const operation = queryAnalysis.operations[0];
-      log.debug(
-        {
-          operation: operation.operation,
-          name: operation.name,
-          fieldCount: operation.fields?.length,
-          queryLength: isString(query) ? query.length : undefined,
-        },
-        "graphql request",
-      );
-
-      // Single pass: validate, flatten object vars, resolve field args + session vars
-      // Returns an immutable ResolvedOperation — original operation is not mutated
-      const resolved = resolveVariables(operation, variables, session);
-
-      if (operation.operation === "query") {
-        // Separate auth fields, remote schema fields, and table fields
-        const authFields = resolved.fields.filter((field) => field.source === EntitySource.AUTH);
-        const remoteFields = resolved.fields.filter(
-          (field) => field.source === EntitySource.REMOTE_SCHEMA,
-        );
-        const aiFields = resolved.fields.filter((field) => field.source === EntitySource.AI);
-        const tableFields = resolved.fields.filter(
-          (field) =>
-            field.source !== EntitySource.AUTH &&
-            field.source !== EntitySource.REMOTE_SCHEMA &&
-            field.source !== EntitySource.AI,
+      // An anonymous operation is named by its root fields, exactly as the slow
+      // query log names one: the document itself would carry inline literals,
+      // which are caller data.
+      const operationName =
+        operation.name ?? (operation.fields ?? []).map((field) => field.name).join(",");
+      const role = session?.role ?? "anonymous";
+      const recordOperation = (outcome: "success" | "error") => {
+        if (!isMetricsEnabled()) return;
+        const labels = {
+          operation: operationName,
+          type: operation.operation,
+          role,
+        };
+        incMetric("graphoria_graphql_operations_total", { ...labels, outcome });
+        observeMetric(
+          "graphoria_graphql_operation_duration_seconds",
+          labels,
+          (Bun.nanoseconds() - startTime) / 1e9,
         );
+      };
+      let outcome: "success" | "error" = "success";
+      const span = startSpan(`${operation.operation} ${operationName}`, {
+        attributes: {
+          "graphql.operation.name": operationName,
+          "graphql.operation.type": operation.operation,
+          "graphoria.role": role,
+        },
+      });
 
-        // Handle auth queries (e.g. auth_me)
-        let authData: Record<string, unknown> = {};
-        for (const field of authFields) {
-          Object.assign(authData, handleAuthMeQuery(field, session));
-        }
-
-        // Handle remote schema queries in parallel
-        let remoteData: Record<string, unknown> = {};
-        if (remoteFields.length > 0) {
-          const remoteResults = await Promise.all(
-            remoteFields.map(async (field) => {
-              const entry = entities.remoteQueriesMap[field.name];
-              if (!entry) {
-                throw new Error(`Remote schema query not found: ${field.name}`);
-              }
-              const result = await proxyRemoteField(
-                field,
-                entry.remoteSchema,
-                entry.originalFieldName,
-                resolved.allVariables,
-                "query",
-                req,
-              );
-              return { [field.alias || field.name]: result };
-            }),
-          );
-          remoteData = remoteResults.reduce((acc, curr) => Object.assign(acc, curr), {});
-        }
-
-        // Handle AI agent queries (admin-only `ask` field)
-        let aiData: Record<string, unknown> = {};
-        for (const field of aiFields) {
-          const alias = field.alias || field.name;
-          const prompt = field.arguments?.prompt;
-          aiData[alias] = await getAgent()(String(prompt ?? ""));
-        }
-
-        // Skip SQL generation if there are no table fields
-        if (tableFields.length === 0) {
+      // The span is entered rather than passed: the statements this operation
+      // runs reach the executor through call chains that carry no span, and the
+      // async context is what joins them to this one.
+      return withActiveSpan(span, async () => {
+        try {
           log.debug(
-            { durationMs: (Bun.nanoseconds() - startTime) / 1e6 },
-            "graphql request completed (no table fields)",
-          );
-          return { data: { ...authData, ...remoteData, ...aiData } };
-        }
-
-        const tableQueryAnalysis = {
-          ...queryAnalysis,
-          operations: [
             {
-              ...operation,
-              fields: tableFields,
-              variables: resolved.variables,
+              operation: operation.operation,
+              name: operation.name,
+              fieldCount: operation.fields?.length,
+              queryLength: isString(query) ? query.length : undefined,
             },
-          ],
-        };
+            "graphql request",
+          );
 
-        const sqlQueries = generateSQL(
-          entities,
-          tableQueryAnalysis,
-          resolved.allVariables,
-          false,
-          (options?.enforcePageLimits ?? true) ? pageLimits : null,
-          options?.timeoutMs,
-        );
+          // Single pass: validate, flatten object vars, resolve field args + session vars
+          // Returns an immutable ResolvedOperation — original operation is not mutated
+          const resolved = resolveVariables(operation, variables, session);
 
-        const data = await Promise.all<object>(
-          sqlQueries.map(([db, query]) =>
-            executeQueryJSON(
-              query,
-              db,
-              resolved.variables,
-              resolved.allVariables as Record<string, string | number | boolean | null>,
-              options?.timeoutMs,
-            ),
-          ),
-        );
+          if (operation.operation === "query") {
+            // Separate auth fields, remote schema fields, and table fields
+            const authFields = resolved.fields.filter(
+              (field) => field.source === EntitySource.AUTH,
+            );
+            const remoteFields = resolved.fields.filter(
+              (field) => field.source === EntitySource.REMOTE_SCHEMA,
+            );
+            const aiFields = resolved.fields.filter((field) => field.source === EntitySource.AI);
+            const tableFields = resolved.fields.filter(
+              (field) =>
+                field.source !== EntitySource.AUTH &&
+                field.source !== EntitySource.REMOTE_SCHEMA &&
+                field.source !== EntitySource.AI,
+            );
 
-        log.debug(
-          { durationMs: (Bun.nanoseconds() - startTime) / 1e6, dbCount: sqlQueries.length },
-          "graphql request completed",
-        );
+            // Handle auth queries (e.g. auth_me)
+            let authData: Record<string, unknown> = {};
+            for (const field of authFields) {
+              Object.assign(authData, handleAuthMeQuery(field, session));
+            }
+
+            // Handle remote schema queries in parallel
+            let remoteData: Record<string, unknown> = {};
+            if (remoteFields.length > 0) {
+              const remoteResults = await Promise.all(
+                remoteFields.map(async (field) => {
+                  const entry = entities.remoteQueriesMap[field.name];
+                  if (!entry) {
+                    throw new Error(`Remote schema query not found: ${field.name}`);
+                  }
+                  const result = await proxyRemoteField(
+                    field,
+                    entry.remoteSchema,
+                    entry.originalFieldName,
+                    resolved.allVariables,
+                    "query",
+                    req,
+                  );
+                  return { [field.alias || field.name]: result };
+                }),
+              );
+              remoteData = remoteResults.reduce((acc, curr) => Object.assign(acc, curr), {});
+            }
+
+            // Handle AI agent queries (admin-only `ask` field)
+            let aiData: Record<string, unknown> = {};
+            for (const field of aiFields) {
+              const alias = field.alias || field.name;
+              const prompt = String(field.arguments?.prompt ?? "");
+              audit().emit({
+                action: "ai.ask",
+                actor: actorFromSession(session),
+                target: { kind: "ai", via: "graphql" },
+                prompt,
+              });
+              aiData[alias] = await getAgent()(prompt);
+            }
+
+            // Skip SQL generation if there are no table fields
+            if (tableFields.length === 0) {
+              log.debug(
+                { durationMs: (Bun.nanoseconds() - startTime) / 1e6 },
+                "graphql request completed (no table fields)",
+              );
+              return { data: { ...authData, ...remoteData, ...aiData } };
+            }
+
+            const tableQueryAnalysis = {
+              ...queryAnalysis,
+              operations: [
+                {
+                  ...operation,
+                  fields: tableFields,
+                  variables: resolved.variables,
+                },
+              ],
+            };
 
-        return {
-          ...(env.queryOnResponse
-            ? {
-                sqlQueries: sqlQueries.map(([db, query]) => ({
-                  db: db.name,
-                  query,
-                })),
-              }
-            : {}),
-          data: data.reduce((acc, curr) => Object.assign(acc, curr), {
-            ...authData,
-            ...remoteData,
-            ...aiData,
-          }),
-        };
-      } else if (operation.operation === "mutation") {
-        // Route mutation to the appropriate handler based on field source
-        let results: Record<string, object> = {};
+            const sqlQueries = generateSQL(
+              entities,
+              tableQueryAnalysis,
+              resolved.allVariables,
+              false,
+              (options?.enforcePageLimits ?? true) ? pageLimits : null,
+              options?.timeoutMs,
+            );
 
-        for await (const field of resolved.fields) {
-          const source = field.source;
+            const data = await Promise.all<object>(
+              sqlQueries.map(([db, query]) =>
+                executeQueryJSON(
+                  query,
+                  db,
+                  resolved.variables,
+                  resolved.allVariables as Record<string, string | number | boolean | null>,
+                  options?.timeoutMs,
+                  {
+                    operation: {
+                      type: operation.operation,
+                      name: operation.name,
+                      fields: tableFields.map((field) => field.name),
+                    },
+                    role: session?.role,
+                  },
+                ),
+              ),
+            );
 
-          if (source && mutationHandlers[source]) {
-            const result = await mutationHandlers[source]!(
-              field,
-              resolved.allVariables,
-              queryAnalysis,
-              req,
-              session,
+            log.debug(
+              { durationMs: (Bun.nanoseconds() - startTime) / 1e6, dbCount: sqlQueries.length },
+              "graphql request completed",
             );
 
-            results = {
-              ...results,
-              ...result.data,
+            return {
+              ...(env.queryOnResponse
+                ? {
+                    sqlQueries: sqlQueries.map(([db, query]) => ({
+                      db: db.name,
+                      query,
+                    })),
+                  }
+                : {}),
+              data: data.reduce((acc, curr) => Object.assign(acc, curr), {
+                ...authData,
+                ...remoteData,
+                ...aiData,
+              }),
             };
-          }
-        }
+          } else if (operation.operation === "mutation") {
+            // Route mutation to the appropriate handler based on field source
+            let results: Record<string, object> = {};
+
+            for await (const field of resolved.fields) {
+              const source = field.source;
+
+              if (source && mutationHandlers[source]) {
+                const result = await mutationHandlers[source]!(
+                  field,
+                  resolved.allVariables,
+                  queryAnalysis,
+                  req,
+                  session,
+                );
+
+                results = {
+                  ...results,
+                  ...result.data,
+                };
+              }
+            }
 
-        log.debug(
-          { durationMs: (Bun.nanoseconds() - startTime) / 1e6 },
-          "graphql request completed",
-        );
+            log.debug(
+              { durationMs: (Bun.nanoseconds() - startTime) / 1e6 },
+              "graphql request completed",
+            );
 
-        return {
-          data: results,
-        };
-      }
+            return {
+              data: results,
+            };
+          }
 
-      return { data: {} };
+          return { data: {} };
+        } catch (error) {
+          outcome = "error";
+          span?.recordError(error);
+          throw error;
+        } finally {
+          recordOperation(outcome);
+          span?.end();
+        }
+      });
     },
   };
 

package/src/configuration/gql/handleGraphQLSubscriptionFactory.ts

@@ -10,6 +10,7 @@ import { getTokenService } from "../../singletons/authentication";
 import { createSubscriptionStrategyRegistry, getStrategyForSource } from "../../subscriptions";
 import { createQueryEventEmitter } from "../../utils/event-emitter";
 import { logger } from "../../logging";
+import { audit } from "../../logging/audit";
 
 export const queryEventEmitter = createQueryEventEmitter();
 
@@ -60,6 +61,14 @@ const handleGraphQLSubscriptionFactory = (
 
         subscriptionMapping.set(ws, session);
 
+        if (session.authMethod === "admin_secret") {
+          audit().emit({
+            action: "admin_secret.used",
+            actor: { type: "admin_secret", ip: ws.remoteAddress },
+            target: { kind: "websocket" },
+          });
+        }
+
         logger("subscriptions").debug({ role: session.role }, "client connected");
 
         ws.send(

package/src/configuration/rest/generateOpenAPI.ts

@@ -1,38 +1,77 @@
+import { GraphQLObjectType } from "graphql";
+
+import type { GraphQLType } from "graphql";
 import type { OpenAPIV3_1 } from "openapi-types";
 import type { SelectionAnalysis } from "../../analyzeQuery/types";
 import type { GetSchemaReturn } from "../../configuration/getSchemas";
 import type { RemoteRESTResolved } from "../../remoteREST/types";
 import type { Env } from "../../types/env";
 
+import { getFieldType, unwrapType } from "../../analyzeQuery/typeUtils";
 import { convertFromZod, errors } from "./openApiErrors";
 
+// Deliberately coarse: Int and Float both map to "number", so a column keeps
+// the OpenAPI type it had when types were read off the SQL data type.
+const openApiTypeOf = (namedType: GraphQLType | undefined) => {
+  const name = namedType && "name" in namedType ? namedType.name : undefined;
+
+  switch (name) {
+    case "Int":
+    case "Float":
+      return "number";
+    case "Boolean":
+      return "boolean";
+    default:
+      return "string";
+  }
+};
+
+const resolveFieldType = (parentType: GraphQLObjectType | undefined, fieldName: string) => {
+  const fieldType = parentType && getFieldType(parentType, fieldName);
+  const namedType = fieldType ? unwrapType(fieldType).type : undefined;
+
+  return {
+    namedType,
+    objectType: namedType instanceof GraphQLObjectType ? namedType : undefined,
+  };
+};
+
+/**
+ * Resolves selections against the GraphQL schema rather than against a table
+ * name. `<table>_aggregate` returns a GroupBy wrapper whose fields — `key`,
+ * `count`, `items`, `min`/`max`/`sum`/`avg` — are not tables, so looking a
+ * selection's parent name up in the entity map typed everything under an
+ * aggregate as a string. Walking the schema also makes sanitised column names
+ * resolve, since the schema is what the client actually queries.
+ */
 const processSelections = (
-  schema: GetSchemaReturn,
-  name: string,
-  selections: SelectionAnalysis[] = [],
+  parentType: GraphQLObjectType | undefined,
+  fieldParent: SelectionAnalysis,
 ) =>
-  selections.reduce<Record<string, unknown>>((acc, field) => {
-    const type = schema.getColumnTypeForOpenApi(name, field.name);
+  fieldParent.selections?.reduce<Record<string, unknown>>((acc, field) => {
+    const { namedType, objectType } = resolveFieldType(parentType, field.name);
 
     if (field.isArray) {
       acc[field.alias || field.name] = {
         type: "array",
         items: {
           type: "object",
-          properties: processSelections(schema, field.name, field.selections),
+          properties: processSelections(objectType, field),
           required: (field.selections ?? [])
             .filter((f) => f.isRequired)
             .map((f) => f.alias || f.name),
+          nullable: !field.isRequired,
         },
       };
     } else {
       acc[field.alias || field.name] = field.selections
         ? {
             type: "object",
-            properties: processSelections(schema, field.name, field.selections),
+            properties: processSelections(objectType, field),
             required: field.selections.filter((f) => f.isRequired).map((f) => f.alias || f.name),
+            nullable: !field.isRequired,
           }
-        : { type };
+        : { type: openApiTypeOf(namedType), nullable: !field.isRequired };
     }
 
     return acc;
@@ -137,7 +176,12 @@ export const generateOpenAPI = ({
         const responseDataSchema = value.output
           ? convertFromZod(value.output)
           : (() => {
-              const fields = value.queryStructure!.operations[0].fields;
+              const operation = value.queryStructure!.operations[0];
+              const fields = operation.fields;
+              const rootType =
+                (operation.operation === "mutation"
+                  ? schema.schema.getMutationType()
+                  : schema.schema.getQueryType()) ?? undefined;
               return {
                 type: "object" as const,
                 properties: fields.reduce<Record<string, unknown>>((acc, field) => {
@@ -146,7 +190,10 @@ export const generateOpenAPI = ({
                       type: "array",
                       items: {
                         type: "object",
-                        properties: processSelections(schema, field.name, field.selections!),
+                        properties: processSelections(
+                          resolveFieldType(rootType, field.name).objectType,
+                          field,
+                        ),
                         required: (field.selections ?? [])
                           .filter((f) => f.isRequired)
                           .map((f) => f.alias || f.name),
@@ -155,7 +202,10 @@ export const generateOpenAPI = ({
                   } else {
                     acc[field.alias || field.name] = {
                       type: "object",
-                      properties: processSelections(schema, field.name, field.selections!),
+                      properties: processSelections(
+                        resolveFieldType(rootType, field.name).objectType,
+                        field,
+                      ),
                       required: (field.selections ?? [])
                         .filter((f) => f.isRequired)
                         .map((f) => f.alias || f.name),