@znight/http 0.0.0-stage → 0.1.1

package/src/metadata.ts

@@ -0,0 +1,162 @@
+/**
+ * HTTP section of the runtime metadata (`metadata.extensions.http`), generated by the compiler
+ * extension `@znight/http/compiler` and consumed by {@link HttpPlugin}. See
+ * docs/internals/architecture.md §9.1. Hand-written metadata (tests) must follow the same shape.
+ */
+import type { Token } from '@znight/core'
+import type { HttpContext } from './context.ts'
+
+/** Route methods. `ALL` registers the route for GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'ALL'
+
+/**
+ * Where a handler parameter comes from (`file` / `files`: `@UploadedFile` / `@UploadedFiles`, the
+ * `name` being the multipart field; `cookie` / `signedCookie`: `@Cookie` / `@SignedCookie`, the
+ * `name` being the cookie name).
+ */
+export type HttpParamSource =
+  | 'param'
+  | 'query'
+  | 'body'
+  | 'headers'
+  | 'request'
+  | 'response'
+  | 'context'
+  | 'file'
+  | 'files'
+  | 'cookie'
+  | 'signedCookie'
+
+/** A handler parameter (informational: extraction, coercion and validation happen in `invoke`). */
+export interface HttpParamDefinition {
+  /** Position in the handler signature. */
+  readonly index: number
+  readonly source: HttpParamSource
+  /** Parameter / query key / header name (lower case) / multipart field. Absent: the whole object (every field). */
+  readonly name?: string
+  /** Serialised declared type (`number`, `string[]`, `'asc' | 'desc'`...). */
+  readonly type?: string
+  readonly optional?: boolean
+  /** `true` when the value is validated with a schema. */
+  readonly schema?: boolean
+}
+
+/**
+ * Files accepted by an upload parameter (`@UploadedFile` / `@UploadedFiles`). The plugin enforces
+ * these rules while the multipart body is read; the presence of required files is checked by
+ * `invoke` (the `uploads` helpers).
+ */
+export interface HttpUploadDefinition {
+  /** Multipart field. Absent: files of any field. */
+  readonly field?: string
+  /** `true` for `@UploadedFiles` (several files). */
+  readonly multiple?: boolean
+  /** `true` when a file must be sent (informational, checked by `invoke`). */
+  readonly required?: boolean
+  /** Maximum size of each file in bytes (`Infinity`: no limit). Default: plugin `uploads.maxFileSize`. */
+  readonly maxSize?: number
+  /** Maximum number of files (`@UploadedFiles`). Default: plugin `uploads.maxFiles` (1 for `@UploadedFile`). */
+  readonly maxFiles?: number
+  /** Accepted media types (`image/png`, `image/*`), compared with the type declared by the client. */
+  readonly mimeTypes?: readonly string[]
+}
+
+/** Options of an `@Sse` route (`HttpRouteDefinition.sse`). */
+export interface HttpSseDefinition {
+  /** Heartbeat interval in ms (≥ 1 000); `0` disables it. Absent: the plugin option `sse.heartbeat`. */
+  readonly heartbeat?: number
+  /** `retry` sent first (ms). Absent: the plugin option `sse.retry`. */
+  readonly retry?: number
+  /** The stream ends gracefully after this many ms (≥ 1 000). */
+  readonly maxDuration?: number
+}
+
+/** A route: one decorated method of a controller. */
+export interface HttpRouteDefinition {
+  readonly method: HttpMethod
+  /** Path of the route decorator, normalised (`/:id`). */
+  readonly path: string
+  /** `joinPaths(controller.basePath, path)` (without the plugin `prefix`). */
+  readonly fullPath: string
+  /** Name of the handler method. */
+  readonly handler: string
+  /** `@HttpCode(status)`. */
+  readonly status?: number
+  /** `@Header(name, value)` entries (names in lower case). */
+  readonly headers?: Readonly<Record<string, string>>
+  /**
+   * Route metadata (`createRouteDecorator`), merged over the controller metadata at runtime, one
+   * decision per group: the route's entry of a group replaces the controller's entries of that group
+   * (see {@link HttpMetadata.groups}).
+   */
+  readonly meta: Readonly<Record<string, unknown>>
+  /** Route guards (provider tokens), run after global and controller guards. */
+  readonly guards: readonly Token[]
+  /** Route interceptors (provider tokens), innermost. */
+  readonly interceptors: readonly Token[]
+  readonly params: readonly HttpParamDefinition[]
+  /**
+   * `@BodyLimit` (route or controller): maximum body size in bytes (`Infinity`: no limit). Default:
+   * the plugin `bodyLimit`, or for upload routes the sum of the file limits plus `bodyLimit`.
+   */
+  readonly bodyLimit?: number
+  /**
+   * Upload rules (one per `@UploadedFile` / `@UploadedFiles` parameter). Routes with uploads parse
+   * `multipart/form-data` bodies before the interceptors and answer 415 to other non-empty bodies.
+   */
+  readonly uploads?: readonly HttpUploadDefinition[]
+  /** `true` when the handler takes `@Res()` and writes the response itself. */
+  readonly rawResponse?: boolean
+  /**
+   * `@Sse` route (GET only): the handler result (an `AsyncIterable`, an `Iterable` or a
+   * `ReadableStream` of `SseEvent`) is served as an event stream; an `HttpResponse` or a Web
+   * `Response` is sent as usual. `{}` without options.
+   */
+  readonly sse?: HttpSseDefinition
+  /**
+   * Calls the handler: extracts, coerces and validates every argument from the context, then calls
+   * the method on the controller instance. May return a promise.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: generated functions take the concrete controller class
+  readonly invoke: (controller: any, ctx: HttpContext) => unknown
+}
+
+/** A controller: a provider whose methods are routes. */
+export interface HttpControllerDefinition {
+  /** Provider token of the controller class. */
+  readonly token: Token
+  /** Normalised base path (`/users`, `/` when absent). */
+  readonly basePath: string
+  /** Controller guards (provider tokens). */
+  readonly guards: readonly Token[]
+  /** Controller interceptors (provider tokens). */
+  readonly interceptors: readonly Token[]
+  /** Controller metadata (`createRouteDecorator` on the class). */
+  readonly meta: Readonly<Record<string, unknown>>
+  readonly routes: readonly HttpRouteDefinition[]
+}
+
+/** A route decorator group (`createRouteDecorator(key, { group, required })`). */
+export interface HttpRouteGroupDefinition {
+  /** Keys of the decorators of the group, sorted. */
+  readonly keys: readonly string[]
+  /** Every route must carry a decision of the group. */
+  readonly required: boolean
+}
+
+/** `metadata.extensions.http`. */
+export interface HttpMetadata {
+  readonly controllers: readonly HttpControllerDefinition[]
+  /**
+   * Route decorator groups that need to be known at runtime (required, holding several keys, or
+   * named differently from their key): group → `{ keys, required }`. A key belongs to one group at
+   * most; a key listed nowhere is its own group. Absent when no group needs it.
+   */
+  readonly groups?: Readonly<Record<string, HttpRouteGroupDefinition>>
+}
+
+declare module '@znight/core' {
+  interface ZnightExtensionsMetadata {
+    readonly http?: HttpMetadata
+  }
+}

package/src/mime.ts

@@ -0,0 +1,157 @@
+/**
+ * Media types of files: a small extension table for downloads and `type/*` patterns for upload
+ * filters. This module is **pure** (no imports, no I/O): the compiler extension validates the
+ * `mimeTypes` option of `@UploadedFile` with it.
+ */
+
+/** Common extensions → media type (text types get `charset=utf-8` in {@link contentTypeFor}). */
+const TYPES: Readonly<Record<string, string>> = {
+  // text
+  txt: 'text/plain',
+  text: 'text/plain',
+  log: 'text/plain',
+  md: 'text/markdown',
+  markdown: 'text/markdown',
+  csv: 'text/csv',
+  tsv: 'text/tab-separated-values',
+  htm: 'text/html',
+  html: 'text/html',
+  css: 'text/css',
+  xml: 'application/xml',
+  js: 'text/javascript',
+  mjs: 'text/javascript',
+  cjs: 'text/javascript',
+  json: 'application/json',
+  map: 'application/json',
+  jsonld: 'application/ld+json',
+  webmanifest: 'application/manifest+json',
+  yaml: 'application/yaml',
+  yml: 'application/yaml',
+  ics: 'text/calendar',
+  vtt: 'text/vtt',
+  // images
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  svg: 'image/svg+xml',
+  ico: 'image/x-icon',
+  bmp: 'image/bmp',
+  tif: 'image/tiff',
+  tiff: 'image/tiff',
+  heic: 'image/heic',
+  // audio / video
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  oga: 'audio/ogg',
+  flac: 'audio/flac',
+  aac: 'audio/aac',
+  m4a: 'audio/mp4',
+  opus: 'audio/opus',
+  mp4: 'video/mp4',
+  m4v: 'video/mp4',
+  webm: 'video/webm',
+  ogv: 'video/ogg',
+  mov: 'video/quicktime',
+  avi: 'video/x-msvideo',
+  mkv: 'video/x-matroska',
+  // fonts
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  // documents and archives
+  pdf: 'application/pdf',
+  rtf: 'application/rtf',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  odt: 'application/vnd.oasis.opendocument.text',
+  ods: 'application/vnd.oasis.opendocument.spreadsheet',
+  odp: 'application/vnd.oasis.opendocument.presentation',
+  epub: 'application/epub+zip',
+  zip: 'application/zip',
+  gz: 'application/gzip',
+  tgz: 'application/gzip',
+  tar: 'application/x-tar',
+  bz2: 'application/x-bzip2',
+  xz: 'application/x-xz',
+  '7z': 'application/x-7z-compressed',
+  rar: 'application/vnd.rar',
+  wasm: 'application/wasm',
+  bin: 'application/octet-stream',
+}
+
+/** Default media type of files without a known extension. */
+export const OCTET_STREAM = 'application/octet-stream'
+
+/**
+ * Media type of a file name from its extension (`report.pdf` → `application/pdf`, text types with
+ * `; charset=utf-8`), `undefined` when the extension is unknown.
+ */
+export function contentTypeFor(filename: string): string | undefined {
+  const dot = filename.lastIndexOf('.')
+  if (dot === -1 || dot === filename.length - 1) return undefined
+  const separator = Math.max(filename.lastIndexOf('/'), filename.lastIndexOf('\\'))
+  if (dot < separator) return undefined
+  const extension = filename.slice(dot + 1).toLowerCase()
+  // own keys only: `.constructor` / `.__proto__` must not resolve to `Object.prototype` members
+  if (!Object.hasOwn(TYPES, extension)) return undefined
+  const type = TYPES[extension] as string
+  return isTextual(type) ? `${type}; charset=utf-8` : type
+}
+
+function isTextual(type: string): boolean {
+  return (
+    type.startsWith('text/') ||
+    type === 'application/json' ||
+    type === 'application/ld+json' ||
+    type === 'application/manifest+json' ||
+    type === 'application/xml' ||
+    type === 'application/yaml' ||
+    type === 'image/svg+xml'
+  )
+}
+
+/** `type/subtype` token characters (RFC 9110). */
+const TOKEN = "[!#$%&'*+\\-.^_`|~0-9A-Za-z]+"
+const MEDIA_TYPE = new RegExp(`^${TOKEN}/${TOKEN}$`)
+
+/**
+ * Whether `pattern` is a valid media type filter: `type/subtype`, `type/*` or `*\/*`
+ * (case-insensitive, without parameters).
+ */
+export function isMediaTypePattern(pattern: string): boolean {
+  if (!MEDIA_TYPE.test(pattern)) return false
+  const [type, subtype] = pattern.split('/') as [string, string]
+  // `*` is only a wildcard on its own: `image/*`, `*/*` (`*/png` and `image/png*` are rejected)
+  if (type.includes('*') && type !== '*') return false
+  if (subtype.includes('*') && subtype !== '*') return false
+  return type !== '*' || subtype === '*'
+}
+
+/** The essence of a media type: lower-case `type/subtype` without parameters (`Text/Plain; charset=x` → `text/plain`). */
+export function mediaTypeEssence(type: string): string {
+  const separator = type.indexOf(';')
+  return (separator === -1 ? type : type.slice(0, separator)).trim().toLowerCase()
+}
+
+/** Whether the media type `type` (parameters ignored) matches one of `patterns` (`image/png`, `image/*`, `*\/*`). */
+export function matchesMediaType(type: string, patterns: readonly string[]): boolean {
+  const essence = mediaTypeEssence(type)
+  const slash = essence.indexOf('/')
+  if (slash <= 0 || slash === essence.length - 1) return false
+  const major = essence.slice(0, slash)
+  for (const raw of patterns) {
+    const pattern = raw.toLowerCase()
+    if (pattern === '*/*' || pattern === essence) return true
+    if (pattern.endsWith('/*') && pattern.slice(0, -2) === major) return true
+  }
+  return false
+}