@toa.io/extensions.exposition 1.0.0-alpha.28 → 1.0.0-alpha.283

package/source/HTTP/Context.ts

@@ -1,13 +1,21 @@
+import crypto from 'node:crypto'
+import { buffer } from 'node:stream/consumers'
 import Negotiator from 'negotiator'
-import { Timing } from './Timing'
-import { type Format, formats, types } from './formats'
-import { read } from './messages'
-import type { OutgoingMessage } from './messages'
-import type * as http from 'node:http'
+import { console } from 'openspan'
+import { Timing } from './Timing.js'
+import { type Format, formats, types } from './formats/index.js'
+import { read } from './messages.js'
+import { address } from './address.js'
+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
+
+  /** the client address, read as the deployment says; none otherwise, see `documentation/ip.md` */
+  public readonly ip: string | undefined
   public readonly url: URL
   public readonly subtype: string | null = null
   public readonly encoder: Format | null = null
@@ -19,19 +27,26 @@ export class Context {
     response: []
   }
 
-  public constructor (authority: string, request: IncomingMessage, properties: Properties) {
+  private consumed = false
+
+  // eslint-disable-next-line max-params
+  public constructor (authority: string, request: IncomingMessage, properties: Properties,
+    url: URL) {
     this.authority = authority
     this.request = request
+    this.ip = address(request, properties.ip)
 
-    this.url = new URL(request.url, `https://${request.headers.host}`)
-    this.timing = new Timing(properties.trace)
+    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)
 
-    if (this.debug)
-      this.log(request)
+    const accept = this.request.headers.accept
 
-    if (this.request.headers.accept !== undefined) {
-      const match = SUBTYPE.exec(this.request.headers.accept)
+    if (accept !== undefined) {
+      const match = SUBTYPE.exec(accept)
 
       if (match !== null) {
         const {
@@ -45,45 +60,77 @@ export class Context {
       }
     }
 
-    const negotiator = new Negotiator(this.request)
-    const mediaType = negotiator.mediaType(types)
+    const encoder = negotiate(this.request)
+
+    if (encoder !== undefined)
+      this.encoder = encoder
+  }
+
+  public async buffer (): Promise<Buffer> {
+    this.consumed = true
 
-    if (mediaType !== undefined)
-      this.encoder = formats[mediaType]
+    return await buffer(this.request)
   }
 
-  public async body<T> (): Promise<T> {
-    const value = await read(this)
+  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)
 
-    return this.pipelines.body.length === 0
-      ? value
-      : this.pipelines.body.reduce((value, transform) => transform(value), value)
+    return value
   }
 
   private log (request: IncomingMessage): void {
-    const message = `${request.method} ${request.url}`
-    const { authorization, ...headers } = request.headers
+    const headers = { ...request.headers }
 
-    if (authorization !== undefined)
-      headers.authorization = authorization.slice(0, authorization.indexOf(' '))
+    if (headers.authorization !== undefined)
+      headers.authorization = SCHEME.exec(headers.authorization)?.[1] ?? '[malformed]'
 
-    console.debug(message, headers)
+    console.debug('Received request', { method: request.method, url: request.url, headers })
   }
 }
 
-export interface IncomingMessage extends http.IncomingMessage {
-  url: string
-  method: string
-}
+/** The scheme of an `authorization` header; the value after it is a credential. */
+const SCHEME = /^(\w{1,32})(?: |$)/
 
 interface Pipelines {
   body: Array<(input: unknown) => unknown>
-  response: Array<(output: OutgoingMessage) => void>
+  response: Array<(output: OutgoingMessage) => void | Promise<void>>
 }
 
 interface Properties {
   debug: boolean
-  trace: boolean
+
+  /** the header the client address is read from; the connection's without one */
+  ip?: string
 }
 
+/**
+ * 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 {
+  const accept = request.headers.accept ?? ''
+  const known = NEGOTIATED.get(accept)
+
+  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()
+
+  NEGOTIATED.set(accept, encoder ?? NONE)
+
+  return encoder
+}
+
+/** distinguishes "negotiated to nothing" from "not negotiated yet" */
+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})$/

package/source/HTTP/Probe.ts

@@ -0,0 +1,112 @@
+import * as http from 'node:http'
+import { console } from 'openspan'
+
+/**
+ * The readiness probe, on a port of its own.
+ *
+ * It cannot share the port the gateway serves traffic on: kubelet speaks HTTP/1.1 only, and a
+ * cleartext HTTP/2 server answers nothing else on its port — there is no ALPN to negotiate with.
+ *
+ * It is the gateway's own readiness, not the process's. The identity composition nested in this
+ * process connects before route discovery has settled, so a probe tied to that composition would
+ * report ready while the gateway still had no routes and no open port.
+ */
+export class Probe {
+  private readonly server = http.createServer()
+  private readonly port: number
+  private readonly path: string
+
+  private ready = false
+  private startedAt = 0
+  private listening = false
+  private skipped = false
+
+  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> {
+    this.startedAt = Date.now()
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        this.server.once('error', reject)
+        this.server.listen(this.port, () => {
+          this.server.removeListener('error', reject)
+          resolve()
+        })
+      })
+    } catch (error: any) {
+      // processes sharing a host share the port; in a pod nothing else claims it
+      if (error?.code === 'EADDRINUSE') {
+        this.skipped = true
+
+        console.warn('Ready probe port already in use, skipping', { port: this.port })
+
+        return
+      }
+
+      throw error
+    }
+
+    this.listening = true
+
+    // a probe answers while the process runs; it must never be the reason it keeps running
+    this.server.unref()
+  }
+
+  /** The gateway is listening and has routes: answer `200`. */
+  public complete (): void {
+    this.ready = true
+
+    // the IPC signal is not tied to the probe: a process that gave up the shared port is
+    // still ready, and pm2 `wait_ready` would otherwise block until `listen_timeout`
+    process.send?.('ready')
+  }
+
+  public async close (): Promise<void> {
+    this.ready = false
+
+    if (!this.listening || this.skipped)
+      return
+
+    this.listening = false
+
+    // keep-alive connections would otherwise hold the server handle, delaying the exit
+    this.server.closeAllConnections()
+
+    await new Promise<void>((resolve) => this.server.close(() => resolve()))
+  }
+
+  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()
+    else {
+      const remaining = Math.ceil((Date.now() - this.startedAt) / 1000).toString()
+
+      response.writeHead(503, { 'retry-after': remaining }).end()
+    }
+  }
+}
+
+/**
+ * Reserved for this probe. `8001` is the Telemetry readiness probe's, and `toa export` refuses a
+ * port claimed twice — `toa mono` and a local run put every service in one process.
+ */
+export const PROBE = 8004
+export const PATH = '/.ready'
+
+/**
+ * The initial delay of the readiness probe. The server does not sleep for it: whoever
+ * probes is the one that waits, and doing it here as well only delayed the process twice.
+ */
+export const DELAY = 3 // seconds