@toa.io/extensions.exposition 1.0.0-alpha.292 → 1.0.0-alpha.294

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

@@ -1,411 +0,0 @@
-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)
-}

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

@@ -1,190 +0,0 @@
-import { Keys } from './Keys.js'
-import type { Batch } from './Sync.js'
-import type { Configuration } from './Configuration.js'
-import type { Parameter } from '../../../../RTD/index.js'
-import type { Input as Context, Output } from '../../../../io.js'
-
-/**
- * A quota per key, metered by GCRA, decided in this process and shared with the others.
- *
- * The state of a key is one theoretical arrival time: the moment the key would be back
- * at zero if nothing more arrived. An admitted request pushes it `emission` further out,
- * time drags it back, and a request is admitted while it stays within `capacity` of now.
- * So `requests` is what a key may spend at once, and `requests / interval` what it earns
- * back — no window to burst across the edge of, and no lockout to time out of.
- *
- * Deciding needs nothing but the local map, which is what keeps the request path free of
- * I/O. What the other gateways have spent arrives on {@link Sync}'s tick, as a debt in
- * milliseconds — a duration, so it carries across processes without their clocks having
- * to agree, and additive, which is what lets each process report only its own increments.
- */
-export class Quotas {
-  /** How often the debt is worth reconciling with the other gateways, in milliseconds. */
-  public readonly period: number
-
-  /** Milliseconds of debt an admitted request adds, `interval / requests`. */
-  private readonly emission: number
-
-  /** Debt a key may carry before it is refused, `interval` — a burst of `requests`. */
-  private readonly capacity: number
-
-  private readonly keys: Keys
-  private readonly prefix: string
-  private readonly conditional: boolean
-  private readonly entries = new Map<string, Entry>()
-
-  /**
-   * The key computed at precall, for settle to charge 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 throttling would quietly stop working.
-   */
-  private readonly keyed = new WeakMap<Context, string>()
-
-  public constructor(options: Options) {
-    this.keys = options.keys
-    this.conditional = options.conditional
-    this.emission = options.interval / options.requests
-    this.capacity = options.interval
-    this.period = period(options.interval)
-
-    // a key means one budget, so quotas that do not share one must not share a key
-    this.prefix =
-      options.name === undefined
-        ? `t:${options.requests}:${options.interval}:`
-        : `${options.name}:`
-  }
-
-  public static create(configuration: Configuration, route: string = ''): Quotas {
-    const { requests, interval, condition } = configuration
-    const keys = Keys.create(configuration.key, condition, route)
-
-    return new this({ keys, requests, interval, conditional: condition !== undefined })
-  }
-
-  /**
-   * Seconds to wait before the request would be admitted, or zero when it is.
-   *
-   * Charges here when nothing conditions the count, so that the request is metered by
-   * the same call that admits it; otherwise only the response can tell whether it counts,
-   * and {@link use} charges once it can.
-   */
-  public check(context: Context, parameters: Parameter[]): number {
-    const key = this.keys.get(context, parameters)
-
-    // a request that cannot be keyed is not metered
-    if (key === undefined) return 0
-
-    this.keyed.set(context, key)
-
-    const now = Date.now()
-    const entry = this.entries.get(key)
-    const tat = Math.max(entry?.tat ?? now, now)
-    const admit = tat + this.emission - this.capacity
-
-    if (admit > now) return Math.ceil((admit - now) / 1000)
-
-    if (!this.conditional) this.charge(key, entry, tat)
-
-    return 0
-  }
-
-  /** Charges what the condition accepts, once the response can be matched against it. */
-  public use(input: Context, output: Output): void {
-    if (!this.conditional || !this.keys.matches(input, output)) return
-
-    // precall always runs first, and a request it refuses never reaches settle
-    const key = this.keyed.get(input) ?? this.keys.get(input)
-
-    if (key === undefined) return
-
-    const now = Date.now()
-    const entry = this.entries.get(key)
-    const tat = Math.max(entry?.tat ?? now, now)
-
-    this.charge(key, entry, tat)
-  }
-
-  /**
-   * Adds what is worth reporting to the batch, and drops what has gone quiet.
-   *
-   * The debt is not cleared here but in {@link settled}, so a tick that fails to reach
-   * Redis leaves it to be reported by the next one instead of losing it.
-   */
-  public flush(now: number, batch: Batch[]): void {
-    for (const [key, entry] of this.entries) {
-      const delta = Math.round(entry.debt)
-
-      if (delta > 0) {
-        batch.push({ quotas: this, key, delta })
-
-        continue
-      }
-
-      // out of debt and with nothing left to report, a key says no more than an absent one
-      if (entry.tat <= now) this.entries.delete(key)
-    }
-  }
-
-  /** Takes the group's debt back, and clears what this process contributed to it. */
-  public settled(reported: Batch, debt: number, now: number): void {
-    const entry = this.entries.get(reported.key)
-
-    if (entry === undefined) {
-      if (debt > 0) this.entries.set(reported.key, { tat: now + debt, debt: 0 })
-
-      return
-    }
-
-    entry.debt -= reported.delta
-
-    // the group has spent at least what this process has, so its debt is the one to keep
-    entry.tat = Math.max(entry.tat, now + debt)
-  }
-
-  public name(key: string): string {
-    return this.prefix + key
-  }
-
-  private charge(key: string, entry: Entry | undefined, tat: number): void {
-    if (entry === undefined)
-      this.entries.set(key, { tat: tat + this.emission, debt: this.emission })
-    else {
-      entry.tat = tat + this.emission
-      entry.debt += this.emission
-    }
-  }
-}
-
-/**
- * How often to reconcile, in milliseconds.
- *
- * Reconciling is what bounds the overshoot — between two ticks a gateway is going on
- * what it alone has spent — so it is worth doing an order of magnitude more often than
- * the interval, within reason on either end.
- */
-function period(interval: number): number {
-  return Math.min(Math.max(interval / 10, MIN_PERIOD), MAX_PERIOD)
-}
-
-const MIN_PERIOD = 250
-const MAX_PERIOD = 2000
-
-interface Entry {
-  /** Theoretical arrival time: when the key is back at zero if nothing more arrives. */
-  tat: number
-
-  /** Milliseconds of debt this process has added and not yet reported. */
-  debt: number
-}
-
-export interface Options {
-  keys: Keys
-  requests: number
-  interval: number
-  conditional: boolean
-
-  /** what the keys are reported under, in place of the budget they carry */
-  name?: string
-}