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

package/source/directives/io/index.ts

@@ -1,3 +1,3 @@
-import { IO } from './IO'
+import { IO } from './IO.js'
 
 export const io = new IO()

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

@@ -0,0 +1,63 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { parse, type Configuration } from './Configuration.js'
+
+const rest: Omit<Configuration, 'key' | 'condition'> = {
+  interval: 1,
+  requests: 1
+}
+
+it('should convert key', () => {
+  const result: Partial<Configuration> = {
+    key: [
+      {
+        method: 'ip'
+      }
+    ]
+  }
+
+  assert.partialDeepStrictEqual(parse({ key: 'ip', ...rest }), result)
+  assert.partialDeepStrictEqual(parse({ key: ['ip'], ...rest }), result)
+})
+
+it('should convert condition', () => {
+  assert.partialDeepStrictEqual(parse({ key: ['ip', 'path'], condition: { status: '404' }, ...rest }), {
+    condition: [
+      {
+        method: 'status',
+        options: '404'
+      }
+    ]
+  })
+
+  assert.partialDeepStrictEqual(parse({ key: 'ip', condition: { status: '404' }, ...rest }), {
+    condition: [
+      {
+        method: 'status',
+        options: '404'
+      }
+    ]
+  })
+})
+
+it('should convert a key component that takes an argument', () => {
+  assert.partialDeepStrictEqual(parse({ key: { segment: 'id' }, ...rest }), {
+    key: [
+      {
+        method: 'segment',
+        options: 'id'
+      }
+    ]
+  })
+})
+
+it('should convert a mixed key', () => {
+  assert.partialDeepStrictEqual(parse({ key: ['route', { segment: 'id' }, 'identity'], ...rest }), {
+    key: [
+      { method: 'route' },
+      { method: 'segment', options: 'id' },
+      { method: 'identity' }
+    ]
+  })
+})

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

@@ -0,0 +1,63 @@
+export interface Configuration {
+  key: KeyComponent[]
+  condition?: KeyCondition[]
+  requests: number
+  interval: number
+}
+
+interface Rule<T, K = unknown> {
+  method: T
+  options?: K
+}
+
+export type KeyComponentMethod = 'ip' | 'path' | 'route' | 'identity' | 'segment'
+export type KeyConditionMethod = 'status'
+
+export type KeyComponent = Rule<KeyComponentMethod>
+export type KeyCondition = Rule<KeyConditionMethod>
+
+/** A bare component, or the one that takes an argument. */
+type KeyEntry = KeyComponentMethod | { segment: string }
+type KeyDeclaration = KeyEntry | KeyEntry[]
+
+type ConditionDeclaration =
+  Record<KeyConditionMethod, unknown>
+  | Array<Record<KeyConditionMethod, unknown>>
+
+export interface Declaration extends Omit<Configuration, 'key' | 'condition'> {
+  key: KeyDeclaration
+  condition?: ConditionDeclaration
+}
+
+export function parse (declaration: Declaration): Configuration {
+  const { key, condition, requests, interval } = declaration
+
+  return {
+    key: mapKey(key),
+    condition: mapCondition(condition),
+    requests,
+    interval: interval * 1000
+  }
+}
+
+function mapKey (declaration: KeyDeclaration): KeyComponent[] {
+  const entries = Array.isArray(declaration) ? declaration : [declaration]
+
+  // 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 {
+  if (declaration === undefined)
+    return
+
+  // reduce to a single object, then map entries to rules
+  const conditions = Array.isArray(declaration) ? declaration : [declaration]
+  const single = conditions.reduce((acc, condition) => ({ ...acc, ...condition }), {})
+
+  return Object.entries(single).map(([method, options]) => ({ method, options })) as KeyCondition[]
+}

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

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto'
+import { Components, type Component } from './components/index.js'
+import { Conditions, type Condition } from './conditions/index.js'
+import type { KeyComponent, KeyCondition } from './Configuration.js'
+import type { Parameter } from '../../../../RTD/index.js'
+import type { Input as Context, Output } from '../../../../io.js'
+
+const NONE: Parameter[] = []
+
+export class Keys {
+  private readonly components: Component[]
+  private readonly conditions?: Condition[]
+
+  public constructor (components: Component[], conditions?: Condition[]) {
+    this.components = components
+    this.conditions = conditions
+  }
+
+  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)
+  }
+
+  /** The key of the request, or nothing when a component cannot key it. */
+  public get (context: Context, parameters: Parameter[] = NONE): string | undefined {
+    const hash = createHash('sha256')
+
+    for (const component of this.components) {
+      const part = component.get(context, parameters)
+
+      if (part === undefined)
+        return
+
+      hash.update(part)
+    }
+
+    return hash.digest('hex')
+  }
+
+  public matches (input: Context, output: Output): boolean {
+    return this.conditions?.some((condition) => !condition.match(input, output)) !== true
+  }
+}

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

@@ -0,0 +1,395 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { setTimeout } from 'node:timers/promises'
+import { Quotas } from './Quotas.js'
+import type { Batch } from './Sync.js'
+import type { Configuration } from './Configuration.js'
+import type { Input as Context, Output } from '../../../../io.js'
+
+let quotas: Quotas
+let configuration: Configuration
+let context: Context
+let output: Output
+
+beforeEach(() => {
+  output = { status: 200 }
+})
+
+describe('common', () => {
+  beforeEach(() => {
+    context = createContext()
+    configuration = createConfiguration()
+    quotas = Quotas.create(configuration)
+  })
+
+  it('should admit a burst of the whole budget', () => {
+    assert.strictEqual(quotas.check(context, []), 0)
+    assert.strictEqual(quotas.check(context, []), 0)
+  })
+
+  it('should refuse past the budget', () => {
+    quotas.check(context, [])
+    quotas.check(context, [])
+
+    assert.ok(quotas.check(context, []) > 0)
+  })
+
+  it('should not charge what it refuses', async () => {
+    quotas.check(context, [])
+    quotas.check(context, [])
+    quotas.check(context, [])
+    quotas.check(context, [])
+
+    // a refused request does not push admission further out, so one emission is
+    // all it takes to be admitted again however hard the key is hammered
+    await timeout(configuration.interval / configuration.requests)
+
+    assert.strictEqual(quotas.check(context, []), 0)
+  })
+
+  it('should earn the budget back over the interval', async () => {
+    quotas.check(context, [])
+    quotas.check(context, [])
+
+    assert.ok(quotas.check(context, []) > 0)
+
+    await timeout(configuration.interval)
+
+    assert.strictEqual(quotas.check(context, []), 0)
+    assert.strictEqual(quotas.check(context, []), 0)
+  })
+})
+
+describe('retry', () => {
+  it('should answer the seconds until the request would be admitted', () => {
+    // an emission is 5 seconds, which is what the budget takes to earn one back
+    quotas = Quotas.create(createConfiguration({ requests: 2, interval: 10_000 }))
+    context = createContext()
+
+    quotas.check(context, [])
+    quotas.check(context, [])
+
+    assert.strictEqual(quotas.check(context, []), 5)
+  })
+
+  it('should never answer zero when it refuses', () => {
+    quotas = Quotas.create(createConfiguration({ requests: 10, interval: 1000 }))
+    context = createContext()
+
+    for (let i = 0; i < 10; i++)
+      quotas.check(context, [])
+
+    // an emission here is a tenth of a second, and `Retry-After` counts in whole ones
+    assert.strictEqual(quotas.check(context, []), 1)
+  })
+})
+
+describe('group', () => {
+  beforeEach(() => {
+    context = createContext()
+    configuration = createConfiguration()
+    quotas = Quotas.create(configuration)
+  })
+
+  it('should report what it has charged', () => {
+    quotas.check(context, [])
+
+    const batch = flush()
+
+    assert.strictEqual(batch.length, 1)
+    assert.strictEqual(batch[0].delta, configuration.interval / configuration.requests)
+    assert.strictEqual(batch[0].quotas, quotas)
+  })
+
+  it('should refuse on what the group has spent, not on what this process has', () => {
+    quotas.check(context, [])
+
+    const batch = flush()
+
+    // one request here, but the group is already at capacity
+    quotas.settled(batch[0], configuration.interval, Date.now())
+
+    assert.ok(quotas.check(context, []) > 0)
+  })
+
+  it('should not refuse below the capacity', () => {
+    quotas.check(context, [])
+
+    const batch = flush()
+
+    quotas.settled(batch[0], 0, Date.now())
+
+    assert.strictEqual(quotas.check(context, []), 0)
+  })
+
+  it('should clear what was reported, and keep what was charged since', () => {
+    quotas.check(context, [])
+
+    const batch = flush()
+
+    quotas.check(context, [])
+    quotas.settled(batch[0], 0, Date.now())
+
+    assert.strictEqual(flush()[0].delta, configuration.interval / configuration.requests)
+  })
+
+  it('should keep what it could not report', () => {
+    quotas.check(context, [])
+
+    const first = flush()
+
+    // no `settled`, as a tick that cannot reach Redis leaves the debt to the next one
+    assert.strictEqual(flush()[0].delta, first[0].delta)
+  })
+
+  it('should take a debt for a key it has already dropped', () => {
+    quotas.check(context, [])
+
+    const batch = flush()
+
+    quotas.settled(batch[0], 0, Date.now())
+    flush(Date.now() + configuration.interval)
+
+    quotas.settled({ ...batch[0], delta: 0 }, configuration.interval, Date.now())
+
+    assert.ok(quotas.check(context, []) > 0)
+  })
+
+  it('should name keys so that quotas with different budgets never share one', () => {
+    const other = Quotas.create(createConfiguration({ requests: 3 }))
+
+    quotas.check(context, [])
+    other.check(context, [])
+
+    const batch = flush(Date.now(), quotas, other)
+
+    assert.strictEqual(batch[0].key, batch[1].key)
+    assert.notStrictEqual(quotas.name(batch[0].key), other.name(batch[1].key))
+  })
+})
+
+describe('sweeping', () => {
+  beforeEach(() => {
+    context = createContext()
+    configuration = createConfiguration()
+    quotas = Quotas.create(configuration)
+  })
+
+  it('should drop a key that is out of debt with nothing to report', () => {
+    quotas.check(context, [])
+
+    const batch = flush()
+
+    quotas.settled(batch[0], 0, Date.now())
+
+    // once the debt has drained, a key says no more than an absent one
+    assert.strictEqual(flush(Date.now() + configuration.interval).length, 0)
+    assert.strictEqual(flush(Date.now() + configuration.interval).length, 0)
+    assert.strictEqual(quotas.check(context, []), 0)
+  })
+
+  it('should keep a key that still owes something', () => {
+    quotas.check(context, [])
+
+    assert.strictEqual(flush(Date.now() + configuration.interval).length, 1)
+  })
+})
+
+describe('path', () => {
+  beforeEach(() => {
+    configuration = createConfiguration()
+    quotas = Quotas.create(configuration)
+  })
+
+  it('should have separate quotas', () => {
+    const one = createContext({ url: new URL('http://localhost/one/') })
+    const two = createContext({ url: new URL('http://localhost/two/') })
+
+    quotas.check(one, [])
+    quotas.check(one, [])
+
+    assert.ok(quotas.check(one, []) > 0)
+    assert.strictEqual(quotas.check(two, []), 0)
+  })
+})
+
+describe('ip', () => {
+  beforeEach(() => {
+    configuration = createConfiguration({ key: [{ method: 'ip' }] })
+  })
+
+  it('should key on the address the context resolved', () => {
+    quotas = Quotas.create(configuration)
+
+    const one = createContext({ ip: '1.1.1.1' })
+    const two = createContext({ ip: '2.2.2.2' })
+
+    quotas.check(one, [])
+    quotas.check(one, [])
+
+    assert.ok(quotas.check(one, []) > 0)
+    assert.strictEqual(quotas.check(two, []), 0)
+  })
+
+  it('should let a request without an address through', () => {
+    quotas = Quotas.create(configuration)
+
+    const context = createContext({})
+
+    for (let i = 0; i < 5; i++)
+      assert.strictEqual(quotas.check(context, []), 0)
+  })
+})
+
+describe('route', () => {
+  it('should key on the route, not on the path it came in on', () => {
+    quotas = Quotas.create(createConfiguration({ key: [{ method: 'route' }] }), '/users/:id')
+
+    const one = createContext({ url: new URL('http://localhost/users/1/') })
+    const two = createContext({ url: new URL('http://localhost/users/2/') })
+
+    quotas.check(one, [])
+    quotas.check(two, [])
+
+    // two paths, one route, one quota — which is the whole difference from `path`
+    assert.strictEqual(flush().length, 1)
+    assert.ok(quotas.check(one, []) > 0)
+  })
+
+  it('should have separate quotas per route', () => {
+    const users = Quotas.create(createConfiguration({ key: [{ method: 'route' }] }), '/users/:id')
+    const posts = Quotas.create(createConfiguration({ key: [{ method: 'route' }] }), '/posts/:id')
+
+    context = createContext({ url: new URL('http://localhost/users/1/') })
+
+    users.check(context, [])
+    posts.check(context, [])
+
+    const batch = flush(Date.now(), users, posts)
+
+    assert.notStrictEqual(batch[0].key, batch[1].key)
+  })
+})
+
+describe('segment', () => {
+  beforeEach(() => {
+    configuration = createConfiguration({ key: [{ method: 'segment', options: 'id' }] })
+    quotas = Quotas.create(configuration)
+    context = createContext()
+  })
+
+  it('should have separate quotas per segment value', () => {
+    const one = [{ name: 'id', value: '1' }]
+    const two = [{ name: 'id', value: '2' }]
+
+    quotas.check(context, one)
+    quotas.check(context, one)
+
+    assert.ok(quotas.check(context, one) > 0)
+    assert.strictEqual(quotas.check(context, two), 0)
+  })
+})
+
+describe('identity', () => {
+  beforeEach(() => {
+    configuration = createConfiguration({ key: [{ method: 'identity' }] })
+    quotas = Quotas.create(configuration)
+  })
+
+  it('should have separate quotas per identity', () => {
+    const one = createContext({ identity: { id: 'one' } })
+    const two = createContext({ identity: { id: 'two' } })
+
+    quotas.check(one, [])
+    quotas.check(one, [])
+
+    assert.ok(quotas.check(one, []) > 0)
+    assert.strictEqual(quotas.check(two, []), 0)
+  })
+
+  it('should put every anonymous request in one quota', () => {
+    const one = createContext({ identity: null })
+    const two = createContext()
+
+    quotas.check(one, [])
+    quotas.check(two, [])
+
+    assert.ok(quotas.check(one, []) > 0)
+    assert.ok(quotas.check(two, []) > 0)
+  })
+})
+
+describe('status', () => {
+  beforeEach(() => {
+    context = createContext()
+    configuration = createConfiguration({ condition: [{ method: 'status', options: 404 }] })
+    quotas = Quotas.create(configuration)
+  })
+
+  it('should not charge before the response can be matched', () => {
+    quotas.check(context, [])
+    quotas.check(context, [])
+    quotas.check(context, [])
+
+    // only the response tells whether a request counts, so checking cannot charge
+    assert.strictEqual(flush().length, 0)
+  })
+
+  it('should not charge what the condition rejects', () => {
+    quotas.check(context, [])
+    quotas.use(context, output)
+
+    assert.strictEqual(flush().length, 0)
+    assert.strictEqual(quotas.check(context, []), 0)
+  })
+
+  it('should charge what the condition accepts', () => {
+    for (let i = 0; i < 2; i++) {
+      quotas.check(context, [])
+      quotas.use(context, { status: 404 })
+    }
+
+    assert.ok(quotas.check(context, []) > 0)
+  })
+
+  it('should charge the key checking saw, which settling cannot recompute', () => {
+    const keys = [{ method: 'segment' as const, options: 'id' }]
+
+    quotas = Quotas.create(createConfiguration({ key: keys, condition: configuration.condition }))
+
+    const one = createContext()
+    const two = createContext()
+
+    quotas.check(one, [{ name: 'id', value: '1' }])
+    quotas.use(one, { status: 404 })
+
+    quotas.check(two, [{ name: 'id', value: '2' }])
+    quotas.use(two, { status: 404 })
+
+    // settling is handed no parameters, so recomputing there would hash an empty
+    // segment both times and the two requests would charge one key
+    assert.strictEqual(flush().length, 2)
+  })
+})
+
+function flush (now: number = Date.now(), ...of: Quotas[]): Batch[] {
+  const batch: Batch[] = []
+
+  for (const one of of.length === 0 ? [quotas] : of)
+    one.flush(now, batch)
+
+  return batch
+}
+
+function createConfiguration (properties?: Partial<Configuration>): Configuration {
+  return Object.assign({ key: [{ method: 'path' }], requests: 2, interval: 100 }, properties)
+}
+
+function createContext (properties?: any): Context {
+  return Object.assign({ url: new URL('http://localhost/') }, properties) as unknown as Context
+}
+
+async function timeout (ms: number): Promise<void> {
+  await setTimeout(ms * 1.2)
+}