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

package/source/RTD/Tree.ts

@@ -1,137 +0,0 @@
-import { console } from 'openspan'
-import { refusal, template } from '../RPC/names.js'
-import { DISCOVERY } from '@toa.io/definitions/extensions.exposition'
-import { branchTTL, createNode } from './factory.js'
-import { fragment } from './segment.js'
-import type { Mount, Node } from './Node.js'
-import type { Match } from './Match.js'
-import type { Context } from './Context.js'
-import type { DirectiveFactory } from './Directives.js'
-import type { EndpointsFactory } from './Endpoint.js'
-import type * as syntax from './syntax/index.js'
-
-export class Tree {
-  private readonly root: syntax.Node
-  private readonly trunk: Node
-  private readonly endpoints: EndpointsFactory
-  private readonly directives: DirectiveFactory
-
-  public constructor(
-    node: syntax.Node,
-    endpoints: EndpointsFactory,
-    directives: DirectiveFactory
-  ) {
-    this.endpoints = endpoints
-    this.directives = directives
-    this.root = node
-    this.trunk = this.createNode(node, PROTECTED)
-
-    announce(this.trunk)
-  }
-
-  public match(path: string): Match | null {
-    if (path === '/')
-      return {
-        node: this.trunk,
-        parameters: []
-      }
-
-    const fragments = fragment(path)
-
-    return this.trunk.match(fragments)
-  }
-
-  /** Every method in the tree, with the template it answers at. */
-  public walk(): Generator<Mount> {
-    return this.trunk.walk([], TRUNK)
-  }
-
-  public merge(node: syntax.Node, extension: unknown): Node[] {
-    const branch = this.createNode(node, !PROTECTED, extension)
-
-    announce(branch)
-
-    return this.trunk.merge(branch)
-  }
-
-  /**
-   * Extends the expiration of an already merged branch, leaving its endpoints
-   * and their remotes intact.
-   */
-  public refresh(nodes: Node[]): void {
-    const expiration = Date.now() + branchTTL()
-
-    for (const node of nodes) node.touch(expiration)
-  }
-
-  public dispose(): void {
-    this.directives.dispose()
-  }
-
-  private createNode(node: syntax.Node, protect: boolean, extension?: unknown): Node {
-    const context: Context = {
-      protected: protect,
-      endpoints: this.endpoints,
-      directives: {
-        factory: this.directives,
-        // A merged branch is mounted under the root, so it inherits the root's
-        // directives. The trunk is the root: createNode adds them itself, and
-        // seeding them here too would apply every one of them twice.
-        stack: node === this.root ? [] : (this.root.directives ?? [])
-      },
-      path: label(extension),
-      extension
-    }
-
-    return createNode(node, context)
-  }
-}
-
-/**
- * What is served but cannot be reached as it reads. Said once per route as it is built,
- * because either of these is otherwise noticed only by the caller who cannot find it.
- */
-function announce(node: Node): void {
-  const said = new Set<string>()
-
-  for (const { segments } of node.walk([], TRUNK)) {
-    const route = template(segments)
-
-    if (said.has(route)) continue
-
-    // the page is served under this prefix, before a request is routed at all
-    if (route === DISCOVERY || route.startsWith(DISCOVERY + '/')) {
-      said.add(route)
-
-      console.warn('Route is shadowed by the discovery endpoint', { route })
-
-      continue
-    }
-
-    const segment = refusal(segments)
-
-    if (segment === null) continue
-
-    said.add(route)
-
-    console.warn('Route cannot be addressed as a procedure', { route, segment })
-  }
-}
-
-/**
- * A branch's routes are relative to wherever it is merged, and the mount point is not
- * known while it is being built — so the component it came from is what keeps two
- * branches from looking like the same route.
- */
-function label(extension: unknown): string {
-  if (extension === null || typeof extension !== 'object') return ''
-
-  const { namespace, component } = extension as Record<string, unknown>
-
-  return typeof namespace === 'string' && typeof component === 'string'
-    ? `${namespace}.${component}`
-    : ''
-}
-
-const PROTECTED = true
-const TRUNK = true

package/source/RTD/expiration.test.ts

@@ -1,81 +0,0 @@
-import { it, mock } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Tree } from './Tree.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 root: syntax.Node = {
-  routes: [],
-  methods: [],
-  directives: []
-}
-
-const pots: syntax.Node = {
-  routes: [
-    {
-      path: '/pots',
-      node: {
-        routes: [],
-        methods: [{ verb: 'GET', directives: [] }],
-        directives: []
-      }
-    }
-  ],
-  methods: [],
-  directives: []
-}
-
-it('should extend expiration without rebuilding the branch', () => {
-  process.env.__TESTING_EXPOSITION_BRANCH_TTL = '1000'
-
-  const now = mock.method(Date, 'now', () => 10_000)
-  const tree = new Tree(root, endpoints, directives)
-  const nodes = tree.merge(pots, { namespace: 'default', component: 'pots' })
-  const match = tree.match('/pots/')
-
-  assert.notStrictEqual(match, null)
-
-  now.mock.mockImplementation(() => 10_900)
-  tree.refresh(nodes)
-
-  now.mock.mockImplementation(() => 11_500)
-
-  const refreshed = tree.match('/pots/')
-
-  assert.notStrictEqual(refreshed, null)
-  assert.strictEqual(refreshed?.node, match?.node)
-
-  now.mock.restore()
-  delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
-})
-
-it('should ignore expired nodes during match', () => {
-  process.env.__TESTING_EXPOSITION_BRANCH_TTL = '1000'
-
-  const now = mock.method(Date, 'now', () => 10_000)
-  const tree = new Tree(root, endpoints, directives)
-
-  tree.merge(pots, { namespace: 'default', component: 'pots' })
-
-  assert.notStrictEqual(tree.match('/pots/'), null)
-
-  now.mock.mockImplementation(() => 11_000)
-
-  assert.strictEqual(tree.match('/pots/'), null)
-
-  now.mock.restore()
-  delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
-})

package/source/RTD/factory.ts

@@ -1,105 +0,0 @@
-import assert from 'node:assert'
-import { BRANCH_TTL } from '@toa.io/definitions/extensions.exposition'
-import { Node, type Properties } from './Node.js'
-import { Route } from './Route.js'
-import { fragment, segment } from './segment.js'
-import { Method, type Methods } from './Method.js'
-import type { Context } from './Context.js'
-import type * as syntax from './syntax/index.js'
-
-export function createNode(node: syntax.Node, context: Context): Node {
-  if (node.isolated === true) context.directives.stack = node.directives
-  else context.directives.stack = node.directives.concat(context.directives.stack)
-
-  described(node, context)
-
-  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 protect = node.protected ?? context.protected
-
-  const properties: Properties = {
-    protected: protect,
-    forward: node.forward,
-    expiration: protect ? Infinity : Date.now() + branchTTL()
-  }
-
-  return new Node(routes, methods, properties)
-}
-
-export function branchTTL(): number {
-  const value = process.env.__TESTING_EXPOSITION_BRANCH_TTL
-
-  if (value === undefined || value === '') return BRANCH_TTL
-
-  const parsed = Number(value)
-
-  return Number.isFinite(parsed) ? parsed : BRANCH_TTL
-}
-
-function createRoute(route: syntax.Route, context: Context): Route {
-  const stack = context.directives.stack.slice()
-  const path = context.path
-  const segments = segment(route.path)
-
-  context.path = join(path, route.path)
-
-  /*
-   * What a node says of itself is not said of what is under it. Its own `/` is the
-   * exception: an intermediate node is never what a path matches, because that route
-   * answers in its place — so the two are one resource and what describes it carries.
-   */
-  if (route.path !== ROOT)
-    context.directives.stack = stack.filter((directive) =>
-      context.directives.factory.inheritable(directive)
-    )
-
-  const node = createNode(route.node, context)
-
-  context.directives.stack = stack // restore
-  context.path = path
-
-  return new Route(segments, node)
-}
-
-function join(base: string, path: string): string {
-  // '/one/' and '/two/' would otherwise read as '/one//two/'
-  return (base + path).replace(/\/+/g, '/').replace(/(.)\/$/, '$1')
-}
-
-function createMethod(method: syntax.Method, context: Context): Method {
-  const stack = method.directives.concat(context.directives.stack)
-  const directives = context.directives.factory.create(stack, context.path)
-
-  const endpoint =
-    method.mapping?.endpoint === undefined
-      ? null
-      : context.endpoints.create(method, context)
-
-  return new Method(endpoint, directives)
-}
-
-/**
- * A resource is what it is described beside: a node with no methods of its own is never
- * what a path answers, so nothing would carry what it says about itself. Refused where the
- * declaration is, rather than left to be noticed by whoever cannot find it in the answer.
- */
-function described(node: syntax.Node, context: Context): void {
-  const help = node.directives.find(
-    (directive) => directive.family === HELP && directive.name === 'node'
-  )
-
-  if (help === undefined || node.methods.length > 0) return
-
-  // an intermediate node's `/` answers in its place, and carries what it says
-  if (node.routes.some((route) => route.path === ROOT)) return
-
-  const route = '/' + fragment(context.path).join('/')
-
-  assert.fail(`Directive help:node: '${route}' serves no methods`)
-}
-
-const ROOT = '/'
-const HELP = 'help'

package/source/RTD/index.ts

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

package/source/RTD/segment.test.ts

@@ -1,35 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { segment, fragment } from './segment.js'
-
-it('should return segments', async () => {
-  const segments = segment('/foo/bar/')
-
-  assert.strictEqual(segments.length, 2)
-  assert.strictEqual(segments[0].fragment, 'foo')
-  assert.strictEqual(segments[1].fragment, 'bar')
-})
-
-it('should parse placeholders', async () => {
-  const segments = segment('/foo/:id/')
-
-  assert.strictEqual(segments.length, 2)
-  assert.strictEqual(segments[0].fragment, 'foo')
-  assert.strictEqual(segments[1].fragment, null)
-
-  // helping typescript
-  if (segments[1].fragment !== null) throw new Error('?')
-
-  assert.strictEqual(segments[1].placeholder, 'id')
-})
-
-it('should handle root path', async () => {
-  assert.deepStrictEqual(segment('/'), [])
-})
-
-it('should split', async () => {
-  const parts = fragment('/foo/bar/')
-
-  assert.deepStrictEqual(parts, ['foo', 'bar'])
-})

package/source/RTD/segment.ts

@@ -1,51 +0,0 @@
-import type { Parameter } from './Match.js'
-
-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 if (segment === '*') return { fragment: null, placeholder: null }
-  else if (segment === '**') return { fragment: null, placeholder: null, wildcard: true }
-  else return { fragment: segment }
-}
-
-export type Segment =
-  | {
-      fragment: string
-    }
-  | {
-      fragment: null
-      placeholder: string | null
-      wildcard?: boolean
-    }
-
-/**
- * What a route template takes, by name. Describing has no values for them — a template is
- * not a path — and nothing that describes a method reads one. A `*` is skipped: it stands
- * for a segment the caller cannot name, so there is nothing to substitute.
- */
-export function variables(segments: Segment[]): Parameter[] {
-  const params: Parameter[] = []
-
-  for (const segment of segments) {
-    if (segment.fragment !== null) continue
-
-    if (segment.wildcard === true) params.push({ name: '**', value: '' })
-    else if (segment.placeholder !== null)
-      params.push({ name: segment.placeholder, value: '' })
-  }
-
-  return params
-}

package/source/RTD/syntax/index.ts

@@ -1 +0,0 @@
-export * from '@toa.io/definitions/extensions.exposition/syntax'

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' }