@toa.io/extensions.exposition 1.0.0-alpha.284 → 1.0.0-alpha.286

package/source/HTTP/messages.test.ts

@@ -107,50 +107,61 @@ describe('read', () => {
   })
 
   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')
+    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 {
+    const response = new (class extends PassThrough {
       public readonly headers = new Headers()
 
-      public setHeader (key: string, value: string): this {
+      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 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'))
+    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 {
+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
@@ -163,8 +174,7 @@ Context {
     url: new URL(url, 'https://host.local'),
     timing: new Timing(),
     buffer: async () => {
-      if (consumed)
-        throw new Error('Request body already consumed')
+      if (consumed) throw new Error('Request body already consumed')
 
       consumed = true
 
@@ -175,7 +185,7 @@ Context {
   return mock as unknown as Context
 }
 
-function resetCalls (target = [], seen = new Set()) {
+function resetCalls(target = [], seen = new Set()) {
   if (target === null || typeof target !== 'object' || seen.has(target)) return
 
   seen.add(target)

package/source/HTTP/messages.ts

@@ -1,7 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
-import { createHash } from 'node:crypto'
 import * as contentType from 'content-type'
 import { console } from 'openspan'
 import { type Format, decoders } from './formats/index.js'
@@ -9,27 +8,28 @@ import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions.js
 import type { Context } from './Context.js'
 import type { ServerResponse } from './types.js'
 
-const server = `Exposition/${JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version}` +
+const server =
+  `Exposition/${JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version}` +
   ((process.env.TOA_CONTEXT === undefined ? '' : ` ${process.env.TOA_CONTEXT}`) +
     (process.env.TOA_ENV === undefined ? '' : `/${process.env.TOA_ENV}`))
 
-const pending = new Map<string, PendingStream>()
-
 /**
  * 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 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> {
+export async function write(
+  context: Context,
+  response: ServerResponse,
+  message: OutgoingMessage
+): Promise<void> {
   await shape(context, message)
 
-  if (message?.status !== undefined)
-    response.statusCode = message.status
+  if (message?.status !== undefined) response.statusCode = message.status
 
   response.setHeader('server', server)
   message.headers?.forEach((value, key) => response.setHeader(key, value))
@@ -42,24 +42,21 @@ export async function write (context: Context, response: ServerResponse, message
   }
 
   response.on('error', (exception: Error) =>
-    console.warn('HTTP response error', { path: context.url.pathname, exception }))
+    console.warn('HTTP response error', { path: context.url.pathname, exception })
+  )
 
-  if (message.body instanceof Readable)
-    stream(message, context, response)
-  else
-    send(message, context, response)
+  if (message.body instanceof Readable) stream(message, context, response)
+  else send(message, context, response)
 }
 
-export async function read (context: Context): Promise<any> {
+export async function read(context: Context): Promise<any> {
   const header = context.request.headers['content-type']
 
-  if (header === undefined)
-    return undefined
+  if (header === undefined) return undefined
 
   const { type, parameters } = contentType.parse(header)
 
-  if (!(type in decoders))
-    throw new UnsupportedMediaType()
+  if (!(type in decoders)) throw new UnsupportedMediaType()
 
   const format = decoders[type]
   const buf = await context.buffer()
@@ -76,56 +73,36 @@ export async function read (context: Context): Promise<any> {
   }
 }
 
-function send (message: OutgoingMessage, context: Context, response: 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')
+    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)
 
-  if (message.etag === true && conditional(context, response, buf))
-    return
-
   response.setHeader('content-type', context.encoder.type)
   response.setHeader('content-length', buf.length.toString())
   response.appendHeader('vary', 'accept')
   response.end(buf)
 }
 
-/**
- * Tags a reply that carries no version with a hash of the body being sent, and answers
- * `304` when the client already has it. The tag is taken from the encoded body rather
- * than from a serialization of its own, so it identifies the representation — which is
- * what `vary` says.
- */
-function conditional (context: Context, response: ServerResponse, buf: Buffer): boolean {
-  const etag = `"${createHash('sha256').update(buf).digest('hex')}"`
-
-  response.setHeader('etag', etag)
-
-  if (context.request.headers['if-none-match'] !== etag)
-    return false
-
-  response.setHeader('content-length', '0')
-  response.appendHeader('vary', 'accept')
-
-  response.statusCode = 304
-  response.end()
-
-  return true
-}
-
-function stream (message: OutgoingMessage, context: Context, response: ServerResponse): void {
+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)
 
@@ -134,21 +111,21 @@ function stream (message: OutgoingMessage, context: Context, response: ServerRes
   //
   // `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 }))
-
-  if (context.debug)
-    debugStream(context, response)
+  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()
+export function multipart(
+  message: OutgoingMessage,
+  context: Context,
+  response: ServerResponse
+): Readable {
+  if (context.encoder === null) throw new NotAcceptable()
 
   const encoder = context.encoder
 
@@ -157,7 +134,7 @@ export function multipart (message: OutgoingMessage, context: Context, response:
   return Readable.from(frames(message.body as Readable, encoder))
 }
 
-async function * frames (body: Readable, encoder: Format): AsyncGenerator<Buffer> {
+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)
@@ -165,7 +142,8 @@ async function * frames (body: Readable, encoder: Format): AsyncGenerator<Buffer
       CRLF /* indicates no boundary headers */,
       encoder.encode(part),
       CRLF,
-      CUT])
+      CUT
+    ])
 
   yield Buffer.concat([CRLF, encoder.encode('FIN'), CRLF, FINALCUT])
 }
@@ -175,41 +153,14 @@ const CUT = Buffer.from(`--${BOUNDARY}\r\n`)
 const CRLF = Buffer.from('\r\n')
 const FINALCUT = Buffer.from(`--${BOUNDARY}--`)
 
-const PENDING_DEBUG_INTERVAL = 30000
-
-let pendingInterval: NodeJS.Timeout | null = null
-
-function debugStream (context: Context, response: ServerResponse): void {
-  const ctx = { method: context.request.method, path: context.url.pathname }
-
-  console.debug('Stream opened', ctx)
-  pending.set(context.id, ctx)
-
-  response.on('close', () => {
-    console.debug('Stream closed', ctx)
-    pending.delete(context.id)
-
-    if (pending.size === 0) {
-      if (pendingInterval !== null)
-        clearInterval(pendingInterval)
-
-      pendingInterval = null
-    }
-  })
-
-  if (pendingInterval === null)
-    pendingInterval = setInterval(() =>
-      console.debug('Pending streams', { size: pending.size }),
-    PENDING_DEBUG_INTERVAL)
-}
-
 export interface OutgoingMessage {
   status?: number
   headers?: Headers
   body?: any
 
-  /** tag the response with a hash of the encoded body, see `conditional` */
-  etag?: boolean
+  /** 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`
@@ -231,8 +182,3 @@ export interface Query {
   limit?: string
   version?: number
 }
-
-interface PendingStream {
-  method: string
-  path: string
-}

package/source/Interception.ts

@@ -4,7 +4,7 @@ import type { Input, Output } from './io.js'
 export class Interception implements Interceptor {
   private readonly interceptors: Interceptor[]
 
-  public constructor (interceptors: Interceptor[], options: http.Options) {
+  public constructor(interceptors: Interceptor[], options: http.Options) {
     this.interceptors = interceptors
 
     // interceptors are module singletons, so a second gateway in one process —
@@ -15,12 +15,11 @@ export class Interception implements Interceptor {
     }
   }
 
-  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

package/source/Introspection.ts

@@ -8,6 +8,9 @@ export interface Introspection {
    * 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
   route?: Record<string, Schema>
   query?: Record<string, Schema>
 
@@ -30,28 +33,40 @@ export type Schema = Awaited<ReturnType<Remote['explain']>>['input']
  * 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 {
+export function order(introspection: Introspection): Introspection {
   const ordered: Introspection = {}
 
   for (const key of KEYS)
-    if (introspection[key] !== undefined)
-      (ordered[key] as unknown) = introspection[key]
+    if (introspection[key] !== undefined) (ordered[key] as unknown) = introspection[key]
 
   return ordered
 }
 
-const KEYS = ['description', 'route', 'query', 'headers', 'input', 'output', 'errors'] as const
+const KEYS = [
+  'title',
+  'description',
+  'route',
+  'query',
+  'headers',
+  '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 {
+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))
+  if (
+    input === undefined ||
+    input === null ||
+    properties === undefined ||
+    !(property in properties)
+  )
     return undefined
 
   const schema = properties[property]
@@ -69,23 +84,23 @@ export function take (carrier: Carrier, property: string): Schema | undefined {
  * 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 {
+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 === 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
+  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
+    if (allowed.has(name)) properties[name] = property
 
   const restricted: Shape = { ...shape, properties }