@znight/http 0.5.1 → 0.6.1

package/src/adapters/hono.ts

@@ -19,12 +19,14 @@ import type {
   InjectStreamResponse,
 } from '../adapter.ts'
 import type { HeaderValue } from '../exceptions.ts'
+import type { AdapterUpgrades, UpgradeHandlerOptions } from '../upgrade.ts'
 
 import { type Context, Hono, type Next } from 'hono'
 
 import { BadRequestException } from '../exceptions.ts'
 import { toHonoPath } from '../path.ts'
 import { discardStream } from '../stream.ts'
+import { isWebSocketUpgrade } from '../upgrade.ts'
 import { isBun } from '../utils.ts'
 import { ConnectionTracker, closeServer, nodeBodyStream, onResponseAbort, readNodeBody } from './node-io.ts'
 import {
@@ -36,6 +38,7 @@ import {
   serverAddress,
   webBodyStream,
 } from './shared.ts'
+import { bunWebSocketOption, FetchUpgradeRequest, NodeUpgrades, refusalResponse } from './upgrade-io.ts'
 
 /** Options of {@link honoAdapter}. */
 export interface HonoAdapterOptions {
@@ -104,11 +107,27 @@ interface BunRuntime {
     options: HonoServeOptions & {
       port: number
       hostname: string
-      fetch: (request: Request, server: BunServer) => Response | Promise<Response>
+      fetch: (request: Request, server: BunServer) => Response | undefined | Promise<Response | undefined>
+      websocket?: unknown
     },
   ): BunServer
 }
 
+/**
+ * The upgrade capability of the Hono adapter (RFC 0003): `Bun.serve()` upgrades on Bun (checked in
+ * the fetch handler before Hono routing), `node:http` upgrades of `@hono/node-server` on Node.js.
+ */
+class HonoUpgrades implements AdapterUpgrades {
+  readonly kind: 'node' | 'bun' = isBun() ? 'bun' : 'node'
+  readonly node: NodeUpgrades = new NodeUpgrades()
+  options: UpgradeHandlerOptions | undefined
+
+  enable(options: UpgradeHandlerOptions): void {
+    this.options = options
+    this.node.enable(options)
+  }
+}
+
 /** Default `idleTimeout` of `Bun.serve()`, in seconds. */
 const BUN_IDLE_TIMEOUT = 10
 
@@ -180,6 +199,8 @@ interface ReadHandlers {
 class HonoHttpAdapter implements HonoAdapter {
   readonly name = 'hono' as const
   readonly app: Hono
+  /** WebSocket upgrades (RFC 0003). */
+  readonly upgrades: HonoUpgrades = new HonoUpgrades()
   readonly #serveOptions: HonoServeOptions
   /** Number of routes of `app` registered by the adapter (see {@link #middleware}). */
   #routes = 0
@@ -411,6 +432,27 @@ class HonoHttpAdapter implements HonoAdapter {
     return response
   }
 
+  /**
+   * A WebSocket upgrade of a gateway path received by `Bun.serve()`, run before Hono routing:
+   * `undefined` for any other request; otherwise the refusal, or `undefined` once upgraded.
+   */
+  #bunUpgrade(
+    options: UpgradeHandlerOptions,
+    request: Request,
+    server: BunServer,
+  ): Promise<Response | undefined> | undefined {
+    const upgrade = request.headers.get('upgrade')
+    if (upgrade === null || !isWebSocketUpgrade({ upgrade })) return undefined
+    const url = pathAndQuery(request.url)
+    if (!options.match(pathOf(url))) return undefined
+    const address = server.requestIP?.(request)?.address ?? undefined
+    const adapterRequest = new FetchUpgradeRequest(request, url, fetchHeaders(request.headers), address)
+    return options.handle(adapterRequest, { kind: 'bun', request, server }).then(
+      reply => (reply === undefined ? undefined : refusalResponse(reply)),
+      () => new Response(null, { status: 500 }),
+    )
+  }
+
   async listen(port: number, host: string): Promise<HttpServerAddress> {
     this.#prepare()
     this.#closing = undefined
@@ -418,15 +460,18 @@ class HonoHttpAdapter implements HonoAdapter {
     if (isBun() && bun !== undefined) {
       const options = this.#serveOptions
       this.#idleTimeout = typeof options.idleTimeout === 'number' ? options.idleTimeout : BUN_IDLE_TIMEOUT
+      const upgrades = this.upgrades.options
       const server = bun.serve({
         // Znight enforces the body limits (route @BodyLimit, plugin bodyLimit): not Bun's 128 MiB default
         maxRequestBodySize: Number.MAX_SAFE_INTEGER,
         ...options,
+        ...(upgrades === undefined ? {} : { websocket: bunWebSocketOption(upgrades.bunWebSocket) }),
         port,
         hostname: host,
         // without middleware, the response of a Znight route is the one Bun sends (no wrapper needed)
         fetch: (request, server) =>
-          this.#middleware() ? this.#bunFetch(request, server) : this.app.fetch(request, server),
+          (upgrades === undefined ? undefined : this.#bunUpgrade(upgrades, request, server)) ??
+          (this.#middleware() ? this.#bunFetch(request, server) : this.app.fetch(request, server)),
       })
       this.#bun = server
       return serverAddress(server.hostname, server.port)
@@ -441,6 +486,7 @@ class HonoHttpAdapter implements HonoAdapter {
       )
     }
     const server = nodeServer.createAdaptorServer({ fetch: this.app.fetch }) as Server
+    this.upgrades.node.attach(server)
     this.#node = server
     this.#tracker = new ConnectionTracker(server)
     await new Promise<void>((resolve, reject) => {

package/src/adapters/node-io.ts

@@ -445,6 +445,14 @@ export class ConnectionTracker {
   }
 }
 
+/**
+ * Marks a socket taken over by a WebSocket transport (RFC 0003) as busy: a graceful close of the
+ * server leaves it to its transport, which closes it with a close frame; a forced close destroys it.
+ */
+export function markUpgraded(socket: object): void {
+  ;(socket as TrackedSocket)[ACTIVE] = 1
+}
+
 /** Closes a `node:http` server: graceful (idle connections ended), then forced when asked. */
 export function closeServer(
   server: Server,

package/src/adapters/node.ts

@@ -20,6 +20,7 @@ import { createServer, type IncomingMessage, type Server, type ServerOptions, ty
 import { RouteTable } from '../router.ts'
 import { ConnectionTracker, closeServer, nodeAdapterRequest, writeNodeFailure, writeNodeReply } from './node-io.ts'
 import { bufferInjectStream, injectNodeStream, serverAddress } from './shared.ts'
+import { NodeUpgrades } from './upgrade-io.ts'
 
 /** Options of {@link nodeAdapter}. */
 export interface NodeAdapterOptions {
@@ -55,6 +56,8 @@ export function nodeAdapter(options: NodeAdapterOptions = {}): NodeAdapter {
 
 class NodeHttpAdapter implements NodeAdapter {
   readonly name = 'node' as const
+  /** WebSocket upgrades (RFC 0003), routed by the server of {@link listen}. */
+  readonly upgrades: NodeUpgrades = new NodeUpgrades()
   readonly #routes = new RouteTable<AdapterHandler>()
   readonly #options: NodeAdapterOptions
   #fallback: FallbackHandler | undefined
@@ -107,6 +110,7 @@ class NodeHttpAdapter implements NodeAdapter {
     this.#tracker ??= new ConnectionTracker(server, { requests: false })
     this.#closing = undefined
     if (!server.listeners('request').includes(this.handler)) server.on('request', this.handler)
+    this.upgrades.attach(server)
     await new Promise<void>((resolve, reject) => {
       const onError = (error: Error): void => reject(error)
       server.once('error', onError)

package/src/adapters/upgrade-io.ts

@@ -0,0 +1,255 @@
+/**
+ * WebSocket upgrades on the adapters (RFC 0003 §8.2.3, internal): the upgrade capability of
+ * `node:http` servers, the request of a handshake as an {@link AdapterRequest} (Node.js, Fetch,
+ * in memory) and the raw HTTP refusal written on a socket.
+ */
+import type { IncomingMessage, Server } from 'node:http'
+import type { Duplex } from 'node:stream'
+import type { AdapterReply, AdapterRequest } from '../adapter.ts'
+import type { HeaderValue } from '../exceptions.ts'
+import type { AdapterUpgrades, BunSocketHandlers, UpgradeHandlerOptions } from '../upgrade.ts'
+
+import { statusText } from '../status.ts'
+import { isWebSocketUpgrade } from '../upgrade.ts'
+import { markUpgraded, normalizeNodeHeaders } from './node-io.ts'
+import { concat } from './shared.ts'
+
+const EMPTY = new Uint8Array(0)
+
+/** A handshake has no body: Znight never reads one. */
+const NO_BODY: Promise<Uint8Array> = Promise.resolve(EMPTY)
+
+/** The `IncomingMessage` of a `node:http` upgrade as an {@link AdapterRequest}. */
+class NodeUpgradeRequest implements AdapterRequest {
+  readonly method: string
+  readonly url: string
+  readonly headers: Readonly<Record<string, string | undefined>>
+  readonly ip: string | undefined
+  readonly remoteAddress: string | undefined
+  readonly encrypted: boolean
+  readonly raw: unknown
+  readonly rawResponse: unknown
+
+  constructor(request: IncomingMessage, socket: Duplex) {
+    const peer = (socket as { readonly remoteAddress?: string }).remoteAddress ?? request.socket?.remoteAddress
+    this.method = request.method ?? 'GET'
+    this.url = request.url ?? '/'
+    this.headers = normalizeNodeHeaders(request.headers)
+    this.ip = peer
+    this.remoteAddress = peer
+    this.encrypted = (request.socket as { readonly encrypted?: unknown } | undefined)?.encrypted === true
+    this.raw = request
+    this.rawResponse = socket
+  }
+
+  readBody(): Promise<Uint8Array> {
+    return NO_BODY
+  }
+
+  hasBody(): boolean {
+    return false
+  }
+}
+
+/** The Fetch `Request` of a `Bun.serve()` upgrade as an {@link AdapterRequest}. */
+export class FetchUpgradeRequest implements AdapterRequest {
+  readonly method: string
+  readonly url: string
+  readonly headers: Readonly<Record<string, string | undefined>>
+  readonly ip: string | undefined
+  readonly remoteAddress: string | undefined
+  readonly encrypted: boolean
+  readonly raw: Request
+  readonly rawResponse: unknown = undefined
+
+  constructor(request: Request, url: string, headers: Record<string, string>, address: string | undefined) {
+    this.method = request.method
+    this.url = url
+    this.headers = headers
+    this.ip = address
+    this.remoteAddress = address
+    this.encrypted = request.url.startsWith('https:')
+    this.raw = request
+  }
+
+  readBody(): Promise<Uint8Array> {
+    return NO_BODY
+  }
+
+  hasBody(): boolean {
+    return false
+  }
+}
+
+/** An in-memory handshake (`HttpPlugin.upgradeInMemory()`) as an {@link AdapterRequest}. */
+export class MemoryUpgradeRequest implements AdapterRequest {
+  readonly method: string
+  readonly url: string
+  readonly headers: Readonly<Record<string, string | undefined>>
+  readonly ip = '127.0.0.1'
+  readonly remoteAddress = '127.0.0.1'
+  readonly encrypted = false
+  readonly raw: unknown = undefined
+  readonly rawResponse: unknown = undefined
+
+  constructor(method: string, url: string, headers: Record<string, string>) {
+    this.method = method
+    this.url = url
+    this.headers = headers
+  }
+
+  readBody(): Promise<Uint8Array> {
+    return NO_BODY
+  }
+
+  hasBody(): boolean {
+    return false
+  }
+}
+
+/** The bytes of a reply body (refusals are small: read whole). */
+export async function replyBytes(reply: AdapterReply): Promise<Uint8Array> {
+  const body = reply.body
+  if (body === null) return EMPTY
+  if (body instanceof Uint8Array) return body
+  if (body instanceof Blob) return new Uint8Array(await body.arrayBuffer())
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for await (const chunk of body as ReadableStream<Uint8Array>) {
+    chunks.push(chunk)
+    size += chunk.byteLength
+  }
+  return concat(chunks, size)
+}
+
+/** Whether a header value can be written on a raw socket (no CR/LF injection). */
+function safeHeader(value: string): boolean {
+  return !/[\r\n]/.test(value)
+}
+
+/**
+ * Writes a refused handshake as a raw HTTP/1.1 response on the upgrade socket, then ends it
+ * (`connection: close`). Never throws.
+ */
+export async function writeRawRefusal(socket: Duplex, reply: AdapterReply): Promise<void> {
+  try {
+    const body = await replyBytes(reply)
+    let head = `HTTP/1.1 ${reply.status} ${statusText(reply.status)}\r\n`
+    const headers: Record<string, HeaderValue> = { ...reply.headers }
+    headers['connection'] = 'close'
+    headers['content-length'] = String(body.byteLength)
+    for (const [name, value] of Object.entries(headers)) {
+      for (const item of typeof value === 'string' ? [value] : value) {
+        if (safeHeader(name) && safeHeader(item)) head += `${name}: ${item}\r\n`
+      }
+    }
+    head += '\r\n'
+    if (socket.destroyed) return
+    socket.write(head)
+    if (body.byteLength > 0) socket.write(body)
+    socket.end()
+    // a client that never closes its side: destroy after a short grace
+    setTimeout(() => socket.destroy(), 1_000).unref?.()
+  } catch {
+    socket.destroy()
+  }
+}
+
+/** The fallback reply when the pipeline failed (never expected). */
+const FAILURE: AdapterReply = Object.freeze({ status: 500, headers: {}, body: null })
+
+/**
+ * The upgrade capability of an adapter built on a `node:http` server (RFC 0003 §8.2.3): upgrade
+ * requests of the gateway paths are routed to the pipeline through `shouldUpgradeCallback`
+ * (composed with the server's own) and an `'upgrade'` listener; other upgrade requests are left to
+ * the server (its own listeners, or ordinary requests).
+ */
+export class NodeUpgrades implements AdapterUpgrades {
+  readonly kind = 'node' as const
+  #options: UpgradeHandlerOptions | undefined
+  readonly #attached = new WeakSet<Server>()
+
+  /** Whether {@link enable} was called. */
+  get enabled(): boolean {
+    return this.#options !== undefined
+  }
+
+  enable(options: UpgradeHandlerOptions): void {
+    this.#options = options
+  }
+
+  /** Routes the gateway upgrades of `server` to the pipeline (once per server; no-op when not enabled). */
+  attach(server: Server): void {
+    const options = this.#options
+    if (options === undefined || this.#attached.has(server)) return
+    this.#attached.add(server)
+    const matches = (request: IncomingMessage): boolean => {
+      if (!isWebSocketUpgrade(request.headers as Record<string, string | undefined>)) return false
+      const url = request.url ?? '/'
+      const query = url.indexOf('?')
+      return options.match(query === -1 ? url : url.slice(0, query))
+    }
+    const target = server as Server & { shouldUpgradeCallback?: (request: IncomingMessage) => boolean }
+    const previous = target.shouldUpgradeCallback
+    const composable = typeof previous === 'function'
+    const listener = (request: IncomingMessage, socket: Duplex, head: Uint8Array): void => {
+      if (!matches(request)) {
+        // without shouldUpgradeCallback (Node.js < 24.12), every upgrade reaches the listeners: answer
+        // the ones nobody else handles
+        if (!composable && server.listenerCount('upgrade') === 1) {
+          void writeRawRefusal(socket, { status: 404, headers: {}, body: null })
+        }
+        return
+      }
+      socket.on('error', () => socket.destroy())
+      markUpgraded(socket)
+      const native = { kind: 'node', request, socket, head } as const
+      options.handle(new NodeUpgradeRequest(request, socket), native).then(
+        reply => {
+          if (reply !== undefined) void writeRawRefusal(socket, reply)
+        },
+        () => void writeRawRefusal(socket, FAILURE),
+      )
+    }
+    if (previous !== undefined) {
+      target.shouldUpgradeCallback = function (this: Server, request: IncomingMessage): boolean {
+        if (matches(request)) return true
+        // the server's callback without Znight's listener (Node's default counts the listeners)
+        const self = this ?? server
+        const view = Object.create(self, {
+          listenerCount: {
+            value: (name: string | symbol): number => self.listenerCount(name) - (name === 'upgrade' ? 1 : 0),
+          },
+        }) as Server
+        return previous.call(view, request) === true
+      }
+    }
+    server.on('upgrade', listener)
+  }
+}
+
+/**
+ * The `websocket` option of `Bun.serve()`: the plugins' settings, and handlers dispatching every
+ * event to the {@link BunSocketHandlers} given as `data` to `server.upgrade()`.
+ */
+export function bunWebSocketOption(settings: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> {
+  type Socket = { readonly data: BunSocketHandlers }
+  return Object.freeze({
+    ...settings,
+    open: (ws: Socket): void => ws.data.open(ws),
+    message: (ws: Socket, message: string | Uint8Array): void => ws.data.message(ws, message),
+    close: (ws: Socket, code: number, reason: string): void => ws.data.close(ws, code, reason),
+    drain: (ws: Socket): void => ws.data.drain(ws),
+    pong: (ws: Socket): void => ws.data.pong?.(ws),
+  })
+}
+
+/** Builds the `Response` of a refused `Bun.serve()` upgrade. */
+export async function refusalResponse(reply: AdapterReply): Promise<Response> {
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(reply.headers)) {
+    for (const item of typeof value === 'string' ? [value] : value) headers.append(name, item)
+  }
+  const body = await replyBytes(reply)
+  return new Response(body.byteLength === 0 ? null : body, { status: reply.status, headers })
+}

package/src/decorators.ts

@@ -286,7 +286,7 @@ export function BodyLimit(_size: ByteSize): ClassMarker & MethodMarker {
   return classOrMethodMarker
 }
 
-/** Injects the native request of the adapter (escape hatch; the compiler warns). */
+/** Injects the native request of the adapter (escape hatch). */
 export function Req(): ParameterMarker {
   return parameterMarker
 }

package/src/index.ts

@@ -59,6 +59,20 @@ export type { ByteSize } from './size.ts'
 export type { SseBody, SseEvent, SseOptions, SseSource } from './sse.ts'
 export type { ParseSseOptions, SseItem, SseMessage } from './sse-parse.ts'
 export type { StreamSource } from './stream.ts'
+export type {
+  AdapterUpgrades,
+  BunSocketHandlers,
+  BunUpgrade,
+  MemoryUpgrade,
+  NativeUpgrade,
+  NodeUpgrade,
+  PendingUpgrade,
+  PluginHttpUpgrades,
+  PluginHttpUpgradesContext,
+  PluginUpgradeRoute,
+  PluginUpgrades,
+  UpgradeHandlerOptions,
+} from './upgrade.ts'
 
 export { type NodeAdapter, type NodeAdapterOptions, nodeAdapter } from './adapters/node.ts'
 export { isJsonType, type MediaType, parseBody, parseMediaType } from './body.ts'

package/src/pipeline.ts

@@ -8,6 +8,7 @@ import type { CanActivate, ExceptionMapper, HttpInterceptor } from './interfaces
 import type { HttpRouteDefinition, HttpSseDefinition } from './metadata.ts'
 import type { TrustPolicy } from './proxy.ts'
 import type { RouteTable } from './router.ts'
+import type { NativeUpgrade } from './upgrade.ts'
 import type { BodyPlan } from './uploads.ts'
 
 import { Buffer } from 'node:buffer'
@@ -46,6 +47,7 @@ import { isSseBody, isSseSource, type SseOptions, SseSession, type SseSource } f
 import { isBodylessStatus } from './status.ts'
 import { type ContextRunner, captureContext, discardStream, type TrackedStream, trackStream } from './stream.ts'
 import { HttpTokens } from './tokens.ts'
+import { PendingUpgradeState } from './upgrade.ts'
 import { emptyRecord, errorMessage, fastRecord, isBun, isThenable } from './utils.ts'
 
 /** A dependency of the pipeline: an instance resolved at bootstrap, or a token resolved per request. */
@@ -73,6 +75,24 @@ export interface RoutePlan {
   readonly redirect?: boolean
 }
 
+/** An upgrade route: its plan, and how long the handshake may take (internal). */
+export interface UpgradePlan {
+  readonly plan: RoutePlan
+  /** `408` after this delay (ms); `undefined`: no limit. */
+  readonly timeoutMs: number | undefined
+}
+
+/**
+ * The pending upgrade of a handshake context (RFC 0003): set by {@link Pipeline.upgrade} for the
+ * upgrade routes only, so that ordinary requests pay nothing.
+ */
+const UPGRADES = new WeakMap<object, PendingUpgradeState>()
+
+/** The pending upgrade of the handshake whose context is `ctx` (internal, upgrade routes). */
+export function pendingUpgradeOf(ctx: HttpContext): PendingUpgradeState | undefined {
+  return UPGRADES.get(ctx)
+}
+
 /** Pipeline settings (resolved plugin options). */
 export interface PipelineOptions {
   readonly adapter: string
@@ -241,6 +261,8 @@ export class Pipeline {
   readonly #streams = new Set<SseSession>()
   /** Set while the server drains: responses ask clients to close their connection. */
   draining = false
+  /** The upgrade routes (RFC 0003), `undefined` when no plugin declares one. */
+  upgrades: RouteTable<UpgradePlan> | undefined = undefined
 
   constructor(
     container: Container,
@@ -781,6 +803,70 @@ export class Pipeline {
     }
   }
 
+  /**
+   * Serves a WebSocket handshake (RFC 0003 §8.2.2): the upgrade route of its raw path runs through
+   * the pipeline. Resolves with the reply to write (a refusal), or `undefined` once the transport
+   * took the connection; the request scope then stays open until the connection closes.
+   */
+  upgrade(request: AdapterRequest, native: NativeUpgrade): Promise<AdapterReply | undefined> {
+    const startTime = performance.now()
+    try {
+      const url = splitUrl(request.url)
+      const upgrade = this.upgrades?.find('GET', url.path)
+      if (upgrade === undefined) return this.#fallback(request, undefined, startTime)
+      const plan = upgrade.plan
+      const raw = matchRoutePath(plan.path, url.path) ?? emptyRecord<string>()
+      const params = emptyRecord<string>()
+      let malformed: string | undefined
+      for (const name of Object.keys(raw)) {
+        const decoded = decodePathValue(raw[name] as string)
+        if (decoded === undefined) malformed ??= name
+        else params[name] = decoded
+      }
+      const target: Target =
+        malformed === undefined
+          ? { kind: 'route', plan }
+          : { kind: 'error', error: new BadRequestException(`Malformed URL parameter "${malformed}"`) }
+      let pending: PendingUpgradeState | undefined
+      const replied = this.#serve(request, url, plan.info, params, target, startTime, plan.body, ctx => {
+        pending = new PendingUpgradeState(native, () => this.#upgradeHeaders(ctx))
+        UPGRADES.set(ctx, pending)
+      })
+      const settled = replied.then(reply => (pending?.accepted === true ? undefined : reply))
+      const timeoutMs = upgrade.timeoutMs
+      if (timeoutMs === undefined) return settled
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const expired = new Promise<AdapterReply>(resolve => {
+        timer = setTimeout(() => {
+          if (pending !== undefined) pending.expired = true
+          const body = { statusCode: 408, error: 'Request Timeout', message: 'WebSocket handshake timed out' }
+          resolve(adapterReply(serializeError(408, body, 'GET'), null))
+        }, timeoutMs)
+      })
+      return Promise.race([settled, expired]).finally(() => clearTimeout(timer))
+    } catch (error) {
+      return Promise.reject(error)
+    }
+  }
+
+  /** The headers of a `101` response: those set on the context, its cookies and the request id. */
+  #upgradeHeaders(ctx: RequestContext): Readonly<Record<string, HeaderValue>> {
+    const headers: Record<string, HeaderValue> = { ...ctx.responseHeaders }
+    const cookies = ctx.cookieLines
+    if (cookies.length > 0) {
+      const existing = headers['set-cookie']
+      const raw: string[] = []
+      if (typeof existing === 'string') raw.push(existing)
+      else if (existing !== undefined) raw.push(...existing)
+      headers['set-cookie'] = [...raw, ...cookies.map(cookie => cookie.line)]
+    }
+    const idHeader = this.#options.requestIdHeader
+    if (idHeader !== undefined && headers[idHeader] === undefined && (this.#validIds || isHeaderValue(ctx.requestId))) {
+      headers[idHeader] = ctx.requestId
+    }
+    return headers
+  }
+
   #fallback(request: AdapterRequest, error: unknown, startTime: number, reroute = true): Promise<AdapterReply> {
     const body = this.#options.body
     if (error !== undefined) {
@@ -799,7 +885,7 @@ export class Pipeline {
     const allowed = this.#table.allowedMethods(path)
     let target: Target
     if (allowed.length === 0) {
-      target = { kind: 'error', error: new NotFoundException(`Cannot ${request.method} ${truncate(path)}`) }
+      target = { kind: 'error', error: this.#unmatched(request.method, path) }
     } else if (request.method === 'OPTIONS') {
       target = { kind: 'options', allow: allowHeader(allowed) }
     } else {
@@ -818,6 +904,19 @@ export class Pipeline {
     return this.#serve(request, url, undefined, emptyRecord(), target, startTime, body)
   }
 
+  /**
+   * The error of a request no route matched: `404`, or `426 Upgrade Required` for a plain `GET` of
+   * a WebSocket gateway path (RFC 0003 §8.2.1).
+   */
+  #unmatched(method: string, path: string): HttpException {
+    if ((method === 'GET' || method === 'HEAD') && this.upgrades?.find('GET', path) !== undefined) {
+      return new HttpException(426, 'This endpoint only accepts WebSocket connections', undefined, {
+        headers: { upgrade: 'websocket', connection: 'upgrade' },
+      })
+    }
+    return new NotFoundException(`Cannot ${method} ${truncate(path)}`)
+  }
+
   /** A CORS preflight (with the `cors` option): answered without running any route. */
   #isPreflight(request: AdapterRequest): boolean {
     return this.#options.cors !== undefined && isPreflight(request.method, request.headers)
@@ -838,12 +937,14 @@ export class Pipeline {
     target: Target,
     startTime: number,
     body: BodyPlan,
+    prepare?: (ctx: RequestContext) => void,
   ): Promise<AdapterReply> {
     this.#enter()
     let x: Exchange
     try {
       const requestId = this.#requestId(request)
       const ctx = this.#context(request, requestId, url.path, url.query, route, params, body)
+      if (prepare !== undefined) prepare(ctx)
       // an event stream requested while draining is served (guards run) with its signal already
       // aborted: a well-behaved source ends at once and the client gets a jittered retry
       if (this.draining && target.kind === 'route' && target.plan.definition.sse !== undefined) ctx.abort('shutdown')
@@ -958,6 +1059,11 @@ export class Pipeline {
     }
     const streaming = this.#send(x, outcome, recheck, run)
     if (streaming !== undefined) this.#streamed(x, streaming, await streaming.tracked.done)
+    else if (outcome === RAW) {
+      // an accepted WebSocket handshake: the connection lives in this scope until it closes
+      const held = UPGRADES.get(ctx)?.held
+      if (held !== undefined) await held
+    }
   }
 
   /**
@@ -993,7 +1099,7 @@ export class Pipeline {
     const event = x.event
     if (outcome === RAW) {
       ctx.commit()
-      const status = x.request.rawStatus?.() ?? 200
+      const status = UPGRADES.get(ctx)?.accepted === true ? 101 : (x.request.rawStatus?.() ?? 200)
       event.status ??= status
       x.answer({ status, headers: {}, body: null, raw: true })
       return undefined

package/src/plugin-routes.ts

@@ -9,6 +9,7 @@ import type { RouteMetaEntry } from './decorators.ts'
 import type { HttpMethod } from './metadata.ts'
 import type { GuardRef } from './plugin.ts'
 import type { ByteSize } from './size.ts'
+import type { PluginHttpUpgradesContext, PluginUpgrades } from './upgrade.ts'
 
 import { ErrorCode, ZnightError } from '@znight/core'
 
@@ -79,6 +80,11 @@ export interface PluginHttpRoutes {
    * waits for a returned promise too (within `drainTimeoutMs`); a failure is logged.
    */
   onHttpDrain?(): void | Promise<void>
+  /**
+   * WebSocket upgrade routes of the plugin (RFC 0003, `@znight/websocket`): see
+   * {@link PluginHttpUpgrades}. Called once in `onBootstrap`, after `httpRoutes()`.
+   */
+  httpUpgrades?(context: PluginHttpUpgradesContext): PluginUpgrades
 }
 
 /** A validated plugin route (internal). */