@toa.io/extensions.exposition 1.0.0-alpha.291 → 1.0.0-alpha.293

package/source/HTTP/Server.ts

@@ -1,430 +0,0 @@
-import assert from 'node:assert'
-import fs from 'node:fs'
-import os from 'node:os'
-import * as http from 'node:http'
-import * as http2 from 'node:http2'
-import { once } from 'node:events'
-import { setTimeout } from 'node:timers/promises'
-import { console, current, decide, decode, run, type SpanContext } from 'openspan'
-import { Connector } from '@toa.io/core'
-import { type OutgoingMessage, write } from './messages.js'
-import { ClientError, Exception } from './exceptions.js'
-import { Context } from './Context.js'
-import { Probe } from './Probe.js'
-import { PORT, PROBE } from '../const.js'
-import type { IncomingMessage, Protocol, ServerResponse } from './types.js'
-import type { Bouncer, MCP, OAuth, RPC } from '../Annotation.js'
-
-export class Server extends Connector {
-  private readonly server: http.Server | http2.Http2Server
-  private readonly properties: Properties
-  /** Host to authority. A map: a `Host` of `constructor` names what a plain object answers. */
-  private readonly authorities: Map<string, string>
-
-  /** Tracked for the drain: `Http2Server` has no `closeIdleConnections`. */
-  private readonly sessions = new Set<http2.ServerHttp2Session>()
-
-  private readonly probe: Probe
-
-  private process?: Processor
-
-  private constructor(properties: Properties) {
-    super()
-
-    this.properties = properties
-    this.authorities = new Map(
-      Object.entries(properties.authorities).map(([key, value]) => [value, key])
-    )
-    this.server = instantiate(properties.protocol)
-    this.probe = new Probe(properties.probe)
-
-    this.server.on('request', (req, res) =>
-      this.listener(req as unknown as IncomingMessage, res as unknown as ServerResponse)
-    )
-
-    if (properties.protocol === 'h1') this.h1(this.server as http.Server)
-    else this.h2(this.server as http2.Http2Server)
-  }
-
-  public static create(options: Options): Server {
-    const properties: Properties = { ...DEFAULTS, ...options }
-
-    return new Server(properties)
-  }
-
-  public attach(process: Processor): void {
-    this.process = process
-  }
-
-  protected override async open(): Promise<void> {
-    // answers 503 from here; the gateway's dependencies have settled by the time `open` runs
-    await this.probe.listen()
-
-    this.server.listen(this.properties.port)
-
-    await once(this.server, 'listening')
-
-    console.info('HTTP Server is listening')
-
-    this.probe.complete()
-
-    console.info('Ready')
-  }
-
-  protected override async close(): Promise<void> {
-    await this.probe.close()
-
-    this.server.close()
-
-    // GOAWAY lets in-flight streams finish; `Http2Server` has no `closeIdleConnections`
-    if (this.properties.protocol === 'h1')
-      (this.server as http.Server).closeIdleConnections()
-    else for (const session of this.sessions) session.close()
-
-    console.info('Stopped accepting new connections')
-
-    // keep-alive clients hold connections open indefinitely, so the drain is bounded
-    await Promise.race([
-      once(this.server, 'close'),
-      setTimeout(this.properties.drain, undefined, { ref: false })
-    ])
-
-    if (this.properties.protocol === 'h1')
-      (this.server as http.Server).closeAllConnections()
-    else for (const session of this.sessions) session.destroy()
-
-    console.info('Stopped')
-  }
-
-  /** A malformed HTTP/1.1 request has no framing to answer in, so the status line is written by hand. */
-  private h1(server: http.Server): void {
-    server.on('clientError', (error, socket) => {
-      console.warn('Client connection error', error)
-
-      if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
-      else socket.destroy()
-    })
-  }
-
-  /** HTTP/2 has no `clientError`: failures surface per session, per stream, or per frame. */
-  private h2(server: http2.Http2Server): void {
-    server.on('session', (session) => {
-      this.sessions.add(session)
-      session.on('close', () => this.sessions.delete(session))
-    })
-
-    server.on('sessionError', (error) => console.warn('Session error', error))
-    server.on('streamError', (error) => console.warn('Stream error', error))
-
-    server.on('unknownProtocol', (socket) => {
-      console.warn('Unknown protocol')
-      socket.destroy()
-    })
-  }
-
-  private listener(request: IncomingMessage, response: ServerResponse): void {
-    request.once('error', (error) => {
-      console.warn('Request error', errorAttributes(request, error))
-
-      if (!response.writableEnded) response.destroy()
-    })
-
-    // no listener on `request.socket`: under HTTP/2 it is the session's socket, shared by
-    // every concurrent stream, and removing listeners on it would strip the siblings'
-
-    const host = authorityOf(request)?.toLowerCase()
-
-    if (host === undefined || !HOST.test(host)) {
-      console.warn(
-        'Request without a valid authority',
-        errorAttributes(request, new Error('Invalid authority'))
-      )
-
-      response.writeHead(400).end()
-
-      return
-    }
-
-    // directives and components read `host`; HTTP/2 sends `:authority` instead, and what a
-    // component sees must not depend on the protocol the request arrived over
-    request.headers.host ??= host
-
-    const url = parse(request, host)
-
-    if (url instanceof Error) {
-      console.warn('Invalid request', errorAttributes(request, url))
-
-      response.writeHead(400).end()
-
-      return
-    }
-
-    if (request.method === undefined || !this.properties.methods.has(request.method)) {
-      response.writeHead(501).end()
-
-      return
-    }
-
-    assert(this.process !== undefined, 'Request processor is not attached')
-
-    const authority = this.authorities.get(host) ?? host
-
-    // if the request carries no trace context, the trace starts here
-    const remote = trace(request.headers)
-
-    const processing =
-      remote === null
-        ? this.serve(request, response, authority, url)
-        : run(remote, async () => await this.serve(request, response, authority, url))
-
-    processing.catch((error) => {
-      console.error('Request processing failed', error)
-
-      if (!response.writableEnded) response.writeHead(500).end()
-    })
-  }
-
-  // eslint-disable-next-line max-params
-  private async serve(
-    request: IncomingMessage,
-    response: ServerResponse,
-    authority: string,
-    url: URL
-  ): Promise<void> {
-    await console.span(
-      {
-        name: `${request.method} ${request.url}`,
-        kind: 'server',
-        service: 'exposition',
-        attributes: { method: request.method, url: request.url, authority }
-      },
-      async () => {
-        response.setHeader('ray', current()!.traceId)
-
-        const context = new Context(authority, request, this.properties, url)
-
-        await this.process!(context)
-          .then(this.success(context, response))
-          .catch(this.fail(context, response))
-          .finally(() => request.removeAllListeners('error'))
-      }
-    )
-  }
-
-  private success(context: Context, response: ServerResponse) {
-    return async (message: OutgoingMessage) => {
-      let status = message.status
-
-      if (status === undefined)
-        if (message.body === null) status = 404
-        else if (context.request.method === 'POST') status = 201
-        else if (message.body === undefined && context.request.method !== 'HEAD')
-          status = 204
-        else status = 200
-
-      message.status = status
-
-      await write(context, response, message)
-    }
-  }
-
-  private fail(context: Context, response: ServerResponse) {
-    return async (exception: Error) => {
-      try {
-        // Over HTTP/2 the reply is followed by RST_STREAM(NO_ERROR), which tells the client
-        // to stop sending without discarding the response — so the body is never read.
-        if (!context.request.complete && this.properties.protocol === 'h1')
-          await adam(context.request)
-
-        const status = exception instanceof Exception ? exception.status : 500
-        const span = current()
-
-        // https://opentelemetry.io/docs/specs/semconv/http/http-spans/#status
-        if (status >= 500 && span !== undefined) span.status = 'error'
-
-        if (!response.writableEnded) {
-          response.statusCode = status
-
-          const message: OutgoingMessage = {
-            status: response.statusCode,
-            authentic: true
-          }
-
-          // eslint-disable-next-line max-depth
-          if (exception instanceof Exception && exception.headers !== undefined)
-            message.headers = exception.headers
-
-          // eslint-disable-next-line max-depth
-          if (context.encoder === null) message.body = undefined
-          else if (exception instanceof ClientError || this.properties.debug)
-            message.body =
-              exception instanceof Exception
-                ? exception.body
-                : ((this.properties.debug && exception.stack) ?? exception.message)
-
-          await write(context, response, message)
-        }
-      } catch (final) {
-        console.error('Error in error handler', final)
-
-        if (!response.writableEnded)
-          try {
-            response.writeHead(500).end()
-          } catch {
-            // Nothing more we can do
-          }
-      }
-    }
-  }
-}
-
-function instantiate(protocol: Protocol): http.Server | http2.Http2Server {
-  if (protocol === 'h1') return http.createServer()
-
-  return http2.createServer({
-    // realtime pins one stream per subscription, and they all share a session
-    maxSessionMemory: SESSION_MEMORY,
-    settings: { initialWindowSize: WINDOW }
-  })
-}
-
-/**
- * The authority the request is addressed to. HTTP/2 carries it in `:authority` and omits
- * `host` entirely, so reading `host` alone would leave every HTTP/2 request unattributed.
- */
-function authorityOf(request: IncomingMessage): string | undefined {
-  return request.headers[':authority'] ?? request.headers.host
-}
-
-/** Parsing the URL is how a request is validated, so the `Context` is handed the result. */
-function parse(request: IncomingMessage, authority: string): URL | Error {
-  try {
-    return new URL(request.url, `https://${authority}`)
-  } catch (error) {
-    return error as Error
-  }
-}
-
-// https://github.com/whatwg/fetch/issues/1254
-async function adam(request: IncomingMessage): Promise<void> {
-  const devnull = fs.createWriteStream(os.devNull)
-
-  devnull.on('error', () => undefined)
-  request.pipe(devnull).on('error', () => undefined)
-
-  await once(request, 'end')
-}
-
-function errorAttributes(
-  request: IncomingMessage,
-  error: Error & any
-): RequestErrorAttributes {
-  const attributes: RequestErrorAttributes = {
-    path: request.url,
-    method: request.method,
-    name: error.name
-  }
-
-  if (typeof error.code === 'string') attributes.code = error.code
-
-  if (typeof error.stack === 'string') attributes.stack = error.stack
-
-  return attributes
-}
-
-export const DRAIN = 10 // seconds
-
-/** Megabytes a single HTTP/2 session may hold, over Node's default of 10. */
-const SESSION_MEMORY = 128
-
-/** Per-stream flow control window. The default 64 KiB throttles in proportion to RTT. */
-const WINDOW = 1024 * 1024
-
-/**
- * Extracts the remote trace context from the request headers.
- *
- * The `ray` header adopts the trace by ID only and does not bypass sampling:
- * the sampling decision is made by the server.
- */
-function trace(headers: IncomingMessage['headers']): SpanContext | null {
-  if (typeof headers.traceparent === 'string') return decode(headers.traceparent)
-
-  // adopting a trace by ID does not bypass sampling
-  if (
-    typeof headers.ray === 'string' &&
-    RAY.test(headers.ray) &&
-    headers.ray !== ZERO_RAY
-  )
-    return { traceId: headers.ray.toLowerCase(), sampled: decide() }
-
-  return null
-}
-
-/**
- * A host name with an optional port, or a bracketed IPv6 literal. The URL parser admits
- * `,` `;` `=` `(` `)` and quotes in a host, and the authority is written into criteria.
- */
-const HOST = /^(?:[a-z0-9.-]{1,253}|\[[0-9a-f:.]{2,45}\])(?::\d{1,5})?$/
-
-const RAY = /^[\da-f]{32}$/i
-const ZERO_RAY = '0'.repeat(32)
-
-const DEFAULTS: Omit<Properties, 'authorities'> = {
-  methods: new Set<string>([
-    'OPTIONS',
-    'GET',
-    'HEAD',
-    'POST',
-    'PUT',
-    'PATCH',
-    'DELETE',
-    'LOCK',
-    'UNLOCK'
-  ]),
-  debug: false,
-  port: PORT,
-  drain: DRAIN * 1000,
-  protocol: 'h1',
-  probe: PROBE
-}
-
-interface Properties {
-  authorities: Record<string, string>
-  methods: Set<string>
-  debug: boolean
-  port: number
-  drain: number
-  protocol: Protocol
-
-  /** Port of the readiness probe, which is HTTP/1.1 whatever the gateway serves. */
-  probe: number
-
-  /** The header the client address is read from; the connection's address without one. */
-  ip?: string
-
-  /** Failed authentications an address may make; none are metered unless set. */
-  bouncer?: Bouncer
-
-  /** The authorization server this context exposes; none is exposed without it. */
-  oauth?: OAuth
-
-  /** JSON-RPC at `/.rpc`; none is served without it. */
-  rpc?: RPC
-
-  /** MCP at `/.mcp`; none is served without it. */
-  mcp?: MCP
-}
-
-export type Options = { authorities: Properties['authorities'] } & {
-  [K in Exclude<keyof Properties, 'authorities'>]?: Properties[K]
-}
-
-export type Processor = (input: Context) => Promise<OutgoingMessage>
-
-interface RequestErrorAttributes {
-  path: string
-  method: string
-  name: string
-  code?: string
-  stack?: string
-}

package/source/HTTP/Timing.ts

@@ -1,14 +0,0 @@
-import { performance } from 'node:perf_hooks'
-import type { ServerResponse } from './types.js'
-
-/** How long the request took, from received to written: one number, the header's. */
-export class Timing {
-  private readonly start = performance.now()
-
-  public append(response: ServerResponse): void {
-    response.setHeader(
-      'server-timing',
-      `total;dur=${(performance.now() - this.start).toFixed(3)}`
-    )
-  }
-}

package/source/HTTP/address.test.ts

@@ -1,28 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { address } from './address.js'
-import type { IncomingMessage } from './types.js'
-
-const request = (headers: Record<string, string>): IncomingMessage =>
-  ({ headers, socket: { remoteAddress: '9.9.9.9' } }) as unknown as IncomingMessage
-
-it('should be nothing without a header named', () => {
-  assert.equal(address(request({ 'x-forwarded-for': '1.1.1.1' })), undefined)
-})
-
-it('should be the last value of the named header', () => {
-  assert.equal(
-    address(request({ 'x-forwarded-for': '1.1.1.1, 2.2.2.2' }), 'x-forwarded-for'),
-    '2.2.2.2'
-  )
-  assert.equal(
-    address(request({ 'cf-connecting-ip': '3.3.3.3' }), 'cf-connecting-ip'),
-    '3.3.3.3'
-  )
-})
-
-it('should be nothing when the named header is absent or empty', () => {
-  assert.equal(address(request({}), 'x-real-ip'), undefined)
-  assert.equal(address(request({ 'x-real-ip': ' ' }), 'x-real-ip'), undefined)
-})

package/source/HTTP/address.ts

@@ -1,16 +0,0 @@
-import type { IncomingMessage } from './types.js'
-
-/**
- * The client address: the value of the header the deployment names, and nothing otherwise.
- * Of a header holding a list, the last value is the one the edge in front appended. The
- * connection's address is never it: behind an edge it is the edge's.
- */
-export function address(request: IncomingMessage, header?: string): string | undefined {
-  if (header === undefined) return
-
-  const value = request.headers[header]
-  const raw = Array.isArray(value) ? value[value.length - 1] : value
-  const last = raw?.slice(raw.lastIndexOf(',') + 1).trim()
-
-  return last === '' ? undefined : last
-}

package/source/HTTP/exceptions.ts

@@ -1,99 +0,0 @@
-export class Exception extends Error {
-  public readonly status: number
-  public readonly body?: any
-
-  /** Headers the status is not complete without, like `Retry-After` on a 429. */
-  public readonly headers?: Headers
-
-  protected constructor(status: number, body?: any, headers?: Headers) {
-    super()
-    this.status = status
-    this.body = body
-    this.headers = headers
-  }
-}
-
-export class ClientError extends Exception {}
-
-export class BadRequest extends ClientError {
-  public constructor(body?: any) {
-    super(400, body)
-  }
-}
-
-export class Unauthorized extends ClientError {
-  public constructor(body?: any) {
-    super(401, body)
-  }
-}
-
-export class Forbidden extends ClientError {
-  public constructor(body?: any) {
-    super(403, body)
-  }
-}
-
-export class NotFound extends ClientError {
-  public constructor(body?: any) {
-    super(404, body)
-  }
-}
-
-export class MethodNotAllowed extends ClientError {
-  public constructor(headers?: Headers) {
-    super(405, undefined, headers)
-  }
-}
-
-export class NotAcceptable extends ClientError {
-  public constructor() {
-    super(406)
-  }
-}
-
-export class Conflict extends ClientError {
-  public constructor(body?: any) {
-    super(409, body)
-  }
-}
-
-export class PreconditionFailed extends ClientError {
-  public constructor() {
-    super(412)
-  }
-}
-
-export class RequestEntityTooLarge extends ClientError {
-  public constructor(body?: any) {
-    super(413, body)
-  }
-}
-
-export class UnsupportedMediaType extends ClientError {
-  public constructor() {
-    super(415)
-  }
-}
-
-export class UnprocessableEntity extends ClientError {
-  public constructor(body?: any) {
-    super(422, body)
-  }
-}
-
-export class TooManyRequests extends ClientError {
-  /** @param retry Seconds until the request would be admitted. */
-  public constructor(retry?: number) {
-    super(
-      429,
-      undefined,
-      retry === undefined ? undefined : new Headers({ 'retry-after': String(retry) })
-    )
-  }
-}
-
-export class ServiceUnavailable extends Exception {
-  public constructor(body?: any) {
-    super(503, body)
-  }
-}

package/source/HTTP/formats/form.ts

@@ -1,21 +0,0 @@
-export const type = 'application/x-www-form-urlencoded'
-
-/**
- * A form is read and never written: it is what an HTML form and a handful of protocols send,
- * and nothing asks for a reply in it.
- *
- * A name repeated in a form is a list, which is how a form says one — `URLSearchParams` keeps
- * every value, and a name given once stays the string it was written as.
- */
-export function decode(buffer: Buffer, charset = 'utf-8'): any {
-  const params = new URLSearchParams(buffer.toString(charset as BufferEncoding))
-  const value: Record<string, string | string[]> = {}
-
-  for (const name of new Set(params.keys())) {
-    const values = params.getAll(name)
-
-    value[name] = values.length === 1 ? values[0] : values
-  }
-
-  return value
-}

package/source/HTTP/formats/index.ts

@@ -1,36 +0,0 @@
-import * as json from './json.js'
-import * as yaml from './yaml.js'
-import * as msgpack from './msgpack.js'
-import * as text from './text.js'
-import * as form from './form.js'
-
-/** What a reply may be encoded as, and so what `accept` is negotiated against. */
-export const formats: Record<string, Format> = {
-  [json.type]: json,
-  [yaml.type]: yaml,
-  [text.type]: text,
-  [msgpack.type]: msgpack
-}
-
-export const types = Object.keys(formats)
-
-/**
- * What a request body may arrive as. Everything a reply may be, and a form besides — which
- * is read and never written, so it is not something a reply can be asked for.
- */
-export const decoders: Record<string, Decoder> = {
-  ...formats,
-  [form.type]: form
-}
-
-export interface Decoder {
-  readonly type: string
-
-  decode: (buffer: Buffer, charset?: string) => any
-}
-
-export interface Format extends Decoder {
-  readonly multipart: string
-
-  encode: (value: any) => Buffer
-}

package/source/HTTP/formats/json.ts

@@ -1,14 +0,0 @@
-export const type = 'application/json'
-export const multipart = 'multipart/json'
-
-export function decode(buffer: Buffer, charset = 'utf-8'): any {
-  const text = buffer.toString(charset as BufferEncoding)
-
-  return JSON.parse(text)
-}
-
-export function encode(value: any): Buffer {
-  const text = JSON.stringify(value)
-
-  return Buffer.from(text)
-}

package/source/HTTP/formats/msgpack.ts

@@ -1,14 +0,0 @@
-import { pack, unpack } from 'msgpackr'
-
-export function decode(buffer: Buffer): any {
-  return unpack(buffer)
-}
-
-export function encode(value: any): Buffer {
-  if (typeof value === 'object' && value !== null) Object.setPrototypeOf(value, null)
-
-  return pack(value)
-}
-
-export const type = 'application/msgpack'
-export const multipart = 'multipart/msgpack'

package/source/HTTP/formats/text.ts

@@ -1,10 +0,0 @@
-export const type = 'text/plain'
-export const multipart = 'multipart/text'
-
-export function decode(buffer: Buffer, charset = 'utf-8'): any {
-  return buffer.toString(charset as BufferEncoding)
-}
-
-export function encode(value: { toString: () => string }): Buffer {
-  return Buffer.from(value.toString())
-}