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

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

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

package/source/HTTP/messages.ts

@@ -9,6 +9,11 @@ import type { Format } from './formats'
 
 export function write
 (request: IncomingMessage, response: Response, message: OutgoingMessage): void {
+  for (const transform of request.pipelines.response)
+    transform(message)
+
+  message.headers?.forEach((value, key) => response.set(key, value))
+
   if (message.body instanceof Readable)
     stream(message, request, response)
   else
@@ -36,7 +41,7 @@ export async function read (request: Request): Promise<any> {
 }
 
 function send (message: OutgoingMessage, request: IncomingMessage, response: Response): void {
-  if (message.body === undefined) {
+  if (message.body === undefined || message.body === null) {
     response.end()
 
     return
@@ -47,8 +52,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 +104,11 @@ export interface IncomingMessage extends Request {
   query: Query
   parse: <T> () => Promise<T>
   encoder: Format | null
+  subtype: string | 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> {

package/source/RTD/Tree.ts

@@ -25,6 +25,9 @@ export class Tree<
   }
 
   public match (path: string): Match<TEndpoint, TDirectives> | null {
+    if (path === '/')
+      return { node: this.trunk, parameters: [] }
+
     const fragments = fragment(path)
 
     return this.trunk.match(fragments)

package/source/RTD/syntax/parse.ts

@@ -28,7 +28,7 @@ function parseNode (input: object, shortcuts?: Shortcuts): Node {
     }
 
     if (key[0] === '/') {
-      const route = parseRoute(key, value, shortcuts)
+      const route = parseRoute(key, value as Node, shortcuts)
 
       node.routes.push(route)
 
@@ -36,7 +36,7 @@ function parseNode (input: object, shortcuts?: Shortcuts): Node {
     }
 
     if (verbs.has(key)) {
-      const method = parseMethod(key, value, shortcuts)
+      const method = parseMethod(key, value as Mapping, shortcuts)
 
       node.methods.push(method)
 
@@ -65,7 +65,7 @@ export function createNode (): Node {
   }
 }
 
-function parseRoute (path: string, value: object, shortcuts?: Shortcuts): Route {
+function parseRoute (path: string, value: Node, shortcuts?: Shortcuts): Route {
   const node = parse(value, shortcuts)
 
   return createRoute(path, node)
@@ -106,10 +106,10 @@ function parseQuery (mapping: any): void {
     return
 
   if (typeof query.limit === 'number')
-    query.limit = expandRange(query.limit)
+    query.limit = expandRange(query.limit as number)
 
   if (typeof query.omit === 'number')
-    query.omit = expandRange(query.omit)
+    query.omit = expandRange(query.omit as number)
 }
 
 function parseDirectives (mapping: Record<string, any>, shortcuts?: Shortcuts): Directive[] {
@@ -132,7 +132,7 @@ function parseDirectives (mapping: Record<string, any>, shortcuts?: Shortcuts):
 
 function parseDirective (key: string, value: any, shortcuts?: Shortcuts): Directive | null {
   if (shortcuts?.has(key) === true)
-    key = shortcuts.get(key) as string
+    key = shortcuts.get(key)! // eslint-disable-line @typescript-eslint/no-non-null-assertion
 
   const match = key.match(DIRECTIVE_RX)
 

package/source/RTD/syntax/types.ts

@@ -45,4 +45,4 @@ export interface Range {
   range: [number, number]
 }
 
-export const verbs = new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+export const verbs = new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'])

package/source/deployment.ts

@@ -27,8 +27,7 @@ export function deployment (_: unknown, annotation: Annotation | undefined): Dep
     }
 
   if (annotation?.['/'] !== undefined) {
-    const node = { '/': annotation['/'] }
-    const tree = parse(node, shortcuts)
+    const tree = parse(annotation['/'], shortcuts)
 
     service.variables.push({
       name: 'TOA_EXPOSITION',