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

package/source/HTTP/Server.ts

@@ -27,32 +27,35 @@ export class Server extends Connector {
 
   private process?: Processor
 
-  private constructor (properties: Properties) {
+  private constructor(properties: Properties) {
     super()
 
     this.properties = properties
-    this.authorities = new Map(Object.entries(properties.authorities).map(([key, value]) => [value, key]))
+    this.authorities = new Map(
+      Object.entries(properties.authorities).map(([key, value]) => [value, key])
+    )
     this.server = instantiate(properties.protocol)
     this.probe = new Probe(properties.probe)
 
     this.server.on('request', (req, res) =>
-      this.listener(req as unknown as IncomingMessage, res as unknown as ServerResponse))
+      this.listener(req as unknown as IncomingMessage, res as unknown as ServerResponse)
+    )
 
     if (properties.protocol === 'h1') this.h1(this.server as http.Server)
     else this.h2(this.server as http2.Http2Server)
   }
 
-  public static create (options: Options): Server {
+  public static create(options: Options): Server {
     const properties: Properties = { ...DEFAULTS, ...options }
 
     return new Server(properties)
   }
 
-  public attach (process: Processor): void {
+  public attach(process: Processor): void {
     this.process = process
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     // answers 503 from here; the gateway's dependencies have settled by the time `open` runs
     await this.probe.listen()
 
@@ -67,7 +70,7 @@ export class Server extends Connector {
     console.info('Ready')
   }
 
-  protected override async close (): Promise<void> {
+  protected override async close(): Promise<void> {
     await this.probe.close()
 
     this.server.close()
@@ -75,8 +78,7 @@ export class Server extends Connector {
     // GOAWAY lets in-flight streams finish; `Http2Server` has no `closeIdleConnections`
     if (this.properties.protocol === 'h1')
       (this.server as http.Server).closeIdleConnections()
-    else
-      for (const session of this.sessions) session.close()
+    else for (const session of this.sessions) session.close()
 
     console.info('Stopped accepting new connections')
 
@@ -88,14 +90,13 @@ export class Server extends Connector {
 
     if (this.properties.protocol === 'h1')
       (this.server as http.Server).closeAllConnections()
-    else
-      for (const session of this.sessions) session.destroy()
+    else for (const session of this.sessions) session.destroy()
 
     console.info('Stopped')
   }
 
   /** A malformed HTTP/1.1 request has no framing to answer in, so the status line is written by hand. */
-  private h1 (server: http.Server): void {
+  private h1(server: http.Server): void {
     server.on('clientError', (error, socket) => {
       console.warn('Client connection error', error)
 
@@ -105,7 +106,7 @@ export class Server extends Connector {
   }
 
   /** HTTP/2 has no `clientError`: failures surface per session, per stream, or per frame. */
-  private h2 (server: http2.Http2Server): void {
+  private h2(server: http2.Http2Server): void {
     server.on('session', (session) => {
       this.sessions.add(session)
       session.on('close', () => this.sessions.delete(session))
@@ -120,12 +121,11 @@ export class Server extends Connector {
     })
   }
 
-  private listener (request: IncomingMessage, response: ServerResponse): void {
+  private listener(request: IncomingMessage, response: ServerResponse): void {
     request.once('error', (error) => {
       console.warn('Request error', errorAttributes(request, error))
 
-      if (!response.writableEnded)
-        response.destroy()
+      if (!response.writableEnded) response.destroy()
     })
 
     // no listener on `request.socket`: under HTTP/2 it is the session's socket, shared by
@@ -134,7 +134,10 @@ export class Server extends Connector {
     const host = authorityOf(request)?.toLowerCase()
 
     if (host === undefined || !HOST.test(host)) {
-      console.warn('Request without a valid authority', errorAttributes(request, new Error('Invalid authority')))
+      console.warn(
+        'Request without a valid authority',
+        errorAttributes(request, new Error('Invalid authority'))
+      )
 
       response.writeHead(400).end()
 
@@ -168,53 +171,55 @@ export class Server extends Connector {
     // if the request carries no trace context, the trace starts here
     const remote = trace(request.headers)
 
-    const processing = remote === null
-      ? this.serve(request, response, authority, url)
-      : run(remote, async () => await this.serve(request, response, authority, url))
+    const processing =
+      remote === null
+        ? this.serve(request, response, authority, url)
+        : run(remote, async () => await this.serve(request, response, authority, url))
 
     processing.catch((error) => {
       console.error('Request processing failed', error)
 
-      if (!response.writableEnded)
-        response.writeHead(500).end()
+      if (!response.writableEnded) response.writeHead(500).end()
     })
   }
 
   // eslint-disable-next-line max-params
-  private async serve (request: IncomingMessage,
+  private async serve(
+    request: IncomingMessage,
     response: ServerResponse,
     authority: string,
-    url: URL): Promise<void> {
-    await console.span({
-      name: `${request.method} ${request.url}`,
-      kind: 'server',
-      service: 'exposition',
-      attributes: { method: request.method, url: request.url, authority }
-    }, async () => {
-      response.setHeader('ray', current()!.traceId)
-
-      const context = new Context(authority, request, this.properties, url)
-
-      await this.process!(context)
-        .then(this.success(context, response))
-        .catch(this.fail(context, response))
-        .finally(() => request.removeAllListeners('error'))
-    })
+    url: URL
+  ): Promise<void> {
+    await console.span(
+      {
+        name: `${request.method} ${request.url}`,
+        kind: 'server',
+        service: 'exposition',
+        attributes: { method: request.method, url: request.url, authority }
+      },
+      async () => {
+        response.setHeader('ray', current()!.traceId)
+
+        const context = new Context(authority, request, this.properties, url)
+
+        await this.process!(context)
+          .then(this.success(context, response))
+          .catch(this.fail(context, response))
+          .finally(() => request.removeAllListeners('error'))
+      }
+    )
   }
 
-  private success (context: Context, response: ServerResponse) {
+  private success(context: Context, response: ServerResponse) {
     return async (message: OutgoingMessage) => {
       let status = message.status
 
       if (status === undefined)
-        if (message.body === null)
-          status = 404
-        else if (context.request.method === 'POST')
-          status = 201
+        if (message.body === null) status = 404
+        else if (context.request.method === 'POST') status = 201
         else if (message.body === undefined && context.request.method !== 'HEAD')
           status = 204
-        else
-          status = 200
+        else status = 200
 
       message.status = status
 
@@ -222,7 +227,7 @@ export class Server extends Connector {
     }
   }
 
-  private fail (context: Context, response: ServerResponse) {
+  private fail(context: Context, response: ServerResponse) {
     return async (exception: Error) => {
       try {
         // Over HTTP/2 the reply is followed by RST_STREAM(NO_ERROR), which tells the client
@@ -234,26 +239,27 @@ export class Server extends Connector {
         const span = current()
 
         // https://opentelemetry.io/docs/specs/semconv/http/http-spans/#status
-        if (status >= 500 && span !== undefined)
-          span.status = 'error'
+        if (status >= 500 && span !== undefined) span.status = 'error'
 
         if (!response.writableEnded) {
           response.statusCode = status
 
-          const message: OutgoingMessage = { status: response.statusCode, authentic: true }
+          const message: OutgoingMessage = {
+            status: response.statusCode,
+            authentic: true
+          }
 
           // eslint-disable-next-line max-depth
           if (exception instanceof Exception && exception.headers !== undefined)
             message.headers = exception.headers
 
           // eslint-disable-next-line max-depth
-          if (context.encoder === null)
-            message.body = undefined
+          if (context.encoder === null) message.body = undefined
           else if (exception instanceof ClientError || this.properties.debug)
             message.body =
               exception instanceof Exception
                 ? exception.body
-                : (this.properties.debug && exception.stack) ?? exception.message
+                : ((this.properties.debug && exception.stack) ?? exception.message)
 
           await write(context, response, message)
         }
@@ -271,9 +277,8 @@ export class Server extends Connector {
   }
 }
 
-function instantiate (protocol: Protocol): http.Server | http2.Http2Server {
-  if (protocol === 'h1')
-    return http.createServer()
+function instantiate(protocol: Protocol): http.Server | http2.Http2Server {
+  if (protocol === 'h1') return http.createServer()
 
   return http2.createServer({
     // realtime pins one stream per subscription, and they all share a session
@@ -286,12 +291,12 @@ function instantiate (protocol: Protocol): http.Server | http2.Http2Server {
  * The authority the request is addressed to. HTTP/2 carries it in `:authority` and omits
  * `host` entirely, so reading `host` alone would leave every HTTP/2 request unattributed.
  */
-function authorityOf (request: IncomingMessage): string | undefined {
+function authorityOf(request: IncomingMessage): string | undefined {
   return request.headers[':authority'] ?? request.headers.host
 }
 
 /** Parsing the URL is how a request is validated, so the `Context` is handed the result. */
-function parse (request: IncomingMessage, authority: string): URL | Error {
+function parse(request: IncomingMessage, authority: string): URL | Error {
   try {
     return new URL(request.url, `https://${authority}`)
   } catch (error) {
@@ -300,7 +305,7 @@ function parse (request: IncomingMessage, authority: string): URL | Error {
 }
 
 // https://github.com/whatwg/fetch/issues/1254
-async function adam (request: IncomingMessage): Promise<void> {
+async function adam(request: IncomingMessage): Promise<void> {
   const devnull = fs.createWriteStream(os.devNull)
 
   devnull.on('error', () => undefined)
@@ -309,18 +314,19 @@ async function adam (request: IncomingMessage): Promise<void> {
   await once(request, 'end')
 }
 
-function errorAttributes (request: IncomingMessage, error: Error & any): RequestErrorAttributes {
+function errorAttributes(
+  request: IncomingMessage,
+  error: Error & any
+): RequestErrorAttributes {
   const attributes: RequestErrorAttributes = {
     path: request.url,
     method: request.method,
     name: error.name
   }
 
-  if (typeof error.code === 'string')
-    attributes.code = error.code
+  if (typeof error.code === 'string') attributes.code = error.code
 
-  if (typeof error.stack === 'string')
-    attributes.stack = error.stack
+  if (typeof error.stack === 'string') attributes.stack = error.stack
 
   return attributes
 }
@@ -341,12 +347,15 @@ const WINDOW = 1024 * 1024
  * The `ray` header adopts the trace by ID only and does not bypass sampling:
  * the sampling decision is made by the server.
  */
-function trace (headers: IncomingMessage['headers']): SpanContext | null {
-  if (typeof headers.traceparent === 'string')
-    return decode(headers.traceparent)
+function trace(headers: IncomingMessage['headers']): SpanContext | null {
+  if (typeof headers.traceparent === 'string') return decode(headers.traceparent)
 
   // adopting a trace by ID does not bypass sampling
-  if (typeof headers.ray === 'string' && RAY.test(headers.ray) && headers.ray !== ZERO_RAY)
+  if (
+    typeof headers.ray === 'string' &&
+    RAY.test(headers.ray) &&
+    headers.ray !== ZERO_RAY
+  )
     return { traceId: headers.ray.toLowerCase(), sampled: decide() }
 
   return null
@@ -362,7 +371,17 @@ const RAY = /^[\da-f]{32}$/i
 const ZERO_RAY = '0'.repeat(32)
 
 const DEFAULTS: Omit<Properties, 'authorities'> = {
-  methods: new Set<string>(['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'LOCK', 'UNLOCK']),
+  methods: new Set<string>([
+    'OPTIONS',
+    'GET',
+    'HEAD',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'LOCK',
+    'UNLOCK'
+  ]),
   debug: false,
   port: PORT,
   drain: DRAIN * 1000,

package/source/HTTP/Timing.ts

@@ -1,29 +1,14 @@
 import { performance } from 'node:perf_hooks'
 import type { ServerResponse } from './types.js'
 
+/** How long the request took, from received to written: one number, the header's. */
 export class Timing {
   private readonly start = performance.now()
-  private readonly breakpoints: Breakpoint[] = []
 
-  public async capture<T>(id: string, promise: Promise<T>): Promise<T> {
-    const start = performance.now()
-    const result = promise instanceof Promise ? await promise : promise
-
-    this.breakpoints.push({ id, duration: performance.now() - start })
-
-    return result
+  public append(response: ServerResponse): void {
+    response.setHeader(
+      'server-timing',
+      `total;dur=${(performance.now() - this.start).toFixed(3)}`
+    )
   }
-
-  public append (response: ServerResponse): void {
-    this.breakpoints.push({ id: 'total', duration: performance.now() - this.start })
-
-    for (const breakpoint of this.breakpoints)
-      response.appendHeader('server-timing',
-        `${breakpoint.id};dur=${breakpoint.duration.toFixed(3)}`)
-  }
-}
-
-interface Breakpoint {
-  id: string
-  duration: number
 }

package/source/HTTP/address.test.ts

@@ -12,8 +12,14 @@ it('should be nothing without a header named', () => {
 })
 
 it('should be the last value of the named header', () => {
-  assert.equal(address(request({ 'x-forwarded-for': '1.1.1.1, 2.2.2.2' }), 'x-forwarded-for'), '2.2.2.2')
-  assert.equal(address(request({ 'cf-connecting-ip': '3.3.3.3' }), 'cf-connecting-ip'), '3.3.3.3')
+  assert.equal(
+    address(request({ 'x-forwarded-for': '1.1.1.1, 2.2.2.2' }), 'x-forwarded-for'),
+    '2.2.2.2'
+  )
+  assert.equal(
+    address(request({ 'cf-connecting-ip': '3.3.3.3' }), 'cf-connecting-ip'),
+    '3.3.3.3'
+  )
 })
 
 it('should be nothing when the named header is absent or empty', () => {

package/source/HTTP/address.ts

@@ -5,9 +5,8 @@ import type { IncomingMessage } from './types.js'
  * Of a header holding a list, the last value is the one the edge in front appended. The
  * connection's address is never it: behind an edge it is the edge's.
  */
-export function address (request: IncomingMessage, header?: string): string | undefined {
-  if (header === undefined)
-    return
+export function address(request: IncomingMessage, header?: string): string | undefined {
+  if (header === undefined) return
 
   const value = request.headers[header]
   const raw = Array.isArray(value) ? value[value.length - 1] : value

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
 }