@graphoria/server 0.2.3 → 0.3.0

package/src/subscriptions/types.ts

@@ -2,6 +2,7 @@ import type { ServerWebSocket } from "bun";
 import type { AnalysisResult, SelectionAnalysis, VariableDefinition } from "../analyzeQuery/types";
 import type { GetSchemaReturn } from "../configuration/getSchemas";
 import type { createQueryEventEmitter } from "../utils/event-emitter";
+import type { SessionContext } from "../utils/sessionVariables";
 
 /**
  * Type for the query event emitter instance
@@ -24,7 +25,7 @@ export interface SubscriptionContext {
   ws: ServerWebSocket<unknown>;
   /** Unique subscription ID from the client */
   subscriptionId: string;
-  /** Analyzed GraphQL query */
+  /** Analyzed GraphQL query, with variables and `$session.*` already resolved */
   analysis: AnalysisResult;
   /** The first field being subscribed to */
   field: SelectionAnalysis;
@@ -34,6 +35,8 @@ export interface SubscriptionContext {
   variables: Record<string, unknown>;
   /** Schema and entity information for the current role */
   schemaEntity: GetSchemaReturn;
+  /** The caller this subscription belongs to. Load-bearing: it keys the group. */
+  session: SessionContext;
   /** Shared event emitter for broadcasting updates */
   eventEmitter: QueryEventEmitter;
 }

package/src/subscriptions/utils/polling.ts

@@ -5,6 +5,7 @@ import type { DatabasePoller, QueryEventEmitter } from "../types";
 
 import { executeQuery, executeQueryJSON, generateSQL } from "../../databases";
 import { logger } from "../../logging";
+import { env } from "../../singletons/env";
 
 export interface DatabasePollerConfig {
   analysis: AnalysisResult;
@@ -60,9 +61,11 @@ export const createDatabasePoller = async (
   const firstFieldName = getFirstFieldName(analysis);
   const db = schemaEntity.queriesMap[firstFieldName!]!.db!;
 
-  // Generate SQL queries (data query and hash query)
-  const [[, queryData]] = generateSQL(schemaEntity, analysis, variables);
-  const [[, queryHash]] = generateSQL(schemaEntity, analysis, variables, true);
+  // Generate SQL queries (data query and hash query). A subscription query is
+  // caller-authored, so it carries the same page bounds an HTTP query does.
+  const pageLimits = { defaultPageSize: env.defaultPageSize, maxPageSize: env.maxPageSize };
+  const [[, queryData]] = generateSQL(schemaEntity, analysis, variables, false, pageLimits);
+  const [[, queryHash]] = generateSQL(schemaEntity, analysis, variables, true, pageLimits);
 
   // Get initial hash and send initial data
   let previousHash = await getResultHash(queryHash, db, variableDefinitions, variables);

package/src/types/env.ts

@@ -30,12 +30,21 @@ export const EnvZod = z
     // Boolean flags use stringbool, not coerce.boolean: Boolean("false") === true would flip them on
     CONSOLE_ENABLED: z.stringbool().default(false),
     CONSOLE_ENDPOINT: z.string().default("/_console"),
+    CONSOLE_SESSION_EXPIRES_IN: z.string().default("1h"),
     PREFIX: z.string().default(""),
     CORS_ENABLED: z.stringbool().default(true),
     PRINT_SCHEMAS: z.stringbool().default(false),
     SCHEMAS_OUTPUT_DIR: z.string().default("./.graphoria/schemas"),
     QUERY_ON_RESPONSE: z.stringbool().default(false),
-    MAX_QUERY_DEPTH: z.coerce.number().int().min(0).default(0),
+    MAX_QUERY_DEPTH: z.coerce.number().int().min(0).default(8),
+    DEFAULT_PAGE_SIZE: z.coerce.number().int().min(0).default(100),
+    MAX_PAGE_SIZE: z.coerce.number().int().min(0).default(1000),
+    QUERY_TIMEOUT_MS: z.coerce.number().int().min(0).default(10000),
+    MAX_QUERY_COST: z.coerce.number().int().min(0).default(0),
+    RATE_LIMIT_MAX: z.coerce.number().int().min(0).default(0),
+    RATE_LIMIT_ANONYMOUS_MAX: z.coerce.number().int().min(0).default(0),
+    RATE_LIMIT_WINDOW_MS: z.coerce.number().int().positive().default(60000),
+    RATE_LIMIT_TRUST_PROXY: z.stringbool().default(false),
     AI_ENABLED: z.stringbool().optional(),
     AI_GRAPHQL_ENABLED: z.stringbool().default(true),
     AI_REST_ENABLED: z.stringbool().default(true),
@@ -66,6 +75,10 @@ export const EnvZod = z
     authStrategy: env.AUTH_STRATEGY,
     queryOnResponse: env.QUERY_ON_RESPONSE,
     maxQueryDepth: env.MAX_QUERY_DEPTH,
+    defaultPageSize: env.DEFAULT_PAGE_SIZE,
+    maxPageSize: env.MAX_PAGE_SIZE,
+    queryTimeoutMs: env.QUERY_TIMEOUT_MS,
+    maxQueryCost: env.MAX_QUERY_COST,
     admin: {
       secret: env.ADMIN_SECRET,
       header: env.ADMIN_SECRET_HEADER,
@@ -80,6 +93,12 @@ export const EnvZod = z
       secretKey: env.PASETO_SECRET_KEY,
       publicKey: env.PASETO_PUBLIC_KEY,
     },
+    rateLimit: {
+      max: env.RATE_LIMIT_MAX,
+      anonymousMax: env.RATE_LIMIT_ANONYMOUS_MAX,
+      windowMs: env.RATE_LIMIT_WINDOW_MS,
+      trustProxy: env.RATE_LIMIT_TRUST_PROXY,
+    },
     cache: {
       store: env.CACHE_STORE,
       redisUrl: env.REDIS_URL,
@@ -94,6 +113,7 @@ export const EnvZod = z
     console: {
       enabled: env.CONSOLE_ENABLED,
       endpoint: env.CONSOLE_ENDPOINT,
+      sessionExpiresIn: env.CONSOLE_SESSION_EXPIRES_IN,
     },
     ai: {
       enabled: env.AI_ENABLED,

package/src/utils/rateLimit.ts

@@ -0,0 +1,209 @@
+import { LRUCache } from "lru-cache";
+
+import { logger } from "../logging";
+
+export type ConsumeResult = { allowed: boolean; retryAfterMs: number };
+
+/**
+ * One method, everything per call: a role with its own limit shares the store
+ * with every other role rather than needing an instance of its own.
+ */
+export interface RateLimitStore {
+  consume(
+    key: string,
+    capacity: number,
+    refillPerMs: number,
+    ttlMs: number,
+  ): Promise<ConsumeResult>;
+}
+
+type Bucket = { tokens: number; ts: number };
+
+export type MemoryRateLimitStoreOptions = {
+  now?: () => number;
+  maxKeys?: number;
+};
+
+const DEFAULT_MAX_KEYS = 10_000;
+
+export const createMemoryRateLimitStore = ({
+  now = Date.now,
+  maxKeys = DEFAULT_MAX_KEYS,
+}: MemoryRateLimitStoreOptions = {}): RateLimitStore => {
+  // The bound is load-bearing: an unbounded map keyed by client address is
+  // itself a memory-exhaustion vector. Evicting a bucket only ever gives its
+  // owner a full one, which is what an idle caller would have had anyway.
+  const buckets = new LRUCache<string, Bucket>({ max: maxKeys });
+
+  return {
+    consume: async (key, capacity, refillPerMs, ttlMs) => {
+      const nowMs = now();
+      const bucket = buckets.get(key);
+      const tokens = bucket
+        ? Math.min(capacity, bucket.tokens + (nowMs - bucket.ts) * refillPerMs)
+        : capacity;
+
+      if (tokens < 1) {
+        buckets.set(key, { tokens, ts: nowMs }, { ttl: ttlMs });
+        return { allowed: false, retryAfterMs: Math.ceil((1 - tokens) / refillPerMs) };
+      }
+
+      buckets.set(key, { tokens: tokens - 1, ts: nowMs }, { ttl: ttlMs });
+      return { allowed: true, retryAfterMs: 0 };
+    },
+  };
+};
+
+export type RateLimitRedisClient = {
+  send(command: string, args: string[]): Promise<unknown>;
+};
+
+type RateLimitLogger = { warn(obj: object, msg: string): void };
+
+export type RedisRateLimitStoreOptions = {
+  now?: () => number;
+  log?: RateLimitLogger;
+};
+
+// KEYS[1] = bucket key, ARGV = capacity, refillPerMs, nowMs, ttlMs. Refill,
+// read and write have to happen inside Redis: doing them from here would race
+// between workers, which is the whole reason for reaching for Redis at all.
+const CONSUME_SCRIPT = `
+local b = redis.call('HMGET', KEYS[1], 'tokens', 'ts')
+local tokens = tonumber(b[1]) or tonumber(ARGV[1])
+local ts = tonumber(b[2]) or tonumber(ARGV[3])
+tokens = math.min(tonumber(ARGV[1]), tokens + (tonumber(ARGV[3]) - ts) * tonumber(ARGV[2]))
+local allowed = 0
+if tokens >= 1 then tokens = tokens - 1; allowed = 1 end
+redis.call('HMSET', KEYS[1], 'tokens', tokens, 'ts', ARGV[3])
+redis.call('PEXPIRE', KEYS[1], ARGV[4])
+return { allowed, tostring(tokens) }
+`;
+
+export const createRedisRateLimitStore = (
+  client: RateLimitRedisClient,
+  { now = Date.now, log = logger("rate-limit") }: RedisRateLimitStoreOptions = {},
+): RateLimitStore => {
+  let lastWarnMs: number | undefined;
+
+  return {
+    consume: async (key, capacity, refillPerMs, ttlMs) => {
+      const nowMs = now();
+
+      try {
+        const reply = (await client.send("EVAL", [
+          CONSUME_SCRIPT,
+          "1",
+          key,
+          String(capacity),
+          String(refillPerMs),
+          String(nowMs),
+          String(ttlMs),
+        ])) as [number | string, string];
+
+        const allowed = Number(reply[0]) === 1;
+        const tokens = Number(reply[1]);
+
+        return allowed
+          ? { allowed: true, retryAfterMs: 0 }
+          : { allowed: false, retryAfterMs: Math.ceil((1 - tokens) / refillPerMs) };
+      } catch (error) {
+        // A dead cache must not take the API down, and a dead cache must not
+        // produce a log line per request either — the flood would outlast the
+        // outage.
+        if (lastWarnMs === undefined || nowMs - lastWarnMs >= ttlMs) {
+          lastWarnMs = nowMs;
+          log.warn({ err: error }, "rate limit store unavailable, allowing the request");
+        }
+        return { allowed: true, retryAfterMs: 0 };
+      }
+    },
+  };
+};
+
+export type RateLimitSettings = {
+  max: number;
+  anonymousMax: number;
+  windowMs: number;
+  trustProxy: boolean;
+};
+
+type RoleRateLimit = { rateLimit?: { max: number; windowMs?: number } | undefined };
+
+export type RateLimiter = {
+  check(
+    session: { role?: string | undefined; sub?: string | undefined } | null,
+    address: string | undefined,
+  ): Promise<ConsumeResult>;
+};
+
+export type CreateRateLimiterOptions = {
+  settings: RateLimitSettings;
+  anonymousRole: string;
+  permissions?: Record<string, RoleRateLimit | undefined>;
+  /** A factory is only called once a limit is configured, so a disabled
+   * limiter never constructs a store — or a Redis client. */
+  store?: RateLimitStore | (() => RateLimitStore);
+};
+
+// Attacker-controlled once RATE_LIMIT_TRUST_PROXY is on, and it ends up in a
+// store key, so it is capped before it gets there.
+const MAX_ADDRESS_LENGTH = 64;
+
+export const resolveClientAddress = (
+  req: Request,
+  server: { requestIP(req: Request): { address: string } | null } | undefined,
+  trustProxy: boolean,
+): string | undefined => {
+  if (trustProxy) {
+    const forwarded = req.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+    if (forwarded) return forwarded.slice(0, MAX_ADDRESS_LENGTH);
+  }
+
+  return server?.requestIP(req)?.address;
+};
+
+/**
+ * `undefined` when nothing is configured, so the caller can skip the wrapper
+ * entirely and the shipped default costs nothing per request.
+ */
+export const createRateLimiter = ({
+  settings,
+  anonymousRole,
+  permissions = {},
+  store,
+}: CreateRateLimiterOptions): RateLimiter | undefined => {
+  const configured =
+    settings.max > 0 ||
+    settings.anonymousMax > 0 ||
+    Object.values(permissions).some((permission) => (permission?.rateLimit?.max ?? 0) > 0);
+
+  if (!configured) return undefined;
+
+  const resolvedStore =
+    typeof store === "function" ? store() : (store ?? createMemoryRateLimitStore());
+
+  const limitFor = (role: string) => {
+    const roleLimit = permissions[role]?.rateLimit;
+
+    return {
+      max: roleLimit?.max ?? (role === anonymousRole ? settings.anonymousMax : settings.max),
+      windowMs: roleLimit?.windowMs ?? settings.windowMs,
+    };
+  };
+
+  return {
+    check: async (session, address) => {
+      const role = session?.role ?? anonymousRole;
+      const { max, windowMs } = limitFor(role);
+
+      if (max === 0) return { allowed: true, retryAfterMs: 0 };
+
+      const sub = session?.sub;
+      const key =
+        sub && sub !== "anonymous" ? `rl:${role}:${sub}` : `rl:${role}:ip:${address ?? "unknown"}`;
+
+      return resolvedStore.consume(key, max, max / windowMs, windowMs);
+    },
+  };
+};

package/src/utils/responses.ts

@@ -35,6 +35,16 @@ export class S404 extends ClientResponse {
   }
 }
 
+export class S429 extends ClientResponse {
+  constructor(retryAfterMs: number) {
+    super({ errors: [{ message: "Rate limit exceeded" }] }, { status: 429 });
+
+    // Seconds, and never 0: a caller told to retry immediately retries
+    // immediately, which is the traffic the limit is there to stop.
+    this.headers.set("Retry-After", String(Math.max(1, Math.ceil(retryAfterMs / 1000))));
+  }
+}
+
 export class S500 extends ClientResponse {
   constructor(body?: object | null, init?: ResponseInit) {
     super(body, { ...init, status: 500 });