@znight/graphql 0.0.0-stage → 0.2.0

package/src/transport/accept.ts

@@ -0,0 +1,155 @@
+/**
+ * Content negotiation of the GraphQL endpoint (RFC 0005 §8.3): which of the media types the
+ * endpoint produces a request accepts best. Import-free.
+ *
+ * `application/json` is the only type matched by wildcards (`*\/*`, `application/*`): the
+ * GraphQL-over-HTTP draft asks for `application/json` when the client accepts anything, and the
+ * other types change the protocol (`application/graphql-response+json` statuses, an event stream,
+ * the GraphiQL page), so they are chosen only when listed. Among types of equal quality,
+ * `application/graphql-response+json` wins, then `application/json`, then HTML (a browser listing
+ * `text/html` first gets GraphiQL). An event stream is chosen only when it is strictly preferred, or
+ * the only acceptable type: a client listing JSON and `text/event-stream` alike (urql, for
+ * incremental delivery) gets its queries and mutations as one JSON body, and its subscriptions as
+ * a stream ({@link STREAMABLE}).
+ */
+
+/** What a response is encoded as. */
+export const Media: {
+  readonly EventStream: 0
+  readonly GraphQLJson: 1
+  readonly Json: 2
+  readonly Html: 3
+  /** Nothing the endpoint produces is acceptable: 406. */
+  readonly None: 4
+} = Object.freeze({ EventStream: 0, GraphQLJson: 1, Json: 2, Html: 3, None: 4 })
+
+/** One of the {@link Media} values. */
+export type MediaKind = (typeof Media)[keyof typeof Media]
+
+/**
+ * Added to a negotiated JSON type when an event stream is acceptable too, though not preferred: a
+ * subscription, which has no JSON answer, is then streamed. `answer & MEDIA` is the {@link MediaKind}.
+ */
+export const STREAMABLE = 8
+
+/** The {@link MediaKind} bits of a {@link negotiate} answer. */
+export const MEDIA = 7
+
+/** The media type names, by {@link Media} value (`None` excluded). */
+const NAMES: readonly (readonly [type: string, subtype: string])[] = [
+  ['text', 'event-stream'],
+  ['application', 'graphql-response+json'],
+  ['application', 'json'],
+  ['text', 'html'],
+]
+
+/** A media range of an `accept` header. */
+interface Range {
+  readonly type: string
+  readonly subtype: string
+  readonly q: number
+}
+
+/** The media ranges of an `accept` header (lower-case, without parameters other than `q`). */
+function parseRanges(header: string): Range[] {
+  const ranges: Range[] = []
+  for (const item of header.split(',')) {
+    const parts = item.split(';')
+    const media = (parts[0] as string).trim().toLowerCase()
+    const slash = media.indexOf('/')
+    if (slash <= 0 || slash === media.length - 1) continue
+    let q = 1
+    for (let index = 1; index < parts.length; index++) {
+      const parameter = (parts[index] as string).trim()
+      if (parameter.length < 2 || (parameter.charCodeAt(0) | 0x20) !== 0x71 /* q */ || parameter[1] !== '=') continue
+      const value = Number(parameter.slice(2))
+      // an invalid weight leaves the range as it is (RFC 9110 §12.4.2 allows 0 to 1, 3 decimals)
+      if (value >= 0 && value <= 1) q = value
+    }
+    ranges.push({ type: media.slice(0, slash), subtype: media.slice(slash + 1), q })
+  }
+  return ranges
+}
+
+/**
+ * The quality of `type/subtype` in `ranges`: that of the most specific matching range (RFC 9110
+ * §12.5.1), wildcards only when `wildcards` is set; 0 when nothing matches.
+ */
+function quality(ranges: readonly Range[], type: string, subtype: string, wildcards: boolean): number {
+  let best = -1
+  let specificity = -1
+  for (const range of ranges) {
+    let level: number
+    if (range.type === type && range.subtype === subtype) level = 2
+    else if (!wildcards) continue
+    else if (range.type === type && range.subtype === '*') level = 1
+    else if (range.type === '*' && range.subtype === '*') level = 0
+    else continue
+    if (level > specificity || (level === specificity && range.q > best)) {
+      specificity = level
+      best = range.q
+    }
+  }
+  return best < 0 ? 0 : best
+}
+
+/**
+ * Chooses the media type of a response among `produced` (a bit mask of `1 << Media.X`), per
+ * `accept` (`undefined`: no header, i.e. `application/json`): a {@link MediaKind}, plus
+ * {@link STREAMABLE} when a JSON type wins and an event stream is acceptable too.
+ */
+export function negotiate(accept: string | undefined, produced: number): number {
+  if (accept === undefined) return produced & (1 << Media.Json) ? Media.Json : Media.None
+  const ranges = parseRanges(accept)
+  if (ranges.length === 0) return produced & (1 << Media.Json) ? Media.Json : Media.None
+  let chosen: number = Media.None
+  let best = 0
+  for (let media: number = Media.GraphQLJson; media < NAMES.length; media++) {
+    if ((produced & (1 << media)) === 0) continue
+    const [type, subtype] = NAMES[media] as readonly [string, string]
+    const q = quality(ranges, type, subtype, media === Media.Json)
+    if (q > best) {
+      best = q
+      chosen = media
+    }
+  }
+  if (produced & (1 << Media.EventStream)) {
+    const q = quality(ranges, 'text', 'event-stream', false)
+    // strictly preferred, or the only acceptable type
+    if (q > best) return Media.EventStream
+    if (q > 0 && (chosen === Media.GraphQLJson || chosen === Media.Json)) chosen |= STREAMABLE
+  }
+  return chosen
+}
+
+const CACHE_MAX = 64
+
+/**
+ * {@link negotiate} for one route, memoised by header value: a server sees a handful of `accept`
+ * values, so a request costs a map lookup. Bounded, since clients choose the values: cleared when
+ * full.
+ */
+export class Negotiator {
+  readonly #produced: number
+  readonly #cache = new Map<string, number>()
+  /** The answer without `accept` header. */
+  readonly #absent: number
+
+  /** `produced`: a bit mask of `1 << Media.X`. */
+  constructor(produced: number) {
+    this.#produced = produced
+    this.#absent = negotiate(undefined, produced)
+  }
+
+  /** The {@link negotiate} answer: a {@link MediaKind}, possibly with {@link STREAMABLE}. */
+  choose(accept: string | undefined): number {
+    if (accept === undefined) return this.#absent
+    let media = this.#cache.get(accept)
+    if (media === undefined) {
+      media = negotiate(accept, this.#produced)
+      if (this.#cache.size === CACHE_MAX) this.#cache.clear()
+      this.#cache.set(accept, media)
+    }
+    return media
+  }
+}

package/src/transport/graphiql.ts

@@ -0,0 +1,106 @@
+/**
+ * The GraphiQL page (RFC 0005 §8.3, §8.9): served on `GET path` with `accept: text/html` when the
+ * `graphiql` option is on (default: `NODE_ENV === 'development'`). React and GraphiQL load from a
+ * pinned CDN with Subresource Integrity; the inline script is fixed at boot and allowed by hash in
+ * the page's own `content-security-policy`, which overrides the strict API default of RFC 0001 on
+ * this response only.
+ */
+import { createHash } from 'node:crypto'
+
+/** jsDelivr. */
+export const GRAPHIQL_CDN = 'https://cdn.jsdelivr.net'
+
+/** A pinned CDN asset. */
+export interface GraphiQLAsset {
+  readonly url: string
+  /** Subresource Integrity of the pinned file. */
+  readonly integrity: string
+  readonly kind: 'script' | 'style'
+}
+
+/**
+ * The assets of the page: GraphiQL 3 (the last major with a UMD build) on React 18. Bumped by hand,
+ * with their SRI hashes (`sha384` of the files on the CDN).
+ */
+export const GRAPHIQL_ASSETS: readonly GraphiQLAsset[] = Object.freeze([
+  {
+    url: `${GRAPHIQL_CDN}/npm/graphiql@3.9.0/graphiql.min.css`,
+    integrity: 'sha384-QMux00XgRtwRLSYIY3kw2rj1ovk5AuuliAchk+HSQbqdbGFnz9GYuqIlOqxhwCE2',
+    kind: 'style',
+  },
+  {
+    url: `${GRAPHIQL_CDN}/npm/react@18.3.1/umd/react.production.min.js`,
+    integrity: 'sha384-DGyLxAyjq0f9SPpVevD6IgztCFlnMF6oW/XQGmfe+IsZ8TqEiDrcHkMLKI6fiB/Z',
+    kind: 'script',
+  },
+  {
+    url: `${GRAPHIQL_CDN}/npm/react-dom@18.3.1/umd/react-dom.production.min.js`,
+    integrity: 'sha384-gTGxhz21lVGYNMcdJOyq01Edg0jhn/c22nsx0kyqP0TxaV5WVdsSH1fSDUf5YJj1',
+    kind: 'script',
+  },
+  {
+    url: `${GRAPHIQL_CDN}/npm/graphiql@3.9.0/graphiql.min.js`,
+    integrity: 'sha384-8NGfVj4CVlqHajlZj+bPJT4thxPMHMJYn7DWK2CvtopLd02E7qsPHazniBYvVjOO',
+    kind: 'script',
+  },
+])
+
+/** The rendered page. */
+export interface GraphiQLPage {
+  readonly html: string
+  readonly csp: string
+}
+
+/** `<`, `>` and `&` escaped: JSON safe inside a `<script>` element. */
+function scriptJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026')
+}
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+/** The GraphiQL page of the endpoint `endpoint` (an absolute path, prefix included) and its CSP. */
+export function renderGraphiQL(endpoint: string): GraphiQLPage {
+  const tags = GRAPHIQL_ASSETS.map(asset =>
+    asset.kind === 'style'
+      ? `<link rel="stylesheet" href="${escapeHtml(asset.url)}" integrity="${asset.integrity}" crossorigin="anonymous">`
+      : `<script src="${escapeHtml(asset.url)}" integrity="${asset.integrity}" crossorigin="anonymous"></script>`,
+  )
+  const inline = [
+    `const fetcher = GraphiQL.createFetcher({ url: ${scriptJson(endpoint)} })`,
+    `ReactDOM.createRoot(document.getElementById('graphiql')).render(React.createElement(GraphiQL, { fetcher }))`,
+  ].join('\n')
+  const hash = `'sha256-${createHash('sha256').update(inline).digest('base64')}'`
+  const html = [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<title>GraphiQL</title>',
+    '<style>body { margin: 0; } #graphiql { height: 100dvh; }</style>',
+    ...tags.filter(tag => tag.startsWith('<link')),
+    '</head>',
+    '<body>',
+    '<div id="graphiql">Loading GraphiQL…</div>',
+    ...tags.filter(tag => tag.startsWith('<script')),
+    `<script>${inline}</script>`,
+    '</body>',
+    '</html>',
+    '',
+  ].join('\n')
+  const csp = [
+    "default-src 'none'",
+    `script-src ${GRAPHIQL_CDN} ${hash}`,
+    // GraphiQL and CodeMirror set inline styles
+    `style-src 'unsafe-inline' ${GRAPHIQL_CDN}`,
+    `font-src data: ${GRAPHIQL_CDN}`,
+    "img-src 'self' data:",
+    "connect-src 'self'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'self'",
+  ].join('; ')
+  return { html, csp }
+}

package/src/transport/http.ts

@@ -0,0 +1,373 @@
+/**
+ * GraphQL over HTTP (RFC 0005 §8.3, GraphQL-over-HTTP specification draft), the handlers of the two
+ * plugin routes of the endpoint (`GET` and `POST` on `path`).
+ *
+ * - `POST`: `application/json` bodies only (415 otherwise: no form or text body, so cross-site
+ *   requests are always preflighted), read by the handler so that every malformed request gets a
+ *   GraphQL-shaped error (malformed JSON, missing query, batching: 400; body limit: 413).
+ * - `GET`: queries only (405 with `allow: POST` otherwise), when `http.get` is on; GraphiQL with
+ *   `accept: text/html` when enabled.
+ * - The response is `application/graphql-response+json` when the client lists it (200 with data,
+ *   400 for request errors), otherwise `application/json` (200 for every well-formed request); no
+ *   `accept` header is `application/json`; nothing acceptable is 406. `accept: text/event-stream`
+ *   selects GraphQL over SSE for any operation when it is preferred to the JSON types (or the only
+ *   one listed); listed at the same quality as a JSON type, only subscriptions are streamed.
+ *
+ * Hot path (a cached query whose resolvers are synchronous): a memoised negotiation (a map lookup),
+ * the query string read without `URLSearchParams` or the body read and parsed once, one options
+ * object and one deferred abort per request, the executor's synchronous result, and a single
+ * `JSON.stringify` by the serialiser. Every answer stays on the fast lane of `@znight/http` (no
+ * promise while the route is synchronous, headers from a template) unless the application adds
+ * CORS, guards, `http:request` listeners or wrappers: a `GET` answered as `application/json` with
+ * status 200 returns the plain result; the other answers are an `HttpResponse` with a plain JSON
+ * body, at most a `content-type` header and an explicit status (a `POST` route answers 201 by
+ * default), which the fast lane serves too.
+ */
+import type { HttpContext, SseOptions } from '@znight/http'
+import type { FormattedExecutionResult } from 'graphql'
+import type { ExecuteOptions, GraphQLExecutor, GraphQLRequest, GraphQLResponse } from '../execution.ts'
+
+import { HttpResponse, isHttpException, parseMediaType } from '@znight/http'
+
+import { GraphQLErrorCode } from '../errors.ts'
+import { SUBSCRIBE } from '../execution.ts'
+import { DeferredAbort } from './abort.ts'
+import { MEDIA, Media, type MediaKind, Negotiator, STREAMABLE } from './accept.ts'
+import { renderGraphiQL } from './graphiql.ts'
+import { ResultEvents } from './sse.ts'
+
+/** What the transport is built from (resolved plugin options). */
+export interface HttpTransportOptions {
+  /** The executor of the plugin, built at bootstrap (after the routes may have been collected). */
+  readonly executor: () => GraphQLExecutor
+  /** Absolute path of the endpoint, prefix included (GraphiQL's fetcher). */
+  readonly endpoint: string
+  /** Queries over `GET`. */
+  readonly get: boolean
+  readonly graphiql: boolean
+  /** `HttpResponse.sse()` options of GraphQL over SSE; `false`: no event streams. */
+  readonly sse: SseOptions | false
+}
+
+const JSON_TYPE = 'application/json; charset=utf-8'
+const GRAPHQL_JSON_TYPE = 'application/graphql-response+json; charset=utf-8'
+
+/** Response options of `application/graphql-response+json` replies, by status. */
+const GRAPHQL_JSON_200 = Object.freeze({ status: 200, headers: Object.freeze({ 'content-type': GRAPHQL_JSON_TYPE }) })
+const GRAPHQL_JSON_400 = Object.freeze({ status: 400, headers: Object.freeze({ 'content-type': GRAPHQL_JSON_TYPE }) })
+/** `application/json` is what the serialiser gives an object body: only the status is set. */
+const JSON_200 = Object.freeze({ status: 200 })
+
+const UTF8 = new TextDecoder('utf-8', { fatal: true })
+
+/** A request error before execution: `{ errors: [{ message, extensions: { code } }] }`. */
+function errorBody(message: string, code: string = GraphQLErrorCode.BadRequest): FormattedExecutionResult {
+  return { errors: [{ message, extensions: { code } }] }
+}
+
+/** A reply of `status` carrying a GraphQL error body in the negotiated JSON type (`application/json` before negotiation). */
+function errorReply(
+  media: MediaKind,
+  status: number,
+  body: FormattedExecutionResult,
+  headers?: Readonly<Record<string, string>>,
+): HttpResponse<FormattedExecutionResult> {
+  const type = media === Media.GraphQLJson ? GRAPHQL_JSON_TYPE : JSON_TYPE
+  return new HttpResponse(body, { status, headers: { ...headers, 'content-type': type } })
+}
+
+const NOT_ACCEPTABLE = errorReply(
+  Media.Json,
+  406,
+  errorBody(
+    'None of the accepted media types can be produced: accept application/graphql-response+json, application/json or text/event-stream',
+  ),
+)
+const GET_NOT_ALLOWED = errorReply(
+  Media.Json,
+  405,
+  errorBody('GraphQL operations are sent with POST on this endpoint'),
+  Object.freeze({ allow: 'POST' }),
+)
+
+/** `content-type` values of JSON bodies seen most often, compared before parsing. */
+function isJsonRequest(contentType: string | undefined): boolean {
+  if (contentType === 'application/json' || contentType === 'application/json; charset=utf-8') return true
+  // parsed once per distinct value (memoised by @znight/http)
+  const media = parseMediaType(contentType)
+  if (media === undefined || media.type !== 'application/json') return false
+  return media.charset === undefined || media.charset === 'utf-8' || media.charset === 'utf8'
+}
+
+/** Why the parameters of a request are invalid, `undefined` when they are valid. */
+function invalidParams(params: Readonly<Record<string, unknown>>): string | undefined {
+  const query = params['query']
+  if (typeof query !== 'string') {
+    return query === undefined || query === null
+      ? 'Missing query: send { query, variables?, operationName?, extensions? }'
+      : 'The query must be a string'
+  }
+  const operationName = params['operationName']
+  if (operationName !== undefined && operationName !== null && typeof operationName !== 'string') {
+    return 'operationName must be a string'
+  }
+  if (!isMapOrNull(params['variables'])) return 'variables must be an object'
+  if (!isMapOrNull(params['extensions'])) return 'extensions must be an object'
+  return undefined
+}
+
+/** The parameters of a GraphQL `GET` request. */
+const GET_PARAMS = ['query', 'operationName', 'variables', 'extensions'] as const
+
+type GetParams = Partial<Record<(typeof GET_PARAMS)[number], string | string[]>>
+
+/** A query string component decoded like `URLSearchParams` (`+` is a space); `undefined` when malformed. */
+function decodeComponent(text: string): string | undefined {
+  if (text.indexOf('%') === -1 && text.indexOf('+') === -1) return text
+  try {
+    return decodeURIComponent(text.replaceAll('+', ' '))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The GraphQL parameters of a request target, read directly: `ctx.query` builds a record of every
+ * parameter through `URLSearchParams` (about 0.35 µs of a `GET` on Node.js, 0.15 µs on Bun, see
+ * `test/bench/http.bench.ts`). A repeated parameter
+ * becomes an array, like `ctx.query`. `undefined` when a component is malformed percent-encoding:
+ * the caller falls back to `ctx.query` (which keeps such sequences as they are).
+ */
+function readGetParams(url: string): GetParams | undefined {
+  const params: GetParams = {}
+  const mark = url.indexOf('?')
+  if (mark === -1) return params
+  const length = url.length
+  let start = mark + 1
+  while (start < length) {
+    let end = url.indexOf('&', start)
+    if (end === -1) end = length
+    if (end > start) {
+      let equals = url.indexOf('=', start)
+      if (equals === -1 || equals > end) equals = end
+      const name = decodeComponent(url.slice(start, equals))
+      if (name === undefined) return undefined
+      if (name === 'query' || name === 'operationName' || name === 'variables' || name === 'extensions') {
+        const value = equals === end ? '' : decodeComponent(url.slice(equals + 1, end))
+        if (value === undefined) return undefined
+        const existing = params[name]
+        if (existing === undefined) params[name] = value
+        else params[name] = typeof existing === 'string' ? [existing, value] : [...existing, value]
+      }
+    }
+    start = end + 1
+  }
+  return params
+}
+
+function isMapOrNull(value: unknown): boolean {
+  return value === undefined || value === null || (typeof value === 'object' && !Array.isArray(value))
+}
+
+function isPromise<T>(value: T | Promise<T>): value is Promise<T> {
+  return typeof (value as { then?: unknown } | null)?.then === 'function'
+}
+
+/** The handlers of the GraphQL endpoint. */
+export class HttpTransport {
+  readonly #resolveExecutor: () => GraphQLExecutor
+  #executor: GraphQLExecutor | undefined
+  readonly #getQueries: boolean
+  readonly #sse: SseOptions | false
+  readonly #post: Negotiator
+  readonly #get: Negotiator
+  /** The GraphiQL page, `undefined` when disabled. */
+  readonly #graphiql: HttpResponse<Uint8Array> | undefined
+
+  constructor(options: HttpTransportOptions) {
+    this.#resolveExecutor = options.executor
+    this.#getQueries = options.get
+    this.#sse = options.sse
+    const json = (1 << Media.GraphQLJson) | (1 << Media.Json) | (options.sse === false ? 0 : 1 << Media.EventStream)
+    this.#post = new Negotiator(json)
+    this.#get = new Negotiator(options.graphiql ? json | (1 << Media.Html) : json)
+    if (options.graphiql) {
+      const page = renderGraphiQL(options.endpoint)
+      // encoded once: the same immutable response serves every request
+      this.#graphiql = new HttpResponse(new TextEncoder().encode(page.html), {
+        status: 200,
+        headers: {
+          'content-type': 'text/html; charset=utf-8',
+          'content-security-policy': page.csp,
+          'cache-control': 'no-store',
+        },
+      })
+    }
+  }
+
+  /** `POST path`. */
+  readonly post = (ctx: HttpContext): unknown => {
+    const headers = ctx.headers
+    const negotiated = this.#post.choose(headers['accept'])
+    const media = (negotiated & MEDIA) as MediaKind
+    if (media === Media.None) return NOT_ACCEPTABLE
+    if (!isJsonRequest(headers['content-type'])) {
+      return errorReply(
+        media,
+        415,
+        errorBody('Send GraphQL requests as application/json (content-type: application/json)'),
+      )
+    }
+    const encoding = headers['content-encoding']
+    if (encoding !== undefined && encoding.trim().toLowerCase() !== 'identity' && encoding.trim() !== '') {
+      return errorReply(media, 415, errorBody(`Unsupported content encoding "${encoding}"`))
+    }
+    return ctx.rawBody().then(
+      bytes => this.#posted(ctx, bytes, media, negotiated >= STREAMABLE),
+      (error: unknown) => transportError(error, media),
+    )
+  }
+
+  /** `GET path`. */
+  readonly get = (ctx: HttpContext): unknown => {
+    const media = (this.#get.choose(ctx.headers['accept']) & MEDIA) as MediaKind
+    if (media === Media.Html) return this.#graphiql
+    if (media === Media.None) return NOT_ACCEPTABLE
+    if (!this.#getQueries) return GET_NOT_ALLOWED
+    const params = readGetParams(ctx.url) ?? ctx.query
+    const request: Record<string, unknown> = {}
+    for (const name of GET_PARAMS) {
+      const value = params[name]
+      if (value === undefined) continue
+      if (typeof value !== 'string') return errorReply(media, 400, errorBody(`Repeated ${name} parameter`))
+      if (name === 'variables' || name === 'extensions') {
+        try {
+          request[name] = JSON.parse(value)
+        } catch {
+          return errorReply(media, 400, errorBody(`The ${name} parameter must be JSON`))
+        }
+      } else {
+        request[name] = value
+      }
+    }
+    const invalid = invalidParams(request)
+    if (invalid !== undefined) return errorReply(media, 400, errorBody(invalid))
+    if (media === Media.EventStream) return this.#stream(ctx, request as unknown as GraphQLRequest, true)
+    // GET carries queries only: no subscription to stream
+    return this.#execute(ctx, request as unknown as GraphQLRequest, media, true, false)
+  }
+
+  /** A `POST` body read: parsed, checked, executed or streamed. */
+  #posted(ctx: HttpContext, bytes: Uint8Array, media: MediaKind, streamable: boolean): unknown {
+    if (bytes.byteLength === 0) {
+      return errorReply(media, 400, errorBody('Missing request body: send { query, variables?, operationName? }'))
+    }
+    let body: unknown
+    try {
+      body = JSON.parse(UTF8.decode(bytes))
+    } catch {
+      return errorReply(media, 400, errorBody('Malformed JSON body'))
+    }
+    if (body === null || typeof body !== 'object') {
+      return errorReply(media, 400, errorBody('The body must be a JSON object: { query, variables?, operationName? }'))
+    }
+    if (Array.isArray(body)) {
+      return errorReply(media, 400, errorBody('Operation batching is not supported: send one operation per request'))
+    }
+    const invalid = invalidParams(body as Record<string, unknown>)
+    if (invalid !== undefined) return errorReply(media, 400, errorBody(invalid))
+    if (media === Media.EventStream) return this.#stream(ctx, body as GraphQLRequest, false)
+    return this.#execute(ctx, body as GraphQLRequest, media, false, streamable)
+  }
+
+  /**
+   * Executes a query or a mutation; synchronous while the execution is. A subscription is streamed
+   * when the client accepts an event stream (`streamable`), a 400 otherwise.
+   */
+  #execute(ctx: HttpContext, request: GraphQLRequest, media: MediaKind, get: boolean, streamable: boolean): unknown {
+    const executor = this.#executor ?? this.#bind()
+    const abort = new DeferredAbort()
+    const options: ExecuteOptions = {
+      transport: 'http',
+      http: ctx,
+      abortSignal: abort.asSignal(),
+      queriesOnly: get,
+      streamSubscriptions: streamable,
+    }
+    const response = executor.execute(request, options)
+    if (response === SUBSCRIBE) return this.#stream(ctx, request, get)
+    if (!isPromise(response)) return reply(response, media, get)
+    // asynchronous resolvers: a client leaving now aborts the execution
+    abort.follow(() => ctx.signal)
+    return response.then(
+      settled => reply(settled, media, get),
+      (error: unknown) => {
+        if (!abort.aborted || error !== abort.reason) throw error
+        // nobody reads it: the client is gone (or the server stops)
+        return errorReply(media, 503, errorBody('The request was aborted', GraphQLErrorCode.ServiceUnavailable))
+      },
+    )
+  }
+
+  /** GraphQL over SSE: any operation, its results as `next` events. */
+  #stream(ctx: HttpContext, request: GraphQLRequest, get: boolean): Promise<unknown> {
+    const executor = this.#executor ?? this.#bind()
+    const signal = ctx.signal
+    const options: ExecuteOptions = { transport: 'sse', http: ctx, signal, queriesOnly: get }
+    return executor.subscribe(request, options).then(
+      outcome => {
+        if ('status' in outcome) {
+          return errorReply(Media.Json, outcome.status, outcome.result, outcome.headers)
+        }
+        // the SSE options were checked at boot (see sseOptions)
+        return HttpResponse.sse(new ResultEvents(outcome, signal), this.#sse as SseOptions)
+      },
+      (error: unknown) => {
+        if (!signal.aborted || error !== signal.reason) throw error
+        return errorReply(Media.Json, 503, errorBody('The request was aborted', GraphQLErrorCode.ServiceUnavailable))
+      },
+    )
+  }
+
+  #bind(): GraphQLExecutor {
+    this.#executor = this.#resolveExecutor()
+    return this.#executor
+  }
+}
+
+/**
+ * The HTTP reply of an executor response. `application/json` answers 200 to every well-formed
+ * request (request errors included); `application/graphql-response+json` keeps the status.
+ */
+function reply(response: GraphQLResponse, media: MediaKind, get: boolean): unknown {
+  const status = response.status
+  const result = response.result
+  if (media === Media.Json) {
+    if (status === 200 || status === 400) {
+      // a plain object on a GET route: 200 application/json (a POST route would answer 201)
+      return get ? result : new HttpResponse(result, JSON_200)
+    }
+    return errorReply(media, status, result, response.headers)
+  }
+  if (response.headers === undefined) {
+    if (status === 200) return new HttpResponse(result, GRAPHQL_JSON_200)
+    if (status === 400) return new HttpResponse(result, GRAPHQL_JSON_400)
+  }
+  return errorReply(media, status, result, response.headers)
+}
+
+/** A failure reading the body (413 past the body limit, 400 for an aborted body) with a GraphQL error body. */
+function transportError(error: unknown, media: MediaKind): HttpResponse<FormattedExecutionResult> {
+  if (!isHttpException(error)) throw error
+  return errorReply(media, error.status, errorBody(error.message))
+}
+
+/** Checks the SSE options once (`HttpResponse.sse()` validates them): `undefined` when they are valid. */
+export function checkSseOptions(options: SseOptions): string | undefined {
+  try {
+    HttpResponse.sse([], options)
+    return undefined
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+}

package/src/transport/sse.ts

@@ -0,0 +1,45 @@
+/**
+ * GraphQL over SSE, distinct connections mode (RFC 0005 §5.6, §8.3, §8.11): the results of an
+ * operation as `next` events, then a `complete` event. Everything else (headers, heartbeats,
+ * backpressure, client abort, graceful close) is RFC 0006's `HttpResponse.sse()`.
+ */
+import type { SseEvent } from '@znight/http'
+import type { GraphQLResultStream } from '../execution.ts'
+
+/** The last event of a stream that ended normally. */
+const COMPLETE: SseEvent<string> = Object.freeze({ event: 'complete', data: '' })
+const DONE: IteratorResult<SseEvent> = Object.freeze({ done: true, value: undefined })
+
+/**
+ * The event source of an operation: one `next` event per result, then `complete` when the
+ * operation ended by itself. A stream ended by `ctx.signal` (client gone, shutdown, `maxDuration`)
+ * gets no `complete`: GraphQL-over-SSE clients then treat it as a lost connection and retry.
+ */
+export class ResultEvents implements AsyncIterableIterator<SseEvent> {
+  readonly #results: GraphQLResultStream
+  readonly #signal: AbortSignal
+  #done = false
+
+  constructor(results: GraphQLResultStream, signal: AbortSignal) {
+    this.#results = results
+    this.#signal = signal
+  }
+
+  async next(): Promise<IteratorResult<SseEvent>> {
+    if (this.#done) return DONE
+    const step = await this.#results.next()
+    if (step.done !== true) return { done: false, value: { event: 'next', data: step.value } }
+    this.#done = true
+    return this.#signal.aborted ? DONE : { done: false, value: COMPLETE }
+  }
+
+  async return(): Promise<IteratorResult<SseEvent>> {
+    this.#done = true
+    await this.#results.return()
+    return DONE
+  }
+
+  [Symbol.asyncIterator](): AsyncIterableIterator<SseEvent> {
+    return this
+  }
+}