@toa.io/extensions.exposition 1.0.0-alpha.291 → 1.0.0-alpha.293

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

@@ -1,196 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { parse } from './parse.js'
-
-describe('routes', () => {
-  it('should parse route', async () => {
-    const declaration = {
-      '/': {},
-      '/foo': {}
-    }
-
-    const node = parse(declaration)
-
-    assert.strictEqual(node.routes.length, 2)
-    assert.strictEqual(node.routes[0].path, '/')
-    assert.strictEqual(node.routes[1].path, '/foo')
-  })
-
-  it('should parse nested routes', async () => {
-    const declaration = {
-      '/': {
-        '/foo': {},
-        '/bar': {}
-      }
-    }
-
-    const node = parse(declaration)
-    const root = node.routes[0].node
-
-    assert.strictEqual(root.routes.length, 2)
-    assert.strictEqual(root.routes[0].path, '/foo')
-    assert.strictEqual(root.routes[1].path, '/bar')
-  })
-})
-
-describe('methods', () => {
-  it('should parse methods', () => {
-    const declaration = {
-      '/': {
-        GET: {
-          endpoint: 'observe'
-        }
-      }
-    }
-
-    const node = parse(declaration)
-    const root = node.routes[0].node
-
-    assert.strictEqual(root.methods.length, 1)
-    assert.strictEqual(root.methods[0].verb, 'GET')
-    assert.partialDeepStrictEqual(root.methods[0].mapping, { endpoint: 'observe' })
-  })
-
-  it('should parse endpoint shortcut', async () => {
-    const declaration = {
-      '/': {
-        GET: 'observe'
-      }
-    }
-
-    const node = parse(declaration)
-    const root = node.routes[0].node
-
-    assert.strictEqual(root.methods.length, 1)
-    assert.strictEqual(root.methods[0].verb, 'GET')
-    assert.partialDeepStrictEqual(root.methods[0].mapping, { endpoint: 'observe' })
-  })
-
-  it('should parse fq endpoint', async () => {
-    const declaration = {
-      '/': {
-        GET: 'dummies.dummy.observe'
-      }
-    }
-
-    const node = parse(declaration)
-    const root = node.routes[0].node
-
-    assert.strictEqual(root.methods.length, 1)
-    assert.strictEqual(root.methods[0].verb, 'GET')
-
-    assert.partialDeepStrictEqual(root.methods[0].mapping, {
-      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
-
-    assert.strictEqual(root.methods.length, 1)
-    assert.strictEqual(root.methods[0].verb, 'GET')
-
-    assert.partialDeepStrictEqual(root.methods[0].mapping, {
-      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
-
-    assert.deepStrictEqual(root.methods[0].directives, [
-      { 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
-
-    assert.strictEqual(root.directives.length, 1)
-    assert.strictEqual(root.directives[0].family, 'dev')
-    assert.strictEqual(root.directives[0].name, 'foo')
-    assert.strictEqual(root.directives[0].value, 'baz')
-  })
-})
-
-describe('validation', () => {
-  it('should throw on unknown key', async () => {
-    const declaration = { hello: 'world' }
-
-    assert.throws(
-      () => parse(declaration),
-      (error: any) => /RTD parse error: unknown key 'hello'/.test(error.message)
-    )
-  })
-
-  it('should throw on invalid mapping', async () => {
-    const declaration = {
-      '/': {
-        GET: {
-          endpoint: 'observe',
-          hello: 'world'
-        }
-      }
-    }
-
-    assert.throws(
-      () => parse(declaration),
-      (error: any) => /\/methods\/0\/mapping/.test(error.message)
-    )
-  })
-})
-
-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
-
-  assert.partialDeepStrictEqual(query, {
-    omit: { value: 3, range: [3, 3] },
-    limit: { value: 2, range: [2, 2] }
-  })
-})

package/source/RTD/syntax/parse.ts

@@ -1,171 +0,0 @@
-import * as schemas from '../../schemas.js'
-import {
-  verbs,
-  type Node,
-  type Route,
-  type Method,
-  type Mapping,
-  type Directive,
-  type Range
-} from './types.js'
-
-export function parse(input: object, shortcuts?: Shortcuts): Node {
-  const node = parseNode(input, shortcuts)
-
-  schemas.node.validate(node)
-
-  return node
-}
-
-function parseNode(input: object | string, shortcuts?: Shortcuts): Node {
-  const node = createNode()
-
-  if (typeof input === 'string') {
-    node.forward = input
-
-    return node
-  }
-
-  for (const [key, value] of Object.entries(input) as Array<[keyof Node, unknown]>)
-    switch (key) {
-      case 'protected':
-      case 'isolated':
-        node[key] = value as boolean
-        break
-      case 'forward':
-        node[key] = value as string
-        break
-
-      default:
-        // eslint-disable-next-line max-depth
-        if (key[0] === '/') {
-          const route = parseRoute(key, value as Node, shortcuts)
-
-          node.routes.push(route)
-
-          continue
-        }
-
-        // eslint-disable-next-line max-depth
-        if (verbs.has(key)) {
-          const method = parseMethod(key, value as Mapping, shortcuts)
-
-          node.methods.push(method)
-
-          continue
-        }
-
-        // eslint-disable-next-line no-case-declarations
-        const directive = parseDirective(key, value, shortcuts)
-
-        // eslint-disable-next-line max-depth
-        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: Node, 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 as number)
-
-  if (typeof query.omit === 'number') query.omit = expandRange(query.omit as number)
-}
-
-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)! // eslint-disable-line @typescript-eslint/no-non-null-assertion
-
-  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})$/
-
-export type Shortcuts = Map<string, string>

package/source/RTD/syntax/types.ts

@@ -1,69 +0,0 @@
-export interface Node {
-  protected?: boolean
-  isolated?: boolean
-  forward?: string
-  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 | null
-
-  /**
-   * Whether the operation this maps to answers a page of a collection, and so takes the
-   * `omit` and `limit` a page is taken by. Written where the component's manifest is read,
-   * beside `namespace` and `component`, and not declared.
-   */
-  paged?: boolean
-}
-
-export interface Query {
-  id?: string
-  criteria?: string
-  search?: boolean
-  sample?: number
-  sort?: string
-  omit?: Range
-  limit?: Range
-  selectors?: string[]
-  projection?: string[]
-  parameters?: string[]
-  deleted?: boolean
-}
-
-export interface Range {
-  value?: number
-  range: [number, number]
-}
-
-export const verbs = new Set<string>([
-  'GET',
-  'HEAD',
-  'POST',
-  'PUT',
-  'PATCH',
-  'DELETE',
-  'LOCK',
-  'UNLOCK'
-])

package/source/RTD/walk.test.ts

@@ -1,147 +0,0 @@
-import { describe, it, mock } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Tree } from './Tree.js'
-import { address, name } from '../RPC/names.js'
-import type { EndpointsFactory } from '../Endpoint.js'
-import type { DirectiveFactory } from './Directives.js'
-import type * as syntax from './syntax/index.js'
-
-const endpoints = {} as unknown as EndpointsFactory
-
-const directives = {
-  create: () => ({
-    precall: async () => null,
-    settle: async () => undefined,
-    dispose: () => undefined
-  }),
-  dispose: mock.fn()
-} as unknown as DirectiveFactory
-
-const node = (
-  path: string,
-  verbs: string[] = [],
-  routes: syntax.Route[] = []
-): syntax.Route => ({
-  path,
-  node: {
-    routes,
-    methods: verbs.map((verb) => ({ verb, directives: [] })),
-    directives: []
-  }
-})
-
-const trunk = (routes: syntax.Route[], verbs: string[] = []): syntax.Node => ({
-  routes,
-  methods: verbs.map((verb) => ({ verb, directives: [] })),
-  directives: []
-})
-
-/** What a walk names, which is what a caller of `/.rpc` would write. */
-function names(tree: Tree): string[] {
-  return [...tree.walk()]
-    .map(({ segments, verb }) => name(segments, verb))
-    .filter((named): named is string => named !== null)
-}
-
-describe('walk', () => {
-  it('should name the trunk by its verb alone', () => {
-    const tree = new Tree(trunk([], ['GET']), endpoints, directives)
-
-    assert.deepEqual(names(tree), ['GET'])
-  })
-
-  it('should name every method of every route', () => {
-    const tree = new Tree(
-      trunk([node('/pots', ['GET', 'POST'], [node('/:id', ['GET', 'DELETE'])])]),
-      endpoints,
-      directives
-    )
-
-    assert.deepEqual(names(tree).sort(), [
-      'pots.GET',
-      'pots.POST',
-      'pots._id.DELETE',
-      'pots._id.GET'
-    ])
-  })
-
-  it('should walk a branch that was merged', () => {
-    const tree = new Tree(trunk([]), endpoints, directives)
-
-    tree.merge(trunk([node('/pots', ['GET'])]), {
-      namespace: 'default',
-      component: 'pots'
-    })
-
-    assert.deepEqual(names(tree), ['pots.GET'])
-  })
-
-  it('should name a tail', () => {
-    const tree = new Tree(
-      trunk([node('/files', [], [node('/**', ['GET'])])]),
-      endpoints,
-      directives
-    )
-
-    assert.deepEqual(names(tree), ['files.__.GET'])
-  })
-
-  it('should skip an intermediate node, whose route answers in its place', () => {
-    const tree = new Tree(
-      trunk([
-        // `/posts` is intermediate: `/posts/` is answered by its `/` route, not by itself
-        node('/posts', ['PATCH'], [node('/', ['PUT'])])
-      ]),
-      endpoints,
-      directives
-    )
-
-    assert.deepEqual(names(tree), ['posts.PUT'])
-  })
-
-  it('should name nothing where a segment cannot be spelled', () => {
-    const tree = new Tree(
-      trunk([node('/v1.0', ['GET']), node('/pots', ['GET'])]),
-      endpoints,
-      directives
-    )
-
-    assert.deepEqual(names(tree), ['pots.GET'])
-  })
-
-  it('should name what the tree then matches', () => {
-    const tree = new Tree(
-      trunk(
-        [
-          node('/pots', ['GET'], [node('/:id', ['GET']), node('/hot', ['GET'])]),
-          node('/files', [], [node('/**', ['GET'])])
-        ],
-        ['GET']
-      ),
-      endpoints,
-      directives
-    )
-
-    const params = { id: 'a1b2', '**': 'a/b/c' }
-
-    for (const { segments, verb } of tree.walk()) {
-      const named = name(segments, verb)
-
-      assert.notStrictEqual(named, null, 'every walked method has a name')
-
-      const { path } = address(named!, params)
-      const match = tree.match(path)
-
-      assert.notStrictEqual(
-        match,
-        null,
-        `'${named!}' resolves to '${path}', which matches`
-      )
-      assert.ok(
-        verb in match!.node.methods,
-        `'${named!}' matches a node that answers ${verb}`
-      )
-    }
-  })
-})

package/source/Remotes.test.ts

@@ -1,79 +0,0 @@
-import { it, beforeEach, mock } from 'node:test'
-import assert from 'node:assert/strict'
-import { isDeepStrictEqual } from 'node:util'
-
-import { generate } from 'randomstring'
-import { Connector } from '@toa.io/core'
-import { Remotes } from './Remotes.js'
-import type { Host } from './Factory.js'
-
-const host = {
-  remote: mock.fn(async () => ({
-    connect: mock.fn(() => undefined),
-    link: mock.fn(() => undefined)
-  }))
-} as unknown as Host
-
-const namespace = generate()
-const name = generate()
-
-let remotes: Remotes
-
-beforeEach(() => {
-  remotes = new Remotes(host)
-})
-
-it('should create remote', async () => {
-  const remote = await remotes.discover(namespace, name)
-
-  assert.ok(
-    host.remote.mock.calls.some(
-      (call: any) =>
-        call.arguments.length === 2 &&
-        isPartial(call.arguments[0], { namespace, name }) &&
-        call.arguments[1] !== null &&
-        call.arguments[1] !== undefined
-    )
-  )
-
-  assert.deepStrictEqual(remote, await host.remote.mock.calls[0].result)
-})
-
-it('should be instance of Connector', async () => {
-  assert.ok(remotes instanceof Connector)
-})
-
-it('should depend on created remotes', async () => {
-  const remote = await remotes.discover(namespace, name)
-
-  assert.ok(
-    remote.link.mock.calls.some(
-      (call: any) =>
-        call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], remotes)
-    )
-  )
-})
-
-it('should attribute calls to the gateway', async () => {
-  await remotes.discover(namespace, name)
-
-  assert.ok(
-    host.remote.mock.calls.some(
-      (call: any) =>
-        call.arguments.length === 2 &&
-        call.arguments[0] !== null &&
-        call.arguments[0] !== undefined &&
-        isDeepStrictEqual(call.arguments[1], { service: 'exposition' })
-    )
-  )
-})
-
-function isPartial(actual, expected) {
-  try {
-    assert.partialDeepStrictEqual(actual, expected)
-
-    return true
-  } catch {
-    return false
-  }
-}

package/source/Remotes.ts

@@ -1,39 +0,0 @@
-import { Locator, Connector, type Remote } from '@toa.io/core'
-import type { Source } from '@toa.io/core/types'
-import { type Host } from './Factory.js'
-
-export class Remotes extends Connector {
-  private readonly host: Host
-  private readonly cache: Record<string, Promise<Remote>> = {}
-
-  public constructor(host: Host) {
-    super()
-    this.host = host
-  }
-
-  public async discover(
-    namespace: string,
-    name: string,
-    version: string = 'local'
-  ): Promise<Remote> {
-    const locator = new Locator(name, namespace)
-    const key = locator.id + ':' + version
-
-    this.cache[key] ??= this.locate(locator)
-
-    return this.cache[key]
-  }
-
-  private async locate(locator: Locator): Promise<Remote> {
-    // the gateway is the origin of every call it forwards
-    const remote = await this.host.remote(locator, SOURCE)
-
-    this.depends(remote)
-
-    await remote.connect()
-
-    return remote
-  }
-}
-
-const SOURCE: Source = { service: 'exposition' }