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

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
-}

package/source/Introspection.ts

@@ -1,179 +0,0 @@
-import type { Remote } from '@toa.io/core'
-import type { Context } from './HTTP/index.js'
-
-export interface Introspection {
-  /**
-   * What the route states this method is. The operation states what it is too, and that is
-   * not this: an operation is written without knowledge of any route, and a method is an
-   * operation and a route together — the same operation mounted twice is two methods, and
-   * one sentence cannot be true of both. The operation's own is for the Introspection.
-   */
-  description?: string
-
-  /** what a person is shown where a client lists this method, which a name is not */
-  title?: string
-
-  /**
-   * whether reaching it takes nothing at all — `auth:anonymous`. Said rather than left
-   * unsaid, because it is also what refuses a caller presenting a credential: a client
-   * cannot know that from an answer that says nothing.
-   */
-  anonymous?: boolean
-
-  /** whether reaching it takes being someone, whoever — `auth:anyone` and its like */
-  authenticated?: boolean
-
-  /** whether reaching it is being the identity it is about — `auth:id` */
-  private?: boolean
-
-  /** whether reaching it takes a role — `auth:role` */
-  protected?: boolean
-
-  /** and whether that role is one of the `system` scope */
-  system?: boolean
-
-  /** whether the route publishes this method to a model — [`mcp:tool`](mcp.md) */
-  mcp?: boolean
-  route?: Record<string, Schema>
-  query?: Record<string, Schema>
-
-  /** what the body is, where it is a file rather than a value — [`octets:put`](octets.md) */
-  octets?: Octets
-  input?: Schema
-  output?: Schema
-  errors?: string[]
-}
-
-/** What sending a file to a resource takes, which is not something a schema states. */
-export interface Octets {
-  /** what may be sent, in the syntax of an `accept` header; anything where unstated */
-  accept?: string
-
-  /** the largest body it takes, as it is written and as a refusal reports it */
-  limit: string
-
-  /**
-   * Whether the reply arrives as a stream of parts rather than as one object: a workflow
-   * runs on what was stored, and each step answers as it finishes. The first part is the
-   * entry itself, which is what a caller that wants nothing else reads and stops.
-   */
-  stream?: boolean
-}
-
-export type Schema = Awaited<ReturnType<Remote['explain']>>['input']
-
-/**
- * The same request, as a description of a resource rather than a call to one. A directive
- * that answers differently to the two reads `exploratory` — `Anonymous` is the one that
- * does, because the rule refusing a credential at an `anonymous` route is about a reply a
- * cache would hold, and a description is not one.
- */
-export function describing(context: Context): Context {
-  return Object.create(context, {
-    exploratory: { value: true, enumerable: true }
-  }) as Context
-}
-
-/**
- * The same, in the order the shape states — whatever order the families that filled it ran
- * in. What a resource says about itself is read, so it is written the way it is documented.
- */
-export function order(introspection: Introspection): Introspection {
-  const ordered: Introspection = {}
-
-  for (const key of KEYS)
-    if (introspection[key] !== undefined) (ordered[key] as unknown) = introspection[key]
-
-  return ordered
-}
-
-const KEYS = [
-  'title',
-  'description',
-  'anonymous',
-  'authenticated',
-  'private',
-  'protected',
-  'system',
-  'mcp',
-  'route',
-  'query',
-  'octets',
-  'input',
-  'output',
-  'errors'
-] as const
-
-/**
- * The schema of one input property, taken out of it: a property another family fills is
- * not the caller's to send, and what took it says where it comes from instead.
- */
-export function take(carrier: Carrier, property: string): Schema | undefined {
-  const input = carrier.input as Shape | null | undefined
-  const properties = input?.properties
-
-  if (
-    input === undefined ||
-    input === null ||
-    properties === undefined ||
-    !(property in properties)
-  )
-    return undefined
-
-  const schema = properties[property]
-
-  delete properties[property]
-
-  if (input.required !== undefined)
-    input.required = input.required.filter((name) => name !== property)
-
-  return schema
-}
-
-/**
- * A schema restricted to the properties a whitelist admits, and an array's items where it
- * describes an array. What is not an object of properties is left alone: a whitelist has
- * nothing to say about a string.
- */
-export function restrict(
-  schema: Schema | undefined,
-  allowed: Set<string>
-): Schema | undefined {
-  const shape = schema as Shape | null | undefined
-
-  if (shape === undefined || shape === null) return schema
-
-  if (shape.items !== undefined)
-    return { ...shape, items: restrict(shape.items, allowed) } as unknown as Schema
-
-  if (shape.properties === undefined) return schema
-
-  const properties: Record<string, Schema> = {}
-
-  for (const [name, property] of Object.entries(shape.properties))
-    if (allowed.has(name)) properties[name] = property
-
-  const restricted: Shape = { ...shape, properties }
-
-  if (shape.required !== undefined)
-    restricted.required = shape.required.filter((name) => allowed.has(name))
-
-  return restricted as unknown as Schema
-}
-
-/**
- * What a schema is read as here: the keywords these narrow, and whatever else it carries.
- * `Schema` as core declares it requires `properties`, which a schema of a string has not,
- * so the two are cast through rather than assigned.
- */
-/** Whatever states an input: an explanation as the operation gave it, or as a route left it. */
-interface Carrier {
-  input?: Schema
-}
-
-interface Shape {
-  properties?: Record<string, Schema>
-  required?: string[]
-  items?: Schema
-  [keyword: string]: unknown
-}