@toa.io/extensions.exposition 1.0.0-alpha.274 → 1.0.0-alpha.277

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

package/source/HTTP/Server.ts

@@ -2,36 +2,42 @@ import assert from 'node:assert'
 import fs from 'node:fs'
 import os from 'node:os'
 import * as http from 'node:http'
+import * as http2 from 'node:http2'
 import { once } from 'node:events'
 import { setTimeout } from 'node:timers/promises'
 import { console, current, decide, decode, run, type SpanContext } from 'openspan'
 import { Connector } from '@toa.io/core'
-import { type OutgoingMessage, write } from './messages'
-import { ClientError, Exception } from './exceptions'
-import { Context, type IncomingMessage } from './Context'
+import { type OutgoingMessage, write } from './messages.js'
+import { ClientError, Exception } from './exceptions.js'
+import { Context } from './Context.js'
+import { PROBE, Probe } from './Probe.js'
+import type { IncomingMessage, Protocol, ServerResponse } from './types.js'
 
 export class Server extends Connector {
-  private readonly server: http.Server = http.createServer()
+  private readonly server: http.Server | http2.Http2Server
   private readonly properties: Properties
   private readonly authorities: Record<string, string>
+
+  /** Tracked for the drain: `Http2Server` has no `closeIdleConnections`. */
+  private readonly sessions = new Set<http2.ServerHttp2Session>()
+
+  private readonly probe: Probe
+
   private process?: Processor
-  private ready: boolean = false
-  private startedAt: number = 0
 
   private constructor (properties: Properties) {
     super()
 
     this.properties = properties
     this.authorities = Object.fromEntries(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, res))
+    this.server.on('request', (req, res) =>
+      this.listener(req as unknown as IncomingMessage, res as unknown as ServerResponse))
 
-    this.server.on('clientError', (error, socket) => {
-      console.warn('Client connection error', error)
-
-      if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
-      else socket.destroy()
-    })
+    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 {
@@ -45,24 +51,30 @@ export class Server extends Connector {
   }
 
   protected override async open (): Promise<void> {
-    this.startedAt = Date.now()
+    // answers 503 from here; the gateway's dependencies have settled by the time `open` runs
+    await this.probe.listen()
+
     this.server.listen(this.properties.port)
 
     await once(this.server, 'listening')
 
     console.info('HTTP Server is listening')
 
-    this.ready = true
+    this.probe.complete()
 
     console.info('Ready')
-    process.send?.('ready')
   }
 
   protected override async close (): Promise<void> {
-    this.ready = false
+    await this.probe.close()
 
     this.server.close()
-    this.server.closeIdleConnections()
+
+    // 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()
 
     console.info('Stopped accepting new connections')
 
@@ -72,12 +84,41 @@ export class Server extends Connector {
       setTimeout(this.properties.drain, undefined, { ref: false })
     ])
 
-    this.server.closeAllConnections()
+    if (this.properties.protocol === 'h1')
+      (this.server as http.Server).closeAllConnections()
+    else
+      for (const session of this.sessions) session.destroy()
 
     console.info('Stopped')
   }
 
-  private listener (request: http.IncomingMessage, response: http.ServerResponse): void {
+  /** 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 {
+    server.on('clientError', (error, socket) => {
+      console.warn('Client connection error', error)
+
+      if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
+      else socket.destroy()
+    })
+  }
+
+  /** HTTP/2 has no `clientError`: failures surface per session, per stream, or per frame. */
+  private h2 (server: http2.Http2Server): void {
+    server.on('session', (session) => {
+      this.sessions.add(session)
+      session.on('close', () => this.sessions.delete(session))
+    })
+
+    server.on('sessionError', (error) => console.warn('Session error', error))
+    server.on('streamError', (error) => console.warn('Stream error', error))
+
+    server.on('unknownProtocol', (socket) => {
+      console.warn('Unknown protocol')
+      socket.destroy()
+    })
+  }
+
+  private listener (request: IncomingMessage, response: ServerResponse): void {
     request.once('error', (error) => {
       console.warn('Request error', errorAttributes(request, error))
 
@@ -85,14 +126,24 @@ export class Server extends Connector {
         response.destroy()
     })
 
-    request.socket.once('error', (error) => {
-      console.warn('Socket error', errorAttributes(request, error))
+    // no listener on `request.socket`: under HTTP/2 it is the session's socket, shared by
+    // every concurrent stream, and removing listeners on it would strip the siblings'
 
-      if (!response.writableEnded)
-        response.destroy()
-    })
+    const host = authorityOf(request)
+
+    if (host === undefined) {
+      console.warn('Request without an authority', errorAttributes(request, new Error('No authority')))
 
-    const url = parse(request)
+      response.writeHead(400).end()
+
+      return
+    }
+
+    // directives and components read `host`; HTTP/2 sends `:authority` instead, and what a
+    // component sees must not depend on the protocol the request arrived over
+    request.headers.host ??= host
+
+    const url = parse(request, host)
 
     if (url instanceof Error) {
       console.warn('Invalid request', errorAttributes(request, url))
@@ -108,21 +159,8 @@ export class Server extends Connector {
       return
     }
 
-    if (request.url === '/.ready') {
-      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()
-      }
-
-      return
-    }
-
     assert(this.process !== undefined, 'Request processor is not attached')
 
-    const host = request.headers.host!
     const authority = this.authorities[host] ?? host
 
     // if the request carries no trace context, the trace starts here
@@ -141,8 +179,8 @@ export class Server extends Connector {
   }
 
   // eslint-disable-next-line max-params
-  private async serve (request: http.IncomingMessage,
-    response: http.ServerResponse,
+  private async serve (request: IncomingMessage,
+    response: ServerResponse,
     authority: string,
     url: URL): Promise<void> {
     await console.span({
@@ -153,19 +191,16 @@ export class Server extends Connector {
     }, async () => {
       response.setHeader('ray', current()!.traceId)
 
-      const context = new Context(authority, request as IncomingMessage, this.properties, url)
+      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')
-          request.socket.removeAllListeners('error')
-        })
+        .finally(() => request.removeAllListeners('error'))
     })
   }
 
-  private success (context: Context, response: http.ServerResponse) {
+  private success (context: Context, response: ServerResponse) {
     return async (message: OutgoingMessage) => {
       let status = message.status
 
@@ -185,10 +220,12 @@ export class Server extends Connector {
     }
   }
 
-  private fail (context: Context, response: http.ServerResponse) {
+  private fail (context: Context, response: ServerResponse) {
     return async (exception: Error) => {
       try {
-        if (!context.request.complete)
+        // Over HTTP/2 the reply is followed by RST_STREAM(NO_ERROR), which tells the client
+        // to stop sending without discarding the response — so the body is never read.
+        if (!context.request.complete && this.properties.protocol === 'h1')
           await adam(context.request)
 
         const status = exception instanceof Exception ? exception.status : 500
@@ -224,7 +261,7 @@ export class Server extends Connector {
         if (!response.writableEnded)
           try {
             response.writeHead(500).end()
-          } catch (e) {
+          } catch {
             // Nothing more we can do
           }
       }
@@ -232,17 +269,36 @@ export class Server extends Connector {
   }
 }
 
+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
+    maxSessionMemory: SESSION_MEMORY,
+    settings: { initialWindowSize: WINDOW }
+  })
+}
+
+/**
+ * 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 {
+  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: http.IncomingMessage): URL | Error {
+function parse (request: IncomingMessage, authority: string): URL | Error {
   try {
-    return new URL(request.url!, `https://${request.headers.host}`)
+    return new URL(request.url, `https://${authority}`)
   } catch (error) {
     return error as Error
   }
 }
 
 // https://github.com/whatwg/fetch/issues/1254
-async function adam (request: http.IncomingMessage): Promise<void> {
+async function adam (request: IncomingMessage): Promise<void> {
   const devnull = fs.createWriteStream(os.devNull)
 
   devnull.on('error', () => undefined)
@@ -251,10 +307,10 @@ async function adam (request: http.IncomingMessage): Promise<void> {
   await once(request, 'end')
 }
 
-function errorAttributes (request: http.IncomingMessage, error: Error & any): RequestErrorAttributes {
+function errorAttributes (request: IncomingMessage, error: Error & any): RequestErrorAttributes {
   const attributes: RequestErrorAttributes = {
-    path: request.url!,
-    method: request.method!,
+    path: request.url,
+    method: request.method,
     name: error.name
   }
 
@@ -269,20 +325,21 @@ function errorAttributes (request: http.IncomingMessage, error: Error & any): Re
 
 export const PORT = 8000
 
-/**
- * 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
 export const DRAIN = 10 // seconds
 
+/** Megabytes a single HTTP/2 session may hold, over Node's default of 10. */
+const SESSION_MEMORY = 128
+
+/** Per-stream flow control window. The default 64 KiB throttles in proportion to RTT. */
+const WINDOW = 1024 * 1024
+
 /**
  * Extracts the remote trace context from the request headers.
  *
  * 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: http.IncomingHttpHeaders): SpanContext | null {
+function trace (headers: IncomingMessage['headers']): SpanContext | null {
   if (typeof headers.traceparent === 'string')
     return decode(headers.traceparent)
 
@@ -300,7 +357,9 @@ const DEFAULTS: Omit<Properties, 'authorities'> = {
   methods: new Set<string>(['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'LOCK', 'UNLOCK']),
   debug: false,
   port: PORT,
-  drain: DRAIN * 1000
+  drain: DRAIN * 1000,
+  protocol: 'h1',
+  probe: PROBE
 }
 
 interface Properties {
@@ -309,6 +368,10 @@ interface Properties {
   debug: boolean
   port: number
   drain: number
+  protocol: Protocol
+
+  /** Port of the readiness probe, which is HTTP/1.1 whatever the gateway serves. */
+  probe: number
 }
 
 export type Options = { authorities: Properties['authorities'] } & {
@@ -324,17 +387,3 @@ interface RequestErrorAttributes {
   code?: string
   stack?: string
 }
-
-/**
- * I'm too fucking dumb to figure out how to handle this in a better way.
- * It can be reproduced by calling `response.destroy()` on the client side while reading
- * an empty stream.
- */
-process.on('uncaughtException', (err: unknown) => {
-  const code = (err as { code?: string }).code
-
-  if (code === 'ECONNRESET' || code === 'EPIPE')
-    console.warn('Connection reset by peer', code)
-  else
-    throw err
-})

package/source/HTTP/Timing.ts

@@ -1,5 +1,5 @@
 import { performance } from 'node:perf_hooks'
-import type { ServerResponse } from 'node:http'
+import type { ServerResponse } from './types.js'
 
 export class Timing {
   private readonly start = performance.now()

package/source/HTTP/formats/index.ts

@@ -1,7 +1,7 @@
-import * as json from './json'
-import * as yaml from './yaml'
-import * as msgpack from './msgpack'
-import * as text from './text'
+import * as json from './json.js'
+import * as yaml from './yaml.js'
+import * as msgpack from './msgpack.js'
+import * as text from './text.js'
 
 export const formats: Record<string, Format> = {
   [json.type]: json,

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

@@ -1,4 +1,7 @@
-import { encode } from './yaml'
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { encode } from './yaml.js'
 
 it('encodes error values as their public properties', () => {
   const value = new (class InvalidUsernameError extends Error {
@@ -6,12 +9,11 @@ it('encodes error values as their public properties', () => {
     public override readonly message = 'Username is not meeting the requirements'
   })()
 
-  expect(encode(value).toString())
-    .toBe('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', () => {
   const secret = { unwrap: () => 's3cret', toJSON: () => '<REDACTED>' }
 
-  expect(encode({ a: 1, b: secret }).toString()).toBe('a: 1\nb: <REDACTED>\n')
+  assert.strictEqual(encode({ a: 1, b: secret }).toString(), 'a: 1\nb: <REDACTED>\n')
 })

package/source/HTTP/formats/yaml.ts

@@ -1,4 +1,4 @@
-import * as yaml from 'js-yaml'
+import { yaml } from '@toa.io/generic'
 
 export const type = 'application/yaml'
 export const multipart = 'multipart/yaml'

package/source/HTTP/index.ts

@@ -1,4 +1,6 @@
-export * from './Server'
-export * from './messages'
-export * from './exceptions'
-export * from './Context'
+export * from './Server.js'
+export * from './messages.js'
+export * from './exceptions.js'
+export * from './Context.js'
+export * from './types.js'
+export * from './Probe.js'

package/source/HTTP/messages.test.ts

@@ -1,17 +1,19 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
 import { PassThrough, Readable } from 'node:stream'
 import * as streamConsumers from 'node:stream/consumers'
-import { once } from 'node:events'
 import { generate } from 'randomstring'
 import * as msgpack from 'msgpackr'
-import { multipart, read, type OutgoingMessage } from './messages'
-import { BadRequest, UnsupportedMediaType } from './exceptions'
-import { formats } from './formats'
-import { Timing } from './Timing'
+import { multipart, read, type OutgoingMessage } from './messages.js'
+import { BadRequest, UnsupportedMediaType } from './exceptions.js'
+import { formats } from './formats/index.js'
+import { Timing } from './Timing.js'
 import type * as http from 'node:http'
-import type { Context } from './Context'
+import type { Context } from './Context.js'
 
 beforeEach(() => {
-  jest.clearAllMocks()
+  resetCalls()
 })
 
 describe('read', () => {
@@ -23,7 +25,7 @@ describe('read', () => {
     const context = createContext(path, headers, json)
     const output = await read(context)
 
-    expect(output).toStrictEqual(input)
+    assert.deepStrictEqual(output, input)
   })
 
   it('should parse application/yaml', async () => {
@@ -33,7 +35,7 @@ describe('read', () => {
     const request = createContext(path, headers, yaml)
     const value = await read(request)
 
-    expect(value).toStrictEqual({ foo: 1 })
+    assert.deepStrictEqual(value, { foo: 1 })
   })
 
   it('should parse application/mskpack', async () => {
@@ -44,7 +46,7 @@ describe('read', () => {
     const request = createContext(path, headers, msg)
     const output = await read(request)
 
-    expect(output).toStrictEqual(input)
+    assert.deepStrictEqual(output, input)
   })
 
   it('should parse text/plain', async () => {
@@ -54,7 +56,7 @@ describe('read', () => {
     const request = createContext(path, headers, input)
     const output = await read(request)
 
-    expect(output).toStrictEqual(input)
+    assert.deepStrictEqual(output, input)
   })
 
   it('should parse application/json with charset parameter', async () => {
@@ -65,7 +67,7 @@ describe('read', () => {
     const context = createContext(path, headers, json)
     const output = await read(context)
 
-    expect(output).toStrictEqual(input)
+    assert.deepStrictEqual(output, input)
   })
 
   it('should throw on unsupported request media type', async () => {
@@ -73,7 +75,7 @@ describe('read', () => {
     const headers = { 'content-type': 'wtf/' + generate() }
     const request = createContext(path, headers)
 
-    await expect(read(request)).rejects.toThrow(UnsupportedMediaType)
+    await assert.rejects(read(request), UnsupportedMediaType)
   })
 
   it('should throw on malformed content', async () => {
@@ -82,7 +84,7 @@ describe('read', () => {
     const headers = { 'content-type': 'application/json' }
     const request = createContext(path, headers, text)
 
-    await expect(read(request)).rejects.toThrow(BadRequest)
+    await assert.rejects(read(request), BadRequest)
   })
 
   it('should output correct mulitpart format', async () => {
@@ -99,13 +101,11 @@ describe('read', () => {
     const context = { encoder: formats['text/plain'] } as unknown as Context
     const message = { body: Readable.from(['Hello', 'New', 'World']) } as unknown as OutgoingMessage
 
-    multipart(message, context, response as unknown as http.ServerResponse)
-
-    await once(message.body, 'end')
+    const framed = multipart(message, context, response as unknown as http.ServerResponse)
 
-    const result = await streamConsumers.text(response)
+    const result = await streamConsumers.text(framed)
 
-    expect(result).toBe([
+    assert.strictEqual(result, [
       '--cut',
       '',
       'ACK',
@@ -126,7 +126,7 @@ describe('read', () => {
 })
 
 export function createContext (url: string, headers: Record<string, string> = {}, content: string | Buffer = ''):
-jest.MockedObject<Context> {
+Context {
   const data = Buffer.isBuffer(content) ? content : Buffer.from(content)
   const stream = Readable.from(data)
   let consumed = false
@@ -148,5 +148,15 @@ jest.MockedObject<Context> {
     }
   }
 
-  return mock as unknown as jest.MockedObject<Context>
+  return mock as unknown as Context
+}
+
+function resetCalls (target = [], seen = new Set()) {
+  if (target === null || typeof target !== 'object' || seen.has(target)) return
+
+  seen.add(target)
+
+  for (const value of Object.values(target))
+    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
+    else resetCalls(value, seen)
 }