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

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 { Context } from './Context'
+import { PROBE, Probe } from './Probe'
+import type { IncomingMessage, Protocol, ServerResponse } from './types'
 
 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
@@ -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'
 
 export class Timing {
   private readonly start = performance.now()

package/source/HTTP/index.ts

@@ -2,3 +2,5 @@ export * from './Server'
 export * from './messages'
 export * from './exceptions'
 export * from './Context'
+export * from './types'
+export * from './Probe'

package/source/HTTP/messages.test.ts

@@ -1,6 +1,5 @@
 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'
@@ -99,11 +98,9 @@ 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)
+    const framed = multipart(message, context, response as unknown as http.ServerResponse)
 
-    await once(message.body, 'end')
-
-    const result = await streamConsumers.text(response)
+    const result = await streamConsumers.text(framed)
 
     expect(result).toBe([
       '--cut',

package/source/HTTP/messages.ts

@@ -1,11 +1,12 @@
 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 { formats } from './formats'
+import { type Format, formats } from './formats'
 import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions'
 import type { Context } from './Context'
-import type * as http from 'node:http'
+import type { ServerResponse } from './types'
 
 const server = `Exposition/${require('../../package.json').version}` +
   ((process.env.TOA_CONTEXT === undefined ? '' : ` ${process.env.TOA_CONTEXT}`) +
@@ -13,7 +14,7 @@ const server = `Exposition/${require('../../package.json').version}` +
 
 const pending = new Map<string, PendingStream>()
 
-export async function write (context: Context, response: http.ServerResponse, message: OutgoingMessage): Promise<void> {
+export async function write (context: Context, response: ServerResponse, message: OutgoingMessage): Promise<void> {
   for (const transform of context.pipelines.response)
     await transform(message)
 
@@ -65,7 +66,7 @@ export async function read (context: Context): Promise<any> {
   }
 }
 
-function send (message: OutgoingMessage, context: Context, response: http.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
@@ -85,11 +86,10 @@ function send (message: OutgoingMessage, context: Context, response: http.Server
   if (message.etag === true && conditional(context, response, buf))
     return
 
-  response
-    .setHeader('content-type', context.encoder.type)
-    .setHeader('content-length', buf.length.toString())
-    .appendHeader('vary', 'accept')
-    .end(buf)
+  response.setHeader('content-type', context.encoder.type)
+  response.setHeader('content-length', buf.length.toString())
+  response.appendHeader('vary', 'accept')
+  response.end(buf)
 }
 
 /**
@@ -98,7 +98,7 @@ function send (message: OutgoingMessage, context: Context, response: http.Server
  * than from a serialization of its own, so it identifies the representation — which is
  * what `vary` says.
  */
-function conditional (context: Context, response: http.ServerResponse, buf: Buffer): boolean {
+function conditional (context: Context, response: ServerResponse, buf: Buffer): boolean {
   const etag = `"${createHash('sha256').update(buf).digest('hex')}"`
 
   response.setHeader('etag', etag)
@@ -106,9 +106,8 @@ function conditional (context: Context, response: http.ServerResponse, buf: Buff
   if (context.request.headers['if-none-match'] !== etag)
     return false
 
-  response
-    .setHeader('content-length', '0')
-    .appendHeader('vary', 'accept')
+  response.setHeader('content-length', '0')
+  response.appendHeader('vary', 'accept')
 
   response.statusCode = 304
   response.end()
@@ -116,24 +115,28 @@ function conditional (context: Context, response: http.ServerResponse, buf: Buff
   return true
 }
 
-function stream (message: OutgoingMessage, context: Context, response: http.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)
 
-  if (encoded)
-    message.body.pipe(response)
-  else
-    multipart(message, context, response)
-
-  message.body.on('error', (exception: Error) => {
-    console.warn('Message stream error', { path: context.url.pathname, exception })
-    response.end()
-  })
+  // not awaited: a reply that streams is written long after the request is answered, and a
+  // realtime subscription outlives the span the reply was produced in
+  //
+  // `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)
 }
 
-export function multipart (message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
+/**
+ * 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()
 
@@ -141,27 +144,20 @@ export function multipart (message: OutgoingMessage, context: Context, response:
 
   response.setHeader('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`)
 
-  response.write(Buffer.concat([
-    CUT,
-    CRLF,
-    encoder.encode('ACK'),
-    CRLF,
-    CUT
-  ]))
+  return Readable.from(frames(message.body as Readable, encoder))
+}
+
+async function * frames (body: Readable, encoder: Format): AsyncGenerator<Buffer> {
+  yield Buffer.concat([CUT, CRLF, encoder.encode('ACK'), CRLF, CUT])
 
-  message.body
-    .map((part: unknown) => Buffer.concat([
+  for await (const part of body)
+    yield Buffer.concat([
       CRLF /* indicates no boundary headers */,
       encoder.encode(part),
       CRLF,
-      CUT]))
-    .on('end', () => response.end(Buffer.concat([
-      CRLF,
-      encoder.encode('FIN'),
-      CRLF,
-      FINALCUT
-    ])))
-    .pipe(response)
+      CUT])
+
+  yield Buffer.concat([CRLF, encoder.encode('FIN'), CRLF, FINALCUT])
 }
 
 const BOUNDARY = 'cut'
@@ -173,7 +169,7 @@ const PENDING_DEBUG_INTERVAL = 30000
 
 let pendingInterval: NodeJS.Timeout | null = null
 
-function debugStream (context: Context, response: http.ServerResponse): void {
+function debugStream (context: Context, response: ServerResponse): void {
   const ctx = { method: context.request.method, path: context.url.pathname }
 
   console.debug('Stream opened', ctx)

package/source/HTTP/types.ts

@@ -0,0 +1,39 @@
+import type { Readable, Writable } from 'node:stream'
+import type { OutgoingHttpHeaders } from 'node:http'
+import type { IncomingHttpHeaders } from 'node:http2'
+
+/**
+ * What Exposition requires of a request. Both `http.IncomingMessage` and
+ * `http2.Http2ServerRequest` satisfy it, so the pipeline is written once.
+ */
+export interface IncomingMessage extends Readable {
+  url: string
+  method: string
+  complete: boolean
+  headers: IncomingHeaders
+  socket: { remoteAddress?: string | undefined }
+}
+
+/**
+ * What Exposition requires of a response.
+ *
+ * `setHeader` and `appendHeader` return `void` because `Http2ServerResponse` returns
+ * nothing from them, so neither can be chained.
+ */
+export interface ServerResponse extends Writable {
+  statusCode: number
+  writableEnded: boolean
+  setHeader: (name: string, value: number | string | string[]) => void
+  appendHeader: (name: string, value: string | string[]) => void
+  hasHeader: (name: string) => boolean
+  writeHead: (status: number, headers?: OutgoingHttpHeaders) => ServerResponse
+}
+
+/**
+ * HTTP/2's header map: HTTP/1.1's, plus the pseudo-headers. `:authority` is typed here
+ * so the authority can be read without narrowing at every call site.
+ */
+export type IncomingHeaders = IncomingHttpHeaders
+
+/** `h2c` is cleartext HTTP/2: there is no in-process TLS to negotiate ALPN with. */
+export type Protocol = 'h1' | 'h2c'

package/source/deployment.ts

@@ -5,7 +5,7 @@ import * as schemas from './schemas'
 import { shortcuts } from './Directive'
 import { components } from './Composition'
 import { parse } from './RTD/syntax'
-import { DELAY, PORT } from './HTTP'
+import { DELAY, PORT, PROBE } from './HTTP'
 
 export function deployment (_: unknown, annotation?: Annotation): Dependency {
   assert.ok(annotation !== undefined, 'Exposition context annotation is required')
@@ -24,7 +24,7 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
     ingress: { path: '/', hosts: [] },
     probe: {
       path: '/.ready',
-      port: PORT,
+      port: PROBE,
       delay: DELAY
     }
   }
@@ -49,17 +49,25 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   if (annotation.annotations !== undefined)
     service.ingress!.annotations = annotation.annotations
 
+  if (annotation.service?.annotations !== undefined)
+    service.annotations = annotation.service.annotations
+
   const properties: Properties = { authorities }
 
   if (debug === true)
     properties.debug = true
 
+  if (annotation.protocol !== undefined)
+    properties.protocol = annotation.protocol
+
   service.variables!.push({
     name: 'TOA_EXPOSITION_PROPERTIES',
     value: JSON.stringify(properties)
   })
 
-  // Nested identity composition shares this process; gateway already exposes /.ready.
+  // The identity composition nested in this process connects before route discovery settles,
+  // so telemetry's probe — which tracks that composition — would report ready too early.
+  // The gateway answers for itself, on the same port telemetry would have used.
   service.variables!.push({
     name: 'TOA_TELEMETRY_READY',
     value: JSON.stringify(false)
@@ -68,4 +76,4 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   return { services: [service] }
 }
 
-type Properties = Pick<Annotation, 'authorities' | 'debug'>
+type Properties = Pick<Annotation, 'authorities' | 'debug' | 'protocol'>

package/source/directives/octets/Get.ts

@@ -64,9 +64,9 @@ export class Get extends Directive {
     if (entry.range !== undefined)
       headers.set('content-range', entry.range)
 
-    if (entry.size === null)
-      headers.set('transfer-encoding', 'chunked')
-    else
+    // an absent content-length is what says the length is unknown; naming the encoding
+    // is redundant over HTTP/1.1 and forbidden over HTTP/2
+    if (entry.size !== null)
       headers.set('content-length', entry.size.toString())
 
     return {

package/transpiled/Annotation.d.ts

@@ -1,9 +1,19 @@
 import type { Resources } from '@toa.io/operations';
+import type { Protocol } from './HTTP';
 export interface Annotation {
     authorities: Record<string, string>;
+    /**
+     * `h2c` requires an ingress controller that proxies cleartext HTTP/2 upstream.
+     * See `documentation/protocol.md`.
+     */
+    protocol?: Protocol;
     class?: string;
     resources?: Resources;
     annotations?: Record<string, string>;
+    /** The Service, as opposed to the Ingress that `annotations` above describes. */
+    service?: {
+        annotations?: Record<string, string>;
+    };
     debug?: boolean;
     '/'?: object;
 }