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

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']
 ])

package/source/Endpoint.ts

@@ -1,17 +1,21 @@
-import { type Component } from '@toa.io/core'
-import { type Remotes } from './Remotes'
-import { Mapping } from './Mapping'
-import { type Context } from './Context'
-import * as http from './HTTP'
-import type * as RTD from './RTD'
+import { Readable } from 'node:stream'
+import { console } from 'openspan'
+import { Mapping } from './Mapping.js'
+import { redact } from './redact.js'
+import * as http from './HTTP/index.js'
+import type { Introspection, Schema } from './Introspection.js'
+import type { Remote } from '@toa.io/core'
+import type { Remotes } from './Remotes.js'
+import type { Context } from './Context.js'
+import type * as RTD from './RTD/index.js'
 
 export class Endpoint implements RTD.Endpoint {
   private readonly endpoint: string
   private readonly mapping: Mapping
-  private readonly discovery: Promise<Component>
-  private remote: Component | null = null
+  private readonly discovery: Promise<Remote>
+  private remote: Remote | null = null
 
-  public constructor (endpoint: string, mapping: Mapping, discovery: Promise<Component>) {
+  public constructor (endpoint: string, mapping: Mapping, discovery: Promise<Remote>) {
     this.endpoint = endpoint
     this.mapping = mapping
     this.discovery = discovery
@@ -24,28 +28,35 @@ export class Endpoint implements RTD.Endpoint {
 
     this.remote ??= await this.discovery
 
+    const endpoint = this.remote.locator.id + '.' + this.endpoint
+
+    console.debug('Calling operation', { endpoint, request: redact(request) })
+
     const reply = await this.remote.invoke(this.endpoint, request)
 
-    if (context.debug)
-      console.debug('Call', `${this.remote.locator.id}.${this.endpoint}`, request)
+    console.debug('Received reply',
+      { endpoint, reply: reply instanceof Readable ? '[Readable stream]' : redact(reply) })
 
     if (reply instanceof Error)
       throw new http.UnprocessableEntity(reply)
 
     const message: http.OutgoingMessage = {}
 
-    if (typeof reply === 'object' && reply !== null && '_version' in reply) {
+    // etag
+    if (reply !== null && reply !== undefined) {
       const etag = context.request.headers['if-none-match']
 
-      message.headers ??= new Headers()
+      if (this.conditionalGet(reply, etag, message))
+        return message
+    }
 
-      if (etag !== undefined && reply._version === this.version(etag)) {
-        message.status = 304
-        message.headers.set('etag', etag)
+    // last-modified
+    if (typeof reply === 'object' && reply !== null && ('_updated' in reply || '_created' in reply)) {
+      const timestamp: string = reply._updated ?? reply._created
+      const date = new Date(timestamp)
 
-        return message
-      } else
-        message.headers.set('etag', `"${reply._version.toString()}"`)
+      message.headers ??= new Headers()
+      message.headers.set('last-modified', date.toUTCString())
     }
 
     message.body = reply
@@ -53,30 +64,106 @@ export class Endpoint implements RTD.Endpoint {
     return message
   }
 
+  public async explain (parameters: RTD.Parameter[]): Promise<Introspection> {
+    this.remote ??= await this.discovery
+
+    const operation = await this.remote.explain(this.endpoint)
+
+    let route: Record<string, Schema> | null = null
+
+    if (operation.input?.type === 'object')
+      for (const parameter of parameters) {
+        const schema = operation.input.properties[parameter.name]
+
+        // eslint-disable-next-line max-depth
+        if (schema !== undefined) {
+          route ??= {}
+          route[parameter.name] = schema
+
+          delete operation.input.properties[parameter.name]
+        }
+      }
+
+    const query = this.mapping.explain(operation)
+    const introspection: Introspection = {}
+
+    if (route !== null)
+      introspection.route = route
+
+    if (query !== null)
+      introspection.query = query
+
+    Object.assign(introspection, operation)
+
+    return introspection
+  }
+
   public async close (): Promise<void> {
     this.remote ??= await this.discovery
 
     await this.remote.disconnect(INTERRUPT)
   }
 
+  private conditionalGet (reply: unknown, etag: string | undefined, message: http.OutgoingMessage): boolean {
+    message.headers ??= new Headers()
+
+    if (typeof reply === 'object' && reply !== null && '_version' in reply) {
+      const version = reply._version as number
+      const matched = etag === undefined ? null : this.matchVersion(etag)
+
+      if (etag !== undefined && matched !== null && version === matched) {
+        message.status = 304
+        message.headers.set('etag', etag)
+
+        return true
+      }
+
+      message.headers.set('etag', `"${version.toString()}"`)
+
+      return false
+    }
+
+    if (reply instanceof Readable)
+      return false
+
+    /*
+     * A reply that carries no version is tagged with a hash of its body. The body is
+     * serialized anyway when the response is written, so the tag is computed from what
+     * is actually sent rather than from a second serialization of the reply — which
+     * makes it specific to the negotiated representation, hence `vary: accept`.
+     */
+    message.etag = true
+
+    return false
+  }
+
   private query (context: http.Context): http.Query {
     const query: http.Query = Object.fromEntries(context.url.searchParams)
     const etag = context.request.headers['if-match']
 
-    if (etag !== undefined)
+    if (etag !== undefined && this.mapping.queryable)
       query.version = this.version(etag)
 
     return query
   }
 
-  private version (etag: string): number {
+  private matchVersion (etag: string): number | null {
     const match = etag.match(ETAG)
 
     if (match === null)
-      throw new http.BadRequest('Invalid ETag.')
+      return null
 
     return Number.parseInt(match.groups!.version)
   }
+
+  private version (etag: string): number {
+    const version = this.matchVersion(etag)
+
+    if (version === null)
+      throw new http.BadRequest('Invalid ETag')
+
+    return version
+  }
 }
 
 export class EndpointsFactory implements RTD.EndpointsFactory {
@@ -88,21 +175,24 @@ export class EndpointsFactory implements RTD.EndpointsFactory {
 
   public create (method: RTD.syntax.Method, context: Context): Endpoint {
     if (method.mapping === undefined)
-      throw new Error('Cannot create Endpoint without mapping.')
+      throw new Error('Cannot create Endpoint without mapping')
 
     const mapping = Mapping.create(method.mapping.query)
-    const namespace = method.mapping.namespace ?? context.extension?.namespace
-    const component = method.mapping.component ?? context.extension?.component
+
+    const branch = context.extension
+
+    const namespace = method.mapping.namespace ?? branch?.namespace
+    const component = method.mapping.component ?? branch?.component
 
     if (namespace === undefined || component === undefined)
-      throw new Error('Annotation endpoints must be fully qualified.')
+      throw new Error('Annotation endpoints must be fully qualified')
 
-    const discovery = this.remotes.discover(namespace, component)
+    const discovery = this.remotes.discover(namespace, component, branch?.version)
 
     return new Endpoint(method.mapping.endpoint, mapping, discovery)
   }
 }
 
-const ETAG = /^"(?<version>\d{1,32})"$/
+const ETAG = /^(W\/)?"(?<version>\d{1,32})"$/
 
 const INTERRUPT = true