@toa.io/extensions.exposition 1.0.0-alpha.266 → 1.0.0-alpha.268

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

@@ -1,5 +1,6 @@
 import { setTimeout } from 'node:timers/promises'
 import { Quotas } from './Quotas'
+import type { Remote } from '@toa.io/core'
 import type { Configuration } from './Configuration'
 import type { Input as Context, Output } from '../../../../io'
 
@@ -7,98 +8,220 @@ let quotas: Quotas
 let configuration: Configuration
 let context: Context
 let output: Output
+let counted: Request[]
 
 beforeEach(() => {
   output = { status: 200 }
+  counted = []
 })
 
 describe('common', () => {
   beforeEach(() => {
     context = createContext()
     configuration = createConfiguration()
-    quotas = Quotas.create(configuration)
+    quotas = Quotas.create(configuration, createCounter())
   })
 
-  it('should be ok', () => {
-    quotas.ok(context)
-    quotas.use(context, output)
+  it('should be ok', async () => {
+    expect(quotas.ok(context, [])).toBe(true)
+
+    await quotas.use(context, output)
   })
 
-  it('should throttle', () => {
-    expect(quotas.ok(context)).toBe(true)
+  it('should throttle', async () => {
+    expect(quotas.ok(context, [])).toBe(true)
 
-    quotas.use(context, output)
-    quotas.use(context, output)
+    await quotas.use(context, output)
+    await quotas.use(context, output)
 
-    expect(quotas.ok(context)).toBe(false)
+    expect(quotas.ok(context, [])).toBe(false)
   })
 
   it('should unblock after cooldown', async () => {
-    quotas.use(context, output)
-    quotas.use(context, output)
+    await quotas.use(context, output)
+    await quotas.use(context, output)
 
-    expect(quotas.ok(context)).toBe(false)
+    expect(quotas.ok(context, [])).toBe(false)
 
     await timeout(configuration.cooldown)
 
-    expect(quotas.ok(context)).toBe(true)
+    expect(quotas.ok(context, [])).toBe(true)
   })
 
-  it('should reset after interval', async () => {
-    quotas.use(context, output)
+  it('should count one request per key and interval', async () => {
+    await quotas.use(context, output)
+
+    expect(counted).toStrictEqual([
+      { name: expect.any(String), interval: configuration.interval, amount: 1 }
+    ])
+  })
+})
+
+describe('group', () => {
+  beforeEach(() => {
+    context = createContext()
+    configuration = createConfiguration()
+  })
 
-    // pseudo-synchronous intervals start somewhere between 0 and interval
-    await timeout(configuration.interval * 2)
+  it('should block on what the group counted, not on what this process did', async () => {
+    // one request here, but the group is already at the limit
+    quotas = Quotas.create(configuration, createCounter(() => configuration.requests))
 
-    quotas.use(context, output)
+    await quotas.use(context, output)
 
-    expect(quotas.ok(context)).toBe(true)
+    expect(quotas.ok(context, [])).toBe(false)
+  })
+
+  it('should not block below the limit', async () => {
+    quotas = Quotas.create(configuration, createCounter(() => configuration.requests - 1))
+
+    await quotas.use(context, output)
+
+    expect(quotas.ok(context, [])).toBe(true)
   })
 })
 
 describe('path', () => {
   beforeEach(() => {
     configuration = createConfiguration()
-    quotas = Quotas.create(configuration)
+    quotas = Quotas.create(configuration, createCounter())
   })
 
-  it('should have separate quotas', () => {
+  it('should have separate quotas', async () => {
     const one = createContext({ url: new URL('http://localhost/one/') })
     const two = createContext({ url: new URL('http://localhost/two/') })
 
-    quotas.use(one, output)
-    quotas.use(one, output)
+    await quotas.use(one, output)
+    await quotas.use(one, output)
 
-    expect(quotas.ok(one)).toBe(false)
-    expect(quotas.ok(two)).toBe(true)
+    expect(quotas.ok(one, [])).toBe(false)
+    expect(quotas.ok(two, [])).toBe(true)
 
-    quotas.use(two, output)
-    quotas.use(two, output)
+    await quotas.use(two, output)
+    await quotas.use(two, output)
 
-    expect(quotas.ok(two)).toBe(false)
+    expect(quotas.ok(two, [])).toBe(false)
   })
 })
 
 describe('ip', () => {
   beforeEach(() => {
     configuration = createConfiguration({ key: [{ method: 'ip' }] })
-    quotas = Quotas.create(configuration)
+    quotas = Quotas.create(configuration, createCounter())
   })
 
-  it('should have separate quotas', () => {
+  it('should have separate quotas', async () => {
     const one = createContext({ request: { headers: { 'x-forwarded-for': '1.1.1.1' } } })
     const two = createContext({ request: { headers: { 'x-forwarded-for': '2.2.2.2' } } })
 
-    quotas.use(one, output)
-    quotas.use(one, output)
+    await quotas.use(one, output)
+    await quotas.use(one, output)
 
-    expect(quotas.ok(one)).toBe(false)
-    expect(quotas.ok(two)).toBe(true)
+    expect(quotas.ok(one, [])).toBe(false)
+    expect(quotas.ok(two, [])).toBe(true)
 
-    quotas.use(two, output)
-    quotas.use(two, output)
+    await quotas.use(two, output)
+    await quotas.use(two, output)
 
-    expect(quotas.ok(two)).toBe(false)
+    expect(quotas.ok(two, [])).toBe(false)
+  })
+})
+
+describe('route', () => {
+  it('should key on the route, not on the path it came in on', async () => {
+    quotas = Quotas.create(createConfiguration({ key: [{ method: 'route' }] }),
+      createCounter(), '/users/:id')
+
+    const one = createContext({ url: new URL('http://localhost/users/1/') })
+    const two = createContext({ url: new URL('http://localhost/users/2/') })
+
+    await quotas.use(one, output)
+    await quotas.use(two, output)
+
+    // two paths, one route, one quota — which is the whole difference from `path`
+    expect(counted[0].name).toBe(counted[1].name)
+    expect(quotas.ok(one, [])).toBe(false)
+  })
+
+  it('should have separate quotas per route', async () => {
+    const users = Quotas.create(createConfiguration({ key: [{ method: 'route' }] }),
+      createCounter(), '/users/:id')
+
+    const posts = Quotas.create(createConfiguration({ key: [{ method: 'route' }] }),
+      createCounter(), '/posts/:id')
+
+    context = createContext({ url: new URL('http://localhost/users/1/') })
+
+    await users.use(context, output)
+    await posts.use(context, output)
+
+    expect(counted[0].name).not.toBe(counted[1].name)
+  })
+})
+
+describe('segment', () => {
+  beforeEach(() => {
+    configuration = createConfiguration({ key: [{ method: 'segment', options: 'id' }] })
+    quotas = Quotas.create(configuration, createCounter())
+  })
+
+  it('should have separate quotas per segment value', async () => {
+    context = createContext()
+
+    const one = [{ name: 'id', value: '1' }]
+    const two = [{ name: 'id', value: '2' }]
+
+    quotas.ok(context, one)
+    await quotas.use(context, output)
+    quotas.ok(context, one)
+    await quotas.use(context, output)
+
+    expect(quotas.ok(context, one)).toBe(false)
+    expect(quotas.ok(context, two)).toBe(true)
+  })
+
+  it('should count under the key preflight saw, which settle cannot recompute', async () => {
+    const one = createContext()
+    const two = createContext()
+
+    quotas.ok(one, [{ name: 'id', value: '1' }])
+    await quotas.use(one, output)
+
+    quotas.ok(two, [{ name: 'id', value: '2' }])
+    await quotas.use(two, output)
+
+    // settle is handed no parameters, so recomputing there would hash an empty
+    // segment both times and the two requests would count as one key
+    expect(counted[0].name).not.toBe(counted[1].name)
+  })
+})
+
+describe('identity', () => {
+  beforeEach(() => {
+    configuration = createConfiguration({ key: [{ method: 'identity' }] })
+    quotas = Quotas.create(configuration, createCounter())
+  })
+
+  it('should have separate quotas per identity', async () => {
+    const one = createContext({ identity: { id: 'one' } })
+    const two = createContext({ identity: { id: 'two' } })
+
+    await quotas.use(one, output)
+    await quotas.use(one, output)
+
+    expect(quotas.ok(one, [])).toBe(false)
+    expect(quotas.ok(two, [])).toBe(true)
+  })
+
+  it('should put every anonymous request in one quota', async () => {
+    const one = createContext({ identity: null })
+    const two = createContext()
+
+    await quotas.use(one, output)
+    await quotas.use(two, output)
+
+    expect(quotas.ok(one, [])).toBe(false)
+    expect(quotas.ok(two, [])).toBe(false)
   })
 })
 
@@ -106,31 +229,69 @@ describe('status', () => {
   beforeEach(() => {
     context = createContext()
     configuration = createConfiguration({ condition: [{ method: 'status', options: 404 }] })
-    quotas = Quotas.create(configuration)
+    quotas = Quotas.create(configuration, createCounter())
+  })
+
+  it('should not throttle on 200', async () => {
+    await quotas.use(context, output)
+
+    expect(quotas.ok(context, [])).toBe(true)
   })
 
-  it('should not throttle on 200', () => {
-    quotas.use(context, output)
+  it('should not count what the condition rejects', async () => {
+    await quotas.use(context, output)
 
-    expect(quotas.ok(context)).toBe(true)
+    expect(counted).toStrictEqual([])
   })
 
-  it('should throttle on 404', () => {
-    quotas.use(context, { status: 404 })
-    quotas.use(context, { status: 404 })
+  it('should throttle on 404', async () => {
+    await quotas.use(context, { status: 404 })
+    await quotas.use(context, { status: 404 })
 
-    expect(quotas.ok(context)).toBe(false)
+    expect(quotas.ok(context, [])).toBe(false)
   })
 })
 
 function createConfiguration (properties?: Partial<Configuration>): Configuration {
-  return Object.assign({ key: [{ method: 'path' }], requests: 2, interval: 10, cooldown: 10 }, properties)
+  return Object.assign({ key: [{ method: 'path' }], requests: 2, interval: 10, cooldown: 10 },
+    properties)
 }
 
 function createContext (properties?: any): Context {
   return Object.assign({ url: new URL('http://localhost/') }, properties) as unknown as Context
 }
 
+/**
+ * Stands in for `exposition.stash`. Counting the way one participant does is enough
+ * here: what a counter reports is comcount's business, and this asserts what the
+ * quotas do with whatever number comes back.
+ */
+function createCounter (reply?: (count: number) => number): Promise<Remote> {
+  const counts: Record<string, number> = {}
+
+  const remote = {
+    invoke: async (endpoint: string, request: { input: Request }): Promise<number> => {
+      expect(endpoint).toBe('count')
+
+      const { name, interval, amount } = request.input
+
+      counted.push({ name, interval, amount })
+
+      counts[name] = (counts[name] ?? 0) + amount
+
+      return reply === undefined ? counts[name] : reply(counts[name])
+    }
+  }
+
+  return Promise.resolve(remote as unknown as Remote)
+}
+
 async function timeout (ms: number): Promise<void> {
   await setTimeout(ms * 1.2)
 }
+
+interface Request {
+  name: string
+  interval: number
+  amount: number
+}

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

@@ -1,75 +1,98 @@
 import { console } from 'openspan'
 import { Keys } from './Keys'
-import { Quota } from './Quota'
-import { Interval } from './Interval'
+import type { Remote } from '@toa.io/core'
 import type { Configuration } from './Configuration'
+import type { Parameter } from '../../../../RTD'
 import type { Input as Context, Output } from '../../../../io'
 
+/**
+ * Quota usage counted across every gateway process, and blocking decided in this one.
+ *
+ * The count comes from the `exposition.stash` component, which counts through Redis
+ * and hands back a lower bound on what the whole group has reached. Blocking stays
+ * local: every process sees the same number and reaches the same conclusion on its
+ * own, and a process that cannot reach Redis still enforces what it has seen itself.
+ */
 export class Quotas {
   private readonly requests: number
+  private readonly interval: number
   private readonly cooldown: number
-  private readonly interval: Interval
   private readonly keys: Keys
-  private readonly quotas: Record<string, Quota | undefined> = {}
+  private readonly counter: Promise<Remote>
   private readonly blocked: Record<string, boolean | undefined> = {}
+  private readonly timers = new Set<NodeJS.Timeout>()
+
+  /**
+   * The key computed at preflight, for settle to count against.
+   *
+   * `segment` reads the route parameters, which settle is not given, and `identity`
+   * can be refreshed between the two — so recomputing there would key a request
+   * differently than it was checked, and blocking would quietly stop working.
+   */
+  private readonly keyed = new WeakMap<Context, string>()
+  private remote: Remote | null = null
 
   public constructor (options: Options) {
     this.requests = options.requests
-    this.cooldown = options.cooldown
     this.interval = options.interval
+    this.cooldown = options.cooldown
     this.keys = options.keys
-
-    this.interval.on('tick', this.reset)
+    this.counter = options.counter
   }
 
-  public static create (configuration: Configuration): Quotas {
-    const requests = configuration.requests
-    const cooldown = configuration.cooldown
-    const keys = Keys.create(configuration.key, configuration.condition)
-    const interval = new Interval(configuration.interval)
+  public static create (configuration: Configuration, counter: Promise<Remote>,
+    route: string = ''): Quotas {
+    const { requests, interval, cooldown } = configuration
+    const keys = Keys.create(configuration.key, configuration.condition, route)
 
-    return new this({ requests, cooldown, keys, interval })
+    return new this({ requests, interval, cooldown, keys, counter })
   }
 
-  public ok (context: Context): boolean {
-    const key = this.keys.get(context)
+  public ok (context: Context, parameters: Parameter[]): boolean {
+    const key = this.keys.get(context, parameters)
+
+    this.keyed.set(context, key)
 
     return this.blocked[key] !== true
   }
 
-  public use (input: Context, output: Output): void {
-    const key = this.keys.match(input, output)
-
-    if (key === null)
+  public async use (input: Context, output: Output): Promise<void> {
+    if (!this.keys.matches(input, output))
       return
 
-    this.quotas[key] ??= new Quota(this.requests)
+    // preflight always runs first, and a request it throws on never reaches settle
+    const key = this.keyed.get(input) ?? this.keys.get(input)
+
+    this.remote ??= await this.counter
 
-    const ok = this.quotas[key]!.use()
+    const count = await this.remote.invoke<number>('count',
+      { input: { name: key, interval: this.interval, amount: 1 } })
 
-    if (!ok)
+    if (count >= this.requests)
       this.block(key)
   }
 
   public dispose (): void {
-    this.interval.dispose()
-  }
-
-  private readonly reset = (): void => {
-    for (const key in this.quotas) {
-      const quota = this.quotas[key]!
+    for (const timer of this.timers)
+      clearTimeout(timer)
 
-      if (quota.idle)
-        delete this.quotas[key]
-      else
-        quota.reset()
-    }
+    this.timers.clear()
   }
 
   private block (key: string): void {
+    if (this.blocked[key] === true)
+      return
+
     this.blocked[key] = true
 
-    setTimeout(() => delete this.blocked[key], this.cooldown)
+    const timer = setTimeout(() => {
+      delete this.blocked[key]
+
+      this.timers.delete(timer)
+    }, this.cooldown)
+
+    timer.unref()
+    this.timers.add(timer)
 
     console.info('Quota exceeded, key blocked', { key, cooldown: this.cooldown })
   }
@@ -78,6 +101,7 @@ export class Quotas {
 interface Options {
   keys: Keys
   requests: number
+  interval: number
   cooldown: number
-  interval: Interval
+  counter: Promise<Remote>
 }

package/source/directives/io/lib/throttle/components/Component.ts

@@ -1,5 +1,6 @@
+import type { Parameter } from '../../../../../RTD'
 import type { Input as Context } from '../../../../../io'
 
 export interface Component {
-  get: (context: Context) => string
+  get: (context: Context, parameters: Parameter[]) => string
 }

package/source/directives/io/lib/throttle/components/Identity.ts

@@ -0,0 +1,19 @@
+import type { Input } from '../../../../../io'
+import type { Component } from './Component'
+
+/**
+ * The authenticated identity, or nothing when the request carries none.
+ *
+ * Anonymous requests therefore share one quota between them; `ip` is the component
+ * that tells them apart.
+ */
+export class Identity implements Component {
+  public get (context: Input): string {
+    return (context as AuthenticatedContext).identity?.id ?? ''
+  }
+}
+
+// declared here rather than imported from `auth`, the way `cache` does it
+interface AuthenticatedContext extends Input {
+  identity?: { id?: string } | null
+}

package/source/directives/io/lib/throttle/components/Route.ts

@@ -0,0 +1,19 @@
+import type { Component } from './Component'
+
+/**
+ * The route as declared — `/users/:id` — rather than the path a request came in on.
+ *
+ * A constant per method, resolved when the tree is built, so every request to one
+ * route shares a quota however many concrete paths match it.
+ */
+export class Route implements Component {
+  private readonly route: string
+
+  public constructor (_: unknown, route: string) {
+    this.route = route
+  }
+
+  public get (): string {
+    return this.route
+  }
+}

package/source/directives/io/lib/throttle/components/Segment.ts

@@ -0,0 +1,19 @@
+import assert from 'node:assert'
+import type { Parameter } from '../../../../../RTD'
+import type { Input as Context } from '../../../../../io'
+import type { Component } from './Component'
+
+/** The value a named route segment was bound to, or nothing when the route has none. */
+export class Segment implements Component {
+  private readonly name: string
+
+  public constructor (name: unknown) {
+    assert.ok(typeof name === 'string', 'Throttle segment must be a string')
+
+    this.name = name
+  }
+
+  public get (_: Context, parameters: Parameter[]): string {
+    return parameters.find(({ name }) => name === this.name)?.value ?? ''
+  }
+}

package/source/directives/io/lib/throttle/components/index.ts

@@ -1,13 +1,19 @@
 import { Path } from './Path'
 import { IP } from './IP'
+import { Route } from './Route'
+import { Identity } from './Identity'
+import { Segment } from './Segment'
 import type { KeyComponentMethod } from '../Configuration'
 import type { Component } from './Component'
 
-type Constructor<T> = new (options: unknown) => T
+type Constructor<T> = new (options: unknown, route: string) => T
 
 export const Components: Record<KeyComponentMethod, Constructor<Component>> = {
   ip: IP,
-  path: Path
+  path: Path,
+  route: Route,
+  identity: Identity,
+  segment: Segment
 }
 
 export type { Component }

package/source/directives/io/schemas.test.ts

@@ -6,4 +6,20 @@ describe('throttle', () => {
   it('should validate key', () => {
     expect(() => schemas.throttle.validate({ key: 'ip', ...rest })).not.toThrow()
   })
+
+  it('should validate every key component', () => {
+    for (const key of ['ip', 'path', 'route', 'identity'])
+      expect(() => schemas.throttle.validate({ key, ...rest })).not.toThrow()
+
+    expect(() => schemas.throttle.validate({ key: { segment: 'id' }, ...rest })).not.toThrow()
+    expect(() => schemas.throttle.validate({
+      key: ['route', { segment: 'id' }],
+      ...rest
+    })).not.toThrow()
+  })
+
+  it('should reject an unknown key component', () => {
+    expect(() => schemas.throttle.validate({ key: 'header', ...rest })).toThrow()
+    expect(() => schemas.throttle.validate({ key: { header: 'x-real-ip' }, ...rest })).toThrow()
+  })
 })

package/source/directives/octets/Octets.ts

@@ -23,7 +23,7 @@ export class Octets implements DirectiveFamily<Directive> {
     if (Class === undefined)
       throw new Error(`Directive 'octets:${name}' is not implemented`)
 
-    this.discovery ??= remotes.discover('octets', 'storage')
+    this.discovery ??= remotes.discover('exposition', 'octets')
 
     return new Class(value, this.discovery, remotes)
   }

package/source/directives/octets/workflows/Execution.ts

@@ -73,7 +73,9 @@ export class Execution extends Readable {
       report.status = 'completed'
 
     if (result instanceof Error) {
-      report.error = result
+      // an Error cannot be serialized where it sits, and the encoders only unwrap
+      // one they are handed directly — this one travels nested inside the report
+      report.error = { ...result }
       this.interrupted = true
     } else if (result !== undefined) {
       report.output = result
@@ -126,5 +128,5 @@ interface Report {
   step: string
   status?: 'completed' | 'exception'
   output?: unknown
-  error?: Error
+  error?: Record<string, unknown>
 }

package/transpiled/Directive.d.ts

@@ -15,7 +15,9 @@ export declare class DirectivesFactory implements RTD.DirectiveFactory {
     private readonly mandatory;
     private readonly instances;
     constructor(families: RTD.DirectiveFamily[], remotes: Remotes);
-    create(declarations: RTD.syntax.Directive[]): Directives;
+    create(declarations: RTD.syntax.Directive[], route?: string): Directives;
     dispose(): void;
+    /** Mandatory families first, in their own order; everything else keeps its own. */
+    private rank;
 }
 export declare const shortcuts: RTD.syntax.Shortcuts;

package/transpiled/Directive.js

@@ -46,16 +46,15 @@ class DirectivesFactory {
         }
         this.remotes = remotes;
     }
-    create(declarations) {
+    create(declarations, route = '') {
         const groups = {};
         const mandatory = new Set(this.mandatory);
-        declarations.sort((a, b) => (mandatory.has(b.family) ? 1 : 0) - (mandatory.has(a.family) ? 1 : 0));
         const names = {};
         for (const declaration of declarations) {
             const family = this.families[declaration.family];
             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);
             names[family.name] ??= [];
@@ -75,6 +74,11 @@ class DirectivesFactory {
                 directives,
                 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);
         return directives;
@@ -83,6 +87,11 @@ class DirectivesFactory {
         for (const directives of this.instances)
             directives.dispose();
     }
+    /** Mandatory families first, in their own order; everything else keeps its own. */
+    rank(family) {
+        const index = this.mandatory.indexOf(family);
+        return index === -1 ? this.mandatory.length : index;
+    }
 }
 exports.DirectivesFactory = DirectivesFactory;
 function options(set, stage) {