@znight/http 0.0.0-stage → 0.1.1

package/src/proxy.ts

@@ -0,0 +1,236 @@
+/**
+ * Trusted proxies (RFC 0001 §5.6): `ctx.ip` and `ctx.protocol` behind load balancers, computed the
+ * same way on every adapter from the socket peer (`AdapterRequest.remoteAddress`) and the
+ * `x-forwarded-for` / `x-forwarded-proto` headers. The `Forwarded` header (RFC 7239) is not read.
+ */
+import { invalidOption } from './option-error.ts'
+
+/**
+ * The `trustProxy` option: `false` (default: the headers are ignored), a number of trusted hops
+ * (`1`: one load balancer in front of the server), or the addresses of the trusted proxies (IPv4 /
+ * IPv6 addresses, CIDR ranges and the aliases `'loopback'`, `'private'`, `'linklocal'`).
+ */
+export type TrustProxy = false | number | readonly string[]
+
+/** Client address and protocol of a request (internal). */
+export interface ClientInfo {
+  readonly ip: string | undefined
+  readonly protocol: 'http' | 'https'
+}
+
+/** A resolved `trustProxy` policy (internal). */
+export interface TrustPolicy {
+  /** `ctx.ip` and `ctx.protocol` of a request. */
+  resolve(
+    remoteAddress: string | undefined,
+    headers: Readonly<Record<string, string | undefined>>,
+    encrypted: boolean,
+  ): ClientInfo
+}
+
+/** A parsed address: IPv4 (4 bytes, IPv4-mapped IPv6 included) or IPv6 (16 bytes). */
+interface Address {
+  readonly bytes: readonly number[]
+  /** Normalised text (`::ffff:10.0.0.1` → `10.0.0.1`). */
+  readonly text: string
+}
+
+interface Range {
+  readonly bytes: readonly number[]
+  readonly prefix: number
+}
+
+const ALIASES: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  loopback: ['127.0.0.0/8', '::1/128'],
+  private: ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', 'fc00::/7'],
+  linklocal: ['169.254.0.0/16', 'fe80::/10'],
+})
+
+const TRUST_HINTS: readonly string[] = [
+  'trustProxy: 1 trusts one proxy (the socket peer); trustProxy: ["loopback", "10.0.0.0/8"] trusts these addresses',
+  'Trusting every hop would let any client choose its ctx.ip with an x-forwarded-for header',
+]
+
+/** Validates the `trustProxy` option (ZNIGHT005); `undefined` when proxies are not trusted. */
+export function resolveTrustProxy(value: TrustProxy | undefined): TrustPolicy | undefined {
+  if (value === undefined || value === false) return undefined
+  if (typeof value === 'number') {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw invalidOption(
+        'trustProxy',
+        'false, a number of hops (an integer >= 1) or a list of addresses',
+        value,
+        undefined,
+        TRUST_HINTS,
+      )
+    }
+    return hopPolicy(value)
+  }
+  if (!Array.isArray(value)) {
+    throw invalidOption(
+      'trustProxy',
+      'false, a number of hops (an integer >= 1) or a list of addresses',
+      value,
+      undefined,
+      TRUST_HINTS,
+    )
+  }
+  const ranges: Range[] = []
+  for (const entry of value) {
+    if (typeof entry !== 'string') {
+      throw invalidOption('trustProxy', 'a list of addresses, CIDR ranges or aliases', value, undefined, TRUST_HINTS)
+    }
+    const expanded = ALIASES[entry] ?? [entry]
+    for (const item of expanded) {
+      const range = parseRange(item)
+      if (range === undefined) {
+        throw invalidOption(
+          'trustProxy',
+          `a list of IP addresses, CIDR ranges ("10.0.0.0/8") or aliases ("loopback", "private", "linklocal"); "${entry}" is invalid`,
+          value,
+          undefined,
+          TRUST_HINTS,
+        )
+      }
+      ranges.push(range)
+    }
+  }
+  return listPolicy(ranges)
+}
+
+function hopPolicy(hops: number): TrustPolicy {
+  return {
+    resolve(remoteAddress, headers, encrypted) {
+      const socket = remoteAddress === undefined ? undefined : parseAddress(remoteAddress)
+      if (socket === undefined) return { ip: remoteAddress, protocol: encrypted ? 'https' : 'http' }
+      let client = socket
+      const chain = forwardedFor(headers)
+      for (let index = 0; index < hops && index < chain.length; index++) {
+        const next = parseAddress(chain[index] as string)
+        if (next === undefined) break // a malformed entry stops the walk at the last valid address
+        client = next
+      }
+      return { ip: client.text, protocol: forwardedProto(headers, encrypted) }
+    },
+  }
+}
+
+function listPolicy(ranges: readonly Range[]): TrustPolicy {
+  const trusted = (address: Address): boolean => ranges.some(range => inRange(address, range))
+  return {
+    resolve(remoteAddress, headers, encrypted) {
+      const socket = remoteAddress === undefined ? undefined : parseAddress(remoteAddress)
+      if (socket === undefined) return { ip: remoteAddress, protocol: encrypted ? 'https' : 'http' }
+      if (!trusted(socket)) return { ip: socket.text, protocol: encrypted ? 'https' : 'http' }
+      let client = socket
+      for (const entry of forwardedFor(headers)) {
+        const next = parseAddress(entry)
+        if (next === undefined) break
+        client = next
+        if (!trusted(next)) break
+      }
+      return { ip: client.text, protocol: forwardedProto(headers, encrypted) }
+    },
+  }
+}
+
+/** `x-forwarded-for` entries from right (nearest proxy) to left (client). */
+function forwardedFor(headers: Readonly<Record<string, string | undefined>>): string[] {
+  const value = headers['x-forwarded-for']
+  if (value === undefined) return []
+  return value
+    .split(',')
+    .map(entry => entry.trim())
+    .reverse()
+}
+
+/** The leftmost `x-forwarded-proto` value when it is `http` or `https`, else the connection protocol. */
+function forwardedProto(headers: Readonly<Record<string, string | undefined>>, encrypted: boolean): 'http' | 'https' {
+  const value = headers['x-forwarded-proto']?.split(',')[0]?.trim().toLowerCase()
+  if (value === 'http' || value === 'https') return value
+  return encrypted ? 'https' : 'http'
+}
+
+function inRange(address: Address, range: Range): boolean {
+  if (address.bytes.length !== range.bytes.length) return false
+  let bits = range.prefix
+  for (let index = 0; index < range.bytes.length && bits > 0; index++) {
+    const mask = bits >= 8 ? 0xff : (0xff << (8 - bits)) & 0xff
+    if (((address.bytes[index] as number) & mask) !== ((range.bytes[index] as number) & mask)) return false
+    bits -= 8
+  }
+  return true
+}
+
+/** `10.0.0.0/8`, `fc00::/7` or a single address. */
+function parseRange(value: string): Range | undefined {
+  const slash = value.indexOf('/')
+  const address = parseAddress(slash === -1 ? value : value.slice(0, slash))
+  if (address === undefined) return undefined
+  const bits = address.bytes.length * 8
+  if (slash === -1) return { bytes: address.bytes, prefix: bits }
+  const prefixText = value.slice(slash + 1)
+  if (!/^\d{1,3}$/.test(prefixText)) return undefined
+  const prefix = Number(prefixText)
+  return prefix > bits ? undefined : { bytes: address.bytes, prefix }
+}
+
+/** Parses an IPv4 or IPv6 address (zone ids ignored); IPv4-mapped IPv6 addresses become IPv4. */
+export function parseAddress(value: string): Address | undefined {
+  const text = value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value
+  const v4 = parseIPv4(text)
+  if (v4 !== undefined) return { bytes: v4, text }
+  const zone = text.indexOf('%')
+  const v6 = parseIPv6(zone === -1 ? text : text.slice(0, zone))
+  if (v6 === undefined) return undefined
+  if (v6.slice(0, 10).every(byte => byte === 0) && v6[10] === 0xff && v6[11] === 0xff) {
+    const bytes = v6.slice(12)
+    return { bytes, text: bytes.join('.') }
+  }
+  return { bytes: v6, text: text.toLowerCase() }
+}
+
+function parseIPv4(text: string): number[] | undefined {
+  const parts = text.split('.')
+  if (parts.length !== 4) return undefined
+  const bytes: number[] = []
+  for (const part of parts) {
+    if (!/^(?:0|[1-9]\d{0,2})$/.test(part)) return undefined
+    const byte = Number(part)
+    if (byte > 255) return undefined
+    bytes.push(byte)
+  }
+  return bytes
+}
+
+function parseIPv6(text: string): number[] | undefined {
+  if (text === '' || text.length > 45) return undefined
+  const halves = text.split('::')
+  if (halves.length > 2) return undefined
+  const groups = (part: string): number[] | undefined => {
+    if (part === '') return []
+    const result: number[] = []
+    const items = part.split(':')
+    for (let index = 0; index < items.length; index++) {
+      const item = items[index] as string
+      if (index === items.length - 1 && item.includes('.')) {
+        const v4 = parseIPv4(item)
+        if (v4 === undefined) return undefined
+        result.push(((v4[0] as number) << 8) | (v4[1] as number), ((v4[2] as number) << 8) | (v4[3] as number))
+      } else {
+        if (!/^[0-9A-Fa-f]{1,4}$/.test(item)) return undefined
+        result.push(Number.parseInt(item, 16))
+      }
+    }
+    return result
+  }
+  const head = groups(halves[0] as string)
+  const tail = halves.length === 2 ? groups(halves[1] as string) : []
+  if (head === undefined || tail === undefined) return undefined
+  const missing = 8 - head.length - tail.length
+  if (halves.length === 2 ? missing < 1 : missing !== 0) return undefined
+  const words = [...head, ...new Array<number>(missing).fill(0), ...tail]
+  const bytes: number[] = []
+  for (const word of words) bytes.push(word >> 8, word & 0xff)
+  return bytes
+}

package/src/query.ts

@@ -0,0 +1,30 @@
+import { emptyRecord } from './utils.ts'
+
+/** Parsed query string (or `application/x-www-form-urlencoded` body): repeated keys become arrays. */
+export type QueryRecord = Record<string, string | string[]>
+
+/**
+ * Parses a query string (with or without the leading `?`) with `URLSearchParams` semantics (`+` is
+ * a space, malformed `%` sequences are kept as is, invalid UTF-8 becomes U+FFFD). A key present
+ * once maps to a string, a repeated key to an array of strings, in order. No nesting (`a[b]=1` is
+ * the key `a[b]`). The returned object has no prototype.
+ *
+ * `parseQuery('?tag=a&tag=b&page=2')` → `{ tag: ['a', 'b'], page: '2' }`
+ */
+export function parseQuery(query: string): QueryRecord {
+  const result = emptyRecord<string | string[]>()
+  if (query === '' || query === '?') return result
+  for (const [key, value] of new URLSearchParams(query)) {
+    const existing = result[key]
+    if (existing === undefined) result[key] = value
+    else if (typeof existing === 'string') result[key] = [existing, value]
+    else existing.push(value)
+  }
+  return result
+}
+
+/** Splits a request target (`/users?page=2`) into its raw path and raw query (without `?`). */
+export function splitUrl(url: string): { readonly path: string; readonly query: string } {
+  const index = url.indexOf('?')
+  return index === -1 ? { path: url, query: '' } : { path: url.slice(0, index), query: url.slice(index + 1) }
+}

package/src/response.ts

@@ -0,0 +1,240 @@
+import type { HeaderValue } from './exceptions.ts'
+
+import {
+  type ClearCookieOptions,
+  type CookieOptions,
+  checkCookie,
+  givenCookieKey,
+  type ResponseCookie,
+} from './cookies.ts'
+import { type ContentDispositionType, contentDisposition, FileBody, type FileResponseOptions } from './files.ts'
+import { contentTypeFor, OCTET_STREAM } from './mime.ts'
+import { SseBody, type SseOptions, type SseSource } from './sse.ts'
+import { isValidStatus } from './status.ts'
+import { isStreamSource, type StreamSource, toByteStream } from './stream.ts'
+
+/** Options of {@link HttpResponse.stream}. */
+export interface StreamResponseOptions {
+  /** Media type. Default: from the extension of `filename`, else `application/octet-stream`. */
+  readonly contentType?: string
+  /** Name proposed to the client (`Content-Disposition: attachment` unless `disposition` says otherwise). */
+  readonly filename?: string
+  /** `attachment` or `inline`. Default: `attachment` when `filename` is set, otherwise no header. */
+  readonly disposition?: ContentDispositionType
+}
+
+/** Options of {@link HttpResponse}. */
+export interface HttpResponseInit {
+  /** Status code. Default: the route default (`@HttpCode`, 201 for POST, 204 without body, 200). */
+  readonly status?: number
+  /** Response headers (names are case-insensitive; arrays send the header several times). */
+  readonly headers?: Readonly<Record<string, HeaderValue>>
+  /** Cookies to set (see {@link HttpResponse.withCookie}), in order. */
+  readonly cookies?: readonly ResponseCookie[]
+}
+
+/** Redirect statuses accepted by {@link HttpResponse.redirect}. */
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308
+
+/**
+ * A handler result carrying a status and headers next to the body. The body is serialised with the
+ * usual rules (objects → JSON, strings → text, bytes and streams → octet-stream).
+ *
+ * ```ts
+ * @Post('/')
+ * async create(@Body(CreateUser) input: CreateUser): Promise<HttpResponse<User>> {
+ *   const user = await this.users.create(input)
+ *   return HttpResponse.created(user, `/users/${user.id}`)
+ * }
+ * ```
+ *
+ * Status precedence: `@HttpCode` > `HttpResponse.status` > route default.
+ */
+export class HttpResponse<T = unknown> {
+  readonly body: T
+  readonly status: number | undefined
+  readonly headers: Readonly<Record<string, HeaderValue>>
+  /** Cookies set by this response (`withCookie` / `withoutCookie`), in order; they win over `ctx.setCookie()`. */
+  readonly cookies: readonly ResponseCookie[]
+
+  constructor(body: T, init: HttpResponseInit = {}) {
+    if (init.status !== undefined && !isValidStatus(init.status)) {
+      throw new RangeError(`Invalid HTTP status ${String(init.status)} (expected an integer between 100 and 599)`)
+    }
+    this.body = body
+    this.status = init.status
+    this.headers = init.headers ?? {}
+    this.cookies = init.cookies === undefined ? NO_COOKIES : Object.freeze([...init.cookies])
+  }
+
+  /** `200 OK` with `body`. */
+  static ok<T>(body: T, headers?: Readonly<Record<string, HeaderValue>>): HttpResponse<T> {
+    return new HttpResponse(body, headers === undefined ? { status: 200 } : { status: 200, headers })
+  }
+
+  /**
+   * `201 Created`, with a `location` header when given. With a body, the response is typed with it
+   * (`Promise<HttpResponse<BookResponse>>` type-checks).
+   */
+  static created(): HttpResponse<undefined>
+  static created<T>(body: T, location?: string): HttpResponse<T>
+  static created<T>(body?: T, location?: string): HttpResponse<T | undefined> {
+    return new HttpResponse(body, location === undefined ? { status: 201 } : { status: 201, headers: { location } })
+  }
+
+  /** `202 Accepted`, typed with its body when there is one. */
+  static accepted(): HttpResponse<undefined>
+  static accepted<T>(body: T): HttpResponse<T>
+  static accepted<T>(body?: T): HttpResponse<T | undefined> {
+    return new HttpResponse(body, { status: 202 })
+  }
+
+  /** `204 No Content`. */
+  static noContent(): HttpResponse<undefined> {
+    return new HttpResponse(undefined, { status: 204 })
+  }
+
+  /** A redirect (`302 Found` by default) to `location`. */
+  static redirect(location: string, status: RedirectStatus = 302): HttpResponse<undefined> {
+    return new HttpResponse(undefined, { status, headers: { location } })
+  }
+
+  /**
+   * Sends a file from disk (`string` path or `file:` URL) or a `Blob` / `File`, streamed with
+   * `Content-Length`, `Content-Type` (from the extension, see `contentTypeFor`), `Last-Modified`,
+   * `ETag` and `Accept-Ranges`. Conditional requests answer 304 / 412 and single byte ranges 206
+   * (416 when unsatisfiable). A missing file answers 404.
+   *
+   * ```ts
+   * @Get('/reports/:name')
+   * download(@Param('name') name: string) {
+   *   // `root` confines the path: '../../etc/passwd' answers 404
+   *   return HttpResponse.file(name, { root: REPORTS_DIR, filename: `rapport ${name}` })
+   * }
+   * ```
+   *
+   * Never pass a path built from the request without `root`.
+   */
+  static file(file: string | URL | Blob, options?: FileResponseOptions): HttpResponse<FileBody> {
+    return new HttpResponse(new FileBody(file, options))
+  }
+
+  /**
+   * Streams a Web `ReadableStream`, a Node.js `Readable` or an async iterable (async generator) of
+   * `Uint8Array` / `string` chunks. The source is read as the client receives the data
+   * (backpressure) and cancelled when the client disconnects; it runs in the request scope.
+   *
+   * ```ts
+   * @Get('/export.csv')
+   * export() {
+   *   return HttpResponse.stream(this.rows.csvLines(), { filename: 'export.csv' }) // text/csv; charset=utf-8
+   * }
+   * ```
+   */
+  static stream(source: StreamSource, options: StreamResponseOptions = {}): HttpResponse<ReadableStream<Uint8Array>> {
+    if (!isStreamSource(source)) {
+      throw new TypeError(
+        'HttpResponse.stream() expects a ReadableStream, a Node.js Readable or an async iterable of Uint8Array / string chunks',
+      )
+    }
+    const headers: Record<string, HeaderValue> = {
+      'content-type':
+        options.contentType ??
+        (options.filename === undefined ? undefined : contentTypeFor(options.filename)) ??
+        OCTET_STREAM,
+    }
+    const disposition = options.disposition ?? (options.filename === undefined ? undefined : 'attachment')
+    if (disposition !== undefined) headers['content-disposition'] = contentDisposition(options.filename, disposition)
+    return new HttpResponse(toByteStream(source), { headers })
+  }
+
+  /**
+   * An event stream (Server-Sent Events) on any route and any method: `200` unless `@HttpCode` or
+   * {@link withStatus} say otherwise (`EventSource` requires 200; `fetch()` clients read any status),
+   * even on `POST` routes. Same source, framing and lifecycle as an `@Sse()` route.
+   *
+   * ```ts
+   * @Post('/:id/assistant')
+   * assistant(@Param('id') id: string, @Body(Prompt) prompt: Prompt, @Ctx() ctx: HttpContext) {
+   *   return HttpResponse.sse(this.llm.complete(id, prompt, { signal: ctx.signal }))
+   * }
+   * ```
+   */
+  static sse(source: SseSource, options?: SseOptions): HttpResponse<SseBody> {
+    return new HttpResponse(new SseBody(source, options))
+  }
+
+  /** A copy of this response with `name` set to `value`. */
+  withHeader(name: string, value: HeaderValue): HttpResponse<T> {
+    return this.#copy({ headers: { ...this.headers, [name.toLowerCase()]: value } })
+  }
+
+  /** A copy of this response with another status. */
+  withStatus(status: number): HttpResponse<T> {
+    return this.#copy({ status })
+  }
+
+  /**
+   * A copy of this response setting a cookie, with the secure defaults (`Path=/; Secure; HttpOnly;
+   * SameSite=Lax`, see the plugin option `cookies.defaults`). It replaces a cookie with the same name,
+   * domain and path set by `ctx.setCookie()` or an earlier `withCookie()`.
+   *
+   * ```ts
+   * return HttpResponse.ok({ id: user.id }).withCookie('__Host-uid', user.id, { signed: true, maxAge: 8 * 3600 })
+   * ```
+   *
+   * The name, the value, the lifetime, the domain, the path and the size are checked now; the rules
+   * depending on the plugin (`secure` default with a prefix or `SameSite=None`, signing, the final
+   * size) when the response is sent: a violation then answers a generic 500, logged as
+   * `Invalid cookie "name": …`.
+   *
+   * @throws TypeError / RangeError for an invalid cookie.
+   */
+  withCookie(name: string, value: string, options: CookieOptions = {}): HttpResponse<T> {
+    checkCookie(name, value, options)
+    return this.#copy({ cookies: withCookie(this.cookies, { name, value, options: Object.freeze({ ...options }) }) })
+  }
+
+  /** A copy of this response clearing a cookie (see `ctx.clearCookie()`). */
+  withoutCookie(name: string, options: ClearCookieOptions = {}): HttpResponse<T> {
+    if (options === null || typeof options !== 'object') {
+      throw new TypeError(`Invalid cookie ${JSON.stringify(String(name))}: options must be an object`)
+    }
+    const { maxAge: _maxAge, expires: _expires, signed: _signed, ...clear } = options as CookieOptions
+    checkCookie(name, undefined, clear)
+    return this.#copy({ cookies: withCookie(this.cookies, { name, value: undefined, options: Object.freeze(clear) }) })
+  }
+
+  #copy(changes: HttpResponseInit): HttpResponse<T> {
+    const status = changes.status ?? this.status
+    return new HttpResponse(this.body, {
+      ...(status === undefined ? {} : { status }),
+      headers: changes.headers ?? this.headers,
+      cookies: changes.cookies ?? this.cookies,
+    })
+  }
+}
+
+const NO_COOKIES: readonly ResponseCookie[] = Object.freeze([])
+
+/** `cookies` with `cookie` added, replacing (in place) a cookie of the same name, domain and path. */
+function withCookie(cookies: readonly ResponseCookie[], cookie: ResponseCookie): ResponseCookie[] {
+  const key = givenCookieKey(cookie.name, cookie.options)
+  const index = cookies.findIndex(existing => givenCookieKey(existing.name, existing.options) === key)
+  if (index === -1) return [...cookies, cookie]
+  const result = [...cookies]
+  result[index] = cookie
+  return result
+}
+
+/** Whether `value` is an {@link HttpResponse} (also across duplicated package copies). */
+export function isHttpResponse(value: unknown): value is HttpResponse {
+  return (
+    value instanceof HttpResponse ||
+    (value !== null &&
+      typeof value === 'object' &&
+      (value as { constructor?: { name?: unknown } }).constructor?.name === 'HttpResponse' &&
+      'body' in value &&
+      'headers' in value)
+  )
+}

package/src/router.ts

@@ -0,0 +1,119 @@
+import type { RoutePath } from './path.ts'
+
+interface RouteNode<T> {
+  statics: Map<string, RouteNode<T>> | undefined
+  param: RouteNode<T> | undefined
+  /** Values of routes ending with a wildcard at this position, by method. */
+  wildcard: Map<string, T> | undefined
+  /** Values of routes ending at this node, by method. */
+  values: Map<string, T> | undefined
+}
+
+function createNode<T>(): RouteNode<T> {
+  return { statics: undefined, param: undefined, wildcard: undefined, values: undefined }
+}
+
+/**
+ * A segment trie mapping `(method, route path)` to values. Lookups prefer static segments over
+ * parameters over the wildcard, with backtracking (the same semantics as find-my-way), and are
+ * case-sensitive on the raw request path. Used by the built-in Node adapter for routing and by the
+ * plugin to tell `404 Not Found` from `405 Method Not Allowed`.
+ */
+export class RouteTable<T> {
+  readonly #root: RouteNode<T> = createNode()
+  #size = 0
+
+  /** Number of `(method, route)` entries. */
+  get size(): number {
+    return this.#size
+  }
+
+  /**
+   * Adds a value for `method` (upper case) and `route`.
+   *
+   * @returns the value already registered for the same method and shape, in which case nothing is
+   *   added.
+   */
+  add(method: string, route: RoutePath, value: T): T | undefined {
+    let node = this.#root
+    for (const segment of route.segments) {
+      if (segment.kind === 'static') {
+        node.statics ??= new Map()
+        let child = node.statics.get(segment.value)
+        if (child === undefined) {
+          child = createNode()
+          node.statics.set(segment.value, child)
+        }
+        node = child
+      } else if (segment.kind === 'param') {
+        node.param ??= createNode()
+        node = node.param
+      } else {
+        node.wildcard ??= new Map()
+        return this.#set(node.wildcard, method, value)
+      }
+    }
+    node.values ??= new Map()
+    return this.#set(node.values, method, value)
+  }
+
+  #set(map: Map<string, T>, method: string, value: T): T | undefined {
+    const existing = map.get(method)
+    if (existing !== undefined) return existing
+    map.set(method, value)
+    this.#size++
+    return undefined
+  }
+
+  /** The value of the most specific route matching `method` and the raw `path` (no query string). */
+  find(method: string, path: string): T | undefined {
+    if (path.charCodeAt(0) !== 47 /* / */) return undefined
+    if (path === '/') return this.#root.values?.get(method) ?? this.#root.wildcard?.get(method)
+    return search(this.#root, path.split('/'), 1, method)
+  }
+
+  /** Methods of every route matching the raw `path`, sorted. */
+  allowedMethods(path: string): string[] {
+    const methods = new Set<string>()
+    if (path.charCodeAt(0) === 47 /* / */) {
+      if (path === '/') {
+        addKeys(methods, this.#root.values)
+        addKeys(methods, this.#root.wildcard)
+      } else {
+        collect(this.#root, path.split('/'), 1, methods)
+      }
+    }
+    return [...methods].sort()
+  }
+}
+
+function search<T>(node: RouteNode<T>, segments: readonly string[], index: number, method: string): T | undefined {
+  if (index === segments.length) return node.values?.get(method)
+  const segment = segments[index] as string
+  const child = node.statics?.get(segment)
+  if (child !== undefined) {
+    const found = search(child, segments, index + 1, method)
+    if (found !== undefined) return found
+  }
+  if (segment !== '' && node.param !== undefined) {
+    const found = search(node.param, segments, index + 1, method)
+    if (found !== undefined) return found
+  }
+  return node.wildcard?.get(method)
+}
+
+function collect<T>(node: RouteNode<T>, segments: readonly string[], index: number, methods: Set<string>): void {
+  if (index === segments.length) {
+    addKeys(methods, node.values)
+    return
+  }
+  const segment = segments[index] as string
+  const child = node.statics?.get(segment)
+  if (child !== undefined) collect(child, segments, index + 1, methods)
+  if (segment !== '' && node.param !== undefined) collect(node.param, segments, index + 1, methods)
+  addKeys(methods, node.wildcard)
+}
+
+function addKeys(target: Set<string>, source: Map<string, unknown> | undefined): void {
+  if (source !== undefined) for (const key of source.keys()) target.add(key)
+}