@graphoria/server 0.2.3 → 0.3.0

package/src/databases/engines/mysql/connection.ts

@@ -5,27 +5,44 @@ import type { VariableDefinition } from "../../../analyzeQuery/types";
 import type { Database } from "../../../types/configuration";
 import type { ProcedureResolver } from "../../../types/db";
 
+import { BunSQLConnectionOptionsZod } from "../../../config/types/db";
 import { databasesConnections } from "../../../singletons/databases";
 import { toMySQLPlaceholders } from "./placeholders";
 
-export const getPool = async (db: Database) => {
-  const opts = db.connectionOptions as BunSQLConnectionOptions | undefined;
-  const pool = new SQL({
+// Every pool bound comes from the schema, which is the only place they are
+// declared and documented. Repeating them here as `?? n` fallbacks let the
+// documented default and the applied one drift apart, differently per engine.
+//
+// Defaults are overlaid rather than re-parsed: `connectionOptions` is an
+// undiscriminated union of the two engine shapes, so an object can arrive
+// already validated against the other one, and a strict re-parse would reject
+// it at boot.
+export const poolOptions = (db: Database) => {
+  const opts = {
+    ...BunSQLConnectionOptionsZod.parse({}),
+    ...(db.connectionOptions as BunSQLConnectionOptions | undefined),
+  };
+
+  return {
     host: db.connection.host,
     port: db.connection.port,
     username: db.connection.user,
     password: db.connection.password,
     database: db.connection.database,
-    adapter: "mysql",
-    max: opts?.max ?? 50,
-    idleTimeout: opts?.idleTimeout ?? 30,
-    connectionTimeout: opts?.connectionTimeout,
-    maxLifetime: opts?.maxLifetime,
-    tls: opts?.tls,
-    allowPublicKeyRetrieval: opts?.allowPublicKeyRetrieval,
-    prepare: opts?.prepare,
-    bigint: opts?.bigint,
-  });
+    adapter: "mysql" as const,
+    max: opts.max,
+    idleTimeout: opts.idleTimeout,
+    connectionTimeout: opts.connectionTimeout,
+    maxLifetime: opts.maxLifetime,
+    tls: opts.tls,
+    allowPublicKeyRetrieval: opts.allowPublicKeyRetrieval,
+    prepare: opts.prepare,
+    bigint: opts.bigint,
+  };
+};
+
+export const getPool = async (db: Database) => {
+  const pool = new SQL(poolOptions(db));
 
   await pool.connect(); // Connect to the database
 

package/src/databases/engines/mysql/format.ts

@@ -2,6 +2,7 @@ import { format as sqlFormatter } from "sql-formatter";
 
 import type { AnalysisResult } from "../../../analyzeQuery/types";
 import type { MergedEntities } from "../../../configuration/getSchemas/mergeEntities";
+import type { PageLimits } from "../../common";
 
 import { generateSQL } from "../../core/query-builder";
 
@@ -16,8 +17,9 @@ export const genSql = (
   query: AnalysisResult,
   variables: Record<string, unknown> = {},
   hash = false,
+  pageLimits: PageLimits | null = null,
 ) => {
-  const [[, sql]] = generateSQL(entitites, query, variables, hash);
+  const [[, sql]] = generateSQL(entitites, query, variables, hash, pageLimits);
 
   return format(sql);
 };

package/src/databases/engines/mysql/query/index.ts

@@ -4,7 +4,7 @@ import type {
   VariableDefinition,
 } from "../../../../analyzeQuery/types";
 import type { MergedEntities } from "../../../../configuration/getSchemas/mergeEntities";
-import type { GroupByInfo } from "../../../common";
+import type { GroupByInfo, PageLimits } from "../../../common";
 
 import {
   buildOrderByClauseMySQL,
@@ -21,6 +21,7 @@ import {
 } from "../../../common";
 
 import { applyDirectives } from "../../../directives";
+import { getQueryTimeoutMs } from "../../../../singletons/queryTimeout";
 
 // Generate CTE for aggregations
 const buildAggregationCTE = (
@@ -157,9 +158,21 @@ export const generateSQL = (
   operation: OperationAnalysis,
   variables: Record<string, unknown> = {},
   forHashMethod: boolean = false,
+  pageLimits: PageLimits | null = null,
+  timeoutMs?: number,
 ): string => {
+  // Bun's MySQL adapter ignores the `connection` bag and exposes no
+  // per-connection init hook, so there is no pool-level route for
+  // max_execution_time: the bound has to ride in the SQL text. MySQL honours the
+  // hint only on the outermost SELECT — one placed inside a CTE is silently
+  // discarded — which is why it is emitted here, at each return, rather than
+  // spliced into the finished string by the executor.
+  const effectiveTimeoutMs = timeoutMs ?? getQueryTimeoutMs();
+  const timeoutHint =
+    effectiveTimeoutMs > 0 ? ` /*+ MAX_EXECUTION_TIME(${effectiveTimeoutMs}) */` : "";
+
   if (forHashMethod) {
-    return `SELECT MD5((${buildSQLForField(entities, operation.variables ?? [], variables, operation.fields[0], null, null, 1, {})})) AS ResultHash`;
+    return `SELECT${timeoutHint} MD5((${buildSQLForField(entities, operation.variables ?? [], variables, operation.fields[0], null, null, 1, {}, pageLimits)})) AS ResultHash`;
   }
 
   const variablesWithDefault = {
@@ -220,6 +233,7 @@ export const generateSQL = (
       null,
       index + 1,
       {},
+      pageLimits,
     );
 
     fieldQueries.push(`'${field.alias || field.name}', ${fieldSQL}`);
@@ -228,7 +242,7 @@ export const generateSQL = (
   const cteClause = ctes.length > 0 ? `WITH\n${ctes.join(",\n")}\n` : "";
 
   return `
-    ${cteClause}SELECT JSON_OBJECT(
+    ${cteClause}SELECT${timeoutHint} JSON_OBJECT(
       ${fieldQueries.join(",\n")}
     ) as json_result`;
 };
@@ -242,6 +256,7 @@ export const buildSQLForField = (
   parentTableAlias: string | null,
   level: number,
   aliasMap: { [alias: string]: string },
+  pageLimits: PageLimits | null,
 ): string => {
   const tableAlias = generateTableAlias(level);
 
@@ -306,6 +321,7 @@ export const buildSQLForField = (
         tableAlias,
         level,
         aliasMap,
+        pageLimits,
       ),
     ([name, selector]) => `'${name}', ${selector}`,
   );
@@ -313,7 +329,12 @@ export const buildSQLForField = (
   const fromClause = `FROM ${dottedQuotedName} ${tableAlias}`;
 
   const orderByClause = buildOrderByClauseMySQL(entities, field, tableAlias);
-  const paginationClause = buildPaginationClauseMySQL(field, variablesDefinition);
+  const paginationClause = buildPaginationClauseMySQL(
+    field,
+    variablesDefinition,
+    variables,
+    pageLimits,
+  );
 
   const isArraySelection = !!field.isArray && !withoutArrayWrapper;
 

package/src/databases/engines/postgresql/connection.ts

@@ -5,24 +5,51 @@ import type { VariableDefinition } from "../../../analyzeQuery/types";
 import type { Database } from "../../../types/configuration";
 import type { ProcedureResolver } from "../../../types/db";
 
+import { BunSQLConnectionOptionsZod } from "../../../config/types/db";
 import { databasesConnections } from "../../../singletons/databases";
+import { getQueryTimeoutMs } from "../../../singletons/queryTimeout";
+
+// Every pool bound comes from the schema, which is the only place they are
+// declared and documented. Repeating them here as `?? n` fallbacks let the
+// documented default and the applied one drift apart, differently per engine.
+//
+// Defaults are overlaid rather than re-parsed: `connectionOptions` is an
+// undiscriminated union of the two engine shapes, so an object can arrive
+// already validated against the other one, and a strict re-parse would reject
+// it at boot.
+export const poolOptions = (db: Database, timeoutMs: number = getQueryTimeoutMs()) => {
+  const opts = {
+    ...BunSQLConnectionOptionsZod.parse({}),
+    ...(db.connectionOptions as BunSQLConnectionOptions | undefined),
+  };
 
-export const getPool = async (db: Database) => {
-  const opts = db.connectionOptions as BunSQLConnectionOptions | undefined;
-  const pool = new SQL({
+  return {
     host: db.connection.host,
     port: db.connection.port,
     user: db.connection.user,
     password: db.connection.password,
     database: db.connection.database,
-    max: opts?.max ?? 5,
-    idleTimeout: opts?.idleTimeout ?? 30,
-    connectionTimeout: opts?.connectionTimeout,
-    maxLifetime: opts?.maxLifetime,
-    tls: opts?.tls,
-    prepare: opts?.prepare,
-    bigint: opts?.bigint,
-  });
+    max: opts.max,
+    idleTimeout: opts.idleTimeout,
+    connectionTimeout: opts.connectionTimeout,
+    maxLifetime: opts.maxLifetime,
+    tls: opts.tls,
+    prepare: opts.prepare,
+    bigint: opts.bigint,
+    // Applied once per pooled connection rather than per query, so it bounds
+    // everything that runs on the connection — auth and introspection included
+    // — at no per-query cost. Omitted at 0 rather than sent as "0", which
+    // Postgres reads as unlimited but still costs a round trip to set.
+    ...(timeoutMs > 0 ? { connection: { statement_timeout: String(timeoutMs) } } : {}),
+  };
+};
+
+/** The bound the pool already applies, so the executor can tell an override from the default. */
+export const poolStatementTimeoutMs = (db: Database) =>
+  Number(poolOptions(db).connection?.statement_timeout ?? 0);
+
+export const getPool = async (db: Database) => {
+  const pool = new SQL(poolOptions(db));
 
   await pool.connect(); // Connect to the database
 
@@ -31,6 +58,35 @@ export const getPool = async (db: Database) => {
 
 export const getPoolSingleton = async (db: Database) => databasesConnections[db.name] as SQL;
 
+// A timeout other than the pool's own has to be set on a connection, which
+// means pinning one for the duration. Only an override pays for that.
+const executeReserved = async <T>(
+  pool: SQL,
+  timeoutMs: number,
+  query: string,
+  params: unknown[],
+) => {
+  // SET takes no bind parameters, so the value is interpolated. It is an
+  // integer from the config schema; re-checked here so a widened type upstream
+  // cannot turn this line into an injection point.
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 0) {
+    throw new Error(`Invalid statement timeout: ${timeoutMs}`);
+  }
+
+  const reserved = await pool.reserve();
+
+  try {
+    await reserved.unsafe(`SET statement_timeout = ${timeoutMs}`);
+
+    return await reserved.unsafe<T>(query, params);
+  } finally {
+    // The connection goes back to the pool carrying the pool's default again,
+    // not this query's override.
+    await reserved.unsafe("RESET statement_timeout");
+    await reserved.release();
+  }
+};
+
 export const executeQueryFactory =
   (singleQuery = false) =>
   async <T>(
@@ -38,13 +94,16 @@ export const executeQueryFactory =
     db: Database,
     variablesDefinition: VariableDefinition[],
     values: Record<string, unknown> = {},
+    timeoutMs?: number,
   ) => {
     const pool = singleQuery ? await getPool(db) : await getPoolSingleton(db);
+    const params = variablesDefinition.map((v) => values[v.name]);
 
-    const result = await pool.unsafe<T>(
-      query,
-      variablesDefinition.map((v) => values[v.name]),
-    );
+    const override = timeoutMs !== undefined && timeoutMs !== poolStatementTimeoutMs(db);
+
+    const result = override
+      ? await executeReserved<T>(pool, timeoutMs, query, params)
+      : await pool.unsafe<T>(query, params);
 
     if (singleQuery) {
       await pool.close();
@@ -63,12 +122,14 @@ export const executeQueryJSONFactory =
     db: Database,
     variablesDefinition: VariableDefinition[] = [],
     values: Record<string, unknown> = {},
+    timeoutMs?: number,
   ) => {
     const result = await (singleQuery ? executeQuerySingle : executeQuery)<[{ json_result: T }]>(
       query,
       db,
       variablesDefinition,
       values,
+      timeoutMs,
     );
 
     return result[0].json_result as T;

package/src/databases/engines/postgresql/format.ts

@@ -2,6 +2,7 @@ import { format as sqlFormatter } from "sql-formatter";
 
 import type { AnalysisResult } from "../../../analyzeQuery/types";
 import type { MergedEntities } from "../../../configuration/getSchemas/mergeEntities";
+import type { PageLimits } from "../../common";
 
 import { generateSQL } from "../../core/query-builder";
 
@@ -16,8 +17,9 @@ export const genSql = (
   query: AnalysisResult,
   variables: Record<string, unknown> = {},
   hash = false,
+  pageLimits: PageLimits | null = null,
 ) => {
-  const [[, sql]] = generateSQL(entitites, query, variables, hash);
+  const [[, sql]] = generateSQL(entitites, query, variables, hash, pageLimits);
 
   return format(sql);
 };

package/src/databases/engines/postgresql/query/index.ts

@@ -4,7 +4,7 @@ import type {
   VariableDefinition,
 } from "../../../../analyzeQuery/types";
 import type { MergedEntities } from "../../../../configuration/getSchemas/mergeEntities";
-import type { GroupByInfo } from "../../../common";
+import type { GroupByInfo, PageLimits } from "../../../common";
 
 import {
   buildOrderByClausePG,
@@ -154,9 +154,10 @@ export const generateSQL = (
   operation: OperationAnalysis,
   variables: Record<string, unknown> = {},
   forHashMethod: boolean = false,
+  pageLimits: PageLimits | null = null,
 ): string => {
   if (forHashMethod) {
-    return `SELECT MD5((${buildSQLForField(entities, operation.variables ?? [], variables, operation.fields[0], null, null, 1, {})})::text) AS "ResultHash"`;
+    return `SELECT MD5((${buildSQLForField(entities, operation.variables ?? [], variables, operation.fields[0], null, null, 1, {}, pageLimits)})::text) AS "ResultHash"`;
   }
 
   const variablesWithDefault = {
@@ -217,6 +218,7 @@ export const generateSQL = (
       null,
       index + 1,
       {},
+      pageLimits,
     );
 
     fieldQueries.push(`'${field.alias || field.name}', ${fieldSQL}`);
@@ -239,6 +241,7 @@ export const buildSQLForField = (
   parentTableAlias: string | null,
   level: number,
   aliasMap: { [alias: string]: string },
+  pageLimits: PageLimits | null,
 ): string => {
   const tableAlias = generateTableAlias(level);
 
@@ -303,6 +306,7 @@ export const buildSQLForField = (
         tableAlias,
         level,
         aliasMap,
+        pageLimits,
       ),
     ([name, selector]) => `'${name}', ${selector}`,
   );
@@ -310,7 +314,12 @@ export const buildSQLForField = (
   const fromClause = `FROM ${dottedQuotedName} ${tableAlias}`;
 
   const orderByClause = buildOrderByClausePG(entities, field, tableAlias);
-  const paginationClause = buildPaginationClausePG(field, variablesDefinition);
+  const paginationClause = buildPaginationClausePG(
+    field,
+    variablesDefinition,
+    variables,
+    pageLimits,
+  );
 
   const isArraySelection = !!field.isArray && !withoutArrayWrapper;
 

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

@@ -28,6 +28,10 @@ export const getDatabasesStructure = async (
 ) => {
   const entities: TableResolver[] = [];
   const enhancedStoredProcedures: ProcedureResolver[] = [];
+  // Taken before the exclusion and auth-table filters below, because that is the
+  // only point where a name the config excludes is still visible. Resolving
+  // `schema.excludedTables` against `entities` could never succeed.
+  const tableNamesByDatabase: Record<string, string[]> = {};
 
   // The auth user table holds the password hash and must never be served via
   // the generated API. Its resolver key matches t.schemaName, which is always
@@ -39,10 +43,17 @@ export const getDatabasesStructure = async (
   for (const db of databases) {
     const { tables, storedProcedures } = await fetchStructure(db);
 
+    // Every other name comparison in this file folds case. This one used not to,
+    // and it is the one where a mismatch fails open: excludedTables is a
+    // 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()));
+
+    tableNamesByDatabase[db.name] = tables.map((t) => t.schemaName);
+
     const tablesToAdd = tables
       .reduce<Tables>((acc, t) => {
         if (authUserKey && t.schemaName === authUserKey) return acc;
-        if (db.schema?.excludedTables.includes(t.schemaName)) return acc;
+        if (excluded.has(t.schemaName.toLowerCase())) return acc;
 
         const tableOverride = db.schema?.database[t.schemaName];
 
@@ -150,7 +161,7 @@ export const getDatabasesStructure = async (
     enhancedStoredProcedures.push(...storedProceduresToAdd);
   }
 
-  return { tables: entities, storedProcedures: enhancedStoredProcedures };
+  return { tables: entities, storedProcedures: enhancedStoredProcedures, tableNamesByDatabase };
 };
 
 export type EntitiesOfRole = {

package/src/index.ts

@@ -18,10 +18,18 @@ import { getAgent, instantiateAI } from "./singletons/ai";
 import { getTokenService, setTokenService } from "./singletons/authentication";
 import { instantiateCronJobs } from "./singletons/cron";
 import { disconnectDatabases, instantiateDatabasesConnections } 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 { ConfigurationZod } from "./types/zod/configuration";
-import { S200, S400, S401, S404 } from "./utils/responses";
+import {
+  createMemoryRateLimitStore,
+  createRateLimiter,
+  createRedisRateLimitStore,
+  resolveClientAddress,
+} from "./utils/rateLimit";
+import { S200, S400, S401, S404, S429 } from "./utils/responses";
 import { writeSchema } from "./utils/writeSchema";
 import { logger, configureLogging } from "./logging";
 
@@ -73,6 +81,20 @@ const bootAnalyzedConfiguration = async (env: Env) => {
     configureLogging(env.logger);
   }
 
+  if (env.maxQueryDepth === 0) {
+    logger("graphoria").warn(
+      "MAX_QUERY_DEPTH=0 disables the query depth limit; one deeply nested query can exhaust the server",
+    );
+  }
+
+  setQueryTimeoutMs(env.queryTimeoutMs);
+
+  if (env.queryTimeoutMs === 0) {
+    logger("graphoria").warn(
+      "QUERY_TIMEOUT_MS=0 disables the statement timeout; one slow query can hold a connection and its locks indefinitely",
+    );
+  }
+
   if (!env.configuration) {
     throw new Error("Configuration is required to create the GraphQL server");
   }
@@ -212,19 +234,57 @@ const createGraphQLServer = async (env: Env) => {
 
   const consoleHtml = await renderPlayground("../playgrounds/console/index.html", {});
 
+  const rateLimiter = createRateLimiter({
+    settings: env.rateLimit,
+    anonymousRole: env.anonymousRole,
+    permissions: projectConfiguration.auth?.permissions,
+    store: () =>
+      env.cache.store === "redis"
+        ? createRedisRateLimitStore(getCacheRedisClient())
+        : createMemoryRateLimitStore(),
+  });
+
   // Helper to get role-based handlers
-  const getRoleHandlers = async (req: Request) => {
+  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),
     );
+
+    // 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),
+    );
+
     return {
       role: session.role!,
       session,
+      limit,
       ...analyzedConfiguration.roles[session.role!].handlers,
     };
   };
 
+  /**
+   * For the entry points that have no session to key on: the websocket upgrade
+   * (the token arrives in `connection_init`, after the upgrade) and MCP. They
+   * are keyed by address against the anonymous ceiling.
+   */
+  const withRateLimit =
+    <T>(handler: (req: BunRequest, server: Bun.Server<unknown>) => T | Promise<T>) =>
+    async (req: BunRequest, server: Bun.Server<unknown>) => {
+      const limit = await rateLimiter?.check(
+        null,
+        resolveClientAddress(req, server, env.rateLimit.trustProxy),
+      );
+
+      if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
+
+      return handler(req, server);
+    };
+
   // Create routes map with all handlers
   const routes: RoutesMap = {};
 
@@ -251,7 +311,8 @@ const createGraphQLServer = async (env: Env) => {
         prefixes,
         projectConfiguration,
         analyzedConfiguration,
-        getRoleHandlers,
+        tokenService: getTokenService(),
+        rateLimiter,
       }),
     );
   }
@@ -259,7 +320,7 @@ const createGraphQLServer = async (env: Env) => {
   // GraphQL endpoint
   routes[prefixes.graphql] = {
     ...(env.enableCors ? { OPTIONS: () => new S200(null) } : {}),
-    GET: async (req: Request, server: Bun.Server<unknown>) => {
+    GET: withRateLimit(async (req: Request, server: Bun.Server<unknown>) => {
       try {
         if (req.headers.get("upgrade") === "websocket") {
           const success = server.upgrade(req, {
@@ -271,17 +332,19 @@ const createGraphQLServer = async (env: Env) => {
       } catch (error) {
         return new S400({ errors: [{ message: (error as Error)?.message }] });
       }
-    },
-    POST: async (req: BunRequest) => {
+    }),
+    POST: async (req: BunRequest, server: Bun.Server<unknown>) => {
       try {
-        const { gql, session } = await getRoleHandlers(req);
+        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);
+        const { hasErrors, validationErrors } = gql.hasErrors(query, { variables });
 
         if (hasErrors)
           return new S400({
@@ -312,7 +375,7 @@ const createGraphQLServer = async (env: Env) => {
 
     if (mcpEnabled) {
       const mcpPath = `${env.prefix}${env.ai?.mcp?.endpoint ?? projectConfiguration.ai?.endpoint ?? "/ai"}`;
-      routes[mcpPath] = createMCPRoutes(analyzedConfiguration, {
+      const mcpRoutes = createMCPRoutes(analyzedConfiguration, {
         ...(env.ai?.mcp ?? {}),
         name: projectConfiguration.name,
         version: projectConfiguration.version,
@@ -320,15 +383,20 @@ const createGraphQLServer = async (env: Env) => {
         adminSecret: env.admin.secret,
         adminSecretHeader: env.admin.header,
       });
+
+      routes[mcpPath] = Object.fromEntries(
+        Object.entries(mcpRoutes).map(([method, handler]) => [method, withRateLimit(handler)]),
+      );
     }
 
     if (env.ai?.restEnabled) {
       const aiPath = `${env.prefix}/rest${projectConfiguration.ai.endpoint ?? "/ai"}`;
       routes[aiPath] = {
         ...(env.enableCors ? { OPTIONS: () => new S200(null) } : {}),
-        POST: async (req: BunRequest) => {
+        POST: async (req: BunRequest, server: Bun.Server<unknown>) => {
           try {
-            const { role } = await getRoleHandlers(req);
+            const { role, limit } = await getRoleHandlers(req, server);
+            if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
             if (role !== env.superadmin.role) return new S404({ error: "Not Found" });
 
             const { prompt } = await req.json();
@@ -347,11 +415,12 @@ const createGraphQLServer = async (env: Env) => {
   }
 
   // REST API endpoint
-  routes[`${prefixes.rest}/*`] = async (req: BunRequest) => {
+  routes[`${prefixes.rest}/*`] = async (req: BunRequest, server: Bun.Server<unknown>) => {
     if (req.method === "OPTIONS" && env.enableCors) return new S200(null);
 
     try {
-      const { rest, session } = await getRoleHandlers(req);
+      const { rest, session, limit } = await getRoleHandlers(req, server);
+      if (limit && !limit.allowed) return new S429(limit.retryAfterMs);
 
       const urlParsed = new URL(req.url);
 

package/src/singletons/queryTimeout.ts

@@ -0,0 +1,20 @@
+/**
+ * The process-wide statement timeout in milliseconds, resolved from
+ * `QUERY_TIMEOUT_MS` at boot.
+ *
+ * It lives here rather than being read from `singletons/env` because the engine
+ * connection modules need it, and that module parses `process.env` the moment it
+ * is imported — reaching it from an engine would make every unit test that
+ * transitively touches a query builder fail without `ADMIN_SECRET` set.
+ *
+ * `0` disables the bound. That is also the value before boot sets it, so an
+ * engine used outside a booted server behaves exactly as it did before timeouts
+ * existed.
+ */
+let queryTimeoutMs = 0;
+
+export const setQueryTimeoutMs = (ms: number) => {
+  queryTimeoutMs = ms;
+};
+
+export const getQueryTimeoutMs = () => queryTimeoutMs;

package/src/subscriptions/strategies/database.ts

@@ -15,10 +15,26 @@ export const createDatabaseSubscriptionStrategy = (): SubscriptionStrategy => ({
   source: EntitySource.TABLE,
 
   getSubscriptionKey(context) {
-    const { analysis } = context;
+    const { analysis, field, session, variables } = context;
     const operation = analysis.operations[0];
-    // Use operation name as the base key (existing behavior)
-    return operation.name ?? operation.fields[0]?.name ?? "unknown";
+    const base = operation.name ?? operation.fields[0]?.name ?? "unknown";
+
+    // Every part of this is load-bearing. A group shares one poller, and every
+    // client joined to it is served that poller's rows — so two callers may
+    // only share a key when the query they asked for is the same query,
+    // resolved against the same session. The role and the subject carry the row
+    // filter; the variables carry everything the caller chose; the selections
+    // carry the shape. Two keys that differ where they should not merely cost a
+    // second poller, but two that match where they should not is a cross-tenant
+    // read.
+    return [
+      base,
+      session.role ?? "",
+      session.sub ?? "",
+      field.alias ?? "",
+      JSON.stringify(field.selections),
+      JSON.stringify(variables),
+    ].join("\u0000");
   },
 
   async subscribe(context: SubscriptionContext): Promise<SubscriptionResult> {