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

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

@@ -0,0 +1,196 @@
+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 preflight, 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
+
+    // preflight 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
+}

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

@@ -0,0 +1,159 @@
+import { it, beforeEach, afterEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Sync } from './Sync.js'
+import { Quotas } from './Quotas.js'
+import type { atomicity } from '@toa.io/core'
+import type { Configuration } from './Configuration.js'
+import type { Input as Context } from '../../../../io.js'
+
+let sync: Sync
+let invocations: Input[]
+let context: Context
+
+beforeEach(() => {
+  mock.timers.enable()
+
+  invocations = []
+  context = createContext()
+})
+
+afterEach(() => {
+  sync.dispose()
+
+  mock.timers.reset()
+})
+
+it('should tick as often as the shortest interval asks', async () => {
+  sync = new Sync(createStash())
+
+  const slow = createQuotas({ interval: 60_000 })
+
+  // on its own a minute reconciles every two seconds, which is the cap
+  sync.register(slow)
+  slow.check(context, [])
+
+  await tick()
+
+  assert.strictEqual(invocations.length, 0)
+
+  // a second asks for every 250ms, and the shortest sets the pace for all of them
+  sync.register(createQuotas({ interval: 1000 }))
+
+  await tick()
+
+  // that a single timer paces every quota was asserted through jest's timer
+  // count, which node:test does not expose; the pacing above still covers it
+  assert.strictEqual(invocations.length, 1)
+})
+
+it('should reconcile every quota in one call', async () => {
+  sync = new Sync(createStash())
+
+  const one = createQuotas()
+  const two = createQuotas({ key: [{ method: 'identity' }] })
+
+  sync.register(one)
+  sync.register(two)
+
+  one.check(context, [])
+  two.check(context, [])
+
+  await tick()
+
+  assert.strictEqual(invocations.length, 1)
+  assert.strictEqual(invocations[0].keys.length, 2)
+  assert.deepStrictEqual(invocations[0].deltas, [50, 50])
+})
+
+it('should not call when there is nothing to report', async () => {
+  sync = new Sync(createStash())
+
+  sync.register(createQuotas())
+
+  await tick()
+
+  assert.strictEqual(invocations.length, 0)
+})
+
+it('should take the group debt back', async () => {
+  sync = new Sync(createStash(() => [1000]))
+
+  const quotas = createQuotas()
+
+  sync.register(quotas)
+  quotas.check(context, [])
+
+  await tick()
+
+  // one request here, but the group is already at capacity
+  assert.ok(quotas.check(context, []) > 0)
+})
+
+it('should clear what it reported', async () => {
+  sync = new Sync(createStash())
+
+  const quotas = createQuotas()
+
+  sync.register(quotas)
+  quotas.check(context, [])
+
+  await tick()
+  await tick()
+
+  assert.strictEqual(invocations.length, 1)
+})
+
+it('should keep what it could not report, and keep serving', async () => {
+  sync = new Sync(createStash(() => {
+    throw new Error('Redis is unreachable')
+  }))
+
+  const quotas = createQuotas()
+
+  sync.register(quotas)
+  quotas.check(context, [])
+
+  await tick()
+  await tick()
+
+  assert.strictEqual(invocations.length, 2)
+  assert.deepStrictEqual(invocations[1].deltas, [50])
+  assert.strictEqual(quotas.check(context, []), 0)
+})
+
+async function tick (): Promise<void> {
+  mock.timers.tick(250)
+
+  // the reconciliation a tick starts is asynchronous, and node:test advances
+  // timers synchronously; let it settle before the next one
+  await new Promise((resolve) => process.nextTick(resolve))
+}
+
+function createQuotas (properties?: Partial<Configuration>): Quotas {
+  const configuration = { key: [{ method: 'path' as const }], requests: 2, interval: 100 }
+
+  return Quotas.create(Object.assign(configuration, properties))
+}
+
+function createContext (properties?: any): Context {
+  return Object.assign({ url: new URL('http://localhost/'), identity: { id: 'one' } },
+    properties) as unknown as Context
+}
+
+function createStash (reply?: (deltas: number[]) => number[]): atomicity.Atom {
+  const atom = {
+    meter: async (keys: string[], deltas: number[]): Promise<number[]> => {
+      invocations.push({ keys, deltas })
+
+      return reply === undefined ? deltas : reply(deltas)
+    }
+  }
+
+  return atom as unknown as atomicity.Atom
+}
+
+interface Input {
+  keys: string[]
+  deltas: number[]
+}

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

@@ -0,0 +1,96 @@
+import { console } from 'openspan'
+import type { Quotas } from './Quotas.js'
+import type { atomicity } from '@toa.io/core'
+
+/**
+ * Reconciles every quota of the process with the other gateways, on one tick.
+ *
+ * Nothing here is on the request path. Each tick takes what the quotas have spent since
+ * the last one and sends all of it as a single call, so the cost of staying in step is
+ * one round trip a tick — not one per key, and not one per directive. What comes back is
+ * the debt the whole group has reached, which the quotas then decide on locally.
+ */
+export class Sync {
+  private readonly atom: atomicity.Atom
+  private readonly quotas: Quotas[] = []
+  private timer: NodeJS.Timeout | null = null
+  private period = Infinity
+
+  /** Ticks do not overlap: a slow round trip delays reconciling, it does not double it. */
+  private reconciling = false
+
+  public constructor (atom: atomicity.Atom) {
+    this.atom = atom
+  }
+
+  public register (quotas: Quotas): void {
+    this.quotas.push(quotas)
+
+    // the shortest interval sets the pace, and reconciling the others more often than
+    // they asked for only makes them more accurate — an idle quota contributes nothing
+    if (quotas.period < this.period) {
+      this.period = quotas.period
+
+      this.start()
+    }
+  }
+
+  public dispose (): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer)
+
+      this.timer = null
+    }
+  }
+
+  private start (): void {
+    this.dispose()
+
+    this.timer = setInterval(this.tick, this.period)
+
+    this.timer.unref()
+  }
+
+  private readonly tick = (): void => {
+    if (this.reconciling)
+      return
+
+    const now = Date.now()
+    const batch: Batch[] = []
+
+    for (const quotas of this.quotas)
+      quotas.flush(now, batch)
+
+    if (batch.length === 0)
+      return
+
+    this.reconciling = true
+
+    void this.reconcile(batch).finally(() => {
+      this.reconciling = false
+    })
+  }
+
+  private async reconcile (batch: Batch[]): Promise<void> {
+    try {
+      const keys = batch.map((entry) => entry.quotas.name(entry.key))
+      const deltas = batch.map((entry) => entry.delta)
+
+      const debts = await this.atom.meter(keys, deltas)
+      const now = Date.now()
+
+      for (let i = 0; i < batch.length; i++)
+        batch[i].quotas.settled(batch[i], debts[i], now)
+    } catch (error) {
+      // what was not reported stays to be reported by the next tick, and until then
+      // this gateway keeps throttling on what it alone has seen, and keeps serving
+      console.warn('Throttling could not reconcile with the group', error as Error)
+    }
+  }
+}
+
+export interface Batch {
+  quotas: Quotas
+  key: string
+  delta: number
+}

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

@@ -0,0 +1,32 @@
+import { it, beforeEach, afterEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { console } from 'openspan'
+import { Warning } from './Warning.js'
+
+let warn: ReturnType<typeof mock.method>
+
+beforeEach(() => {
+  mock.timers.enable({ apis: ['Date'] })
+  warn = mock.method(console, 'warn', () => undefined)
+})
+
+afterEach(() => {
+  warn.mock.restore()
+  mock.timers.reset()
+})
+
+it('should write once per interval', () => {
+  const warning = new Warning('no ip', 1000)
+
+  warning.emit()
+  warning.emit()
+
+  assert.equal(warn.mock.callCount(), 1)
+
+  mock.timers.tick(1000)
+  warning.emit()
+
+  assert.equal(warn.mock.callCount(), 2)
+  assert.equal(warn.mock.calls[0].arguments[0], 'no ip')
+})

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

@@ -0,0 +1,30 @@
+import { console } from 'openspan'
+
+/**
+ * A warning about a condition that holds for request after request, written once per
+ * `interval` rather than once per request.
+ */
+export class Warning {
+  private readonly message: string
+  private readonly interval: number
+  private last = -Infinity
+
+  public constructor (message: string, interval: number = INTERVAL) {
+    this.message = message
+    this.interval = interval
+  }
+
+  public emit (attributes?: Record<string, unknown>): void {
+    const now = Date.now()
+
+    if (now - this.last < this.interval)
+      return
+
+    this.last = now
+
+    console.warn(this.message, attributes)
+  }
+}
+
+/** 100 seconds */
+const INTERVAL = 100_000

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

@@ -0,0 +1,7 @@
+import type { Parameter } from '../../../../../RTD/index.js'
+import type { Input as Context } from '../../../../../io.js'
+
+export interface Component {
+  /** what to key on, or nothing when the request cannot be keyed by this component */
+  get: (context: Context, parameters: Parameter[]) => string | undefined
+}

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

@@ -0,0 +1,31 @@
+import { Warning } from '../Warning.js'
+import type { Context } from '../../../../../HTTP/index.js'
+import type { Component } from './Component.js'
+
+/**
+ * The client address, as the request context resolved it; see `documentation/ip.md`.
+ *
+ * A request without one cannot be keyed, so it is let through, and whoever keys on the
+ * address says so — once in a while rather than on every request, because the cause is
+ * the deployment, not the request.
+ */
+export class IP implements Component {
+  private readonly warning: Warning
+
+  public constructor (options: unknown, route: string) {
+    const subject = typeof options === 'string' ? options : throttle(route)
+
+    this.warning = new Warning(`${subject} is not in effect: the request has no ip`)
+  }
+
+  public get (context: Context): string | undefined {
+    if (context.ip === undefined)
+      this.warning.emit()
+
+    return context.ip
+  }
+}
+
+function throttle (route: string): string {
+  return route === '' ? 'Throttle' : `Throttle of ${route}`
+}

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

@@ -0,0 +1,19 @@
+import type { Input } from '../../../../../io.js'
+import type { Component } from './Component.js'
+
+/**
+ * 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/Path.ts

@@ -0,0 +1,8 @@
+import type { Context } from '../../../../../HTTP/index.js'
+import type { Component } from './Component.js'
+
+export class Path implements Component {
+  public get (context: Context): string {
+    return context.url.pathname
+  }
+}

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

@@ -0,0 +1,19 @@
+import type { Component } from './Component.js'
+
+/**
+ * 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/index.js'
+import type { Input as Context } from '../../../../../io.js'
+import type { Component } from './Component.js'
+
+/** 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

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

package/source/directives/io/lib/throttle/conditions/Condition.ts

@@ -0,0 +1,5 @@
+import type { Input, Output } from '../../../../../io.js'
+
+export interface Condition {
+  match: (input: Input, output: Output) => boolean
+}

package/source/directives/io/lib/throttle/conditions/Status.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert'
+import type { Input, Output } from '../../../../../io.js'
+import type { Condition } from './Condition.js'
+
+export class Status implements Condition {
+  private readonly status: number
+
+  public constructor (status: unknown) {
+    assert.ok(typeof status === 'number', 'Status must be a number')
+
+    this.status = status
+  }
+
+  public match (input: Input, output: Output): boolean {
+    return output?.status === this.status
+  }
+}

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

@@ -0,0 +1,11 @@
+import { Status } from './Status.js'
+import type { KeyConditionMethod } from '../Configuration.js'
+import type { Condition } from './Condition.js'
+
+type Constructor<T> = new (options: unknown) => T
+
+export const Conditions: Record<KeyConditionMethod, Constructor<Condition>> = {
+  status: Status
+}
+
+export type { Condition }

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

@@ -0,0 +1,4 @@
+export { Quotas } from './Quotas.js'
+export { Sync } from './Sync.js'
+export { Warning } from './Warning.js'
+export { parse, type Configuration, type Declaration } from './Configuration.js'