@znight/http 0.5.1 → 0.6.1

package/src/plugin.ts

@@ -25,10 +25,13 @@ import type { CollectedPluginRoute } from './plugin-routes.ts'
 import type { TrustPolicy, TrustProxy } from './proxy.ts'
 import type { SecurityHeadersOptions } from './security-headers.ts'
 import type { ByteSize } from './size.ts'
+import type { CollectedUpgradeRoute, MemoryUpgrade } from './upgrade.ts'
 
 import { displayName, ErrorCode, resolveOptions, ZnightError } from '@znight/core'
 
 import { nodeAdapter } from './adapters/node.ts'
+import { injectResponse, normalizeInject } from './adapters/shared.ts'
+import { MemoryUpgradeRequest, replyBytes } from './adapters/upgrade-io.ts'
 import { DEFAULT_COOKIE_SETTINGS, missingSecrets, signValue } from './cookie-settings.ts'
 import { type CookieSecret, CookieSigner, checkSecrets } from './cookie-signer.ts'
 import { DEFAULT_COOKIE_OPTIONS, decodeCookieValue, isCookieName, serializeResponseCookie } from './cookies.ts'
@@ -43,6 +46,7 @@ import {
   RouteGroups,
   type RouteMeta,
 } from './decisions.ts'
+import { HttpException, ServiceUnavailableException } from './exceptions.ts'
 import { isHeaderName } from './headers.ts'
 import { openInjectSse } from './inject-sse.ts'
 import { isMediaTypePattern } from './mime.ts'
@@ -51,10 +55,12 @@ import { compareRoutePaths, compareStrings, joinPaths, parseRoutePath, type Rout
 import {
   DEFAULT_SSE_SETTINGS,
   Pipeline,
+  pendingUpgradeOf,
   type Resolvable,
   type RoutePlan,
   randomRequestId,
   type SseSettings,
+  type UpgradePlan,
 } from './pipeline.ts'
 import { collectPluginRoutes, drainPlugins } from './plugin-routes.ts'
 import { resolveTrustProxy } from './proxy.ts'
@@ -64,6 +70,7 @@ import { parseByteSize } from './size.ts'
 import { MAX_SSE_TIMER_MS, MIN_SSE_INTERVAL_MS } from './sse.ts'
 import { isValidStatus } from './status.ts'
 import { HttpTokens } from './tokens.ts'
+import { checkHandshake, collectPluginUpgrades } from './upgrade.ts'
 import { bodyPlan, DEFAULT_UPLOAD_LIMITS, type ResolvedUploadLimits, type UploadLimits } from './uploads.ts'
 
 /** How requests whose path ends with an extra `/` are handled. */
@@ -197,6 +204,8 @@ export interface HttpRouteSummary {
   readonly meta: Readonly<Record<string, unknown>>
   /** Display names of the guards, in chain order (global, controller, route). */
   readonly guards: readonly string[]
+  /** `'websocket'` for a WebSocket upgrade route (RFC 0003): a gateway of `@znight/websocket`. */
+  readonly upgrade?: 'websocket'
 }
 
 interface Resolved {
@@ -236,6 +245,8 @@ interface Registration {
   readonly method: Exclude<HttpMethod, 'ALL'>
   readonly path: RoutePath
   readonly plan: RoutePlan
+  /** An upgrade route (RFC 0003): registered in the upgrade table, not on the adapter. */
+  readonly upgrade?: UpgradePlan
   /** `BookController.list`, `plugin "openapi" (document)`. */
   readonly label: string
   readonly source: string
@@ -451,6 +462,29 @@ export class HttpPlugin implements Plugin {
     return openInjectSse(stream => this.injectStream(stream), request)
   }
 
+  /**
+   * Runs a WebSocket handshake in memory (RFC 0003, `WebSocketPlugin.connect()`): the same pipeline
+   * as an upgrade request of the adapter (guards, hooks, the route's checks), without socket. The
+   * transport receives `{ kind: 'memory', peer }`. Resolves with the refusal, or `undefined` once
+   * the connection was accepted. Available after `onBootstrap`.
+   */
+  async upgradeInMemory(request: InjectRequest, native: MemoryUpgrade): Promise<InjectResponse | undefined> {
+    const runtime = this.#require('upgradeInMemory()')
+    const normalized = await normalizeInject(withSignedCookies(request, runtime.options.cookies, 'upgradeInMemory()'))
+    const headers = normalized.headers
+    headers['upgrade'] ??= 'websocket'
+    headers['connection'] ??= 'Upgrade'
+    headers['sec-websocket-version'] ??= '13'
+    headers['sec-websocket-key'] ??= btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(16))))
+    headers['host'] ??= 'localhost'
+    const reply = await runtime.pipeline.upgrade(
+      new MemoryUpgradeRequest(normalized.method, normalized.url, headers),
+      native,
+    )
+    if (reply === undefined) return undefined
+    return injectResponse(reply.status, reply.headers, await replyBytes(reply))
+  }
+
   register(ctx: PluginContext): void {
     if (this.#active) {
       throw new ZnightError(ErrorCode.DuplicateProvider, 'This HttpPlugin is already used by another application', {
@@ -504,17 +538,40 @@ export class HttpPlugin implements Plugin {
       },
       table,
     )
-    const pluginRoutes = collectPluginRoutes(ctx.app.plugins, this, {
-      prefix: options.prefix === '/' ? '' : options.prefix,
+    const prefix = options.prefix === '/' ? '' : options.prefix
+    const pluginRoutes = collectPluginRoutes(ctx.app.plugins, this, { prefix, container: ctx.container })
+    const support = options.adapter.upgrades
+    const upgrades = collectPluginUpgrades(ctx.app.plugins, this, {
+      prefix,
       container: ctx.container,
+      adapter: options.adapter.name,
+      upgrades: support?.kind,
     })
-    const { registrations, checked } = buildRegistrations(ctx, options, raw, pluginRoutes)
+    const { registrations, checked } = buildRegistrations(ctx, options, raw, pluginRoutes, upgrades.routes, pipeline)
     checkDecisions(checked.routes, checked.groups, options.enforcement, ctx.logger, checked.enforcers)
     const adapter = options.adapter
     const routes: HttpRouteSummary[] = []
+    let upgradeTable: RouteTable<UpgradePlan> | undefined
     for (const registration of registrations) {
-      table.add(registration.method, registration.path, registration.plan)
       const plan = registration.plan
+      if (registration.upgrade !== undefined) {
+        upgradeTable ??= new RouteTable<UpgradePlan>()
+        upgradeTable.add('GET', registration.path, registration.upgrade)
+        routes.push(
+          Object.freeze({
+            method: 'GET',
+            path: registration.path.path,
+            controller: displayName(plan.info.controller),
+            handler: plan.info.handler,
+            source: registration.source,
+            meta: plan.info.meta,
+            guards: registration.guards,
+            upgrade: 'websocket' as const,
+          }),
+        )
+        continue
+      }
+      table.add(registration.method, registration.path, registration.plan)
       adapter.registerRoute({
         method: registration.method,
         path: registration.path,
@@ -533,6 +590,22 @@ export class HttpPlugin implements Plugin {
       )
     }
     adapter.setFallbackHandler((request, error) => pipeline.fallback(request, error))
+    if (upgradeTable !== undefined) {
+      if (support === undefined) {
+        throw new ZnightError(
+          ErrorCode.WebSocketTransportUnavailable,
+          `HttpPlugin: the ${adapter.name} adapter cannot serve WebSocket upgrade routes`,
+          { hints: ['Use a built-in adapter (node, fastify, express, hono) or implement HttpAdapter.upgrades'] },
+        )
+      }
+      const found = upgradeTable
+      pipeline.upgrades = found
+      support.enable({
+        match: path => found.find('GET', path) !== undefined,
+        handle: (request, native) => pipeline.upgrade(request, native),
+        bunWebSocket: upgrades.bunWebSocket,
+      })
+    }
     this.#runtime = { adapter, pipeline, options, routes: Object.freeze(routes) }
   }
 
@@ -882,6 +955,8 @@ interface Declared {
   readonly guards: readonly GuardEntry[]
   /** Effective metadata (available once every group is known). */
   meta(): RouteMeta
+  /** An upgrade route (RFC 0003): its handshake time limit. */
+  readonly upgrade?: { readonly timeoutMs: number | undefined }
 }
 
 function buildRegistrations(
@@ -889,6 +964,8 @@ function buildRegistrations(
   options: Resolved,
   raw: HttpPluginOptions,
   pluginRoutes: readonly CollectedPluginRoute[],
+  upgradeRoutes: readonly CollectedUpgradeRoute[],
+  pipeline: Pipeline,
 ): { readonly registrations: Registration[]; readonly checked: Checked } {
   const { container, metadata } = ctx
   const http = httpMetadata(metadata)
@@ -1071,6 +1148,91 @@ function buildRegistrations(
     })
   }
 
+  for (const route of upgradeRoutes) {
+    const label = `plugin "${route.plugin}" (${route.name})`
+    const where = `${route.path.path} (${route.name})`
+    const invalidGuard = (ref: unknown): ZnightError =>
+      new ZnightError(
+        ErrorCode.InvalidRoute,
+        `HttpPlugin: plugin "${route.plugin}": the guards of the upgrade route ${where} must be provider tokens, classes or objects with a canActivate() method (received ${describeValue(ref)})`,
+      )
+    const guards = [
+      ...globalGuards,
+      ...route.guards.map(ref =>
+        typeof ref === 'string'
+          ? compiledGuard(ref, `guard of ${where}`)
+          : (guardEntries(container, metadata, [ref], invalidGuard)[0] as GuardEntry),
+      ),
+    ]
+    const values: Record<string, unknown> = {}
+    for (const entry of route.meta) {
+      groups.declare(entry, `the plugin "${route.plugin}"`)
+      values[entry.key] = entry.value
+    }
+    const meta: RouteMeta = Object.freeze(values)
+    pending.push(() => checkTargetMeta(meta, groupOf, `the upgrade route ${where} of the plugin "${route.plugin}"`))
+    const accept = route.accept
+    const precheck = route.precheck
+    // the protocol checks, the drain and the route's own checks run before the global guards
+    const checks: CanActivate = {
+      canActivate: (ctx: HttpContext): boolean | Promise<boolean> => {
+        checkHandshake(ctx)
+        if (pipeline.draining) {
+          throw new ServiceUnavailableException('The server is shutting down', undefined, {
+            headers: { 'retry-after': '1' },
+          })
+        }
+        if (precheck === undefined) return true
+        const done = precheck(ctx)
+        return done instanceof Promise ? done.then(() => true) : true
+      },
+    }
+    const definition: HttpRouteDefinition = Object.freeze({
+      method: 'GET',
+      path: route.relativePath,
+      fullPath: route.relativePath,
+      handler: route.name,
+      meta,
+      guards: [],
+      interceptors: [],
+      params: [],
+      rawResponse: true,
+      invoke: async (_plugin: unknown, http: HttpContext): Promise<undefined> => {
+        const upgrade = pendingUpgradeOf(http)
+        if (upgrade === undefined) throw new Error(`The upgrade route ${where} only serves upgrade requests`)
+        // answered 408 already: the late handshake is not completed
+        if (upgrade.expired) throw handshakeExpired()
+        await accept(http, upgrade)
+        if (!upgrade.accepted) throw new Error(`accept() of the upgrade route ${where} did not take the connection`)
+        return undefined
+      },
+    })
+    const instance: Resolvable<object> = { instance: route.instance }
+    const chain = [{ instance: checks }, ...guards.map(guard => guard.resolvable)]
+    const body = bodyPlan({}, options.bodyLimit, options.uploads)
+    const path = route.path
+    declared.push({
+      method: 'GET',
+      path,
+      plan: (method: string): RoutePlan => ({
+        definition,
+        invoke: definition.invoke,
+        path,
+        info: Object.freeze({ method, path: path.path, controller: route.owner, handler: route.name, meta }),
+        controller: instance,
+        guards: chain,
+        interceptors: [],
+        parseBody: false,
+        body,
+      }),
+      label,
+      source: route.plugin,
+      guards,
+      meta: () => meta,
+      upgrade: { timeoutMs: route.timeoutMs },
+    })
+  }
+
   // `enforces` of every guard class, read once per class. The guards of the chains declare their
   // groups; the guard classes of the application that sit in no chain only make their groups known,
   // so that a decision whose guard was forgotten everywhere (a second entrypoint, a worker, a test)
@@ -1108,18 +1270,30 @@ function buildRegistrations(
     }
   })
 
-  const registration = (route: Declared, method: Exclude<HttpMethod, 'ALL'>): Registration => ({
-    method,
-    path: route.path,
-    plan: route.plan(method),
-    label: route.label,
-    source: route.source,
-    guards: Object.freeze(route.guards.map(guard => guard.name)),
-  })
+  const registration = (route: Declared, method: Exclude<HttpMethod, 'ALL'>): Registration => {
+    const plan = route.plan(method)
+    return {
+      method,
+      path: route.path,
+      plan,
+      label: route.label,
+      source: route.source,
+      guards: Object.freeze(route.guards.map(guard => guard.name)),
+      ...(route.upgrade === undefined ? {} : { upgrade: { plan, timeoutMs: route.upgrade.timeoutMs } }),
+    }
+  }
   const explicit: Registration[] = []
   const catchAll: Declared[] = []
+  // upgrade routes have their own table: a page and its socket may share a path
+  const upgradeTable = new RouteTable<Registration>()
+  const upgrades: Registration[] = []
   for (const route of declared) {
-    if (route.method === 'ALL') catchAll.push(route)
+    if (route.upgrade !== undefined) {
+      const candidate = registration(route, 'GET')
+      const existing = upgradeTable.add('GET', candidate.path, candidate)
+      if (existing !== undefined) throw duplicateRoute(candidate, existing)
+      upgrades.push(candidate)
+    } else if (route.method === 'ALL') catchAll.push(route)
     else explicit.push(registration(route, route.method))
   }
 
@@ -1144,7 +1318,8 @@ function buildRegistrations(
     for (const method of CONCRETE_METHODS) add(method === 'GET' ? first : registration(route, method), false)
   }
 
-  // trailing-slash variants
+  // trailing-slash variants (an upgrade route never redirects: WebSocket clients do not follow redirects)
+  accepted.push(...upgrades)
   const result: Registration[] = [...accepted]
   if (options.trailingSlash !== 'strict') {
     for (const candidate of accepted) {
@@ -1158,10 +1333,11 @@ function buildRegistrations(
         shape: `${path.shape}/`,
       }
       const plan: RoutePlan =
-        options.trailingSlash === 'redirect'
+        options.trailingSlash === 'redirect' && candidate.upgrade === undefined
           ? { ...candidate.plan, path: variant, redirect: true }
           : { ...candidate.plan, path: variant }
-      result.push({ ...candidate, path: variant, plan })
+      const upgrade = candidate.upgrade === undefined ? {} : { upgrade: { ...candidate.upgrade, plan } }
+      result.push({ ...candidate, path: variant, plan, ...upgrade })
     }
   }
 
@@ -1478,3 +1654,8 @@ function resolveRef<T>(
   }
   throw invalid()
 }
+
+/** A handshake completed after its `408`: refused quietly (a 4xx is not logged as a server error). */
+function handshakeExpired(): HttpException {
+  return new HttpException(408, 'WebSocket handshake timed out')
+}

package/src/upgrade.ts

@@ -0,0 +1,341 @@
+/**
+ * Upgrade routes (RFC 0003 §8.2): WebSocket handshakes served by `HttpPlugin` on behalf of another
+ * plugin (`@znight/websocket`). The handshake is an HTTP request: it runs through the pipeline
+ * (`http:request` hook, request scope, global guards, the route's guards, exception mappers), then
+ * the plugin's `accept` takes the connection. The request scope stays open until the connection
+ * closes.
+ *
+ * Upgrade routes live in their own route table, consulted only for upgrade requests: they never
+ * change the ordinary routing, and a page and its socket may share a path.
+ */
+import type { Token } from '@znight/core'
+import type { AdapterReply, AdapterRequest } from './adapter.ts'
+import type { HttpContext } from './context.ts'
+import type { RouteMetaEntry } from './decorators.ts'
+import type { HeaderValue } from './exceptions.ts'
+import type { GuardRef } from './plugin.ts'
+import type { NormalizedMetaEntry, PluginHttpRoutesContext } from './plugin-routes.ts'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+
+import { isGroupOf } from './decorators.ts'
+import { BadRequestException, HttpException } from './exceptions.ts'
+import { joinPaths, normalizePath, parseRoutePath, type RoutePath, RoutePathError } from './path.ts'
+
+/**
+ * The upgrade of a `node:http` server (`'upgrade'` event): every adapter built on `node:http`
+ * (`node`, `express`, `fastify`, `hono` on Node.js), on Node.js and on Bun.
+ */
+export interface NodeUpgrade {
+  readonly kind: 'node'
+  /** The `IncomingMessage` of the handshake. */
+  readonly request: unknown
+  /** The `net.Socket` (a `Duplex`) of the connection. */
+  readonly socket: unknown
+  /** The first bytes after the handshake headers. */
+  readonly head: Uint8Array
+}
+
+/** The upgrade of a `Bun.serve()` server (`honoAdapter()` on Bun). */
+export interface BunUpgrade {
+  readonly kind: 'bun'
+  /** The Fetch `Request` of the handshake. */
+  readonly request: Request
+  /** The `Bun.serve()` server (`server.upgrade(request, { data, headers })`). */
+  readonly server: unknown
+}
+
+/** An in-memory upgrade (`HttpPlugin.upgradeInMemory()`, tests): `peer` belongs to the caller. */
+export interface MemoryUpgrade {
+  readonly kind: 'memory'
+  readonly peer: unknown
+}
+
+/** The native side of an upgrade request, completed by a transport. */
+export type NativeUpgrade = NodeUpgrade | BunUpgrade | MemoryUpgrade
+
+/** What {@link PluginUpgradeRoute.accept} receives to complete the handshake. */
+export interface PendingUpgrade {
+  readonly native: NativeUpgrade
+  /**
+   * Headers of the `101` response: the headers and cookies the guards set on the context, the
+   * request id and the security headers are not included (they are HTTP response headers); read
+   * once, when the transport completes the handshake.
+   */
+  readonly headers: Readonly<Record<string, HeaderValue>>
+  /**
+   * The handshake timed out and was answered `408`: the transport must not complete it. Check it
+   * after every `await`, right before completing the handshake.
+   */
+  readonly expired: boolean
+  /**
+   * Keeps the request scope (and the in-flight count of `HttpPlugin`) open until `closed`
+   * settles: the connection lives in the scope of its handshake. Call it once, after the transport
+   * completed the handshake.
+   */
+  hold(closed: Promise<unknown>): void
+}
+
+/**
+ * A route answering upgrade requests (`GET` with `upgrade: websocket`), declared by another plugin
+ * through {@link PluginHttpUpgrades.httpUpgrades}.
+ */
+export interface PluginUpgradeRoute {
+  /** Path relative to the `HttpPlugin` prefix, with the route grammar (`/chat`, `/docs/:docId`). */
+  readonly path: string
+  /** Name of the route (the gateway), shown in `HttpPlugin.routes`, logs and errors. */
+  readonly name: string
+  /** `ctx.route.controller` during the handshake (the gateway token). Default: the plugin name. */
+  readonly owner?: Token
+  /** Route metadata (`ctx.route.meta`), one entry per group, checked at boot like plugin routes. */
+  readonly meta?: readonly RouteMetaEntry[]
+  /** Guards of the handshake (classes, instances or provider tokens), after the global guards. */
+  readonly guards?: readonly (GuardRef | Token)[]
+  /** Time the handshake gets before it is answered `408` (ms). Default: none. */
+  readonly timeoutMs?: number
+  /**
+   * Cheap checks before the guards (origin, subprotocols, capacity), after the protocol checks of
+   * RFC 6455. Throw an `HttpException` to refuse.
+   */
+  precheck?(ctx: HttpContext): void | Promise<void>
+  /** After the guards: take the connection. Throw an `HttpException` to refuse. */
+  accept(ctx: HttpContext, upgrade: PendingUpgrade): void | Promise<void>
+}
+
+/** What {@link PluginHttpUpgrades.httpUpgrades} returns. */
+export interface PluginUpgrades {
+  readonly routes: readonly PluginUpgradeRoute[]
+  /**
+   * Server-wide settings of the `websocket` option of `Bun.serve()` (`maxPayloadLength`,
+   * `idleTimeout`, `backpressureLimit`, `sendPings`, `perMessageDeflate`...), used by adapters
+   * serving with `Bun.serve()`. The handlers are set by `HttpPlugin`: they dispatch every event to
+   * the `data` given to `server.upgrade()`, a {@link BunSocketHandlers}.
+   */
+  readonly bunWebSocket?: Readonly<Record<string, unknown>>
+}
+
+/** What {@link PluginHttpUpgrades.httpUpgrades} receives. */
+export interface PluginHttpUpgradesContext extends PluginHttpRoutesContext {
+  /** Name of the adapter (`node`, `fastify`...). */
+  readonly adapter: string
+  /**
+   * The native upgrades the adapter produces (`node`: a `node:http` server, `bun`: `Bun.serve()`),
+   * `undefined` when the adapter cannot upgrade connections.
+   */
+  readonly upgrades: 'node' | 'bun' | undefined
+}
+
+/**
+ * Implemented, next to {@link PluginHttpRoutes}, by a plugin that accepts WebSocket connections
+ * (`@znight/websocket`). `HttpPlugin` calls `httpUpgrades()` once in its `onBootstrap`, after
+ * `httpRoutes()`, whatever the plugin order, and asks its adapter to route the matching upgrade
+ * requests to the pipeline. `onHttpDrain()` is where the plugin closes its connections.
+ */
+export interface PluginHttpUpgrades {
+  httpUpgrades(context: PluginHttpUpgradesContext): PluginUpgrades
+}
+
+/**
+ * The `data` a transport gives to `server.upgrade()` on `Bun.serve()`: `HttpPlugin` dispatches
+ * every event of the socket to it.
+ */
+export interface BunSocketHandlers {
+  open(ws: unknown): void
+  message(ws: unknown, message: string | Uint8Array): void
+  close(ws: unknown, code: number, reason: string): void
+  drain(ws: unknown): void
+  pong?(ws: unknown): void
+}
+
+/** What `HttpPlugin` gives to {@link AdapterUpgrades.enable}. */
+export interface UpgradeHandlerOptions {
+  /** Whether an upgrade request to the raw `path` (no query string) is for Znight. */
+  match(path: string): boolean
+  /**
+   * Runs the handshake through the pipeline. Resolves with the refusal to write (an HTTP response),
+   * or `undefined` once the transport took the connection. Never rejects.
+   */
+  handle(request: AdapterRequest, native: NodeUpgrade | BunUpgrade): Promise<AdapterReply | undefined>
+  /** The `websocket` option of `Bun.serve()` (settings and dispatching handlers), Bun adapters only. */
+  readonly bunWebSocket: Readonly<Record<string, unknown>>
+}
+
+/** The optional upgrade capability of an adapter (RFC 0003 §8.2.3). */
+export interface AdapterUpgrades {
+  /** The native upgrades the adapter produces. */
+  readonly kind: 'node' | 'bun'
+  /** Called once, before `listen()`, when the application has upgrade routes. */
+  enable(options: UpgradeHandlerOptions): void
+}
+
+/** A validated upgrade route (internal). */
+export interface CollectedUpgradeRoute {
+  readonly plugin: string
+  readonly instance: object
+  readonly path: RoutePath
+  readonly relativePath: string
+  readonly name: string
+  readonly owner: Token
+  readonly meta: readonly NormalizedMetaEntry[]
+  readonly guards: readonly unknown[]
+  readonly timeoutMs: number | undefined
+  readonly precheck: ((ctx: HttpContext) => void | Promise<void>) | undefined
+  readonly accept: (ctx: HttpContext, upgrade: PendingUpgrade) => void | Promise<void>
+}
+
+/** The upgrade routes of the plugins and the merged `Bun.serve()` settings (internal). */
+export interface CollectedUpgrades {
+  readonly routes: readonly CollectedUpgradeRoute[]
+  readonly bunWebSocket: Readonly<Record<string, unknown>>
+}
+
+/** Calls `httpUpgrades()` on every other plugin implementing it, in plugin order, and validates the routes. */
+export function collectPluginUpgrades(
+  plugins: readonly object[],
+  self: object,
+  context: PluginHttpUpgradesContext,
+): CollectedUpgrades {
+  const routes: CollectedUpgradeRoute[] = []
+  const bunWebSocket: Record<string, unknown> = {}
+  for (const plugin of plugins) {
+    if (plugin === self) continue
+    const provider = plugin as Partial<PluginHttpUpgrades> & { readonly name?: unknown }
+    if (typeof provider.httpUpgrades !== 'function') continue
+    const name = String(provider.name)
+    const result: unknown = provider.httpUpgrades(context)
+    const declared = (result as Partial<PluginUpgrades> | null | undefined)?.routes
+    if (!Array.isArray(declared)) {
+      throw invalid(name, `httpUpgrades() must return { routes: [...] } (received ${describe(result)})`)
+    }
+    for (const route of declared as unknown[]) routes.push(validateRoute(plugin, name, route, context.prefix))
+    const settings = (result as PluginUpgrades).bunWebSocket
+    if (settings !== undefined) Object.assign(bunWebSocket, settings)
+  }
+  return { routes, bunWebSocket }
+}
+
+function validateRoute(instance: object, plugin: string, value: unknown, prefix: string): CollectedUpgradeRoute {
+  if (value === null || typeof value !== 'object') throw invalid(plugin, `invalid upgrade route ${describe(value)}`)
+  const route = value as Partial<PluginUpgradeRoute>
+  if (typeof route.name !== 'string' || route.name === '') {
+    throw invalid(plugin, `the upgrade route ${String(route.path)} needs a name`)
+  }
+  const where = `${String(route.path)} (${route.name})`
+  if (typeof route.path !== 'string') throw invalid(plugin, `the upgrade route ${where} has no path`)
+  if (typeof route.accept !== 'function') throw invalid(plugin, `the upgrade route ${where} has no accept function`)
+  if (route.precheck !== undefined && typeof route.precheck !== 'function') {
+    throw invalid(plugin, `the precheck of the upgrade route ${where} must be a function`)
+  }
+  let path: RoutePath
+  try {
+    path = parseRoutePath(joinPaths(prefix, route.path))
+  } catch (error) {
+    if (!(error instanceof RoutePathError)) throw error
+    throw invalid(plugin, `invalid path of the upgrade route ${where}: ${error.issue.message}`, error)
+  }
+  const meta = route.meta ?? []
+  if (!Array.isArray(meta)) throw invalid(plugin, `the meta of the upgrade route ${where} must be an array of entries`)
+  const entries = (meta as unknown[]).map(entry => metaEntry(plugin, where, entry))
+  const guards = route.guards ?? []
+  if (!Array.isArray(guards)) throw invalid(plugin, `the guards of the upgrade route ${where} must be an array`)
+  const timeoutMs = route.timeoutMs
+  if (timeoutMs !== undefined && !(typeof timeoutMs === 'number' && timeoutMs > 0)) {
+    throw invalid(plugin, `invalid timeoutMs ${describe(timeoutMs)} of the upgrade route ${where}`)
+  }
+  return {
+    plugin,
+    instance,
+    path,
+    relativePath: normalizePath(route.path),
+    name: route.name,
+    owner: route.owner ?? plugin,
+    meta: entries,
+    guards,
+    timeoutMs: timeoutMs === Number.POSITIVE_INFINITY ? undefined : timeoutMs,
+    precheck: route.precheck?.bind(route),
+    accept: route.accept.bind(route),
+  }
+}
+
+function metaEntry(plugin: string, where: string, value: unknown): NormalizedMetaEntry {
+  const entry = (value ?? {}) as Partial<RouteMetaEntry>
+  if (value === null || typeof value !== 'object' || typeof entry.key !== 'string' || entry.key === '') {
+    throw invalid(plugin, `invalid meta entry ${describe(value)} of the upgrade route ${where}`)
+  }
+  const group = entry.group ?? entry.key
+  const required = entry.required ?? false
+  if (!isGroupOf(group, entry.key) || typeof required !== 'boolean') {
+    throw invalid(plugin, `invalid group of the meta entry "${entry.key}" of the upgrade route ${where}`)
+  }
+  return { key: entry.key, value: entry.value, group, required }
+}
+
+function invalid(plugin: string, reason: string, cause?: unknown): ZnightError {
+  return new ZnightError(ErrorCode.InvalidRoute, `HttpPlugin: plugin "${plugin}": ${reason}`, {
+    ...(cause === undefined ? {} : { cause }),
+  })
+}
+
+function describe(value: unknown): string {
+  try {
+    return typeof value === 'function' ? 'a function' : (JSON.stringify(value) ?? String(value))
+  } catch {
+    return typeof value
+  }
+}
+
+// -------------------------------------------------------------------------------------------------
+// Handshake checks (RFC 6455 §4.2.1)
+// -------------------------------------------------------------------------------------------------
+
+const KEY = /^[A-Za-z0-9+/]{22}==$/
+
+/** Whether a request asks for a WebSocket upgrade (`upgrade: websocket`, any case). */
+export function isWebSocketUpgrade(headers: Readonly<Record<string, string | undefined>>): boolean {
+  const upgrade = headers['upgrade']
+  return upgrade !== undefined && upgrade.length === 9 && upgrade.toLowerCase() === 'websocket'
+}
+
+/**
+ * The protocol checks of a handshake: `GET`, `sec-websocket-version: 13` (`426` with the supported
+ * version otherwise) and a base64 16-byte `sec-websocket-key` (`400`).
+ */
+export function checkHandshake(ctx: HttpContext): void {
+  if (ctx.method !== 'GET') throw new BadRequestException('A WebSocket handshake must be a GET request')
+  if (ctx.headers['sec-websocket-version'] !== '13') {
+    throw new HttpException(426, 'Unsupported WebSocket version', undefined, {
+      headers: { 'sec-websocket-version': '13' },
+    })
+  }
+  const key = ctx.headers['sec-websocket-key']
+  if (key === undefined || !KEY.test(key.trim())) throw new BadRequestException('Invalid Sec-WebSocket-Key')
+}
+
+/** Internal: the pending upgrade of a handshake, created by the pipeline. */
+export class PendingUpgradeState implements PendingUpgrade {
+  readonly native: NativeUpgrade
+  readonly #headers: () => Readonly<Record<string, HeaderValue>>
+  /** The transport completed the handshake (`101`). */
+  accepted = false
+  /** The handshake timed out: the transport must not complete it. */
+  expired = false
+  held: Promise<unknown> | undefined
+
+  constructor(native: NativeUpgrade, headers: () => Readonly<Record<string, HeaderValue>>) {
+    this.native = native
+    this.#headers = headers
+  }
+
+  get headers(): Readonly<Record<string, HeaderValue>> {
+    return this.#headers()
+  }
+
+  hold(closed: Promise<unknown>): void {
+    if (this.held !== undefined) throw new Error('PendingUpgrade.hold() can only be called once')
+    this.accepted = true
+    this.held = closed.then(
+      () => undefined,
+      () => undefined,
+    )
+  }
+}