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

package/source/HTTP/messages.test.ts

@@ -0,0 +1,116 @@
+import { Buffer } from 'node:buffer'
+import { generate } from 'randomstring'
+import * as msgpack from 'msgpackr'
+import { type OutgoingMessage, read, write } from './messages'
+import { createRequest, res } from './Server.fixtures'
+import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions'
+
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+describe('read', () => {
+  it('should parse application/json', async () => {
+    const path = generate()
+    const headers = { 'content-type': 'application/json' }
+    const input = { [generate()]: generate() }
+    const json = JSON.stringify(input)
+    const request = createRequest({ path, headers }, json)
+    const output = await read(request)
+
+    expect(output).toStrictEqual(input)
+  })
+
+  it('should parse application/yaml', async () => {
+    const path = generate()
+    const headers = { 'content-type': 'application/yaml' }
+    const yaml = 'foo: 1'
+    const request = createRequest({ path, headers }, yaml)
+    const value = await read(request)
+
+    expect(value).toStrictEqual({ foo: 1 })
+  })
+
+  it('should parse application/mskpack', async () => {
+    const path = generate()
+    const headers = { 'content-type': 'application/msgpack' }
+    const input = { [generate()]: generate() }
+    const msg = msgpack.encode(input)
+    const request = createRequest({ path, headers }, msg)
+    const output = await read(request)
+
+    expect(output).toStrictEqual(input)
+  })
+
+  it('should parse text/plain', async () => {
+    const path = generate()
+    const headers = { 'content-type': 'text/plain' }
+    const input = generate()
+    const request = createRequest({ path, headers }, input)
+    const output = await read(request)
+
+    expect(output).toStrictEqual(input)
+  })
+
+  it('should throw on unsupported request media type', async () => {
+    const path = generate()
+    const headers = { 'content-type': 'wtf/' + generate() }
+    const request = createRequest({ path, headers })
+
+    await expect(read(request)).rejects.toThrow(UnsupportedMediaType)
+  })
+
+  it('should throw on malformed content', async () => {
+    const path = generate()
+    const text = '{ "foo": "val... oops '
+    const headers = { 'content-type': 'application/json' }
+    const request = createRequest({ path, headers }, text)
+
+    await expect(read(request)).rejects.toThrow(BadRequest)
+  })
+})
+
+describe('write', () => {
+  it('should write encoded response', async () => {
+    const value = { [generate()]: generate() }
+    const json = JSON.stringify(value)
+    const buf = Buffer.from(json)
+    const headers = { accept: 'application/json' }
+    const request = createRequest({ headers }, buf)
+
+    write(request, res, value)
+
+    expect(res.set).toHaveBeenCalledWith('content-type', 'application/json')
+    expect(res.send).toHaveBeenCalledWith(buf)
+  })
+
+  it('should throw on unsupported response media type', async () => {
+    const headers = { accept: 'wtf/' + generate() }
+    const request = createRequest({ headers })
+    const value = generate()
+
+    expect(() => {
+      write(request, res, value)
+    }).toThrow(NotAcceptable)
+  })
+
+  it('should use application/yaml as default', async () => {
+    const request = createRequest()
+    const message: OutgoingMessage = { headers: {}, body: 'hello' }
+
+    write(request, res, message)
+
+    expect(res.set).toHaveBeenCalledWith('content-type', 'application/yaml')
+    expect(res.send).toHaveBeenCalled()
+  })
+
+  it('should negotiate', async () => {
+    const headers = { accept: 'text/html, application/*;q=0.2, image/jpeg;q=0.8' }
+    const request = createRequest({ headers })
+    const message: OutgoingMessage = { headers: {}, body: 'hello' }
+
+    write(request, res, message)
+
+    expect(res.set).toHaveBeenCalledWith('content-type', 'application/yaml')
+  })
+})

package/source/HTTP/messages.ts

@@ -0,0 +1,77 @@
+import { type IncomingHttpHeaders, type OutgoingHttpHeaders } from 'node:http'
+import { type Request, type Response } from 'express'
+import Negotiator from 'negotiator'
+import { buffer } from '@toa.io/generic'
+import { formats, types } from './formats'
+import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions'
+
+export function write (request: Request, response: Response, body: any): void {
+  const buf = format(body, request, response)
+
+  response.send(buf)
+}
+
+export async function read (request: Request): Promise<any> {
+  const type = request.headers['content-type']
+
+  if (type === undefined) return undefined
+
+  if (!(type in formats)) throw new UnsupportedMediaType()
+
+  const format = formats[type]
+
+  const buf = await buffer(request)
+
+  try {
+    return format.decode(buf)
+  } catch {
+    throw new BadRequest()
+  }
+}
+
+function format (body: any, request: Request, response: Response): Buffer | undefined {
+  if (body === undefined || body?.length === 0) return
+
+  const type = negotiate(request)
+  const format = formats[type]
+  const buf = format.encode(body)
+
+  // content-length and etag are set by Express
+  response.set('content-type', type)
+
+  return buf
+}
+
+function negotiate (request: Request): string {
+  const negotiator = new Negotiator(request)
+  const mediaType = negotiator.mediaType(types)
+
+  if (mediaType === undefined) throw new NotAcceptable()
+
+  return mediaType
+}
+
+interface Message {
+  body: any
+}
+
+export interface IncomingMessage extends Message {
+  method: string
+  path: string
+  headers: IncomingHttpHeaders
+  query: Query
+}
+
+export interface OutgoingMessage {
+  status?: number
+  headers?: OutgoingHttpHeaders
+  body?: any
+}
+
+export interface Query {
+  id?: string
+  criteria?: string
+  sort?: string
+  omit?: string
+  limit?: string
+}

package/source/Mapping.ts

@@ -0,0 +1,48 @@
+import { type Parameter } from './RTD'
+import { Query } from './Query'
+import type * as http from './HTTP'
+import type * as syntax from './RTD/syntax'
+import type * as core from '@toa.io/core'
+
+export abstract class Mapping {
+  public static create (verb: string, query?: syntax.Query): Mapping {
+    if (verb === 'POST')
+      return new InputMapping()
+
+    if (query === undefined)
+      throw new Error(`Query constraints must be defined for ${verb}`)
+
+    const q = new Query(query)
+
+    return new QueryableMapping(q)
+  }
+
+  public abstract fit (input: any, qs: http.Query, parameters: Parameter[]): core.Request
+}
+
+class QueryableMapping extends Mapping {
+  private readonly query: Query
+
+  public constructor (query: Query) {
+    super()
+
+    this.query = query
+  }
+
+  public fit (input: any, qs: http.Query, parameters: Parameter[]): core.Request {
+    const query = this.query.fit(qs, parameters)
+
+    return { input, query }
+  }
+}
+
+class InputMapping extends Mapping {
+  public fit (body: any, _: unknown, parameters: Parameter[]): core.Request {
+    const input = { ...body }
+
+    for (const parameter of parameters)
+      input[parameter.name] = parameter.value
+
+    return { input }
+  }
+}

package/source/Query.test.ts

@@ -0,0 +1,37 @@
+import { Query } from './Query'
+import { type Parameter, type syntax } from './RTD'
+
+it('should combine request criteria', async () => {
+  const query: syntax.Query = {
+    criteria: 'foo==1;',
+    omit: { range: [0, 1] },
+    limit: { range: [0, 1] }
+  }
+
+  const parameters: Parameter[] = [
+    { name: 'bar', value: '2' },
+    { name: 'baz', value: '3' }
+  ]
+
+  const instance = new Query(query)
+  const result = instance.fit({ criteria: 'qux==4' }, parameters)
+
+  expect(result.criteria).toStrictEqual('(foo==1);(bar==2;baz==3);(qux==4)')
+})
+
+it('should set id parameter as query.id', async () => {
+  const query: syntax.Query = {
+    omit: { range: [0, 1] },
+    limit: { range: [0, 1] }
+  }
+
+  const id = '87782631058445da81cb82f78b20c223'
+
+  const parameters: Parameter[] = [{ name: 'id', value: id }]
+
+  const instance = new Query(query)
+  const result = instance.fit({}, parameters)
+
+  expect(result.criteria).toBeUndefined()
+  expect(result.id).toStrictEqual(id)
+})

package/source/Query.ts

@@ -0,0 +1,105 @@
+import * as http from './HTTP'
+import { type Parameter } from './RTD'
+import * as schemas from './schemas'
+import type * as syntax from './RTD/syntax'
+import type * as core from '@toa.io/core'
+
+export class Query {
+  private readonly query: syntax.Query
+  private readonly closed: boolean = false
+
+  public constructor (query: syntax.Query) {
+    if (query.criteria !== undefined) {
+      const open = query.criteria[query.criteria.length - 1] === ';'
+
+      if (open) query.criteria = query.criteria.slice(0, -1)
+      else this.closed = true
+    }
+
+    this.query = query
+  }
+
+  public fit (query: http.Query, parameters: Parameter[]): core.Query {
+    const error = schemas.querystring.fit(query)
+
+    if (error !== null)
+      throw new http.BadRequest('Query ' + error.message)
+
+    this.fitCriteria(query, parameters)
+    this.fitRanges(query)
+    this.fitSort(query)
+
+    return query as core.Query
+  }
+
+  private fitCriteria (query: http.Query, parameters: Parameter[]): void {
+    const criteria: string[] = []
+
+    if (this.query.criteria !== undefined)
+      criteria.push(this.query.criteria)
+
+    const idx = parameters.findIndex((parameter) => parameter.name === 'id')
+
+    if (idx !== -1) {
+      query.id = parameters[idx].value
+
+      parameters.splice(idx, 1)
+    }
+
+    if (parameters.length > 0) {
+      const chunks = parameters
+        .map(({ name, value }) => `${name}==${value}`)
+        .join(';')
+
+      criteria.push(chunks)
+    }
+
+    if (query.criteria !== undefined)
+      if (this.closed) throw new http.BadRequest('Query criteria is closed.')
+      else criteria.push(query.criteria)
+
+    switch (criteria.length) {
+      case 0:
+        break
+      case 1:
+        query.criteria = criteria[0]
+        break
+      default:
+        query.criteria = '(' + criteria.join(');(') + ')'
+        break
+    }
+  }
+
+  private fitRanges (qs: http.Query): void {
+    const query = qs as core.Query
+
+    if (qs.limit !== undefined)
+      query.limit = fit(qs.limit, this.query.limit.range, 'limit')
+    else
+      query.limit = this.query.limit.value
+
+    if (qs.omit !== undefined)
+      query.omit = fit(qs.omit, this.query.omit.range, 'omit')
+  }
+
+  private fitSort (qs: http.Query): void {
+    const query = qs as core.Query
+
+    if (qs.sort === undefined && this.query.sort === undefined)
+      return
+
+    const sort = (this.query.sort ?? '') + (qs.sort ?? '')
+
+    query.sort = sort.split(';')
+  }
+}
+
+function fit (string: string, range: [number, number], name: string): number {
+  const number = parseInt(string)
+
+  if (number < range[0] || number > range[1])
+    throw new http.BadRequest(`Query ${name} must be between ` +
+      `${range[0]} and ${range[1]} inclusive.`)
+
+  return number
+}

package/source/RTD/Context.ts

@@ -0,0 +1,16 @@
+import { type Directives, type DirectivesFactory } from './Directives'
+import { type Endpoint, type EndpointsFactory } from './Endpoint'
+
+export interface Context<
+  TEndpoint extends Endpoint = any,
+  TDirectives extends Directives<TDirectives> = any,
+  TExtension = any
+> {
+  readonly protected: boolean
+  readonly endpoints: EndpointsFactory<TEndpoint>
+  readonly directives: {
+    readonly factory: DirectivesFactory
+    stack: TDirectives[]
+  }
+  readonly extension?: TExtension
+}

package/source/RTD/Directives.ts

@@ -0,0 +1,9 @@
+import type * as syntax from './syntax'
+
+export interface Directives<T = any> {
+  merge: (directive: T) => void
+}
+
+export interface DirectivesFactory<T = any> {
+  create: (directives: syntax.Directive[]) => T
+}

package/source/RTD/Endpoint.ts

@@ -0,0 +1,11 @@
+import { type Context } from './Context'
+import type * as syntax from './syntax'
+
+export interface Endpoint<T extends Endpoint = any> {
+  call: T['call']
+  close: () => Promise<void>
+}
+
+export interface EndpointsFactory<T extends Endpoint<T> = any> {
+  create: (method: syntax.Method, context: Context) => T
+}

package/source/RTD/Match.ts

@@ -0,0 +1,16 @@
+import { type Node } from './Node'
+import { type Directives } from './Directives'
+import { type Endpoint } from './Endpoint'
+
+export interface Match<
+  TEndpoint extends Endpoint<TEndpoint> = any,
+  TDirectives extends Directives<TDirectives> = any
+> {
+  node: Node<TEndpoint, TDirectives>
+  parameters: Parameter[]
+}
+
+export interface Parameter {
+  name: string
+  value: string
+}

package/source/RTD/Method.ts

@@ -0,0 +1,24 @@
+import { type Directives } from './Directives'
+import { type Endpoint } from './Endpoint'
+
+export class Method<
+  TEndpoint extends Endpoint<TEndpoint> = any,
+  TDirectives extends Directives<TDirectives> = any
+> {
+  public readonly endpoint: TEndpoint | null
+  public readonly directives: TDirectives
+
+  public constructor (endpoint: TEndpoint | null, directives: TDirectives) {
+    this.endpoint = endpoint
+    this.directives = directives
+  }
+
+  public async close (): Promise<void> {
+    await this.endpoint?.close()
+  }
+}
+
+export type Methods<
+  TEndpoint extends Endpoint<TEndpoint> = any,
+  TDirectives extends Directives<TDirectives> = any
+> = Record<string, Method<TEndpoint, TDirectives>>

package/source/RTD/Node.ts

@@ -0,0 +1,85 @@
+import { type Route } from './Route'
+import { type Methods } from './Method'
+import { type Parameter } from './Match'
+import { type Directives } from './Directives'
+import { type Endpoint } from './Endpoint'
+
+export class Node<
+  TEndpoint extends Endpoint<TEndpoint> = any,
+  TDirectives extends Directives<TDirectives> = any
+> {
+  public intermediate: boolean
+  public methods: Methods<TEndpoint, TDirectives>
+  private readonly protected: boolean
+  private routes: Route[]
+
+  public constructor
+  (routes: Route[], methods: Methods<TEndpoint, TDirectives>, properties: Properties) {
+    this.routes = routes
+    this.methods = methods
+    this.protected = properties.protected
+    this.intermediate = this.routes.findIndex((route) => route.root) !== -1
+
+    this.sort()
+  }
+
+  public match (fragments: string[], parameters: Parameter[]): Node<TEndpoint, TDirectives> | null {
+    for (const route of this.routes) {
+      const node = route.match(fragments, parameters)
+
+      if (node !== null)
+        return node
+    }
+
+    return null
+  }
+
+  public merge (node: Node<TEndpoint, TDirectives>): void {
+    this.intermediate = node.intermediate
+
+    if (!this.protected) this.replace(node)
+    else this.append(node)
+
+    this.sort()
+  }
+
+  private replace (node: Node<TEndpoint, TDirectives>): void {
+    const methods = Object.values(this.methods)
+
+    this.routes = node.routes
+    this.methods = node.methods
+
+    for (const method of methods)
+      void method.close() // race condition is really unlikely
+  }
+
+  private append (node: Node<TEndpoint, TDirectives>): void {
+    for (const route of node.routes)
+      this.mergeRoute(route)
+
+    for (const [verb, method] of Object.entries(node.methods))
+      if (verb in this.methods)
+        console.warn(`Overriding of the protected method ${verb} is not permitted.`)
+      else
+        this.methods[verb] = method
+  }
+
+  private mergeRoute (candidate: Route): void {
+    for (const route of this.routes)
+      if (candidate.equals(route)) {
+        route.merge(candidate)
+
+        return
+      }
+
+    this.routes.push(candidate)
+  }
+
+  private sort (): void {
+    this.routes.sort((a, b) => a.variables - b.variables)
+  }
+}
+
+export interface Properties {
+  protected: boolean
+}

package/source/RTD/Route.ts

@@ -0,0 +1,58 @@
+import { type Node } from './Node'
+import { type Segment } from './segment'
+import { type Parameter } from './Match'
+
+export class Route {
+  public readonly root: boolean
+  public readonly variables: number = 0
+  private readonly segments: Segment[]
+  private readonly node: Node
+
+  public constructor (segments: Segment[], node: Node) {
+    this.root = segments.length === 0
+    this.segments = segments
+    this.node = node
+
+    for (const segment of segments)
+      if (segment.fragment === null)
+        this.variables++
+  }
+
+  public match (fragments: string[], parameters: Parameter[]): Node | null {
+    for (let i = 0; i < this.segments.length; i++) {
+      const segment = this.segments[i]
+
+      if (segment.fragment !== null && segment.fragment !== fragments[i])
+        return null
+
+      if (segment.fragment === null)
+        parameters.push({ name: segment.placeholder, value: fragments[i] })
+    }
+
+    const exact = this.segments.length === fragments.length
+
+    if (exact && !this.node.intermediate) return this.node
+    else return this.matchNested(fragments, parameters)
+  }
+
+  public equals (route: Route): boolean {
+    if (route.segments.length !== this.segments.length)
+      return false
+
+    for (let i = 0; i < this.segments.length; i++)
+      if (this.segments[i].fragment !== route.segments[i].fragment)
+        return false
+
+    return true
+  }
+
+  public merge (route: Route): void {
+    this.node.merge(route.node)
+  }
+
+  private matchNested (fragments: string[], parameters: Parameter[]): Node | null {
+    fragments = fragments.slice(this.segments.length)
+
+    return this.node.match(fragments, parameters)
+  }
+}

package/source/RTD/Tree.ts

@@ -0,0 +1,57 @@
+import { type Node } from './Node'
+import { createNode } from './factory'
+import { fragment } from './segment'
+import { type Match, type Parameter } from './Match'
+import { type Context } from './Context'
+import { type Directives, type DirectivesFactory } from './Directives'
+import { type Endpoint, type EndpointsFactory } from './Endpoint'
+import type * as syntax from './syntax'
+
+export class Tree<
+  TEndpoint extends Endpoint<TEndpoint> = any,
+  TDirectives extends Directives<TDirectives> = any
+> {
+  private readonly root: syntax.Node
+  private readonly trunk: Node<TEndpoint, TDirectives>
+  private readonly endpoints: EndpointsFactory<TEndpoint>
+  private readonly directives: DirectivesFactory
+
+  public constructor
+  (node: syntax.Node, endpoints: EndpointsFactory, directives: DirectivesFactory) {
+    this.endpoints = endpoints
+    this.directives = directives
+    this.trunk = this.createNode(node, PROTECTED)
+    this.root = node
+  }
+
+  public match (path: string): Match<TEndpoint, TDirectives> | null {
+    const fragments = fragment(path)
+    const parameters: Parameter[] = []
+    const node = this.trunk.match(fragments, parameters)
+
+    if (node === null) return null
+    else return { node, parameters }
+  }
+
+  public merge (node: syntax.Node, extension: any): void {
+    const branch = this.createNode(node, !PROTECTED, extension)
+
+    this.trunk.merge(branch)
+  }
+
+  private createNode (node: syntax.Node, protect: boolean, extension?: any): Node {
+    const context: Context = {
+      protected: protect,
+      endpoints: this.endpoints,
+      directives: {
+        factory: this.directives,
+        stack: this.root?.directives ?? []
+      },
+      extension
+    }
+
+    return createNode(node, context)
+  }
+}
+
+const PROTECTED = true