@toa.io/extensions.exposition 1.0.0-alpha.0 → 1.0.0-alpha.100

package/source/Gateway.ts

@@ -1,81 +1,114 @@
+import assert from 'node:assert'
+import { console } from 'openspan'
 import { type bindings, Connector } from '@toa.io/core'
-import { type Maybe } from '@toa.io/types'
 import * as http from './HTTP'
 import { rethrow } from './exceptions'
-import { type Method, type Parameter, type Tree } from './RTD'
-import { type Label } from './discovery'
-import { type Branch } from './Branch'
-import { type Endpoint } from './Endpoint'
-import { type Directives } from './Directive'
+import type { Interception } from './Interception'
+import type { Node, Method, Parameter, Tree, Match } from './RTD'
+import type { Label } from './discovery'
+import type { Branch } from './Branch'
 
 export class Gateway extends Connector {
   private readonly broadcast: Broadcast
-  private readonly tree: Tree<Endpoint, Directives>
+  private readonly tree: Tree
+  private readonly interceptor: Interception
+  private readonly merged = new Set<string>()
 
-  public constructor (broadcast: Broadcast, server: http.Server, tree: Tree<Endpoint, Directives>) {
+  public constructor (broadcast: Broadcast, tree: Tree, interception: Interception) {
     super()
 
     this.broadcast = broadcast
     this.tree = tree
+    this.interceptor = interception
 
     this.depends(broadcast)
-    this.depends(server)
+  }
+
+  public async process (context: http.Context): Promise<http.OutgoingMessage> {
+    const interception = await context.timing.capture('intercept',
+      this.interceptor.intercept(context))
+
+    if (interception !== null)
+      return interception
+
+    const { node, parameters } = this.match(context)
+
+    if (context.request.method === 'OPTIONS')
+      return await this.explain(node, parameters)
+
+    if (!(context.request.method in node.methods))
+      throw new http.MethodNotAllowed()
 
-    server.attach(this.process.bind(this))
+    const method = node.methods[context.request.method]
+
+    const interruption = await context.timing.capture('preflight',
+      method.directives.preflight(context, parameters)).catch(rethrow)
+
+    const response = interruption ??
+      await context.timing.capture('call', this.call(method, context, parameters))
+
+    await context.timing.capture('settle',
+      method.directives.settle(context, response)).catch(rethrow)
+
+    return response
   }
 
   protected override async open (): Promise<void> {
     await this.discover()
 
-    console.info('Gateway has started and is awaiting resource branches.')
+    console.info('Gateway started')
   }
 
   protected override dispose (): void {
-    console.info('Gateway is closed.')
+    console.info('Gateway is closed')
   }
 
-  private async process (request: http.IncomingMessage): Promise<http.OutgoingMessage> {
-    const match = this.tree.match(request.path)
+  private match (context: http.Context): Match {
+    const match = this.tree.match(context.url.pathname)
 
     if (match === null)
-      throw new http.NotFound()
+      throw new http.NotFound('Route not found')
 
-    const { node, parameters } = match
+    if (match.node.forward === null)
+      return match
 
-    if (!(request.method in node.methods))
-      throw new http.MethodNotAllowed()
+    const destination = match.node.forward.replace(/\/:([^/]+)/g,
+      (_, name) => {
+        const value = match.parameters.find((parameter) => parameter.name === name)?.value
 
-    const method = node.methods[request.method]
-    const interruption = await method.directives.preflight(request, parameters)
-    const response = interruption ?? await this.call(method, request, parameters)
+        assert.ok(value !== undefined, `Forwarded parameter '${name}' not found`)
 
-    await method.directives.settle(request, response)
+        return `/${value}`
+      })
 
-    return response
+    const forward = this.tree.match(destination)
+
+    assert.ok(forward !== null, 'Forwarded route not found')
+
+    return forward
   }
 
-  private async call
-  (method: Method<Endpoint, Directives>, request: http.IncomingMessage, parameters: Parameter[]):
-  Promise<http.OutgoingMessage> {
-    if (request.path[request.path.length - 1] !== '/')
-      throw new http.NotFound('Trailing slash is required.')
+  private async call (method: Method, context: http.Context, parameters: Parameter[]): Promise<http.OutgoingMessage> {
+    if (context.url.pathname[context.url.pathname.length - 1] !== '/')
+      throw new http.NotFound('Trailing slash is required')
 
-    if (request.encoder === null)
+    if (context.encoder === null)
       throw new http.NotAcceptable()
 
     if (method.endpoint === null)
       throw new http.MethodNotAllowed()
 
-    const body = await request.parse()
-
-    const reply = await method.endpoint
-      .call(body, request.query, parameters)
-      .catch(rethrow) as Maybe<unknown>
+    return await method.endpoint
+      .call(context, parameters)
+      .catch(rethrow) as http.OutgoingMessage
+  }
 
-    if (reply instanceof Error)
-      throw new http.Conflict(reply)
+  private async explain (node: Node, parameters: Parameter[]): Promise<http.OutgoingMessage> {
+    const body = await node.explain(parameters)
+    const allow = [...Object.keys(node.methods)].join(', ')
+    const headers = new Headers({ allow })
 
-    return { body: reply }
+    return { body, headers }
   }
 
   private async discover (): Promise<void> {
@@ -84,15 +117,34 @@ export class Gateway extends Connector {
   }
 
   private merge (branch: Branch): void {
+    const id = branch.namespace + '.' + branch.component + '@' + branch.version
+
+    if (this.merged.has(id)) {
+      console.debug('Branch already merged, ignoring', {
+        namespace: branch.namespace,
+        component: branch.component,
+        version: branch.version
+      })
+
+      return
+    }
+
+    this.merged.add(id)
+
+    const attributes = {
+      namespace: branch.namespace,
+      component: branch.component,
+      version: branch.version
+    }
+
     try {
       this.tree.merge(branch.node, branch)
 
-      console.info('Resource branch of ' +
-        `'${branch.namespace}.${branch.component}' has been merged.`)
-    } catch (exception) {
-      console.error(exception)
+      console.info('Branch merged', attributes)
+    } catch (exception: unknown) {
+      console.error('Branch merge exception', { exception, ...attributes })
     }
   }
 }
 
-type Broadcast = bindings.Broadcast<Label>
+export type Broadcast = bindings.Broadcast<Label>

package/source/HTTP/Context.ts

@@ -0,0 +1,90 @@
+import Negotiator from 'negotiator'
+import { console } from 'openspan'
+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'
+
+export class Context {
+  public readonly authority: string
+  public readonly request: IncomingMessage
+  public readonly url: URL
+  public readonly subtype: string | null = null
+  public readonly encoder: Format | null = null
+  public readonly timing: Timing
+  public readonly debug: boolean
+
+  public readonly pipelines: Pipelines = {
+    body: [],
+    response: []
+  }
+
+  public constructor (authority: string, request: IncomingMessage, properties: Properties) {
+    this.authority = authority
+    this.request = request
+
+    this.url = new URL(request.url, `https://${request.headers.host}`)
+    this.timing = new Timing(properties.trace)
+    this.debug = properties.debug
+
+    if (this.debug)
+      this.log(request)
+
+    if (this.request.headers.accept !== undefined) {
+      const match = SUBTYPE.exec(this.request.headers.accept)
+
+      if (match !== null) {
+        const {
+          type,
+          subtype,
+          suffix
+        } = match.groups!
+
+        this.request.headers.accept = `${type}/${suffix}`
+        this.subtype = subtype
+      }
+    }
+
+    const negotiator = new Negotiator(this.request)
+    const mediaType = negotiator.mediaType(types)
+
+    if (mediaType !== undefined)
+      this.encoder = formats[mediaType]
+  }
+
+  public async body<T> (): Promise<T> {
+    const value = await read(this)
+
+    return this.pipelines.body.length === 0
+      ? value
+      : this.pipelines.body.reduce((value, transform) => transform(value), value)
+  }
+
+  private log (request: IncomingMessage): void {
+    const headers = { ...request.headers }
+
+    if (headers.authorization !== undefined)
+      // only scheme
+      headers.authorization = headers.authorization.slice(0, headers.authorization.indexOf(' '))
+
+    console.debug('Received request', { method: request.method, url: request.url, headers })
+  }
+}
+
+export interface IncomingMessage extends http.IncomingMessage {
+  url: string
+  method: string
+}
+
+interface Pipelines {
+  body: Array<(input: unknown) => unknown>
+  response: Array<(output: OutgoingMessage) => void | Promise<void>>
+}
+
+interface Properties {
+  debug: boolean
+  trace: boolean
+}
+
+const SUBTYPE = /^(?<type>\w{1,32})\/(vnd\.toa\.(?<subtype>\S{1,32})\+)(?<suffix>\S{1,32})$/

package/source/HTTP/Server.ts

@@ -1,149 +1,172 @@
-import express from 'express'
-import cors from 'cors'
+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 } from 'openspan'
 import { Connector } from '@toa.io/core'
-import { promex } from '@toa.io/generic'
-import Negotiator from 'negotiator'
-import { read, write, type IncomingMessage, type OutgoingMessage } from './messages'
+import { type OutgoingMessage, write } from './messages'
 import { ClientError, Exception } from './exceptions'
-import { formats, types } from './formats'
-import type { Format } from './formats'
-import type * as http from 'node:http'
-import type { Express, Request, Response, NextFunction } from 'express'
+import { Context } from './Context'
+import type { IncomingMessage } from './Context'
 
 export class Server extends Connector {
-  private readonly debug: boolean
-  private readonly app: Express
-  private server?: http.Server
-
-  private constructor (app: Express, debug: boolean) {
+  private readonly server: http.Server = http.createServer()
+  private readonly properties: Properties
+  private readonly authorities: Record<string, string>
+  private process?: Processing
+  private ready: boolean = false
+  private startedAt: number = 0
+
+  private constructor (properties: Properties) {
     super()
 
-    this.app = app
-    this.debug = debug
-  }
+    this.properties = properties
+    this.authorities = Object.fromEntries(Object.entries(properties.authorities).map(([key, value]) => [value, key]))
 
-  public static create (options: Partial<Properties> = {}): Server {
-    const properties: Properties = Object.assign({}, defaults(), options)
+    this.server.on('request', (req, res) => this.listener(req, res))
 
-    const app = express()
+    if (this.properties.debug)
+      this.server.on('connection', (socket) =>
+        console.debug('Connected', { address: socket.remoteAddress }))
+  }
 
-    app.disable('x-powered-by')
-    app.use(cors({ allowedHeaders: ['content-type'] }))
-    app.use(supportedMethods(properties.methods))
+  public static create (options: Options): Server {
+    const properties: Properties = Object.assign({}, DEFAULTS, options)
 
-    return new Server(app, properties.debug)
+    return new Server(properties)
   }
 
   public attach (process: Processing): void {
-    this.app.use((request: any, response: Response): void => {
-      this.extend(request)
-        .then(process)
-        .then(this.success(request, response))
-        .catch(this.fail(request, response))
-    })
+    this.process = process
   }
 
   protected override async open (): Promise<void> {
-    const listening = promex()
+    this.startedAt = Date.now()
+    this.server.listen(this.properties.port)
+
+    await once(this.server, 'listening')
+
+    console.info('HTTP Server is listening')
 
-    this.server = this.app.listen(8000, listening.callback)
+    await setTimeout(this.properties.delay)
 
-    await listening
+    this.ready = true
 
-    console.info('HTTP Server is listening.')
+    console.info('Ready')
   }
 
   protected override async close (): Promise<void> {
-    const stopped = promex()
+    this.server.close()
+    this.ready = false
 
-    this.server?.close(stopped.callback)
+    console.info('Stopped accepting new connections')
 
-    await stopped
-  }
+    await once(this.server, 'close')
 
-  protected override dispose (): void {
-    console.info('HTTP Server has been stopped.')
+    console.info('Stopped')
   }
 
-  private async extend (request: IncomingMessage): Promise<IncomingMessage> {
-    const message = request as unknown as IncomingMessage
+  private listener (request: http.IncomingMessage, response: http.ServerResponse): void {
+    if (request.method === undefined || !this.properties.methods.has(request.method)) {
+      response.writeHead(501).end()
+
+      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()
 
-    message.encoder = negotiate(request)
-    message.parse = async <T> (): Promise<T> => await read(request)
+        response.writeHead(503, { 'retry-after': remaining }).end()
+      }
 
-    return message
+      return
+    }
+
+    const host = request.headers.host!
+    const authority = this.authorities[host] ?? host
+    const context = new Context(authority, request as IncomingMessage, this.properties)
+
+    this.process!(context)
+      .then(this.success(context, response))
+      .catch(this.fail(context, response))
   }
 
-  private success (request: IncomingMessage, response: Response) {
-    return (message: OutgoingMessage) => {
+  private success (context: Context, response: http.ServerResponse) {
+    return async (message: OutgoingMessage) => {
       let status = message.status
 
       if (status === undefined)
-        if (message.body === null) status = 404
-        else if (request.method === 'POST') status = 201
-        else if (message.body === undefined) status = 204
-        else status = 200
-
-      response.status(status)
-      message.headers?.forEach((value, key) => response.set(key, value))
-
-      if (message.body !== undefined && message.body !== null)
-        write(request, response, message)
-      else
-        response.end()
+        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
+
+      response.statusCode = message.status = status
+      await write(context, response, message)
     }
   }
 
-  private fail (request: IncomingMessage, response: Response) {
-    return (exception: Error) => {
-      const status = exception instanceof Exception
-        ? exception.status
-        : 500
-
-      response.status(status)
+  private fail (context: Context, response: http.ServerResponse) {
+    return async (exception: Error) => {
+      if (!context.request.complete)
+        await adam(context.request)
 
-      const outputAllowed = exception instanceof ClientError || this.debug
+      response.statusCode = exception instanceof Exception ? exception.status : 500
 
-      if (outputAllowed) {
-        const body = exception instanceof Exception
-          ? exception.body
-          : (exception.stack ?? exception.message)
+      const message: OutgoingMessage = { status: response.statusCode }
 
-        write(request, response, { body })
-      } else
-        response.end()
+      if (context.encoder === null)
+        message.body = undefined
+      else if (exception instanceof ClientError || this.properties.debug)
+        message.body =
+          exception instanceof Exception
+            ? exception.body
+            : exception.stack ?? exception.message
 
-      // stop accepting request
-      if (!request.complete)
-        request.destroy()
+      await write(context, response, message)
     }
   }
 }
 
-function supportedMethods (methods: Set<string>) {
-  return (req: Request, res: Response, next: NextFunction): void => {
-    if (methods.has(req.method)) next()
-    else res.sendStatus(501)
-  }
+// https://github.com/whatwg/fetch/issues/1254
+async function adam (request: http.IncomingMessage): Promise<void> {
+  const devnull = fs.createWriteStream(os.devNull)
+
+  request.pipe(devnull)
+
+  await once(request, 'end')
 }
 
-function negotiate (request: Request): Format | null {
-  const negotiator = new Negotiator(request)
-  const mediaType = negotiator.mediaType(types)
+export const PORT = 8000
+export const DELAY = 3 // seconds
 
-  return mediaType === undefined ? null : formats[mediaType]
+const DEFAULTS: Omit<Properties, 'authorities'> = {
+  methods: new Set<string>(['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'LOCK', 'UNLOCK']),
+  debug: false,
+  trace: false,
+  port: PORT,
+  delay: DELAY * 1000
 }
 
 interface Properties {
+  authorities: Record<string, string>
   methods: Set<string>
   debug: boolean
+  trace: boolean
+  port: number
+  delay: number
 }
 
-function defaults (): Properties {
-  return {
-    methods: new Set<string>(['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']),
-    debug: false
-  }
+export type Options = { authorities: Properties['authorities'] } & {
+  [K in Exclude<keyof Properties, 'authorities'>]?: Properties[K]
 }
 
-export type Processing = (input: IncomingMessage) => Promise<OutgoingMessage>
+export type Processing = (input: Context) => Promise<OutgoingMessage>

package/source/HTTP/Timing.ts

@@ -0,0 +1,40 @@
+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
+
+    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 {
+    if (this.skip)
+      return
+
+    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/exceptions.ts

@@ -37,11 +37,17 @@ export class NotFound extends ClientError {
 }
 
 export class Conflict extends ClientError {
-  public constructor (body: any) {
+  public constructor (body?: any) {
     super(409, body)
   }
 }
 
+export class UnprocessableEntity extends ClientError {
+  public constructor (body?: any) {
+    super(422, body)
+  }
+}
+
 export class MethodNotAllowed extends ClientError {
   public constructor () {
     super(405)
@@ -65,3 +71,9 @@ export class PreconditionFailed extends ClientError {
     super(412)
   }
 }
+
+export class RequestEntityTooLarge extends ClientError {
+  public constructor (body?: any) {
+    super(413, body)
+  }
+}

package/source/HTTP/formats/index.ts

@@ -5,10 +5,10 @@ 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)

package/source/HTTP/formats/msgpack.ts

@@ -1,13 +1,16 @@
 import { type Buffer } from 'node:buffer'
-import * as msgpack from 'msgpackr'
-
-export const type = 'application/msgpack'
-export const multipart = 'multipart/msgpack'
+import { pack, unpack } from 'msgpackr'
 
 export function decode (buffer: Buffer): any {
-  return msgpack.decode(buffer)
+  return unpack(buffer)
 }
 
 export function encode (value: any): Buffer {
-  return msgpack.encode(value)
+  if (typeof value === 'object' && value !== null)
+    Object.setPrototypeOf(value, null)
+
+  return pack(value)
 }
+
+export const type = 'application/msgpack'
+export const multipart = 'multipart/msgpack'

package/source/HTTP/formats/text.ts

@@ -7,6 +7,6 @@ export function decode (buffer: Buffer): any {
   return buffer.toString()
 }
 
-export function encode (value: any): Buffer {
+export function encode (value: { toString: () => string }): Buffer {
   return Buffer.from(value.toString())
 }

package/source/HTTP/formats/yaml.ts

@@ -11,7 +11,7 @@ export function decode (buffer: Buffer): any {
 }
 
 export function encode (value: any): Buffer {
-  const text = yaml.dump(value)
+  const text = yaml.dump(value, { lineWidth: -1, noRefs: true })
 
   return Buffer.from(text)
 }