@toa.io/extensions.exposition 0.24.0-alpha.9 → 1.0.0-alpha.10

package/source/Factory.ts

@@ -3,45 +3,56 @@ import { Gateway } from './Gateway'
 import { Remotes } from './Remotes'
 import { Tree, syntax } from './RTD'
 import { Server } from './HTTP'
-import { type Endpoint, EndpointsFactory } from './Endpoint'
-import * as directives from './directives'
-import { type Directives, DirectivesFactory, type Family } from './Directive'
+import { EndpointsFactory } from './Endpoint'
+import { families, interceptors } from './directives'
+import { DirectivesFactory } from './Directive'
 import { Composition } from './Composition'
 import * as root from './root'
+import { Interception } from './Interception'
+import type { Broadcast } from './Gateway'
 import type { Connector, Locator, extensions } from '@toa.io/core'
 
 export class Factory implements extensions.Factory {
   private readonly boot: Bootloader
-  private readonly families: Family[]
 
   public constructor (boot: Bootloader) {
     this.boot = boot
-    this.families = directives.families
   }
 
   public tenant (locator: Locator, node: syntax.Node): Connector {
-    const broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id)
+    const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id)
 
     return new Tenant(broadcast, locator, node)
   }
 
   public service (): Connector | null {
     const debug = process.env.TOA_EXPOSITION_DEBUG === '1'
-    const broadcast = this.boot.bindings.broadcast(CHANNEL)
-    const server = Server.create({ methods: syntax.verbs, debug })
+    const trace = process.env.TOA_EXPOSITION_TRACE === '1'
+    const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL)
+
+    const server = Server.create({
+      methods: syntax.verbs,
+      debug,
+      trace
+    })
+
     const remotes = new Remotes(this.boot)
     const node = root.resolve()
     const methods = new EndpointsFactory(remotes)
-    const directives = new DirectivesFactory(this.families, remotes)
-    const tree = new Tree<Endpoint, Directives>(node, methods, directives)
+    const directives = new DirectivesFactory(families, remotes)
+    const interception = new Interception(interceptors)
+    const tree = new Tree(node, methods, directives)
 
     const composition = new Composition(this.boot)
-    const gateway = new Gateway(broadcast, server, tree)
+    const gateway = new Gateway(broadcast, tree, interception)
 
     gateway.depends(remotes)
     gateway.depends(composition)
 
-    return gateway
+    server.attach(gateway.process.bind(gateway))
+    server.depends(gateway)
+
+    return server
   }
 }
 

package/source/Gateway.ts

@@ -1,81 +1,84 @@
 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 { Method, Parameter, Tree } 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
 
-  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)
-
-    server.attach(this.process.bind(this))
   }
 
-  protected override async open (): Promise<void> {
-    await this.discover()
-
-    console.info('Gateway has started and is awaiting resource branches.')
-  }
+  public async process (context: http.Context): Promise<http.OutgoingMessage> {
+    const interception = await context.timing.capture('intercept',
+      this.interceptor.intercept(context))
 
-  protected override dispose (): void {
-    console.info('Gateway is closed.')
-  }
+    if (interception !== null)
+      return interception
 
-  private async process (request: http.IncomingMessage): Promise<http.OutgoingMessage> {
-    const match = this.tree.match(request.path)
+    const match = this.tree.match(context.url.pathname)
 
     if (match === null)
       throw new http.NotFound()
 
-    const { node, parameters } = match
+    const {
+      node,
+      parameters
+    } = match
 
-    if (!(request.method in node.methods))
+    if (!(context.request.method in node.methods))
       throw new http.MethodNotAllowed()
 
-    const method = node.methods[request.method]
-    const interruption = await method.directives.preflight(request, parameters)
-    const response = interruption ?? await this.call(method, request, parameters)
+    const method = node.methods[context.request.method]
 
-    await method.directives.settle(request, response)
+    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
   }
 
-  private async call
-  (method: Method<Endpoint, Directives>, request: http.IncomingMessage, parameters: Parameter[]):
+  protected override async open (): Promise<void> {
+    await this.discover()
+
+    console.info('Gateway has started and is awaiting resource branches.')
+  }
+
+  protected override dispose (): void {
+    console.info('Gateway is closed.')
+  }
+
+  private async call (method: Method, context: http.Context, parameters: Parameter[]):
   Promise<http.OutgoingMessage> {
-    if (request.path[request.path.length - 1] !== '/')
+    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>
-
-    if (reply instanceof Error)
-      throw new http.Conflict(reply)
-
-    return { body: reply }
+    return await method.endpoint
+      .call(context, parameters)
+      .catch(rethrow) as http.OutgoingMessage
   }
 
   private async discover (): Promise<void> {
@@ -95,4 +98,4 @@ export class Gateway extends Connector {
   }
 }
 
-type Broadcast = bindings.Broadcast<Label>
+export type Broadcast = bindings.Broadcast<Label>

package/source/HTTP/Context.ts

@@ -0,0 +1,67 @@
+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'
+
+export class Context {
+  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 pipelines: Pipelines = {
+    body: [],
+    response: []
+  }
+
+  public constructor (request: IncomingMessage, trace = false) {
+    this.request = request
+
+    this.url = new URL(request.url, `https://${request.headers.host}`)
+    this.timing = new Timing(trace)
+
+    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)
+  }
+}
+
+export interface IncomingMessage extends http.IncomingMessage {
+  url: string
+  method: string
+}
+
+interface Pipelines {
+  body: Array<(input: unknown) => unknown>
+  response: Array<(output: OutgoingMessage) => void>
+}
+
+const SUBTYPE = /^(?<type>\w{1,32})\/(vnd\.toa\.(?<subtype>\S{1,32})\+)(?<suffix>\S{1,32})$/

package/source/HTTP/Server.test.ts

@@ -1,199 +1,126 @@
+import { randomUUID } from 'node:crypto'
 import { Connector } from '@toa.io/core'
-import { immediate } from '@toa.io/generic'
-import { generate } from 'randomstring'
 import { type Processing, Server } from './Server'
 import { type OutgoingMessage } from './messages'
-import { express, cors, createRequest, res, next } from './Server.fixtures'
 import { BadRequest } from './exceptions'
-import type { Express, Request, RequestHandler } from 'express'
-import type { CorsOptions } from 'cors'
-import type http from 'node:http'
-
-jest.mock('express', () => () => express())
-jest.mock('cors', () => (options: CorsOptions) => cors(options))
 
 let server: Server
-let app: jest.MockedObject<Express>
-
-beforeEach(() => {
-  jest.clearAllMocks()
 
-  server = Server.create()
-  app = express.mock.results[0]?.value
+beforeAll(() => {
+  server = Server.create({ port: 0 })
 })
 
 it('should instance of connector', async () => {
   expect(server).toBeInstanceOf(Connector)
 })
 
-it('should create express app', async () => {
-  expect(express).toHaveBeenCalled()
-  expect(app.disable).toHaveBeenCalledWith('x-powered-by')
-})
-
-it('should support cors', async () => {
-  expect(cors).toHaveBeenCalledWith({ allowedHeaders: ['content-type'] } satisfies CorsOptions)
-
-  const middleware = cors.mock.results[0].value
-
-  expect(app.use).toHaveBeenCalledWith(middleware)
-})
-
 it('should start HTTP server', async () => {
-  const stared = server.connect()
-
-  await immediate()
-
-  expect(app.listen).toHaveBeenCalledWith(8000, expect.anything())
-
-  const done = app.listen.mock.calls[0][1]
-
-  if (done !== undefined) done()
+  await server.connect()
 
-  await stared
-})
-
-it('should stop HTTP server', async () => {
-  const started = server.connect()
-
-  await immediate()
-
-  app.listen.mock.calls[0][1]?.() // `listen` callback
-
-  await started
-
-  const stopped = server.disconnect()
-  const httpServer: jest.MockedObject<http.Server> = app.listen.mock.results[0].value
-
-  await immediate()
-
-  expect(httpServer.close).toHaveBeenCalled()
-
-  httpServer.close.mock.calls[0][0]?.() // `close` callback
-
-  await stopped
+  expect(server.connected).toBeTruthy()
+  expect(server.port).toBeGreaterThan(0)
 })
 
 it('should register request handler', async () => {
-  const process = jest.fn(async () => ({})) as unknown as Processing
-  const req = createRequest()
+  const process: Processing = jest.fn().mockResolvedValue(undefined)
 
   server.attach(process)
 
-  await use(req)
+  const res = await fetch(`http://localhost:${server.port}`)
+
+  await res.text()
 
-  expect(process).toHaveBeenCalled()
+  expect(process).toHaveBeenCalledTimes(1)
 })
 
 it('should send 501 on unknown method', async () => {
-  const req = createRequest({ method: generate() })
+  const head = await fetch(`http://localhost:${server.port}/`, { method: 'COPY' })
 
-  await use(req)
+  await head.text()
+  expect(head.status).toBe(501)
+})
 
-  expect(res.sendStatus).toHaveBeenCalledWith(501)
+it('should stop HTTP server', async () => {
+  await server.connect()
+  await server.disconnect()
+  expect(server.connected).toBeFalsy()
 })
 
 describe('result', () => {
-  it('should send status code 200 if the result has a value', async () => {
-    const req = createRequest()
+  beforeEach(async () => {
+    server = Server.create({ port: 0 })
+    await server.connect()
+  })
+
+  afterEach(async () => {
+    await server.disconnect()
+  })
 
+  it('should send status code 200 if the result has a value', async () => {
     server.attach(async (): Promise<OutgoingMessage> => ({
-      headers: new Headers(), body: generate()
+      headers: new Headers(), body: randomUUID()
     }))
-    await use(req)
 
-    expect(res.status).toHaveBeenCalledWith(200)
+    const res = await fetch(`http://localhost:${server.port}/`)
+
+    await res.text()
+    expect(res.status).toBe(200)
   })
 
   it('should send status code 204 if the result has no value', async () => {
-    const req = createRequest()
-
     server.attach(async (): Promise<OutgoingMessage> => ({ headers: new Headers() }))
-    await use(req)
 
-    expect(res.status).toHaveBeenCalledWith(204)
+    const res = await fetch(`http://localhost:${server.port}/`)
+
+    await res.text()
+    expect(res.status).toBe(204)
   })
 
   it('should send result', async () => {
-    const body = { [generate()]: generate() }
-    const json = JSON.stringify(body)
-    const buf = Buffer.from(json)
-    const req = createRequest({ headers: { accept: 'application/json' } })
+    const body = { [randomUUID()]: randomUUID() }
 
-    server.attach(async (): Promise<OutgoingMessage> => ({ headers: new Headers(), body }))
-    await use(req)
+    server.attach(async (): Promise<OutgoingMessage> =>
+      ({ headers: new Headers(), body }))
 
-    expect(res.end).toHaveBeenCalledWith(buf)
-  })
+    const res = await fetch(`http://localhost:${server.port}/`,
+      { headers: { accept: 'application/json' } })
 
-  it('should return 500 on exception', async () => {
-    async function process (): Promise<OutgoingMessage> {
-      throw new Error('Bad')
-    }
+    const result = await res.json()
 
-    const req = createRequest()
-
-    server.attach(process)
-    await use(req)
-
-    expect(res.status).toHaveBeenCalledWith(500)
+    expect(result).toEqual(body)
   })
 
-  it('should output exception message if debug is enabled', async () => {
-    jest.clearAllMocks()
-
-    server = Server.create({ debug: true })
-    app = express.mock.results[0]?.value
-
-    const message = generate()
-    const req = createRequest()
-
-    async function process (): Promise<OutgoingMessage> {
-      throw new Error(message)
-    }
+  it('should return 500 on exception', async () => {
+    server.attach(jest.fn().mockRejectedValue(new Error('Bad')))
 
-    server.attach(process)
-    await use(req)
+    const res = await fetch(`http://localhost:${server.port}/`)
 
-    expect(res.status).toHaveBeenCalledWith(500)
+    await res.text()
+    expect(res.status).toBe(500)
   })
 
   it('should send client error', async () => {
-    const req = createRequest()
-    const message = generate()
+    const message = randomUUID()
 
-    async function process (): Promise<OutgoingMessage> {
-      throw new BadRequest(message)
-    }
+    server.attach(jest.fn().mockRejectedValueOnce(new BadRequest(message)))
 
-    server.attach(process)
-    await use(req)
+    const res = await fetch(`http://localhost:${server.port}/`)
+    const text = await res.text()
 
-    expect(res.status).toHaveBeenCalledWith(400)
+    expect(res.status).toBe(400)
+    expect(text).toContain(message)
   })
 })
 
 describe('options', () => {
   it('should send 501 on unspecified method', async () => {
-    jest.clearAllMocks()
+    server = Server.create({ methods: new Set(['COPY']), port: 0 })
+    await server.connect()
 
-    server = Server.create({ methods: new Set(['COPY']) })
-    app = express.mock.results[0]?.value
+    const res = await fetch(`http://localhost:${server.port}/`)
 
-    const req = createRequest({ method: 'GET' })
-
-    await use(req)
-
-    expect(res.sendStatus).toHaveBeenCalledWith(501)
+    await res.text()
+    await server.disconnect()
+    expect(res.status).toBe(501)
   })
 })
-
-async function use (req: Request): Promise<void> {
-  for (const call of app.use.mock.calls) {
-    const usage = call[0] as unknown as RequestHandler
-
-    usage(req, res, next)
-  }
-
-  await immediate()
-}