@nifrajs/graphql 3.3.0 → 4.0.0

package/src/limits.ts

@@ -0,0 +1,215 @@
+import { type DocumentNode, type GraphQLError, Kind, type SelectionNode } from "graphql"
+
+export const DEFAULT_GRAPHQL_LIMITS = Object.freeze({
+  maxQueryBytes: 64 * 1024,
+  maxVariablesBytes: 256 * 1024,
+  maxDepth: 20,
+  maxAliases: 100,
+  maxComplexity: 1_000,
+  maxOperations: 10,
+})
+
+export interface GraphqlLimitsOptions {
+  readonly maxQueryBytes?: number
+  readonly maxVariablesBytes?: number
+  readonly maxDepth?: number
+  readonly maxAliases?: number
+  readonly maxComplexity?: number
+  readonly maxOperations?: number
+}
+
+export interface GraphqlLimits {
+  readonly maxQueryBytes: number
+  readonly maxVariablesBytes: number
+  readonly maxDepth: number
+  readonly maxAliases: number
+  readonly maxComplexity: number
+  readonly maxOperations: number
+}
+
+function limit(value: number | undefined, fallback: number, name: string, minimum: number): number {
+  const result = value ?? fallback
+  if (!Number.isSafeInteger(result) || result < minimum) {
+    throw new RangeError(`GraphQL ${name} must be a safe integer >= ${minimum}`)
+  }
+  return result
+}
+
+export function graphqlLimits(options: GraphqlLimitsOptions = {}): GraphqlLimits {
+  return {
+    maxQueryBytes: limit(
+      options.maxQueryBytes,
+      DEFAULT_GRAPHQL_LIMITS.maxQueryBytes,
+      "maxQueryBytes",
+      1,
+    ),
+    maxVariablesBytes: limit(
+      options.maxVariablesBytes,
+      DEFAULT_GRAPHQL_LIMITS.maxVariablesBytes,
+      "maxVariablesBytes",
+      0,
+    ),
+    maxDepth: limit(options.maxDepth, DEFAULT_GRAPHQL_LIMITS.maxDepth, "maxDepth", 1),
+    maxAliases: limit(options.maxAliases, DEFAULT_GRAPHQL_LIMITS.maxAliases, "maxAliases", 0),
+    maxComplexity: limit(
+      options.maxComplexity,
+      DEFAULT_GRAPHQL_LIMITS.maxComplexity,
+      "maxComplexity",
+      1,
+    ),
+    maxOperations: limit(
+      options.maxOperations,
+      DEFAULT_GRAPHQL_LIMITS.maxOperations,
+      "maxOperations",
+      1,
+    ),
+  }
+}
+
+export function utf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength
+}
+
+export function variablesBytes(value: Record<string, unknown> | null): number {
+  return value === null ? 0 : utf8Bytes(JSON.stringify(value))
+}
+
+export interface GraphqlDocumentMetrics {
+  readonly operations: number
+  readonly depth: number
+  readonly aliases: number
+  readonly complexity: number
+}
+
+type SelectionMetrics = Omit<GraphqlDocumentMetrics, "operations">
+
+const NO_SELECTIONS: SelectionMetrics = { depth: 0, aliases: 0, complexity: 0 }
+
+/** `depth` counts from the selection set's own level, so one fragment measure holds at every spread. */
+function selectionsMetrics(
+  selections: readonly SelectionNode[],
+  fragment: (name: string) => SelectionMetrics,
+): SelectionMetrics {
+  let depth = 0
+  let aliases = 0
+  let complexity = 0
+  for (const selection of selections) {
+    let nested: SelectionMetrics
+    if (selection.kind === Kind.FIELD) {
+      complexity += 1
+      if (selection.alias !== undefined) aliases += 1
+      nested =
+        selection.selectionSet === undefined
+          ? NO_SELECTIONS
+          : selectionsMetrics(selection.selectionSet.selections, fragment)
+      depth = Math.max(depth, nested.depth + 1)
+    } else {
+      nested =
+        selection.kind === Kind.INLINE_FRAGMENT
+          ? selectionsMetrics(selection.selectionSet.selections, fragment)
+          : fragment(selection.name.value)
+      depth = Math.max(depth, nested.depth)
+    }
+    aliases += nested.aliases
+    complexity += nested.complexity
+  }
+  return { depth, aliases, complexity }
+}
+
+/**
+ * Each fragment is measured once and reused at every spread. Expanding spreads in place costs a visit
+ * per expanded field, and a document whose fragments each spread the one before twice turns n short
+ * lines into 2^n visits, all of it synchronous before any limit can refuse the document.
+ */
+export function documentMetrics(document: DocumentNode): GraphqlDocumentMetrics {
+  const definitions = new Map<string, readonly SelectionNode[]>()
+  for (const definition of document.definitions) {
+    if (definition.kind === Kind.FRAGMENT_DEFINITION) {
+      definitions.set(definition.name.value, definition.selectionSet.selections)
+    }
+  }
+  const measured = new Map<string, SelectionMetrics>()
+  const measuring = new Set<string>()
+  const fragment = (name: string): SelectionMetrics => {
+    const known = measured.get(name)
+    if (known !== undefined) return known
+    const selections = definitions.get(name)
+    // An unknown fragment and a cycle back into one being measured, both refused by validation,
+    // add nothing.
+    if (selections === undefined || measuring.has(name)) return NO_SELECTIONS
+    measuring.add(name)
+    const metrics = selectionsMetrics(selections, fragment)
+    measuring.delete(name)
+    measured.set(name, metrics)
+    return metrics
+  }
+  let operations = 0
+  let depth = 0
+  let aliases = 0
+  let complexity = 0
+  for (const definition of document.definitions) {
+    if (definition.kind !== Kind.OPERATION_DEFINITION) continue
+    operations += 1
+    const metrics = selectionsMetrics(definition.selectionSet.selections, fragment)
+    depth = Math.max(depth, metrics.depth)
+    aliases += metrics.aliases
+    complexity += metrics.complexity
+  }
+  return { operations, depth, aliases, complexity }
+}
+
+export function requestLimitError(
+  query: string,
+  variables: Record<string, unknown> | null,
+  limits: GraphqlLimits,
+): string | undefined {
+  if (utf8Bytes(query) > limits.maxQueryBytes) {
+    return `GraphQL query exceeds the ${limits.maxQueryBytes}-byte limit.`
+  }
+  if (variablesBytes(variables) > limits.maxVariablesBytes) {
+    return `GraphQL variables exceed the ${limits.maxVariablesBytes}-byte limit.`
+  }
+  return undefined
+}
+
+export function documentLimitError(
+  metrics: GraphqlDocumentMetrics,
+  limits: GraphqlLimits,
+): string | undefined {
+  if (metrics.operations > limits.maxOperations) {
+    return `GraphQL document exceeds the ${limits.maxOperations}-operation limit.`
+  }
+  if (metrics.depth > limits.maxDepth) {
+    return `GraphQL document exceeds the depth limit of ${limits.maxDepth}.`
+  }
+  if (metrics.aliases > limits.maxAliases) {
+    return `GraphQL document exceeds the ${limits.maxAliases}-alias limit.`
+  }
+  if (metrics.complexity > limits.maxComplexity) {
+    return `GraphQL document exceeds the complexity limit of ${limits.maxComplexity}.`
+  }
+  return undefined
+}
+
+export function maskExecutionError(error: GraphQLError): Record<string, unknown> {
+  return {
+    message: "Internal server error.",
+    ...(error.locations === undefined ? {} : { locations: error.locations }),
+    ...(error.path === undefined ? {} : { path: error.path }),
+  }
+}
+
+export function safeFormattedError(
+  error: GraphQLError,
+  phase: "request" | "execution",
+  formatter?: (error: GraphQLError, phase: "request" | "execution") => unknown,
+): unknown {
+  if (formatter !== undefined) {
+    try {
+      return formatter(error, phase)
+    } catch {
+      return phase === "execution" ? maskExecutionError(error) : error.toJSON()
+    }
+  }
+  return phase === "execution" ? maskExecutionError(error) : error.toJSON()
+}

package/src/ws.ts

@@ -14,7 +14,17 @@
  */
 
 import type { NifraWebSocket, WebSocketContext, WebSocketHandler } from "@nifrajs/core/ws"
-import { execute, type GraphQLSchema, subscribe } from "graphql"
+import {
+  type DocumentNode,
+  type ExecutionResult,
+  execute,
+  GraphQLError,
+  type GraphQLSchema,
+  parse,
+  specifiedRules,
+  subscribe,
+  validate,
+} from "graphql"
 import {
   type ConnectionInitMessage,
   GRAPHQL_TRANSPORT_WS_PROTOCOL,
@@ -23,6 +33,13 @@ import {
   type ServerOptions,
 } from "graphql-ws"
 import { buildContext, type GraphqlContextBuilder } from "./context.ts"
+import {
+  documentLimitError,
+  documentMetrics,
+  type GraphqlLimits,
+  graphqlLimits,
+  requestLimitError,
+} from "./limits.ts"
 
 /** Per-connection state carried on `ws.data` for the graphql-ws bridge. */
 interface GraphqlWsConnection {
@@ -31,6 +48,7 @@ interface GraphqlWsConnection {
   dispatch?: (message: string) => void | Promise<void>
   /** Tear the graphql-ws connection down (graphql-ws's `opened()` return value). */
   closed?: (code: number, reason: string) => void | Promise<void>
+  readonly subscriptions: Set<string>
 }
 
 export interface GraphqlWsOptions<
@@ -50,6 +68,17 @@ export interface GraphqlWsOptions<
   ) => boolean | Promise<boolean>
   /** Additional raw `graphql-ws` server options merged last (advanced escape hatch). */
   readonly serverOptions?: Partial<ServerOptions>
+  /** Same query/complexity limits as the HTTP transport. */
+  readonly maxQueryBytes?: number
+  readonly maxVariablesBytes?: number
+  readonly maxDepth?: number
+  readonly maxAliases?: number
+  readonly maxComplexity?: number
+  readonly maxOperations?: number
+  /** Maximum concurrent subscription operation ids per connection. Default 20. */
+  readonly maxSubscriptions?: number
+  /** Maximum time for initial execute/subscribe setup. Default 10 seconds. */
+  readonly executionTimeoutMs?: number
 }
 
 /** A frame is a string for JSON control messages; graphql-ws only speaks text frames. */
@@ -57,6 +86,123 @@ function asText(data: string | Uint8Array): string {
   return typeof data === "string" ? data : new TextDecoder().decode(data)
 }
 
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function graphqlWsLimits(options: GraphqlWsOptions): GraphqlLimits {
+  return graphqlLimits(options)
+}
+
+function assertWsNumber(value: number, name: string, minimum: number): void {
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new RangeError(`GraphQL ${name} must be a safe integer >= ${minimum}`)
+  }
+}
+
+function subscriptionFrameError(
+  message: string,
+  schema: GraphQLSchema,
+  limits: GraphqlLimits,
+): { readonly id: unknown; readonly message: string } | undefined {
+  let frame: unknown
+  try {
+    frame = JSON.parse(message)
+  } catch {
+    return undefined
+  }
+  const envelope = recordOf(frame)
+  if (envelope?.type !== "subscribe") return undefined
+  const id = envelope.id
+  const payload = recordOf(envelope.payload)
+  const query = payload?.query
+  if (typeof query !== "string") return { id, message: "A subscription query is required." }
+  const variablesValue = payload?.variables
+  const variables =
+    variablesValue === undefined || variablesValue === null ? null : recordOf(variablesValue)
+  if (variablesValue !== undefined && variablesValue !== null && variables === undefined) {
+    return { id, message: "Subscription variables must be an object." }
+  }
+  const requestError = requestLimitError(query, variables ?? null, limits)
+  if (requestError !== undefined) return { id, message: requestError }
+  let document: DocumentNode
+  try {
+    document = parse(query)
+  } catch (error) {
+    return { id, message: error instanceof GraphQLError ? error.message : "Invalid GraphQL query." }
+  }
+  const validationErrors = validate(schema, document, specifiedRules)
+  if (validationErrors.length > 0)
+    return { id, message: validationErrors[0]?.message ?? "Invalid GraphQL query." }
+  const limitError = documentLimitError(documentMetrics(document), limits)
+  return limitError === undefined ? undefined : { id, message: limitError }
+}
+
+function maskWsError(error: unknown): unknown {
+  const record = recordOf(error)
+  if (record === undefined) return { message: "Internal server error." }
+  return {
+    message: "Internal server error.",
+    ...(record.locations === undefined ? {} : { locations: record.locations }),
+    ...(Array.isArray(record.path) ? { path: record.path } : {}),
+  }
+}
+
+/**
+ * A frame graphql-ws sends, execution errors masked. A `complete` or `error` frame ends its operation,
+ * so the id stops counting against `maxSubscriptions`: a client is not expected to complete an
+ * operation the server already ended.
+ */
+function outboundFrame(message: string, subscriptions: Set<string>): string {
+  try {
+    const parsed = recordOf(JSON.parse(message))
+    if (parsed === undefined) return message
+    if ((parsed.type === "complete" || parsed.type === "error") && typeof parsed.id === "string") {
+      subscriptions.delete(parsed.id)
+    }
+    if (parsed.type === "next") {
+      const payload = recordOf(parsed.payload)
+      if (payload !== undefined && Array.isArray(payload.errors)) {
+        return JSON.stringify({
+          ...parsed,
+          payload: { ...payload, errors: payload.errors.map(maskWsError) },
+        })
+      }
+    }
+    if (parsed.type === "error" && Array.isArray(parsed.payload)) {
+      return JSON.stringify({ ...parsed, payload: parsed.payload.map(maskWsError) })
+    }
+  } catch {
+    return message
+  }
+  return message
+}
+
+/**
+ * A timeout is that operation's error result. graphql-ws does not catch a rejected execute or
+ * subscribe, so a rejection would end the whole socket instead of the one operation.
+ */
+async function withWsTimeout<T>(
+  work: T | Promise<T>,
+  timeoutMs: number,
+): Promise<T | ExecutionResult> {
+  if (!(work instanceof Promise) || timeoutMs === 0) return work
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<ExecutionResult>((resolve) => {
+    timer = setTimeout(
+      () => resolve({ errors: [new GraphQLError("Execution timed out.")] }),
+      timeoutMs,
+    )
+  })
+  try {
+    return await Promise.race([work, timeout])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
 /**
  * Build a nifra {@link WebSocketHandler} that terminates the `graphql-transport-ws` protocol. Register
  * it on a route enabled with `.use(websocket())`:
@@ -74,28 +220,44 @@ function asText(data: string | Uint8Array): string {
 export function graphqlWebSocket<Context extends Record<string, unknown> = Record<string, unknown>>(
   options: GraphqlWsOptions<Context>,
 ): WebSocketHandler<GraphqlWsConnection> {
+  const limits = graphqlWsLimits(options)
+  const maxSubscriptions = options.maxSubscriptions ?? 20
+  assertWsNumber(maxSubscriptions, "maxSubscriptions", 1)
+  const executionTimeoutMs = options.executionTimeoutMs ?? 10_000
+  assertWsNumber(executionTimeoutMs, "executionTimeoutMs", 0)
+  const executeWithTimeout: typeof execute = (args) =>
+    withWsTimeout(execute(args), executionTimeoutMs)
+  const subscribeWithTimeout: typeof subscribe = (args) =>
+    withWsTimeout(subscribe(args), executionTimeoutMs)
   const gqlServer = makeServer<Record<string, unknown>, { request: Request }>({
+    // Keep the raw escape hatch for auxiliary graphql-ws hooks, but make the package's safety
+    // controls authoritative: callers cannot accidentally replace the bounded execute/subscribe
+    // wrappers or the context/authentication seams with an unbounded implementation.
+    ...options.serverOptions,
     schema: options.schema,
-    execute,
-    subscribe,
+    execute: executeWithTimeout,
+    subscribe: subscribeWithTimeout,
     onConnect: options.onConnect
       ? async (ctx: GraphqlWsContext<Record<string, unknown>, { request: Request }>) => {
-          return await options.onConnect?.(
-            ctx.connectionParams as ConnectionInitMessage["payload"],
-            ctx.extra.request,
-          )
+          try {
+            return await options.onConnect?.(
+              ctx.connectionParams as ConnectionInitMessage["payload"],
+              ctx.extra.request,
+            )
+          } catch {
+            return false
+          }
         }
       : undefined,
     context: options.context
       ? async (ctx: GraphqlWsContext<Record<string, unknown>, { request: Request }>) =>
           await buildContext(options.context, { request: ctx.extra.request })
       : undefined,
-    ...options.serverOptions,
   })
 
   return {
     upgrade(c: WebSocketContext): GraphqlWsConnection {
-      return { request: c.req }
+      return { request: c.req, subscriptions: new Set() }
     },
 
     open(ws: NifraWebSocket<GraphqlWsConnection>): void {
@@ -106,7 +268,7 @@ export function graphqlWebSocket<Context extends Record<string, unknown> = Recor
         {
           protocol,
           send: async (data: string) => {
-            ws.send(data)
+            ws.send(outboundFrame(data, ws.data.subscriptions))
           },
           close: (code: number, reason: string) => {
             ws.close(code, reason)
@@ -118,7 +280,15 @@ export function graphqlWebSocket<Context extends Record<string, unknown> = Recor
         { request: ws.data.request },
       )
       ws.data.closed = closed
-      ws.data.dispatch = (message: string) => onFrame?.(message)
+      ws.data.dispatch = async (message: string) => {
+        try {
+          await onFrame?.(message)
+        } catch {
+          // graphql-ws leaves a failed frame (a throwing context builder, say) to its socket adapter.
+          // Unhandled, the rejection would end a Bun or Node process; the protocol closes one socket.
+          ws.close(4500, "Internal server error")
+        }
+      }
     },
 
     message(ws: NifraWebSocket<GraphqlWsConnection>, data: string | Uint8Array): void {
@@ -126,11 +296,45 @@ export function graphqlWebSocket<Context extends Record<string, unknown> = Recor
       // iterator completes (`await for await`), so awaiting it here would block every later frame on
       // this socket - including the client's `Complete` that stops the subscription. graphql-ws drives
       // its own sends and error frames from inside that loop; we only feed it inbound frames.
-      void ws.data.dispatch?.(asText(data))
+      const message = asText(data)
+      const rejected = subscriptionFrameError(message, options.schema, limits)
+      if (rejected !== undefined) {
+        ws.send(
+          JSON.stringify({
+            id: rejected.id,
+            type: "error",
+            payload: [{ message: rejected.message }],
+          }),
+        )
+        return
+      }
+      try {
+        const frame = recordOf(JSON.parse(message))
+        if (frame?.type === "subscribe" && typeof frame.id === "string") {
+          if (ws.data.subscriptions.size >= maxSubscriptions) {
+            ws.send(
+              JSON.stringify({
+                id: frame.id,
+                type: "error",
+                payload: [{ message: "Subscription limit exceeded." }],
+              }),
+            )
+            return
+          }
+          ws.data.subscriptions.add(frame.id)
+        } else if (frame?.type === "complete" && typeof frame.id === "string") {
+          ws.data.subscriptions.delete(frame.id)
+        }
+      } catch {
+        // graphql-ws owns malformed protocol-frame handling; pass it through unchanged.
+      }
+      void ws.data.dispatch?.(message)
     },
 
     close(ws: NifraWebSocket<GraphqlWsConnection>, code: number, reason: string): void {
-      void ws.data.closed?.(code, reason)
+      ws.data.subscriptions.clear()
+      // The socket is gone: a failing iterator return() or onClose hook has no one left to answer.
+      void Promise.resolve(ws.data.closed?.(code, reason)).catch(() => {})
     },
   }
 }