@nifrajs/graphql 3.3.0 → 3.5.0

package/src/limits.ts

@@ -0,0 +1,212 @@
+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
+}
+
+function selectionsMetrics(
+  selections: readonly SelectionNode[],
+  fragments: ReadonlyMap<string, readonly SelectionNode[]>,
+  depth: number,
+  activeFragments: ReadonlySet<string>,
+): Omit<GraphqlDocumentMetrics, "operations"> {
+  let maxDepth = depth
+  let aliases = 0
+  let complexity = 0
+  for (const selection of selections) {
+    if (selection.kind === Kind.FIELD) {
+      complexity += 1
+      if (selection.alias !== undefined) aliases += 1
+      if (selection.selectionSet !== undefined) {
+        const nested = selectionsMetrics(
+          selection.selectionSet.selections,
+          fragments,
+          depth + 1,
+          activeFragments,
+        )
+        maxDepth = Math.max(maxDepth, nested.depth)
+        aliases += nested.aliases
+        complexity += nested.complexity
+      } else {
+        maxDepth = Math.max(maxDepth, depth + 1)
+      }
+      continue
+    }
+    if (selection.kind === Kind.INLINE_FRAGMENT) {
+      const nested = selectionsMetrics(
+        selection.selectionSet.selections,
+        fragments,
+        depth,
+        activeFragments,
+      )
+      maxDepth = Math.max(maxDepth, nested.depth)
+      aliases += nested.aliases
+      complexity += nested.complexity
+      continue
+    }
+    const nestedSelections = fragments.get(selection.name.value)
+    if (nestedSelections === undefined || activeFragments.has(selection.name.value)) continue
+    const nextActive = new Set(activeFragments)
+    nextActive.add(selection.name.value)
+    const nested = selectionsMetrics(nestedSelections, fragments, depth, nextActive)
+    maxDepth = Math.max(maxDepth, nested.depth)
+    aliases += nested.aliases
+    complexity += nested.complexity
+  }
+  return { depth: maxDepth, aliases, complexity }
+}
+
+export function documentMetrics(document: DocumentNode): GraphqlDocumentMetrics {
+  const fragments = new Map<string, readonly SelectionNode[]>()
+  for (const definition of document.definitions) {
+    if (definition.kind === Kind.FRAGMENT_DEFINITION) {
+      fragments.set(definition.name.value, definition.selectionSet.selections)
+    }
+  }
+  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, fragments, 0, new Set())
+    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,16 @@
  */
 
 import type { NifraWebSocket, WebSocketContext, WebSocketHandler } from "@nifrajs/core/ws"
-import { execute, type GraphQLSchema, subscribe } from "graphql"
+import {
+  type DocumentNode,
+  execute,
+  GraphQLError,
+  type GraphQLSchema,
+  parse,
+  specifiedRules,
+  subscribe,
+  validate,
+} from "graphql"
 import {
   type ConnectionInitMessage,
   GRAPHQL_TRANSPORT_WS_PROTOCOL,
@@ -23,6 +32,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 +47,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 +67,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 +85,105 @@ 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 } : {}),
+  }
+}
+
+function maskWsFrame(message: string): string {
+  try {
+    const parsed = recordOf(JSON.parse(message))
+    if (parsed === undefined) return message
+    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
+}
+
+async function withWsTimeout<T>(work: T | Promise<T>, timeoutMs: number): Promise<T> {
+  if (!(work instanceof Promise) || timeoutMs === 0) return work
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<T>((_, reject) => {
+    timer = setTimeout(() => reject(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,10 +201,23 @@ 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?.(
@@ -90,12 +230,11 @@ export function graphqlWebSocket<Context extends Record<string, unknown> = Recor
       ? 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 +245,7 @@ export function graphqlWebSocket<Context extends Record<string, unknown> = Recor
         {
           protocol,
           send: async (data: string) => {
-            ws.send(data)
+            ws.send(maskWsFrame(data))
           },
           close: (code: number, reason: string) => {
             ws.close(code, reason)
@@ -126,10 +265,43 @@ 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 {
+      ws.data.subscriptions.clear()
       void ws.data.closed?.(code, reason)
     },
   }