@toa.io/extensions.exposition 1.0.0-alpha.31 → 1.0.0-alpha.310

package/schemas/octets/store.cos.yaml

@@ -1,3 +0,0 @@
-accept+: string
-workflow+: <string>
-_: true

package/schemas/query.cos.yaml

@@ -1,17 +0,0 @@
-_: true
-id?: string
-criteria?: string
-sort?: string
-omit:
-  $ref: range
-  default:
-    value: 0
-    range: [0, 1000]
-limit:
-  $ref: range
-  default:
-    value: 10
-    range: [1, 1000]
-  required: [value]
-selectors?: [string]
-projection?: [string]

package/schemas/querystring.cos.yaml

@@ -1,6 +0,0 @@
-id: string
-criteria: string
-sort: string
-omit: number
-limit: number
-version: number

package/schemas/range.cos.yaml

@@ -1,2 +0,0 @@
-value?: number
-range: [number]

package/schemas/route.cos.yaml

@@ -1,2 +0,0 @@
-path: string
-node: ref:node

package/source/Annotation.ts

@@ -1,8 +0,0 @@
-export interface Annotation {
-  authorities: Record<string, string>
-  class?: string
-  annotations?: Record<string, string>
-  debug?: boolean
-  trace?: boolean
-  '/'?: object // parsed and validated by RTD.syntax.parse
-}

package/source/Branch.ts

@@ -1,8 +0,0 @@
-import type * as RTD from './RTD/syntax'
-
-export interface Branch {
-  namespace: string
-  component: string
-  isolated: boolean
-  node: RTD.Node
-}

package/source/Composition.ts

@@ -1,57 +0,0 @@
-import { readdirSync, type Dirent } from 'node:fs'
-import { resolve } from 'node:path'
-import { Connector } from '@toa.io/core'
-import { type Bootloader } from './Factory'
-
-export class Composition extends Connector {
-  private readonly boot: Bootloader
-
-  public constructor (boot: Bootloader) {
-    super()
-    this.boot = boot
-  }
-
-  protected override async open (): Promise<void> {
-    const paths = find()
-    const composition = await this.boot.composition(paths)
-
-    await composition.connect()
-
-    this.depends(composition)
-
-    console.info('Composition complete.')
-  }
-
-  protected override dispose (): void {
-    console.info('Composition shutdown complete.')
-  }
-}
-
-function find (): string[] {
-  return entries().map((entry) => resolve(ROOT, entry.name))
-}
-
-function entries (): Dirent[] {
-  const entries = readdirSync(ROOT, { withFileTypes: true })
-
-  return entries.filter((entry) => entry.isDirectory())
-}
-
-export function components (): Components {
-  const labels: string[] = []
-  const paths: string[] = []
-
-  for (const entry of entries()) {
-    labels.push(entry.name.replace('.', '-'))
-    paths.push(resolve(ROOT, entry.name))
-  }
-
-  return { labels, paths }
-}
-
-interface Components {
-  labels: string[]
-  paths: string[]
-}
-
-const ROOT = resolve(__dirname, '../components/')

package/source/Context.ts

@@ -1,8 +0,0 @@
-import type * as RTD from './RTD'
-
-export type Context = RTD.Context<Extension>
-
-interface Extension {
-  namespace: string
-  component: string
-}

package/source/Directive.test.ts

@@ -1,97 +0,0 @@
-import assert from 'node:assert'
-import { generate } from 'randomstring'
-import { DirectivesFactory } from './Directive'
-import type { syntax, DirectiveFamily } from './RTD'
-import type { Remotes } from './Remotes'
-import type { Context } from './HTTP'
-
-const families: Array<jest.MockedObjectDeep<DirectiveFamily>> = [
-  {
-    name: 'foo',
-    mandatory: true,
-    create: jest.fn((_0: any, _1: any, _2: any) => generate() as any),
-    preflight: jest.fn(),
-    settle: jest.fn()
-  },
-  {
-    name: 'bar',
-    mandatory: false,
-    create: jest.fn((_0: string, _1: any, _2: any) => generate() as any),
-    preflight: jest.fn(),
-    settle: jest.fn()
-  }
-]
-
-let factory: DirectivesFactory
-
-beforeEach(() => {
-  jest.clearAllMocks()
-
-  assert.ok(families[0].preflight !== undefined)
-  assert.ok(families[1].preflight !== undefined)
-
-  families[0].preflight.mockImplementation(() => null)
-  families[1].preflight.mockImplementation(() => null)
-  factory = new DirectivesFactory(families, {} as unknown as Remotes)
-})
-
-it('should create directive', async () => {
-  const declarations: syntax.Directive[] = [
-    {
-      family: 'foo',
-      name: generate(),
-      value: generate()
-    },
-    {
-      family: 'bar',
-      name: generate(),
-      value: generate()
-    }
-  ]
-
-  factory.create(declarations)
-
-  for (let i = 0; i < declarations.length; i++) {
-    expect(families[i].create.mock.calls[0][0]).toBe(declarations[i].name)
-    expect(families[i].create.mock.calls[0][1]).toBe(declarations[i].value)
-  }
-})
-
-it('should throw error if directive family is not found', async () => {
-  const declaration: syntax.Directive = {
-    family: generate(),
-    name: generate(),
-    value: generate()
-  }
-
-  expect(() => factory.create([declaration]))
-    .toThrowError(`Directive family '${declaration.family}' is not found.`)
-})
-
-it('should apply directive', async () => {
-  const declaration: syntax.Directive = {
-    family: 'foo',
-    name: generate(),
-    value: generate()
-  }
-
-  const directives = factory.create([declaration])
-  const request = generate() as unknown as Context
-  const directive = families[0].create.mock.results[0].value
-
-  await directives.preflight(request, [])
-
-  assert.ok(families[0].preflight !== undefined)
-
-  expect(families[0].preflight.mock.calls[0][0]).toStrictEqual([directive])
-  expect(families[0].preflight.mock.calls[0][1]).toEqual(request)
-})
-
-it('should apply mandatory families', async () => {
-  const directives = factory.create([])
-  const request = generate() as unknown as Context
-
-  await directives.preflight(request, [])
-
-  expect(families[0].preflight).toHaveBeenCalled()
-})

package/source/Directive.ts

@@ -1,96 +0,0 @@
-import type { Context, 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 {
-  private readonly sets: RTD.DirectiveSet[]
-
-  public constructor (sets: RTD.DirectiveSet[]) {
-    this.sets = sets
-  }
-
-  public async preflight (context: Context, parameters: RTD.Parameter[]): Promise<Output> {
-    for (const set of this.sets) {
-      if (set.family.preflight === undefined)
-        continue
-
-      const output = await set.family.preflight(set.directives, context, parameters)
-
-      if (output !== null)
-        return output
-    }
-
-    return null
-  }
-
-  public async settle (context: Context, response: OutgoingMessage): Promise<void> {
-    for (const set of this.sets)
-      if (set.family.settle !== undefined)
-        await set.family.settle(set.directives, context, response)
-  }
-}
-
-export class DirectivesFactory implements RTD.DirectiveFactory {
-  private readonly remotes: Remotes
-  private readonly families: Record<string, RTD.DirectiveFamily> = {}
-  private readonly mandatory: string[] = []
-
-  public constructor (families: RTD.DirectiveFamily[], remotes: Remotes) {
-    for (const family of families) {
-      this.families[family.name] = family
-
-      if (family.mandatory)
-        this.mandatory.push(family.name)
-    }
-
-    this.remotes = remotes
-  }
-
-  public create (declarations: RTD.syntax.Directive[]): Directives {
-    const groups: Record<string, any> = {}
-    const mandatory = new Set(this.mandatory)
-
-    declarations.sort((a, b) =>
-      (mandatory.has(b.family) ? 1 : 0) - (mandatory.has(a.family) ? 1 : 0))
-
-    for (const declaration of declarations) {
-      const family = this.families[declaration.family]
-
-      if (family === undefined)
-        throw new Error(`Directive family '${declaration.family}' is not found.`)
-
-      const directive = family.create(declaration.name, declaration.value, this.remotes)
-
-      groups[family.name] ??= []
-      groups[family.name].push(directive)
-      mandatory.delete(family.name)
-    }
-
-    const sets: RTD.DirectiveSet[] = []
-
-    for (const family of mandatory)
-      sets.push({
-        family: this.families[family],
-        directives: []
-      })
-
-    for (const [family, directives] of Object.entries(groups))
-      sets.push({
-        family: this.families[family],
-        directives
-      })
-
-    return new Directives(sets)
-  }
-}
-
-export const shortcuts: RTD.syntax.Shortcuts = new Map([
-  ['anonymous', 'auth:anonymous'],
-  ['id', 'auth:id'],
-  ['role', 'auth:role'],
-  ['rule', 'auth:rule'],
-  ['incept', 'auth:incept'],
-  ['input', 'io:input'],
-  ['output', 'io:output']
-])

package/source/Endpoint.ts

@@ -1,108 +0,0 @@
-import { type Component } from '@toa.io/core'
-import { type Remotes } from './Remotes'
-import { Mapping } from './Mapping'
-import { type Context } from './Context'
-import * as http from './HTTP'
-import type * as RTD from './RTD'
-
-export class Endpoint implements RTD.Endpoint {
-  private readonly endpoint: string
-  private readonly mapping: Mapping
-  private readonly discovery: Promise<Component>
-  private remote: Component | null = null
-
-  public constructor (endpoint: string, mapping: Mapping, discovery: Promise<Component>) {
-    this.endpoint = endpoint
-    this.mapping = mapping
-    this.discovery = discovery
-  }
-
-  public async call (context: http.Context, parameters: RTD.Parameter[]): Promise<http.OutgoingMessage> {
-    const body = await context.body()
-    const query = this.query(context)
-    const request = this.mapping.fit(body, query, parameters)
-
-    this.remote ??= await this.discovery
-
-    const reply = await this.remote.invoke(this.endpoint, request)
-
-    if (context.debug)
-      console.debug('Call', `${this.remote.locator.id}.${this.endpoint}`, request)
-
-    if (reply instanceof Error)
-      throw new http.UnprocessableEntity(reply)
-
-    const message: http.OutgoingMessage = {}
-
-    if (typeof reply === 'object' && reply !== null && '_version' in reply) {
-      const etag = context.request.headers['if-none-match']
-
-      message.headers ??= new Headers()
-
-      if (etag !== undefined && reply._version === this.version(etag)) {
-        message.status = 304
-        message.headers.set('etag', etag)
-
-        return message
-      } else
-        message.headers.set('etag', `"${reply._version.toString()}"`)
-    }
-
-    message.body = reply
-
-    return message
-  }
-
-  public async close (): Promise<void> {
-    this.remote ??= await this.discovery
-
-    await this.remote.disconnect(INTERRUPT)
-  }
-
-  private query (context: http.Context): http.Query {
-    const query: http.Query = Object.fromEntries(context.url.searchParams)
-    const etag = context.request.headers['if-match']
-
-    if (etag !== undefined)
-      query.version = this.version(etag)
-
-    return query
-  }
-
-  private version (etag: string): number {
-    const match = etag.match(ETAG)
-
-    if (match === null)
-      throw new http.BadRequest('Invalid ETag.')
-
-    return Number.parseInt(match.groups!.version)
-  }
-}
-
-export class EndpointsFactory implements RTD.EndpointsFactory {
-  private readonly remotes: Remotes
-
-  public constructor (remotes: Remotes) {
-    this.remotes = remotes
-  }
-
-  public create (method: RTD.syntax.Method, context: Context): Endpoint {
-    if (method.mapping === undefined)
-      throw new Error('Cannot create Endpoint without mapping.')
-
-    const mapping = Mapping.create(method.mapping.query)
-    const namespace = method.mapping.namespace ?? context.extension?.namespace
-    const component = method.mapping.component ?? context.extension?.component
-
-    if (namespace === undefined || component === undefined)
-      throw new Error('Annotation endpoints must be fully qualified.')
-
-    const discovery = this.remotes.discover(namespace, component)
-
-    return new Endpoint(method.mapping.endpoint, mapping, discovery)
-  }
-}
-
-const ETAG = /^"(?<version>\d{1,32})"$/
-
-const INTERRUPT = true

package/source/Factory.ts

@@ -1,60 +0,0 @@
-import assert from 'node:assert'
-import { decode } from '@toa.io/generic'
-import { Tenant } from './Tenant'
-import { Gateway } from './Gateway'
-import { Remotes } from './Remotes'
-import { Tree, syntax } from './RTD'
-import { EndpointsFactory } from './Endpoint'
-import { families, interceptors } from './directives'
-import { DirectivesFactory } from './Directive'
-import { Composition } from './Composition'
-import * as root from './root'
-import { Interception } from './Interception'
-import * as http from './HTTP'
-import type { Broadcast } from './Gateway'
-import type { Connector, Locator, extensions } from '@toa.io/core'
-
-export class Factory implements extensions.Factory {
-  private readonly boot: Bootloader
-
-  public constructor (boot: Bootloader) {
-    this.boot = boot
-  }
-
-  public tenant (locator: Locator, node: syntax.Node): Connector {
-    const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id)
-
-    return new Tenant(broadcast, locator, node)
-  }
-
-  public service (): Connector | null {
-    assert.ok(process.env.TOA_EXPOSITION_PROPERTIES,
-      'TOA_EXPOSITION_PROPERTIES is undefined')
-
-    const options = decode<http.Options>(process.env.TOA_EXPOSITION_PROPERTIES)
-    const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL)
-    const server = http.Server.create({ ...options, methods: syntax.verbs })
-    const remotes = new Remotes(this.boot)
-    const node = root.resolve()
-    const methods = new EndpointsFactory(remotes)
-    const directives = new DirectivesFactory(families, remotes)
-    const interception = new Interception(interceptors)
-    const tree = new Tree(node, methods, directives)
-
-    const composition = new Composition(this.boot)
-    const gateway = new Gateway(broadcast, tree, interception)
-
-    gateway.depends(remotes)
-    gateway.depends(composition)
-
-    server.attach(gateway.process.bind(gateway))
-    server.depends(gateway)
-
-    return server
-  }
-}
-
-const CHANNEL = 'exposition'
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-export type Bootloader = typeof import('@toa.io/boot')

package/source/Gateway.ts

@@ -1,97 +0,0 @@
-import { type bindings, Connector } from '@toa.io/core'
-import * as http from './HTTP'
-import { rethrow } from './exceptions'
-import type { Interception } from './Interception'
-import type { Method, Parameter, Tree } from './RTD'
-import type { Label } from './discovery'
-import type { Branch } from './Branch'
-
-export class Gateway extends Connector {
-  private readonly broadcast: Broadcast
-  private readonly tree: Tree
-  private readonly interceptor: Interception
-
-  public constructor (broadcast: Broadcast, tree: Tree, interception: Interception) {
-    super()
-
-    this.broadcast = broadcast
-    this.tree = tree
-    this.interceptor = interception
-
-    this.depends(broadcast)
-  }
-
-  public async process (context: http.Context): Promise<http.OutgoingMessage> {
-    const interception = await context.timing.capture('intercept',
-      this.interceptor.intercept(context))
-
-    if (interception !== null)
-      return interception
-
-    const match = this.tree.match(context.url.pathname)
-
-    if (match === null)
-      throw new http.NotFound('Route not found')
-
-    const { node, parameters } = match
-
-    if (!(context.request.method in node.methods))
-      throw new http.MethodNotAllowed()
-
-    const method = node.methods[context.request.method]
-
-    const interruption = await context.timing.capture('preflight',
-      method.directives.preflight(context, parameters)).catch(rethrow)
-
-    const response = interruption ??
-      await context.timing.capture('call', this.call(method, context, parameters))
-
-    await context.timing.capture('settle',
-      method.directives.settle(context, response)).catch(rethrow)
-
-    return response
-  }
-
-  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 call (method: Method, context: http.Context, parameters: Parameter[]): Promise<http.OutgoingMessage> {
-    if (context.url.pathname[context.url.pathname.length - 1] !== '/')
-      throw new http.NotFound('Trailing slash is required')
-
-    if (context.encoder === null)
-      throw new http.NotAcceptable()
-
-    if (method.endpoint === null)
-      throw new http.MethodNotAllowed()
-
-    return await method.endpoint
-      .call(context, parameters)
-      .catch(rethrow) as http.OutgoingMessage
-  }
-
-  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)
-    }
-  }
-}
-
-export type Broadcast = bindings.Broadcast<Label>

package/source/HTTP/Context.ts

@@ -1,89 +0,0 @@
-import Negotiator from 'negotiator'
-import { Timing } from './Timing'
-import { type Format, formats, types } from './formats'
-import { read } from './messages'
-import type { OutgoingMessage } from './messages'
-import type * as http from 'node:http'
-
-export class Context {
-  public readonly authority: string
-  public readonly request: IncomingMessage
-  public readonly url: URL
-  public readonly subtype: string | null = null
-  public readonly encoder: Format | null = null
-  public readonly timing: Timing
-  public readonly debug: boolean
-
-  public readonly pipelines: Pipelines = {
-    body: [],
-    response: []
-  }
-
-  public constructor (authority: string, request: IncomingMessage, properties: Properties) {
-    this.authority = authority
-    this.request = request
-
-    this.url = new URL(request.url, `https://${request.headers.host}`)
-    this.timing = new Timing(properties.trace)
-    this.debug = properties.debug
-
-    if (this.debug)
-      this.log(request)
-
-    if (this.request.headers.accept !== undefined) {
-      const match = SUBTYPE.exec(this.request.headers.accept)
-
-      if (match !== null) {
-        const {
-          type,
-          subtype,
-          suffix
-        } = match.groups!
-
-        this.request.headers.accept = `${type}/${suffix}`
-        this.subtype = subtype
-      }
-    }
-
-    const negotiator = new Negotiator(this.request)
-    const mediaType = negotiator.mediaType(types)
-
-    if (mediaType !== undefined)
-      this.encoder = formats[mediaType]
-  }
-
-  public async body<T> (): Promise<T> {
-    const value = await read(this)
-
-    return this.pipelines.body.length === 0
-      ? value
-      : this.pipelines.body.reduce((value, transform) => transform(value), value)
-  }
-
-  private log (request: IncomingMessage): void {
-    const message = `${request.method} ${request.url}`
-    const { authorization, ...headers } = request.headers
-
-    if (authorization !== undefined)
-      headers.authorization = authorization.slice(0, authorization.indexOf(' '))
-
-    console.debug(message, headers)
-  }
-}
-
-export interface IncomingMessage extends http.IncomingMessage {
-  url: string
-  method: string
-}
-
-interface Pipelines {
-  body: Array<(input: unknown) => unknown>
-  response: Array<(output: OutgoingMessage) => void>
-}
-
-interface Properties {
-  debug: boolean
-  trace: boolean
-}
-
-const SUBTYPE = /^(?<type>\w{1,32})\/(vnd\.toa\.(?<subtype>\S{1,32})\+)(?<suffix>\S{1,32})$/