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

package/source/HTTP/Context.ts

@@ -1,4 +1,3 @@
-import crypto from 'node:crypto'
 import { buffer } from 'node:stream/consumers'
 import Negotiator from 'negotiator'
 import { console } from 'openspan'
@@ -10,7 +9,6 @@ import type { OutgoingMessage } from './messages.js'
 import type { IncomingMessage } from './types.js'
 
 export class Context {
-  public readonly id: string
   public readonly authority: string
   public readonly request: IncomingMessage
 
@@ -20,7 +18,6 @@ export class Context {
   public readonly subtype: string | null = null
   public readonly encoder: Format | null = null
   public readonly timing: Timing
-  public readonly debug: boolean
 
   /**
    * Whether this is a procedure a request made, rather than the request. What forks one
@@ -37,17 +34,19 @@ export class Context {
   private consumed = false
 
   // eslint-disable-next-line max-params
-  public constructor (authority: string, request: IncomingMessage, properties: Properties,
-    url: URL) {
+  public constructor(
+    authority: string,
+    request: IncomingMessage,
+    properties: Properties,
+    url: URL
+  ) {
     this.authority = authority
     this.request = request
     this.ip = address(request, properties.ip)
 
-    this.id = crypto.randomUUID()
     // parsed by the server, which had to parse it anyway to know the request is valid
     this.url = url
     this.timing = new Timing()
-    this.debug = properties.debug
     this.log(request)
 
     const accept = this.request.headers.accept
@@ -56,11 +55,7 @@ export class Context {
       const match = SUBTYPE.exec(accept)
 
       if (match !== null) {
-        const {
-          type,
-          subtype,
-          suffix
-        } = match.groups!
+        const { type, subtype, suffix } = match.groups!
 
         this.request.headers.accept = `${type}/${suffix}`
         this.subtype = subtype
@@ -69,11 +64,10 @@ export class Context {
 
     const encoder = negotiate(this.request)
 
-    if (encoder !== undefined)
-      this.encoder = encoder
+    if (encoder !== undefined) this.encoder = encoder
   }
 
-  public async buffer (): Promise<Buffer> {
+  public async buffer(): Promise<Buffer> {
     this.consumed = true
 
     return await buffer(this.request)
@@ -82,19 +76,21 @@ export class Context {
   public async body<T>(): Promise<T> {
     let value = this.consumed ? null : await read(this)
 
-    for (const transform of this.pipelines.body)
-      value = await transform(value)
+    for (const transform of this.pipelines.body) value = await transform(value)
 
     return value
   }
 
-  private log (request: IncomingMessage): void {
-    const headers = { ...request.headers }
+  private log(request: IncomingMessage): void {
+    // built only when the line is written, which at `info` it is not
+    console.debug('Received request', () => {
+      const headers = { ...request.headers }
 
-    if (headers.authorization !== undefined)
-      headers.authorization = SCHEME.exec(headers.authorization)?.[1] ?? '[malformed]'
+      if (headers.authorization !== undefined)
+        headers.authorization = SCHEME.exec(headers.authorization)?.[1] ?? '[malformed]'
 
-    console.debug('Received request', { method: request.method, url: request.url, headers })
+      return { method: request.method, url: request.url, headers }
+    })
   }
 }
 
@@ -107,8 +103,6 @@ interface Pipelines {
 }
 
 interface Properties {
-  debug: boolean
-
   /** the header the client address is read from; the connection's without one */
   ip?: string
 }
@@ -117,18 +111,16 @@ interface Properties {
  * Negotiation parses the header and sorts the candidates, and the value repeats:
  * clients send one of a handful of `accept` strings. Bounded, the header is theirs.
  */
-function negotiate (request: IncomingMessage): Format | undefined {
+function negotiate(request: IncomingMessage): Format | undefined {
   const accept = request.headers.accept ?? ''
   const known = NEGOTIATED.get(accept)
 
-  if (known !== undefined)
-    return known === NONE ? undefined : known
+  if (known !== undefined) return known === NONE ? undefined : known
 
   const mediaType = new Negotiator(request).mediaType(types)
   const encoder = mediaType === undefined ? undefined : formats[mediaType]
 
-  if (NEGOTIATED.size >= NEGOTIATED_LIMIT)
-    NEGOTIATED.clear()
+  if (NEGOTIATED.size >= NEGOTIATED_LIMIT) NEGOTIATED.clear()
 
   NEGOTIATED.set(accept, encoder ?? NONE)
 
@@ -140,4 +132,5 @@ const NONE = Symbol('not acceptable') as unknown as Format
 const NEGOTIATED = new Map<string, Format>()
 const NEGOTIATED_LIMIT = 1024
 
-const SUBTYPE = /^(?<type>\w{1,32})\/(vnd\.toa\.(?<subtype>\S{1,32})\+)(?<suffix>\S{1,32})$/
+const SUBTYPE =
+  /^(?<type>\w{1,32})\/(vnd\.toa\.(?<subtype>\S{1,32})\+)(?<suffix>\S{1,32})$/

package/source/HTTP/Probe.ts

@@ -21,14 +21,14 @@ export class Probe {
   private listening = false
   private skipped = false
 
-  public constructor (port: number, path: string = PATH) {
+  public constructor(port: number, path: string = PATH) {
     this.port = port
     this.path = path
 
     this.server.on('request', (request, response) => this.listener(request, response))
   }
 
-  public async listen (): Promise<void> {
+  public async listen(): Promise<void> {
     this.startedAt = Date.now()
 
     try {
@@ -59,7 +59,7 @@ export class Probe {
   }
 
   /** The gateway is listening and has routes: answer `200`. */
-  public complete (): void {
+  public complete(): void {
     this.ready = true
 
     // the IPC signal is not tied to the probe: a process that gave up the shared port is
@@ -67,11 +67,10 @@ export class Probe {
     process.send?.('ready')
   }
 
-  public async close (): Promise<void> {
+  public async close(): Promise<void> {
     this.ready = false
 
-    if (!this.listening || this.skipped)
-      return
+    if (!this.listening || this.skipped) return
 
     this.listening = false
 
@@ -81,15 +80,14 @@ export class Probe {
     await new Promise<void>((resolve) => this.server.close(() => resolve()))
   }
 
-  private listener (request: http.IncomingMessage, response: http.ServerResponse): void {
+  private listener(request: http.IncomingMessage, response: http.ServerResponse): void {
     if (request.url !== this.path) {
       response.writeHead(404).end()
 
       return
     }
 
-    if (this.ready)
-      response.writeHead(200, { 'cache-control': 'no-store' }).end()
+    if (this.ready) response.writeHead(200, { 'cache-control': 'no-store' }).end()
     else {
       const remaining = Math.ceil((Date.now() - this.startedAt) / 1000).toString()
 

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