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

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
   }

package/source/directives/map/Headers.ts

@@ -15,11 +15,13 @@ const FORBIDDEN = new Set(['host', 'origin'])
 export class Headers extends Mapping<Record<string, string>> {
   private readonly headers: string[]
 
-  public constructor (map: Record<string, string>) {
+  public constructor(map: Record<string, string>) {
     assert.ok(map.constructor === Object, '`map:headers` must be an object')
 
-    assert.ok(Object.values(map).every((value) => typeof value === 'string'),
-      '`map:headers` must be an object with string values')
+    assert.ok(
+      Object.values(map).every((value) => typeof value === 'string'),
+      '`map:headers` must be an object with string values'
+    )
 
     super(map)
 
@@ -27,7 +29,7 @@ export class Headers extends Mapping<Record<string, string>> {
     this.headers.forEach((header) => cors.allow(header))
   }
 
-  public override explain (introspection: Introspection): void {
+  public override explain(introspection: Introspection): void {
     for (const [property, header] of Object.entries(this.value)) {
       const schema = take(introspection, property)
 
@@ -36,21 +38,23 @@ export class Headers extends Mapping<Record<string, string>> {
     }
   }
 
-  public properties (context: Input): Record<string, string> {
+  public properties(context: Input): Record<string, string> {
     context.pipelines.response.push((response) => {
       response.headers ??= new global.Headers()
 
-      for (const header of this.headers)
-        response.headers.append('vary', header)
+      for (const header of this.headers) response.headers.append('vary', header)
     })
 
-    return Object.entries(this.value).reduce((properties: Record<string, string>, [property, header]) => {
-      const value = context.request.headers[header]
+    return Object.entries(this.value).reduce(
+      (properties: Record<string, string>, [property, header]) => {
+        const value = context.request.headers[header]
 
-      if (value !== undefined)
-        properties[property] = Array.isArray(value) ? value.join(', ') : value
+        if (value !== undefined)
+          properties[property] = Array.isArray(value) ? value.join(', ') : value
 
-      return properties
-    }, {})
+        return properties
+      },
+      {}
+    )
   }
 }

package/source/directives/map/Language.ts

@@ -10,14 +10,18 @@ import type { Directive } from './Directive.js'
 export class Language extends Mapping<string> {
   private languages: string[] | null = null
 
-  public constructor (property: string) {
+  public constructor(property: string) {
     assert.ok(typeof property === 'string', '`map:language` must be a string')
 
     cors.allow('accept-language')
     super(property)
   }
 
-  public properties (context: Input, parameters: Parameter[], directives: Directive[]): Record<string, string> {
+  public properties(
+    context: Input,
+    parameters: Parameter[],
+    directives: Directive[]
+  ): Record<string, string> {
     this.languages ??= this.resolve(directives)
 
     const negotiator = new Negotiator(context.request)
@@ -32,10 +36,9 @@ export class Language extends Mapping<string> {
     return { [this.value]: language }
   }
 
-  private resolve (directives: Directive[]): string[] {
+  private resolve(directives: Directive[]): string[] {
     for (const directive of directives)
-      if (directive instanceof Languages)
-        return directive.value
+      if (directive instanceof Languages) return directive.value
 
     throw new Error('Supported languages are not defined, add `map:languages` directive')
   }

package/source/directives/map/Languages.ts

@@ -2,9 +2,15 @@ import assert from 'node:assert'
 import { Property } from './Properties.js'
 
 export class Languages extends Property<'languages'> {
-  public constructor (value: string[]) {
-    assert.ok(Array.isArray(value) && value.length > 0, '`map:languages` must be a non-empty array of strings')
-    assert.ok(value.every((language) => typeof language === 'string'), '`map:languages` must be an array of strings')
+  public constructor(value: string[]) {
+    assert.ok(
+      Array.isArray(value) && value.length > 0,
+      '`map:languages` must be a non-empty array of strings'
+    )
+    assert.ok(
+      value.every((language) => typeof language === 'string'),
+      '`map:languages` must be an array of strings'
+    )
 
     super('languages', value)
   }