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

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

@@ -1,163 +0,0 @@
-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/types'
-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

@@ -1,93 +0,0 @@
-import { console } from 'openspan'
-import type { Quotas } from './Quotas.js'
-import type { atomicity } from '@toa.io/core/types'
-
-/**
- * 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

@@ -1,32 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

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

@@ -1,30 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

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

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

@@ -1,40 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import * as schemas from './schemas.js'
-
-describe('throttle', () => {
-  const rest = { requests: 1, interval: 1 }
-
-  it('should validate key', () => {
-    assert.doesNotThrow(() => schemas.throttle.validate({ key: 'ip', ...rest }))
-  })
-
-  it('should validate every key component', () => {
-    for (const key of ['ip', 'path', 'route', 'identity'])
-      assert.doesNotThrow(() => schemas.throttle.validate({ key, ...rest }))
-
-    assert.doesNotThrow(() =>
-      schemas.throttle.validate({ key: { segment: 'id' }, ...rest })
-    )
-    assert.doesNotThrow(() =>
-      schemas.throttle.validate({
-        key: ['route', { segment: 'id' }],
-        ...rest
-      })
-    )
-  })
-
-  it('should reject an unknown key component', () => {
-    assert.throws(() => schemas.throttle.validate({ key: 'header', ...rest }))
-    assert.throws(() =>
-      schemas.throttle.validate({ key: { header: 'x-real-ip' }, ...rest })
-    )
-  })
-
-  it('should reject a declaration it no longer honours', () => {
-    // metering earns the budget back rather than locking a key out, so a `cooldown`
-    // left behind is not something to ignore quietly
-    assert.throws(() => schemas.throttle.validate({ key: 'ip', cooldown: 1, ...rest }))
-  })
-})

package/source/directives/io/schemas.ts

@@ -1,16 +0,0 @@
-import { resolve } from 'node:path'
-import * as schemas from '@toa.io/schemas'
-import type { Schema } from '@toa.io/schemas'
-import type { Permissions as InputPermissions } from './Input.js'
-import type { Permissions as OutputPermissions } from './Output.js'
-import type { Declaration as ThrottleDeclaration } from './lib/throttle/index.js'
-
-import type { Message } from './Message.js'
-
-const path = resolve(import.meta.dirname, '../../../schemas/io')
-const namespace = schemas.namespace(path)
-
-export const message: Schema<Message | Message[]> = namespace.schema('message')
-export const input: Schema<InputPermissions> = namespace.schema('input')
-export const output: Schema<OutputPermissions> = namespace.schema('output')
-export const throttle: Schema<ThrottleDeclaration> = namespace.schema('throttle')

package/source/directives/map/Authority.ts

@@ -1,15 +0,0 @@
-import assert from 'node:assert'
-import { Mapping } from './Mapping.js'
-import type { Input } from '../../io.js'
-
-export class Authority extends Mapping<string> {
-  public constructor(property: string) {
-    assert.ok(typeof property === 'string', '`map:authority` must be a string')
-
-    super(property)
-  }
-
-  public properties(context: Input): Record<string, string> {
-    return { [this.value]: context.authority }
-  }
-}

package/source/directives/map/Buffer.ts

@@ -1,15 +0,0 @@
-import assert from 'node:assert'
-import { Mapping } from './Mapping.js'
-import type { Input } from '../../io.js'
-
-export class BufferMapping extends Mapping<string> {
-  public constructor(property: string) {
-    assert.ok(typeof property === 'string', '`map:buffer` must be a string')
-
-    super(property)
-  }
-
-  public override async properties(context: Input): Promise<Record<string, string>> {
-    return { [this.value]: (await context.buffer()).toString('utf8') }
-  }
-}

package/source/directives/map/Claims.ts

@@ -1,63 +0,0 @@
-import assert from 'node:assert'
-import { Mapping } from './Mapping.js'
-import type { Component } from '@toa.io/core'
-import type { Remotes } from '../../Remotes.js'
-import type { Input } from '../../io.js'
-
-export class Claims extends Mapping<Record<string, string>> {
-  private readonly discovery!: Promise<Component>
-  private federation: Component | null = null
-
-  public constructor(map: Record<string, string>, remotes: Remotes) {
-    assert.ok(map.constructor === Object, '`map:claims` must be an object')
-
-    assert.ok(
-      Object.values(map).every((value) => typeof value === 'string'),
-      '`map:claims ` must be an object with string values'
-    )
-
-    super(map, remotes)
-
-    this.discovery = remotes.discover('identity', 'federation')
-  }
-
-  public override async properties(
-    context: Input
-  ): Promise<Record<string, string> | null> {
-    const authentication = context.request.headers.authorization
-
-    if (authentication === undefined) return null
-
-    const claims = await this.claims(authentication)
-
-    if (claims === null) return null
-
-    return Object.entries(this.value).reduce(
-      (properties: Record<string, string>, [property, claim]) => {
-        const value = claims[claim]
-
-        if (value !== undefined) properties[property] = value
-
-        return properties
-      },
-      {}
-    )
-  }
-
-  private async claims(authentication: string): Promise<Record<string, string> | null> {
-    const [scheme, credentials] = authentication.split(' ')
-
-    if (scheme !== 'Bearer' || credentials === undefined) return null
-
-    this.federation ??= await this.discovery
-
-    const claims = await this.federation.invoke<Record<string, string> | Error>(
-      'decode',
-      { input: credentials }
-    )
-
-    if (claims instanceof Error) return null
-
-    return claims
-  }
-}

package/source/directives/map/Directive.ts

@@ -1,4 +0,0 @@
-import type { Mapping } from './Mapping.js'
-import type { Property } from './Properties.js'
-
-export type Directive = Mapping | Property