@toa.io/extensions.exposition 1.0.0-alpha.267 → 1.0.0-alpha.269

package/source/Directive.test.ts

@@ -14,6 +14,14 @@ const families: Array<jest.MockedObjectDeep<DirectiveFamily>> = [
     settle: jest.fn(),
     dispose: jest.fn()
   },
+  {
+    name: 'qux',
+    mandatory: true,
+    create: jest.fn((_0: any, _1: any, _2: any) => generate() as any),
+    preflight: jest.fn(),
+    settle: jest.fn(),
+    dispose: jest.fn()
+  },
   {
     name: 'bar',
     mandatory: false,
@@ -29,11 +37,12 @@ let factory: DirectivesFactory
 beforeEach(() => {
   jest.clearAllMocks()
 
-  assert.ok(families[0].preflight !== undefined)
-  assert.ok(families[1].preflight !== undefined)
+  for (const family of families) {
+    assert.ok(family.preflight !== undefined)
+
+    family.preflight.mockImplementation(() => null)
+  }
 
-  families[0].preflight.mockImplementation(() => null)
-  families[1].preflight.mockImplementation(() => null)
   factory = new DirectivesFactory(families, {} as unknown as Remotes)
 })
 
@@ -53,12 +62,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)!
+
+    expect(family.create.mock.calls[0][0]).toBe(declaration.name)
+    expect(family.create.mock.calls[0][1]).toBe(declaration.value)
   }
 })
 
+it('should pass the route to the families', async () => {
+  const route = '/' + generate()
+
+  factory.create([{ family: 'foo', name: generate(), value: generate() }], route)
+
+  expect(families[0].create.mock.calls[0][3]).toBe(route)
+})
+
 it('should throw error if directive family is not found', async () => {
   const declaration: syntax.Directive = {
     family: generate(),
@@ -97,3 +116,49 @@ it('should apply mandatory families', async () => {
 
   expect(families[0].preflight).toHaveBeenCalled()
 })
+
+describe('order', () => {
+  function order (): string[] {
+    return families
+      .filter(({ preflight }) => preflight!.mock.calls.length > 0)
+      .sort((a, b) => a.preflight!.mock.invocationCallOrder[0] -
+        b.preflight!.mock.invocationCallOrder[0])
+      .map(({ name }) => name)
+  }
+
+  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, [])
+
+    expect(order()).toStrictEqual(['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, [])
+
+      expect(order()).toStrictEqual(['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, [])
+
+    expect(order()).toStrictEqual(['foo', 'qux', 'bar'])
+  })
+})

package/source/Directive.ts

@@ -63,13 +63,10 @@ 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) {
@@ -78,7 +75,7 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
       if (family === undefined)
         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)
@@ -103,6 +100,12 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
         names: names[family]
       })
 
+    // 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))
+
     const directives = new Directives(sets)
 
     this.instances.push(directives)
@@ -114,6 +117,13 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
     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 {

package/source/HTTP/messages.ts

@@ -66,7 +66,11 @@ export async function read (context: Context): Promise<any> {
 
 function send (message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
   if (message.body === undefined || message.body === null) {
-    response.setHeader('content-length', '0')
+    // a HEAD reply carries no body but must still report the length a GET would
+    // have returned, so a length already set by a directive is left alone
+    if (!response.hasHeader('content-length'))
+      response.setHeader('content-length', '0')
+
     response.end()
 
     return

package/source/Interception.ts

@@ -5,6 +5,11 @@ export class Interception implements Interceptor {
 
   public constructor (interceptors: Interceptor[]) {
     this.interceptors = interceptors
+
+    // interceptors are module singletons, so a second gateway in one process —
+    // which is how the features run — would otherwise inherit the first one's state
+    for (const interceptor of interceptors)
+      interceptor.reset?.()
   }
 
   public async intercept (input: Input): Promise<Output> {
@@ -21,4 +26,7 @@ export class Interception implements Interceptor {
 
 export interface Interceptor {
   intercept: (input: Input) => Output | Promise<Output>
+
+  /** Discards whatever the interceptor accumulated while serving. */
+  reset?: () => void
 }

package/source/RTD/Context.ts

@@ -9,5 +9,8 @@ export interface Context<TExtension = any> {
     readonly factory: DirectiveFactory
     stack: Directive[]
   }
+
+  /** The route being built, accumulated on the way down and restored on the way up. */
+  path: string
   readonly extension: TExtension
 }

package/source/RTD/Directives.ts

@@ -10,7 +10,7 @@ export interface Directives {
 }
 
 export interface DirectiveFactory {
-  create: (directives: syntax.Directive[]) => Directives
+  create: (directives: syntax.Directive[], route: string) => Directives
   dispose: () => void
 }
 

package/source/RTD/Tree.ts

@@ -61,6 +61,7 @@ export class Tree {
         factory: this.directives,
         stack: this.root.directives ?? []
       },
+      path: label(extension),
       extension
     }
 
@@ -68,4 +69,20 @@ export class Tree {
   }
 }
 
+/**
+ * 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

package/source/RTD/factory.ts

@@ -42,17 +42,27 @@ export function branchTTL (): number {
 
 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)
+
   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)
+  const directives = context.directives.factory.create(stack, context.path)
 
   const endpoint = method.mapping?.endpoint === undefined
     ? null

package/source/directives/cors/CORS.ts

@@ -1,21 +1,24 @@
 import type { Input, Output } from '../../io'
 import type { Interceptor } from '../../Interception'
 
+/** What is allowed before any directive asks for more. */
+const REQUEST_HEADERS = [
+  'accept',
+  'authorization',
+  'content-type',
+  'if-match',
+  'if-none-match'
+]
+
 export class CORS implements Interceptor {
   public readonly name = 'cors'
 
-  private readonly requestHeaders = new Set<string>([
-    'accept',
-    'authorization',
-    'content-type',
-    'if-match',
-    'if-none-match'
-  ])
+  private requestHeaders = new Set<string>(REQUEST_HEADERS)
 
   private readonly headers = new Headers({
     'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK',
     'access-control-allow-credentials': 'true',
-    'access-control-allow-headers': Array.from(this.requestHeaders).join(', '),
+    'access-control-allow-headers': this.allowedHeaders(),
     'access-control-max-age': '3600',
     'cache-control': 'max-age=3600',
     vary: 'origin'
@@ -46,9 +49,23 @@ export class CORS implements Interceptor {
     return null
   }
 
+  public reset (): void {
+    this.requestHeaders = new Set(REQUEST_HEADERS)
+    this.headers.set('access-control-allow-headers', this.allowedHeaders())
+  }
+
   public allow (header: string): void {
     this.requestHeaders.add(header.toLowerCase())
-    this.headers.set('access-control-allow-headers', Array.from(this.requestHeaders).join(', '))
+    this.headers.set('access-control-allow-headers', this.allowedHeaders())
+  }
+
+  /**
+   * Sorted, because the set is filled as branches merge and their order is not
+   * fixed — an unsorted value would differ between otherwise identical processes,
+   * and between one restart and the next.
+   */
+  private allowedHeaders (): string {
+    return Array.from(this.requestHeaders).sort().join(', ')
   }
 
   private preflightResponse (origin: string): Output {

package/source/directives/io/Directive.ts

@@ -1,8 +1,10 @@
+import type { Remote } from '@toa.io/core'
+import type { Parameter } from '../../RTD'
 import type { Input as Context } from '../../io'
 import type * as http from '../../HTTP'
 
 export interface Directive {
-  preflight: (context: Context) => void
+  preflight: (context: Context, parameters: Parameter[]) => void
   settle?: (context: Context, response: http.OutgoingMessage) => Promise<void> | void
   dispose?: () => void
 }
@@ -10,5 +12,5 @@ export interface Directive {
 export interface Constructor {
   validate: (value: unknown) => void
 
-  new (value: any): Directive
+  new (value: any, counter: Promise<Remote>, route: string): Directive
 }

package/source/directives/io/IO.ts

@@ -1,15 +1,21 @@
 import { Output } from './Output'
 import { Input } from './Input'
 import { Throttle } from './Throttle'
+import type { Remote } from '@toa.io/core'
 import type * as http from '../../HTTP'
+import type { Parameter, DirectiveFamily } from '../../RTD'
+import type { Remotes } from '../../Remotes'
 import type { Constructor, Directive } from './Directive'
-import type { DirectiveFamily } from '../../RTD'
 
 export class IO implements DirectiveFamily<Directive> {
   public readonly name = 'io'
   public readonly mandatory = true
 
-  public create (name: string, value: unknown): Directive {
+  /** Throttling counts through a component, because only a component has a stash aspect. */
+  private counter: Promise<Remote> | null = null
+
+  // eslint-disable-next-line max-params
+  public create (name: string, value: unknown, remotes: Remotes, route: string): Directive {
     if (!(name in constructors))
       throw new Error(`Directive 'io:${name}' is not implemented`)
 
@@ -17,20 +23,25 @@ export class IO implements DirectiveFamily<Directive> {
 
     Directive.validate(value)
 
-    return new Directive(value)
+    // discovering boots the component, so nothing is discovered until something throttles
+    if (name === 'throttle')
+      this.counter ??= remotes.discover('exposition', 'stash')
+
+    return new Directive(value, this.counter!, route)
   }
 
-  public preflight (directives: Directive[], context: http.Context): null {
+  public preflight (directives: Directive[], context: http.Context,
+    parameters: Parameter[]): null {
     let restricted = false
 
     for (const directive of directives) {
       restricted ||= directive instanceof Output
 
-      directive.preflight(context)
+      directive.preflight(context, parameters)
     }
 
     if (!restricted)
-      DENIAL.preflight(context)
+      DENIAL.preflight(context, parameters)
 
     return null
   }
@@ -52,4 +63,4 @@ const constructors: Record<string, Constructor> = {
   throttle: Throttle
 }
 
-const DENIAL: Output = new Output([])
+const DENIAL: Directive = new Output([])

package/source/directives/io/Input.ts

@@ -16,7 +16,11 @@ export class Input implements Directive {
   }
 
   public preflight (context: Context): void {
-    context.pipelines.body.push((body) => this.check(body))
+    // Restrictions are on what the client sent, so the check goes to the front of the
+    // pipeline whatever order the families ran in: `auth:delegate` embeds the identity
+    // and `map:*` assigns mapped properties, and those additions are the server's own,
+    // not input to be restricted.
+    context.pipelines.body.unshift((body) => this.check(body))
   }
 
   private check (body: unknown): Message | Message[] | undefined {

package/source/directives/io/Throttle.ts

@@ -1,29 +1,31 @@
 import { TooManyRequests } from '../../HTTP'
 import * as schemas from './schemas'
 import { parse, Quotas, type Declaration } from './lib/throttle'
+import type { Remote } from '@toa.io/core'
 import type * as http from '../../HTTP'
+import type { Parameter } from '../../RTD'
 import type { Directive } from './Directive'
 
 export class Throttle implements Directive {
   private readonly quotas: Quotas
 
-  public constructor (declaration: Declaration) {
+  public constructor (declaration: Declaration, counter: Promise<Remote>, route: string) {
     const configuration = parse(declaration)
 
-    this.quotas = Quotas.create(configuration)
+    this.quotas = Quotas.create(configuration, counter, route)
   }
 
   public static validate (declaration: unknown): asserts declaration is Declaration {
     schemas.throttle.validate(declaration, 'Incorrect \'io:throttle\' format')
   }
 
-  public preflight (context: http.Context): void {
-    if (!this.quotas.ok(context))
+  public preflight (context: http.Context, parameters: Parameter[]): void {
+    if (!this.quotas.ok(context, parameters))
       throw new TooManyRequests()
   }
 
-  public settle (context: http.Context, output: http.OutgoingMessage): void {
-    this.quotas.use(context, output)
+  public async settle (context: http.Context, output: http.OutgoingMessage): Promise<void> {
+    await this.quotas.use(context, output)
   }
 
   public dispose (): void {

package/source/directives/io/lib/throttle/Configuration.test.ts

@@ -38,3 +38,24 @@ it('should convert condition', () => {
     ]
   })
 })
+
+it('should convert a key component that takes an argument', () => {
+  expect(parse({ key: { segment: 'id' }, ...rest })).toMatchObject({
+    key: [
+      {
+        method: 'segment',
+        options: 'id'
+      }
+    ]
+  })
+})
+
+it('should convert a mixed key', () => {
+  expect(parse({ key: ['route', { segment: 'id' }, 'identity'], ...rest })).toMatchObject({
+    key: [
+      { method: 'route' },
+      { method: 'segment', options: 'id' },
+      { method: 'identity' }
+    ]
+  })
+})

package/source/directives/io/lib/throttle/Configuration.ts

@@ -11,13 +11,15 @@ interface Rule<T, K = unknown> {
   options?: K
 }
 
-export type KeyComponentMethod = 'ip' | 'path'
+export type KeyComponentMethod = 'ip' | 'path' | 'route' | 'identity' | 'segment'
 export type KeyConditionMethod = 'status'
 
 export type KeyComponent = Rule<KeyComponentMethod>
 export type KeyCondition = Rule<KeyConditionMethod>
 
-type KeyDeclaration = KeyComponentMethod | KeyComponentMethod[]
+/** A bare component, or the one that takes an argument. */
+type KeyEntry = KeyComponentMethod | { segment: string }
+type KeyDeclaration = KeyEntry | KeyEntry[]
 
 type ConditionDeclaration =
   Record<KeyConditionMethod, unknown>
@@ -41,9 +43,14 @@ export function parse (declaration: Declaration): Configuration {
 }
 
 function mapKey (declaration: KeyDeclaration): KeyComponent[] {
-  const methods = Array.isArray(declaration) ? declaration : [declaration]
+  const entries = Array.isArray(declaration) ? declaration : [declaration]
 
-  return methods.map((method) => ({ method }))
+  // a bare `path`, or `segment: id` for the ones that take an argument
+  return entries.flatMap((entry): KeyComponent[] =>
+    typeof entry === 'string'
+      ? [{ method: entry }]
+      : Object.entries(entry).map(([method, options]) =>
+        ({ method: method as KeyComponentMethod, options })))
 }
 
 function mapCondition (declaration?: ConditionDeclaration): KeyCondition[] | undefined {

package/source/directives/io/lib/throttle/Keys.ts

@@ -2,8 +2,11 @@ import { createHash } from 'node:crypto'
 import { Components, type Component } from './components'
 import { Conditions, type Condition } from './conditions'
 import type { KeyComponent, KeyCondition } from './Configuration'
+import type { Parameter } from '../../../../RTD'
 import type { Input as Context, Output } from '../../../../io'
 
+const NONE: Parameter[] = []
+
 export class Keys {
   private readonly components: Component[]
   private readonly conditions?: Condition[]
@@ -13,28 +16,26 @@ export class Keys {
     this.conditions = conditions
   }
 
-  public static create (componentRules: KeyComponent[], conditionRules?: KeyCondition[]): Keys {
-    const components = componentRules.map((rule) => new Components[rule.method](rule.options))
+  public static create (componentRules: KeyComponent[], conditionRules?: KeyCondition[],
+    route: string = ''): Keys {
+    const components = componentRules.map((rule) =>
+      new Components[rule.method](rule.options, route))
+
     const conditions = conditionRules?.map((rule) => new Conditions[rule.method](rule.options))
 
     return new this(components, conditions)
   }
 
-  public get (context: Context): string {
+  public get (context: Context, parameters: Parameter[] = NONE): string {
     const hash = createHash('sha256')
 
     for (const component of this.components)
-      hash.update(component.get(context))
+      hash.update(component.get(context, parameters))
 
     return hash.digest('hex')
   }
 
-  public match (input: Context, output: Output): string | null {
-    const miss = this.conditions?.some((condition) => !condition.match(input, output))
-
-    if (miss === true)
-      return null
-    else
-      return this.get(input)
+  public matches (input: Context, output: Output): boolean {
+    return this.conditions?.some((condition) => !condition.match(input, output)) !== true
   }
 }