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

package/source/Directive.ts

@@ -1,17 +1,21 @@
-import { type IncomingMessage, type OutgoingMessage } from './HTTP'
-import { type Remotes } from './Remotes'
+import type { IncomingMessage, OutgoingMessage } from './HTTP'
+import type { Remotes } from './Remotes'
+import type { Output } from './io'
 import type * as RTD from './RTD'
 
 export class Directives implements RTD.Directives<Directives> {
-  private readonly directives: DirectiveSet[]
+  private readonly sets: DirectiveSet[]
 
-  public constructor (directives: DirectiveSet[]) {
-    this.directives = directives
+  public constructor (sets: DirectiveSet[]) {
+    this.sets = sets
   }
 
   public async preflight (request: IncomingMessage, parameters: RTD.Parameter[]): Promise<Output> {
-    for (const directive of this.directives) {
-      const output = await directive.family.preflight(directive.directives, request, parameters)
+    for (const set of this.sets) {
+      if (set.family.preflight === undefined)
+        continue
+
+      const output = await set.family.preflight(set.directives, request, parameters)
 
       if (output !== null) {
         await this.settle(request, output)
@@ -24,13 +28,13 @@ export class Directives implements RTD.Directives<Directives> {
   }
 
   public async settle (request: IncomingMessage, response: OutgoingMessage): Promise<void> {
-    for (const directive of this.directives)
-      if (directive.family.settle !== undefined)
-        await directive.family.settle(directive.directives, request, response)
+    for (const set of this.sets)
+      if (set.family.settle !== undefined)
+        await set.family.settle(set.directives, request, response)
   }
 
   public merge (directives: Directives): void {
-    this.directives.push(...directives.directives)
+    this.sets.push(...directives.sets)
   }
 }
 
@@ -61,7 +65,7 @@ export class DirectivesFactory implements RTD.DirectivesFactory<Directives> {
       const family = this.families[declaration.family]
 
       if (family === undefined)
-        throw new Error(`Directive family '${declaration.family}' not found.`)
+        throw new Error(`Directive family '${declaration.family}' is not found.`)
 
       const directive = family.create(declaration.name, declaration.value, this.remtoes)
 
@@ -100,9 +104,11 @@ export interface Family<TDirective = any, TExtension = any> {
   readonly name: string
   readonly mandatory: boolean
 
+  // produce: (declarations: RTD.syntax.Directive[], remotes: Remotes) => TDirective[]
+
   create: (name: string, value: any, remotes: Remotes) => TDirective
 
-  preflight: (directives: TDirective[],
+  preflight?: (directives: TDirective[],
     request: IncomingMessage & TExtension,
     parameters: RTD.Parameter[]) => Output | Promise<Output>
 
@@ -115,6 +121,3 @@ interface DirectiveSet {
   family: Family
   directives: any[]
 }
-
-export type Input = IncomingMessage
-export type Output = OutgoingMessage | null

package/source/Factory.ts

@@ -4,19 +4,18 @@ 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 { families, interceptors } from './directives'
+import { type Directives, DirectivesFactory } from './Directive'
 import { Composition } from './Composition'
 import * as root from './root'
+import { Interception } from './Interception'
 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 {
@@ -32,16 +31,18 @@ export class Factory implements extensions.Factory {
     const remotes = new Remotes(this.boot)
     const node = root.resolve()
     const methods = new EndpointsFactory(remotes)
-    const directives = new DirectivesFactory(this.families, remotes)
+    const directives = new DirectivesFactory(families, remotes)
+    const interception = new Interception(interceptors)
     const tree = new Tree<Endpoint, Directives>(node, methods, directives)
 
     const composition = new Composition(this.boot)
-    const gateway = new Gateway(broadcast, server, tree)
+    const gateway = new Gateway(broadcast, server, tree, interception)
 
     gateway.depends(remotes)
     gateway.depends(composition)
+    server.depends(gateway)
 
-    return gateway
+    return server
   }
 }
 

package/source/Gateway.ts

@@ -1,25 +1,31 @@
 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 { Interceptor } from './Interception'
+import type { Maybe } from '@toa.io/types'
+import type { Method, Parameter, Tree } from './RTD'
+import type { Label } from './discovery'
+import type { Branch } from './Branch'
+import type { Endpoint } from './Endpoint'
+import type { Directives } from './Directive'
 
 export class Gateway extends Connector {
   private readonly broadcast: Broadcast
   private readonly tree: Tree<Endpoint, Directives>
+  private readonly interceptor: Interceptor
+  private readonly server: Connector
 
-  public constructor (broadcast: Broadcast, server: http.Server, tree: Tree<Endpoint, Directives>) {
+  // eslint-disable-next-line max-params, max-len
+  public constructor (broadcast: Broadcast, server: http.Server, tree: Tree<Endpoint, Directives>, interception: Interceptor) {
     super()
 
     this.broadcast = broadcast
     this.tree = tree
+    this.interceptor = interception
+    this.server = server
 
     this.depends(broadcast)
-    this.depends(server)
+    // this.depends(server)
 
     server.attach(this.process.bind(this))
   }
@@ -35,6 +41,11 @@ export class Gateway extends Connector {
   }
 
   private async process (request: http.IncomingMessage): Promise<http.OutgoingMessage> {
+    const interception = await this.interceptor.intercept(request)
+
+    if (interception !== null)
+      return interception
+
     const match = this.tree.match(request.path)
 
     if (match === null)
@@ -68,6 +79,9 @@ export class Gateway extends Connector {
 
     const body = await request.parse()
 
+    if ('embed' in request && typeof body === 'object' && body !== null)
+      Object.assign(body, request.embed)
+
     const reply = await method.endpoint
       .call(body, request.query, parameters)
       .catch(rethrow) as Maybe<unknown>

package/source/HTTP/Server.fixtures.ts

@@ -1,4 +1,3 @@
-import { Buffer } from 'buffer'
 import { Readable } from 'stream'
 import type { IncomingMessage } from './messages'
 import type * as http from 'node:http'

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.disconnect()
+  expect(server.port).toBe(0)
+  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()
-}

package/source/HTTP/Server.ts

@@ -1,52 +1,67 @@
+import fs from 'node:fs'
+import os from 'node:os'
 import express from 'express'
-import cors from 'cors'
 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 { 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'
 
 export class Server extends Connector {
-  private readonly debug: boolean
-  private readonly app: Express
   private server?: http.Server
+  private readonly app: Express
+  private readonly debug: boolean
+  private readonly requestedPort: number
 
-  private constructor (app: Express, debug: boolean) {
+  private constructor (app: Express, debug: boolean, port: number) {
     super()
 
     this.app = app
     this.debug = debug
+    this.requestedPort = port
+  }
+
+  public get port (): number {
+    if (this.server === undefined) return this.requestedPort
+
+    const address = this.server.address()
+
+    if (address === null || typeof address === 'string')
+      throw new Error('Server is not listening on a port.')
+
+    return address.port
   }
 
-  public static create (options: Partial<Properties> = {}): Server {
-    const properties: Properties = Object.assign({}, defaults(), options)
+  public static create (options?: Partial<Properties>): Server {
+    const properties = options === undefined
+      ? DEFAULTS
+      : { ...DEFAULTS, ...options }
 
     const app = express()
 
     app.disable('x-powered-by')
-    app.use(cors({ allowedHeaders: ['content-type'] }))
     app.use(supportedMethods(properties.methods))
 
-    return new Server(app, properties.debug)
+    return new Server(app, properties.debug, properties.port)
   }
 
   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.app.use((request: Request, response: Response) => {
+      const message = this.extend(request)
+
+      process(message)
+        .then(this.success(message, response))
+        .catch(this.fail(message, response))
     })
   }
 
   protected override async open (): Promise<void> {
     const listening = promex()
 
-    this.server = this.app.listen(8000, listening.callback)
+    this.server = this.app.listen(this.requestedPort, listening.callback)
 
     await listening
 
@@ -59,17 +74,27 @@ export class Server extends Connector {
     this.server?.close(stopped.callback)
 
     await stopped
-  }
 
-  protected override dispose (): void {
+    this.server = undefined
+
     console.info('HTTP Server has been stopped.')
   }
 
-  private async extend (request: IncomingMessage): Promise<IncomingMessage> {
-    const message = request as unknown as IncomingMessage
+  private extend (request: Request): IncomingMessage {
+    const message = request as IncomingMessage
+
+    negotiate(request, message)
+
+    message.pipelines = { body: [], response: [] }
+
+    message.parse = async <T> (): Promise<T> => {
+      const value = await read(request)
 
-    message.encoder = negotiate(request)
-    message.parse = async <T> (): Promise<T> => await read(request)
+      if (message.pipelines.body.length === 0)
+        return value
+
+      return message.pipelines.body.reduce((value, transform) => transform(value), value)
+    }
 
     return message
   }
@@ -85,37 +110,30 @@ export class Server extends Connector {
         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()
+      write(request, response, message)
     }
   }
 
   private fail (request: IncomingMessage, response: Response) {
-    return (exception: Error) => {
+    return async (exception: Error) => {
+      if (!request.complete)
+        await adam(request)
+
       const status = exception instanceof Exception
         ? exception.status
         : 500
 
       response.status(status)
 
-      const outputAllowed = exception instanceof ClientError || this.debug
+      const message: OutgoingMessage = {}
+      const verbose = exception instanceof ClientError || this.debug
 
-      if (outputAllowed) {
-        const body = exception instanceof Exception
+      if (verbose)
+        message.body = exception instanceof Exception
           ? exception.body
           : (exception.stack ?? exception.message)
 
-        write(request, response, { body })
-      } else
-        response.end()
-
-      // stop accepting request
-      if (!request.complete)
-        request.destroy()
+      write(request, response, message)
     }
   }
 }
@@ -127,23 +145,49 @@ function supportedMethods (methods: Set<string>) {
   }
 }
 
-function negotiate (request: Request): Format | null {
+function negotiate (request: Request, message: IncomingMessage): void {
+  if (request.headers.accept !== undefined) {
+    const match = SUBTYPE.exec(request.headers.accept)
+
+    if (match !== null) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const { type, subtype, suffix } = match.groups!
+
+      request.headers.accept = `${type}/${suffix}`
+      message.subtype = subtype
+    }
+  }
+
   const negotiator = new Negotiator(request)
   const mediaType = negotiator.mediaType(types)
 
-  return mediaType === undefined ? null : formats[mediaType]
+  message.encoder = mediaType === undefined ? null : formats[mediaType]
+}
+
+// https://github.com/whatwg/fetch/issues/1254
+async function adam (request: Request): Promise<void> {
+  const completed = promex()
+  const devnull = fs.createWriteStream(os.devNull)
+
+  request
+    .on('end', completed.callback)
+    .pipe(devnull)
+
+  return await completed
+}
+
+const DEFAULTS: Properties = {
+  methods: new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']),
+  debug: false,
+  port: 8000
 }
 
 interface Properties {
   methods: Set<string>
   debug: boolean
-}
-
-function defaults (): Properties {
-  return {
-    methods: new Set<string>(['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']),
-    debug: false
-  }
+  port: number
 }
 
 export type Processing = (input: IncomingMessage) => Promise<OutgoingMessage>
+
+const SUBTYPE = /^(?<type>\w{1,32})\/(vnd\.toa\.(?<subtype>\S{1,32})\+)(?<suffix>\S{1,32})$/