@toa.io/extensions.exposition 1.0.0-alpha.285 → 1.0.0-alpha.287

package/source/HTTP/exceptions.ts

@@ -5,7 +5,7 @@ export class Exception extends Error {
   /** 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) {
+  protected constructor(status: number, body?: any, headers?: Headers) {
     super()
     this.status = status
     this.body = body
@@ -13,85 +13,87 @@ export class Exception extends Error {
   }
 }
 
-export class ClientError extends Exception {
-}
+export class ClientError extends Exception {}
 
 export class BadRequest extends ClientError {
-  public constructor (body?: any) {
+  public constructor(body?: any) {
     super(400, body)
   }
 }
 
 export class Unauthorized extends ClientError {
-  public constructor (body?: any) {
+  public constructor(body?: any) {
     super(401, body)
   }
 }
 
 export class Forbidden extends ClientError {
-  public constructor (body?: any) {
+  public constructor(body?: any) {
     super(403, body)
   }
 }
 
 export class NotFound extends ClientError {
-  public constructor (body?: any) {
+  public constructor(body?: any) {
     super(404, body)
   }
 }
 
 export class MethodNotAllowed extends ClientError {
-  public constructor (headers?: Headers) {
+  public constructor(headers?: Headers) {
     super(405, undefined, headers)
   }
 }
 
 export class NotAcceptable extends ClientError {
-  public constructor () {
+  public constructor() {
     super(406)
   }
 }
 
 export class Conflict extends ClientError {
-  public constructor (body?: any) {
+  public constructor(body?: any) {
     super(409, body)
   }
 }
 
 export class PreconditionFailed extends ClientError {
-  public constructor () {
+  public constructor() {
     super(412)
   }
 }
 
 export class RequestEntityTooLarge extends ClientError {
-  public constructor (body?: any) {
+  public constructor(body?: any) {
     super(413, body)
   }
 }
 
 export class UnsupportedMediaType extends ClientError {
-  public constructor () {
+  public constructor() {
     super(415)
   }
 }
 
 export class UnprocessableEntity extends ClientError {
-  public constructor (body?: any) {
+  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) }))
+  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) {
+  public constructor(body?: any) {
     super(503, body)
   }
 }

package/source/HTTP/formats/form.ts

@@ -7,7 +7,7 @@ export const type = 'application/x-www-form-urlencoded'
  * 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 {
+export function decode(buffer: Buffer, charset = 'utf-8'): any {
   const params = new URLSearchParams(buffer.toString(charset as BufferEncoding))
   const value: Record<string, string | string[]> = {}
 

package/source/HTTP/formats/json.ts

@@ -1,13 +1,13 @@
 export const type = 'application/json'
 export const multipart = 'multipart/json'
 
-export function decode (buffer: Buffer, charset = 'utf-8'): any {
+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 {
+export function encode(value: any): Buffer {
   const text = JSON.stringify(value)
 
   return Buffer.from(text)

package/source/HTTP/formats/msgpack.ts

@@ -1,12 +1,11 @@
 import { pack, unpack } from 'msgpackr'
 
-export function decode (buffer: Buffer): any {
+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)
+export function encode(value: any): Buffer {
+  if (typeof value === 'object' && value !== null) Object.setPrototypeOf(value, null)
 
   return pack(value)
 }

package/source/HTTP/formats/text.ts

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

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

@@ -9,7 +9,10 @@ it('encodes error values as their public properties', () => {
     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')
+  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', () => {

package/source/HTTP/formats/yaml.ts

@@ -3,35 +3,38 @@ 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 {
+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)
+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))
+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 ('toJSON' in value && typeof value.toJSON === 'function') return value.toJSON()
 
-  if (Array.isArray(value))
-    return value.map(represent)
+  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])
+  for (const key of Object.keys(object)) represented[key] = represent(object[key])
 
   return represented
 }

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