@znight/http 0.0.0-stage → 0.1.1

package/src/security-headers.ts

@@ -0,0 +1,161 @@
+/**
+ * Security headers (RFC 0001 §5.5): validated and computed once at boot, then added to every reply
+ * (except `@Res()` raw replies) when the handler, an interceptor, an exception or a hook wrapper did
+ * not set them.
+ */
+import { isHeaderValue } from './headers.ts'
+import { invalidOption } from './option-error.ts'
+
+/** HSTS settings (`strict-transport-security`). */
+export interface HstsOptions {
+  /** `max-age`, in seconds. Default `31536000` (one year). */
+  readonly maxAge?: number
+  /** `includeSubDomains`. Default `true`. */
+  readonly includeSubDomains?: boolean
+  /** `preload` (needs `includeSubDomains` and a `maxAge` of at least one year). Default `false`. */
+  readonly preload?: boolean
+}
+
+/** The `securityHeaders` option of `HttpPlugin.configure` (merged over the defaults). */
+export interface SecurityHeadersOptions {
+  /** `content-security-policy`. Default `"default-src 'none'; frame-ancestors 'none'"`. */
+  readonly contentSecurityPolicy?: string | false
+  /** `x-frame-options`. Default `'DENY'`. */
+  readonly frameOptions?: 'DENY' | 'SAMEORIGIN' | false
+  /** `x-content-type-options: nosniff`. Default `true`. */
+  readonly noSniff?: boolean
+  /** `referrer-policy` (a policy or a comma-separated fallback list). Default `'no-referrer'`. */
+  readonly referrerPolicy?: string | false
+  /** `strict-transport-security`. Default `false`; `true`: `max-age=31536000; includeSubDomains`. */
+  readonly hsts?: boolean | HstsOptions
+  /** `cross-origin-resource-policy`. Default `false`. */
+  readonly crossOriginResourcePolicy?: 'same-origin' | 'same-site' | 'cross-origin' | false
+  /** `cache-control` of replies that do not set one (`'no-store'` for personal data). Default `false`. */
+  readonly cacheControl?: string | false
+}
+
+const DEFAULT_CSP = "default-src 'none'; frame-ancestors 'none'"
+const ONE_YEAR = 31_536_000
+const KEYS = new Set([
+  'contentSecurityPolicy',
+  'frameOptions',
+  'noSniff',
+  'referrerPolicy',
+  'hsts',
+  'crossOriginResourcePolicy',
+  'cacheControl',
+])
+const REFERRER_POLICIES = new Set([
+  'no-referrer',
+  'no-referrer-when-downgrade',
+  'origin',
+  'origin-when-cross-origin',
+  'same-origin',
+  'strict-origin',
+  'strict-origin-when-cross-origin',
+  'unsafe-url',
+])
+const RESOURCE_POLICIES = new Set(['same-origin', 'same-site', 'cross-origin'])
+const NO_HEADERS: Readonly<Record<string, string>> = Object.freeze({})
+
+/**
+ * Validates the `securityHeaders` option (ZNIGHT005) and returns the headers to add, frozen
+ * (`{}` when disabled).
+ */
+export function resolveSecurityHeaders(
+  value: boolean | SecurityHeadersOptions | undefined,
+): Readonly<Record<string, string>> {
+  if (value === false) return NO_HEADERS
+  if (value !== undefined && value !== true && (value === null || typeof value !== 'object' || Array.isArray(value))) {
+    throw invalidOption('securityHeaders', 'a boolean or an object of header settings', value)
+  }
+  const options: SecurityHeadersOptions = value === undefined || value === true ? {} : value
+  for (const key of Object.keys(options)) {
+    if (!KEYS.has(key)) {
+      throw invalidOption('securityHeaders', `an object with ${[...KEYS].join(', ')} (unknown "${key}")`, options)
+    }
+  }
+  const headers: Record<string, string> = {}
+  const csp = options.contentSecurityPolicy ?? DEFAULT_CSP
+  if (csp !== false) headers['content-security-policy'] = text('securityHeaders.contentSecurityPolicy', csp)
+  const frame = options.frameOptions ?? 'DENY'
+  if (frame !== false) {
+    if (frame !== 'DENY' && frame !== 'SAMEORIGIN') {
+      throw invalidOption('securityHeaders.frameOptions', '"DENY", "SAMEORIGIN" or false', frame)
+    }
+    headers['x-frame-options'] = frame
+  }
+  const noSniff = options.noSniff ?? true
+  if (typeof noSniff !== 'boolean') throw invalidOption('securityHeaders.noSniff', 'a boolean', noSniff)
+  if (noSniff) headers['x-content-type-options'] = 'nosniff'
+  const referrer = options.referrerPolicy ?? 'no-referrer'
+  if (referrer !== false) headers['referrer-policy'] = referrerPolicy(referrer)
+  const hsts = strictTransportSecurity(options.hsts ?? false)
+  if (hsts !== undefined) headers['strict-transport-security'] = hsts
+  const corp = options.crossOriginResourcePolicy ?? false
+  if (corp !== false) {
+    if (typeof corp !== 'string' || !RESOURCE_POLICIES.has(corp)) {
+      throw invalidOption(
+        'securityHeaders.crossOriginResourcePolicy',
+        '"same-origin", "same-site", "cross-origin" or false',
+        corp,
+      )
+    }
+    headers['cross-origin-resource-policy'] = corp
+  }
+  const cacheControl = options.cacheControl ?? false
+  if (cacheControl !== false) headers['cache-control'] = text('securityHeaders.cacheControl', cacheControl)
+  return Object.freeze(headers)
+}
+
+function text(name: string, value: unknown): string {
+  if (typeof value !== 'string' || value.trim() === '' || !isHeaderValue(value)) {
+    throw invalidOption(name, 'a non-empty header value (or false)', value)
+  }
+  return value
+}
+
+function referrerPolicy(value: unknown): string {
+  const policies = typeof value === 'string' ? value.split(',').map(item => item.trim()) : []
+  if (policies.length === 0 || !policies.every(policy => REFERRER_POLICIES.has(policy))) {
+    throw invalidOption(
+      'securityHeaders.referrerPolicy',
+      `a referrer policy (${[...REFERRER_POLICIES].join(', ')}) or false`,
+      value,
+    )
+  }
+  return policies.join(', ')
+}
+
+function strictTransportSecurity(value: boolean | HstsOptions): string | undefined {
+  if (value === false) return undefined
+  if (value !== true && (value === null || typeof value !== 'object' || Array.isArray(value))) {
+    throw invalidOption('securityHeaders.hsts', 'a boolean or { maxAge?, includeSubDomains?, preload? }', value)
+  }
+  const options: HstsOptions = value === true ? {} : value
+  for (const key of Object.keys(options)) {
+    if (key !== 'maxAge' && key !== 'includeSubDomains' && key !== 'preload') {
+      throw invalidOption('securityHeaders.hsts', '{ maxAge?, includeSubDomains?, preload? }', options)
+    }
+  }
+  const maxAge = options.maxAge ?? ONE_YEAR
+  if (!Number.isSafeInteger(maxAge) || maxAge < 0) {
+    throw invalidOption('securityHeaders.hsts.maxAge', 'a positive integer number of seconds', maxAge)
+  }
+  const includeSubDomains = options.includeSubDomains ?? true
+  if (typeof includeSubDomains !== 'boolean') {
+    throw invalidOption('securityHeaders.hsts.includeSubDomains', 'a boolean', includeSubDomains)
+  }
+  const preload = options.preload ?? false
+  if (typeof preload !== 'boolean') throw invalidOption('securityHeaders.hsts.preload', 'a boolean', preload)
+  if (preload && (!includeSubDomains || maxAge < ONE_YEAR)) {
+    throw invalidOption(
+      'securityHeaders.hsts',
+      'includeSubDomains and a maxAge of at least 31536000 with preload',
+      options,
+      undefined,
+      ['The HSTS preload list requires includeSubDomains and max-age >= 31536000'],
+    )
+  }
+  return `max-age=${maxAge}${includeSubDomains ? '; includeSubDomains' : ''}${preload ? '; preload' : ''}`
+}

package/src/serialize.ts

@@ -0,0 +1,264 @@
+import type { ReplyBody } from './adapter.ts'
+import type { ResponseCookie } from './cookies.ts'
+import type { HeaderValue, HttpErrorBody } from './exceptions.ts'
+import type { ResolvedFile } from './files.ts'
+import type { HttpResponse } from './response.ts'
+import type { SseSession } from './sse.ts'
+
+import { Readable } from 'node:stream'
+
+import { isFileBody } from './files.ts'
+import { isHttpResponse } from './response.ts'
+import { isSseBody } from './sse.ts'
+import { isBodylessStatus } from './status.ts'
+import { discardStream, isByteStream, toByteStream } from './stream.ts'
+import { emptyRecord } from './utils.ts'
+
+const ENCODER = new TextEncoder()
+
+/** Content types set by the serialiser. */
+export const ContentType: {
+  readonly json: string
+  readonly text: string
+  readonly bytes: string
+  readonly eventStream: string
+} = Object.freeze({
+  json: 'application/json; charset=utf-8',
+  text: 'text/plain; charset=utf-8',
+  bytes: 'application/octet-stream',
+  eventStream: 'text/event-stream; charset=utf-8',
+})
+
+/** How a handler result is turned into a response. */
+export interface SerializeOptions {
+  /** Request method (`HEAD` responses have no body). */
+  readonly method: string
+  /** Method of the route definition (`POST` routes default to 201). */
+  readonly routeMethod: string
+  /** `@HttpCode` status (wins over everything but a Web `Response`). */
+  readonly status: number | undefined
+  /** `@Header` entries. */
+  readonly headers: Readonly<Record<string, string>> | undefined
+  /** Headers set on the context (`ctx.setHeader`), applied after `@Header`. */
+  readonly context?: Readonly<Record<string, HeaderValue>> | undefined
+}
+
+/** A serialised response (mutable headers, merged by the pipeline). */
+export interface SerializedReply {
+  readonly status: number
+  readonly headers: Record<string, HeaderValue>
+  readonly body: ReplyBody
+  /** Cookies of the `HttpResponse` (`withCookie`), applied by the pipeline over those of the context. */
+  readonly cookies?: readonly ResponseCookie[]
+  /** The event stream of the body (`@Sse`, `HttpResponse.sse()`). */
+  readonly sse?: SseSession
+}
+
+/**
+ * Serialises a handler result:
+ *
+ * - Web `Response` → sent as is (status, headers, body); `@HttpCode` / `@Header` do not apply;
+ * - `HttpResponse` → its body with its status and headers;
+ * - `undefined` → empty body, `204` (`201` for POST routes);
+ * - `string` → `text/plain`; `Uint8Array`/`ArrayBuffer`/views → `application/octet-stream`;
+ * - `ReadableStream`, Node.js `Readable`, `Blob` → streamed (`application/octet-stream` or the blob type);
+ * - anything else (objects, arrays, numbers, booleans, `null`) → JSON.
+ *
+ * Status precedence: `@HttpCode` > `HttpResponse.status` > default (`201` for POST routes,
+ * `204` without body, `200`). Header precedence: content type < `@Header` < `ctx.setHeader()` <
+ * `HttpResponse.headers` (a Web `Response` keeps its own headers).
+ */
+export function serializeResult(result: unknown, options: SerializeOptions): SerializedReply {
+  if (result instanceof Response) {
+    const reply = fromWebResponse(result, options.method)
+    if (options.context !== undefined) addMissingHeaders(reply.headers, options.context)
+    return reply
+  }
+  let payload = result
+  let status: number | undefined
+  let extra: Readonly<Record<string, HeaderValue>> | undefined
+  let cookies: readonly ResponseCookie[] | undefined
+  if (isHttpResponse(result)) {
+    payload = result.body
+    status = result.status
+    extra = result.headers
+    cookies = cookiesOf(result)
+  }
+  const finalStatus = options.status ?? status ?? defaultStatus(options.routeMethod, payload)
+  const headers = emptyRecord<HeaderValue>()
+  const body = encode(payload, headers)
+  if (options.headers !== undefined) assignHeaders(headers, options.headers)
+  if (options.context !== undefined) assignHeaders(headers, options.context)
+  if (extra !== undefined) assignHeaders(headers, extra)
+  return withCookies(finish(finalStatus, headers, body, options.method), cookies)
+}
+
+/**
+ * Serialises an event stream (`@Sse` result, `HttpResponse.sse()`): status 200 unless `@HttpCode`
+ * or `HttpResponse.status` say otherwise; `cache-control: no-cache, no-transform` and
+ * `x-accel-buffering: no` under `@Header`, `ctx.setHeader()` and the `HttpResponse` headers;
+ * `content-type: text/event-stream; charset=utf-8` last; never `content-length` or
+ * `transfer-encoding`. A `HEAD` request or a bodyless status cancels the stream before its first read.
+ */
+export function serializeSseReply(
+  session: SseSession,
+  response: HttpResponse | undefined,
+  options: SerializeOptions,
+): SerializedReply {
+  const status = options.status ?? response?.status ?? 200
+  const headers = emptyRecord<HeaderValue>()
+  headers['cache-control'] = 'no-cache, no-transform'
+  headers['x-accel-buffering'] = 'no'
+  if (options.headers !== undefined) assignHeaders(headers, options.headers)
+  if (options.context !== undefined) assignHeaders(headers, options.context)
+  if (response !== undefined) assignHeaders(headers, response.headers)
+  headers['content-type'] = ContentType.eventStream
+  delete headers['content-length']
+  delete headers['transfer-encoding']
+  const reply = finish(status, headers, session.stream, options.method)
+  return withCookies(reply.body === null ? reply : { ...reply, sse: session }, response && cookiesOf(response))
+}
+
+/** The cookies of an `HttpResponse` (none for a copy of the class from an older package version). */
+function cookiesOf(response: HttpResponse): readonly ResponseCookie[] | undefined {
+  const cookies = (response as { cookies?: readonly ResponseCookie[] }).cookies
+  return Array.isArray(cookies) && cookies.length > 0 ? cookies : undefined
+}
+
+function withCookies(reply: SerializedReply, cookies: readonly ResponseCookie[] | undefined): SerializedReply {
+  return cookies === undefined ? reply : { ...reply, cookies }
+}
+
+/**
+ * Serialises a resolved file response (`HttpResponse.file()`): the file headers, then `@Header`,
+ * `ctx.setHeader()` and the `HttpResponse` headers. 206 / 304 keep their status; a 200 follows the
+ * usual precedence (`@HttpCode` > `HttpResponse.status` > 200).
+ */
+export function serializeFileReply(
+  file: ResolvedFile,
+  response: HttpResponse,
+  options: SerializeOptions,
+): SerializedReply {
+  const status = file.status === 200 ? (options.status ?? response.status ?? 200) : file.status
+  const headers = emptyRecord<HeaderValue>()
+  assignHeaders(headers, file.headers)
+  if (options.headers !== undefined) assignHeaders(headers, options.headers)
+  if (options.context !== undefined) assignHeaders(headers, options.context)
+  assignHeaders(headers, response.headers)
+  return withCookies(finish(status, headers, file.body, options.method), cookiesOf(response))
+}
+
+/** `201` for POST routes, otherwise `204` without payload and `200` with one. */
+function defaultStatus(routeMethod: string, payload: unknown): number {
+  if (routeMethod === 'POST') return 201
+  return payload === undefined ? 204 : 200
+}
+
+/** Serialises an error body as JSON. */
+export function serializeError(status: number, body: HttpErrorBody | unknown, method: string): SerializedReply {
+  const headers = emptyRecord<HeaderValue>()
+  const encoded = encode(body, headers)
+  return finish(status, headers, encoded, method)
+}
+
+/** Copies headers with lower-case names (later values win). */
+export function assignHeaders(
+  target: Record<string, HeaderValue>,
+  source: Readonly<Record<string, HeaderValue>>,
+): void {
+  for (const name of Object.keys(source)) {
+    const value = source[name]
+    if (value !== undefined) target[name.toLowerCase()] = typeof value === 'string' ? value : [...value]
+  }
+}
+
+/** Adds headers that are not already present (case-insensitive). */
+export function addMissingHeaders(
+  target: Record<string, HeaderValue>,
+  source: Readonly<Record<string, HeaderValue>>,
+): void {
+  for (const name of Object.keys(source)) {
+    const key = name.toLowerCase()
+    const value = source[name]
+    if (value !== undefined && target[key] === undefined) target[key] = typeof value === 'string' ? value : [...value]
+  }
+}
+
+function finish(
+  status: number,
+  headers: Record<string, HeaderValue>,
+  body: ReplyBody,
+  method: string,
+): SerializedReply {
+  if (isBodylessStatus(status)) {
+    discard(body)
+    delete headers['content-type']
+    delete headers['content-length']
+    return { status, headers, body: null }
+  }
+  if (method === 'HEAD') {
+    discard(body)
+    return { status, headers, body: null }
+  }
+  return { status, headers, body }
+}
+
+function discard(body: ReplyBody): void {
+  if (body instanceof ReadableStream) discardStream(body)
+}
+
+function encode(payload: unknown, headers: Record<string, HeaderValue>): ReplyBody {
+  if (payload === undefined) return null
+  if (typeof payload === 'string') return bytes(ENCODER.encode(payload), headers, ContentType.text)
+  if (payload instanceof Uint8Array) return bytes(payload, headers, ContentType.bytes)
+  if (payload instanceof ArrayBuffer) return bytes(new Uint8Array(payload), headers, ContentType.bytes)
+  if (ArrayBuffer.isView(payload)) {
+    return bytes(new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength), headers, ContentType.bytes)
+  }
+  if (payload instanceof ReadableStream) {
+    headers['content-type'] = ContentType.bytes
+    // adapters get bytes (`ReplyBody`): string / ArrayBuffer chunks of a returned stream are converted
+    return isByteStream(payload) ? (payload as ReadableStream<Uint8Array>) : toByteStream(payload)
+  }
+  if (payload instanceof Blob) {
+    headers['content-type'] = payload.type === '' ? ContentType.bytes : payload.type
+    headers['content-length'] = String(payload.size)
+    return payload
+  }
+  if (isNodeReadable(payload)) {
+    headers['content-type'] = ContentType.bytes
+    return toByteStream(payload)
+  }
+  if (isFileBody(payload)) throw new TypeError('A file body (HttpResponse.file()) cannot be serialised here')
+  if (isSseBody(payload)) throw new TypeError('An event stream (HttpResponse.sse()) cannot be serialised here')
+  const json = JSON.stringify(payload)
+  if (json === undefined) throw new TypeError(`Cannot serialise a ${typeof payload} as a response body`)
+  return bytes(ENCODER.encode(json), headers, ContentType.json)
+}
+
+function bytes(data: Uint8Array, headers: Record<string, HeaderValue>, type: string): Uint8Array {
+  headers['content-type'] = type
+  headers['content-length'] = String(data.byteLength)
+  return data
+}
+
+function isNodeReadable(value: unknown): value is Readable {
+  return (
+    value instanceof Readable ||
+    (value !== null &&
+      typeof value === 'object' &&
+      typeof (value as { pipe?: unknown }).pipe === 'function' &&
+      typeof (value as { on?: unknown }).on === 'function' &&
+      typeof (value as { read?: unknown }).read === 'function')
+  )
+}
+
+function fromWebResponse(response: Response, method: string): SerializedReply {
+  const headers = emptyRecord<HeaderValue>()
+  for (const [name, value] of response.headers) {
+    if (name !== 'set-cookie') headers[name] = value
+  }
+  const cookies = response.headers.getSetCookie()
+  if (cookies.length > 0) headers['set-cookie'] = cookies
+  return finish(response.status, headers, response.body, method)
+}

package/src/size.ts

@@ -0,0 +1,66 @@
+/**
+ * Byte sizes (`1048576`, `'512kb'`, `'10 MiB'`, `'1.5gb'`) used by body and upload limits. This
+ * module is **pure** (no imports, no I/O): the compiler extension evaluates `@BodyLimit('10mb')` and
+ * `maxSize` options with it at build time.
+ *
+ * Units are case-insensitive and binary, like the `bytes` package used by Express:
+ * `b`, `kb`/`kib`/`k` = 1024, `mb`/`mib`/`m` = 1024², `gb`/`gib`/`g` = 1024³, `tb`/`tib`/`t` = 1024⁴.
+ */
+
+/**
+ * A size in bytes: a non-negative integer (`Infinity` disables the limit) or a string with a unit
+ * (`'512kb'`, `'10mb'`, `'1.5 GiB'`; `kb` = 1024 bytes).
+ */
+export type ByteSize = number | string
+
+const UNITS: Readonly<Record<string, number>> = {
+  b: 1,
+  k: 1024,
+  kb: 1024,
+  kib: 1024,
+  m: 1024 ** 2,
+  mb: 1024 ** 2,
+  mib: 1024 ** 2,
+  g: 1024 ** 3,
+  gb: 1024 ** 3,
+  gib: 1024 ** 3,
+  t: 1024 ** 4,
+  tb: 1024 ** 4,
+  tib: 1024 ** 4,
+}
+
+const SIZE = /^(\d+(?:\.\d+)?|\.\d+)\s*([a-z]*)$/i
+
+/**
+ * Parses a {@link ByteSize}: `1024` → `1024`, `'10mb'` → `10485760`, `'1.5kb'` → `1536` (fractions
+ * are rounded down). Returns `undefined` for anything else (negative or fractional numbers,
+ * unknown units, `NaN`).
+ */
+export function parseByteSize(value: unknown): number | undefined {
+  if (typeof value === 'number') {
+    if (value === Number.POSITIVE_INFINITY) return value
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined
+  }
+  if (typeof value !== 'string') return undefined
+  const match = SIZE.exec(value.trim())
+  if (match === null) return undefined
+  const unit = (match[2] as string).toLowerCase()
+  const multiplier = unit === '' ? 1 : UNITS[unit]
+  if (multiplier === undefined) return undefined
+  const bytes = Math.floor(Number(match[1]) * multiplier)
+  return Number.isSafeInteger(bytes) ? bytes : undefined
+}
+
+/** Human-readable size for messages: `5 MiB`, `1.5 KiB`, `512 bytes`, `unlimited`. */
+export function formatByteSize(bytes: number): string {
+  if (bytes === Number.POSITIVE_INFINITY) return 'unlimited'
+  for (const [unit, size] of [
+    ['TiB', 1024 ** 4],
+    ['GiB', 1024 ** 3],
+    ['MiB', 1024 ** 2],
+    ['KiB', 1024],
+  ] as const) {
+    if (bytes >= size) return `${Number((bytes / size).toFixed(2))} ${unit}`
+  }
+  return bytes === 1 ? '1 byte' : `${bytes} bytes`
+}

package/src/sse-parse.ts

@@ -0,0 +1,194 @@
+/**
+ * Client side of Server-Sent Events: the WHATWG "interpreting an event stream" algorithm over a
+ * byte stream (`parseSseStream`), used by `injectSse()` and by tests over real sockets. Import-free.
+ */
+
+/** A dispatched event. */
+export interface SseMessage {
+  /** Event type: `message` by default. */
+  readonly event: string
+  readonly data: string
+  /** The last event id at dispatch time (what `EventSource` sends back as `Last-Event-ID`). */
+  readonly id: string
+  /** `JSON.parse(data)`. */
+  json<T = unknown>(): T
+}
+
+/** An item of an event stream: an event, a comment (heartbeats are `''`) or a reconnection delay. */
+export type SseItem =
+  | ({ readonly type: 'event' } & SseMessage)
+  | { readonly type: 'comment'; readonly text: string }
+  | { readonly type: 'retry'; readonly retry: number }
+
+/** Options of {@link parseSseStream}. */
+export interface ParseSseOptions {
+  /** Stops reading (the body is cancelled) when aborted. */
+  readonly signal?: AbortSignal
+}
+
+/**
+ * Incremental parser (internal): feed it decoded text, collect the items. Follows the HTML
+ * specification: CR, LF and CRLF line ends (a CR at the end of a chunk included), one leading space
+ * stripped from values, `data` lines buffered and the final LF removed, `id` values containing NUL
+ * ignored, `retry` accepted only as ASCII digits, the type defaulting to `message`, an event without
+ * data not dispatched.
+ */
+export class SseParser {
+  /** The last event id (updated when an event is dispatched, even without data). */
+  lastEventId = ''
+  #line = ''
+  #skipLf = false
+  #data = ''
+  #hasData = false
+  #type = ''
+  #idBuffer = ''
+
+  /** Parses a chunk of text; returns the items it completes. */
+  push(text: string): SseItem[] {
+    const items: SseItem[] = []
+    let start = 0
+    for (let index = 0; index < text.length; index++) {
+      const code = text.charCodeAt(index)
+      if (code === 0x0a && this.#skipLf) {
+        // the LF of a CRLF (possibly split across chunks)
+        this.#skipLf = false
+        start = index + 1
+        continue
+      }
+      this.#skipLf = false
+      if (code !== 0x0a && code !== 0x0d) continue
+      this.#line += text.slice(start, index)
+      this.#processLine(this.#line, items)
+      this.#line = ''
+      start = index + 1
+      if (code === 0x0d) this.#skipLf = true
+    }
+    if (start < text.length) this.#line += text.slice(start)
+    return items
+  }
+
+  #processLine(line: string, items: SseItem[]): void {
+    if (line === '') {
+      this.#dispatch(items)
+      return
+    }
+    const colon = line.indexOf(':')
+    if (colon === 0) {
+      items.push({ type: 'comment', text: line.charCodeAt(1) === 0x20 ? line.slice(2) : line.slice(1) })
+      return
+    }
+    const field = colon === -1 ? line : line.slice(0, colon)
+    let value = colon === -1 ? '' : line.slice(colon + 1)
+    if (value.charCodeAt(0) === 0x20) value = value.slice(1)
+    switch (field) {
+      case 'event':
+        this.#type = value
+        break
+      case 'data':
+        this.#data += `${value}\n`
+        this.#hasData = true
+        break
+      case 'id':
+        if (!value.includes('\u0000')) this.#idBuffer = value
+        break
+      case 'retry':
+        if (/^\d+$/.test(value)) items.push({ type: 'retry', retry: Number(value) })
+        break
+      default:
+        break
+    }
+  }
+
+  #dispatch(items: SseItem[]): void {
+    this.lastEventId = this.#idBuffer
+    if (!this.#hasData) {
+      this.#type = ''
+      return
+    }
+    const data = this.#data.endsWith('\n') ? this.#data.slice(0, -1) : this.#data
+    const event = this.#type === '' ? 'message' : this.#type
+    const id = this.lastEventId
+    items.push({ type: 'event', event, data, id, json: <T = unknown>(): T => JSON.parse(data) as T })
+    this.#data = ''
+    this.#hasData = false
+    this.#type = ''
+  }
+}
+
+/**
+ * Turns an event stream body (a `fetch()` response body, `injectStream().body`) into its items.
+ * UTF-8 is decoded with the BOM stripped; an unterminated event at the end is discarded. Calling
+ * `return()` (leaving a `for await` loop) or aborting `signal` cancels the body.
+ *
+ * ```ts
+ * const response = await fetch(`${http.address}/orders/o-1/events`)
+ * for await (const item of parseSseStream(response.body!)) {
+ *   if (item.type === 'event') console.log(item.event, item.json())
+ * }
+ * ```
+ */
+export function parseSseStream(
+  body: ReadableStream<Uint8Array>,
+  options: ParseSseOptions = {},
+): AsyncIterableIterator<SseItem> {
+  return parseWith(new SseParser(), body, options)
+}
+
+/** {@link parseSseStream} with a given parser (internal: `injectSse()` reads its `lastEventId`). */
+export function parseWith(
+  parser: SseParser,
+  body: ReadableStream<Uint8Array>,
+  options: ParseSseOptions = {},
+): AsyncIterableIterator<SseItem> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder('utf-8')
+  const queue: SseItem[] = []
+  let ended = false
+  let cancelled: Promise<void> = Promise.resolve()
+  const stop = (): void => {
+    if (ended) return
+    ended = true
+    queue.length = 0
+    cancelled = reader.cancel().catch(() => undefined)
+  }
+  const signal = options.signal
+  if (signal !== undefined) {
+    if (signal.aborted) stop()
+    else signal.addEventListener('abort', stop, { once: true })
+  }
+  const iterator: AsyncIterableIterator<SseItem> = {
+    async next(): Promise<IteratorResult<SseItem>> {
+      for (;;) {
+        const queued = queue.shift()
+        if (queued !== undefined) return { done: false, value: queued }
+        if (ended) return { done: true, value: undefined }
+        let result: Awaited<ReturnType<typeof reader.read>>
+        try {
+          result = await reader.read()
+        } catch (error) {
+          if (ended) return { done: true, value: undefined }
+          ended = true
+          throw error
+        }
+        if (result.done) {
+          // the decoder may hold the start of a character; an unterminated event is discarded
+          parser.push(decoder.decode())
+          ended = true
+          signal?.removeEventListener('abort', stop)
+          return { done: true, value: undefined }
+        }
+        if (!ended) queue.push(...parser.push(decoder.decode(result.value, { stream: true })))
+      }
+    },
+    async return(): Promise<IteratorResult<SseItem>> {
+      stop()
+      signal?.removeEventListener('abort', stop)
+      await cancelled
+      return { done: true, value: undefined }
+    },
+    [Symbol.asyncIterator](): AsyncIterableIterator<SseItem> {
+      return iterator
+    },
+  }
+  return iterator
+}