@getsoda/core 0.2.2 → 0.3.0

package/src/http/routes.ts

@@ -11,9 +11,11 @@
  * ```
  */
 
+import { InjectionToken } from '../di/index.ts'
 import type { Constructor, Container, ControllerEntry, ModuleClass } from '../di/index.ts'
 import type { RouteDefinition } from '../routing/index.ts'
 import { parsePath } from '../routing/path.ts'
+import { methodNames } from '../utils/object.ts'
 import { isThenable } from '../utils/promise.ts'
 import type { Argument } from './arguments.ts'
 import type { Context, RouteInfo } from './context.ts'
@@ -25,6 +27,10 @@ import { ControllerError } from './errors.ts'
 import { createEnhancerResolver, createPipeline } from './pipeline.ts'
 import type { EnhancerResolver } from './pipeline.ts'
 import { createResponder } from './response.ts'
+import { createSseResponder } from './sse.ts'
+import { getGatewayPath } from '../websocket/decorators.ts'
+import { buildGateway } from '../websocket/gateway.ts'
+import type { BuiltGateway } from '../websocket/gateway.ts'
 
 /**
  * Options of `controllerRoutes`.
@@ -62,29 +68,6 @@ const joinPaths = (...parts: readonly string[]): string => {
   return path || '/'
 }
 
-/**
- * Public method names along the prototype chain, most derived first, without duplicates.
- */
-const methodNames = (instance: object): string[] => {
-  const names: string[] = []
-  const seen = new Set<string>(['constructor'])
-
-  for (
-    let prototype: object | null = Object.getPrototypeOf(instance);
-    prototype !== null && prototype !== Object.prototype;
-    prototype = Object.getPrototypeOf(prototype)
-  ) {
-    for (const name of Object.getOwnPropertyNames(prototype)) {
-      if (!seen.has(name)) {
-        seen.add(name)
-        names.push(name)
-      }
-    }
-  }
-
-  return names
-}
-
 /** Every `param()` must name a parameter of the full path, controller prefix included. */
 const assertParamsExist = (args: readonly Argument<unknown>[], path: string, name: string): void => {
   const names = new Set<string>()
@@ -157,6 +140,9 @@ const resolveAll = <T, S>(
 class RoutesBuilder {
   readonly routes: RouteDefinition[] = []
   readonly controllers: MappedController[] = []
+  readonly gateways: BuiltGateway[] = []
+  /** Routes of the controller being added. */
+  #mapped: MappedRoute[] = []
   /** Guards, interceptors and filters created from classes, in creation order. */
   readonly enhancers: unknown[] = []
   readonly #options: ControllerRoutesOptions
@@ -174,6 +160,14 @@ class RoutesBuilder {
   }
 
   addController(entry: ControllerEntry): void {
+    const gatewayPath = getGatewayPath(entry.controller)
+
+    if (gatewayPath !== undefined) {
+      this.#addGateway(entry, gatewayPath)
+
+      return
+    }
+
     const controllerPath = getControllerPath(entry.controller)
 
     if (controllerPath === undefined) {
@@ -185,14 +179,32 @@ class RoutesBuilder {
 
     const basePath = joinPaths(this.#options.prefix ?? '', controllerPath)
 
-    const start = this.routes.length
+    this.#mapped = []
 
     // The most derived function: an override without route decorators has no metadata.
     for (const name of methodNames(entry.instance as object)) {
       this.#addMethod(entry, basePath, name)
     }
 
-    this.controllers.push({ controller: entry.controller, path: basePath, routes: this.routes.slice(start) })
+    this.controllers.push({ controller: entry.controller, path: basePath, routes: this.#mapped })
+  }
+
+  /** A gateway: its handshake gets the guards and filters of the class and the global ones. */
+  #addGateway(entry: ControllerEntry, gatewayPath: string): void {
+    const local = this.#resolverOf(entry)
+    const controller = getClassEnhancers(entry.controller)
+    const options = this.#options
+
+    this.gateways.push(
+      buildGateway({
+        entry,
+        path: joinPaths(options.prefix ?? '', gatewayPath),
+        guards: resolveAll([options.guards ?? [], controller.guards, []], this.#global.guard, local.guard),
+        filters: resolveAll([options.filters ?? [], controller.filters, []], this.#global.filter, local.filter).reverse(),
+        metadata: controller.metadata,
+        onError: this.#onError,
+      })
+    )
   }
 
   #resolverOf(entry: ControllerEntry): EnhancerResolver {
@@ -238,6 +250,9 @@ class RoutesBuilder {
         assertParamsExist(route.args, path, `${entry.controller.name}.${name}`)
       }
 
+      const status = statusOf(metadata, route)
+
+      this.#mapped.push({ info, args: route.args, status, sse: route.sse })
       this.routes.push({
         method: route.method,
         path,
@@ -248,7 +263,7 @@ class RoutesBuilder {
           interceptors,
           filters,
           invoke: createInvoker(instance, method, route.args),
-          respond: createResponder(statusOf(metadata, route), metadata.headers),
+          respond: route.sse ? createSseResponder(metadata.headers, this.#onError) : createResponder(status, metadata.headers),
           onError: this.#onError,
         }),
       })
@@ -256,14 +271,36 @@ class RoutesBuilder {
   }
 }
 
-/** A controller and the routes made from it, as `createApp` logs them at startup. */
+/** A route as declared: what startup logs and API descriptions (OpenAPI) show. */
+export interface MappedRoute {
+  /** Controller, method name, HTTP method, full path and custom metadata. */
+  readonly info: RouteInfo
+  /** Declared arguments; `undefined` when the method receives the context. */
+  readonly args: readonly Argument<unknown>[] | undefined
+  /** Status of the responses built from returned values. */
+  readonly status: number
+  /** Declared with `@Sse()`. */
+  readonly sse: boolean
+}
+
+/** A controller and the routes made from it. */
 export interface MappedController {
   readonly controller: Constructor<unknown>
   /** Path of the controller, with the global prefix. */
   readonly path: string
-  readonly routes: readonly RouteDefinition[]
+  readonly routes: readonly MappedRoute[]
 }
 
+/**
+ * The routes of the application, grouped by controller: `inject(ROUTES)`.
+ * Filled once the routes are built, so read it when serving, not in a constructor.
+ */
+export interface RouteRegistry {
+  readonly controllers: readonly MappedController[]
+}
+
+export const ROUTES = new InjectionToken<RouteRegistry>('ROUTES')
+
 /**
  * Routes of every controller, and the guards, interceptors and filters created
  * for them from classes (whose lifecycle hooks the application runs).
@@ -272,6 +309,8 @@ export interface BuiltRoutes {
   readonly routes: RouteDefinition[]
   /** In module order. */
   readonly controllers: readonly MappedController[]
+  /** WebSocket gateways, in module order. */
+  readonly gateways: readonly BuiltGateway[]
   /** In creation order. */
   readonly enhancers: readonly unknown[]
 }
@@ -286,7 +325,7 @@ export const buildRoutes = (container: Container, options: ControllerRoutesOptio
     builder.addController(entry)
   }
 
-  return { routes: builder.routes, controllers: builder.controllers, enhancers: builder.enhancers }
+  return { routes: builder.routes, controllers: builder.controllers, gateways: builder.gateways, enhancers: builder.enhancers }
 }
 
 /**

package/src/http/sse.ts

@@ -0,0 +1,120 @@
+/**
+ * @module
+ * Server-sent events: a route decorated with `@Sse()` returns an async
+ * iterable of messages, streamed as `text/event-stream`, as Nest's `@Sse()`
+ * streams an observable.
+ *
+ * ```ts
+ * @Sse('ticks')
+ * async *ticks(): AsyncGenerator<SseMessage> {
+ *   for (let i = 0; ; i++) {
+ *     yield { data: { tick: i } }
+ *     await Bun.sleep(1000)
+ *   }
+ * }
+ * ```
+ *
+ * When the client disconnects, the iterator is returned: a generator runs its
+ * `finally` blocks. An error thrown while streaming ends the stream and is logged.
+ */
+
+import type { Context } from './context.ts'
+
+/** One event. Fields are those of the `EventSource` protocol. */
+export interface SseMessage {
+  /** A string is sent as is, anything else as JSON. */
+  readonly data: unknown
+  /** Event name, listened to with `source.addEventListener(event, ...)`. */
+  readonly event?: string
+  /** Sent back by the browser as `Last-Event-ID` when it reconnects. */
+  readonly id?: string
+  /** Milliseconds the browser waits before reconnecting. */
+  readonly retry?: number
+}
+
+/** Headers of Nest's SSE responses: no caching, no buffering by nginx. */
+const SSE_HEADERS: readonly [string, string][] = [
+  ['content-type', 'text/event-stream'],
+  ['cache-control', 'private, no-cache, no-store, must-revalidate, max-age=0, no-transform'],
+  ['x-accel-buffering', 'no'],
+]
+
+const NEWLINE = /\r\n|\r|\n/
+const encoder = new TextEncoder()
+
+const assertSingleLine = (name: string, value: string): void => {
+  if (NEWLINE.test(value)) {
+    throw new TypeError(`SSE ${name} must not contain line breaks: ${JSON.stringify(value)}`)
+  }
+}
+
+/** A message in the event stream format, one `data:` line per line of data. */
+export const formatSseMessage = (message: SseMessage): string => {
+  const data = typeof message.data === 'string' ? message.data : JSON.stringify(message.data)
+  let text = ''
+
+  if (message.event !== undefined) {
+    assertSingleLine('event', message.event)
+    text += `event: ${message.event}\n`
+  }
+
+  if (message.id !== undefined) {
+    assertSingleLine('id', message.id)
+    text += `id: ${message.id}\n`
+  }
+
+  if (message.retry !== undefined) {
+    text += `retry: ${Math.trunc(message.retry)}\n`
+  }
+
+  for (const line of (data ?? '').split(NEWLINE)) {
+    text += `data: ${line}\n`
+  }
+
+  return `${text}\n`
+}
+
+const isAsyncIterable = (value: unknown): value is AsyncIterable<SseMessage> =>
+  typeof value === 'object' && value !== null && Symbol.asyncIterator in value
+
+/**
+ * Creates the function streaming what an `@Sse()` route returns. `headers`
+ * come from `@Header()`; errors while streaming go to `onError`.
+ */
+export const createSseResponder = (
+  headers: readonly [string, string][],
+  onError: (error: unknown, req: Request) => void
+): ((value: unknown, ctx: Context) => Response) => {
+  const init: ResponseInit = { status: 200, headers: [...SSE_HEADERS, ...headers] }
+
+  return (value, ctx) => {
+    if (!isAsyncIterable(value)) {
+      throw new TypeError(`${ctx.route.controller.name}.${ctx.route.handler} is an @Sse() route: it must return an async iterable`)
+    }
+
+    const iterator = value[Symbol.asyncIterator]()
+
+    const body = new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        try {
+          const next = await iterator.next()
+
+          if (next.done === true) {
+            controller.close()
+          } else {
+            controller.enqueue(encoder.encode(formatSseMessage(next.value)))
+          }
+        } catch (error) {
+          onError(error, ctx.req)
+          controller.close()
+        }
+      },
+      // The client went away: let the source clean up.
+      async cancel() {
+        await iterator.return?.()
+      },
+    })
+
+    return new Response(body, init)
+  }
+}

package/src/index.ts

@@ -37,3 +37,4 @@ export * from './di/index.ts'
 export * from './http/index.ts'
 export * from './logger/index.ts'
 export * from './routing/index.ts'
+export * from './websocket/index.ts'

package/src/openapi/decorators.ts

@@ -0,0 +1,50 @@
+/**
+ * @module
+ * Decorators describing routes in the OpenAPI document, as `@nestjs/swagger` does.
+ */
+
+import { createDecorator } from '../http/enhancers.ts'
+import type { ClassOrMethodDecorator } from '../http/enhancers.ts'
+import type { StandardSchemaV1 } from '../http/schema.ts'
+
+export interface ApiOperationOptions {
+  readonly summary?: string
+  readonly description?: string
+  readonly deprecated?: boolean
+}
+
+export interface ApiResponseOptions {
+  readonly description: string
+  /** Schema of the JSON body; needs a library implementing Standard JSON Schema, such as zod. */
+  readonly schema?: StandardSchemaV1
+}
+
+const operation = createDecorator<ApiOperationOptions>('ApiOperation')
+const tags = createDecorator<readonly string[]>('ApiTags')
+const responses = createDecorator<Readonly<Record<number, ApiResponseOptions>>>('ApiResponses')
+const bearer = createDecorator<boolean>('ApiBearerAuth')
+const exclude = createDecorator<boolean>('ApiExclude')
+
+/** Summary, description and deprecation of an operation. */
+export const ApiOperation = (options: ApiOperationOptions): ClassOrMethodDecorator => operation(options)
+
+/** Tags grouping operations, on a controller or a method (which wins). */
+export const ApiTags = (...names: string[]): ClassOrMethodDecorator => tags(names)
+
+/**
+ * Responses of an operation, by status. Without it, the operation has the
+ * status of its route (`200`, `201` for `POST`, or `@HttpCode()`).
+ *
+ * ```ts
+ * @ApiResponses({ 200: { description: 'The user', schema: User }, 404: { description: 'No such user' } })
+ * ```
+ */
+export const ApiResponses = (byStatus: Readonly<Record<number, ApiResponseOptions>>): ClassOrMethodDecorator => responses(byStatus)
+
+/** Operations need `Authorization: Bearer <token>`, as `JwtGuard` reads. */
+export const ApiBearerAuth = (): ClassOrMethodDecorator => bearer(true)
+
+/** Leaves a controller or a method out of the document. */
+export const ApiExclude = (): ClassOrMethodDecorator => exclude(true)
+
+export const KEYS = { operation: operation.key, tags: tags.key, responses: responses.key, bearer: bearer.key, exclude: exclude.key } as const

package/src/openapi/document.ts

@@ -0,0 +1,221 @@
+/**
+ * @module
+ * Building an OpenAPI 3.1 document from the routes of an application.
+ *
+ * Schemas come from what validates requests: argument parsers (`int()`,
+ * `uuid()`...) and Standard Schemas implementing Standard JSON Schema, as zod
+ * does. Paths with optional parameters give one path per form, as OpenAPI has
+ * no optional path parameters; `@All()` routes are left out, OpenAPI has no
+ * such method.
+ */
+
+import type { Argument } from '../http/arguments.ts'
+import type { Parser } from '../http/parsers.ts'
+import type { MappedController, MappedRoute } from '../http/routes.ts'
+import { isStandardSchema } from '../http/schema.ts'
+import type { StandardSchemaV1 } from '../http/schema.ts'
+import { expandOptional, parsePath } from '../routing/path.ts'
+import type { Segment } from '../routing/path.ts'
+import { KEYS } from './decorators.ts'
+import type { ApiOperationOptions, ApiResponseOptions } from './decorators.ts'
+
+export type JsonSchema = Readonly<Record<string, unknown>>
+
+export interface OpenApiOptions {
+  readonly info: { readonly title: string; readonly version: string; readonly description?: string }
+  readonly servers?: readonly { readonly url: string; readonly description?: string }[]
+}
+
+export interface OpenApiParameter {
+  readonly name: string
+  readonly in: 'path' | 'query' | 'header' | 'cookie'
+  readonly required: boolean
+  readonly schema: JsonSchema
+}
+
+export interface OpenApiOperation {
+  readonly operationId: string
+  readonly summary?: string
+  readonly description?: string
+  readonly deprecated?: boolean
+  readonly tags?: readonly string[]
+  readonly parameters?: readonly OpenApiParameter[]
+  readonly requestBody?: { readonly required: boolean; readonly content: Readonly<Record<string, { readonly schema: JsonSchema }>> }
+  readonly responses: Readonly<Record<string, { readonly description: string; readonly content?: Readonly<Record<string, { readonly schema: JsonSchema }>> }>>
+  readonly security?: readonly Readonly<Record<string, readonly string[]>>[]
+}
+
+export interface OpenApiDocument {
+  readonly openapi: '3.1.0'
+  readonly info: OpenApiOptions['info']
+  readonly servers?: OpenApiOptions['servers']
+  readonly paths: Readonly<Record<string, Readonly<Record<string, OpenApiOperation>>>>
+  readonly components?: { readonly securitySchemes: Readonly<Record<string, JsonSchema>> }
+}
+
+const METHODS = new Set(['GET', 'PUT', 'POST', 'DELETE', 'OPTIONS', 'HEAD', 'PATCH', 'TRACE'])
+const IN = { query: 'query', header: 'header', cookie: 'cookie' } as const
+const STRING: JsonSchema = { type: 'string' }
+const FORM_TYPES = ['multipart/form-data', 'application/x-www-form-urlencoded']
+
+/** Standard JSON Schema: the part of `~standard` a schema library may add. */
+interface WithJsonSchema {
+  readonly '~standard': { readonly jsonSchema?: { readonly input: (options: { readonly target: string }) => Record<string, unknown> } }
+}
+
+/** JSON Schema of what a parser or schema accepts, `{}` when it cannot tell. */
+const toJsonSchema = (source: Argument<unknown>['source']): JsonSchema => {
+  if (source === undefined) {
+    return STRING
+  }
+
+  if (!isStandardSchema(source)) {
+    return (source as Parser<unknown>).jsonSchema ?? STRING
+  }
+
+  const converter = (source as WithJsonSchema)['~standard'].jsonSchema
+
+  if (converter === undefined) {
+    return {}
+  }
+
+  const { $schema: _, ...schema } = converter.input({ target: 'draft-2020-12' })
+
+  return schema
+}
+
+/** A value may be missing when its parser says so, or its schema accepts `undefined`. */
+const isOptional = (source: Argument<unknown>['source']): boolean => {
+  if (source === undefined) {
+    return true
+  }
+
+  if (!isStandardSchema(source)) {
+    return (source as Parser<unknown>).optional === true
+  }
+
+  const result = (source as StandardSchemaV1)['~standard'].validate(undefined)
+
+  return !(result instanceof Promise) && result.issues === undefined
+}
+
+const toOpenApiPath = (segments: readonly Segment[]): string =>
+  `/${segments
+    .map((segment) =>
+      segment.type === 'static' ? decodeURIComponent(segment.value) : `{${segment.type === 'param' ? segment.name : (segment.name ?? 'wildcard')}}`
+    )
+    .join('/')}`
+
+const pathParameters = (segments: readonly Segment[], args: readonly Argument<unknown>[]): OpenApiParameter[] => {
+  const parameters: OpenApiParameter[] = []
+
+  for (const segment of segments) {
+    if (segment.type === 'static') {
+      continue
+    }
+
+    const name = segment.type === 'param' ? segment.name : (segment.name ?? 'wildcard')
+    const declared = args.find((arg) => arg.kind === 'param' && arg.name === name)
+    const pattern = segment.type === 'param' && segment.pattern !== undefined ? { pattern: `^(?:${segment.pattern})$` } : {}
+
+    parameters.push({ name, in: 'path', required: true, schema: { ...toJsonSchema(declared?.source), ...pattern } })
+  }
+
+  return parameters
+}
+
+const requestBody = (args: readonly Argument<unknown>[]): OpenApiOperation['requestBody'] => {
+  const body = args.find((arg) => arg.kind === 'body')
+
+  if (body === undefined) {
+    return undefined
+  }
+
+  const schema = body.source === undefined ? {} : toJsonSchema(body.source)
+  const types = body.multipart === true ? FORM_TYPES : ['application/json']
+
+  return { required: !isOptional(body.source), content: Object.fromEntries(types.map((type) => [type, { schema }])) }
+}
+
+const responsesOf = (route: MappedRoute): OpenApiOperation['responses'] => {
+  const declared = route.info.metadata.get(KEYS.responses) as Readonly<Record<number, ApiResponseOptions>> | undefined
+
+  if (declared === undefined) {
+    return route.sse
+      ? { 200: { description: 'Event stream', content: { 'text/event-stream': { schema: STRING } } } }
+      : { [route.status]: { description: 'Success' } }
+  }
+
+  return Object.fromEntries(
+    Object.entries(declared).map(([status, response]) => [
+      status,
+      response.schema === undefined
+        ? { description: response.description }
+        : { description: response.description, content: { 'application/json': { schema: toJsonSchema(response.schema) } } },
+    ])
+  )
+}
+
+const operationOf = (route: MappedRoute, segments: readonly Segment[], suffix: string): OpenApiOperation => {
+  const { info } = route
+  const args = route.args ?? []
+  const parameters = pathParameters(segments, args)
+
+  for (const arg of args) {
+    if (arg.kind === 'query' || arg.kind === 'header' || arg.kind === 'cookie') {
+      parameters.push({ name: arg.name, in: IN[arg.kind], required: !isOptional(arg.source), schema: toJsonSchema(arg.source) })
+    }
+  }
+
+  const options = (info.metadata.get(KEYS.operation) as ApiOperationOptions | undefined) ?? {}
+  const tags = info.metadata.get(KEYS.tags) as readonly string[] | undefined
+  const body = requestBody(args)
+
+  return {
+    operationId: `${info.controller.name}_${info.handler}${suffix}`,
+    ...options,
+    ...(tags === undefined ? {} : { tags }),
+    ...(parameters.length === 0 ? {} : { parameters }),
+    ...(body === undefined ? {} : { requestBody: body }),
+    responses: responsesOf(route),
+    ...(info.metadata.get(KEYS.bearer) === true ? { security: [{ bearer: [] }] } : {}),
+  }
+}
+
+/** Adds the operations of `route` to `paths`, one per form of its path; `false` when it is left out. */
+const addRoute = (paths: Record<string, Record<string, OpenApiOperation>>, route: MappedRoute): boolean => {
+  const { info } = route
+
+  if (!METHODS.has(info.method) || info.metadata.get(KEYS.exclude) === true) {
+    return false
+  }
+
+  for (const [index, segments] of expandOptional(info.path, parsePath(info.path)).entries()) {
+    const path = toOpenApiPath(segments)
+
+    paths[path] ??= {}
+    paths[path][info.method.toLowerCase()] = operationOf(route, segments, index === 0 ? '' : `_${index}`)
+  }
+
+  return true
+}
+
+/** The OpenAPI document of `controllers`, as `inject(ROUTES).controllers` lists them. */
+export const createOpenApiDocument = (controllers: readonly MappedController[], options: OpenApiOptions): OpenApiDocument => {
+  const paths: Record<string, Record<string, OpenApiOperation>> = {}
+  let bearer = false
+
+  for (const controller of controllers) {
+    for (const route of controller.routes) {
+      bearer = (addRoute(paths, route) && route.info.metadata.get(KEYS.bearer) === true) || bearer
+    }
+  }
+
+  return {
+    openapi: '3.1.0',
+    info: options.info,
+    ...(options.servers === undefined ? {} : { servers: options.servers }),
+    paths,
+    ...(bearer ? { components: { securitySchemes: { bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } } } } : {}),
+  }
+}

package/src/openapi/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @module
+ * OpenAPI documents of an application, and a Swagger UI page, as `@nestjs/swagger`.
+ */
+
+export { ApiBearerAuth, ApiExclude, ApiOperation, ApiResponses, ApiTags } from './decorators.ts'
+export type { ApiOperationOptions, ApiResponseOptions } from './decorators.ts'
+export { createOpenApiDocument } from './document.ts'
+export type { JsonSchema, OpenApiDocument, OpenApiOperation, OpenApiOptions, OpenApiParameter } from './document.ts'
+export { OpenApiModule } from './module.ts'
+export type { OpenApiModuleOptions } from './module.ts'

package/src/openapi/module.ts

@@ -0,0 +1,95 @@
+/**
+ * @module
+ * `OpenApiModule`: serves the OpenAPI document of the application, and a
+ * Swagger UI page, as `SwaggerModule.setup()` of `@nestjs/swagger` does.
+ */
+
+import { inject, Module } from '../di/index.ts'
+import type { DynamicModule } from '../di/index.ts'
+import { Controller, Get } from '../http/decorators.ts'
+import { ROUTES } from '../http/routes.ts'
+import { ApiExclude } from './decorators.ts'
+import { createOpenApiDocument } from './document.ts'
+import type { OpenApiDocument, OpenApiOptions } from './document.ts'
+
+export interface OpenApiModuleOptions extends OpenApiOptions {
+  /** Path of the JSON document. Defaults to `/openapi.json`. */
+  readonly path?: string
+  /** Path of a Swagger UI page reading the document, such as `/docs`. None by default. */
+  readonly ui?: string
+}
+
+/** Swagger UI, from a CDN at a fixed version. */
+const SWAGGER_UI = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.34.0'
+
+const page = (title: string, documentUrl: string): string => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${Bun.escapeHTML(title)}</title>
+<link rel="stylesheet" href="${SWAGGER_UI}/swagger-ui.css">
+</head>
+<body>
+<div id="docs"></div>
+<script src="${SWAGGER_UI}/swagger-ui-bundle.js" crossorigin></script>
+<script>SwaggerUIBundle({ url: ${JSON.stringify(documentUrl)}, dom_id: '#docs' })</script>
+</body>
+</html>
+`
+
+/**
+ * ```ts
+ * @Module({ imports: [OpenApiModule.forRoot({ info: { title: 'Shop', version: '1.0.0' }, ui: '/docs' })] })
+ * class AppModule {}
+ * ```
+ *
+ * The document is built on the first request, from every route of the
+ * application (these two excepted), and kept.
+ */
+@Module({})
+export class OpenApiModule {
+  static forRoot(options: OpenApiModuleOptions): DynamicModule {
+    const documentPath = options.path ?? '/openapi.json'
+
+    @Controller()
+    @ApiExclude()
+    class OpenApiController {
+      readonly #routes = inject(ROUTES)
+      #document: OpenApiDocument | undefined
+
+      @Get(documentPath)
+      document(): OpenApiDocument {
+        this.#document ??= createOpenApiDocument(this.#routes.controllers, options)
+
+        return this.#document
+      }
+    }
+
+    const controllers: (new () => unknown)[] = [OpenApiController]
+
+    if (options.ui !== undefined) {
+      const ui = options.ui
+
+      @Controller()
+      @ApiExclude()
+      class OpenApiUiController {
+        readonly #routes = inject(ROUTES)
+
+        @Get(ui)
+        page(): Response {
+          // The document's own path, global prefix included.
+          const documentUrl = this.#routes.controllers.find((mapped) => mapped.controller === OpenApiController)?.routes[0]?.info.path
+
+          return new Response(page(options.info.title, documentUrl ?? documentPath), {
+            headers: { 'content-type': 'text/html;charset=utf-8' },
+          })
+        }
+      }
+
+      controllers.push(OpenApiUiController)
+    }
+
+    return { module: OpenApiModule, controllers }
+  }
+}