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

package/source/HTTP/formats/yaml.test.ts

@@ -1,22 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { encode } from './yaml.js'
-
-it('encodes error values as their public properties', () => {
-  const value = new (class InvalidUsernameError extends Error {
-    public readonly code = 'INVALID_USERNAME'
-    public override readonly message = 'Username is not meeting the requirements'
-  })()
-
-  assert.strictEqual(
-    encode(value).toString(),
-    'code: INVALID_USERNAME\nmessage: Username is not meeting the requirements\n'
-  )
-})
-
-it('writes a value the way its toJSON says', () => {
-  const secret = { unwrap: () => 's3cret', toJSON: () => '<REDACTED>' }
-
-  assert.strictEqual(encode({ a: 1, b: secret }).toString(), 'a: 1\nb: <REDACTED>\n')
-})

package/source/HTTP/formats/yaml.ts

@@ -1,40 +0,0 @@
-import { yaml } from '@toa.io/generic'
-
-export const type = 'application/yaml'
-export const multipart = 'multipart/yaml'
-
-export function decode(buffer: Buffer, charset = 'utf-8'): any {
-  const text = buffer.toString(charset as BufferEncoding)
-
-  return yaml.load(text)
-}
-
-export function encode(value: any): Buffer {
-  const serializable =
-    value instanceof Error ? Object.assign({}, value) : represent(value)
-  const text = yaml.dump(serializable, { lineWidth: -1, noRefs: true })
-
-  return Buffer.from(text)
-}
-
-/** What says how it is to be written — a redacted secret — is written that way, as in JSON. */
-function represent(value: unknown): unknown {
-  if (
-    typeof value !== 'object' ||
-    value === null ||
-    value instanceof Date ||
-    Buffer.isBuffer(value)
-  )
-    return value
-
-  if ('toJSON' in value && typeof value.toJSON === 'function') return value.toJSON()
-
-  if (Array.isArray(value)) return value.map(represent)
-
-  const object = value as Record<string, unknown>
-  const represented: Record<string, unknown> = {}
-
-  for (const key of Object.keys(object)) represented[key] = represent(object[key])
-
-  return represented
-}

package/source/HTTP/index.ts

@@ -1,6 +0,0 @@
-export * from './Server.js'
-export * from './messages.js'
-export * from './exceptions.js'
-export * from './Context.js'
-export * from './types.js'
-export * from './Probe.js'

package/source/HTTP/messages.test.ts

@@ -1,196 +0,0 @@
-import { describe, it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { PassThrough, Readable } from 'node:stream'
-import * as streamConsumers from 'node:stream/consumers'
-import { generate } from 'randomstring'
-import * as msgpack from 'msgpackr'
-import { multipart, read, type OutgoingMessage } from './messages.js'
-import { BadRequest, UnsupportedMediaType } from './exceptions.js'
-import { formats, types } from './formats/index.js'
-import { Timing } from './Timing.js'
-import type * as http from 'node:http'
-import type { Context } from './Context.js'
-
-beforeEach(() => {
-  resetCalls()
-})
-
-describe('read', () => {
-  it('should parse application/json', async () => {
-    const path = generate()
-    const headers = { 'content-type': 'application/json' }
-    const input = { [generate()]: generate() }
-    const json = JSON.stringify(input)
-    const context = createContext(path, headers, json)
-    const output = await read(context)
-
-    assert.deepStrictEqual(output, input)
-  })
-
-  it('should parse application/yaml', async () => {
-    const path = generate()
-    const headers = { 'content-type': 'application/yaml' }
-    const yaml = 'foo: 1'
-    const request = createContext(path, headers, yaml)
-    const value = await read(request)
-
-    assert.deepStrictEqual(value, { foo: 1 })
-  })
-
-  it('should parse application/mskpack', async () => {
-    const path = generate()
-    const headers = { 'content-type': 'application/msgpack' }
-    const input = { [generate()]: generate() }
-    const msg = msgpack.encode(input)
-    const request = createContext(path, headers, msg)
-    const output = await read(request)
-
-    assert.deepStrictEqual(output, input)
-  })
-
-  it('should parse text/plain', async () => {
-    const path = generate()
-    const headers = { 'content-type': 'text/plain' }
-    const input = generate()
-    const request = createContext(path, headers, input)
-    const output = await read(request)
-
-    assert.deepStrictEqual(output, input)
-  })
-
-  it('should parse application/json with charset parameter', async () => {
-    const path = generate()
-    const headers = { 'content-type': 'application/json; charset=utf-8' }
-    const input = { [generate()]: generate() }
-    const json = JSON.stringify(input)
-    const context = createContext(path, headers, json)
-    const output = await read(context)
-
-    assert.deepStrictEqual(output, input)
-  })
-
-  it('should throw on unsupported request media type', async () => {
-    const path = generate()
-    const headers = { 'content-type': 'wtf/' + generate() }
-    const request = createContext(path, headers)
-
-    await assert.rejects(read(request), UnsupportedMediaType)
-  })
-
-  it('should throw on malformed content', async () => {
-    const path = generate()
-    const text = '{ "foo": "val... oops '
-    const headers = { 'content-type': 'application/json' }
-    const request = createContext(path, headers, text)
-
-    await assert.rejects(read(request), BadRequest)
-  })
-
-  it('should parse application/x-www-form-urlencoded', async () => {
-    const headers = { 'content-type': 'application/x-www-form-urlencoded' }
-    const form = 'grant_type=authorization_code&code=SplxlO&scope=a+b'
-    const request = createContext(generate(), headers, form)
-
-    assert.deepStrictEqual(await read(request), {
-      grant_type: 'authorization_code',
-      code: 'SplxlO',
-      scope: 'a b'
-    })
-  })
-
-  it('should read a repeated form name as the list it is', async () => {
-    const headers = { 'content-type': 'application/x-www-form-urlencoded' }
-    const request = createContext(generate(), headers, 'resource=one&resource=two')
-
-    assert.deepStrictEqual(await read(request), { resource: ['one', 'two'] })
-  })
-
-  it('should not offer a form as a reply encoding', () => {
-    assert.ok(
-      !types.includes('application/x-www-form-urlencoded'),
-      'a form is read and never written'
-    )
-  })
-
-  it('should output correct mulitpart format', async () => {
-    const response = new (class extends PassThrough {
-      public readonly headers = new Headers()
-
-      public setHeader(key: string, value: string): this {
-        this.headers.set(key, value)
-
-        return this
-      }
-    })()
-
-    const context = { encoder: formats['text/plain'] } as unknown as Context
-    const message = {
-      body: Readable.from(['Hello', 'New', 'World'])
-    } as unknown as OutgoingMessage
-
-    const framed = multipart(message, context, response as unknown as http.ServerResponse)
-
-    const result = await streamConsumers.text(framed)
-
-    assert.strictEqual(
-      result,
-      [
-        '--cut',
-        '',
-        'ACK',
-        '--cut',
-        '',
-        'Hello',
-        '--cut',
-        '',
-        'New',
-        '--cut',
-        '',
-        'World',
-        '--cut',
-        '',
-        'FIN',
-        '--cut--'
-      ].join('\r\n')
-    )
-  })
-})
-
-export function createContext(
-  url: string,
-  headers: Record<string, string> = {},
-  content: string | Buffer = ''
-): Context {
-  const data = Buffer.isBuffer(content) ? content : Buffer.from(content)
-  const stream = Readable.from(data)
-  let consumed = false
-
-  const mock: Partial<Context> = {
-    request: Object.assign(stream, {
-      url,
-      headers
-    }) as unknown as Context['request'],
-    url: new URL(url, 'https://host.local'),
-    timing: new Timing(),
-    buffer: async () => {
-      if (consumed) throw new Error('Request body already consumed')
-
-      consumed = true
-
-      return data
-    }
-  }
-
-  return mock as unknown as Context
-}
-
-function resetCalls(target = [], seen = new Set()) {
-  if (target === null || typeof target !== 'object' || seen.has(target)) return
-
-  seen.add(target)
-
-  for (const value of Object.values(target))
-    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
-    else resetCalls(value, seen)
-}

package/source/HTTP/messages.ts

@@ -1,186 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { Readable } from 'node:stream'
-import { pipeline } from 'node:stream/promises'
-import * as contentType from 'content-type'
-import { console } from 'openspan'
-import { type Format, decoders } from './formats/index.js'
-import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions.js'
-import { environment } from '@toa.io/generic'
-import type { Context } from './Context.js'
-import type { ServerResponse } from './types.js'
-
-const context = environment.get('TOA_CONTEXT')
-const env = environment.get('TOA_ENV')
-const server =
-  `Exposition/${JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version}` +
-  ((context === undefined ? '' : ` ${context}`) + (env === undefined ? '' : `/${env}`))
-
-/**
- * Applies what the request accumulated in `pipelines.response` — an `io:output` restriction,
- * a `vary` a `map` directive owes. Separate from `write` because a message is not always
- * written: one call of several produces a value the reply is assembled from.
- */
-export async function shape(context: Context, message: OutgoingMessage): Promise<void> {
-  for (const transform of context.pipelines.response) await transform(message)
-}
-
-export async function write(
-  context: Context,
-  response: ServerResponse,
-  message: OutgoingMessage
-): Promise<void> {
-  await shape(context, message)
-
-  if (message?.status !== undefined) response.statusCode = message.status
-
-  response.setHeader('server', server)
-  message.headers?.forEach((value, key) => response.setHeader(key, value))
-  context.timing.append(response)
-
-  if (response.destroyed) {
-    console.warn('Request destroyed prematurely', { path: context.url.pathname })
-
-    return
-  }
-
-  response.on('error', (exception: Error) =>
-    console.warn('HTTP response error', { path: context.url.pathname, exception })
-  )
-
-  if (message.body instanceof Readable) stream(message, context, response)
-  else send(message, context, response)
-}
-
-export async function read(context: Context): Promise<any> {
-  const header = context.request.headers['content-type']
-
-  if (header === undefined) return undefined
-
-  const { type, parameters } = contentType.parse(header)
-
-  if (!(type in decoders)) throw new UnsupportedMediaType()
-
-  const format = decoders[type]
-  const buf = await context.buffer()
-
-  try {
-    return format.decode(buf, parameters.charset)
-  } catch (error: unknown) {
-    console.debug('Failed to decode message', {
-      path: context.url.pathname,
-      error: error?.toString?.()
-    })
-
-    throw new BadRequest()
-  }
-}
-
-function send(
-  message: OutgoingMessage,
-  context: Context,
-  response: ServerResponse
-): void {
-  if (message.body === undefined || message.body === null) {
-    // a HEAD reply carries no body but must still report the length a GET would
-    // have returned, so a length already set by a directive is left alone
-    if (!response.hasHeader('content-length')) response.setHeader('content-length', '0')
-
-    response.end()
-
-    return
-  }
-
-  if (context.encoder === null) throw new NotAcceptable()
-
-  const buf = context.encoder.encode(message.body)
-
-  response.setHeader('content-type', context.encoder.type)
-  response.setHeader('content-length', buf.length.toString())
-  response.appendHeader('vary', 'accept')
-  response.end(buf)
-}
-
-function stream(
-  message: OutgoingMessage,
-  context: Context,
-  response: ServerResponse
-): void {
-  const encoded = message.headers !== undefined && message.headers.has('content-type')
-  const source: Readable = encoded ? message.body : multipart(message, context, response)
-
-  // not awaited: a reply that streams is written long after the request is answered, and a
-  // realtime subscription outlives the span the reply was produced in
-  //
-  // `pipeline` carries an error to every stage and destroys them. `pipe` leaves the stages it
-  // built behind, and an `error` on a stream nobody listens to is an uncaught exception.
-  pipeline(source, response).catch((exception: Error) =>
-    console.warn('Message stream error', { path: context.url.pathname, exception })
-  )
-}
-
-/**
- * Frames an object stream as `multipart/*`: an `ACK` part, the parts themselves, then `FIN`.
- * The body is a `Readable`; `write` reached here by testing it.
- */
-export function multipart(
-  message: OutgoingMessage,
-  context: Context,
-  response: ServerResponse
-): Readable {
-  if (context.encoder === null) throw new NotAcceptable()
-
-  const encoder = context.encoder
-
-  response.setHeader('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`)
-
-  return Readable.from(frames(message.body as Readable, encoder))
-}
-
-async function* frames(body: Readable, encoder: Format): AsyncGenerator<Buffer> {
-  yield Buffer.concat([CUT, CRLF, encoder.encode('ACK'), CRLF, CUT])
-
-  for await (const part of body)
-    yield Buffer.concat([
-      CRLF /* indicates no boundary headers */,
-      encoder.encode(part),
-      CRLF,
-      CUT
-    ])
-
-  yield Buffer.concat([CRLF, encoder.encode('FIN'), CRLF, FINALCUT])
-}
-
-const BOUNDARY = 'cut'
-const CUT = Buffer.from(`--${BOUNDARY}\r\n`)
-const CRLF = Buffer.from('\r\n')
-const FINALCUT = Buffer.from(`--${BOUNDARY}--`)
-
-export interface OutgoingMessage {
-  status?: number
-  headers?: Headers
-  body?: any
-
-  /** what the reply carries for a cache to validate by; the `cache` family sets the headers */
-  version?: number
-  modified?: number | string
-
-  /**
-   * Built by the gateway rather than returned by an operation, as a request is `authentic`
-   * when it was made by one: what is in it is the gateway's own, and the checks that answer
-   * for what an operation returns have nothing to say about it.
-   */
-  authentic?: boolean
-}
-
-export interface Query {
-  [key: string]: string | number | undefined
-
-  id?: string
-  criteria?: string
-  search?: string
-  sample?: number
-  sort?: string
-  omit?: string
-  limit?: string
-  version?: number
-}

package/source/HTTP/types.ts

@@ -1,39 +0,0 @@
-import type { Readable, Writable } from 'node:stream'
-import type { OutgoingHttpHeaders } from 'node:http'
-import type { IncomingHttpHeaders } from 'node:http2'
-
-/**
- * What Exposition requires of a request. Both `http.IncomingMessage` and
- * `http2.Http2ServerRequest` satisfy it, so the pipeline is written once.
- */
-export interface IncomingMessage extends Readable {
-  url: string
-  method: string
-  complete: boolean
-  headers: IncomingHeaders
-  socket: { remoteAddress?: string | undefined }
-}
-
-/**
- * What Exposition requires of a response.
- *
- * `setHeader` and `appendHeader` return `void` because `Http2ServerResponse` returns
- * nothing from them, so neither can be chained.
- */
-export interface ServerResponse extends Writable {
-  statusCode: number
-  writableEnded: boolean
-  setHeader: (name: string, value: number | string | string[]) => void
-  appendHeader: (name: string, value: string | string[]) => void
-  hasHeader: (name: string) => boolean
-  writeHead: (status: number, headers?: OutgoingHttpHeaders) => ServerResponse
-}
-
-/**
- * HTTP/2's header map: HTTP/1.1's, plus the pseudo-headers. `:authority` is typed here
- * so the authority can be read without narrowing at every call site.
- */
-export type IncomingHeaders = IncomingHttpHeaders
-
-/** `h2c` is cleartext HTTP/2: there is no in-process TLS to negotiate ALPN with. */
-export type Protocol = 'h1' | 'h2c'

package/source/Interception.ts

@@ -1,37 +0,0 @@
-import type * as http from './HTTP/index.js'
-import type { Input, Output } from './io.js'
-
-export class Interception implements Interceptor {
-  private readonly interceptors: Interceptor[]
-
-  public constructor(interceptors: Interceptor[], options: http.Options) {
-    this.interceptors = interceptors
-
-    // interceptors are module singletons, so a second gateway in one process —
-    // which is how the features run — would otherwise inherit the first one's state
-    for (const interceptor of interceptors) {
-      interceptor.reset?.()
-      interceptor.mount?.(options)
-    }
-  }
-
-  public async intercept(input: Input): Promise<Output> {
-    for (const interceptor of this.interceptors) {
-      const output = await interceptor.intercept(input)
-
-      if (output !== null) return output
-    }
-
-    return null
-  }
-}
-
-export interface Interceptor {
-  intercept: (input: Input) => Output | Promise<Output>
-
-  /** Discards whatever the interceptor accumulated while serving. */
-  reset?: () => void
-
-  /** What the annotation says, for an interceptor that answers from it. */
-  mount?: (options: http.Options) => void
-}