@graphoria/server 0.2.2 → 0.3.0

package/src/ai/tools/core.ts

@@ -15,8 +15,10 @@ import type { BunRequest } from "bun";
 import type { GraphQLNamedType, GraphQLSchema } from "graphql";
 import type { GetSchemaReturn } from "../../configuration/getSchemas";
 
+import { checkQueryCost } from "../../analyzeQuery/costLimit";
 import { depthLimitRule } from "../../analyzeQuery/depthLimit";
 import { categorizeSqlType, isNumericType, SqlTypeCategory } from "../../databases/sqlTypeUtils";
+import { env } from "../../singletons/env";
 
 /**
  * A per-role compiled schema bundle (tables, operations, handlers, …).
@@ -202,7 +204,10 @@ export type ValidationError = {
   locations?: ReadonlyArray<{ line: number; column: number }>;
 };
 
-export type ValidateQueryFn = (query: string) => {
+export type ValidateQueryFn = (
+  query: string,
+  variables?: Record<string, unknown>,
+) => {
   hasErrors: boolean;
   validationErrors: readonly ValidationError[];
 };
@@ -211,18 +216,37 @@ export type ValidateQueryFn = (query: string) => {
  * Build a query validator for a role. Without a positive depth limit it
  * delegates to the role's own `hasErrors`; with one it layers a depth-limit
  * rule on the standard rule set.
+ *
+ * The cost budget applies on both branches, and there is no MCP-specific
+ * override for it. MCP gets its own depth knob because an agent legitimately
+ * writes deeper queries than an application does; nothing makes the same
+ * argument for asking a database for more rows.
  */
 export const makeValidateQuery =
   (role: RoleEntities, maxQueryDepth?: number): ValidateQueryFn =>
-  (query) => {
+  (query, variables) => {
     if (maxQueryDepth === undefined || maxQueryDepth <= 0) {
-      return role.handlers.gql.hasErrors(query);
+      return role.handlers.gql.hasErrors(query, { variables });
     }
-    const errors = validate(role.schema, parse(query), [
+    const document = parse(query);
+    const errors = validate(role.schema, document, [
       ...specifiedRules,
       depthLimitRule(maxQueryDepth),
     ]);
-    return { hasErrors: errors.length > 0, validationErrors: errors };
+    if (errors.length > 0) return { hasErrors: true, validationErrors: errors };
+
+    if (env.maxQueryCost > 0) {
+      const costError = checkQueryCost(
+        document,
+        role.schema,
+        variables ?? {},
+        { defaultPageSize: env.defaultPageSize, maxPageSize: env.maxPageSize },
+        env.maxQueryCost,
+      );
+      if (costError) return { hasErrors: true, validationErrors: [costError] };
+    }
+
+    return { hasErrors: false, validationErrors: errors };
   };
 
 // ---- graphql_execute ----
@@ -246,7 +270,7 @@ export const executeGraphqlCore = async (
   try {
     if (containsNonQueryOperation(query)) return { kind: "non_query" };
 
-    const { hasErrors, validationErrors } = validateQuery(query);
+    const { hasErrors, validationErrors } = validateQuery(query, variables);
     if (hasErrors) {
       return {
         kind: "validation",

package/src/analyzeQuery/costLimit.ts

@@ -0,0 +1,236 @@
+import { GraphQLError, GraphQLObjectType, Kind } from "graphql";
+
+import type {
+  DocumentNode,
+  FieldNode,
+  FragmentDefinitionNode,
+  GraphQLSchema,
+  OperationDefinitionNode,
+  SelectionSetNode,
+  ValueNode,
+} from "graphql";
+
+import { collectFragments } from "./fragments";
+import { getFieldType, unwrapType } from "./typeUtils";
+
+/**
+ * Page bounds the estimate is drawn against. `maxPageSize` is carried, not read:
+ * a resolved limit above it is rejected at execution, so the walk never has to
+ * clamp — but the estimator needs it the day that ordering changes.
+ */
+export type CostPageLimits = {
+  defaultPageSize: number;
+  maxPageSize: number;
+};
+
+type WalkContext = {
+  schema: GraphQLSchema;
+  variables: Record<string, unknown>;
+  pageLimits: CostPageLimits;
+  fragments: Map<string, FragmentDefinitionNode>;
+  // A fragment's cost depends only on its own body and type condition, so one
+  // expansion serves every spread of it. Without this a document whose
+  // fragments each spread the next one twice costs 2^n to estimate.
+  fragmentCosts: Map<string, number>;
+};
+
+// Resolve an argument to a number, following a variable into the runtime values.
+// Mirrors `resolveLimitValue` in databases/common.ts so the estimate and the
+// page-size cap agree on what "resolves to a number" means.
+const resolveIntValue = (
+  value: ValueNode | undefined,
+  variables: Record<string, unknown>,
+): number | undefined => {
+  if (!value) return undefined;
+
+  if (value.kind === Kind.INT) return Number.parseInt(value.value, 10);
+
+  if (value.kind === Kind.VARIABLE) {
+    const resolved = variables[value.name.value];
+    return typeof resolved === "number" ? resolved : undefined;
+  }
+
+  return undefined;
+};
+
+// How many rows a field's children are paid for. Only a list field multiplies:
+// a to-one relationship, a single-row field and a scalar each cost their subtree
+// once.
+const multiplierFor = (field: FieldNode, isArray: boolean, ctx: WalkContext): number => {
+  if (!isArray) return 1;
+
+  const limit = field.arguments?.find((argument) => argument.name.value === "limit")?.value;
+
+  return resolveIntValue(limit, ctx.variables) ?? ctx.pageLimits.defaultPageSize;
+};
+
+const objectTypeNamed = (schema: GraphQLSchema, name: string): GraphQLObjectType | undefined => {
+  const type = schema.getType(name);
+  return type instanceof GraphQLObjectType ? type : undefined;
+};
+
+const costOfFragment = (name: string, ctx: WalkContext, onPath: Set<string>): number => {
+  const memoised = ctx.fragmentCosts.get(name);
+  if (memoised !== undefined) return memoised;
+
+  // A fragment already on the path is a cycle. `validate` rejects those before
+  // the estimate runs; cutting here only keeps a hand-built document finite.
+  if (onPath.has(name)) return 0;
+
+  const fragment = ctx.fragments.get(name);
+  if (!fragment) return 0;
+
+  onPath.add(name);
+  const cost = costOfSelectionSet(
+    fragment.selectionSet,
+    objectTypeNamed(ctx.schema, fragment.typeCondition.name.value),
+    ctx,
+    onPath,
+  );
+  onPath.delete(name);
+
+  ctx.fragmentCosts.set(name, cost);
+  return cost;
+};
+
+/**
+ * `cost(field) = 1 + multiplier(field) × Σ cost(child)`, summed across the
+ * selection set. An unresolved parent type costs its children once — the
+ * estimate degrades, it does not throw.
+ */
+const costOfSelectionSet = (
+  selectionSet: SelectionSetNode | undefined,
+  parentType: GraphQLObjectType | undefined,
+  ctx: WalkContext,
+  onPath: Set<string>,
+): number => {
+  if (!selectionSet) return 0;
+
+  let total = 0;
+
+  for (const selection of selectionSet.selections) {
+    switch (selection.kind) {
+      case Kind.FIELD: {
+        if (selection.name.value.startsWith("__")) continue;
+
+        const fieldType = parentType ? getFieldType(parentType, selection.name.value) : undefined;
+        const unwrapped = fieldType ? unwrapType(fieldType) : undefined;
+        const childType = unwrapped?.type instanceof GraphQLObjectType ? unwrapped.type : undefined;
+
+        const children = costOfSelectionSet(selection.selectionSet, childType, ctx, onPath);
+
+        total += 1 + multiplierFor(selection, unwrapped?.isArray ?? false, ctx) * children;
+        break;
+      }
+
+      case Kind.FRAGMENT_SPREAD: {
+        total += costOfFragment(selection.name.value, ctx, onPath);
+        break;
+      }
+
+      case Kind.INLINE_FRAGMENT: {
+        const condition = selection.typeCondition
+          ? objectTypeNamed(ctx.schema, selection.typeCondition.name.value)
+          : parentType;
+
+        total += costOfSelectionSet(selection.selectionSet, condition, ctx, onPath);
+        break;
+      }
+    }
+  }
+
+  return total;
+};
+
+const rootTypeFor = (
+  schema: GraphQLSchema,
+  operation: OperationDefinitionNode,
+): GraphQLObjectType | undefined => {
+  switch (operation.operation) {
+    case "mutation":
+      return schema.getMutationType() ?? undefined;
+    case "subscription":
+      return schema.getSubscriptionType() ?? undefined;
+    default:
+      return schema.getQueryType() ?? undefined;
+  }
+};
+
+const costliestOperation = (
+  document: DocumentNode,
+  schema: GraphQLSchema,
+  variables: Record<string, unknown>,
+  pageLimits: CostPageLimits,
+): { cost: number; operation: OperationDefinitionNode | undefined } => {
+  const ctx: WalkContext = {
+    schema,
+    variables,
+    pageLimits,
+    fragments: collectFragments(document),
+    fragmentCosts: new Map(),
+  };
+
+  let worst: { cost: number; operation: OperationDefinitionNode | undefined } = {
+    cost: 0,
+    operation: undefined,
+  };
+
+  for (const definition of document.definitions) {
+    if (definition.kind !== Kind.OPERATION_DEFINITION) continue;
+
+    const cost = costOfSelectionSet(
+      definition.selectionSet,
+      rootTypeFor(schema, definition),
+      ctx,
+      new Set<string>(),
+    );
+
+    if (cost > worst.cost || worst.operation === undefined) {
+      worst = { cost, operation: definition };
+    }
+  }
+
+  return worst;
+};
+
+/**
+ * Estimate how many rows a document asks a database for, before executing it.
+ *
+ * Every field costs 1 for itself plus the cost of its children multiplied by the
+ * page size it requests — the `limit` argument for a list field, resolved through
+ * `variables`, falling back to `defaultPageSize`; 1 for anything that returns a
+ * single row. Fragment spreads are expanded, so moving a fan-out into a fragment
+ * does not hide it.
+ *
+ * A document carrying several operations is scored by its most expensive one:
+ * a request executes one of them.
+ */
+export const estimateQueryCost = (
+  document: DocumentNode,
+  schema: GraphQLSchema,
+  variables: Record<string, unknown>,
+  pageLimits: CostPageLimits,
+): number => costliestOperation(document, schema, variables, pageLimits).cost;
+
+/**
+ * Reject a document whose estimated cost exceeds `maxCost`. Returns `null` when
+ * it is within budget.
+ */
+export const checkQueryCost = (
+  document: DocumentNode,
+  schema: GraphQLSchema,
+  variables: Record<string, unknown>,
+  pageLimits: CostPageLimits,
+  maxCost: number,
+): GraphQLError | null => {
+  const { cost, operation } = costliestOperation(document, schema, variables, pageLimits);
+
+  if (cost <= maxCost) return null;
+
+  const operationName = operation?.name?.value ?? "anonymous";
+
+  return new GraphQLError(
+    `Estimated query cost of ${cost} exceeds the maximum allowed cost of ${maxCost} (operation: "${operationName}"). Raise MAX_QUERY_COST to allow more expensive queries.`,
+    { nodes: operation ? [operation] : undefined },
+  );
+};

package/src/analyzeQuery/depthLimit.ts

@@ -1,12 +1,8 @@
 import { GraphQLError, Kind } from "graphql";
 
-import type {
-  ASTNode,
-  ASTVisitor,
-  DocumentNode,
-  FragmentDefinitionNode,
-  ValidationContext,
-} from "graphql";
+import type { ASTNode, ASTVisitor, FragmentDefinitionNode, ValidationContext } from "graphql";
+
+import { collectFragments } from "./fragments";
 
 /**
  * Compute the depth of a selection set, resolving fragment spreads.
@@ -68,21 +64,6 @@ function computeDepth(
   return max;
 }
 
-/**
- * Collect all fragment definitions from a document.
- */
-function collectFragments(document: DocumentNode): Map<string, FragmentDefinitionNode> {
-  const fragments = new Map<string, FragmentDefinitionNode>();
-
-  for (const def of document.definitions) {
-    if (def.kind === Kind.FRAGMENT_DEFINITION) {
-      fragments.set(def.name.value, def);
-    }
-  }
-
-  return fragments;
-}
-
 /**
  * GraphQL validation rule that rejects queries exceeding a maximum nesting depth.
  *
@@ -113,7 +94,7 @@ export const depthLimitRule =
 
             context.reportError(
               new GraphQLError(
-                `Query depth of ${depth} exceeds the maximum allowed depth of ${maxDepth} (operation: "${operationName}")`,
+                `Query depth of ${depth} exceeds the maximum allowed depth of ${maxDepth} (operation: "${operationName}"). Raise MAX_QUERY_DEPTH to allow deeper queries.`,
                 { nodes: [def] },
               ),
             );

package/src/analyzeQuery/fragments.ts

@@ -0,0 +1,18 @@
+import { Kind } from "graphql";
+
+import type { DocumentNode, FragmentDefinitionNode } from "graphql";
+
+/**
+ * Collect all fragment definitions from a document.
+ */
+export const collectFragments = (document: DocumentNode): Map<string, FragmentDefinitionNode> => {
+  const fragments = new Map<string, FragmentDefinitionNode>();
+
+  for (const def of document.definitions) {
+    if (def.kind === Kind.FRAGMENT_DEFINITION) {
+      fragments.set(def.name.value, def);
+    }
+  }
+
+  return fragments;
+};

package/src/config/types/auth.ts

@@ -137,6 +137,13 @@ export const RolePermissionZod = z
       .union([z.array(z.string()), z.literal("ALL")])
       .optional()
       .default([]),
+    /** Request ceiling for this role, overriding RATE_LIMIT_MAX. 0 disables it */
+    rateLimit: z
+      .strictObject({
+        max: z.number().int().min(0),
+        windowMs: z.number().int().positive().optional(),
+      })
+      .optional(),
   })
   .default({
     tables: [],

package/src/config/types/db.ts

@@ -168,11 +168,18 @@ export const MSSQLConnectionOptionsZod = z.strictObject({
       min: z.number().int().nonnegative().default(0),
       /** Maximum time in seconds a connection can be idle before being closed */
       idleTimeout: z.number().nonnegative().default(30),
+      /**
+       * Maximum time in seconds to wait for a free connection when the pool is
+       * saturated. Without a bound, a slow-query storm queues callers instead of
+       * failing them. Bun's SQL driver exposes no equivalent, so this is MSSQL only.
+       */
+      acquireTimeout: z.number().positive().default(30),
     })
     .default({
       max: 10,
       min: 0,
       idleTimeout: 30,
+      acquireTimeout: 30,
     }),
   /** Maximum time in seconds to wait when establishing a connection */
   connectionTimeout: z.number().nonnegative().default(30),

package/src/config/types/operation.ts

@@ -108,6 +108,8 @@ export const OperationZod = z
     rest: OperationRestConfigZod.optional(),
     graphql: OperationGraphQLConfigZod.optional().default({ enabled: true }),
     cache: OperationCacheConfigZod.optional(),
+    /** Statement timeout in milliseconds. Overrides QUERY_TIMEOUT_MS for this operation. */
+    timeout: z.number().int().positive().optional(),
   })
   .refine(
     (operation) => {
@@ -249,6 +251,8 @@ export type BaseOperation<TInput, TOutput, TInitData> = {
   graphql?: OperationGraphQLConfig;
   /** Cache configuration */
   cache?: OperationCacheConfig;
+  /** Statement timeout in milliseconds. Overrides `QUERY_TIMEOUT_MS` for this operation. */
+  timeout?: number;
 };
 
 /**