@toa.io/extensions.exposition 1.0.0-alpha.28 → 1.0.0-alpha.283

package/source/Branch.ts

@@ -1,8 +1,46 @@
-import type * as RTD from './RTD/syntax'
+import type * as RTD from './RTD/syntax/index.js'
+import type { Node } from './RTD/index.js'
 
 export interface Branch {
   namespace: string
   component: string
   isolated: boolean
   node: RTD.Node
+  version: string
+
+  /**
+   * When the tenant that announced it started, by its own clock. A replica on its way
+   * out announces the same component with an older stamp than the one replacing it, and
+   * that is what tells the two apart when their versions differ.
+   */
+  timestamp: number
+}
+
+/** A branch the gateway has merged, and the tenant it came from. */
+export interface Exposed {
+  version: string
+
+  /** The start time of the tenant this branch came from. */
+  timestamp: number
+
+  nodes: Node[]
 }
+
+/**
+ * What to do with an announcement about a component that already has a branch exposed.
+ *
+ * - `refresh`: the same version, so its expiration is extended and its endpoints left alone
+ * - `superseded`: it came from a tenant that started before the one exposed now
+ * - `merge`: everything else
+ */
+export function decide (exposed: Exposed, branch: Branch): Decision {
+  if (exposed.version === branch.version)
+    return 'refresh'
+
+  if (branch.timestamp < exposed.timestamp)
+    return 'superseded'
+
+  return 'merge'
+}
+
+export type Decision = 'merge' | 'refresh' | 'superseded'

package/source/Composition.ts

@@ -1,29 +1,23 @@
 import { readdirSync, type Dirent } from 'node:fs'
 import { resolve } from 'node:path'
 import { Connector } from '@toa.io/core'
-import { type Bootloader } from './Factory'
+import { type Host } from './Factory.js'
 
 export class Composition extends Connector {
-  private readonly boot: Bootloader
+  private readonly host: Host
 
-  public constructor (boot: Bootloader) {
+  public constructor (host: Host) {
     super()
-    this.boot = boot
+    this.host = host
   }
 
   protected override async open (): Promise<void> {
     const paths = find()
-    const composition = await this.boot.composition(paths)
+    const composition = await this.host.composition(paths)
 
     await composition.connect()
 
     this.depends(composition)
-
-    console.info('Composition complete.')
-  }
-
-  protected override dispose (): void {
-    console.info('Composition shutdown complete.')
   }
 }
 
@@ -54,4 +48,4 @@ interface Components {
   paths: string[]
 }
 
-const ROOT = resolve(__dirname, '../components/')
+const ROOT = resolve(import.meta.dirname, '../components/')

package/source/Context.ts

@@ -1,8 +1,11 @@
-import type * as RTD from './RTD'
+import type * as RTD from './RTD/index.js'
 
-export type Context = RTD.Context<Extension>
+// the trunk is built from the context annotation and belongs to no branch,
+// thus its endpoints must be fully qualified and are not versioned
+export type Context = RTD.Context<Extension | undefined>
 
 interface Extension {
   namespace: string
   component: string
+  version: string
 }

package/source/Directive.test.ts

@@ -1,38 +1,59 @@
-import assert from 'node:assert'
+import { describe, it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
 import { generate } from 'randomstring'
-import { DirectivesFactory } from './Directive'
-import type { syntax, DirectiveFamily } from './RTD'
-import type { Remotes } from './Remotes'
-import type { Context } from './HTTP'
+import { DirectivesFactory } from './Directive.js'
+import type { syntax, DirectiveFamily } from './RTD/index.js'
+import type { Remotes } from './Remotes.js'
+import type { Host } from './Factory.js'
+import type { Context } from './HTTP/index.js'
+
+const sequence: string[] = []
 
-const families: Array<jest.MockedObjectDeep<DirectiveFamily>> = [
+const families: Array<DirectiveFamily> = [
   {
     name: 'foo',
     mandatory: true,
-    create: jest.fn((_0: any, _1: any, _2: any) => generate() as any),
-    preflight: jest.fn(),
-    settle: jest.fn()
+    create: mock.fn((_0: any, _1: any, _2: any) => generate() as any),
+    arrange: mock.fn(),
+    preflight: mock.fn(() => { sequence.push('foo'); return null }),
+    settle: mock.fn(),
+    dispose: mock.fn()
+  },
+  {
+    name: 'qux',
+    mandatory: true,
+    create: mock.fn((_0: any, _1: any, _2: any) => generate() as any),
+    arrange: mock.fn(),
+    preflight: mock.fn(() => { sequence.push('qux'); return null }),
+    settle: mock.fn(),
+    dispose: mock.fn()
   },
   {
     name: 'bar',
     mandatory: false,
-    create: jest.fn((_0: string, _1: any, _2: any) => generate() as any),
-    preflight: jest.fn(),
-    settle: jest.fn()
+    create: mock.fn((_0: string, _1: any, _2: any) => generate() as any),
+    arrange: mock.fn(),
+    preflight: mock.fn(() => { sequence.push('bar'); return null }),
+    settle: mock.fn(),
+    dispose: mock.fn()
   }
 ]
 
 let factory: DirectivesFactory
 
 beforeEach(() => {
-  jest.clearAllMocks()
+  resetCalls()
+  sequence.length = 0
 
-  assert.ok(families[0].preflight !== undefined)
-  assert.ok(families[1].preflight !== undefined)
+  for (const family of families) {
+    assert.ok(family.preflight !== undefined)
+
+    family.preflight.mock.mockImplementation(() => { sequence.push(family.name); return null })
+  }
 
-  families[0].preflight.mockImplementation(() => null)
-  families[1].preflight.mockImplementation(() => null)
-  factory = new DirectivesFactory(families, {} as unknown as Remotes)
+  factory = new DirectivesFactory(families, {} as unknown as Remotes, {} as unknown as Host,
+    { authorities: {} })
 })
 
 it('should create directive', async () => {
@@ -51,12 +72,22 @@ it('should create directive', async () => {
 
   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)
+  for (const declaration of declarations) {
+    const family = families.find(({ name }) => name === declaration.family)!
+
+    assert.strictEqual(family.create.mock.calls[0].arguments[0], declaration.name)
+    assert.strictEqual(family.create.mock.calls[0].arguments[1], declaration.value)
   }
 })
 
+it('should pass the route to the families', async () => {
+  const route = '/' + generate()
+
+  factory.create([{ family: 'foo', name: generate(), value: generate() }], route)
+
+  assert.strictEqual(families[0].create.mock.calls[0].arguments[3], route)
+})
+
 it('should throw error if directive family is not found', async () => {
   const declaration: syntax.Directive = {
     family: generate(),
@@ -64,8 +95,8 @@ it('should throw error if directive family is not found', async () => {
     value: generate()
   }
 
-  expect(() => factory.create([declaration]))
-    .toThrowError(`Directive family '${declaration.family}' is not found.`)
+  assert.throws(() => factory.create([declaration]),
+    (error: Error) => error.message.includes(`Directive family '${declaration.family}' is not found`))
 })
 
 it('should apply directive', async () => {
@@ -77,14 +108,14 @@ it('should apply directive', async () => {
 
   const directives = factory.create([declaration])
   const request = generate() as unknown as Context
-  const directive = families[0].create.mock.results[0].value
+  const directive = families[0].create.mock.calls[0].result
 
   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)
+  assert.deepStrictEqual(families[0].preflight.mock.calls[0].arguments[0], [directive])
+  assert.deepStrictEqual(families[0].preflight.mock.calls[0].arguments[1], request)
 })
 
 it('should apply mandatory families', async () => {
@@ -93,5 +124,58 @@ it('should apply mandatory families', async () => {
 
   await directives.preflight(request, [])
 
-  expect(families[0].preflight).toHaveBeenCalled()
+  assert.ok(families[0].preflight.mock.callCount() > 0)
+})
+
+describe('order', () => {
+  // the order the families actually ran, as each preflight recorded it
+  function order (): string[] {
+    return sequence
+  }
+
+  it('should run mandatory families in their own order, whatever a manifest says', async () => {
+    // `qux` declared first, but `foo` is registered first and both are mandatory
+    const directives = factory.create([
+      { family: 'qux', name: generate(), value: generate() },
+      { family: 'foo', name: generate(), value: generate() }
+    ])
+
+    await directives.preflight(generate() as unknown as Context, [])
+
+    assert.deepStrictEqual(order(), ['foo', 'qux'])
+  })
+
+  it('should run a mandatory family before a declared one it is not declared with',
+    async () => {
+      // only `qux` is declared: `foo` still has to run first, not merely first of
+      // whatever had no declarations
+      const directives = factory.create([
+        { family: 'qux', name: generate(), value: generate() }
+      ])
+
+      await directives.preflight(generate() as unknown as Context, [])
+
+      assert.deepStrictEqual(order(), ['foo', 'qux'])
+    })
+
+  it('should run mandatory families before the rest', async () => {
+    const directives = factory.create([
+      { family: 'bar', name: generate(), value: generate() },
+      { family: 'qux', name: generate(), value: generate() }
+    ])
+
+    await directives.preflight(generate() as unknown as Context, [])
+
+    assert.deepStrictEqual(order(), ['foo', 'qux', 'bar'])
+  })
 })
+
+function resetCalls (target = [families], seen = new Set()) {
+  if (target === null || typeof target !== 'object' || seen.has(target)) return
+
+  seen.add(target)
+
+  for (const value of Object.values(target))
+    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
+    else resetCalls(value, seen)
+}

package/source/Directive.ts

@@ -1,33 +1,61 @@
-import type { Context, OutgoingMessage } from './HTTP'
-import type { Remotes } from './Remotes'
-import type { Output } from './io'
-import type * as RTD from './RTD'
+import { console, type SpanOptions } from 'openspan'
+import type { Context, OutgoingMessage, Options } from './HTTP/index.js'
+import type { Remotes } from './Remotes.js'
+import type { Host } from './Factory.js'
+import type { Output } from './io.js'
+import type * as RTD from './RTD/index.js'
 
 export class Directives implements RTD.Directives {
   private readonly sets: RTD.DirectiveSet[]
 
+  /** the span of a stage depends only on the set, so it is built once per route */
+  private readonly spans: Spans[]
+
   public constructor (sets: RTD.DirectiveSet[]) {
     this.sets = sets
+    this.spans = sets.map((set) => ({
+      preflight: options(set, 'preflight'),
+      settle: options(set, 'settle')
+    }))
   }
 
   public async preflight (context: Context, parameters: RTD.Parameter[]): Promise<Output> {
-    for (const set of this.sets) {
+    let output = null
+
+    for (let i = 0; i < this.sets.length; i++) {
+      const set = this.sets[i]
+
       if (set.family.preflight === undefined)
         continue
 
-      const output = await set.family.preflight(set.directives, context, parameters)
+      const out = await console.span(this.spans[i].preflight,
+        async () => await set.family.preflight!(set.directives, context, parameters))
+
+      if (out === null)
+        continue
 
       if (output !== null)
-        return output
+        throw new Error('Multiple preflight directives responded')
+      else
+        output = out
     }
 
-    return null
+    return output
   }
 
   public async settle (context: Context, response: OutgoingMessage): Promise<void> {
-    for (const set of this.sets)
+    for (let i = 0; i < this.sets.length; i++) {
+      const set = this.sets[i]
+
       if (set.family.settle !== undefined)
-        await set.family.settle(set.directives, context, response)
+        await console.span(this.spans[i].settle,
+          async () => await set.family.settle!(set.directives, context, response))
+    }
+  }
+
+  public dispose (): void {
+    for (const set of this.sets)
+      set.family.dispose?.(set.directives)
   }
 }
 
@@ -35,9 +63,13 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
   private readonly remotes: Remotes
   private readonly families: Record<string, RTD.DirectiveFamily> = {}
   private readonly mandatory: string[] = []
+  private readonly instances: Directives[] = []
 
-  public constructor (families: RTD.DirectiveFamily[], remotes: Remotes) {
+  // eslint-disable-next-line max-params
+  public constructor (families: RTD.DirectiveFamily[], remotes: Remotes, host: Host,
+    options: Options) {
     for (const family of families) {
+      family.mount?.(host, options)
       this.families[family.name] = family
 
       if (family.mandatory)
@@ -47,23 +79,24 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
     this.remotes = remotes
   }
 
-  public create (declarations: RTD.syntax.Directive[]): Directives {
+  public create (declarations: RTD.syntax.Directive[], route: string = ''): 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))
+    const names: Record<string, string[]> = {}
 
     for (const declaration of declarations) {
       const family = this.families[declaration.family]
 
       if (family === undefined)
-        throw new Error(`Directive family '${declaration.family}' is not found.`)
+        throw new Error(`Directive family '${declaration.family}' is not found`)
 
-      const directive = family.create(declaration.name, declaration.value, this.remotes)
+      const directive = family.create(declaration.name, declaration.value, this.remotes, route)
 
       groups[family.name] ??= []
       groups[family.name].push(directive)
+      names[family.name] ??= []
+      names[family.name].push(`${declaration.family}:${declaration.name}`)
       mandatory.delete(family.name)
     }
 
@@ -72,25 +105,69 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
     for (const family of mandatory)
       sets.push({
         family: this.families[family],
-        directives: []
+        directives: [],
+        names: []
       })
 
     for (const [family, directives] of Object.entries(groups))
       sets.push({
         family: this.families[family],
-        directives
+        directives,
+        names: names[family]
       })
 
-    return new Directives(sets)
+    // Mandatory families run in the order they are registered in, not in the order a
+    // manifest happens to mention them: `auth` must resolve the identity before `io`
+    // can key a quota on it, and a request it denies should not reach `io` at all.
+    // The rest keep the order they were declared in, the sort being stable.
+    sets.sort((a, b) => this.rank(a.family.name) - this.rank(b.family.name))
+
+    // whatever order a family needs among its own directives is fixed here, not per request
+    for (const set of sets)
+      set.family.arrange?.(set.directives)
+
+    const directives = new Directives(sets)
+
+    this.instances.push(directives)
+
+    return directives
+  }
+
+  public dispose (): void {
+    for (const directives of this.instances)
+      directives.dispose()
+  }
+
+  /** Mandatory families first, in their own order; everything else keeps its own. */
+  private rank (family: string): number {
+    const index = this.mandatory.indexOf(family)
+
+    return index === -1 ? this.mandatory.length : index
   }
 }
 
+function options (set: RTD.DirectiveSet, stage: 'preflight' | 'settle'): SpanOptions {
+  const options: SpanOptions = { name: `${set.family.name} ${stage}` }
+
+  if (set.names !== undefined && set.names.length > 0)
+    options.attributes = { directives: Array.from(new Set(set.names)).join(' ') }
+
+  return options
+}
+
+interface Spans {
+  preflight: SpanOptions
+  settle: SpanOptions
+}
+
 export const shortcuts: RTD.syntax.Shortcuts = new Map([
   ['anonymous', 'auth:anonymous'],
+  ['anyone', 'auth:anyone'],
   ['id', 'auth:id'],
   ['role', 'auth:role'],
   ['rule', 'auth:rule'],
   ['incept', 'auth:incept'],
   ['input', 'io:input'],
-  ['output', 'io:output']
+  ['output', 'io:output'],
+  ['languages', 'map:languages']
 ])