@znight/graphql 0.2.2 → 0.4.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/metadata.ts

@@ -12,7 +12,7 @@
 import type { Token } from '@znight/core'
 import type { HttpRouteGroupDefinition } from '@znight/http'
 import type { GraphQLResolveInfo, GraphQLScalarType } from 'graphql'
-import type { GraphQLArgs, GraphQLContext, ScalarDefinition } from './types.ts'
+import type { GraphQLArgs, GraphQLContext, ResolverContext, ScalarDefinition } from './types.ts'
 
 /** Format version of `metadata.extensions.graphql` (another version is ZNIGHT066 at boot). */
 export const GRAPHQL_METADATA_VERSION = 1
@@ -201,18 +201,34 @@ export interface GraphQLResolverBinding {
   readonly meta: Readonly<Record<string, unknown>>
   /** Informational: loader provider tokens the method injects. */
   readonly loaders?: readonly Token[]
+  /**
+   * The method has custom parameters (`createParamDecorator`, RFC 0010): the pipeline passes the
+   * field's `ResolverContext` to `invoke` (`f`). Absent otherwise.
+   */
+  readonly context?: true
+  /**
+   * Provider classes resolving custom parameters (`ParamResolver`), in order of first use: the
+   * pipeline resolves them in the operation scope and passes the instances to `invoke` (`x`).
+   * Absent when there is none.
+   */
+  readonly paramResolvers?: readonly Token[]
   /**
    * Calls the method: maps the graphql-js arguments to the method parameters (§7.3). Synchronous
-   * unless an argument is validated with a Standard Schema.
+   * unless an argument is validated with a Standard Schema or a custom parameter resolver returns a
+   * promise. `field` and `resolvers` are passed only to methods with custom parameters (declared as
+   * a method so that a generated invoke requiring them is accepted).
    */
-  readonly invoke: (
+  invoke(
     // biome-ignore lint/suspicious/noExplicitAny: generated invokers receive the concrete resolver class
     resolver: any,
     parent: unknown,
     args: GraphQLArgs,
     context: GraphQLContext,
     info: GraphQLResolveInfo,
-  ) => unknown
+    field?: ResolverContext,
+    // biome-ignore lint/suspicious/noExplicitAny: generated invokers receive the tuple of resolver classes
+    resolvers?: any,
+  ): unknown
 }
 
 declare module '@znight/core' {

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/pipeline.ts

@@ -45,6 +45,8 @@ export interface PipelineOptions {
   readonly guard: (token: Token, coordinate: string) => Resolvable<GraphQLGuard>
   /** The resolver provider of a binding (memoised by the caller). */
   readonly resolver: (binding: GraphQLResolverBinding, coordinate: string) => Resolvable<object>
+  /** The provider of a custom parameter resolver class (RFC 0010; memoised by the caller). */
+  readonly paramResolver?: (token: Token, coordinate: string) => Resolvable<object>
   /** Input object types by name (null handling of nested input values). */
   readonly inputs: ReadonlyMap<string, GraphQLInputTypeDefinition>
   /** The {@link Recover} function of a field that carries results (RFC 0008), `undefined` for the others. */
@@ -52,7 +54,15 @@ export interface PipelineOptions {
 }
 
 /** The generated invoker of a binding. */
-type Invoke = GraphQLResolverBinding['invoke']
+type Invoke = (
+  resolver: object,
+  parent: unknown,
+  args: GraphQLArgs,
+  context: GraphQLContext,
+  info: GraphQLResolveInfo,
+  field?: ResolverContext,
+  resolvers?: readonly object[],
+) => unknown
 
 /** Mutates a coerced argument or input value in place: `null` → `undefined` where flagged. */
 type Normalize = (value: unknown) => void
@@ -78,7 +88,6 @@ function fieldFunctions(
   parent: GraphQLObjectTypeDefinition,
 ): FieldFunctions {
   const container = options.container
-  const invoke: Invoke = binding.invoke
   const target = options.resolver(binding, coordinate)
   const guards: Resolvable<GraphQLGuard>[] = [
     ...(globalGuardsApply(binding) ? options.globalGuards : []),
@@ -86,10 +95,16 @@ function fieldFunctions(
   ]
   const normalize = field.args === undefined ? undefined : normalizers.args(field.args)
   const recover = options.results?.(field, coordinate)
+  const custom = binding.context === true
   const route =
-    guards.length === 0 && recover === undefined ? undefined : Object.freeze({ meta: binding.meta, coordinate })
+    guards.length === 0 && recover === undefined && !custom
+      ? undefined
+      : Object.freeze({ meta: binding.meta, coordinate })
   const parentType = parent.name
   const fieldName = field.name
+  const invoke: Invoke = custom
+    ? customInvoke(options, binding, coordinate, route as ResolverContext['route'], parentType, fieldName)
+    : (binding.invoke as Invoke)
 
   let resolve: GraphQLFieldResolver<unknown, unknown>
   if (guards.length === 0) {
@@ -120,15 +135,21 @@ function fieldFunctions(
     resolve = (p, a, c, i) => {
       const operation = c as OperationContext
       const args = a as GraphQLArgs
-      const allowed = runGuards(
-        container,
-        guards,
-        new FieldContext(route as ResolverContext['route'], operation, parentType, fieldName, args, p, i),
+      const fieldContext = new FieldContext(
+        route as ResolverContext['route'],
+        operation,
+        parentType,
+        fieldName,
+        args,
+        p,
+        i,
       )
-      // §8.5: guards (they see the coerced arguments), then null handling, then invoke
+      const allowed = runGuards(container, guards, fieldContext)
+      // §8.5: guards (they see the coerced arguments), then null handling, then invoke (custom
+      // parameters share the guards' ResolverContext)
       const call = (): unknown => {
         if (normalize !== undefined) normalize(args)
-        return invoke(resolveIn(container, target), p, args, operation, i)
+        return invoke(resolveIn(container, target), p, args, operation, i, fieldContext)
       }
       if (allowed === true) return call()
       if (allowed === false) return forbidden()
@@ -150,6 +171,48 @@ function identity(payload: unknown): unknown {
   return payload
 }
 
+/**
+ * The invoke of a method with custom parameters (RFC 0010): the generated `invoke` receives the
+ * field's `ResolverContext` (the guards' one when the field has guards, else a new one) and the
+ * instances of its parameter resolvers: one frozen array resolved at boot when they are all
+ * singletons, otherwise resolved in the operation scope on every call.
+ */
+function customInvoke(
+  options: PipelineOptions,
+  binding: GraphQLResolverBinding,
+  coordinate: string,
+  route: ResolverContext['route'],
+  parentType: string,
+  fieldName: string,
+): Invoke {
+  const generated = binding.invoke as Invoke
+  const container = options.container
+  const tokens = binding.paramResolvers ?? []
+  const resolvers = tokens.map(token => {
+    if (options.paramResolver === undefined) throw new TypeError(`No parameter resolver for ${coordinate}`)
+    return options.paramResolver(token, coordinate)
+  })
+  const context = (p: unknown, a: GraphQLArgs, c: GraphQLContext, i: GraphQLResolveInfo, f?: ResolverContext) =>
+    f ?? new FieldContext(route, c as OperationContext, parentType, fieldName, a, p, i)
+  if (resolvers.length === 0) {
+    return (r, p, a, c, i, f) => generated(r, p, a, c, i, context(p, a, c, i, f))
+  }
+  if (resolvers.every(resolver => resolver.token === undefined)) {
+    const instances = Object.freeze(resolvers.map(resolver => resolveIn(container, resolver)))
+    return (r, p, a, c, i, f) => generated(r, p, a, c, i, context(p, a, c, i, f), instances)
+  }
+  return (r, p, a, c, i, f) =>
+    generated(
+      r,
+      p,
+      a,
+      c,
+      i,
+      context(p, a, c, i, f),
+      resolvers.map(resolver => resolveIn(container, resolver)),
+    )
+}
+
 /**
  * The resolve function of a field that carries results (RFC 0008): errors of the whole pipeline
  * (guards, null handling, `invoke`), thrown or rejected, go through `recover`. Synchronous results

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,
@@ -396,6 +493,8 @@ export class GraphQLPlugin implements Plugin, PluginHttpRoutes {
         guard: (token, coordinate) => providers.token<GraphQLGuard>(token, `guard of ${coordinate}`, 'canResolve'),
         resolver: (binding, coordinate) =>
           providers.token<object>(binding.token, `resolver of ${coordinate}`, binding.method),
+        paramResolver: (token, coordinate) =>
+          providers.token<object>(token, `parameter resolver of ${coordinate}`, 'resolve'),
         inputs,
         results: (field, coordinate) => results.recover(field, coordinate),
       }),
@@ -423,13 +522,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 +559,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, '')}`