@toa.io/extensions.exposition 0.9.0-canary.2 → 0.20.0-alpha.1

package/source/Factory.ts

@@ -0,0 +1,53 @@
+import { Tenant } from './Tenant'
+import { Gateway } from './Gateway'
+import { Remotes } from './Remotes'
+import { Tree, syntax } from './RTD'
+import { Server } from './HTTP'
+import { type Endpoint, EndpointFactory } from './Endpoint'
+import * as directives from './directives'
+import { type Directives, DirectivesFactory, type Family } from './Directive'
+import { Composition } from './Composition'
+import * as root from './root'
+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, manifest: syntax.Node): Connector {
+    const broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id)
+
+    return new Tenant(broadcast, locator, manifest)
+  }
+
+  public service (): Connector | null {
+    return this.gateway()
+  }
+
+  private gateway (): Gateway {
+    const broadcast = this.boot.bindings.broadcast(CHANNEL)
+    const server = Server.create({ methods: syntax.verbs })
+    const remotes = new Remotes(this.boot)
+    const methods = new EndpointFactory(remotes)
+    const directives = new DirectivesFactory(this.families, remotes)
+    const node = root.resolve()
+    const tree = new Tree<Endpoint, Directives>(node, methods, directives)
+
+    const composition = new Composition(this.boot)
+    const gateway = new Gateway(broadcast, server, tree)
+
+    gateway.depends(composition)
+
+    return gateway
+  }
+}
+
+const CHANNEL = 'exposition'
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+export type Bootloader = typeof import('@toa.io/boot')

package/source/Gateway.ts

@@ -0,0 +1,93 @@
+import { type bindings, Connector } from '@toa.io/core'
+import { Nope, type Nopeable } from 'nopeable'
+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'
+
+export class Gateway extends Connector {
+  private readonly broadcast: Broadcast
+  private readonly tree: Tree<Endpoint, Directives>
+
+  public constructor (broadcast: Broadcast, server: http.Server, tree: Tree<Endpoint, Directives>) {
+    super()
+
+    this.broadcast = broadcast
+    this.tree = tree
+
+    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.')
+  }
+
+  protected override dispose (): void {
+    console.info('Gateway is closed.')
+  }
+
+  private async process (request: http.IncomingMessage): Promise<http.OutgoingMessage> {
+    if (request.path[request.path.length - 1] !== '/')
+      throw new http.NotFound('Trailing slash is required.')
+
+    const match = this.tree.match(request.path)
+
+    if (match === null)
+      throw new http.NotFound()
+
+    const { node, parameters } = match
+
+    if (!(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)
+
+    await method.directives.settle(request, response)
+
+    return response
+  }
+
+  private async call
+  (method: Method<Endpoint, Directives>, request: http.IncomingMessage, parameters: Parameter[]):
+  Promise<http.OutgoingMessage> {
+    if (method.endpoint === null)
+      throw new http.MethodNotAllowed()
+
+    const reply = await method.endpoint
+      .call(request.body, request.query, parameters)
+      .catch(rethrow) as Nopeable<unknown>
+
+    if (reply instanceof Nope)
+      throw new http.Conflict(reply)
+
+    return { body: reply }
+  }
+
+  private async discover (): Promise<void> {
+    await this.broadcast.receive<Branch>('expose', this.merge.bind(this))
+    await this.broadcast.transmit<null>('ping', null)
+  }
+
+  private merge (branch: Branch): void {
+    try {
+      this.tree.merge(branch.node, branch)
+
+      console.info('Resource branch of ' +
+        `'${branch.namespace}.${branch.component}' has been merged.`)
+    } catch (exception) {
+      console.error(exception)
+    }
+  }
+}
+
+type Broadcast = bindings.Broadcast<Label>

package/source/HTTP/Server.fixtures.ts

@@ -0,0 +1,45 @@
+import { Buffer } from 'buffer'
+import { Readable } from 'stream'
+import type { IncomingMessage } from './messages'
+import type * as http from 'node:http'
+import type { NextFunction, Response, Express, Request } from 'express'
+import type { CorsOptions } from 'cors'
+
+const server = {
+  close: jest.fn()
+} as unknown as jest.Mock<http.Server>
+
+const app = {
+  enable: jest.fn(),
+  disable: jest.fn(),
+  use: jest.fn(),
+  listen: jest.fn(() => server)
+} as unknown as jest.Mock<Express>
+
+export function createRequest (req: Partial<Request> = {}, content: string | Buffer = ''):
+jest.MockedObject<Request> {
+  const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content)
+  const stream = Readable.from(buffer)
+
+  Object.assign(stream, { headers: {} }, req)
+
+  return stream as unknown as jest.MockedObject<Request>
+}
+
+export function createIncomingMessage (path: string, method: string = 'GET'): IncomingMessage {
+  return { method, path, headers: {}, body: undefined, query: {} }
+}
+
+export const res = {
+  status: jest.fn(() => res),
+  sendStatus: jest.fn(() => res),
+  set: jest.fn(() => res),
+  send: jest.fn(() => res),
+  end: jest.fn(() => res)
+} as unknown as jest.MockedObject<Response>
+
+export const next = jest.fn() as unknown as NextFunction
+
+export const express = jest.fn(() => app)
+
+export const cors = jest.fn((_: CorsOptions) => () => undefined)

package/source/HTTP/Server.test.ts

@@ -0,0 +1,221 @@
+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
+})
+
+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 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
+})
+
+it('should register request handler', async () => {
+  const process = jest.fn(async () => ({})) as unknown as Processing
+  const req = createRequest()
+
+  server.attach(process)
+
+  await use(req)
+
+  expect(process).toHaveBeenCalled()
+})
+
+it('should send 501 on unknown method', async () => {
+  const req = createRequest({ method: generate() })
+
+  await use(req)
+
+  expect(res.sendStatus).toHaveBeenCalledWith(501)
+})
+
+describe('request', () => {
+  const process = jest.fn(async () => ({})) as unknown as Processing
+
+  beforeEach(() => {
+    server.attach(process)
+  })
+
+  it('should pass decoded request', async () => {
+    const path = generate()
+    const method = generate()
+    const headers = { 'content-type': 'application/json' }
+    const body = { [generate()]: generate() }
+    const json = JSON.stringify(body)
+    const req = createRequest({ path, method, headers }, json)
+
+    await use(req)
+
+    expect(process).toHaveBeenCalledWith(expect.objectContaining({ path, method, headers, body }))
+  })
+})
+
+describe('result', () => {
+  it('should send status code 200 if the result has a value', async () => {
+    const process = async (): Promise<OutgoingMessage> => ({ headers: {}, body: generate() })
+    const req = createRequest()
+
+    server.attach(process)
+    await use(req)
+
+    expect(res.status).toHaveBeenCalledWith(200)
+  })
+
+  it('should send status code 204 if the result has no value', async () => {
+    const process = async (): Promise<OutgoingMessage> => ({ headers: {} })
+    const req = createRequest()
+
+    server.attach(process)
+    await use(req)
+
+    expect(res.status).toHaveBeenCalledWith(204)
+  })
+
+  it('should send result', async () => {
+    const body = { [generate()]: generate() }
+    const json = JSON.stringify(body)
+    const buf = Buffer.from(json)
+    const process = async (): Promise<OutgoingMessage> => ({ headers: {}, body })
+    const req = createRequest({ headers: { accept: 'application/json' } })
+
+    server.attach(process)
+    await use(req)
+
+    expect(res.send).toHaveBeenCalledWith(buf)
+  })
+
+  it('should return 500 on exception', async () => {
+    const process = async (): Promise<OutgoingMessage> => {
+      throw new Error('Bad')
+    }
+
+    const req = createRequest()
+
+    server.attach(process)
+    await use(req)
+
+    expect(res.status).toHaveBeenCalledWith(500)
+  })
+
+  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()
+
+    const process = async (): Promise<OutgoingMessage> => {
+      throw new Error(message)
+    }
+
+    server.attach(process)
+    await use(req)
+
+    expect(res.status).toHaveBeenCalledWith(500)
+  })
+
+  it('should send client error', async () => {
+    const req = createRequest()
+    const message = generate()
+
+    const process = async (): Promise<OutgoingMessage> => {
+      throw new BadRequest(message)
+    }
+
+    server.attach(process)
+    await use(req)
+
+    expect(res.status).toHaveBeenCalledWith(400)
+  })
+})
+
+describe('options', () => {
+  it('should send 501 on unspecified method', async () => {
+    jest.clearAllMocks()
+
+    server = Server.create({ methods: new Set(['COPY']) })
+    app = express.mock.results[0]?.value
+
+    const req = createRequest({ method: 'GET' })
+
+    await use(req)
+
+    expect(res.sendStatus).toHaveBeenCalledWith(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

@@ -0,0 +1,135 @@
+import express from 'express'
+import cors from 'cors'
+import { Connector } from '@toa.io/core'
+import { promex } from '@toa.io/generic'
+import { read, write, type IncomingMessage, type OutgoingMessage } from './messages'
+import { ClientError, Exception } from './exceptions'
+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) {
+    super()
+
+    this.app = app
+    this.debug = debug
+  }
+
+  public static create (options: Partial<Properties> = {}): Server {
+    const properties: Properties = Object.assign({}, 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)
+  }
+
+  public attach (process: Processing): void {
+    this.app.use((request: Request, response: Response): void => {
+      this.read(request)
+        .then(process)
+        .then(this.success(request, response))
+        .catch(this.fail(request, response))
+    })
+  }
+
+  protected override async open (): Promise<void> {
+    const listening = promex()
+
+    this.server = this.app.listen(8000, listening.callback)
+
+    await listening
+
+    console.info('HTTP Server is listening.')
+  }
+
+  protected override async close (): Promise<void> {
+    const stopped = promex()
+
+    this.server?.close(stopped.callback)
+
+    await stopped
+  }
+
+  protected override dispose (): void {
+    console.info('HTTP Server has been stopped.')
+  }
+
+  private async read (request: Request): Promise<IncomingMessage> {
+    const { method, path, headers, query } = request
+    const body = await read(request)
+
+    return { method, path, headers, query, body }
+  }
+
+  private success (request: Request, response: Response) {
+    return (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)
+        .set(message.headers)
+
+      if (message.body !== undefined && message.body !== null)
+        write(request, response, message.body)
+      else
+        response.end()
+    }
+  }
+
+  private fail (request: Request, response: Response) {
+    return (exception: Error) => {
+      let status = 500
+
+      if (exception instanceof Exception)
+        status = exception.status
+
+      const outputAllowed = exception instanceof ClientError || this.debug
+
+      response.status(status)
+
+      if (outputAllowed) {
+        const body = exception instanceof Exception
+          ? exception.body
+          : (exception.stack ?? exception.message)
+
+        write(request, response, body)
+      } else
+        response.end()
+    }
+  }
+}
+
+function supportedMethods (methods: Set<string>) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (methods.has(req.method)) next()
+    else res.sendStatus(501)
+  }
+}
+
+interface Properties {
+  methods: Set<string>
+  debug: boolean
+}
+
+function defaults (): Properties {
+  return {
+    methods: new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+    debug: process.env.TOA_DEV === '1'
+  }
+}
+
+export type Processing = (input: IncomingMessage) => Promise<OutgoingMessage>

package/source/HTTP/exceptions.ts

@@ -0,0 +1,77 @@
+import { types } from './formats'
+
+export class Exception extends Error {
+  public readonly status: number
+  public readonly body?: any
+
+  protected constructor (status: number, body?: any) {
+    super()
+    this.status = status
+    this.body = body
+  }
+}
+
+export class ClientError extends Exception {
+}
+
+export class BadRequest extends ClientError {
+  public constructor (body?: any) {
+    super(400, body)
+  }
+}
+
+export class Unauthorized extends ClientError {
+  public constructor (body?: any) {
+    super(401, body)
+  }
+}
+
+export class Forbidden extends ClientError {
+  public constructor (body?: any) {
+    super(403, body)
+  }
+}
+
+export class NotFound extends ClientError {
+  public constructor (body?: any) {
+    super(404, body)
+  }
+}
+
+export class Conflict extends ClientError {
+  public constructor (body: any) {
+    super(409, body)
+  }
+}
+
+export class MethodNotAllowed extends ClientError {
+  public constructor () {
+    super(405)
+  }
+}
+
+class MediaTypeException extends ClientError {
+  private static readonly message = 'Supported media types:\n- ' + types.join('\n- ')
+
+  protected constructor (status: number) {
+    super(status, MediaTypeException.message)
+  }
+}
+
+export class NotAcceptable extends MediaTypeException {
+  public constructor () {
+    super(406)
+  }
+}
+
+export class UnsupportedMediaType extends MediaTypeException {
+  public constructor () {
+    super(415)
+  }
+}
+
+export class PreconditionFailed extends ClientError {
+  public constructor () {
+    super(412)
+  }
+}

package/source/HTTP/formats/index.ts

@@ -0,0 +1,19 @@
+import { type Buffer } from 'node:buffer'
+import * as json from './json'
+import * as yaml from './yaml'
+import * as msgpack from './msgpack'
+import * as text from './text'
+
+export const formats: Record<string, Format> = {
+  'application/yaml': yaml,
+  'application/msgpack': msgpack,
+  'application/json': json,
+  'text/plain': text
+}
+
+export const types = Object.keys(formats)
+
+export interface Format {
+  encode: (value: any) => Buffer
+  decode: (buffer: Buffer) => any
+}

package/source/HTTP/formats/json.ts

@@ -0,0 +1,13 @@
+import { Buffer } from 'node:buffer'
+
+export function decode (buffer: Buffer): any {
+  const text = buffer.toString()
+
+  return JSON.parse(text)
+}
+
+export function encode (value: any): Buffer {
+  const text = JSON.stringify(value)
+
+  return Buffer.from(text)
+}

package/source/HTTP/formats/msgpack.ts

@@ -0,0 +1,10 @@
+import { type Buffer } from 'node:buffer'
+import * as msgpack from 'msgpackr'
+
+export function decode (buffer: Buffer): any {
+  return msgpack.decode(buffer)
+}
+
+export function encode (value: any): Buffer {
+  return msgpack.encode(value)
+}

package/source/HTTP/formats/text.ts

@@ -0,0 +1,9 @@
+import { Buffer } from 'node:buffer'
+
+export function decode (buffer: Buffer): any {
+  return buffer.toString()
+}
+
+export function encode (value: any): Buffer {
+  return Buffer.from(value.toString())
+}

package/source/HTTP/formats/yaml.ts

@@ -0,0 +1,14 @@
+import { Buffer } from 'node:buffer'
+import * as yaml from 'js-yaml'
+
+export function decode (buffer: Buffer): any {
+  const text = buffer.toString()
+
+  return yaml.load(text)
+}
+
+export function encode (value: any): Buffer {
+  const text = yaml.dump(value)
+
+  return Buffer.from(text)
+}

package/source/HTTP/index.ts

@@ -0,0 +1,3 @@
+export * from './Server'
+export * from './messages'
+export * from './exceptions'