@znight/http 0.0.0-stage → 0.1.0

package/src/standard-schema.ts

@@ -0,0 +1,81 @@
+/**
+ * A copy of the [Standard Schema v1](https://standardschema.dev) interface, flattened (no namespace,
+ * so the file stays erasable). Every compliant library (Zod, Valibot, ArkType, Effect Schema...)
+ * produces values assignable to {@link StandardSchemaV1}: no adapter and no dependency are needed.
+ */
+
+/** A schema implementing the Standard Schema v1 interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1Props<Input, Output>
+}
+
+/** The Standard Schema properties. */
+export interface StandardSchemaV1Props<Input = unknown, Output = Input> {
+  /** The version number of the standard. */
+  readonly version: 1
+  /** The vendor name of the schema library. */
+  readonly vendor: string
+  /** Validates an unknown input value (synchronously or not). */
+  readonly validate: (
+    value: unknown,
+    options?: StandardSchemaV1Options | undefined,
+  ) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>
+  /** Inferred types associated with the schema. */
+  readonly types?: StandardSchemaV1Types<Input, Output> | undefined
+}
+
+/** Options of {@link StandardSchemaV1Props.validate}. */
+export interface StandardSchemaV1Options {
+  /** Vendor-specific parameters. */
+  readonly libraryOptions?: Record<string, unknown> | undefined
+}
+
+/** Result of {@link StandardSchemaV1Props.validate}. */
+export type StandardSchemaV1Result<Output> = StandardSchemaV1SuccessResult<Output> | StandardSchemaV1FailureResult
+
+/** Successful validation: the (possibly transformed) output value. */
+export interface StandardSchemaV1SuccessResult<Output> {
+  readonly value: Output
+  readonly issues?: undefined
+}
+
+/** Failed validation. */
+export interface StandardSchemaV1FailureResult {
+  readonly issues: readonly StandardSchemaV1Issue[]
+}
+
+/** One validation issue. */
+export interface StandardSchemaV1Issue {
+  readonly message: string
+  readonly path?: readonly (PropertyKey | StandardSchemaV1PathSegment)[] | undefined
+}
+
+/** A path segment of an issue. */
+export interface StandardSchemaV1PathSegment {
+  readonly key: PropertyKey
+}
+
+/** Input and output types of a schema. */
+export interface StandardSchemaV1Types<Input = unknown, Output = Input> {
+  readonly input: Input
+  readonly output: Output
+}
+
+/** The input type of a schema. */
+export type InferSchemaInput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['input']
+
+/** The output type of a schema (what handlers receive). */
+export type InferSchemaOutput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['output']
+
+/** Whether `value` looks like a Standard Schema v1 (has a `~standard` object with a `validate` function). */
+export function isStandardSchema(value: unknown): value is StandardSchemaV1 {
+  if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return false
+  const props = (value as { '~standard'?: unknown })['~standard']
+  return (
+    props !== null &&
+    typeof props === 'object' &&
+    (props as { version?: unknown }).version === 1 &&
+    typeof (props as { validate?: unknown }).validate === 'function'
+  )
+}

package/src/status.ts

@@ -0,0 +1,78 @@
+/** Standard reason phrases (RFC 9110 and common extensions), used in error bodies. */
+const REASONS: Readonly<Record<number, string>> = {
+  100: 'Continue',
+  101: 'Switching Protocols',
+  102: 'Processing',
+  103: 'Early Hints',
+  200: 'OK',
+  201: 'Created',
+  202: 'Accepted',
+  203: 'Non-Authoritative Information',
+  204: 'No Content',
+  205: 'Reset Content',
+  206: 'Partial Content',
+  207: 'Multi-Status',
+  300: 'Multiple Choices',
+  301: 'Moved Permanently',
+  302: 'Found',
+  303: 'See Other',
+  304: 'Not Modified',
+  307: 'Temporary Redirect',
+  308: 'Permanent Redirect',
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  402: 'Payment Required',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  406: 'Not Acceptable',
+  407: 'Proxy Authentication Required',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  410: 'Gone',
+  411: 'Length Required',
+  412: 'Precondition Failed',
+  413: 'Payload Too Large',
+  414: 'URI Too Long',
+  415: 'Unsupported Media Type',
+  416: 'Range Not Satisfiable',
+  417: 'Expectation Failed',
+  418: "I'm a Teapot",
+  421: 'Misdirected Request',
+  422: 'Unprocessable Entity',
+  423: 'Locked',
+  424: 'Failed Dependency',
+  425: 'Too Early',
+  426: 'Upgrade Required',
+  428: 'Precondition Required',
+  429: 'Too Many Requests',
+  431: 'Request Header Fields Too Large',
+  451: 'Unavailable For Legal Reasons',
+  500: 'Internal Server Error',
+  501: 'Not Implemented',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+  505: 'HTTP Version Not Supported',
+  507: 'Insufficient Storage',
+  508: 'Loop Detected',
+  511: 'Network Authentication Required',
+}
+
+/** Reason phrase of `status` (`404` → `Not Found`), or a generic one for unknown codes. */
+export function statusText(status: number): string {
+  const reason = REASONS[status]
+  if (reason !== undefined) return reason
+  if (status >= 500) return 'Server Error'
+  return status >= 400 ? 'Client Error' : 'Unknown Status'
+}
+
+/** Whether `status` is an integer in the 100–599 range. */
+export function isValidStatus(status: unknown): status is number {
+  return typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599
+}
+
+/** Statuses whose responses never have a body. */
+export function isBodylessStatus(status: number): boolean {
+  return status === 204 || status === 304 || (status >= 100 && status < 200)
+}

package/src/stream.ts

@@ -0,0 +1,200 @@
+/**
+ * Web stream helpers shared by the pipeline and the adapters (internal): conversion of handler
+ * stream sources (`ReadableStream`, Node.js `Readable`, async iterables) to byte streams, tracking of
+ * response streams (request scope lifetime) and small constructors.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/**
+ * A stream source accepted by `HttpResponse.stream()`: a Web `ReadableStream`, a Node.js `Readable`
+ * or any async iterable (async generator...) of `Uint8Array` / `string` chunks (strings are encoded
+ * as UTF-8).
+ */
+export type StreamSource = ReadableStream<Uint8Array | string> | AsyncIterable<Uint8Array | string>
+
+/** Runs a function in a captured async context (`AsyncLocalStorage.snapshot()`). */
+export type ContextRunner = <R>(fn: () => R) => R
+
+const ENCODER = new TextEncoder()
+
+/** The current async context, to run stream reads in it later (the request scope of a response). */
+export function captureContext(): ContextRunner {
+  const snapshot = (AsyncLocalStorage as { snapshot?: () => ContextRunner }).snapshot
+  return typeof snapshot === 'function' ? snapshot() : run => run()
+}
+
+/** Whether `value` is a stream source (Web stream, Node.js readable or async iterable). */
+export function isStreamSource(value: unknown): value is StreamSource {
+  return (
+    value instanceof ReadableStream ||
+    (value !== null &&
+      typeof value === 'object' &&
+      typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function')
+  )
+}
+
+/** Byte streams created by {@link toByteStream} (already normalised: not wrapped again). */
+const BYTE_STREAMS = new WeakSet<ReadableStream<Uint8Array>>()
+
+/** Whether `stream` was created by {@link toByteStream}. */
+export function isByteStream(stream: ReadableStream<unknown>): boolean {
+  return BYTE_STREAMS.has(stream as ReadableStream<Uint8Array>)
+}
+
+/**
+ * Converts a stream source to a pull-based byte stream: the source is read only when the consumer
+ * reads (backpressure), strings are encoded as UTF-8, `ArrayBuffer`s and views are converted, empty
+ * chunks are skipped and cancelling the stream cancels the source (`iterator.return()`, which
+ * destroys a Node.js `Readable`; a `Readable` that was never read is destroyed directly).
+ *
+ * @throws TypeError (as a stream error) for chunks that are neither bytes nor strings.
+ */
+export function toByteStream(source: StreamSource): ReadableStream<Uint8Array> {
+  let iterator: AsyncIterator<unknown> | undefined
+  let reader: ChunkReader | undefined
+  const next = (): Promise<IteratorResult<unknown>> => {
+    if (source instanceof ReadableStream) {
+      const current: ChunkReader = reader ?? source.getReader()
+      reader = current
+      return current.read() as Promise<IteratorResult<unknown>>
+    }
+    iterator ??= source[Symbol.asyncIterator]()
+    return iterator.next()
+  }
+  const stream = new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        for (;;) {
+          const result = await next()
+          if (result.done === true) {
+            controller.close()
+            return
+          }
+          const chunk = toChunk(result.value)
+          if (chunk.byteLength > 0) {
+            controller.enqueue(chunk)
+            return
+          }
+        }
+      },
+      async cancel(reason) {
+        if (reader !== undefined) await reader.cancel(reason)
+        else if (source instanceof ReadableStream) await source.cancel(reason)
+        else if (iterator === undefined) {
+          // never read: an async generator has nothing to clean up, a Node.js `Readable` holds its resource
+          const destroyable = source as { destroy?: unknown }
+          if (typeof destroyable.destroy === 'function') destroyable.destroy()
+        } else await iterator.return?.(reason)
+      },
+    },
+    { highWaterMark: 0 },
+  )
+  BYTE_STREAMS.add(stream)
+  return stream
+}
+
+/** The part of a stream reader used here (Node.js and Bun declare different reader types). */
+interface ChunkReader {
+  read(): Promise<{ readonly done?: boolean; readonly value?: unknown }>
+  cancel(reason?: unknown): Promise<void>
+}
+
+function toChunk(value: unknown): Uint8Array {
+  if (value instanceof Uint8Array) return value
+  if (typeof value === 'string') return ENCODER.encode(value)
+  if (value instanceof ArrayBuffer) return new Uint8Array(value)
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+  throw new TypeError(
+    `Invalid stream chunk: expected a Uint8Array or a string, received ${value === null ? 'null' : typeof value}`,
+  )
+}
+
+/** The part of a byte stream reader used by {@link trackStream}. */
+interface ByteReader {
+  read(): Promise<{ readonly done?: boolean; readonly value?: Uint8Array | undefined }>
+  cancel(reason?: unknown): Promise<void>
+}
+
+/** A response stream whose completion is observed. */
+export interface TrackedStream {
+  readonly stream: ReadableStream<Uint8Array>
+  /**
+   * Resolves once the source was fully read (`undefined`), cancelled by the consumer (`undefined`:
+   * client disconnected, HEAD...) or failed (the error). Never rejects.
+   */
+  readonly done: Promise<unknown>
+}
+
+/**
+ * Wraps a response body so that the pipeline knows when it has been fully sent (or abandoned) and
+ * reads the source in `run` (the async context of the request scope, so that stream producers can
+ * use request-scoped providers). The wrapper is pull-based (no read-ahead): backpressure is the
+ * consumer's. A `Blob` is read through `blob.stream()`, opened on the first read only. `onCancel`
+ * runs when the consumer cancels the stream (the client left), before the source is cancelled.
+ */
+export function trackStream(
+  body: ReadableStream<Uint8Array> | Blob,
+  run: ContextRunner,
+  onCancel?: () => void,
+): TrackedStream {
+  let reader: ByteReader | undefined = body instanceof Blob ? undefined : body.getReader()
+  let settle: (error: unknown) => void = () => undefined
+  const done = new Promise<unknown>(resolve => {
+    settle = resolve
+  })
+  let finished = false
+  const finish = (error?: unknown): void => {
+    if (finished) return
+    finished = true
+    settle(error)
+  }
+  const stream = new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        let result: Awaited<ReturnType<ByteReader['read']>>
+        try {
+          result = await run(() => {
+            reader ??= (body as Blob).stream().getReader()
+            return reader.read()
+          })
+        } catch (error) {
+          finish(error)
+          throw error
+        }
+        if (result.done === true) {
+          controller.close()
+          finish()
+          return
+        }
+        controller.enqueue(result.value as Uint8Array)
+      },
+      async cancel(reason) {
+        onCancel?.()
+        try {
+          const current = reader
+          if (current !== undefined) await run(() => current.cancel(reason))
+        } catch {
+          // the source failed while being cancelled: nothing left to send anyway
+        } finally {
+          finish()
+        }
+      },
+    },
+    { highWaterMark: 0 },
+  )
+  return { stream, done }
+}
+
+/** A stream failing with `error` on first read. */
+export function failedStream(error: unknown): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.error(error)
+    },
+  })
+}
+
+/** Cancels a stream, ignoring failures (unconsumed response bodies). */
+export function discardStream(stream: ReadableStream<Uint8Array> | null | undefined): void {
+  if (stream instanceof ReadableStream && !stream.locked) stream.cancel().catch(() => undefined)
+}

package/src/tokens.ts

@@ -0,0 +1,21 @@
+import type { TypedToken } from '@znight/core'
+import type { HttpContext, RequestId } from './context.ts'
+import type { HttpPlugin } from './plugin.ts'
+
+/**
+ * Tokens of the values `@znight/http` supplies to the container. `HttpContext` and `RequestId` are
+ * request-scoped externals (declared in the package manifest): inject them in request-scoped
+ * providers or through `Lazy<HttpContext>`.
+ */
+export const HttpTokens: {
+  /** The {@link HttpContext} of the current request (request scope). */
+  readonly Context: TypedToken<HttpContext>
+  /** The id of the current request (request scope). */
+  readonly RequestId: TypedToken<RequestId>
+  /** The {@link HttpPlugin} instance (singleton). */
+  readonly Plugin: TypedToken<HttpPlugin>
+} = Object.freeze({
+  Context: '@znight/http#HttpContext',
+  RequestId: '@znight/http#RequestId',
+  Plugin: '@znight/http#HttpPlugin',
+})

package/src/uploads.ts

@@ -0,0 +1,176 @@
+/**
+ * File uploads: options of `@UploadedFile` / `@UploadedFiles`, the plugin-wide limits, the
+ * `uploads` helpers used by generated `invoke` functions, and the body plan of a route (body limit
+ * and multipart policy).
+ */
+import type { HttpContext } from './context.ts'
+import type { HttpRouteDefinition, HttpUploadDefinition } from './metadata.ts'
+import type { FileRule, MultipartPolicy } from './multipart.ts'
+import type { ByteSize } from './size.ts'
+
+import { BadRequestException, issue } from './exceptions.ts'
+
+/** Options of `@UploadedFile` (static: evaluated at build time). */
+export interface UploadedFileOptions {
+  /**
+   * Answer 400 when no file is sent. Default: `true`, unless the parameter is optional
+   * (`file?: File`, `File | undefined`).
+   */
+  readonly required?: boolean
+  /** Maximum size of the file (`5_000_000`, `'5mb'`; `kb` = 1024 bytes). Default: plugin `uploads.maxFileSize`. */
+  readonly maxSize?: ByteSize
+  /**
+   * Accepted media types, as declared by the client: `'image/png'`, `'image/*'`, `'*\/*'`. Other
+   * types answer 415. Default: any.
+   */
+  readonly mimeTypes?: readonly string[]
+}
+
+/** Options of `@UploadedFiles` (static: evaluated at build time). */
+export interface UploadedFilesOptions extends UploadedFileOptions {
+  /** Maximum number of files (413 above). Default: plugin `uploads.maxFiles`. */
+  readonly maxFiles?: number
+}
+
+/** Plugin-wide upload limits (`HttpPlugin.configure({ uploads })`). */
+export interface UploadLimits {
+  /** Default maximum size of one file (`maxSize` of upload parameters). Default: `'10mb'`. */
+  readonly maxFileSize?: ByteSize
+  /** Default maximum number of files of `@UploadedFiles` (and of multipart bodies of other routes). Default: `10`. */
+  readonly maxFiles?: number
+  /** Maximum number of parts (text fields and files) of a multipart body (413 above). Default: `1000`. */
+  readonly maxParts?: number
+  /** Maximum size of one text field of a multipart body (413 above). Default: `'1mb'`. */
+  readonly maxFieldSize?: ByteSize
+}
+
+/** {@link UploadLimits} with defaults applied, in bytes. */
+export interface ResolvedUploadLimits {
+  readonly maxFileSize: number
+  readonly maxFiles: number
+  readonly maxParts: number
+  readonly maxFieldSize: number
+}
+
+/** Default upload limits. */
+export const DEFAULT_UPLOAD_LIMITS: ResolvedUploadLimits = Object.freeze({
+  maxFileSize: 10 * 1024 * 1024,
+  maxFiles: 10,
+  maxParts: 1000,
+  maxFieldSize: 1024 * 1024,
+})
+
+/** How the body of a route is read (internal). */
+export interface BodyPlan {
+  /** Maximum body size in bytes (`Infinity`: no limit). */
+  readonly limit: number
+  /** Rules applied to `multipart/form-data` bodies. */
+  readonly multipart: MultipartPolicy
+  /** The route declares upload parameters: non-multipart bodies answer 415. */
+  readonly upload: boolean
+}
+
+/**
+ * The body plan of a route: `@BodyLimit` (`route.bodyLimit`) or, for upload routes, the sum of the
+ * file limits plus the plugin `bodyLimit` (room for text fields and multipart framing), else the
+ * plugin `bodyLimit`.
+ */
+export function bodyPlan(
+  route: Pick<HttpRouteDefinition, 'bodyLimit' | 'uploads'>,
+  bodyLimit: number,
+  limits: ResolvedUploadLimits,
+): BodyPlan {
+  const definitions = route.uploads ?? []
+  const upload = definitions.length > 0
+  const rules: FileRule[] = upload
+    ? definitions.map(definition => fileRule(definition, limits))
+    : [
+        {
+          field: undefined,
+          multiple: true,
+          maxSize: limits.maxFileSize,
+          maxFiles: limits.maxFiles,
+          mimeTypes: undefined,
+        },
+      ]
+  let limit = route.bodyLimit
+  if (limit === undefined) {
+    limit = bodyLimit
+    if (upload) for (const rule of rules) limit += rule.maxSize * rule.maxFiles
+  }
+  return { limit, upload, multipart: { rules, maxParts: limits.maxParts, maxFieldSize: limits.maxFieldSize } }
+}
+
+function fileRule(definition: HttpUploadDefinition, limits: ResolvedUploadLimits): FileRule {
+  const multiple = definition.multiple === true
+  return {
+    field: definition.field,
+    multiple,
+    maxSize: definition.maxSize ?? limits.maxFileSize,
+    maxFiles: multiple ? (definition.maxFiles ?? limits.maxFiles) : 1,
+    mimeTypes: definition.mimeTypes,
+  }
+}
+
+// -------------------------------------------------------------------------------------------------
+// Helpers of the generated code
+// -------------------------------------------------------------------------------------------------
+
+/**
+ * Reads uploaded files from the context (`ctx.files`) in generated `invoke` functions
+ * (`@UploadedFile('avatar') avatar: File` → `uploads.file(ctx, 'avatar')`). `field` `undefined`
+ * means any field. Limits were enforced while the body was read; these helpers check presence.
+ */
+export interface Uploads {
+  /** The file of `field`; 400 `Missing file "field"` when absent. */
+  file(ctx: HttpContext, field: string | undefined): File
+  /** The file of `field`, `undefined` when absent. */
+  optionalFile(ctx: HttpContext, field: string | undefined): File | undefined
+  /** The files of `field` (at least one); 400 `Missing files "field"` when none. */
+  files(ctx: HttpContext, field: string | undefined): File[]
+  /** The files of `field`, possibly none. */
+  optionalFiles(ctx: HttpContext, field: string | undefined): File[]
+}
+
+const NO_FILES: readonly File[] = Object.freeze([])
+
+function filesOf(ctx: HttpContext, field: string | undefined): readonly File[] {
+  const files = ctx.files
+  if (field !== undefined) return Object.hasOwn(files, field) ? (files[field] ?? NO_FILES) : NO_FILES
+  const all: File[] = []
+  for (const name of Object.keys(files)) all.push(...(files[name] ?? NO_FILES))
+  return all
+}
+
+function missing(ctx: HttpContext, field: string | undefined, multiple: boolean): BadRequestException {
+  const what = multiple ? 'files' : 'file'
+  if (field === undefined) return new BadRequestException(`Missing ${what}`)
+  const body = ctx.body
+  if (body !== null && typeof body === 'object' && Object.hasOwn(body, field)) {
+    return new BadRequestException(
+      `Expected a file in field ${JSON.stringify(field)}, received a text value`,
+      issue(field, 'Expected a file, received a text value'),
+    )
+  }
+  return new BadRequestException(`Missing ${what} ${JSON.stringify(field)}`, issue(field, `Missing ${what}`))
+}
+
+/** The helpers of the generated code (`import { uploads } from '@znight/http'`). */
+export const uploads: Uploads = Object.freeze({
+  file(ctx: HttpContext, field: string | undefined): File {
+    const [file] = filesOf(ctx, field)
+    if (file === undefined) throw missing(ctx, field, false)
+    return file
+  },
+  optionalFile(ctx: HttpContext, field: string | undefined): File | undefined {
+    return filesOf(ctx, field)[0]
+  },
+  files(ctx: HttpContext, field: string | undefined): File[] {
+    const files = filesOf(ctx, field)
+    if (files.length === 0) throw missing(ctx, field, true)
+    return [...files]
+  },
+  optionalFiles(ctx: HttpContext, field: string | undefined): File[] {
+    return [...filesOf(ctx, field)]
+  },
+})

package/src/utils.ts

@@ -0,0 +1,31 @@
+/** Internal helpers (not part of the public API). */
+
+/** Whether `value` is a promise-like object (has a callable `then`). */
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof (value as { then?: unknown }).then === 'function'
+  )
+}
+
+/** Message of any thrown value. */
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message
+  if (typeof error === 'string') return error
+  try {
+    return String(error)
+  } catch {
+    return Object.prototype.toString.call(error)
+  }
+}
+
+/** A `Record` without prototype (safe for user-controlled keys such as `__proto__`). */
+export function emptyRecord<V>(): Record<string, V> {
+  return Object.create(null) as Record<string, V>
+}
+
+/** Whether the code runs on Bun. */
+export function isBun(): boolean {
+  return typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'
+}

package/src/validate.ts

@@ -0,0 +1,65 @@
+import { ValidationException } from './exceptions.ts'
+import {
+  type InferSchemaOutput,
+  isStandardSchema,
+  type StandardSchemaV1,
+  type StandardSchemaV1Issue,
+  type StandardSchemaV1Result,
+} from './standard-schema.ts'
+import { isThenable } from './utils.ts'
+
+/**
+ * Validates `value` with a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType...)
+ * and returns the schema **output** (defaults applied, transforms run, unknown keys stripped when
+ * the schema strips them).
+ *
+ * Returns synchronously when the schema validates synchronously, a promise otherwise (async
+ * refinements): generated code always `await`s it.
+ *
+ * @param location what is validated, used in the error message: `body`, `query`, `query "page"`,
+ *   `param "id"`, `headers`, `cookie "sid"`, `cookies`...
+ * @throws ValidationException (400, `details: [{ path, message }]`) when the value is invalid. For
+ *   cookies (`cookie "name"`, `cookies`) the issue messages are replaced with `Invalid value`: some
+ *   libraries quote the received value in them (Valibot, ArkType), and cookies often carry tokens.
+ * @throws TypeError when `schema` is not a Standard Schema v1 (a programming error → 500).
+ */
+export function validate<S extends StandardSchemaV1>(
+  schema: S,
+  value: unknown,
+  location: string,
+): InferSchemaOutput<S> | Promise<InferSchemaOutput<S>> {
+  if (!isStandardSchema(schema)) {
+    throw new TypeError(`The schema of ${location} is not a Standard Schema v1 (missing "~standard.validate")`)
+  }
+  const result = schema['~standard'].validate(value) as
+    | StandardSchemaV1Result<InferSchemaOutput<S>>
+    | Promise<StandardSchemaV1Result<InferSchemaOutput<S>>>
+  if (isThenable(result)) return Promise.resolve(result).then(settled => unwrap(settled, location))
+  return unwrap(result, location)
+}
+
+function unwrap<T>(result: StandardSchemaV1Result<T>, location: string): T {
+  if (result.issues !== undefined) {
+    throw new ValidationException(location, isCookieLocation(location) ? result.issues.map(redact) : result.issues)
+  }
+  return result.value
+}
+
+/** The message of a redacted issue (cookie values are never echoed). */
+const REDACTED = 'Invalid value'
+
+function isCookieLocation(location: string): boolean {
+  return location === 'cookies' || location.startsWith('cookie ')
+}
+
+/**
+ * The issue with the keys of its path only: its message may quote the value (`Received "eyJ..."`),
+ * and so may the path segments of some libraries (Valibot keeps `input` and `value` there).
+ */
+function redact(issue: StandardSchemaV1Issue): StandardSchemaV1Issue {
+  if (issue.path === undefined) return { message: REDACTED }
+  const path = issue.path.map(segment =>
+    typeof segment === 'object' && segment !== null ? { key: segment.key } : segment,
+  )
+  return { message: REDACTED, path }
+}