@toa.io/extensions.exposition 1.0.0-alpha.27 → 1.0.0-alpha.271

package/source/HTTP/Server.ts

@@ -1,19 +1,20 @@
+import assert from 'node:assert'
 import fs from 'node:fs'
 import os from 'node:os'
 import * as http from 'node:http'
 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 } from './Context'
-import type { IncomingMessage } from './Context'
+import { Context, type IncomingMessage } from './Context'
 
 export class Server extends Connector {
   private readonly server: http.Server = http.createServer()
   private readonly properties: Properties
   private readonly authorities: Record<string, string>
-  private process?: Processing
+  private process?: Processor
   private ready: boolean = false
   private startedAt: number = 0
 
@@ -24,15 +25,22 @@ export class Server extends Connector {
     this.authorities = Object.fromEntries(Object.entries(properties.authorities).map(([key, value]) => [value, key]))
 
     this.server.on('request', (req, res) => this.listener(req, res))
+
+    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()
+    })
   }
 
   public static create (options: Options): Server {
-    const properties: Properties = Object.assign({}, DEFAULTS, options)
+    const properties: Properties = { ...DEFAULTS, ...options }
 
     return new Server(properties)
   }
 
-  public attach (process: Processing): void {
+  public attach (process: Processor): void {
     this.process = process
   }
 
@@ -44,25 +52,56 @@ export class Server extends Connector {
 
     console.info('HTTP Server is listening')
 
-    await setTimeout(this.properties.delay)
-
     this.ready = true
 
     console.info('Ready')
+    process.send?.('ready')
   }
 
   protected override async close (): Promise<void> {
-    this.server.close()
     this.ready = false
 
-    console.info('HTTP Server stopped accepting new connections')
+    this.server.close()
+    this.server.closeIdleConnections()
+
+    console.info('Stopped accepting new connections')
 
-    await once(this.server, 'close')
+    // keep-alive clients hold connections open indefinitely, so the drain is bounded
+    await Promise.race([
+      once(this.server, 'close'),
+      setTimeout(this.properties.drain, undefined, { ref: false })
+    ])
 
-    console.info('HTTP Server has been stopped')
+    this.server.closeAllConnections()
+
+    console.info('Stopped')
   }
 
   private listener (request: http.IncomingMessage, response: http.ServerResponse): void {
+    request.once('error', (error) => {
+      console.warn('Request error', errorAttributes(request, error))
+
+      if (!response.writableEnded)
+        response.destroy()
+    })
+
+    request.socket.once('error', (error) => {
+      console.warn('Socket error', errorAttributes(request, error))
+
+      if (!response.writableEnded)
+        response.destroy()
+    })
+
+    const url = parse(request)
+
+    if (url instanceof Error) {
+      console.warn('Invalid request', errorAttributes(request, url))
+
+      response.writeHead(400).end()
+
+      return
+    }
+
     if (request.method === undefined || !this.properties.methods.has(request.method)) {
       response.writeHead(501).end()
 
@@ -81,22 +120,53 @@ export class Server extends Connector {
       return
     }
 
-    if (request.headers.host === undefined || !(request.headers.host in this.authorities)) {
-      response.writeHead(404).end('Unknown authority')
+    assert(this.process !== undefined, 'Request processor is not attached')
 
-      return
-    }
+    const host = request.headers.host!
+    const authority = this.authorities[host] ?? host
+
+    // 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))
+
+    processing.catch((error) => {
+      console.error('Request processing failed', error)
 
-    const authority = this.authorities[request.headers.host]
-    const context = new Context(authority, request as IncomingMessage, this.properties)
+      if (!response.writableEnded)
+        response.writeHead(500).end()
+    })
+  }
 
-    this.process!(context)
-      .then(this.success(context, response))
-      .catch(this.fail(context, response))
+  // eslint-disable-next-line max-params
+  private async serve (request: http.IncomingMessage,
+    response: http.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 as IncomingMessage, 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')
+        })
+    })
   }
 
   private success (context: Context, response: http.ServerResponse) {
-    return (message: OutgoingMessage) => {
+    return async (message: OutgoingMessage) => {
       let status = message.status
 
       if (status === undefined)
@@ -104,68 +174,167 @@ export class Server extends Connector {
           status = 404
         else if (context.request.method === 'POST')
           status = 201
-        else if (message.body === undefined)
+        else if (message.body === undefined && context.request.method !== 'HEAD')
           status = 204
         else
           status = 200
 
-      response.statusCode = message.status = status
-      write(context, response, message)
+      message.status = status
+
+      await write(context, response, message)
     }
   }
 
   private fail (context: Context, response: http.ServerResponse) {
     return async (exception: Error) => {
-      if (!context.request.complete)
-        await adam(context.request)
-
-      response.statusCode = exception instanceof Exception ? exception.status : 500
-
-      const message: OutgoingMessage = { status: response.statusCode }
-      const verbose = exception instanceof ClientError || this.properties.debug
-
-      if (verbose)
-        message.body =
-          exception instanceof Exception
-            ? exception.body
-            : exception.stack ?? exception.message
-
-      write(context, response, message)
+      try {
+        if (!context.request.complete)
+          await adam(context.request)
+
+        const status = exception instanceof Exception ? exception.status : 500
+        const span = current()
+
+        // https://opentelemetry.io/docs/specs/semconv/http/http-spans/#status
+        if (status >= 500 && span !== undefined)
+          span.status = 'error'
+
+        if (!response.writableEnded) {
+          response.statusCode = status
+
+          const message: OutgoingMessage = { status: response.statusCode }
+
+          // 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
+          else if (exception instanceof ClientError || this.properties.debug)
+            message.body =
+              exception instanceof Exception
+                ? exception.body
+                : (this.properties.debug && exception.stack) ?? exception.message
+
+          await write(context, response, message)
+        }
+      } catch (final) {
+        console.error('Error in error handler', final)
+
+        if (!response.writableEnded)
+          try {
+            response.writeHead(500).end()
+          } catch (e) {
+            // Nothing more we can do
+          }
+      }
     }
   }
 }
 
+/** Parsing the URL is how a request is validated, so the `Context` is handed the result. */
+function parse (request: http.IncomingMessage): URL | Error {
+  try {
+    return new URL(request.url!, `https://${request.headers.host}`)
+  } catch (error) {
+    return error as Error
+  }
+}
+
 // https://github.com/whatwg/fetch/issues/1254
-async function adam (request: http.IncomingMessage): Promise<any> {
+async function adam (request: http.IncomingMessage): Promise<void> {
   const devnull = fs.createWriteStream(os.devNull)
 
-  request.pipe(devnull)
+  devnull.on('error', () => undefined)
+  request.pipe(devnull).on('error', () => undefined)
+
+  await once(request, 'end')
+}
+
+function errorAttributes (request: http.IncomingMessage, error: Error & any): RequestErrorAttributes {
+  const attributes: RequestErrorAttributes = {
+    path: request.url!,
+    method: request.method!,
+    name: error.name
+  }
 
-  return once(request, 'end')
+  if (typeof error.code === 'string')
+    attributes.code = error.code
+
+  if (typeof error.stack === 'string')
+    attributes.stack = error.stack
+
+  return attributes
 }
 
 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
+
+/**
+ * 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 {
+  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)
+    return { traceId: headers.ray.toLowerCase(), sampled: decide() }
+
+  return null
+}
+
+const RAY = /^[\da-f]{32}$/i
+const ZERO_RAY = '0'.repeat(32)
 
 const DEFAULTS: Omit<Properties, 'authorities'> = {
-  methods: new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']),
+  methods: new Set<string>(['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'LOCK', 'UNLOCK']),
   debug: false,
-  trace: false,
   port: PORT,
-  delay: DELAY * 1000
+  drain: DRAIN * 1000
 }
 
 interface Properties {
   authorities: Record<string, string>
   methods: Set<string>
   debug: boolean
-  trace: boolean
   port: number
-  delay: number
+  drain: number
 }
 
 export type Options = { authorities: Properties['authorities'] } & {
   [K in Exclude<keyof Properties, 'authorities'>]?: Properties[K]
 }
 
-export type Processing = (input: Context) => Promise<OutgoingMessage>
+export type Processor = (input: Context) => Promise<OutgoingMessage>
+
+interface RequestErrorAttributes {
+  path: string
+  method: string
+  name: string
+  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

@@ -2,18 +2,10 @@ import { performance } from 'node:perf_hooks'
 import type { ServerResponse } from 'node:http'
 
 export class Timing {
-  private readonly skip: boolean
   private readonly start = performance.now()
   private readonly breakpoints: Breakpoint[] = []
 
-  public constructor (enabled: boolean) {
-    this.skip = !enabled
-  }
-
-  public async capture<T> (id: string, promise: Promise<T>): Promise<T> {
-    if (this.skip)
-      return promise
-
+  public async capture<T>(id: string, promise: Promise<T>): Promise<T> {
     const start = performance.now()
     const result = promise instanceof Promise ? await promise : promise
 
@@ -23,9 +15,6 @@ export class Timing {
   }
 
   public append (response: ServerResponse): void {
-    if (this.skip)
-      return
-
     this.breakpoints.push({ id: 'total', duration: performance.now() - this.start })
 
     for (const breakpoint of this.breakpoints)

package/source/HTTP/exceptions.ts

@@ -2,10 +2,14 @@ export class Exception extends Error {
   public readonly status: number
   public readonly body?: any
 
-  protected constructor (status: number, body?: any) {
+  /** 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) {
     super()
     this.status = status
     this.body = body
+    this.headers = headers
   }
 }
 
@@ -36,27 +40,33 @@ export class NotFound extends ClientError {
   }
 }
 
-export class Conflict extends ClientError {
-  public constructor (body?: any) {
-    super(409, body)
+export class MethodNotAllowed extends ClientError {
+  public constructor () {
+    super(405)
   }
 }
 
-export class UnprocessableEntity extends ClientError {
+export class NotAcceptable extends ClientError {
+  public constructor () {
+    super(406)
+  }
+}
+
+export class Conflict extends ClientError {
   public constructor (body?: any) {
-    super(422, body)
+    super(409, body)
   }
 }
 
-export class MethodNotAllowed extends ClientError {
+export class PreconditionFailed extends ClientError {
   public constructor () {
-    super(405)
+    super(412)
   }
 }
 
-export class NotAcceptable extends ClientError {
-  public constructor () {
-    super(406)
+export class RequestEntityTooLarge extends ClientError {
+  public constructor (body?: any) {
+    super(413, body)
   }
 }
 
@@ -66,8 +76,22 @@ export class UnsupportedMediaType extends ClientError {
   }
 }
 
-export class PreconditionFailed extends ClientError {
-  public constructor () {
-    super(412)
+export class UnprocessableEntity extends ClientError {
+  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) }))
+  }
+}
+
+export class ServiceUnavailable extends Exception {
+  public constructor (body?: any) {
+    super(503, body)
   }
 }

package/source/HTTP/formats/index.ts

@@ -1,14 +1,13 @@
-import { type Buffer } from 'node:buffer'
 import * as json from './json'
 import * as yaml from './yaml'
 import * as msgpack from './msgpack'
 import * as text from './text'
 
 export const formats: Record<string, Format> = {
-  [msgpack.type]: msgpack,
-  [yaml.type]: yaml,
   [json.type]: json,
-  [text.type]: text
+  [yaml.type]: yaml,
+  [text.type]: text,
+  [msgpack.type]: msgpack
 }
 
 export const types = Object.keys(formats)
@@ -18,5 +17,5 @@ export interface Format {
   readonly multipart: string
 
   encode: (value: any) => Buffer
-  decode: (buffer: Buffer) => any
+  decode: (buffer: Buffer, charset?: string) => any
 }

package/source/HTTP/formats/json.ts

@@ -1,10 +1,8 @@
-import { Buffer } from 'node:buffer'
-
 export const type = 'application/json'
 export const multipart = 'multipart/json'
 
-export function decode (buffer: Buffer): any {
-  const text = buffer.toString()
+export function decode (buffer: Buffer, charset = 'utf-8'): any {
+  const text = buffer.toString(charset as BufferEncoding)
 
   return JSON.parse(text)
 }

package/source/HTTP/formats/msgpack.ts

@@ -1,4 +1,3 @@
-import { type Buffer } from 'node:buffer'
 import { pack, unpack } from 'msgpackr'
 
 export function decode (buffer: Buffer): any {

package/source/HTTP/formats/text.ts

@@ -1,10 +1,8 @@
-import { Buffer } from 'node:buffer'
-
 export const type = 'text/plain'
 export const multipart = 'multipart/text'
 
-export function decode (buffer: Buffer): any {
-  return buffer.toString()
+export function decode (buffer: Buffer, charset = 'utf-8'): any {
+  return buffer.toString(charset as BufferEncoding)
 }
 
 export function encode (value: { toString: () => string }): Buffer {

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

@@ -0,0 +1,9 @@
+import { Err } from 'error-value'
+import { encode } from './yaml'
+
+it('encodes error values as their public properties', () => {
+  const value = new Err('INVALID_USERNAME', 'Username is not meeting the requirements')
+
+  expect(encode(value).toString())
+    .toBe('code: INVALID_USERNAME\nmessage: Username is not meeting the requirements\n')
+})

package/source/HTTP/formats/yaml.ts

@@ -1,17 +1,17 @@
-import { Buffer } from 'node:buffer'
 import * as yaml from 'js-yaml'
 
 export const type = 'application/yaml'
 export const multipart = 'multipart/yaml'
 
-export function decode (buffer: Buffer): any {
-  const text = buffer.toString()
+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 text = yaml.dump(value, { lineWidth: -1, noRefs: true })
+  const serializable = value instanceof Error ? Object.assign({}, value) : value
+  const text = yaml.dump(serializable, { lineWidth: -1, noRefs: true })
 
   return Buffer.from(text)
 }

package/source/HTTP/messages.test.ts

@@ -1,9 +1,13 @@
-import { Readable } from 'node:stream'
+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 { read } from './messages'
+import { multipart, read, type OutgoingMessage } from './messages'
 import { BadRequest, UnsupportedMediaType } from './exceptions'
+import { formats } from './formats'
 import { Timing } from './Timing'
+import type * as http from 'node:http'
 import type { Context } from './Context'
 
 beforeEach(() => {
@@ -53,6 +57,17 @@ describe('read', () => {
     expect(output).toStrictEqual(input)
   })
 
+  it('should parse application/json with charset parameter', async () => {
+    const path = generate()
+    const headers = { 'content-type': 'application/json; charset=utf-8' }
+    const input = { [generate()]: generate() }
+    const json = JSON.stringify(input)
+    const context = createContext(path, headers, json)
+    const output = await read(context)
+
+    expect(output).toStrictEqual(input)
+  })
+
   it('should throw on unsupported request media type', async () => {
     const path = generate()
     const headers = { 'content-type': 'wtf/' + generate() }
@@ -69,20 +84,68 @@ describe('read', () => {
 
     await expect(read(request)).rejects.toThrow(BadRequest)
   })
+
+  it('should output correct mulitpart format', async () => {
+    const response = new class extends PassThrough {
+      public readonly headers = new Headers()
+
+      public setHeader (key: string, value: string): this {
+        this.headers.set(key, value)
+
+        return this
+      }
+    }()
+
+    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 result = await streamConsumers.text(response)
+
+    expect(result).toBe([
+      '--cut',
+      '',
+      'ACK',
+      '--cut',
+      '',
+      'Hello',
+      '--cut',
+      '',
+      'New',
+      '--cut',
+      '',
+      'World',
+      '--cut',
+      '',
+      'FIN',
+      '--cut--'].join('\r\n'))
+  })
 })
 
-export function createContext
-(url: string, headers: Record<string, string> = {}, content: string | Buffer = ''):
+export function createContext (url: string, headers: Record<string, string> = {}, content: string | Buffer = ''):
 jest.MockedObject<Context> {
-  const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content)
-  const stream = Readable.from(buffer)
+  const data = Buffer.isBuffer(content) ? content : Buffer.from(content)
+  const stream = Readable.from(data)
+  let consumed = false
 
   const mock: Partial<Context> = {
     request: Object.assign(stream, {
       url,
       headers
     }) as unknown as Context['request'],
-    timing: new Timing(false)
+    url: new URL(url, 'https://host.local'),
+    timing: new Timing(),
+    buffer: async () => {
+      if (consumed)
+        throw new Error('Request body already consumed')
+
+      consumed = true
+
+      return data
+    }
   }
 
   return mock as unknown as jest.MockedObject<Context>