@znight/http 0.0.0-stage → 0.1.0

package/src/headers.ts

@@ -0,0 +1,39 @@
+/** Validation of HTTP header names and values (internal). */
+import type { HeaderValue } from './exceptions.ts'
+
+/** A field name: an RFC 9110 token. */
+const NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+
+/**
+ * Characters a field value may not contain: everything but HTAB, visible ASCII, space and obs-text
+ * (what Node.js `validateHeaderValue` accepts; Fetch `Headers` are less strict, Latin-1 only).
+ */
+const INVALID_VALUE = /[^\t\x20-\x7e\x80-\xff]/
+
+/** Whether `name` is a valid header name. */
+export function isHeaderName(name: string): boolean {
+  return NAME.test(name)
+}
+
+/** Whether `value` can be sent as a header value by every adapter (no CR / LF, Latin-1 only...). */
+export function isHeaderValue(value: string): boolean {
+  return !INVALID_VALUE.test(value)
+}
+
+/**
+ * The name of the first header whose name or value cannot be sent (`ctx.setHeader('x', 'a\r\nb')`,
+ * a non Latin-1 file name...), `undefined` when every header is valid.
+ */
+export function findInvalidHeader(headers: Readonly<Record<string, HeaderValue | undefined>>): string | undefined {
+  for (const name of Object.keys(headers)) {
+    const value = headers[name]
+    if (value === undefined) continue
+    if (!NAME.test(name)) return name
+    if (typeof value === 'string') {
+      if (INVALID_VALUE.test(value)) return name
+    } else {
+      for (const item of value) if (INVALID_VALUE.test(String(item))) return name
+    }
+  }
+  return undefined
+}

package/src/index.ts

@@ -0,0 +1,185 @@
+/**
+ * `@znight/http`: controllers, routing, guards, interceptors and validation for Znight, with a
+ * built-in `node:http` server and Fastify / Express / Hono adapters (subpath exports).
+ */
+export type {
+  AdapterCloseOptions,
+  AdapterHandler,
+  AdapterReply,
+  AdapterRequest,
+  AdapterRoute,
+  FallbackHandler,
+  HttpAdapter,
+  HttpServerAddress,
+  InjectRequest,
+  InjectResponse,
+  InjectStreamOptions,
+  InjectStreamRequest,
+  InjectStreamResponse,
+  ReplyBody,
+} from './adapter.ts'
+export type { HttpContext, HttpRouteInfo, RequestAbortKind, RequestId } from './context.ts'
+export type {
+  ClearCookieOptions,
+  CookieDefaults,
+  CookieOptions,
+  ResponseCookie,
+  SetCookieInfo,
+} from './cookies.ts'
+export type { CorsOptions, CorsOrigin } from './cors.ts'
+export type { EnforcementMode } from './decisions.ts'
+export type { EventChannelOptions } from './event-channel.ts'
+export type { InjectSseResponse, InjectSseWaitOptions } from './inject-sse.ts'
+export type {
+  CallHandler,
+  CanActivate,
+  ExceptionMapper,
+  ExceptionMapperClass,
+  ExceptionMapperResult,
+  GuardClass,
+  GuardEnforcement,
+  HttpInterceptor,
+  HttpInterceptorClass,
+} from './interfaces.ts'
+export type {
+  HttpControllerDefinition,
+  HttpMetadata,
+  HttpMethod,
+  HttpParamDefinition,
+  HttpParamSource,
+  HttpRouteDefinition,
+  HttpRouteGroupDefinition,
+  HttpSseDefinition,
+  HttpUploadDefinition,
+} from './metadata.ts'
+export type { PluginHttpRoutes, PluginHttpRoutesContext, PluginRoute } from './plugin-routes.ts'
+export type { TrustProxy } from './proxy.ts'
+export type { HstsOptions, SecurityHeadersOptions } from './security-headers.ts'
+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 NodeAdapter, type NodeAdapterOptions, nodeAdapter } from './adapters/node.ts'
+export { isJsonType, type MediaType, parseBody, parseMediaType } from './body.ts'
+export { type Coercer, type Coercers, coerce } from './coerce.ts'
+export { RequestAbortedError } from './context.ts'
+export { parseCookieHeader, parseSetCookie, serializeClearCookie, serializeCookie } from './cookies.ts'
+export {
+  All,
+  Body,
+  BodyLimit,
+  Controller,
+  type ControllerOptions,
+  Cookie,
+  Ctx,
+  createRouteDecorator,
+  Delete,
+  Get,
+  Head,
+  Header,
+  Headers,
+  HttpCode,
+  Options,
+  Param,
+  Patch,
+  Post,
+  Put,
+  Query,
+  Req,
+  Res,
+  type RouteDecorator,
+  type RouteDecoratorArgs,
+  type RouteDecoratorInfo,
+  type RouteDecoratorOptions,
+  type RouteMetaEntry,
+  SignedCookie,
+  Sse,
+  UploadedFile,
+  UploadedFiles,
+  UseGuard,
+  UseInterceptor,
+  Validate,
+} from './decorators.ts'
+export { EventChannel } from './event-channel.ts'
+export {
+  BadGatewayException,
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+  GatewayTimeoutException,
+  GoneException,
+  type HeaderValue,
+  type HttpErrorBody,
+  HttpException,
+  type HttpExceptionOptions,
+  InternalServerErrorException,
+  isHttpException,
+  MethodNotAllowedException,
+  NotFoundException,
+  NotImplementedException,
+  PayloadTooLargeException,
+  ServiceUnavailableException,
+  TooManyRequestsException,
+  toIssueDetail,
+  UnauthorizedException,
+  UnprocessableEntityException,
+  UnsupportedMediaTypeException,
+  ValidationException,
+  type ValidationIssueDetail,
+} from './exceptions.ts'
+export {
+  type ByteRange,
+  type ContentDispositionType,
+  contentDisposition,
+  type FileBody,
+  type FileResponseOptions,
+  parseRange,
+} from './files.ts'
+export { contentTypeFor, matchesMediaType } from './mime.ts'
+export {
+  type ExceptionMapperRef,
+  type GuardRef,
+  type HttpCookieOptions,
+  HttpPlugin,
+  type HttpPluginOptions,
+  type HttpRouteSummary,
+  type HttpSseOptions,
+  type InterceptorRef,
+  type TrailingSlashPolicy,
+} from './plugin.ts'
+export { parseQuery, type QueryRecord } from './query.ts'
+export {
+  HttpResponse,
+  type HttpResponseInit,
+  isHttpResponse,
+  type RedirectStatus,
+  type StreamResponseOptions,
+} from './response.ts'
+export { formatByteSize, parseByteSize } from './size.ts'
+export { encodeSseEvent } from './sse.ts'
+export { parseSseStream } from './sse-parse.ts'
+export {
+  type InferSchemaInput,
+  type InferSchemaOutput,
+  isStandardSchema,
+  type StandardSchemaV1,
+  type StandardSchemaV1FailureResult,
+  type StandardSchemaV1Issue,
+  type StandardSchemaV1Options,
+  type StandardSchemaV1PathSegment,
+  type StandardSchemaV1Props,
+  type StandardSchemaV1Result,
+  type StandardSchemaV1SuccessResult,
+  type StandardSchemaV1Types,
+} from './standard-schema.ts'
+export { isValidStatus, statusText } from './status.ts'
+export { HttpTokens } from './tokens.ts'
+export {
+  type UploadedFileOptions,
+  type UploadedFilesOptions,
+  type UploadLimits,
+  type Uploads,
+  uploads,
+} from './uploads.ts'
+export { validate } from './validate.ts'

package/src/inject-sse.ts

@@ -0,0 +1,309 @@
+/**
+ * `injectSse()`: an in-memory `EventSource` for tests, on top of `injectStream()`. Events are read
+ * only when asked for (`next()`, `take()`, iteration, `done`), so a test controls the pace of the
+ * client. Opening never waits forever ({@link OPEN_TIMEOUT_MS} per step): without response headers
+ * it fails (the request is aborted); without a first chunk (an `@Sse` stream sends `retry` or a
+ * comment at once, a hand-written or proxied one may stay quiet) the stream is open anyway, and the
+ * read goes on in the background.
+ */
+import type { InjectStreamOptions, InjectStreamRequest, InjectStreamResponse } from './adapter.ts'
+import type { SetCookieInfo } from './cookies.ts'
+
+import { isEventStreamType } from './adapters/shared.ts'
+import { parseWith, type SseItem, type SseMessage, SseParser } from './sse-parse.ts'
+
+/** Options of {@link InjectSseResponse.next} and {@link InjectSseResponse.take}. */
+export interface InjectSseWaitOptions {
+  /** Maximum wait for each event (ms). Default: 2 000. */
+  readonly timeoutMs?: number
+}
+
+/** The response of `injectSse()`: an event stream read in memory, like `EventSource` would. */
+export interface InjectSseResponse extends AsyncIterable<SseMessage>, AsyncDisposable {
+  readonly status: number
+  readonly headers: Record<string, string | string[]>
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>
+  /** `''` for an event stream; otherwise the whole body, read to its end (an error, a 204...). */
+  readonly body: string
+  /** `JSON.parse(body)`. */
+  json<T = unknown>(): T
+  /** The next event (comments skipped). Rejects on timeout (default 2 000 ms) or when the stream ended. */
+  next(options?: InjectSseWaitOptions): Promise<SseMessage>
+  /** The next `count` events (the timeout applies to each). */
+  take(count: number, options?: InjectSseWaitOptions): Promise<SseMessage[]>
+  /** Comments received so far (heartbeats are `''`). */
+  readonly comments: readonly string[]
+  /** What a browser would send as `Last-Event-ID` on reconnection. */
+  readonly lastEventId: string
+  /** The last `retry` received (ms). */
+  readonly retry: number | undefined
+  /** Resolves when the server ends the stream (reading the remaining events, which stay available to `next()`). */
+  readonly done: Promise<void>
+  /** Disconnects (cancels the body): the server sees a client disconnect. Idempotent. */
+  close(): Promise<void>
+  /** Reconnects like `EventSource`: closes this stream and sends the same request plus `last-event-id`. */
+  reconnect(): Promise<InjectSseResponse>
+}
+
+const DEFAULT_TIMEOUT_MS = 2_000
+/** How long opening waits for the response headers, then for the first chunk of an event stream (ms). */
+const OPEN_TIMEOUT_MS = 2_000
+const DECODER = new TextDecoder()
+
+type InjectStream = (request: InjectStreamOptions) => Promise<InjectStreamResponse>
+
+/**
+ * Opens an event stream with `injectStream` (adds `accept: text/event-stream` when absent), waiting
+ * at most `openTimeoutMs` for the response headers, then at most `openTimeoutMs` for the first chunk.
+ */
+export async function openInjectSse(
+  injectStream: InjectStream,
+  request: InjectStreamOptions,
+  openTimeoutMs: number = OPEN_TIMEOUT_MS,
+): Promise<InjectSseResponse> {
+  if (request === null || typeof request !== 'object') throw new TypeError('injectSse() expects a request object')
+  const headers: Record<string, string> = { ...request.headers }
+  if (!Object.keys(headers).some(name => name.toLowerCase() === 'accept')) headers['accept'] = 'text/event-stream'
+  const sent: InjectStreamRequest = { ...request, method: request.method ?? 'GET', headers }
+  const response = await answered(injectStream, sent, openTimeoutMs)
+  if (!isEventStreamType(response.headers['content-type'])) {
+    const body = await readText(response.body)
+    return new SseClient(injectStream, sent, response, body, openTimeoutMs)
+  }
+  const client = new SseClient(injectStream, sent, response, '', openTimeoutMs)
+  // the first chunk makes `retry` and `comments` known at once; a quiet stream must not hang the test
+  await client.ready()
+  return client
+}
+
+/**
+ * `injectStream(request)`, waiting at most `ms` for the response headers. Past it, the request is
+ * aborted (a late response is cancelled: the server sees a client disconnect) and opening fails
+ * with an error naming the request, instead of hanging the test.
+ */
+async function answered(
+  injectStream: InjectStream,
+  request: InjectStreamRequest,
+  ms: number,
+): Promise<InjectStreamResponse> {
+  const abort = new AbortController()
+  const signal = request.signal === undefined ? abort.signal : AbortSignal.any([request.signal, abort.signal])
+  const pending = injectStream({ ...request, signal })
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<undefined>(resolve => {
+    timer = setTimeout(() => resolve(undefined), ms)
+  })
+  const response = await Promise.race([pending, timeout]).finally(() => clearTimeout(timer))
+  if (response !== undefined) return response
+  const message = `injectSse(): no response from ${describe(request)} within ${ms} ms`
+  abort.abort(new Error(message))
+  void pending.then(
+    late => late.body.cancel().catch(() => undefined),
+    () => undefined,
+  )
+  throw new Error(
+    `${message}: the handler has not answered, or the adapter holds the response headers until the first byte of the body`,
+  )
+}
+
+/** `GET /orders/o-1/events`. */
+function describe(request: InjectStreamRequest): string {
+  return `${(request.method ?? 'GET').toUpperCase()} ${request.url}`
+}
+
+async function readText(body: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = body.getReader()
+  let text = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) return text + DECODER.decode()
+    text += DECODER.decode(value, { stream: true })
+  }
+}
+
+class SseClient implements InjectSseResponse {
+  readonly status: number
+  readonly headers: Record<string, string | string[]>
+  readonly cookies: Readonly<Record<string, SetCookieInfo>>
+  readonly body: string
+  readonly #injectStream: InjectStream
+  readonly #request: InjectStreamRequest
+  readonly #openTimeoutMs: number
+  readonly #parser = new SseParser()
+  readonly #items: AsyncIterableIterator<SseItem> | undefined
+  readonly #events: SseMessage[] = []
+  readonly #comments: string[] = []
+  #retry: number | undefined
+  /** Whether an item (event, comment, `retry`) was read since the stream opened. */
+  #received = false
+  #ended: boolean
+  #failure: unknown
+  #reading: Promise<void> | undefined
+  #closing: Promise<void> | undefined
+  #draining: Promise<void> | undefined
+
+  constructor(
+    injectStream: InjectStream,
+    request: InjectStreamRequest,
+    response: InjectStreamResponse,
+    body: string,
+    openTimeoutMs: number,
+  ) {
+    this.#injectStream = injectStream
+    this.#request = request
+    this.#openTimeoutMs = openTimeoutMs
+    this.status = response.status
+    this.headers = response.headers
+    this.cookies = response.cookies
+    this.body = body
+    const stream = isEventStreamType(response.headers['content-type'])
+    this.#ended = !stream
+    this.#items = stream ? parseWith(this.#parser, response.body) : undefined
+  }
+
+  get comments(): readonly string[] {
+    return [...this.#comments]
+  }
+
+  get lastEventId(): string {
+    return this.#parser.lastEventId
+  }
+
+  get retry(): number | undefined {
+    return this.#retry
+  }
+
+  get done(): Promise<void> {
+    this.#draining ??= (async (): Promise<void> => {
+      while (!this.#ended) await this.#read()
+    })()
+    return this.#draining
+  }
+
+  json<T = unknown>(): T {
+    return JSON.parse(this.body) as T
+  }
+
+  /**
+   * Reads the first item (the preamble every `@Sse` stream starts with, so that `retry` is known),
+   * waiting at most the open timeout: the read of a quiet stream goes on in the background.
+   */
+  async ready(): Promise<void> {
+    await this.#readWithin(this.#openTimeoutMs)
+  }
+
+  async next(options: InjectSseWaitOptions = {}): Promise<SseMessage> {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    if (!(timeoutMs >= 0)) throw new TypeError('injectSse(): timeoutMs must be a number ≥ 0')
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      const event = this.#events.shift()
+      if (event !== undefined) return event
+      if (this.#ended) {
+        throw new Error(`injectSse(): the event stream of ${this.#describe()} ended`, {
+          ...(this.#failure === undefined ? {} : { cause: this.#failure }),
+        })
+      }
+      const remaining = deadline - Date.now()
+      if (remaining <= 0 || !(await this.#readWithin(remaining))) {
+        const quiet = this.#received ? '' : ' (the stream has sent nothing since it opened)'
+        throw new Error(`injectSse(): no event received within ${timeoutMs} ms from ${this.#describe()}${quiet}`)
+      }
+    }
+  }
+
+  async take(count: number, options?: InjectSseWaitOptions): Promise<SseMessage[]> {
+    if (!Number.isSafeInteger(count) || count < 0) throw new TypeError('injectSse(): take() expects an integer ≥ 0')
+    const events: SseMessage[] = []
+    while (events.length < count) events.push(await this.next(options))
+    return events
+  }
+
+  close(): Promise<void> {
+    if (this.#closing === undefined) {
+      this.#ended = true
+      this.#closing =
+        this.#items === undefined
+          ? Promise.resolve()
+          : (this.#items.return?.().then(() => undefined) ?? Promise.resolve())
+    }
+    return this.#closing
+  }
+
+  async reconnect(): Promise<InjectSseResponse> {
+    await this.close()
+    const headers: Record<string, string> = {}
+    for (const [name, value] of Object.entries(this.#request.headers ?? {})) {
+      if (name.toLowerCase() !== 'last-event-id') headers[name] = value
+    }
+    // EventSource only sends a non-empty last event id
+    if (this.lastEventId !== '') headers['last-event-id'] = this.lastEventId
+    return openInjectSse(this.#injectStream, { ...this.#request, headers }, this.#openTimeoutMs)
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<SseMessage> {
+    return {
+      next: async (): Promise<IteratorResult<SseMessage>> => {
+        for (;;) {
+          const event = this.#events.shift()
+          if (event !== undefined) return { done: false, value: event }
+          if (this.#ended) return { done: true, value: undefined }
+          await this.#read()
+        }
+      },
+      return: async (): Promise<IteratorResult<SseMessage>> => {
+        await this.close()
+        return { done: true, value: undefined }
+      },
+    }
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close()
+  }
+
+  /** Waits for the next item at most `ms` (the read goes on in the background); `false` on timeout. */
+  async #readWithin(ms: number): Promise<boolean> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timeout = new Promise<false>(resolve => {
+      timer = setTimeout(() => resolve(false), ms)
+    })
+    const outcome = await Promise.race([this.#read().then(() => true as const), timeout])
+    clearTimeout(timer)
+    return outcome
+  }
+
+  /** Reads one item (one read at a time, shared by concurrent callers). */
+  #read(): Promise<void> {
+    this.#reading ??= this.#readItem().finally(() => {
+      this.#reading = undefined
+    })
+    return this.#reading
+  }
+
+  async #readItem(): Promise<void> {
+    const items = this.#items
+    if (items === undefined || this.#ended) return
+    let result: IteratorResult<SseItem>
+    try {
+      result = await items.next()
+    } catch (error) {
+      this.#failure = error
+      this.#ended = true
+      return
+    }
+    if (result.done === true) {
+      this.#ended = true
+      return
+    }
+    const item = result.value
+    this.#received = true
+    if (item.type === 'comment') this.#comments.push(item.text)
+    else if (item.type === 'retry') this.#retry = item.retry
+    else this.#events.push({ event: item.event, data: item.data, id: item.id, json: item.json })
+  }
+
+  #describe(): string {
+    return describe(this.#request)
+  }
+}

package/src/interfaces.ts

@@ -0,0 +1,101 @@
+import type { HttpContext } from './context.ts'
+import type { RouteDecoratorInfo } from './decorators.ts'
+import type { HttpException } from './exceptions.ts'
+import type { HttpResponse } from './response.ts'
+
+/**
+ * A guard decides whether a request may reach the handler. Guards run in order: global (plugin
+ * options) → controller (`@UseGuard` on the class) → route. Returning `false` responds
+ * `403 Forbidden`; throw an `HttpException` (e.g. `UnauthorizedException`) for another response.
+ *
+ * ```ts
+ * @Injectable()
+ * export class RolesGuard implements CanActivate {
+ *   canActivate(ctx: HttpContext): boolean {
+ *     const roles = Roles.get(ctx) // route metadata from createRouteDecorator
+ *     return roles === undefined || roles.some(role => currentUser(ctx).roles.includes(role))
+ *   }
+ * }
+ * ```
+ */
+export interface CanActivate {
+  canActivate(ctx: HttpContext): boolean | Promise<boolean>
+}
+
+/** Runs the rest of the interceptor chain and the handler; resolves with the handler result. */
+export type CallHandler = () => Promise<unknown>
+
+/**
+ * Wraps the handler (after the guards). Interceptors run global → controller → route, the first one
+ * being the outermost. `next()` resolves with the handler result (before serialisation): return it,
+ * transform it, or return something else without calling `next()` (cache hit...).
+ *
+ * ```ts
+ * @Injectable()
+ * export class TimingInterceptor implements HttpInterceptor {
+ *   async intercept(ctx: HttpContext, next: CallHandler) {
+ *     const started = performance.now()
+ *     try {
+ *       return await next()
+ *     } finally {
+ *       ctx.setHeader('server-timing', `handler;dur=${performance.now() - started}`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface HttpInterceptor {
+  intercept(ctx: HttpContext, next: CallHandler): unknown
+}
+
+/** What an {@link ExceptionMapper} may return: `undefined` lets the next mapper (or the default) handle the error. */
+export type ExceptionMapperResult = HttpException | HttpResponse | Response | undefined
+
+/**
+ * Converts errors to responses. Mappers (plugin option `exceptionMappers`) are tried in order for
+ * every error of the pipeline, including `404`/`405`; the first one returning something wins. Return
+ * an `HttpException` to reuse the default error body, an `HttpResponse` or a Web `Response` for full
+ * control, `undefined` to pass.
+ *
+ * ```ts
+ * @Injectable()
+ * export class DomainErrorMapper implements ExceptionMapper {
+ *   map(error: unknown) {
+ *     if (error instanceof UserNotFoundError) return new NotFoundException(error.message)
+ *     return undefined
+ *   }
+ * }
+ * ```
+ */
+export interface ExceptionMapper {
+  map(error: unknown, ctx: HttpContext): ExceptionMapperResult | Promise<ExceptionMapperResult>
+}
+
+/**
+ * Static side of a guard class: the route decorators whose decisions the guard enforces. Read by
+ * `HttpPlugin` at boot: a route whose decision belongs to a required group (or to a group some
+ * guard enforces) must have a guard enforcing that group in its chain (ZNIGHT023 otherwise).
+ *
+ * ```ts
+ * @Injectable()
+ * export class AuthGuard implements CanActivate {
+ *   static readonly enforces = [Public, Authenticated, Roles]
+ *   canActivate(ctx: HttpContext) { ... }
+ * }
+ * ```
+ *
+ * Typed with {@link RouteDecoratorInfo} (not `RouteDecorator<unknown>`) so that `[Public, Roles]`
+ * stays assignable under `strictFunctionTypes`.
+ */
+export interface GuardEnforcement {
+  readonly enforces?: readonly RouteDecoratorInfo[]
+}
+
+/** A class producing {@link CanActivate} instances (for `@UseGuard` and plugin options). */
+export type GuardClass = (abstract new (...args: never[]) => CanActivate) & GuardEnforcement
+
+/** A class producing {@link HttpInterceptor} instances. */
+export type HttpInterceptorClass = abstract new (...args: never[]) => HttpInterceptor
+
+/** A class producing {@link ExceptionMapper} instances. */
+export type ExceptionMapperClass = abstract new (...args: never[]) => ExceptionMapper