@znight/graphql 0.2.2 → 0.4.0

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}"`))

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>>
   /**
@@ -121,9 +131,17 @@ export interface GraphQLContext {
   loader(token: Token): BatchLoader<unknown, unknown>
 }
 
+declare module '@znight/core' {
+  /** Custom parameter decorators (`createParamDecorator`) resolve GraphQL parameters from the {@link ResolverContext}. */
+  interface ParamContexts {
+    graphql: ResolverContext
+  }
+}
+
 /**
- * What a {@link GraphQLGuard} receives for one resolver call (§5.9). It satisfies the
- * `RouteMetaCarrier` of `@znight/http`, so route decorators read it: `Roles.get(ctx)`.
+ * What a {@link GraphQLGuard} receives for one resolver call (§5.9), and the context of custom
+ * parameter resolvers (RFC 0010). It satisfies the `RouteMetaCarrier` of `@znight/http`, so route
+ * decorators read it: `Roles.get(ctx)`.
  */
 export interface ResolverContext<TParent = unknown, TArgs extends GraphQLArgs = GraphQLArgs> extends RouteMetaCarrier {
   /** Effective metadata of the field (method decisions over class decisions) and its schema coordinate. */