@toa.io/extensions.exposition 0.24.0-alpha.17 → 0.24.0-alpha.19

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,203 +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(expect.objectContaining({
-    credentials: true,
-    maxAge: 86400,
-    allowedHeaders: ['accept', 'authorization', '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,57 +1,64 @@
 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 { CorsOptions } from 'cors'
 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 constructor (app: Express, debug: boolean) {
+  private constructor (private readonly app: Express,
+    private readonly debug: boolean,
+    private readonly requestedPort: number) {
     super()
+  }
+
+  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.')
 
-    this.app = app
-    this.debug = debug
+    return address.port
   }
 
   public static create (options?: Partial<Properties>): Server {
-    const properties: Properties = options === undefined
+    const properties = options === undefined
       ? DEFAULTS
       : { ...DEFAULTS, ...options }
 
     const app = express()
 
     app.disable('x-powered-by')
-    app.use(cors(CORS))
+    // app.use(cors(CORS))
     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) => {
-      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
 
@@ -64,23 +71,35 @@ 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
 
     message.encoder = negotiate(request)
-    message.parse = async <T> (): Promise<T> => await read(request)
+    message.pipelines = { body: [], response: [] }
+
+    message.parse = async <T> (): Promise<T> => {
+      const value = await read(request)
+
+      if (message.pipelines.body.length === 0)
+        return value
+
+      return message.pipelines.body.reduce((value, transform) => transform(value), value)
+    }
 
     return message
   }
 
   private success (request: IncomingMessage, response: Response) {
     return (message: OutgoingMessage) => {
+      for (const transform of request.pipelines.response)
+        transform(message)
+
       let status = message.status
 
       if (status === undefined)
@@ -150,21 +169,16 @@ async function adam (request: Request): Promise<void> {
   return await completed
 }
 
-const DEFAULTS = {
-  methods: new Set<string>(['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']),
-  debug: false
-}
-
-const CORS: CorsOptions = {
-  credentials: true,
-  maxAge: 86400,
-  allowedHeaders: ['accept', 'authorization', 'content-type'],
-  origin: (origin: string | undefined, callback) => callback(null, origin)
+const DEFAULTS: Properties = {
+  methods: new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']),
+  debug: false,
+  port: 8000
 }
 
 interface Properties {
   methods: Set<string>
   debug: boolean
+  port: number
 }
 
 export type Processing = (input: IncomingMessage) => Promise<OutgoingMessage>

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)
 }

package/source/HTTP/messages.ts

@@ -47,8 +47,10 @@ function send (message: OutgoingMessage, request: IncomingMessage, response: Res
 
   const buf = request.encoder.encode(message.body)
 
-  response.set('content-type', request.encoder.type)
-  response.end(buf)
+  response
+    .set('content-type', request.encoder.type)
+    .append('vary', 'accept')
+    .end(buf)
 }
 
 function stream
@@ -97,6 +99,10 @@ export interface IncomingMessage extends Request {
   query: Query
   parse: <T> () => Promise<T>
   encoder: Format | null
+  pipelines: {
+    body: Array<(input: unknown) => unknown>
+    response: Array<(output: OutgoingMessage) => void>
+  }
 }
 
 export interface OutgoingMessage {

package/source/Interception.ts

@@ -0,0 +1,24 @@
+import type { Input, Output } from './io'
+
+export class Interception implements Interceptor {
+  private readonly interceptors: Interceptor[]
+
+  public constructor (interceptors: Interceptor[]) {
+    this.interceptors = interceptors
+  }
+
+  public async intercept (input: Input): Promise<Output> {
+    for (const interceptor of this.interceptors) {
+      const output = await interceptor.intercept(input)
+
+      if (output !== null)
+        return output
+    }
+
+    return null
+  }
+}
+
+export interface Interceptor {
+  intercept: (input: Input) => Output | Promise<Output>
+}

package/source/RTD/Directives.ts

@@ -1,7 +1,7 @@
 import type * as syntax from './syntax'
 
-export interface Directives<T = any> {
-  merge: (directive: T) => void
+export interface Directives<TDirective = any> {
+  merge: (directive: TDirective) => void
 }
 
 export interface DirectivesFactory<T = any> {