@toa.io/extensions.exposition 1.0.0-alpha.285 → 1.0.0-alpha.286

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

@@ -11,30 +11,35 @@ export class Keys {
   private readonly components: Component[]
   private readonly conditions?: Condition[]
 
-  public constructor (components: Component[], 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))
+  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))
+    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 {
+  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
+      if (part === undefined) return
 
       hash.update(part)
     }
@@ -42,7 +47,7 @@ export class Keys {
     return hash.digest('hex')
   }
 
-  public matches (input: Context, output: Output): boolean {
+  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

@@ -77,8 +77,7 @@ describe('retry', () => {
     quotas = Quotas.create(createConfiguration({ requests: 10, interval: 1000 }))
     context = createContext()
 
-    for (let i = 0; i < 10; i++)
-      quotas.check(context, [])
+    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)
@@ -237,14 +236,16 @@ describe('ip', () => {
 
     const context = createContext({})
 
-    for (let i = 0; i < 5; i++)
-      assert.strictEqual(quotas.check(context, []), 0)
+    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')
+    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/') })
@@ -258,8 +259,14 @@ describe('route', () => {
   })
 
   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')
+    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/') })
 
@@ -323,7 +330,9 @@ describe('identity', () => {
 describe('status', () => {
   beforeEach(() => {
     context = createContext()
-    configuration = createConfiguration({ condition: [{ method: 'status', options: 404 }] })
+    configuration = createConfiguration({
+      condition: [{ method: 'status', options: 404 }]
+    })
     quotas = Quotas.create(configuration)
   })
 
@@ -356,7 +365,9 @@ describe('status', () => {
   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 }))
+    quotas = Quotas.create(
+      createConfiguration({ key: keys, condition: configuration.condition })
+    )
 
     const one = createContext()
     const two = createContext()
@@ -373,23 +384,28 @@ describe('status', () => {
   })
 })
 
-function flush (now: number = Date.now(), ...of: Quotas[]): Batch[] {
+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)
+  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 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
+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> {
+async function timeout(ms: number): Promise<void> {
   await setTimeout(ms * 1.2)
 }

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

@@ -42,7 +42,7 @@ export class Quotas {
    */
   private readonly keyed = new WeakMap<Context, string>()
 
-  public constructor (options: Options) {
+  public constructor(options: Options) {
     this.keys = options.keys
     this.conditional = options.conditional
     this.emission = options.interval / options.requests
@@ -50,12 +50,13 @@ export class Quotas {
     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}:`
+    this.prefix =
+      options.name === undefined
+        ? `t:${options.requests}:${options.interval}:`
+        : `${options.name}:`
   }
 
-  public static create (configuration: Configuration, route: string = ''): Quotas {
+  public static create(configuration: Configuration, route: string = ''): Quotas {
     const { requests, interval, condition } = configuration
     const keys = Keys.create(configuration.key, condition, route)
 
@@ -69,12 +70,11 @@ export class Quotas {
    * 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 {
+  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
+    if (key === undefined) return 0
 
     this.keyed.set(context, key)
 
@@ -83,25 +83,21 @@ export class Quotas {
     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 (admit > now) return Math.ceil((admit - now) / 1000)
 
-    if (!this.conditional)
-      this.charge(key, entry, tat)
+    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
+  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
+    if (key === undefined) return
 
     const now = Date.now()
     const entry = this.entries.get(key)
@@ -116,7 +112,7 @@ export class Quotas {
    * 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 {
+  public flush(now: number, batch: Batch[]): void {
     for (const [key, entry] of this.entries) {
       const delta = Math.round(entry.debt)
 
@@ -127,18 +123,16 @@ export class Quotas {
       }
 
       // 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)
+      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 {
+  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 })
+      if (debt > 0) this.entries.set(reported.key, { tat: now + debt, debt: 0 })
 
       return
     }
@@ -149,11 +143,11 @@ export class Quotas {
     entry.tat = Math.max(entry.tat, now + debt)
   }
 
-  public name (key: string): string {
+  public name(key: string): string {
     return this.prefix + key
   }
 
-  private charge (key: string, entry: Entry | undefined, tat: number): void {
+  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 {
@@ -170,7 +164,7 @@ export class Quotas {
  * 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 {
+function period(interval: number): number {
   return Math.min(Math.max(interval / 10, MIN_PERIOD), MAX_PERIOD)
 }
 

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

@@ -3,7 +3,7 @@ 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 { atomicity } from '@toa.io/core/types'
 import type { Configuration } from './Configuration.js'
 import type { Input as Context } from '../../../../io.js'
 
@@ -105,9 +105,11 @@ it('should clear what it reported', async () => {
 })
 
 it('should keep what it could not report, and keep serving', async () => {
-  sync = new Sync(createStash(() => {
-    throw new Error('Redis is unreachable')
-  }))
+  sync = new Sync(
+    createStash(() => {
+      throw new Error('Redis is unreachable')
+    })
+  )
 
   const quotas = createQuotas()
 
@@ -122,7 +124,7 @@ it('should keep what it could not report, and keep serving', async () => {
   assert.strictEqual(quotas.check(context, []), 0)
 })
 
-async function tick (): Promise<void> {
+async function tick(): Promise<void> {
   mock.timers.tick(250)
 
   // the reconciliation a tick starts is asynchronous, and node:test advances
@@ -130,18 +132,20 @@ async function tick (): Promise<void> {
   await new Promise((resolve) => process.nextTick(resolve))
 }
 
-function createQuotas (properties?: Partial<Configuration>): Quotas {
+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 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 {
+function createStash(reply?: (deltas: number[]) => number[]): atomicity.Atom {
   const atom = {
     meter: async (keys: string[], deltas: number[]): Promise<number[]> => {
       invocations.push({ keys, deltas })

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

@@ -1,6 +1,6 @@
 import { console } from 'openspan'
 import type { Quotas } from './Quotas.js'
-import type { atomicity } from '@toa.io/core'
+import type { atomicity } from '@toa.io/core/types'
 
 /**
  * Reconciles every quota of the process with the other gateways, on one tick.
@@ -19,11 +19,11 @@ export class Sync {
   /** Ticks do not overlap: a slow round trip delays reconciling, it does not double it. */
   private reconciling = false
 
-  public constructor (atom: atomicity.Atom) {
+  public constructor(atom: atomicity.Atom) {
     this.atom = atom
   }
 
-  public register (quotas: Quotas): void {
+  public register(quotas: Quotas): void {
     this.quotas.push(quotas)
 
     // the shortest interval sets the pace, and reconciling the others more often than
@@ -35,7 +35,7 @@ export class Sync {
     }
   }
 
-  public dispose (): void {
+  public dispose(): void {
     if (this.timer !== null) {
       clearInterval(this.timer)
 
@@ -43,7 +43,7 @@ export class Sync {
     }
   }
 
-  private start (): void {
+  private start(): void {
     this.dispose()
 
     this.timer = setInterval(this.tick, this.period)
@@ -52,17 +52,14 @@ export class Sync {
   }
 
   private readonly tick = (): void => {
-    if (this.reconciling)
-      return
+    if (this.reconciling) return
 
     const now = Date.now()
     const batch: Batch[] = []
 
-    for (const quotas of this.quotas)
-      quotas.flush(now, batch)
+    for (const quotas of this.quotas) quotas.flush(now, batch)
 
-    if (batch.length === 0)
-      return
+    if (batch.length === 0) return
 
     this.reconciling = true
 
@@ -71,7 +68,7 @@ export class Sync {
     })
   }
 
-  private async reconcile (batch: Batch[]): Promise<void> {
+  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)

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

@@ -9,16 +9,15 @@ export class Warning {
   private readonly interval: number
   private last = -Infinity
 
-  public constructor (message: string, interval: number = INTERVAL) {
+  public constructor(message: string, interval: number = INTERVAL) {
     this.message = message
     this.interval = interval
   }
 
-  public emit (attributes?: Record<string, unknown>): void {
+  public emit(attributes?: Record<string, unknown>): void {
     const now = Date.now()
 
-    if (now - this.last < this.interval)
-      return
+    if (now - this.last < this.interval) return
 
     this.last = now
 

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

@@ -12,20 +12,19 @@ import type { Component } from './Component.js'
 export class IP implements Component {
   private readonly warning: Warning
 
-  public constructor (options: unknown, route: string) {
+  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()
+  public get(context: Context): string | undefined {
+    if (context.ip === undefined) this.warning.emit()
 
     return context.ip
   }
 }
 
-function throttle (route: string): string {
+function throttle(route: string): string {
   return route === '' ? 'Throttle' : `Throttle of ${route}`
 }

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

@@ -8,7 +8,7 @@ import type { Component } from './Component.js'
  * that tells them apart.
  */
 export class Identity implements Component {
-  public get (context: Input): string {
+  public get(context: Input): string {
     return (context as AuthenticatedContext).identity?.id ?? ''
   }
 }

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

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

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

@@ -9,11 +9,11 @@ import type { Component } from './Component.js'
 export class Route implements Component {
   private readonly route: string
 
-  public constructor (_: unknown, route: string) {
+  public constructor(_: unknown, route: string) {
     this.route = route
   }
 
-  public get (): string {
+  public get(): string {
     return this.route
   }
 }

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

@@ -7,13 +7,13 @@ import type { Component } from './Component.js'
 export class Segment implements Component {
   private readonly name: string
 
-  public constructor (name: unknown) {
+  public constructor(name: unknown) {
     assert.ok(typeof name === 'string', 'Throttle segment must be a string')
 
     this.name = name
   }
 
-  public get (_: Context, parameters: Parameter[]): string {
+  public get(_: Context, parameters: Parameter[]): string {
     return parameters.find(({ name }) => name === this.name)?.value ?? ''
   }
 }

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

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

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

@@ -14,16 +14,22 @@ describe('throttle', () => {
     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
-    }))
+    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 }))
+    assert.throws(() =>
+      schemas.throttle.validate({ key: { header: 'x-real-ip' }, ...rest })
+    )
   })
 
   it('should reject a declaration it no longer honours', () => {

package/source/directives/map/Authority.ts

@@ -3,13 +3,13 @@ import { Mapping } from './Mapping.js'
 import type { Input } from '../../io.js'
 
 export class Authority extends Mapping<string> {
-  public constructor (property: 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> {
+  public properties(context: Input): Record<string, string> {
     return { [this.value]: context.authority }
   }
 }

package/source/directives/map/Buffer.ts

@@ -3,13 +3,13 @@ import { Mapping } from './Mapping.js'
 import type { Input } from '../../io.js'
 
 export class BufferMapping extends Mapping<string> {
-  public constructor (property: 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>> {
+  public override async properties(context: Input): Promise<Record<string, string>> {
     return { [this.value]: (await context.buffer()).toString('utf8') }
   }
 }

package/source/directives/map/Claims.ts

@@ -8,50 +8,55 @@ 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) {
+  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')
+    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> {
+  public override async properties(
+    context: Input
+  ): Promise<Record<string, string> | null> {
     const authentication = context.request.headers.authorization
 
-    if (authentication === undefined)
-      return null
+    if (authentication === undefined) return null
 
     const claims = await this.claims(authentication)
 
-    if (claims === null)
-      return null
+    if (claims === null) return null
 
-    return Object.entries(this.value).reduce((properties: Record<string, string>, [property, claim]) => {
-      const value = claims[claim]
+    return Object.entries(this.value).reduce(
+      (properties: Record<string, string>, [property, claim]) => {
+        const value = claims[claim]
 
-      if (value !== undefined)
-        properties[property] = value
+        if (value !== undefined) properties[property] = value
 
-      return properties
-    }, {})
+        return properties
+      },
+      {}
+    )
   }
 
-  private async claims (authentication: string): Promise<Record<string, string> | null> {
+  private async claims(authentication: string): Promise<Record<string, string> | null> {
     const [scheme, credentials] = authentication.split(' ')
 
-    if (scheme !== 'Bearer' || credentials === undefined)
-      return null
+    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 })
+    const claims = await this.federation.invoke<Record<string, string> | Error>(
+      'decode',
+      { input: credentials }
+    )
 
-    if (claims instanceof Error)
-      return null
+    if (claims instanceof Error) return null
 
     return claims
   }