@znight/graphql 0.2.2 → 0.3.0

package/src/index.ts

@@ -7,6 +7,13 @@
 
 export type { StandardSchemaV1 } from '@znight/http'
 export type { Float, ID, Int, JSONValue, ResolverOptions } from './decorators.ts'
+export type {
+  GraphQLDriver,
+  GraphQLDriverContext,
+  GraphQLDriverRoute,
+  GraphQLDriverRoutesContext,
+} from './driver.ts'
+export type { EngineExecuteOptions, GraphQLEngine, GraphQLEngineSettings } from './engine.ts'
 export type { GraphQLRequest, GraphQLResultStream } from './execution.ts'
 export type {
   AnyPubSub,

package/src/limits.ts

@@ -5,7 +5,7 @@
  * written, and, when the document spreads fragments, as each operation executes them (a fragment
  * spread several times counts each time). `maxTokens` is enforced by `parse()` itself.
  */
-import type { DirectiveNode, DocumentNode, FragmentDefinitionNode, SelectionSetNode } from 'graphql'
+import type { DirectiveNode, DocumentNode, FragmentDefinitionNode, SelectionSetNode, ValidationRule } from 'graphql'
 
 import { GraphQLError, Kind } from 'graphql'
 
@@ -76,6 +76,27 @@ export function checkLimits(document: DocumentNode, limits: DocumentLimits): Gra
   return errors
 }
 
+/**
+ * The limits as a graphql-js validation rule (`GraphQLEngine.rules`, RFC 0009), for GraphQL servers
+ * that parse and validate documents themselves: the same check as {@link checkLimits}, run once on
+ * the document node. `undefined` when every limit is disabled.
+ */
+export function limitsRule(limits: DocumentLimits): ValidationRule | undefined {
+  if (limits.maxDepth === undefined && limits.maxAliases === undefined && limits.maxDirectives === undefined) {
+    return undefined
+  }
+  const rule: ValidationRule = context => ({
+    Document(node) {
+      const errors = checkLimits(node, limits)
+      if (errors !== undefined) for (const error of errors) context.reportError(error)
+      // the whole document is checked at once: nothing to visit below it
+      return false
+    },
+  })
+  Object.defineProperty(rule, 'name', { value: 'ZnightDocumentLimitsRule' })
+  return rule
+}
+
 interface Counter {
   aliases: number
   directives: number

package/src/options.ts

@@ -2,6 +2,7 @@
  * Options of `GraphQLPlugin` (RFC 0005 §5.11): their types, defaults and validation (ZNIGHT066).
  */
 import type { ByteSize, GuardRef, RouteMetaEntry } from '@znight/http'
+import type { GraphQLDriver } from './driver.ts'
 import type { SubscribeOptions } from './pubsub.ts'
 import type {
   GraphQLErrorMapper,
@@ -70,9 +71,12 @@ export interface GraphQLSubscriptionOptions {
   readonly maxActive?: number
   /** Events buffered per subscriber by the default `MemoryPubSub`. Default 100. */
   readonly bufferSize?: number
-  /** SSE heartbeat (ms), `false` for none. Default: the `HttpPlugin` `sse` option. */
+  /**
+   * SSE heartbeat (ms), `false` for none. Default: the `HttpPlugin` `sse` option. Built-in transport
+   * only: with a `driver`, its own keep-alive options apply (ZNIGHT066).
+   */
   readonly heartbeat?: number | false
-  /** SSE maximum duration (ms). Default: none. */
+  /** SSE maximum duration (ms). Default: none. Built-in transport only (ZNIGHT066 with a `driver`). */
   readonly maxDuration?: number
 }
 
@@ -95,12 +99,15 @@ export interface GraphQLPluginOptions {
   readonly exposeErrors?: boolean
   /** Introspection; off, suggestions are hidden too. Default `NODE_ENV !== 'production'`. */
   readonly introspection?: boolean
-  /** GraphiQL on `GET path` with `accept: text/html`. Default `NODE_ENV === 'development'`. */
+  /**
+   * GraphiQL on `GET path` with `accept: text/html`; with a `driver`, the driver's IDE. Default
+   * `NODE_ENV === 'development'`.
+   */
   readonly graphiql?: boolean
   readonly limits?: GraphQLLimits
   /** Distinct documents kept parsed and validated (LRU); 0 disables the cache. Default 1 000. */
   readonly documentCache?: number
-  /** `false` disables subscriptions over SSE. */
+  /** `false` disables subscriptions over SSE (with a `driver`, subscriptions altogether). */
   readonly subscriptions?: GraphQLSubscriptionOptions | false
   /** The `PubSub` provided to the container. Default: a `MemoryPubSub` (closed with the application). */
   readonly pubsub?: AnyPubSub
@@ -109,6 +116,11 @@ export interface GraphQLPluginOptions {
    * `'error'` (default) fails the boot, `'warn'` logs.
    */
   readonly enforcement?: 'error' | 'warn'
+  /**
+   * The GraphQL server serving the schema (RFC 0009): a driver of a subpath (`yogaDriver()`) or a
+   * third party's. Default: the built-in GraphQL-over-HTTP and SSE transport, the fastest.
+   */
+  readonly driver?: GraphQLDriver
 }
 
 /** Options with their defaults, validated. */
@@ -139,6 +151,8 @@ export interface ResolvedGraphQLOptions {
   readonly bufferSize: number
   readonly pubsub: AnyPubSub | undefined
   readonly enforcement: 'error' | 'warn'
+  /** `undefined`: the built-in transport. */
+  readonly driver: GraphQLDriver | undefined
 }
 
 const KEYS: ReadonlySet<string> = new Set([
@@ -155,6 +169,7 @@ const KEYS: ReadonlySet<string> = new Set([
   'subscriptions',
   'pubsub',
   'enforcement',
+  'driver',
 ])
 const PATH = /^\/[A-Za-z0-9\-._~!$&'()*+,;=:@/]*$/
 const LIMIT_DEFAULTS = { maxTokens: 2000, maxDepth: 12, maxAliases: 30, maxDirectives: 50 } as const
@@ -307,6 +322,19 @@ export function resolveGraphQLOptions(
   if (enforcement !== 'error' && enforcement !== 'warn')
     throw invalidOption('enforcement', "'error' or 'warn'", enforcement)
 
+  const driver = resolveDriver(options['driver'])
+  if (driver !== undefined && subscriptions !== false) {
+    for (const key of ['heartbeat', 'maxDuration'] as const) {
+      if (subscriptions[key] !== undefined) {
+        throw new ZnightError(
+          ErrorCode.InvalidGraphQLSetup,
+          `GraphQLPlugin: subscriptions.${key} configures the built-in SSE transport, not the ${driver.name} driver`,
+          { hints: [`Remove subscriptions.${key}: the ${driver.name} driver's own keep-alive options apply`] },
+        )
+      }
+    }
+  }
+
   return {
     path,
     http,
@@ -327,5 +355,26 @@ export function resolveGraphQLOptions(
     bufferSize,
     pubsub: pubsub as AnyPubSub | undefined,
     enforcement,
+    driver,
+  }
+}
+
+/** The `driver` option: an object with a `name` (not `builtin`) and `start()`, `routes()` and `stop()` functions when present. */
+function resolveDriver(value: unknown): GraphQLDriver | undefined {
+  if (value === undefined) return undefined
+  const expected = 'a GraphQL driver ({ name, start(), routes?(), stop?() }, from yogaDriver() for instance)'
+  if (value === null || typeof value !== 'object') throw invalidOption('driver', expected, value)
+  const driver = value as Record<string, unknown>
+  const name = driver['name']
+  if (typeof name !== 'string' || name === '') throw invalidOption('driver', `${expected} with a name`, value)
+  if (name === 'builtin') {
+    throw invalidOption('driver.name', "a name other than 'builtin' (reserved for the built-in transport)", name)
+  }
+  if (typeof driver['start'] !== 'function') throw invalidOption('driver', `${expected} with a start() method`, value)
+  for (const method of ['routes', 'stop']) {
+    if (driver[method] !== undefined && typeof driver[method] !== 'function') {
+      throw invalidOption(`driver.${method}`, 'a function', driver[method])
+    }
   }
+  return value as GraphQLDriver
 }

package/src/plugin.ts

@@ -1,7 +1,8 @@
 /**
  * `GraphQLPlugin` (RFC 0005 §5.11, §8.2): builds the schema from `metadata.extensions.graphql`,
  * provides `GraphQLContext`, `PubSub` and itself to the container, executes operations
- * (`execute()`, `subscribe()`) and contributes the GraphQL endpoint to `HttpPlugin`.
+ * (`execute()`, `subscribe()`, the `engine` of drivers, RFC 0009) and contributes the routes of its
+ * driver (the built-in GraphQL-over-HTTP endpoint by default) to `HttpPlugin`.
  */
 import type {
   Container,
@@ -15,9 +16,11 @@ import type {
   Token,
   ZnightMetadata,
 } from '@znight/core'
-import type { PluginHttpRoutes, PluginHttpRoutesContext, PluginRoute, SseOptions } from '@znight/http'
+import type { HttpPlugin, PluginHttpRoutes, PluginHttpRoutesContext, PluginRoute, SseOptions } from '@znight/http'
 import type { FormattedExecutionResult, GraphQLSchema } from 'graphql'
 import type { CheckedField } from './decisions.ts'
+import type { GraphQLDriver, GraphQLDriverRoute } from './driver.ts'
+import type { GraphQLEngine } from './engine.ts'
 import type { ExecuteOptions, GraphQLRequest, GraphQLResultStream } from './execution.ts'
 import type { Resolvable } from './format.ts'
 import type { GraphQLInputTypeDefinition, GraphQLMetadata, GraphQLResolverBinding } from './metadata.ts'
@@ -28,6 +31,7 @@ import { displayName, ErrorCode, resolveOptions, ZnightError } from '@znight/cor
 import { printSchema } from 'graphql'
 
 import { checkFieldDecisions } from './decisions.ts'
+import { Engine } from './engine.ts'
 import { GraphQLExecutor, singleResult } from './execution.ts'
 import { ErrorFormatter } from './format.ts'
 import { LoaderFactory } from './loaders.ts'
@@ -38,7 +42,8 @@ import { PubSub } from './pubsub.ts'
 import { checkResultTypes, declaredTypes, ResultMappers } from './results.ts'
 import { buildGraphQLSchema, checkGraphQLSection, graphqlSection } from './schema.ts'
 import { GraphQLTokens } from './tokens.ts'
-import { checkSseOptions, HttpTransport } from './transport/http.ts'
+import { BUILTIN_DRIVER, BuiltinDriver } from './transport/builtin.ts'
+import { checkSseOptions } from './transport/http.ts'
 
 /** Options of {@link GraphQLPlugin.execute} and {@link GraphQLPlugin.subscribe}. */
 export interface DirectExecuteOptions {
@@ -53,6 +58,7 @@ interface Runtime {
   readonly schema: GraphQLSchema
   readonly section: GraphQLMetadata
   readonly executor: GraphQLExecutor
+  readonly engine: GraphQLEngine
 }
 
 let readExecutor: (plugin: GraphQLPlugin) => GraphQLExecutor
@@ -101,6 +107,10 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
   #runtime: Runtime | undefined
   #stop: AbortController | undefined
   #endpoint: string | undefined
+  /** The driver serving the schema: the `driver` option, or the built-in transport. */
+  #driver: GraphQLDriver | undefined
+  /** The driver was started (`onBootstrap`): `onStop` stops it. */
+  #started = false
   #active = false
 
   private constructor(options: PluginOptions<GraphQLPluginOptions>) {
@@ -164,6 +174,8 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
     this.#runtime = undefined
     this.#ownPubSub = undefined
     this.#endpoint = undefined
+    this.#driver = undefined
+    this.#started = false
     this.#container = ctx.container
     this.#metadata = ctx.metadata
     this.#logger = ctx.logger
@@ -183,42 +195,58 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
   }
 
   /**
-   * The `PluginHttpRoutes` contract of `@znight/http`: the GraphQL endpoint (`GET` and `POST` on
-   * `path`). `[]` with `http: false`.
+   * The `PluginHttpRoutes` contract of `@znight/http`: the routes of the driver, with the `http`
+   * option's meta and guards, and its body limit on the routes that are not `GET`. For the built-in
+   * transport, the GraphQL endpoint (`GET` and `POST` on `path`). `[]` with `http: false`.
    */
   httpRoutes(context: PluginHttpRoutesContext): readonly PluginRoute[] {
     this.#container ??= context.container
     const options = this.#resolve()
     const http = options.http
     if (http === false) return []
+    const driver = this.#driverOf(options)
+    // a server-mounted driver attaches itself to the adapter in start()
+    if (driver.routes === undefined) return []
     const endpoint = endpointPath(context.prefix, options.path)
-    const transport = new HttpTransport({
-      // called on the first request: the routes are collected before or after this plugin's onBootstrap
-      executor: () => this.#ready().executor,
-      endpoint,
-      get: http.get,
-      graphiql: options.graphiql,
-      sse: sseOptions(options),
-    })
+    const routes = driver.routes({ path: options.path, endpoint })
+    if (!Array.isArray(routes))
+      throw invalidOption(`routes() of the ${driver.name} driver`, 'an array of routes', routes)
     this.#endpoint = endpoint
-    const common = {
-      name: 'handle',
-      path: options.path,
-      ...(http.meta.length === 0 ? {} : { meta: http.meta }),
-      ...(http.guards.length === 0 ? {} : { guards: http.guards }),
-    }
-    const routes: PluginRoute[] = [{ ...common, method: 'POST', handler: transport.post, bodyLimit: http.bodyLimit }]
-    // GET serves queries (`http.get`) and GraphiQL; without either, the router answers 405
-    if (http.get || options.graphiql) routes.unshift({ ...common, method: 'GET', handler: transport.get })
-    return routes
+    return routes.map(route => mount(route, http, driver))
   }
 
-  onBootstrap(ctx: PluginContext): void {
+  onBootstrap(ctx: PluginContext): void | Promise<void> {
     this.#container = ctx.container
     const options = this.#resolve()
     if (typeof this.#options === 'function') this.#checkHttp(ctx, options)
-    this.#checkSse(options)
-    this.#runtime = this.#build(ctx, options)
+    if (options.driver === undefined) this.#checkSse(options)
+    const runtime = this.#build(ctx, options)
+    this.#runtime = runtime
+    const driver = this.#driverOf(options)
+    // the built-in transport reads the executor on its first request: nothing to start
+    if (options.driver === undefined) return
+    let started: void | Promise<void>
+    try {
+      started = driver.start(runtime.engine, {
+        logger: ctx.logger,
+        container: ctx.container,
+        http: ctx.getPlugin<HttpPlugin>('http'),
+      })
+    } catch (error) {
+      throw driverFailed(driver, error)
+    }
+    if (!isPromise(started)) {
+      this.#started = true
+      return
+    }
+    return started.then(
+      () => {
+        this.#started = true
+      },
+      (error: unknown) => {
+        throw driverFailed(driver, error)
+      },
+    )
   }
 
   onStart(ctx: PluginContext): void {
@@ -230,12 +258,45 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
     else ctx.logger.info('GraphQL endpoint ready', { path: options.path, ...details })
   }
 
+  /**
+   * The `PluginHttpRoutes` contract: `HttpPlugin` starts draining, whatever the plugin order. The
+   * subscriptions of the engine end (a route-mounted driver serves them as streamed responses
+   * `HttpPlugin` does not close), and new ones are refused (503); queries and mutations in flight
+   * are served. Built-in SSE streams are closed by `HttpPlugin` itself.
+   */
+  onHttpDrain(): Promise<void> | undefined {
+    return this.#runtime?.executor.stopEngineStreams()
+  }
+
   async onStop(): Promise<void> {
     this.#stop?.abort(new Error('The application is stopping'))
-    await this.#runtime?.executor.stopDirect()
+    // direct subscriptions and the driver's (engine) ones; built-in SSE streams end with HttpPlugin
+    await this.#runtime?.executor.stopStreams()
+    // a route-mounted driver serves requests until HttpPlugin drained them: it stops in onDispose
+    if (this.#driver?.routes === undefined) await this.#stopDriver()
+  }
+
+  onDispose(): void | Promise<void> {
+    if (!this.#started) {
+      this.#release()
+      return
+    }
+    // after HttpPlugin drained (every onStop ran), or disposed without having started (onStop did not run)
+    this.#stop?.abort(new Error('The application is stopping'))
+    return Promise.resolve(this.#runtime?.executor.stopStreams())
+      .then(() => this.#stopDriver())
+      .finally(() => this.#release())
   }
 
-  onDispose(): void {
+  /** Stops the driver started in onBootstrap (once). */
+  #stopDriver(): void | Promise<void> {
+    const driver = this.#driver
+    if (!this.#started) return
+    this.#started = false
+    return driver?.stop?.()
+  }
+
+  #release(): void {
     this.#active = false
     this.#ownPubSub?.close()
     this.#ownPubSub = undefined
@@ -250,6 +311,15 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
     return this.#ready().schema
   }
 
+  /**
+   * The GraphQL engine (after bootstrap, RFC 0009): graphql-js-shaped `parse`, `validate`, `execute`
+   * and `subscribe` running this plugin's schema with its guards, loaders, request scope, error
+   * formatting and hook. What drivers receive in `start()`; any GraphQL server can call it.
+   */
+  get engine(): GraphQLEngine {
+    return this.#ready().engine
+  }
+
   /** The SDL of the schema (graphql-js `printSchema`). */
   printSchema(): string {
     return printSchema(this.#ready().schema)
@@ -320,6 +390,25 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
     return this.#resolved
   }
 
+  /** The driver of the application: the `driver` option, or the built-in transport. */
+  #driverOf(options: ResolvedGraphQLOptions): GraphQLDriver {
+    let driver = this.#driver
+    if (driver === undefined) {
+      const http = options.http
+      driver =
+        options.driver ??
+        new BuiltinDriver({
+          // called on the first request: the routes are collected before or after this plugin's onBootstrap
+          executor: () => this.#ready().executor,
+          get: http !== false && http.get,
+          graphiql: options.graphiql,
+          sse: sseOptions(options),
+        })
+      this.#driver = driver
+    }
+    return driver
+  }
+
   /** The SSE options are those of `HttpResponse.sse()` (heartbeat and maxDuration from 1 000 ms): checked at boot. */
   #checkSse(options: ResolvedGraphQLOptions): void {
     const sse = sseOptions(options)
@@ -329,6 +418,14 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
   }
 
   #checkHttp(ctx: PluginContext, options: ResolvedGraphQLOptions): void {
+    const driver = options.driver
+    if (options.http === false && driver?.routes !== undefined) {
+      throw new ZnightError(
+        ErrorCode.InvalidGraphQLSetup,
+        `GraphQLPlugin: the ${driver.name} driver serves routes, which http: false turns off`,
+        { hints: ['Remove http: false: the driver serves the endpoint through HttpPlugin'] },
+      )
+    }
     if (options.http !== false && ctx.getPlugin('http') === undefined) {
       throw new ZnightError(
         ErrorCode.InvalidGraphQLSetup,
@@ -423,13 +520,29 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
       introspection: options.introspection,
       documentCache: options.documentCache,
       maxActiveSubscriptions: options.subscriptions === false ? undefined : options.subscriptions.maxActive,
+      subscriptions: options.subscriptions !== false,
     })
+    const http = ctx.getPlugin<HttpPlugin>('http')
+    const engine = new Engine(
+      executor,
+      {
+        path:
+          this.#endpoint ?? endpointPath(options.http === false || http === undefined ? '' : http.prefix, options.path),
+        introspection: options.introspection,
+        ide: options.graphiql,
+        exposeErrors: options.exposeErrors,
+        maxTokens: options.limits.maxTokens,
+        subscriptions: options.subscriptions === false ? false : { maxActive: options.subscriptions.maxActive },
+        http: options.http === false ? false : { get: options.http.get, bodyLimit: options.http.bodyLimit },
+      },
+      options.driver?.name ?? BUILTIN_DRIVER,
+    )
     ctx.logger.debug('GraphQL schema built', {
       types: types.length,
       schemaHash: section.schemaHash,
       ...(results.fields === 0 ? {} : { resultFields: results.fields }),
     })
-    return { schema, section, executor }
+    return { schema, section, executor, engine }
   }
 }
 
@@ -444,6 +557,34 @@ function direct(options: DirectExecuteOptions | undefined): ExecuteOptions {
 
 const DIRECT: ExecuteOptions = Object.freeze({ transport: 'direct' })
 
+/** A route of the driver as a plugin route: the `http` option's meta and guards, its body limit unless `GET`. */
+function mount(
+  route: GraphQLDriverRoute,
+  http: Exclude<ResolvedGraphQLOptions['http'], false>,
+  driver: GraphQLDriver,
+): PluginRoute {
+  if (route === null || typeof route !== 'object' || typeof route.handler !== 'function') {
+    throw invalidOption(`routes() of the ${driver.name} driver`, 'routes { method, path, name, handler }', route)
+  }
+  return {
+    method: route.method,
+    path: route.path,
+    name: route.name,
+    handler: route.handler,
+    ...(http.meta.length === 0 ? {} : { meta: http.meta }),
+    ...(http.guards.length === 0 ? {} : { guards: http.guards }),
+    ...(route.method === 'GET' || route.method === 'HEAD' ? {} : { bodyLimit: http.bodyLimit }),
+  }
+}
+
+/** ZNIGHT066 for a driver whose `start()` failed, the original error as `cause`. */
+function driverFailed(driver: GraphQLDriver, error: unknown): ZnightError {
+  return new ZnightError(ErrorCode.InvalidGraphQLSetup, `GraphQLPlugin: the ${driver.name} driver failed to start`, {
+    cause: error,
+    hints: ['See the cause: the driver could not create its server'],
+  })
+}
+
 /** `prefix` (`''`, `/api`) joined with `path` (`/graphql`), without trailing slash: `/api/graphql`. */
 function endpointPath(prefix: string, path: string): string {
   const joined = `${prefix.replace(/\/+$/, '')}/${path.replace(/^\/+|\/+$/g, '')}`

package/src/testing.ts

@@ -6,6 +6,7 @@
  *   `GraphQLPlugin.execute()`;
  * - `subscribeOperation()` streams an operation over GraphQL over SSE in memory, or through
  *   `GraphQLPlugin.subscribe()` without HTTP transport;
+ * - `describeDriverConformance()` describes the conformance scenarios of a GraphQL driver (RFC 0009);
  * - `fakeLoader()` builds a `Loader<L>` whose `load` / `loadMany` are spies of the running test
  *   framework (`bun:test`, Vitest, Jest, or the built-in spy of `@znight/testing`).
  *
@@ -23,6 +24,8 @@ import { resolveMockFn } from '@znight/testing'
 
 import { endpointOf, executorOf, type GraphQLPlugin } from './plugin.ts'
 
+export { type ConformanceTestApi, type DriverConformanceOptions, describeDriverConformance } from './conformance.ts'
+
 /** An operation for {@link executeOperation} and {@link subscribeOperation}. */
 export interface OperationRequest {
   readonly query: string

package/src/transport/builtin.ts

@@ -0,0 +1,57 @@
+/**
+ * The built-in transport as a driver (RFC 0009 §4.11): GraphQL over HTTP and SSE, the default when
+ * the `driver` option is absent. It keeps its privileged access to the internal executor (statuses,
+ * formatted results, SSE sessions, the memoised negotiation): its handlers are the ones of
+ * `HttpTransport`, unchanged, and it never goes through the public engine.
+ */
+import type { SseOptions } from '@znight/http'
+import type { GraphQLDriver, GraphQLDriverRoute, GraphQLDriverRoutesContext } from '../driver.ts'
+import type { GraphQLExecutor } from '../execution.ts'
+
+import { HttpTransport } from './http.ts'
+
+/** What the built-in driver is built from (resolved plugin options). */
+export interface BuiltinDriverOptions {
+  /** The executor of the plugin, read on the first request (routes may be collected before the bootstrap). */
+  readonly executor: () => GraphQLExecutor
+  /** Queries over `GET`. */
+  readonly get: boolean
+  readonly graphiql: boolean
+  /** `HttpResponse.sse()` options of GraphQL over SSE; `false`: no event streams. */
+  readonly sse: SseOptions | false
+}
+
+/** The name of the built-in transport (`GraphQLOperationEvent.driver`), reserved. */
+export const BUILTIN_DRIVER = 'builtin'
+
+/** The built-in GraphQL-over-HTTP and SSE endpoint. */
+export class BuiltinDriver implements GraphQLDriver {
+  readonly name: string = BUILTIN_DRIVER
+  readonly #options: BuiltinDriverOptions
+
+  constructor(options: BuiltinDriverOptions) {
+    this.#options = options
+  }
+
+  /** `POST` on the path, and `GET` when queries over `GET` or GraphiQL are on (the router answers 405 otherwise). */
+  routes(context: GraphQLDriverRoutesContext): readonly GraphQLDriverRoute[] {
+    const options = this.#options
+    const transport = new HttpTransport({
+      executor: options.executor,
+      endpoint: context.endpoint,
+      get: options.get,
+      graphiql: options.graphiql,
+      sse: options.sse,
+    })
+    const routes: GraphQLDriverRoute[] = [
+      { method: 'POST', path: context.path, name: 'handle', handler: transport.post },
+    ]
+    if (options.get || options.graphiql) {
+      routes.unshift({ method: 'GET', path: context.path, name: 'handle', handler: transport.get })
+    }
+    return routes
+  }
+
+  /** Nothing to start: the handlers read the executor on the first request. */
+  start(): void {}
+}

package/src/transport/fetch.ts

@@ -0,0 +1,57 @@
+/**
+ * The Fetch bridge of route-mounted drivers (RFC 0009 §4.4, Q10): the Web `Request` a Fetch server
+ * (GraphQL Yoga) handles, built from the `HttpContext` of the route. Internal to `@znight/graphql`
+ * (a candidate for `@znight/http` once a second user appears).
+ *
+ * - On `honoAdapter()` the native request already is a Web `Request`: it is handed over as is when
+ *   its body was not read and cannot exceed the route's body limit (a `GET`, or a declared
+ *   `content-length` within the limit), so nothing is copied.
+ * - Otherwise (Node-style adapters, chunked bodies) a `Request` is built from the method, the URL,
+ *   the headers and the body read by `ctx.rawBody()`: the route's body limit then answers with
+ *   `HttpPlugin`'s 413 on every adapter, before the server sees the request. GraphQL servers buffer
+ *   the body to parse it anyway, so reading it first costs no extra copy of note.
+ */
+import type { HttpContext } from '@znight/http'
+
+/** The Web `Request` of the route's request, read under `limit` bytes. */
+export function fetchRequest(ctx: HttpContext, limit: number): Request | Promise<Request> {
+  const native = ctx.request
+  const method = ctx.method
+  const bodyless = method === 'GET' || method === 'HEAD'
+  if (native instanceof Request && !native.bodyUsed) {
+    if (bodyless) return native
+    const length = ctx.headers['content-length']
+    if (length !== undefined && ctx.headers['transfer-encoding'] === undefined) {
+      // past the limit, ctx.rawBody() below rejects with HttpPlugin's own 413
+      const declared = Number(length)
+      if (Number.isSafeInteger(declared) && declared >= 0 && declared <= limit) return native
+    }
+  }
+  const url = requestUrl(ctx)
+  const headers = requestHeaders(ctx)
+  if (bodyless) return new Request(url, { method, headers, signal: ctx.signal })
+  return ctx.rawBody().then(body => new Request(url, { method, headers, body, signal: ctx.signal }))
+}
+
+/** The absolute URL of the request: the raw target on the request's protocol and host. */
+function requestUrl(ctx: HttpContext): string {
+  const host = ctx.headers['host']
+  const target = ctx.url
+  if (host !== undefined && target.startsWith('/') && !target.startsWith('//')) {
+    const url = `${ctx.protocol}://${host}${target}`
+    if (URL.canParse(url)) return url
+  }
+  // no host header, or one a URL cannot hold: the path and query string still route the request
+  return new URL(target.startsWith('/') ? target.replace(/^\/+/, '/') : `/${target}`, `${ctx.protocol}://localhost`)
+    .href
+}
+
+function requestHeaders(ctx: HttpContext): Headers {
+  const headers = new Headers()
+  const source = ctx.headers
+  for (const name in source) {
+    const value = source[name]
+    if (value !== undefined) headers.append(name, value)
+  }
+  return headers
+}

package/src/transport/http.ts

@@ -90,8 +90,12 @@ const GET_NOT_ALLOWED = errorReply(
   Object.freeze({ allow: 'POST' }),
 )
 
-/** `content-type` values of JSON bodies seen most often, compared before parsing. */
-function isJsonRequest(contentType: string | undefined): boolean {
+/**
+ * Whether a `POST` body is JSON (`application/json`, UTF-8): the only body the endpoint takes (and
+ * the Yoga driver), so that a cross-site request, which cannot send it without a CORS preflight,
+ * never executes an operation. `content-type` values seen most often are compared before parsing.
+ */
+export 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)
@@ -99,6 +103,11 @@ function isJsonRequest(contentType: string | undefined): boolean {
   return media.charset === undefined || media.charset === 'utf-8' || media.charset === 'utf8'
 }
 
+/** The 415 of a `POST` body that is not JSON, in the negotiated JSON type. */
+export function notJson(media: MediaKind): HttpResponse<FormattedExecutionResult> {
+  return errorReply(media, 415, errorBody('Send GraphQL requests as application/json (content-type: application/json)'))
+}
+
 /** 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']
@@ -211,13 +220,7 @@ export class HttpTransport {
     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)'),
-      )
-    }
+    if (!isJsonRequest(headers['content-type'])) return notJson(media)
     const encoding = headers['content-encoding']
     if (encoding !== undefined && encoding.trim().toLowerCase() !== 'identity' && encoding.trim() !== '') {
       return errorReply(media, 415, errorBody(`Unsupported content encoding "${encoding}"`))