@znight/graphql 0.2.2 → 0.3.0

package/src/types.ts

@@ -17,8 +17,11 @@ export type GraphQLArgs = Readonly<Record<string, unknown>>
 /** Kind of a GraphQL operation. */
 export type GraphQLOperationKind = 'query' | 'mutation' | 'subscription'
 
-/** How an operation reached the server: GraphQL over HTTP, GraphQL over SSE, or `plugin.execute()`. */
-export type GraphQLTransport = 'http' | 'sse' | 'direct'
+/**
+ * How an operation reached the server: GraphQL over HTTP, GraphQL over SSE, GraphQL over WebSocket
+ * (`ws`, reserved for `graphql-ws`), or `plugin.execute()` / `plugin.subscribe()` (`direct`).
+ */
+export type GraphQLTransport = 'http' | 'sse' | 'ws' | 'direct'
 
 /**
  * Options of a loader (§5.5), read once per loader class: the `options` property of a
@@ -112,6 +115,13 @@ export interface GraphQLContext {
   readonly signal: AbortSignal
   /** Per-operation storage. */
   readonly state: Map<string | symbol, unknown>
+  /**
+   * The context of the GraphQL server that received the operation through a driver (RFC 0009): the
+   * `contextValue` it passed to `GraphQLEngine.execute()` (Yoga's initial context, Apollo's context
+   * value). `undefined` for the built-in transport and direct calls. Resolvers do not need it: the
+   * request is `http`, the user a request-scoped provider.
+   */
+  readonly serverContext: unknown
   /** The DataLoader of the current execution for a loader class (`ctx.loader(AuthorsById)`). */
   loader<L extends BatchLoad<unknown, unknown>>(loader: BatchLoadClass<L>): BatchLoader<LoaderKey<L>, LoaderValue<L>>
   /**

package/src/yoga.ts

@@ -0,0 +1,471 @@
+/**
+ * `@znight/graphql/yoga`: the GraphQL Yoga driver (RFC 0009 §5.1). GraphQL Yoga 6 serves the schema
+ * of `GraphQLPlugin` (its protocol, Envelop plugins, GraphiQL, SSE subscriptions) and hands every
+ * document to Znight's engine, which parses it through its document cache, validates it with its
+ * limits, and executes it with the application's guards, loaders, request scope, error masking and
+ * hook. Mounted as plugin routes of `HttpPlugin`: the HTTP pipeline (request scope, hooks, guards,
+ * CORS, security headers, drain) wraps every request, on every adapter, on Node.js and Bun.
+ *
+ * Needs `graphql-yoga` (an optional peer dependency of `@znight/graphql`), only loaded by this entry.
+ */
+import type { CoreLogger } from '@znight/core'
+import type { HttpContext } from '@znight/http'
+import type { DocumentNode, ExecutionArgs, ExecutionResult, GraphQLSchema, ValidationRule } from 'graphql'
+import type {
+  GraphiQLOptions,
+  YogaInitialContext,
+  Plugin as YogaPlugin,
+  YogaServerInstance,
+  YogaServerOptions,
+} from 'graphql-yoga'
+import type { GraphQLDriver, GraphQLDriverContext, GraphQLDriverRoute, GraphQLDriverRoutesContext } from './driver.ts'
+import type { EngineExecuteOptions, GraphQLEngine } from './engine.ts'
+import type { GraphQLContext } from './types.ts'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+import { parseByteSize } from '@znight/http'
+import { GraphQLError } from 'graphql'
+import { createYoga } from 'graphql-yoga'
+
+import { GraphQLErrorCode } from './errors.ts'
+import { MEDIA, Media, type MediaKind, negotiate } from './transport/accept.ts'
+import { fetchRequest } from './transport/fetch.ts'
+import { isJsonRequest, notJson } from './transport/http.ts'
+
+/** The server context the driver gives Yoga: the `HttpContext` of the route, as `znight`. */
+export interface YogaServerContext {
+  readonly znight: HttpContext
+}
+
+/**
+ * Yoga's context of an operation: its initial context (`request`, `params`, `log`) and the server
+ * context of the driver. What {@link yogaContext} returns.
+ */
+export type YogaContext = YogaInitialContext & YogaServerContext
+
+/** Options of Yoga the engine or `GraphQLPlugin` own (RFC 0009 §4.6): refused by {@link yogaDriver}. */
+const OWNED = [
+  'schema',
+  'context',
+  'graphqlEndpoint',
+  'maskedErrors',
+  'cors',
+  'fetchAPI',
+  'maxRequestBodySize',
+  'parserAndValidationCache',
+  'requestId',
+  'healthCheckEndpoint',
+  'landingPage',
+  'disposeOnProcessTerminate',
+  'batching',
+  'multipart',
+] as const
+
+/** Where each owned option comes from, for the ZNIGHT066 hint. */
+const OWNER: Readonly<Record<(typeof OWNED)[number], string>> = {
+  schema: 'the engine serves the schema GraphQLPlugin built',
+  context: "resolvers get GraphQLContext; read Yoga's context with yogaContext(ctx)",
+  graphqlEndpoint: 'set the path option of GraphQLPlugin',
+  maskedErrors: 'the engine masks errors once (exposeErrors, errorMappers)',
+  cors: 'set the cors option of HttpPlugin',
+  fetchAPI: "the driver gives Yoga the runtime's own Fetch API",
+  maxRequestBodySize: 'set http.bodyLimit of GraphQLPlugin',
+  parserAndValidationCache: 'the engine caches documents (the documentCache option of GraphQLPlugin)',
+  requestId: 'Yoga uses the request id of HttpPlugin',
+  healthCheckEndpoint: 'the driver only serves the GraphQL endpoint',
+  landingPage: 'the driver only serves the GraphQL endpoint',
+  disposeOnProcessTerminate: 'the application stops Yoga once HttpPlugin drained its requests',
+  batching:
+    'Send one operation per request: the operations of a batch would share the request scope and its GraphQLContext',
+  multipart:
+    'POST bodies are application/json only: form and multipart bodies skip the CORS preflight (CSRF); upload files through an HTTP controller',
+}
+
+/**
+ * Options of {@link yogaDriver}: Yoga's own (`plugins`, `logging`, `allowedHeaders`...), except
+ * those the engine, `GraphQLPlugin` or `HttpPlugin` own: the schema, the context, the endpoint
+ * (`path`), masking (`exposeErrors`), CORS, the body limit (`http.bodyLimit`), the document cache,
+ * the request id and the IDE switch (`graphiql`); and those the driver refuses: `batching` (one
+ * operation per request scope) and `multipart` (JSON bodies only, see {@link yogaDriver}). Yoga's
+ * `logging` is off unless set: requests and operations are logged by Znight.
+ */
+export interface YogaDriverOptions
+  extends Omit<YogaServerOptions<YogaServerContext, Record<string, unknown>>, (typeof OWNED)[number] | 'graphiql'> {
+  /**
+   * GraphiQL's options (title, default query...), when the `graphiql` option of `GraphQLPlugin` is
+   * on (it decides whether the IDE is served).
+   */
+  readonly graphiql?: GraphiQLOptions
+}
+
+/** A GraphQL Yoga driver: `GraphQLPlugin.configure({ driver: yogaDriver() })`. */
+export interface YogaDriver extends GraphQLDriver {
+  readonly name: 'yoga'
+  /** The Yoga server, once started (`undefined` before `start()` and after `stop()`). */
+  readonly yoga: YogaServerInstance<YogaServerContext, Record<string, unknown>> | undefined
+}
+
+/**
+ * The GraphQL Yoga driver (RFC 0009 §5.1): `GraphQLPlugin.configure({ driver: yogaDriver({ plugins }) })`.
+ * Yoga handles the protocol and its Envelop plugins; the engine parses, validates and executes
+ * (guards, loaders, request scope, masking, the `graphql:operation` hook). Plugins that replace
+ * the engine's execution (`useGraphQlJit`) are refused: the operation fails with ZNIGHT066.
+ *
+ * Like the built-in transport, a `POST` body is `application/json` only (415 otherwise): form,
+ * multipart and text bodies, which a cross-site page sends without a CORS preflight, never run
+ * an operation (CSRF). Errors thrown outside the engine (by Yoga or an Envelop plugin) are masked
+ * like the engine's (`Unexpected error.` unless `exposeErrors`) and logged.
+ *
+ * ```ts
+ * GraphQLPlugin.configure({
+ *   guards: [AccessGuard],
+ *   driver: yogaDriver({ plugins: [useResponseCache({ session: () => null })] }),
+ * })
+ * ```
+ */
+export function yogaDriver(options: YogaDriverOptions = {}): YogaDriver {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw invalid('yogaDriver(): expected an options object', ['yogaDriver({ plugins: [...] })'])
+  }
+  for (const key of OWNED) {
+    if ((options as Record<string, unknown>)[key] !== undefined) {
+      throw invalid(`yogaDriver(): the ${key} option of Yoga is not available with Znight`, [OWNER[key]])
+    }
+  }
+  const graphiql: unknown = options.graphiql
+  if (graphiql !== undefined && (graphiql === null || typeof graphiql !== 'object')) {
+    throw invalid("yogaDriver(): graphiql takes GraphiQL's options", [
+      'Turn the IDE on or off with the graphiql option of GraphQLPlugin',
+    ])
+  }
+  if (options.plugins !== undefined && !Array.isArray(options.plugins)) {
+    throw invalid('yogaDriver(): plugins must be an array of Envelop plugins', [])
+  }
+  return new Driver(options)
+}
+
+/**
+ * Yoga's context of an operation received by the Yoga driver (RFC 0009 Q2): `GraphQLContext.serverContext`,
+ * typed. For the rare resolver that needs Yoga's `request`, `params` or the context an Envelop
+ * plugin extended; the HTTP request is `ctx.http`, the user a request-scoped provider.
+ *
+ * @throws ZnightError (ZNIGHT066) when the operation did not come through the Yoga driver.
+ */
+export function yogaContext<TContext extends Record<string, unknown> = Record<string, unknown>>(
+  ctx: GraphQLContext,
+): YogaContext & TContext {
+  const server = ctx?.serverContext as Partial<YogaContext> | undefined
+  if (server === null || typeof server !== 'object' || server.znight === undefined || server.params === undefined) {
+    throw invalid('yogaContext(): the operation was not received by the Yoga driver', [
+      'yogaContext() reads GraphQLContext.serverContext of operations served by yogaDriver()',
+    ])
+  }
+  return server as YogaContext & TContext
+}
+
+// ------------------------------------------------------------------------------------------------
+
+type Yoga = YogaServerInstance<YogaServerContext, Record<string, unknown>>
+
+const SSE: EngineExecuteOptions = Object.freeze({ transport: 'sse' })
+const DEFAULT_BODY_LIMIT = 1024 * 1024
+
+class Driver implements YogaDriver {
+  readonly name = 'yoga' as const
+  readonly #options: YogaDriverOptions
+  #yoga: Yoga | undefined
+  /** Stopped: the application stops, requests that still reach the driver get a 503. */
+  #stopped = false
+  #get = true
+  #ide = false
+  #limit = DEFAULT_BODY_LIMIT
+
+  constructor(options: YogaDriverOptions) {
+    this.#options = options
+  }
+
+  get yoga(): Yoga | undefined {
+    return this.#yoga
+  }
+
+  /** `GET` and `POST` on the path (`GET` answers 405 when neither queries over `GET` nor GraphiQL apply). */
+  routes(context: GraphQLDriverRoutesContext): readonly GraphQLDriverRoute[] {
+    return [
+      { method: 'GET', path: context.path, name: 'yoga', handler: this.#getHandler },
+      { method: 'POST', path: context.path, name: 'yoga', handler: this.#postHandler },
+    ]
+  }
+
+  start(engine: GraphQLEngine, context: GraphQLDriverContext): void {
+    if (this.#yoga !== undefined) {
+      throw invalid('yogaDriver(): this driver already serves an application', [
+        'Create one driver per application: GraphQLPlugin.configure({ driver: yogaDriver() })',
+      ])
+    }
+    const settings = engine.settings
+    const http = settings.http
+    this.#get = http !== false && http.get
+    this.#ide = settings.ide
+    this.#limit = http === false ? DEFAULT_BODY_LIMIT : (parseByteSize(http.bodyLimit) ?? DEFAULT_BODY_LIMIT)
+    const { graphiql, plugins = [], logging = false, ...rest } = this.#options
+    const engineFns = engineFunctions(engine, context.logger)
+    this.#yoga = createYoga<YogaServerContext, Record<string, unknown>>({
+      ...rest,
+      logging,
+      schema: engine.schema,
+      graphqlEndpoint: settings.path,
+      graphiql: settings.ide ? (graphiql ?? true) : false,
+      landingPage: false,
+      healthCheckEndpoint: UNREACHABLE,
+      // the engine masked its errors (kept as they are); those thrown outside of it are masked here
+      maskedErrors: { maskError: outsideErrors(settings.exposeErrors, context.logger) },
+      batching: false,
+      multipart: false,
+      cors: false, // HttpPlugin's CORS
+      maxRequestBodySize: this.#limit,
+      parserAndValidationCache: false, // the engine's document cache
+      disposeOnProcessTerminate: false,
+      requestId: { generateRequestId: requestIdOf, trustHeader: false },
+      fetchAPI: fetchApi(),
+      plugins: [engineFns.plugin, ...plugins, engineFns.guard],
+    })
+    this.#stopped = false
+  }
+
+  /** Called once `HttpPlugin` drained the requests (`GraphQLPlugin.onDispose`). */
+  async stop(): Promise<void> {
+    const yoga = this.#yoga
+    this.#yoga = undefined
+    this.#stopped = true
+    await yoga?.dispose()
+  }
+
+  readonly #handle = (ctx: HttpContext): Response | Promise<Response> => {
+    const yoga = this.#yoga
+    if (yoga === undefined) {
+      if (this.#stopped) return shuttingDown()
+      throw notStarted()
+    }
+    const request = fetchRequest(ctx, this.#limit)
+    const server: YogaServerContext = { znight: ctx }
+    const response =
+      request instanceof Request ? yoga.fetch(request, server) : request.then(built => yoga.fetch(built, server))
+    return response instanceof Response ? response : Promise.resolve(response).then(sendable)
+  }
+
+  /** `POST`: JSON bodies only (the 415 of the built-in transport otherwise: no CSRF). */
+  readonly #postHandler = (ctx: HttpContext): unknown => {
+    const headers = ctx.headers
+    if (!isJsonRequest(headers['content-type'])) return notJson(jsonMedia(headers['accept']))
+    return this.#handle(ctx)
+  }
+
+  /** `GET`: Yoga's, or 405 when queries over `GET` are off (GraphiQL pages still served). */
+  readonly #getHandler = (ctx: HttpContext): Response | Promise<Response> => {
+    if (this.#get || (this.#ide && acceptsHtml(ctx))) return this.#handle(ctx)
+    return getNotAllowed()
+  }
+}
+
+/** A path no request reaches: the driver's routes only serve the GraphQL endpoint. */
+const UNREACHABLE = '/.znight/unreachable'
+
+/**
+ * The Fetch API of the runtime: on Node.js, Yoga would otherwise use the ponyfills of
+ * `@whatwg-node/fetch`, whose `Response` objects `HttpPlugin` cannot send.
+ */
+function fetchApi(): Record<string, unknown> {
+  return {
+    fetch: globalThis.fetch,
+    Request: globalThis.Request,
+    Response: globalThis.Response,
+    Headers: globalThis.Headers,
+    FormData: globalThis.FormData,
+    ReadableStream: globalThis.ReadableStream,
+    WritableStream: globalThis.WritableStream,
+    TransformStream: globalThis.TransformStream,
+    CompressionStream: globalThis.CompressionStream,
+    DecompressionStream: globalThis.DecompressionStream,
+    TextDecoderStream: globalThis.TextDecoderStream,
+    TextEncoderStream: globalThis.TextEncoderStream,
+    Blob: globalThis.Blob,
+    File: globalThis.File,
+    TextEncoder: globalThis.TextEncoder,
+    TextDecoder: globalThis.TextDecoder,
+    URL: globalThis.URL,
+    URLSearchParams: globalThis.URLSearchParams,
+    btoa: globalThis.btoa,
+  }
+}
+
+/**
+ * A `Response` `HttpPlugin` recognises: `@hono/node-server` replaces the global `Response` when it
+ * starts listening, after Yoga captured the runtime's own; such a response is rebuilt on the
+ * global class (same status, headers and body stream).
+ */
+function sendable(response: Response): Response {
+  if (response instanceof Response) return response
+  const foreign: { readonly body: ReadableStream<Uint8Array> | null } & ResponseInit = response
+  return new Response(foreign.body, foreign)
+}
+
+/** The request id of `HttpPlugin` (a UUID for a request handed to `yoga.fetch()` directly). */
+function requestIdOf(payload: { readonly context: Partial<YogaServerContext> }): string {
+  return payload.context.znight?.requestId ?? crypto.randomUUID()
+}
+
+function acceptsHtml(ctx: HttpContext): boolean {
+  return ctx.headers['accept']?.includes('text/html') === true
+}
+
+/** The JSON type a refusal is written in, like the built-in transport: `application/json` unless the client prefers `application/graphql-response+json`. */
+function jsonMedia(accept: string | undefined): MediaKind {
+  const media = (negotiate(accept, (1 << Media.GraphQLJson) | (1 << Media.Json)) & MEDIA) as MediaKind
+  return media === Media.None ? Media.Json : media
+}
+
+/** A request reaching the driver once it stopped (after `HttpPlugin` drained): 503. */
+function shuttingDown(): Response {
+  return Response.json(
+    {
+      errors: [
+        {
+          message: 'The server is shutting down, retry later',
+          extensions: { code: GraphQLErrorCode.ServiceUnavailable },
+        },
+      ],
+    },
+    { status: 503 },
+  )
+}
+
+/**
+ * Yoga's `maskError`: the errors of the engine (masked already) and the `GraphQLError`s thrown on
+ * purpose (by Yoga or a plugin, with a code) are kept; any other error, thrown outside the engine
+ * (an Envelop plugin's hook, Yoga itself), is logged and masked like the engine masks it
+ * (`Unexpected error.`, its message with `exposeErrors`). Yoga then answers 500 for a request error.
+ */
+function outsideErrors(expose: boolean, logger: CoreLogger): (error: unknown, message: string) => Error {
+  return (error, message) => {
+    if (isOriginalGraphQLError(error)) return error
+    logger.error('GraphQL: an error was thrown outside the engine (by Yoga or an Envelop plugin)', { err: error })
+    const original = error instanceof Error ? error : new Error(String(error))
+    return new GraphQLError(expose ? original.message : message, {
+      originalError: original,
+      extensions: { code: GraphQLErrorCode.InternalServerError },
+    })
+  }
+}
+
+/** A `GraphQLError` that wraps no other error: the engine's, or thrown on purpose. */
+function isOriginalGraphQLError(error: unknown): error is GraphQLError {
+  if (!(error instanceof GraphQLError)) return false
+  const original = error.originalError
+  return original === undefined || original === null || isOriginalGraphQLError(original)
+}
+
+function getNotAllowed(): Response {
+  return Response.json(
+    {
+      errors: [
+        { message: 'GraphQL operations are sent with POST on this endpoint', extensions: { code: 'BAD_REQUEST' } },
+      ],
+    },
+    { status: 405, headers: { allow: 'POST' } },
+  )
+}
+
+/** Envelop's onExecute payload (the part the driver reads). */
+interface ExecutePayload {
+  readonly executeFn: unknown
+  readonly context: unknown
+  setExecuteFn(fn: (args: ExecutionArgs) => unknown): void
+}
+
+interface SubscribePayload {
+  readonly subscribeFn: unknown
+  readonly context: unknown
+  setSubscribeFn(fn: (args: ExecutionArgs) => unknown): void
+}
+
+interface ResultPayload {
+  readonly result: unknown
+  setResult(result: ExecutionResult): void
+}
+
+/**
+ * The Envelop plugins of the engine: one installed before the application's plugins, which makes
+ * the engine Yoga's `parse`, `validate`, `execute` and `subscribe` (Envelop's `useEngine`), and a
+ * guard installed after them, which refuses an operation that a plugin executed elsewhere
+ * (`useGraphQlJit`): its resolvers would not get the `GraphQLContext`. Plugins wrapping the
+ * execution (`useResponseCache`) keep working: they call the engine.
+ */
+function engineFunctions(engine: GraphQLEngine, logger: CoreLogger): { plugin: YogaPlugin; guard: YogaPlugin } {
+  const parse = engine.parse
+  const validate = (schema: GraphQLSchema, document: DocumentNode, rules?: readonly ValidationRule[]) =>
+    engine.validate(schema, document, rules)
+  // marks the contexts the engine ran, once a plugin wrapped or replaced the execution
+  let watching = false
+  const ran = new WeakSet<object>()
+  const execute = (args: ExecutionArgs): unknown => {
+    if (watching) mark(ran, args.contextValue)
+    return engine.execute(args)
+  }
+  const subscribe = (args: ExecutionArgs): unknown => {
+    if (watching) mark(ran, args.contextValue)
+    return engine.subscribe(args, SSE)
+  }
+  let reported = false
+  const bypassed = (): ExecutionResult => {
+    const error = invalid(
+      'GraphQLPlugin: a Yoga plugin executed the operation instead of the Znight engine (useGraphQlJit?)',
+      ['Remove the plugin: resolvers, guards and loaders only run on the engine'],
+    )
+    if (!reported) {
+      reported = true
+      logger.error(error.message, { error })
+    }
+    return { errors: [new GraphQLError(error.message, { extensions: { code: 'INTERNAL_SERVER_ERROR' } })] }
+  }
+  const plugin = {
+    onParse: ({ setParseFn }: { setParseFn(fn: unknown): void }) => setParseFn(parse),
+    onValidate: ({ setValidationFn }: { setValidationFn(fn: unknown): void }) => setValidationFn(validate),
+    onExecute: ({ setExecuteFn }: ExecutePayload) => setExecuteFn(execute),
+    onSubscribe: ({ setSubscribeFn }: SubscribePayload) => setSubscribeFn(subscribe),
+  }
+  const guard = {
+    onExecute: ({ executeFn, context }: ExecutePayload) => {
+      if (executeFn === execute) return undefined
+      watching = true
+      return {
+        onExecuteDone: ({ setResult }: ResultPayload) => {
+          if (!ran.has(context as object)) setResult(bypassed())
+        },
+      }
+    },
+    onSubscribe: ({ subscribeFn, context }: SubscribePayload) => {
+      if (subscribeFn === subscribe) return undefined
+      watching = true
+      return {
+        onSubscribeResult: ({ setResult }: ResultPayload) => {
+          if (!ran.has(context as object)) setResult(bypassed())
+        },
+      }
+    },
+  }
+  return { plugin: plugin as YogaPlugin, guard: guard as YogaPlugin }
+}
+
+function mark(ran: WeakSet<object>, context: unknown): void {
+  if (context !== null && typeof context === 'object') ran.add(context)
+}
+
+function notStarted(): ZnightError {
+  return new ZnightError(ErrorCode.LifecycleFailed, 'The Yoga driver is not started yet', {
+    hints: ['GraphQLPlugin starts its driver in onBootstrap'],
+  })
+}
+
+function invalid(message: string, hints: readonly string[]): ZnightError {
+  return new ZnightError(ErrorCode.InvalidGraphQLSetup, message, { hints: [...hints] })
+}