@nifrajs/graphql 3.2.0

package/src/http.ts

@@ -0,0 +1,326 @@
+/**
+ * The GraphQL-over-HTTP transport - a plain Web `fetch` handler you mount at `POST /graphql` (and
+ * optionally `GET /graphql`). It parses, validates, and executes against your `GraphQLSchema` using
+ * `graphql`'s own `parse`/`validate`/`execute`; no server framework is re-bundled and no second HTTP
+ * trust boundary is created - the request body is read through core's one bounded/proto-guarded lane
+ * (`@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
+ * **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.
+ *
+ * PRIVACY: the handler never logs the query text, variables, or the request body. GraphQL documents are
+ * user payloads; keeping them out of this package's output is the guardrail (a payload sink is an
+ * operated concern, not a public-package one).
+ */
+
+import {
+  EMPTY_RESPONSE_CONTROLS,
+  type ProtoPoisoning,
+  plainError,
+  queryObjectOf,
+  type ResponseResult,
+  readBodyFramed,
+  searchOf,
+  toResponse,
+} from "@nifrajs/core/edge-kit"
+import {
+  type DocumentNode,
+  type ExecutionResult,
+  execute,
+  GraphQLError,
+  type GraphQLSchema,
+  getOperationAST,
+  parse,
+  Source,
+  specifiedRules,
+  validate,
+} from "graphql"
+import {
+  buildContext,
+  type GraphqlContextBuilder,
+  type GraphqlContextInput,
+  type NifraContextLike,
+} from "./context.ts"
+
+const DEFAULT_MAX_BODY_BYTES = 1_000_000
+const GRAPHQL_RESPONSE_JSON = "application/graphql-response+json; charset=utf-8"
+const JSON_UTF8 = "application/json; charset=utf-8"
+
+const CORS_BASE: Record<string, string> = {
+  "access-control-allow-methods": "GET, POST, OPTIONS",
+  "access-control-allow-headers": "content-type, authorization",
+  "access-control-max-age": "86400",
+}
+
+export interface GraphqlHttpOptions<Context = unknown, Env = unknown> {
+  /** The executable schema (types + resolvers), e.g. from `graphql`'s `buildSchema` or a schema builder. */
+  readonly schema: GraphQLSchema
+  /** Build the resolver `contextValue` from the request (and nifra context when mounted). */
+  readonly context?: GraphqlContextBuilder<Context, Env>
+  /** The nifra route context, when the caller has one (supplied by `mountGraphql`). */
+  readonly nifra?: NifraContextLike<Env>
+  /** Maximum request body size in bytes. Default 1 MB. Rejected bodies answer 413. */
+  readonly maxBodyBytes?: number
+  /** Prototype-pollution policy for the parsed JSON body. Default `"reject"`. */
+  readonly protoPoisoning?: ProtoPoisoning
+  /** Optional root value passed to the executor. */
+  readonly rootValue?: unknown
+  /**
+   * Origin allowlist for the CORS `access-control-allow-origin` header. Omit to reflect any origin
+   * (`*`) - correct for a public API; set it to lock the browser callers down.
+   */
+  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.
+   */
+  readonly authorize?: (request: Request) => boolean | Promise<boolean>
+  /** Emit the legacy always-200 `application/json` response shape instead of `application/graphql-response+json`. */
+  readonly legacyJsonResponse?: boolean
+}
+
+/** A parsed GraphQL request payload (POST body or GET query string), before validation. */
+interface GraphqlParams {
+  readonly query: string
+  readonly operationName: string | null
+  readonly variables: Record<string, unknown> | null
+}
+
+function assertByteLimit(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RangeError("GraphQL maxBodyBytes must be a non-negative safe integer")
+  }
+}
+
+function corsFor(
+  request: Request,
+  allowedOrigins: readonly string[] | undefined,
+): Record<string, string> | null {
+  if (allowedOrigins === undefined) return { ...CORS_BASE, "access-control-allow-origin": "*" }
+  const origin = request.headers.get("origin")
+  if (origin === null) return { ...CORS_BASE, vary: "Origin" }
+  if (allowedOrigins.includes(origin)) {
+    return { ...CORS_BASE, "access-control-allow-origin": origin, vary: "Origin" }
+  }
+  return null
+}
+
+/** Render a rejection from readBodyFramed - a `Response` passes through, a `ResponseResult` is rendered
+ * through the same core renderer the full Server uses, so the wire bytes match. */
+function render(r: Response | ResponseResult): Response {
+  return r instanceof Response ? r : toResponse(r, EMPTY_RESPONSE_CONTROLS)
+}
+
+/** Serialize an execution/error payload to a JSON `Response` with the negotiated media type + status.
+ * `payload` is any JSON-serializable GraphQL result (`{data?, errors?}`); GraphQLError values serialize
+ * via their own `toJSON`. */
+function graphqlResponse(
+  payload: unknown,
+  status: number,
+  legacy: boolean,
+  cors: Record<string, string>,
+): Response {
+  return new Response(JSON.stringify(payload), {
+    status: legacy ? 200 : status,
+    headers: { "content-type": legacy ? JSON_UTF8 : GRAPHQL_RESPONSE_JSON, ...cors },
+  })
+}
+
+/** A request-level (parse/validate/auth/method) failure: `{ errors: [...] }`, no `data` key. */
+function requestError(
+  message: string,
+  status: number,
+  legacy: boolean,
+  cors: Record<string, string>,
+  errors?: readonly GraphQLError[],
+): Response {
+  const payload = errors ?? [new GraphQLError(message)]
+  return graphqlResponse({ errors: payload.map((e) => e.toJSON()) }, status, legacy, cors)
+}
+
+/** Coerce a `?variables=<json>` string (GET) into an object, or throw a GraphQLError on bad JSON. */
+function parseVariables(raw: unknown): Record<string, unknown> | null {
+  if (raw === undefined || raw === null || raw === "") return null
+  if (typeof raw === "object") return raw as Record<string, unknown>
+  if (typeof raw !== "string") throw new GraphQLError("Variables must be a JSON object.")
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new GraphQLError("Variables are invalid JSON.")
+  }
+  if (parsed === null) return null
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new GraphQLError("Variables must be a JSON object.")
+  }
+  return parsed as Record<string, unknown>
+}
+
+/** 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)) {
+    throw new GraphQLError("POST body must be a JSON object.")
+  }
+  const b = body as Record<string, unknown>
+  if (typeof b.query !== "string" || b.query.length === 0) {
+    throw new GraphQLError("A `query` string is required.")
+  }
+  const operationName = typeof b.operationName === "string" ? b.operationName : null
+  return { query: b.query, operationName, variables: parseVariables(b.variables) }
+}
+
+/** Read the same shape from a GET query string. */
+function paramsFromQuery(query: Record<string, unknown>): GraphqlParams {
+  const q = query.query
+  if (typeof q !== "string" || q.length === 0)
+    throw new GraphQLError("A `query` parameter is required.")
+  const operationName = typeof query.operationName === "string" ? query.operationName : null
+  return { query: q, operationName, variables: parseVariables(query.variables) }
+}
+
+/** Parse, validate, and execute one already-extracted GraphQL request. */
+async function run<Context, Env>(
+  params: GraphqlParams,
+  request: Request,
+  opts: GraphqlHttpOptions<Context, Env>,
+  isGet: boolean,
+  legacy: boolean,
+  cors: Record<string, string>,
+): Promise<Response> {
+  let document: DocumentNode
+  try {
+    document = parse(new Source(params.query, "GraphQL request"))
+  } catch (err) {
+    const gqlErr = err instanceof GraphQLError ? err : new GraphQLError(String(err))
+    return requestError("", 400, legacy, cors, [gqlErr])
+  }
+
+  const validationErrors = validate(opts.schema, document, specifiedRules)
+  if (validationErrors.length > 0) {
+    return requestError("", 400, legacy, cors, validationErrors)
+  }
+
+  // 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") {
+    return requestError(
+      "Only query operations may run over GET.",
+      405,
+      legacy,
+      { ...cors, allow: "POST" },
+      [new GraphQLError("Only query operations are allowed over GET.")],
+    )
+  }
+
+  const contextInput: GraphqlContextInput<Env> =
+    opts.nifra !== undefined ? { request, nifra: opts.nifra } : { request }
+  let contextValue: Context
+  try {
+    contextValue = await buildContext(opts.context, contextInput)
+  } catch (err) {
+    const gqlErr =
+      err instanceof GraphQLError ? err : new GraphQLError("Failed to build request context.")
+    return graphqlResponse({ errors: [gqlErr.toJSON()] }, 500, legacy, cors)
+  }
+
+  let result: ExecutionResult
+  try {
+    result = (await execute({
+      schema: opts.schema,
+      document,
+      rootValue: opts.rootValue,
+      contextValue,
+      variableValues: params.variables ?? undefined,
+      operationName: params.operationName ?? undefined,
+    })) as ExecutionResult
+  } catch (err) {
+    const gqlErr = err instanceof GraphQLError ? err : new GraphQLError("Execution failed.")
+    return graphqlResponse({ errors: [gqlErr.toJSON()] }, 400, legacy, cors)
+  }
+
+  // Field/execution errors are a normal 200 result with both `data` and `errors`.
+  return graphqlResponse(result, 200, legacy, cors)
+}
+
+/**
+ * Handle one GraphQL HTTP request. Never throws - a malformed request becomes a GraphQL error envelope.
+ * Mount it directly (`app.all('/graphql', (c) => respondGraphql(c.req, { schema }))`) or via
+ * {@link mountGraphql}, which also wires the nifra context in.
+ */
+export async function respondGraphql<Context = unknown, Env = unknown>(
+  request: Request,
+  options: GraphqlHttpOptions<Context, Env>,
+): Promise<Response> {
+  const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  assertByteLimit(maxBytes)
+  const legacy = options.legacyJsonResponse === true
+
+  const cors = corsFor(request, options.allowedOrigins)
+  if (cors === null) return new Response(null, { status: 403 })
+
+  if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: cors })
+
+  if (options.authorize !== undefined) {
+    const ok = await options.authorize(request)
+    if (!ok) {
+      return requestError("Unauthorized.", 401, legacy, cors, [new GraphQLError("Unauthorized.")])
+    }
+  }
+
+  if (request.method === "GET") {
+    let params: GraphqlParams
+    try {
+      params = paramsFromQuery(queryObjectOf(searchOf(request.url)) as Record<string, unknown>)
+    } catch (err) {
+      const gqlErr = err instanceof GraphQLError ? err : new GraphQLError(String(err))
+      return requestError("", 400, legacy, cors, [gqlErr])
+    }
+    return run(params, request, options, true, legacy, cors)
+  }
+
+  if (request.method !== "POST") {
+    return requestError("Method not allowed.", 405, legacy, { ...cors, allow: "GET, POST" }, [
+      new GraphQLError("Only GET and POST are supported."),
+    ])
+  }
+
+  // Read the JSON body through core's single bounded + proto-guarded framing lane.
+  return readBodyFramed<Response>(
+    request,
+    maxBytes,
+    options.protoPoisoning ?? "reject",
+    async (parsed) => {
+      let params: GraphqlParams
+      try {
+        params = paramsFromBody(parsed)
+      } catch (err) {
+        const gqlErr = err instanceof GraphQLError ? err : new GraphQLError(String(err))
+        return requestError("", 400, legacy, cors, [gqlErr])
+      }
+      return run(params, request, options, false, legacy, cors)
+    },
+    (response: Response | ResponseResult) => {
+      // readBodyFramed's own rejections (413 too-large, 415, proto-guard) - render + attach CORS.
+      const res = render(response)
+      for (const [k, v] of Object.entries(cors)) res.headers.set(k, v)
+      return res
+    },
+    (err: unknown) => {
+      // A body that failed to read (bad JSON / proto-guard) is a request error, not a crash.
+      if (err instanceof Response) return err
+      return requestError("Invalid request body.", 400, legacy, cors, [
+        new GraphQLError("Request body could not be read as JSON."),
+      ])
+    },
+  ).catch(() => plainErrorResponse(cors))
+}
+
+/** Last-resort framing fallback so the handler contract ("never throws") holds even on an edge-kit change. */
+function plainErrorResponse(cors: Record<string, string>): Response {
+  const res = render(plainError(400, "bad_request"))
+  for (const [k, v] of Object.entries(cors)) res.headers.set(k, v)
+  return res
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+/**
+ * `@nifrajs/graphql` - mount a GraphQL endpoint on a nifra app.
+ *
+ * - {@link respondGraphql} (`./http.ts`) - a spec-compliant GraphQL-over-HTTP `fetch` handler.
+ * - {@link graphqlWebSocket} (`./ws.ts`) - `graphql-transport-ws` subscriptions over `app.ws()`.
+ * - {@link createPubSub} (`./pubsub.ts`) - an in-memory subscription source; swap for a durable bus.
+ * - {@link mountGraphql} - the one-call sugar that wires POST/GET (and, optionally, subscriptions).
+ *
+ * It executes with `graphql`'s own `parse`/`validate`/`execute`/`subscribe`; no HTTP framework is
+ * re-bundled, the request body reuses core's single bounded trust boundary, and the query text is never
+ * logged. `graphql` is a required peer; `graphql-ws` is optional (needed only for subscriptions).
+ */
+
+import type { GraphqlContextBuilder, NifraContextLike } from "./context.ts"
+import { type GraphqlHttpOptions, respondGraphql } from "./http.ts"
+import { type GraphqlWsOptions, graphqlWebSocket } from "./ws.ts"
+
+export type {
+  GraphqlContextBuilder,
+  GraphqlContextInput,
+  NifraContextLike,
+} from "./context.ts"
+export { buildContext } from "./context.ts"
+export { type GraphqlHttpOptions, respondGraphql } from "./http.ts"
+export { createPubSub, type GraphqlPubSub } 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. */
+interface RouteContextLike<Env = unknown> extends NifraContextLike<Env> {
+  readonly req: Request
+}
+
+interface MountableApp<Env = unknown> {
+  get(path: string, handler: (c: RouteContextLike<Env>) => Response | Promise<Response>): unknown
+  post(path: string, handler: (c: RouteContextLike<Env>) => Response | Promise<Response>): unknown
+  ws?(path: string, handler: unknown): unknown
+}
+
+export interface MountGraphqlOptions<Context = unknown, Env = unknown>
+  extends Omit<GraphqlHttpOptions<Context, Env>, "nifra"> {
+  /** Endpoint path. Default `/graphql`. */
+  readonly path?: string
+  /** 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.
+   */
+  readonly subscriptions?: boolean | GraphqlWsOptions<Record<string, unknown>>
+}
+
+/**
+ * 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
+ * on the same path.
+ *
+ * ```ts
+ * import { server } from "@nifrajs/core"
+ * import { websocket } from "@nifrajs/core/ws"
+ * import { mountGraphql, createPubSub } from "@nifrajs/graphql"
+ *
+ * const pubsub = createPubSub()
+ * const app = server().use(websocket())
+ * mountGraphql(app, {
+ *   schema,
+ *   context: ({ nifra }) => ({ user: nifra?.env, pubsub }),
+ *   subscriptions: true,
+ * })
+ * ```
+ */
+export function mountGraphql<Context = unknown, Env = unknown>(
+  app: MountableApp<Env>,
+  options: MountGraphqlOptions<Context, Env>,
+): void {
+  const path = options.path ?? "/graphql"
+  const enableGet = options.enableGet !== false
+
+  const handle = (c: RouteContextLike<Env>): Promise<Response> =>
+    respondGraphql(c.req, { ...options, nifra: c })
+
+  app.post(path, handle)
+  if (enableGet) app.get(path, handle)
+
+  if (options.subscriptions) {
+    if (typeof app.ws !== "function") {
+      throw new Error(
+        "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
+    }
+    app.ws(path, graphqlWebSocket(wsOptions))
+  }
+}

package/src/pubsub.ts

@@ -0,0 +1,98 @@
+/**
+ * A trivial in-memory pub/sub for `subscription` resolvers - the reference implementation of the
+ * subscription source seam. A resolver's `subscribe` returns `pubsub.subscribe(topic)` (an async
+ * iterator); anything in the process calls `pubsub.publish(topic, payload)` to push an event.
+ *
+ * This is deliberately in-process and unbounded-fan-in only within one server instance - the same
+ * single-instance contract as core's `TopicRegistry`. A durable, multi-instance, or tenant-scoped
+ * pub/sub (Redis, a Durable Object, NATS) is an operated concern: implement the same
+ * `{ publish, subscribe }` shape over your bus and pass it in. Keeping only the in-memory impl here is
+ * the guardrail - a durable payload-carrying sink does not belong in a public package.
+ */
+
+/** The subscription source shape a resolver's `subscribe` consumes. Swap the impl for a durable bus. */
+export interface GraphqlPubSub<Event = unknown> {
+  /** Push `payload` to every open iterator on `topic`. */
+  publish(topic: string, payload: Event): void
+  /** An async iterator that yields each future `publish(topic, ...)` until it is returned/closed. */
+  subscribe(topic: string): AsyncIterableIterator<Event>
+}
+
+/** Create an in-memory {@link GraphqlPubSub}. */
+export function createPubSub<Event = unknown>(): GraphqlPubSub<Event> {
+  const topics = new Map<string, Set<Sink<Event>>>()
+
+  const publish = (topic: string, payload: Event): void => {
+    const sinks = topics.get(topic)
+    if (sinks === undefined) return
+    for (const sink of sinks) sink.push(payload)
+  }
+
+  const subscribe = (topic: string): AsyncIterableIterator<Event> => {
+    let sinks = topics.get(topic)
+    if (sinks === undefined) {
+      sinks = new Set()
+      topics.set(topic, sinks)
+    }
+    const set = sinks
+    const sink = createSink<Event>(() => {
+      set.delete(sink)
+      if (set.size === 0) topics.delete(topic)
+    })
+    set.add(sink)
+    return sink.iterator
+  }
+
+  return { publish, subscribe }
+}
+
+/** One subscriber: a bounded push queue bridged to an async iterator with backpressure via awaiting pulls. */
+interface Sink<Event> {
+  push(payload: Event): void
+  readonly iterator: AsyncIterableIterator<Event>
+}
+
+function createSink<Event>(onClose: () => void): Sink<Event> {
+  const queue: Event[] = []
+  const pulls: Array<(result: IteratorResult<Event>) => void> = []
+  let done = false
+
+  const push = (payload: Event): void => {
+    if (done) return
+    const pull = pulls.shift()
+    if (pull !== undefined) {
+      pull({ value: payload, done: false })
+      return
+    }
+    queue.push(payload)
+  }
+
+  const finish = (): IteratorResult<Event> => {
+    if (!done) {
+      done = true
+      onClose()
+      for (const pull of pulls.splice(0)) pull({ value: undefined, done: true })
+    }
+    return { value: undefined, done: true }
+  }
+
+  const iterator: AsyncIterableIterator<Event> = {
+    next(): Promise<IteratorResult<Event>> {
+      if (queue.length > 0) return Promise.resolve({ value: queue.shift() as Event, done: false })
+      if (done) return Promise.resolve({ value: undefined, done: true })
+      return new Promise((resolve) => pulls.push(resolve))
+    },
+    return(): Promise<IteratorResult<Event>> {
+      return Promise.resolve(finish())
+    },
+    throw(err?: unknown): Promise<IteratorResult<Event>> {
+      finish()
+      return Promise.reject(err)
+    },
+    [Symbol.asyncIterator]() {
+      return this
+    },
+  }
+
+  return { push, iterator }
+}

package/src/ws.ts

@@ -0,0 +1,136 @@
+/**
+ * GraphQL subscriptions over nifra's native WebSocket lane, speaking the `graphql-transport-ws`
+ * protocol (the modern `graphql-ws` wire protocol). This adapts `graphql-ws`'s transport-agnostic
+ * server (`makeServer`) onto a nifra `app.ws()` route, so subscription operations run through the same
+ * socket runtime as every other nifra WebSocket - no separate socket server, no second upgrade path.
+ *
+ * `graphql-ws` owns the per-operation async-iterator lifecycle (one `subscribe` iterator per client
+ * `Subscribe` message, drained to that client's socket). The event *source* those iterators pull from
+ * is yours - typically a {@link ./pubsub.ts | GraphqlPubSub}, whose in-memory reference impl mirrors
+ * core's `TopicRegistry` and can be swapped for a durable bus without touching this transport.
+ *
+ * `graphql-ws` is an optional peer dependency: import this module only when you need subscriptions, and
+ * the dependency (and its bundle weight) stays off every app that doesn't.
+ */
+
+import type { NifraWebSocket, WebSocketContext, WebSocketHandler } from "@nifrajs/core/ws"
+import { execute, type GraphQLSchema, subscribe } from "graphql"
+import {
+  type ConnectionInitMessage,
+  GRAPHQL_TRANSPORT_WS_PROTOCOL,
+  type Context as GraphqlWsContext,
+  makeServer,
+  type ServerOptions,
+} from "graphql-ws"
+import { buildContext, type GraphqlContextBuilder } from "./context.ts"
+
+/** Per-connection state carried on `ws.data` for the graphql-ws bridge. */
+interface GraphqlWsConnection {
+  readonly request: Request
+  /** Feed one raw inbound frame into graphql-ws (registered via its `onMessage`). */
+  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>
+}
+
+export interface GraphqlWsOptions<
+  Context extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /** The executable schema. */
+  readonly schema: GraphQLSchema
+  /** Build the resolver `contextValue` from the upgrade request. Shared with the HTTP transport. */
+  readonly context?: GraphqlContextBuilder<Context>
+  /**
+   * Called once per connection with the client's `connection_init` payload; return `false` (or throw)
+   * to reject the connection. The seam for authenticating a socket from an init token.
+   */
+  readonly onConnect?: (
+    payload: ConnectionInitMessage["payload"],
+    request: Request,
+  ) => boolean | Promise<boolean>
+  /** Additional raw `graphql-ws` server options merged last (advanced escape hatch). */
+  readonly serverOptions?: Partial<ServerOptions>
+}
+
+/** A frame is a string for JSON control messages; graphql-ws only speaks text frames. */
+function asText(data: string | Uint8Array): string {
+  return typeof data === "string" ? data : new TextDecoder().decode(data)
+}
+
+/**
+ * Build a nifra {@link WebSocketHandler} that terminates the `graphql-transport-ws` protocol. Register
+ * it on a route enabled with `.use(websocket())`:
+ *
+ * ```ts
+ * import { websocket } from "@nifrajs/core/ws"
+ * import { graphqlWebSocket } from "@nifrajs/graphql/ws"
+ *
+ * const app = server().use(websocket()).ws("/graphql", graphqlWebSocket({ schema, context }))
+ * ```
+ *
+ * The route MUST negotiate the `graphql-transport-ws` subprotocol at the WebSocket layer for a browser
+ * `graphql-ws` client to connect.
+ */
+export function graphqlWebSocket<Context extends Record<string, unknown> = Record<string, unknown>>(
+  options: GraphqlWsOptions<Context>,
+): WebSocketHandler<GraphqlWsConnection> {
+  const gqlServer = makeServer<Record<string, unknown>, { request: Request }>({
+    schema: options.schema,
+    execute,
+    subscribe,
+    onConnect: options.onConnect
+      ? async (ctx: GraphqlWsContext<Record<string, unknown>, { request: Request }>) => {
+          return await options.onConnect?.(
+            ctx.connectionParams as ConnectionInitMessage["payload"],
+            ctx.extra.request,
+          )
+        }
+      : 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 }
+    },
+
+    open(ws: NifraWebSocket<GraphqlWsConnection>): void {
+      const protocol =
+        (ws.raw as { protocol?: string } | undefined)?.protocol ?? GRAPHQL_TRANSPORT_WS_PROTOCOL
+      let onFrame: ((message: string) => void | Promise<void>) | undefined
+      const closed = gqlServer.opened(
+        {
+          protocol,
+          send: async (data: string) => {
+            ws.send(data)
+          },
+          close: (code: number, reason: string) => {
+            ws.close(code, reason)
+          },
+          onMessage: (cb) => {
+            onFrame = cb
+          },
+        },
+        { request: ws.data.request },
+      )
+      ws.data.closed = closed
+      ws.data.dispatch = (message: string) => onFrame?.(message)
+    },
+
+    message(ws: NifraWebSocket<GraphqlWsConnection>, data: string | Uint8Array): void {
+      // Fire-and-forget: graphql-ws's per-message handler does not resolve until a subscription's
+      // 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))
+    },
+
+    close(ws: NifraWebSocket<GraphqlWsConnection>, code: number, reason: string): void {
+      void ws.data.closed?.(code, reason)
+    },
+  }
+}