@nifrajs/graphql 4.0.2 → 5.1.0

package/src/http.ts

@@ -6,7 +6,8 @@
  * (`@nifrajs/core/edge-kit`'s {@link readBodyFramed}).
  *
  * Spec: https://graphql.github.io/graphql-over-http/draft/. POST carries `{query, operationName?,
- * variables?, extensions?}` as `application/json`; GET carries them as query-string params and may run
+ * variables?, extensions?}` as `application/json` (any other media type answers 415, so a cross-site
+ * form cannot post a mutation); GET carries them as query-string params and may run
  * **queries only** (never a mutation) so it stays a safe, cacheable idempotent method. Responses use the
  * `application/graphql-response+json` media type with spec status codes by default; set
  * `legacyJsonResponse` for the old always-200 `application/json` shape older clients expect.
@@ -35,7 +36,6 @@ import {
   getOperationAST,
   parse,
   Source,
-  specifiedRules,
   validate,
 } from "graphql"
 import {
@@ -49,8 +49,10 @@ import {
   documentMetrics,
   type GraphqlLimits,
   graphqlLimits,
+  overlapLimitError,
   requestLimitError,
   safeFormattedError,
+  validationRules,
 } from "./limits.ts"
 
 const DEFAULT_MAX_BODY_BYTES = 1_000_000
@@ -84,10 +86,24 @@ export interface GraphqlHttpOptions<Context = unknown, Env = unknown> {
   readonly maxComplexity?: number
   /** Maximum operation definitions in one document. Default 10. */
   readonly maxOperations?: number
-  /** Maximum asynchronous resolver execution time. Default 10 seconds. */
+  /**
+   * Maximum pairs of fields sharing a response name in one selection set, counted through fragments.
+   * Validation compares every such pair, so this bounds its cost. Default 2,000.
+   */
+  readonly maxFieldOverlaps?: number
+  /**
+   * Maximum asynchronous resolver execution time. Default 10 seconds. The execution's abort signal,
+   * which a resolver reads through `info.getAbortSignal()`, is aborted at this deadline and when the
+   * request itself is aborted.
+   */
   readonly executionTimeoutMs?: number
   /** Prototype-pollution policy for the parsed JSON body. Default `"reject"`. */
   readonly protoPoisoning?: ProtoPoisoning
+  /**
+   * Answer introspection queries (`__schema`, `__type`). Default `true`. Set `false` to refuse them
+   * as a validation error (400); `__typename` still resolves. Shared with `subscriptions`.
+   */
+  readonly introspection?: boolean
   /** Optional root value passed to the executor. */
   readonly rootValue?: unknown
   /**
@@ -96,8 +112,8 @@ export interface GraphqlHttpOptions<Context = unknown, Env = unknown> {
    */
   readonly allowedOrigins?: readonly string[]
   /**
-   * Per-request authorization, run after the body parses and before execution. Return `false` to answer
-   * `401` with a GraphQL error envelope and skip execution entirely.
+   * Per-request authorization, run after the origin check and before the body is read or parsed; a
+   * CORS preflight (`OPTIONS`) skips it. Return `false` to answer `401` with a GraphQL error envelope.
    */
   readonly authorize?: (request: Request) => boolean | Promise<boolean>
   /** Emit the legacy always-200 `application/json` response shape instead of `application/graphql-response+json`. */
@@ -195,6 +211,12 @@ function parseVariables(raw: unknown): Record<string, unknown> | null {
   return parsed as Record<string, unknown>
 }
 
+/** `application/json` or a structured `+json` type, parameters ignored. */
+function isJsonMediaType(header: string | null): boolean {
+  const essence = header?.split(";", 1)[0]?.trim().toLowerCase() ?? ""
+  return essence === "application/json" || /^application\/[a-z0-9.+-]+\+json$/.test(essence)
+}
+
 /** Read `{query, operationName, variables}` from a parsed POST body. Throws GraphQLError when malformed. */
 function paramsFromBody(body: unknown): GraphqlParams {
   if (body === null || typeof body !== "object" || Array.isArray(body)) {
@@ -247,12 +269,10 @@ async function run<Context, Env>(
     return requestError("", 400, legacy, cors, [gqlErr], opts.formatError)
   }
 
-  const validationErrors = validate(opts.schema, document, specifiedRules)
-  if (validationErrors.length > 0) {
-    return requestError("", 400, legacy, cors, validationErrors, opts.formatError)
-  }
-
-  const documentLimit = documentLimitError(documentMetrics(document), limits)
+  // Every limit runs before validate(): its overlap rule is quadratic, so a small document within the
+  // byte limit can hold the event loop for seconds.
+  const documentLimit =
+    documentLimitError(documentMetrics(document), limits) ?? overlapLimitError(document, limits)
   if (documentLimit !== undefined) {
     return requestError(
       documentLimit,
@@ -264,6 +284,11 @@ async function run<Context, Env>(
     )
   }
 
+  const validationErrors = validate(opts.schema, document, validationRules(opts.introspection))
+  if (validationErrors.length > 0) {
+    return requestError("", 400, legacy, cors, validationErrors, opts.formatError)
+  }
+
   // GET is idempotent and cacheable, so per the GraphQL-over-HTTP spec it may run queries only.
   const operationAst = getOperationAST(document, params.operationName ?? undefined)
   if (isGet && operationAst != null && operationAst.operation !== "query") {
@@ -295,15 +320,20 @@ async function run<Context, Env>(
 
   let result: ExecutionResult
   try {
-    const execution = execute({
-      schema: opts.schema,
-      document,
-      rootValue: opts.rootValue,
-      contextValue,
-      variableValues: params.variables ?? undefined,
-      operationName: params.operationName ?? undefined,
-    })
-    result = (await withExecutionTimeout(execution, executionTimeoutMs)) as ExecutionResult
+    result = await withExecutionTimeout(
+      (abortSignal) =>
+        execute({
+          schema: opts.schema,
+          document,
+          rootValue: opts.rootValue,
+          contextValue,
+          variableValues: params.variables ?? undefined,
+          operationName: params.operationName ?? undefined,
+          abortSignal,
+        }),
+      request.signal,
+      executionTimeoutMs,
+    )
   } catch (err) {
     const gqlErr =
       err instanceof GraphQLError
@@ -342,11 +372,23 @@ class ExecutionTimeoutError extends Error {
   }
 }
 
-async function withExecutionTimeout<T>(work: T | Promise<T>, timeoutMs: number): Promise<T> {
+/** Run `start` under a deadline. A timeout rejects and aborts the signal resolvers were given. */
+async function withExecutionTimeout<T>(
+  start: (abortSignal: AbortSignal) => T | Promise<T>,
+  outer: AbortSignal,
+  timeoutMs: number,
+): Promise<T> {
+  const controller = new AbortController()
+  const work = start(AbortSignal.any([outer, controller.signal]))
   if (!(work instanceof Promise) || timeoutMs === 0) return work
   let timer: ReturnType<typeof setTimeout> | undefined
   const timeout = new Promise<T>((_, reject) => {
-    timer = setTimeout(() => reject(new ExecutionTimeoutError()), timeoutMs)
+    timer = setTimeout(() => {
+      const error = new ExecutionTimeoutError()
+      // Rejected first: the abort can reject the work, and the race must settle on the timeout.
+      reject(error)
+      controller.abort(error)
+    }, timeoutMs)
   })
   try {
     return await Promise.race([work, timeout])
@@ -412,6 +454,19 @@ export async function respondGraphql<Context = unknown, Env = unknown>(
     )
   }
 
+  // Checked before the body is read: urlencoded, multipart and text/plain are what a browser sends
+  // cross-site without a preflight, so accepting one would let a form run a mutation with cookies.
+  if (!isJsonMediaType(request.headers.get("content-type"))) {
+    return requestError(
+      "Unsupported media type.",
+      415,
+      legacy,
+      cors,
+      [new GraphQLError("A POST body must be sent as application/json.")],
+      options.formatError,
+    )
+  }
+
   // Read the JSON body through core's single bounded + proto-guarded framing lane.
   return readBodyFramed<Response>(
     request,

package/src/index.ts

@@ -22,7 +22,12 @@ export type {
 } from "./context.ts"
 export { buildContext } from "./context.ts"
 export { type GraphqlHttpOptions, respondGraphql } from "./http.ts"
-export { createPubSub, type GraphqlPubSub } from "./pubsub.ts"
+export {
+  createPubSub,
+  type GraphqlPubSub,
+  type GraphqlPubSubOptions,
+  GraphqlPubSubOverflowError,
+} from "./pubsub.ts"
 export { type GraphqlWsOptions, graphqlWebSocket } from "./ws.ts"
 
 /** The structural slice of a nifra server `mountGraphql` needs. Kept loose so core stays a peer dep. */
@@ -43,12 +48,42 @@ export interface MountGraphqlOptions<Context = unknown, Env = unknown>
   /** Enable `GET /graphql` (queries only). Default `true`. */
   readonly enableGet?: boolean
   /**
-   * Enable `graphql-transport-ws` subscriptions on the same path. Pass the WS options (or `true` to
-   * reuse `schema`/`context`). Requires the app to have `.use(websocket())` and `graphql-ws` installed.
+   * Enable `graphql-transport-ws` subscriptions on the same path. Pass `true` to reuse `schema`,
+   * `context`, `authorize` (run on the upgrade request) and the query limits, or pass the WS options.
+   * With `authorize` set, WS options must bring their own `authorize` or `onConnect`; the mount throws
+   * otherwise, since every socket would be admitted. Requires `.use(websocket())` and `graphql-ws`.
    */
   readonly subscriptions?: boolean | GraphqlWsOptions<Record<string, unknown>>
 }
 
+type Writable<T> = { -readonly [K in keyof T]: T[K] }
+
+const SHARED_LIMITS = [
+  "maxQueryBytes",
+  "maxVariablesBytes",
+  "maxDepth",
+  "maxAliases",
+  "maxComplexity",
+  "maxOperations",
+  "maxFieldOverlaps",
+  "executionTimeoutMs",
+] as const
+
+/** The socket transport of `subscriptions: true`: the HTTP endpoint's schema, context, authorization and limits. */
+function sharedWsOptions<Context, Env>(
+  options: MountGraphqlOptions<Context, Env>,
+): GraphqlWsOptions<Record<string, unknown>> {
+  const shared: Writable<GraphqlWsOptions<Record<string, unknown>>> = { schema: options.schema }
+  const ctx = options.context as GraphqlContextBuilder<Record<string, unknown>> | undefined
+  if (ctx !== undefined) shared.context = ctx
+  if (options.authorize !== undefined) shared.authorize = options.authorize
+  for (const limit of SHARED_LIMITS) {
+    const value = options[limit]
+    if (value !== undefined) shared[limit] = value
+  }
+  return shared
+}
+
 /**
  * Mount a GraphQL endpoint. Wires `POST` (and `GET`, unless disabled) on `path`, injecting the nifra
  * route context into your resolver context, and - when `subscriptions` is set - a `graphql-ws` WebSocket
@@ -87,13 +122,22 @@ export function mountGraphql<Context = unknown, Env = unknown>(
         "mountGraphql: subscriptions require a WebSocket-enabled app - call `.use(websocket())` first.",
       )
     }
-    let wsOptions: GraphqlWsOptions<Record<string, unknown>>
-    if (options.subscriptions === true) {
-      const ctx = options.context as GraphqlContextBuilder<Record<string, unknown>> | undefined
-      wsOptions =
-        ctx !== undefined ? { schema: options.schema, context: ctx } : { schema: options.schema }
-    } else {
-      wsOptions = options.subscriptions
+    const given = options.subscriptions === true ? sharedWsOptions(options) : options.subscriptions
+    // A schema hidden over HTTP stays hidden over the socket unless the WS options say otherwise.
+    const wsOptions =
+      options.introspection === false && given.introspection === undefined
+        ? { ...given, introspection: false }
+        : given
+    if (
+      options.authorize !== undefined &&
+      wsOptions.authorize === undefined &&
+      wsOptions.onConnect === undefined
+    ) {
+      throw new Error(
+        "mountGraphql: `authorize` guards the HTTP endpoint only, and these subscription options " +
+          "admit every socket. Give them their own `authorize` or `onConnect`, or pass " +
+          "`subscriptions: true` to reuse `authorize`.",
+      )
     }
     app.ws(path, graphqlWebSocket(wsOptions))
   }

package/src/limits.ts

@@ -1,4 +1,25 @@
-import { type DocumentNode, type GraphQLError, Kind, type SelectionNode } from "graphql"
+import {
+  type DocumentNode,
+  type GraphQLError,
+  Kind,
+  NoSchemaIntrospectionCustomRule,
+  type SelectionNode,
+  type SelectionSetNode,
+  specifiedRules,
+  type ValidationRule,
+  visit,
+} from "graphql"
+
+const RULES_WITHOUT_INTROSPECTION: readonly ValidationRule[] = [
+  ...specifiedRules,
+  NoSchemaIntrospectionCustomRule,
+]
+
+/** The rules a transport validates with: graphql's own, plus a refusal of `__schema` and `__type`
+ * fields when `introspection` is `false`. */
+export function validationRules(introspection: boolean | undefined): readonly ValidationRule[] {
+  return introspection === false ? RULES_WITHOUT_INTROSPECTION : specifiedRules
+}
 
 export const DEFAULT_GRAPHQL_LIMITS = Object.freeze({
   maxQueryBytes: 64 * 1024,
@@ -7,6 +28,7 @@ export const DEFAULT_GRAPHQL_LIMITS = Object.freeze({
   maxAliases: 100,
   maxComplexity: 1_000,
   maxOperations: 10,
+  maxFieldOverlaps: 2_000,
 })
 
 export interface GraphqlLimitsOptions {
@@ -16,6 +38,7 @@ export interface GraphqlLimitsOptions {
   readonly maxAliases?: number
   readonly maxComplexity?: number
   readonly maxOperations?: number
+  readonly maxFieldOverlaps?: number
 }
 
 export interface GraphqlLimits {
@@ -25,6 +48,7 @@ export interface GraphqlLimits {
   readonly maxAliases: number
   readonly maxComplexity: number
   readonly maxOperations: number
+  readonly maxFieldOverlaps: number
 }
 
 function limit(value: number | undefined, fallback: number, name: string, minimum: number): number {
@@ -63,6 +87,12 @@ export function graphqlLimits(options: GraphqlLimitsOptions = {}): GraphqlLimits
       "maxOperations",
       1,
     ),
+    maxFieldOverlaps: limit(
+      options.maxFieldOverlaps,
+      DEFAULT_GRAPHQL_LIMITS.maxFieldOverlaps,
+      "maxFieldOverlaps",
+      0,
+    ),
   }
 }
 
@@ -172,6 +202,113 @@ export function requestLimitError(
   return undefined
 }
 
+/**
+ * Pairs of same-named fields across every selection set, the work graphql-js's
+ * OverlappingFieldsCanBeMerged rule does: it compares every two fields that share a response name in
+ * one selection set, counting the fields its fragment spreads and inline fragments bring in. A few
+ * thousand bytes of `b(x: 1) b(x: 2) ...` hold within the depth and complexity limits yet cost seconds
+ * of synchronous validation, so this is counted, and refused, before `validate()` runs. Measured
+ * once {@link documentLimitError} passes and no fragment is unused, the fields it walks are bounded
+ * by `maxComplexity`.
+ */
+export function fieldOverlaps(document: DocumentNode): number {
+  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)
+    }
+  }
+  const fragmentNames = new Map<string, ReadonlyMap<string, number>>()
+  const expanding = new Set<string>()
+  const add = (
+    selections: readonly SelectionNode[],
+    names: Map<string, number>,
+    spread: Set<string>,
+  ): void => {
+    for (const selection of selections) {
+      if (selection.kind === Kind.FIELD) {
+        const name = selection.alias?.value ?? selection.name.value
+        names.set(name, (names.get(name) ?? 0) + 1)
+      } else if (selection.kind === Kind.INLINE_FRAGMENT) {
+        add(selection.selectionSet.selections, names, spread)
+      } else if (!spread.has(selection.name.value)) {
+        spread.add(selection.name.value)
+        for (const [name, count] of fragmentNamesOf(selection.name.value)) {
+          names.set(name, (names.get(name) ?? 0) + count)
+        }
+      }
+    }
+  }
+  // An unknown fragment and a cycle, both refused by validation, contribute nothing.
+  const fragmentNamesOf = (fragment: string): ReadonlyMap<string, number> => {
+    const known = fragmentNames.get(fragment)
+    if (known !== undefined) return known
+    const selections = fragments.get(fragment)
+    if (selections === undefined || expanding.has(fragment)) return new Map()
+    expanding.add(fragment)
+    const names = new Map<string, number>()
+    add(selections, names, new Set([fragment]))
+    expanding.delete(fragment)
+    fragmentNames.set(fragment, names)
+    return names
+  }
+  let pairs = 0
+  visit(document, {
+    SelectionSet(node: SelectionSetNode) {
+      const names = new Map<string, number>()
+      add(node.selections, names, new Set())
+      for (const count of names.values()) pairs += (count * (count - 1)) / 2
+    },
+  })
+  return pairs
+}
+
+/** The first fragment no operation reaches; graphql-js refuses it, and no limit above counts it. */
+function unusedFragment(document: DocumentNode): string | undefined {
+  const spreads = new Map<string, readonly string[]>()
+  const pending: string[] = []
+  const spreadsIn = (node: DocumentNode["definitions"][number]): string[] => {
+    const names: string[] = []
+    visit(node, {
+      FragmentSpread(spread) {
+        names.push(spread.name.value)
+      },
+    })
+    return names
+  }
+  for (const definition of document.definitions) {
+    if (definition.kind === Kind.FRAGMENT_DEFINITION) {
+      spreads.set(definition.name.value, spreadsIn(definition))
+    } else if (definition.kind === Kind.OPERATION_DEFINITION) {
+      pending.push(...spreadsIn(definition))
+    }
+  }
+  const reached = new Set<string>()
+  for (let name = pending.pop(); name !== undefined; name = pending.pop()) {
+    if (reached.has(name)) continue
+    reached.add(name)
+    pending.push(...(spreads.get(name) ?? []))
+  }
+  for (const name of spreads.keys()) if (!reached.has(name)) return name
+  return undefined
+}
+
+/**
+ * Refuses, before `validate()`, the documents whose overlap validation is expensive: too many
+ * same-named field pairs, or a fragment no operation uses (its fields escape `maxComplexity`). Run it
+ * after {@link documentLimitError} passes.
+ */
+export function overlapLimitError(
+  document: DocumentNode,
+  limits: GraphqlLimits,
+): string | undefined {
+  const unused = unusedFragment(document)
+  if (unused !== undefined) return `Fragment "${unused}" is never used.`
+  return fieldOverlaps(document) > limits.maxFieldOverlaps
+    ? `GraphQL document repeats field names in one selection set beyond the limit of ${limits.maxFieldOverlaps} same-named field pairs.`
+    : undefined
+}
+
 export function documentLimitError(
   metrics: GraphqlDocumentMetrics,
   limits: GraphqlLimits,

package/src/pubsub.ts

@@ -18,8 +18,34 @@ export interface GraphqlPubSub<Event = unknown> {
   subscribe(topic: string): AsyncIterableIterator<Event>
 }
 
-/** Create an in-memory {@link GraphqlPubSub}. */
-export function createPubSub<Event = unknown>(): GraphqlPubSub<Event> {
+export interface GraphqlPubSubOptions {
+  /** Maximum queued events per subscriber. Positive safe integer; default 1024. */
+  readonly maxQueuedEvents?: number
+  /** A full queue closes with an error by default. Dropping requires explicit opt-in. */
+  readonly overflow?: "error" | "drop-oldest" | "drop-newest"
+}
+
+export class GraphqlPubSubOverflowError extends Error {
+  readonly code = "graphql_pubsub_overflow"
+
+  constructor() {
+    super("GraphQL subscription event queue is full")
+    this.name = "GraphqlPubSubOverflowError"
+  }
+}
+
+/** Create an in-memory {@link GraphqlPubSub} with finite subscriber queues. */
+export function createPubSub<Event = unknown>(
+  options: GraphqlPubSubOptions = {},
+): GraphqlPubSub<Event> {
+  const maxQueuedEvents = options.maxQueuedEvents ?? 1024
+  const overflow = options.overflow ?? "error"
+  if (!Number.isSafeInteger(maxQueuedEvents) || maxQueuedEvents < 1) {
+    throw new RangeError("createPubSub maxQueuedEvents must be a positive safe integer")
+  }
+  if (overflow !== "error" && overflow !== "drop-oldest" && overflow !== "drop-newest") {
+    throw new TypeError("createPubSub overflow must be error, drop-oldest or drop-newest")
+  }
   const topics = new Map<string, Set<Sink<Event>>>()
 
   const publish = (topic: string, payload: Event): void => {
@@ -35,7 +61,7 @@ export function createPubSub<Event = unknown>(): GraphqlPubSub<Event> {
       topics.set(topic, sinks)
     }
     const set = sinks
-    const sink = createSink<Event>(() => {
+    const sink = createSink<Event>(maxQueuedEvents, overflow, () => {
       set.delete(sink)
       if (set.size === 0) topics.delete(topic)
     })
@@ -46,16 +72,21 @@ export function createPubSub<Event = unknown>(): GraphqlPubSub<Event> {
   return { publish, subscribe }
 }
 
-/** One subscriber: a bounded push queue bridged to an async iterator with backpressure via awaiting pulls. */
+/** Awaiting pulls consume immediately; synchronous publish cannot provide producer backpressure. */
 interface Sink<Event> {
   push(payload: Event): void
   readonly iterator: AsyncIterableIterator<Event>
 }
 
-function createSink<Event>(onClose: () => void): Sink<Event> {
+function createSink<Event>(
+  maxQueuedEvents: number,
+  overflow: NonNullable<GraphqlPubSubOptions["overflow"]>,
+  onClose: () => void,
+): Sink<Event> {
   const queue: Event[] = []
   const pulls: Array<(result: IteratorResult<Event>) => void> = []
   let done = false
+  let failure: GraphqlPubSubOverflowError | undefined
 
   const push = (payload: Event): void => {
     if (done) return
@@ -64,12 +95,22 @@ function createSink<Event>(onClose: () => void): Sink<Event> {
       pull({ value: payload, done: false })
       return
     }
+    if (queue.length >= maxQueuedEvents) {
+      if (overflow === "drop-newest") return
+      if (overflow === "error") {
+        failure = new GraphqlPubSubOverflowError()
+        finish()
+        return
+      }
+      queue.shift()
+    }
     queue.push(payload)
   }
 
   const finish = (): IteratorResult<Event> => {
     if (!done) {
       done = true
+      queue.length = 0
       onClose()
       for (const pull of pulls.splice(0)) pull({ value: undefined, done: true })
     }
@@ -78,14 +119,22 @@ function createSink<Event>(onClose: () => void): Sink<Event> {
 
   const iterator: AsyncIterableIterator<Event> = {
     next(): Promise<IteratorResult<Event>> {
-      if (queue.length > 0) return Promise.resolve({ value: queue.shift() as Event, done: false })
+      if (failure !== undefined) {
+        const error = failure
+        failure = undefined
+        return Promise.reject(error)
+      }
       if (done) return Promise.resolve({ value: undefined, done: true })
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a nonempty queue owns one Event; undefined is itself a valid Event payload.
+      if (queue.length > 0) return Promise.resolve({ value: queue.shift() as Event, done: false })
       return new Promise((resolve) => pulls.push(resolve))
     },
     return(): Promise<IteratorResult<Event>> {
+      failure = undefined
       return Promise.resolve(finish())
     },
     throw(err?: unknown): Promise<IteratorResult<Event>> {
+      failure = undefined
       finish()
       return Promise.reject(err)
     },