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

package/source/HTTP/messages.ts

@@ -1,90 +1,153 @@
+import { readFileSync } from 'node:fs'
 import { Readable } from 'node:stream'
-import { buffer } from 'node:stream/consumers'
-import { formats } from './formats'
-import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions'
-import type { Context } from './Context'
-import type * as http from 'node:http'
+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)
 
-export function write
-(context: Context, response: http.ServerResponse, message: OutgoingMessage): void {
-  for (const transform of context.pipelines.response)
-    transform(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 (message.body instanceof Readable)
-    stream(message, context, response)
-  else
-    send(message, context, 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 type = context.request.headers['content-type']
+export async function read(context: Context): Promise<any> {
+  const header = context.request.headers['content-type']
+
+  if (header === undefined) return undefined
 
-  if (type === undefined)
-    return undefined
+  const { type, parameters } = contentType.parse(header)
 
-  if (!(type in formats))
-    throw new UnsupportedMediaType()
+  if (!(type in decoders)) throw new UnsupportedMediaType()
 
-  const format = formats[type]
-  const buf = await context.timing.capture('buffer', buffer(context.request))
+  const format = decoders[type]
+  const buf = await context.buffer()
 
   try {
-    return format.decode(buf)
-  } catch {
+    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: http.ServerResponse): void {
+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()
+  if (context.encoder === null) throw new NotAcceptable()
 
   const buf = context.encoder.encode(message.body)
 
-  response
-    .setHeader('content-type', context.encoder.type)
-    .appendHeader('vary', 'accept')
-    .end(buf)
+  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: http.ServerResponse): void {
+function stream(
+  message: OutgoingMessage,
+  context: Context,
+  response: ServerResponse
+): void {
   const encoded = message.headers !== undefined && message.headers.has('content-type')
-
-  if (encoded)
-    message.body.pipe(response)
-  else
-    multipart(message, context, response)
-
-  message.body.on('error', (e: Error) => {
-    console.error(e)
-    response.end()
-  })
+  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 })
+  )
 }
 
-function multipart
-(message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
-  if (context.encoder === null)
-    throw new NotAcceptable()
+/**
+ * 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}`)
 
-  message.body
-    .map((part: unknown) => Buffer.concat([CUT, encoder.encode(part), CRLF]))
-    .on('end', () => response.end(FINALCUT))
-    .pipe(response)
+  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'
@@ -96,6 +159,17 @@ 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 {
@@ -103,6 +177,8 @@ export interface Query {
 
   id?: string
   criteria?: string
+  search?: string
+  sample?: number
   sort?: string
   omit?: string
   limit?: string

package/source/HTTP/types.ts

@@ -0,0 +1,39 @@
+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,18 +1,25 @@
-import type { Input, Output } from './io'
+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[]) {
+  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> {
+  public async intercept(input: Input): Promise<Output> {
     for (const interceptor of this.interceptors) {
       const output = await interceptor.intercept(input)
 
-      if (output !== null)
-        return output
+      if (output !== null) return output
     }
 
     return null
@@ -21,4 +28,10 @@ export class Interception implements Interceptor {
 
 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

@@ -0,0 +1,179 @@
+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
+}