@toa.io/extensions.exposition 1.0.0-alpha.24 → 1.0.0-alpha.243

package/source/RTD/Node.ts

@@ -4,15 +4,18 @@ import { type Match, type Parameter } from './Match'
 
 export class Node {
   public intermediate: boolean
+  public forward: string | null
+  public expiration: number
   public methods: Methods
   private readonly protected: boolean
   private routes: Route[]
 
-  public constructor
-  (routes: Route[], methods: Methods, properties: Properties) {
+  public constructor (routes: Route[], methods: Methods, properties: Properties) {
     this.routes = routes
     this.methods = methods
     this.protected = properties.protected
+    this.forward = properties.forward ?? null
+    this.expiration = properties.expiration ?? Infinity
     this.intermediate = this.routes.findIndex((route) => route.root) !== -1
 
     this.sort()
@@ -20,7 +23,8 @@ export class Node {
 
   public match (fragments: string[], parameters: Parameter[] = []): Match | null {
     for (const route of this.routes) {
-      const match = route.match(fragments, parameters)
+      const params = parameters.slice()
+      const match = route.match(fragments, params)
 
       if (match !== null)
         return match
@@ -29,56 +33,94 @@ export class Node {
     return null
   }
 
-  public merge (node: Node): void {
+  /**
+   * Returns the nodes the merged branch has landed on, so that its expiration
+   * can later be extended without rebuilding anything.
+   */
+  public merge (node: Node): Node[] {
     this.intermediate = node.intermediate
 
-    if (!this.protected)
-      this.replace(node)
-    else
-      this.append(node)
+    const nodes = this.protected ? this.append(node) : this.replace(node)
 
     this.sort()
+
+    return nodes
+  }
+
+  public touch (expiration: number): void {
+    if (!this.protected)
+      this.expiration = expiration
   }
 
-  private replace (node: Node): void {
+  public async explain (parameters: Parameter[]): Promise<Record<string, unknown>> {
+    const methods: Record<string, unknown> = {}
+
+    const explained = Object.entries(this.methods)
+      .map(async ([verb, method]) =>
+        (methods[verb] = await method.explain(parameters)))
+
+    await Promise.all(explained)
+
+    return methods
+  }
+
+  private replace (node: Node): Node[] {
     const methods = Object.values(this.methods)
 
     this.routes = node.routes
     this.methods = node.methods
+    this.expiration = node.expiration
+    this.forward = node.forward
 
+    // race condition is really unlikely
     for (const method of methods)
       void method.close()
 
-    // race condition is really unlikely
+    return this.nodes()
   }
 
-  private append (node: Node): void {
+  private append (node: Node): Node[] {
+    const nodes: Node[] = []
+
     for (const route of node.routes)
-      this.mergeRoute(route)
+      nodes.push(...this.route(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
+      this.methods[verb] = method
+
+    return nodes
   }
 
-  private mergeRoute (candidate: Route): void {
+  private route (candidate: Route): Node[] {
     for (const route of this.routes)
-      if (candidate.equals(route)) {
-        route.merge(candidate)
-
-        return
-      }
+      if (candidate.equals(route))
+        return route.merge(candidate)
 
     this.routes.push(candidate)
+
+    return candidate.node.nodes()
+  }
+
+  private nodes (): Node[] {
+    const nodes: Node[] = [this]
+
+    for (const route of this.routes)
+      nodes.push(...route.node.nodes())
+
+    return nodes
   }
 
   private sort (): void {
-    this.routes.sort((a, b) => a.variables - b.variables)
+    this.routes.sort((a, b) => {
+      return a.variables === b.variables
+        ? b.segments.length - a.segments.length // routes with more segments should be matched first
+        : a.variables - b.variables // routes with more variables should be matched last
+    })
   }
 }
 
 export interface Properties {
   protected: boolean
+  forward?: string
+  expiration?: number
 }

package/source/RTD/Route.ts

@@ -1,12 +1,13 @@
-import { type Node } from './Node'
 import { type Segment } from './segment'
 import { type Match, type Parameter } from './Match'
+import type { Node } from './Node'
 
 export class Route {
   public readonly root: boolean
   public readonly variables: number = 0
-  private readonly segments: Segment[]
-  private readonly node: Node
+  public readonly segments: Segment[]
+  public readonly node: Node
+  private readonly wildcard: boolean = false
 
   public constructor (segments: Segment[], node: Node) {
     this.root = segments.length === 0
@@ -14,11 +15,16 @@ export class Route {
     this.node = node
 
     for (const segment of segments)
-      if (segment.fragment === null)
+      if (segment.fragment === null) {
         this.variables++
+        this.wildcard ||= segment.wildcard === true
+      }
   }
 
   public match (fragments: string[], parameters: Parameter[]): Match | null {
+    if (Date.now() >= this.node.expiration)
+      return null
+
     for (let i = 0; i < this.segments.length; i++) {
       const segment = this.segments[i]
 
@@ -27,12 +33,17 @@ export class Route {
 
       if (segment.fragment === null && segment.placeholder !== null)
         parameters.push({ name: segment.placeholder, value: fragments[i] })
+
+      if (segment.fragment === null && segment.wildcard === true)
+        parameters.push({ name: '**', value: fragments.slice(this.segments.length - 1).join('/') })
     }
 
     const exact = this.segments.length === fragments.length
 
-    if (exact && !this.node.intermediate) return { node: this.node, parameters }
-    else return this.matchNested(fragments, parameters)
+    if ((exact && !this.node.intermediate) || this.wildcard)
+      return { node: this.node, parameters }
+    else
+      return this.matchNested(fragments, parameters)
   }
 
   public equals (route: Route): boolean {
@@ -46,13 +57,12 @@ export class Route {
     return true
   }
 
-  public merge (route: Route): void {
-    this.node.merge(route.node)
+  public merge (route: Route): Node[] {
+    return this.node.merge(route.node)
   }
 
   private matchNested (fragments: string[], parameters: Parameter[]): Match | null {
     fragments = fragments.slice(this.segments.length)
-    parameters = parameters.slice()
 
     return this.node.match(fragments, parameters)
   }

package/source/RTD/Tree.ts

@@ -1,4 +1,4 @@
-import { createNode } from './factory'
+import { branchTTL, createNode } from './factory'
 import { fragment } from './segment'
 import type { Node } from './Node'
 import type { Match } from './Match'
@@ -13,12 +13,11 @@ export class Tree {
   private readonly endpoints: EndpointsFactory
   private readonly directives: DirectiveFactory
 
-  public constructor
-  (node: syntax.Node, endpoints: EndpointsFactory, directives: DirectiveFactory) {
+  public constructor (node: syntax.Node, endpoints: EndpointsFactory, directives: DirectiveFactory) {
     this.endpoints = endpoints
     this.directives = directives
-    this.trunk = this.createNode(node, PROTECTED)
     this.root = node
+    this.trunk = this.createNode(node, PROTECTED)
   }
 
   public match (path: string): Match | null {
@@ -33,20 +32,34 @@ export class Tree {
     return this.trunk.match(fragments)
   }
 
-  public merge (node: syntax.Node, extension: any): void {
+  public merge (node: syntax.Node, extension: unknown): Node[] {
     const branch = this.createNode(node, !PROTECTED, extension)
 
-    this.trunk.merge(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?: any): Node {
+  private createNode (node: syntax.Node, protect: boolean, extension?: unknown): Node {
     const context: Context = {
       protected: protect,
       endpoints: this.endpoints,
       directives: {
         factory: this.directives,
-        stack: this.root?.directives ?? []
+        stack: this.root.directives ?? []
       },
       extension
     }

package/source/RTD/expiration.test.ts

@@ -0,0 +1,78 @@
+import { Tree } from './Tree'
+import type { EndpointsFactory } from '../Endpoint'
+import type { DirectiveFactory } from './Directives'
+import type * as syntax from './syntax'
+
+const endpoints = {} as unknown as EndpointsFactory
+
+const directives = {
+  create: () => ({
+    preflight: async () => null,
+    settle: async () => undefined,
+    dispose: () => undefined
+  }),
+  dispose: jest.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 = jest.spyOn(Date, 'now').mockReturnValue(10_000)
+  const tree = new Tree(root, endpoints, directives)
+  const nodes = tree.merge(pots, { namespace: 'default', component: 'pots' })
+  const match = tree.match('/pots/')
+
+  expect(match).not.toBeNull()
+
+  now.mockReturnValue(10_900)
+  tree.refresh(nodes)
+
+  now.mockReturnValue(11_500)
+
+  const refreshed = tree.match('/pots/')
+
+  expect(refreshed).not.toBeNull()
+  expect(refreshed?.node).toBe(match?.node)
+
+  now.mockRestore()
+  delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
+})
+
+it('should ignore expired nodes during match', () => {
+  process.env.__TESTING_EXPOSITION_BRANCH_TTL = '1000'
+
+  const now = jest.spyOn(Date, 'now').mockReturnValue(10_000)
+  const tree = new Tree(root, endpoints, directives)
+
+  tree.merge(pots, { namespace: 'default', component: 'pots' })
+
+  expect(tree.match('/pots/')).not.toBeNull()
+
+  now.mockReturnValue(11_000)
+
+  expect(tree.match('/pots/')).toBeNull()
+
+  now.mockRestore()
+  delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
+})

package/source/RTD/factory.ts

@@ -1,3 +1,4 @@
+import { BRANCH_TTL } from '../const'
 import { Node, type Properties } from './Node'
 import { Route } from './Route'
 import { segment } from './segment'
@@ -17,11 +18,28 @@ export function createNode (node: syntax.Node, context: Context): Node {
   for (const method of node.methods)
     methods[method.verb] = createMethod(method, context)
 
-  const properties: Properties = { protected: node.protected ?? context.protected }
+  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 segments = segment(route.path)

package/source/RTD/segment.ts

@@ -15,6 +15,7 @@ export function fragment (path: string): string[] {
 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 }
 }
 
@@ -23,4 +24,5 @@ export type Segment = {
 } | {
   fragment: null
   placeholder: string | null
+  wildcard?: boolean
 }

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

@@ -148,7 +148,7 @@ describe('validation', () => {
   it('should throw on unknown key', async () => {
     const declaration = { hello: 'world' }
 
-    expect(() => parse(declaration)).toThrow('RTD parse error: unknown key \'hello\'.')
+    expect(() => parse(declaration)).toThrow('RTD parse error: unknown key \'hello\'')
   })
 
   it('should throw on invalid mapping', async () => {

package/source/RTD/syntax/parse.ts

@@ -17,42 +17,56 @@ export function parse (input: object, shortcuts?: Shortcuts): Node {
   return node
 }
 
-function parseNode (input: object, shortcuts?: Shortcuts): Node {
+function parseNode (input: object | string, 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
+  if (typeof input === 'string') {
+    node.forward = input
 
-      continue
-    }
+    return node
+  }
 
-    if (key[0] === '/') {
-      const route = parseRoute(key, value as Node, shortcuts)
+  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
 
-      node.routes.push(route)
+      default:
+        // eslint-disable-next-line max-depth
+        if (key[0] === '/') {
+          const route = parseRoute(key, value as Node, shortcuts)
 
-      continue
-    }
+          node.routes.push(route)
 
-    if (verbs.has(key)) {
-      const method = parseMethod(key, value as Mapping, shortcuts)
+          continue
+        }
 
-      node.methods.push(method)
+        // eslint-disable-next-line max-depth
+        if (verbs.has(key)) {
+          const method = parseMethod(key, value as Mapping, shortcuts)
 
-      continue
-    }
+          node.methods.push(method)
 
-    const directive = parseDirective(key, value, shortcuts)
+          continue
+        }
 
-    if (directive !== null) {
-      node.directives.push(directive)
+        // eslint-disable-next-line no-case-declarations
+        const directive = parseDirective(key, value, shortcuts)
 
-      continue
-    }
+        // eslint-disable-next-line max-depth
+        if (directive !== null) {
+          node.directives.push(directive)
 
-    throw new Error(`RTD parse error: unknown key '${key}'.`)
-  }
+          continue
+        }
+
+        throw new Error(`RTD parse error: unknown key '${key}'`)
+    }
 
   return node
 }
@@ -149,6 +163,5 @@ function expandRange (range: number): 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

@@ -1,6 +1,7 @@
 export interface Node {
   protected?: boolean
   isolated?: boolean
+  forward?: string
   routes: Route[]
   methods: Method[]
   directives: Directive[]
@@ -27,17 +28,21 @@ export interface Mapping {
   namespace?: string
   component?: string
   endpoint: string
-  query?: Query
+  query?: Query | null
 }
 
 export interface Query {
   id?: string
   criteria?: string
+  search?: boolean
+  sample?: number
   sort?: string
-  omit: Range
-  limit: Range
+  omit?: Range
+  limit?: Range
   selectors?: string[]
   projection?: string[]
+  parameters?: string[]
+  deleted?: boolean
 }
 
 export interface Range {
@@ -45,4 +50,4 @@ export interface Range {
   range: [number, number]
 }
 
-export const verbs = new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'])
+export const verbs = new Set<string>(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'LOCK', 'UNLOCK'])

package/source/Remotes.ts

@@ -1,24 +1,25 @@
-import { Locator, Connector, type Component } from '@toa.io/core'
+import { Locator, Connector, type Remote } from '@toa.io/core'
 import { type Bootloader } from './Factory'
 
 export class Remotes extends Connector {
   private readonly boot: Bootloader
-  private readonly remotes: Record<string, Promise<Component>> = {}
+  private readonly cache: Record<string, Promise<Remote>> = {}
 
   public constructor (boot: Bootloader) {
     super()
     this.boot = boot
   }
 
-  public async discover (namespace: string, name: string): Promise<Component> {
+  public async discover (namespace: string, name: string, version: string = 'local'): Promise<Remote> {
     const locator = new Locator(name, namespace)
+    const key = locator.id + ':' + version
 
-    this.remotes[locator.id] ??= this.create(locator)
+    this.cache[key] ??= this.locate(locator)
 
-    return await this.remotes[locator.id]
+    return this.cache[key]
   }
 
-  private async create (locator: Locator): Promise<Component> {
+  private async locate (locator: Locator): Promise<Remote> {
     const remote = await this.boot.remote(locator)
 
     this.depends(remote)

package/source/Tenant.ts

@@ -1,30 +1,48 @@
-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'
+import { setTimeout } from 'node:timers/promises'
+import { Connector } from '@toa.io/core'
+import type { bindings } from '@toa.io/core'
+import type { Label } from './discovery'
+import type { Branch } from './Branch'
 
 export class Tenant extends Connector {
   private readonly broadcast: Broadcast
   private readonly branch: Branch
+  private started = 0
+  private stopped = false
 
-  public constructor (broadcast: Broadcast, locator: Locator, node: RTD.Node) {
+  public constructor (broadcast: Broadcast, branch: Branch) {
     super()
 
     this.broadcast = broadcast
-
-    this.branch = {
-      namespace: locator.namespace,
-      component: locator.name,
-      isolated: locator.namespace === 'identity',
-      node
-    }
+    this.branch = branch
 
     this.depends(broadcast)
   }
 
   public override async open (): Promise<void> {
+    this.started = Date.now()
+
     await this.expose()
     await this.broadcast.receive('ping', this.expose.bind(this))
+
+    void this.announce()
+  }
+
+  protected override dispose (): void {
+    this.stopped = true
+  }
+
+  private async announce (): Promise<void> {
+    while (!this.stopped) {
+      const delay = exposeInterval(Date.now() - this.started)
+
+      await setTimeout(delay, undefined, { ref: false })
+
+      if (this.stopped)
+        break
+
+      await this.expose()
+    }
   }
 
   private async expose (): Promise<void> {
@@ -32,4 +50,14 @@ export class Tenant extends Connector {
   }
 }
 
+function exposeInterval (uptime: number): number {
+  return Math.round(EXPOSE_MAX - (EXPOSE_MAX - EXPOSE_MIN) * Math.exp(-uptime / EXPOSE_TAU))
+}
+
+const EXPOSE_MIN = 5_000
+
+// a refresh no longer rebuilds the branch, so exposing often is cheap
+const EXPOSE_MAX = 120_000
+const EXPOSE_TAU = 900_000
+
 type Broadcast = bindings.Broadcast<Label>

package/source/const.ts

@@ -0,0 +1 @@
+export const BRANCH_TTL = 1_800_000