@toa.io/extensions.exposition 0.20.0-dev.9 → 0.20.0

package/source/RTD/Tree.ts

@@ -0,0 +1,54 @@
+import { type Node } from './Node'
+import { createNode } from './factory'
+import { fragment } from './segment'
+import { type Match } 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)
+
+    return this.trunk.match(fragments)
+  }
+
+  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

package/source/RTD/factory.ts

@@ -0,0 +1,47 @@
+import { Node, type Properties } from './Node'
+import { Route } from './Route'
+import { type Context } from './Context'
+import { segment } from './segment'
+import { Method, type Methods } from './Method'
+import { type Endpoint } from './Endpoint'
+import { type Directives } from './Directives'
+import type * as syntax from './syntax'
+
+export function createNode<TEndpoint extends Endpoint, TDirectives extends Directives>
+(node: syntax.Node, context: Context): Node<TEndpoint, TDirectives> {
+  if (node.isolated === true)
+    context.directives.stack = node.directives
+  else
+    context.directives.stack = node.directives.concat(context.directives.stack)
+
+  const routes: Route[] = node.routes.map((route) => createRoute(route, context))
+  const methods: Methods = {}
+
+  for (const method of node.methods)
+    methods[method.verb] = createMethod(method, context)
+
+  const properties: Properties = { protected: node.protected ?? context.protected }
+
+  return new Node(routes, methods, properties)
+}
+
+function createRoute (route: syntax.Route, context: Context): Route {
+  const stack = context.directives.stack.slice()
+  const segments = segment(route.path)
+  const node = createNode(route.node, context)
+
+  context.directives.stack = stack // restore
+
+  return new Route(segments, node)
+}
+
+function createMethod (method: syntax.Method, context: Context): Method {
+  const stack = context.directives.stack.concat(method.directives.reverse())
+  const directives = context.directives.factory.create(stack)
+
+  const endpoint = method.mapping?.endpoint === undefined
+    ? null
+    : context.endpoints.create(method, context)
+
+  return new Method(endpoint, directives)
+}

package/source/RTD/index.ts

@@ -0,0 +1,8 @@
+export * from './Tree'
+export * from './Node'
+export * from './Match'
+export * from './Method'
+export * from './Context'
+export * from './Endpoint'
+export * from './Directives'
+export * as syntax from './syntax'

package/source/RTD/segment.test.ts

@@ -0,0 +1,32 @@
+import { segment, fragment } from './segment'
+
+it('should return segments', async () => {
+  const segments = segment('/foo/bar/')
+
+  expect(segments).toHaveLength(2)
+  expect(segments[0].fragment).toBe('foo')
+  expect(segments[1].fragment).toBe('bar')
+})
+
+it('should parse placeholders', async () => {
+  const segments = segment('/foo/:id/')
+
+  expect(segments).toHaveLength(2)
+  expect(segments[0].fragment).toBe('foo')
+  expect(segments[1].fragment).toBeNull()
+
+  // helping typescript
+  if (segments[1].fragment !== null) throw new Error('?')
+
+  expect(segments[1].placeholder).toBe('id')
+})
+
+it('should handle root path', async () => {
+  expect(segment('/')).toStrictEqual([])
+})
+
+it('should split', async () => {
+  const parts = fragment('/foo/bar/')
+
+  expect(parts).toStrictEqual(['foo', 'bar'])
+})

package/source/RTD/segment.ts

@@ -0,0 +1,25 @@
+export function segment (path: string): Segment[] {
+  return fragment(path).map(parse)
+}
+
+export function fragment (path: string): string[] {
+  const parts = path.split('/')
+
+  // trailing slash
+  if (parts[parts.length - 1] === '') parts.length--
+
+  // leading slash
+  return parts.splice(1)
+}
+
+function parse (segment: string): Segment {
+  if (segment[0] === ':') return { fragment: null, placeholder: segment.substring(1) }
+  else return { fragment: segment }
+}
+
+export type Segment = {
+  fragment: string
+} | {
+  fragment: null
+  placeholder: string
+}

package/source/RTD/syntax/index.ts

@@ -0,0 +1,2 @@
+export * from './parse'
+export * from './types'

package/source/RTD/syntax/parse.test.ts

@@ -0,0 +1,188 @@
+import { parse } from './parse'
+
+describe('routes', () => {
+  it('should parse route', async () => {
+    const declaration = {
+      '/': {},
+      '/foo': {}
+    }
+
+    const node = parse(declaration)
+
+    expect(node.routes).toHaveLength(2)
+    expect(node.routes[0].path).toBe('/')
+    expect(node.routes[1].path).toBe('/foo')
+  })
+
+  it('should parse nested routes', async () => {
+    const declaration = {
+      '/': {
+        '/foo': {},
+        '/bar': {}
+      }
+    }
+
+    const node = parse(declaration)
+    const root = node.routes[0].node
+
+    expect(root.routes).toHaveLength(2)
+    expect(root.routes[0].path).toBe('/foo')
+    expect(root.routes[1].path).toBe('/bar')
+  })
+})
+
+describe('methods', () => {
+  it('should parse methods', () => {
+    const declaration = {
+      '/': {
+        GET: {
+          endpoint: 'observe'
+        }
+      }
+    }
+
+    const node = parse(declaration)
+    const root = node.routes[0].node
+
+    expect(root.methods).toHaveLength(1)
+    expect(root.methods[0].verb).toBe('GET')
+    expect(root.methods[0].mapping).toMatchObject({ endpoint: 'observe' })
+  })
+
+  it('should parse endpoint shortcut', async () => {
+    const declaration = {
+      '/': {
+        GET: 'observe'
+      }
+    }
+
+    const node = parse(declaration)
+    const root = node.routes[0].node
+
+    expect(root.methods).toHaveLength(1)
+    expect(root.methods[0].verb).toBe('GET')
+    expect(root.methods[0].mapping).toMatchObject({ endpoint: 'observe' })
+  })
+
+  it('should parse fq endpoint', async () => {
+    const declaration = {
+      '/': {
+        GET: 'dummies.dummy.observe'
+      }
+    }
+
+    const node = parse(declaration)
+    const root = node.routes[0].node
+
+    expect(root.methods).toHaveLength(1)
+    expect(root.methods[0].verb).toBe('GET')
+
+    expect(root.methods[0].mapping).toMatchObject({
+      namespace: 'dummies',
+      component: 'dummy',
+      endpoint: 'observe'
+    })
+  })
+
+  it('should parse fq endpoint within default namespace', async () => {
+    const declaration = {
+      '/': {
+        GET: 'dummy.observe'
+      }
+    }
+
+    const node = parse(declaration)
+    const root = node.routes[0].node
+
+    expect(root.methods).toHaveLength(1)
+    expect(root.methods[0].verb).toBe('GET')
+
+    expect(root.methods[0].mapping).toMatchObject({
+      namespace: 'default',
+      component: 'dummy',
+      endpoint: 'observe'
+    })
+  })
+
+  it('should parse directives', async () => {
+    const declaration = {
+      '/': {
+        GET: {
+          'auth:incept': 'id',
+          endpoint: 'observe'
+        }
+      }
+    }
+
+    const node = parse(declaration)
+    const root = node.routes[0].node
+
+    expect(root.methods[0].directives)
+      .toStrictEqual([{ family: 'auth', name: 'incept', value: 'id' }])
+  })
+})
+
+describe('directives', () => {
+  it('should parse shortcuts', async () => {
+    const declaration = {
+      '/': {
+        foo: 'baz'
+      }
+    }
+
+    const shortcuts = new Map<string, string>([
+      ['foo', 'dev:foo']
+    ])
+
+    const node = parse(declaration, shortcuts)
+    const root = node.routes[0].node
+
+    expect(root.directives).toHaveLength(1)
+    expect(root.directives[0].family).toBe('dev')
+    expect(root.directives[0].name).toBe('foo')
+    expect(root.directives[0].value).toBe('baz')
+  })
+})
+
+describe('validation', () => {
+  it('should throw on unknown key', async () => {
+    const declaration = { hello: 'world' }
+
+    expect(() => parse(declaration)).toThrow('RTD parse error: unknown key \'hello\'.')
+  })
+
+  it('should throw on invalid mapping', async () => {
+    const declaration = {
+      '/': {
+        GET: {
+          endpoint: 'observe',
+          hello: 'world'
+        }
+      }
+    }
+
+    expect(() => parse(declaration)).toThrow('/methods/0/mapping')
+  })
+})
+
+it('should expand ranges', async () => {
+  const declaration = {
+    '/': {
+      GET: {
+        endpoint: 'enumerate',
+        query: {
+          omit: 3,
+          limit: 2
+        }
+      }
+    }
+  }
+
+  const node = parse(declaration)
+  const query = node.routes[0].node.methods[0].mapping?.query
+
+  expect(query).toMatchObject({
+    omit: { value: 3, range: [3, 3] },
+    limit: { value: 2, range: [2, 2] }
+  })
+})

package/source/RTD/syntax/parse.ts

@@ -0,0 +1,153 @@
+import * as schemas from '../../schemas'
+import {
+  verbs,
+  type Node,
+  type Route,
+  type Method,
+  type Mapping,
+  type Directive, type Range
+} from './types'
+
+export function parse (input: object, shortcuts?: Shortcuts): Node {
+  const node = parseNode(input, shortcuts)
+
+  schemas.node.validate(node)
+
+  return node
+}
+
+function parseNode (input: object, shortcuts?: Shortcuts): Node {
+  const node = createNode()
+
+  for (const [key, value] of Object.entries(input)) {
+    if (PROPERTIES.includes(key as keyof Node)) {
+      node[key as keyof Node] = value
+
+      continue
+    }
+
+    if (key[0] === '/') {
+      const route = parseRoute(key, value, shortcuts)
+
+      node.routes.push(route)
+
+      continue
+    }
+
+    if (verbs.has(key)) {
+      const method = parseMethod(key, value, shortcuts)
+
+      node.methods.push(method)
+
+      continue
+    }
+
+    const directive = parseDirective(key, value, shortcuts)
+
+    if (directive !== null) {
+      node.directives.push(directive)
+
+      continue
+    }
+
+    throw new Error(`RTD parse error: unknown key '${key}'.`)
+  }
+
+  return node
+}
+
+export function createNode (): Node {
+  return {
+    routes: [],
+    methods: [],
+    directives: []
+  }
+}
+
+function parseRoute (path: string, value: object, shortcuts?: Shortcuts): Route {
+  const node = parse(value, shortcuts)
+
+  return createRoute(path, node)
+}
+
+function createRoute (path: string, node: Node): Route {
+  return { path, node }
+}
+
+function parseMethod (verb: string, value: Mapping | string, shortcuts?: Shortcuts): Method {
+  const mapping = typeof value === 'string' ? { endpoint: value } : value
+
+  parseEndpoint(mapping)
+  parseQuery(mapping)
+
+  const directives = parseDirectives(mapping, shortcuts)
+
+  return { verb, mapping, directives }
+}
+
+function parseEndpoint (mapping: Mapping): void {
+  if (mapping.endpoint === undefined)
+    return
+
+  const [endpoiont, component, namespace] = mapping.endpoint.split('.').reverse()
+
+  if (component !== undefined) {
+    mapping.component = component
+    mapping.namespace = namespace ?? mapping.namespace ?? 'default'
+    mapping.endpoint = endpoiont
+  }
+}
+
+function parseQuery (mapping: any): void {
+  const query = mapping.query
+
+  if (query === undefined || query === null)
+    return
+
+  if (typeof query.limit === 'number')
+    query.limit = expandRange(query.limit)
+
+  if (typeof query.omit === 'number')
+    query.omit = expandRange(query.omit)
+}
+
+function parseDirectives (mapping: Record<string, any>, shortcuts?: Shortcuts): Directive[] {
+  const directives: Directive[] = []
+
+  for (const [key, value] of Object.entries(mapping)) {
+    const directive = parseDirective(key, value, shortcuts)
+
+    if (directive === null)
+      continue
+
+    directives.push(directive)
+
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    delete mapping[key]
+  }
+
+  return directives
+}
+
+function parseDirective (key: string, value: any, shortcuts?: Shortcuts): Directive | null {
+  if (shortcuts?.has(key) === true)
+    key = shortcuts.get(key) as string
+
+  const match = key.match(DIRECTIVE_RX)
+
+  if (match === null)
+    return null
+
+  const { family, name } = match.groups as { family: string, name: string }
+
+  return { family, name, value }
+}
+
+function expandRange (range: number): Range {
+  return { value: range, range: [range, range] }
+}
+
+const DIRECTIVE_RX = /^(?<family>\w{1,32}):(?<name>\w{1,32})$/
+const PROPERTIES: Array<keyof Node> = ['protected', 'isolated']
+
+export type Shortcuts = Map<string, string>

package/source/RTD/syntax/types.ts

@@ -0,0 +1,48 @@
+export interface Node {
+  protected?: boolean
+  isolated?: boolean
+  routes: Route[]
+  methods: Method[]
+  directives: Directive[]
+}
+
+export interface Route {
+  path: string
+  node: Node
+}
+
+export interface Method {
+  verb: string
+  mapping?: Mapping
+  directives: Directive[]
+}
+
+export interface Directive {
+  family: string
+  name: string
+  value: any
+}
+
+export interface Mapping {
+  namespace?: string
+  component?: string
+  endpoint: string
+  query?: Query
+}
+
+export interface Query {
+  id?: string
+  criteria?: string
+  sort?: string
+  omit: Range
+  limit: Range
+  selectors?: string[]
+  projection?: string[]
+}
+
+export interface Range {
+  value?: number
+  range: [number, number]
+}
+
+export const verbs = new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])

package/source/Remotes.test.ts

@@ -0,0 +1,42 @@
+import { generate } from 'randomstring'
+import { Connector } from '@toa.io/core'
+import { Remotes } from './Remotes'
+import type { Bootloader } from './Factory'
+import type { Locator } from '@toa.io/core'
+
+jest.mock('@toa.io/boot', () => ({
+  remote: async (locator: Locator) => await boot.remote(locator)
+}))
+
+const boot = {
+  remote: jest.fn(async (..._) => ({
+    connect: jest.fn(() => undefined),
+    link: jest.fn(() => undefined)
+  }))
+} as unknown as jest.MockedObjectDeep<Bootloader>
+
+const namespace = generate()
+const name = generate()
+
+let remotes: Remotes
+
+beforeEach(() => {
+  remotes = new Remotes(boot)
+})
+
+it('should create remote', async () => {
+  const remote = await remotes.discover(namespace, name)
+
+  expect(boot.remote).toHaveBeenCalledWith(expect.objectContaining({ namespace, name }))
+  expect(remote).toStrictEqual(await boot.remote.mock.results[0].value)
+})
+
+it('should be instance of Connector', async () => {
+  expect(remotes).toBeInstanceOf(Connector)
+})
+
+it('should depend on created remotes', async () => {
+  const remote = await remotes.discover(namespace, name)
+
+  expect(remote.link).toHaveBeenCalledWith(remotes)
+})

package/source/Remotes.ts

@@ -0,0 +1,22 @@
+import { Locator, Connector, type Component } from '@toa.io/core'
+import { type Bootloader } from './Factory'
+
+export class Remotes extends Connector {
+  private readonly boot: Bootloader
+
+  public constructor (boot: Bootloader) {
+    super()
+    this.boot = boot
+  }
+
+  public async discover (namespace: string, name: string): Promise<Component> {
+    const locator = new Locator(name, namespace)
+    const remote = await this.boot.remote(locator)
+
+    this.depends(remote)
+
+    await remote.connect()
+
+    return remote
+  }
+}

package/source/Tenant.ts

@@ -0,0 +1,38 @@
+import { Connector, type Locator, type bindings } from '@toa.io/core'
+import { type Label } from './discovery'
+import { type Branch } from './Branch'
+import type * as RTD from './RTD/syntax'
+
+export class Tenant extends Connector {
+  private readonly broadcast: Broadcast
+  private readonly branch: Branch
+
+  public constructor (broadcast: Broadcast, locator: Locator, node: RTD.Node) {
+    super()
+
+    this.broadcast = broadcast
+
+    this.branch = {
+      namespace: locator.namespace,
+      component: locator.name,
+      isolated: locator.namespace === 'identity',
+      node
+    }
+
+    this.depends(broadcast)
+  }
+
+  public override async open (): Promise<void> {
+    await this.expose()
+    await this.broadcast.receive('ping', this.expose.bind(this))
+
+    console.info('Exposition Tenant for ' +
+      `'${this.branch.namespace}.${this.branch.component}' has started.`)
+  }
+
+  private async expose (): Promise<void> {
+    await this.broadcast.transmit('expose', this.branch)
+  }
+}
+
+type Broadcast = bindings.Broadcast<Label>