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

package/source/directives/io/IO.ts

@@ -10,7 +10,7 @@ import type { Remotes } from '../../Remotes.js'
 import type { Constructor, Directive } from './Directive.js'
 import type { Introspection } from '../../Introspection.js'
 import { ATOM_GROUP } from '../../const.js'
-import type { extensions } from '@toa.io/core'
+import type { extensions } from '@toa.io/core/types'
 
 export class IO implements DirectiveFamily<Directive> {
   public readonly name = 'io'
@@ -21,12 +21,17 @@ export class IO implements DirectiveFamily<Directive> {
   /** Throttling reconciles through the atom of the gateways, one for every directive. */
   private sync: Sync | null = null
 
-  public mount (host: extensions.Host): void {
+  public mount(host: extensions.Host): void {
     this.host = host
   }
 
   // eslint-disable-next-line max-params
-  public create (name: string, value: unknown, remotes: Remotes, route: string): Directive {
+  public create(
+    name: string,
+    value: unknown,
+    remotes: Remotes,
+    route: string
+  ): Directive {
     if (!(name in constructors))
       throw new Error(`Directive 'io:${name}' is not implemented`)
 
@@ -34,14 +39,16 @@ export class IO implements DirectiveFamily<Directive> {
 
     Directive.validate(value)
 
-    if (name === 'throttle')
-      this.sync ??= new Sync(this.host.atom(ATOM_GROUP))
+    if (name === 'throttle') this.sync ??= new Sync(this.host.atom(ATOM_GROUP))
 
     return new Directive(value, this.sync!, route)
   }
 
-  public precall (directives: Directive[], context: http.Context,
-    parameters: Parameter[]): null {
+  public precall(
+    directives: Directive[],
+    context: http.Context,
+    parameters: Parameter[]
+  ): null {
     let restricted = false
 
     for (const directive of directives) {
@@ -50,8 +57,7 @@ export class IO implements DirectiveFamily<Directive> {
       directive.precall(context, parameters)
     }
 
-    if (!restricted)
-      DENIAL.precall(context, parameters)
+    if (!restricted) DENIAL.precall(context, parameters)
 
     return null
   }
@@ -60,16 +66,18 @@ export class IO implements DirectiveFamily<Directive> {
    * What a whitelist admits is what the schema states. Without an `io:output` the reply is
    * dropped before it is sent, so there is no output to describe at all.
    */
-  public explain (directives: Directive[], _: http.Context,
-    introspection: Introspection): Introspection {
+  public explain(
+    directives: Directive[],
+    _: http.Context,
+    introspection: Introspection
+  ): Introspection {
     let restricted = false
 
     for (const directive of directives) {
       if (directive instanceof Input)
         introspection.input = restrict(introspection.input, directive.allowed)
 
-      if (!(directive instanceof Output))
-        continue
+      if (!(directive instanceof Output)) continue
 
       restricted = true
 
@@ -77,16 +85,17 @@ export class IO implements DirectiveFamily<Directive> {
         introspection.output = restrict(introspection.output, directive.allowed)
     }
 
-    if (!restricted)
-      delete introspection.output
+    if (!restricted) delete introspection.output
 
     return introspection
   }
 
-  public settle (directives: Directive[], context: http.Context,
-    output: http.OutgoingMessage): void {
-    for (const directive of directives)
-      directive.settle?.(context, output)
+  public settle(
+    directives: Directive[],
+    context: http.Context,
+    output: http.OutgoingMessage
+  ): void {
+    for (const directive of directives) directive.settle?.(context, output)
   }
 
   /**
@@ -94,7 +103,7 @@ export class IO implements DirectiveFamily<Directive> {
    * factory disposes every route it made — so this runs once per route at shutdown,
    * and disposing an already stopped ticker is what makes that harmless.
    */
-  public dispose (): void {
+  public dispose(): void {
     this.sync?.dispose()
   }
 }

package/source/directives/io/Input.ts

@@ -8,15 +8,15 @@ export class Input implements Directive {
   /** what a client may send, which is therefore what the input schema states */
   public readonly allowed: Set<string>
 
-  public constructor (permissions: Permissions) {
+  public constructor(permissions: Permissions) {
     this.allowed = new Set(permissions)
   }
 
-  public static validate (permissions: unknown): asserts permissions is Permissions {
-    schemas.input.validate<Permissions>(permissions, 'Incorrect \'io:input\' format')
+  public static validate(permissions: unknown): asserts permissions is Permissions {
+    schemas.input.validate<Permissions>(permissions, "Incorrect 'io:input' format")
   }
 
-  public precall (context: Context): void {
+  public precall(context: Context): void {
     // Restrictions are on what the client sent, so the check goes to the front of the
     // pipeline whatever order the families ran in: `auth:delegate` embeds the identity
     // and `map:*` assigns mapped properties, and those additions are the server's own,
@@ -24,9 +24,8 @@ export class Input implements Directive {
     context.pipelines.body.unshift((body) => this.check(body))
   }
 
-  private check (body: unknown): Message | Message[] | undefined {
-    if (body === undefined)
-      return body
+  private check(body: unknown): Message | Message[] | undefined {
+    if (body === undefined) return body
 
     try {
       schemas.message.validate<Message | Message[]>(body)
@@ -36,21 +35,19 @@ export class Input implements Directive {
 
     const property = this.violation(body)
 
-    if (property !== undefined)
-      throw new BadRequest(`Unexpected input: ${property}`)
+    if (property !== undefined) throw new BadRequest(`Unexpected input: ${property}`)
 
     return body
   }
 
-  private violation (value: Message | Message[]): string | undefined {
+  private violation(value: Message | Message[]): string | undefined {
     if (!Array.isArray(value))
       return Object.keys(value).find((key) => !this.allowed.has(key))
 
     for (const item of value) {
       const property = this.violation(item)
 
-      if (property !== undefined)
-        return property
+      if (property !== undefined) return property
     }
   }
 }

package/source/directives/io/Output.ts

@@ -15,28 +15,24 @@ export class Output implements Directive {
   private readonly omitted: boolean = true
   private readonly permissions: string[] = []
 
-  public constructor (permissions: Permissions) {
+  public constructor(permissions: Permissions) {
     if (typeof permissions === 'boolean')
-      if (permissions)
-        this.disabled = true
-      else
-        this.omitted = false
-
-    else
-      this.permissions = permissions
+      if (permissions) this.disabled = true
+      else this.omitted = false
+    else this.permissions = permissions
 
     this.allowed = new Set(this.permissions)
   }
 
-  public static validate (permissions: unknown): asserts permissions is Permissions {
-    schemas.output.validate(permissions, 'Incorrect \'io:output\' format')
+  public static validate(permissions: unknown): asserts permissions is Permissions {
+    schemas.output.validate(permissions, "Incorrect 'io:output' format")
   }
 
-  public precall (context: Context): void {
+  public precall(context: Context): void {
     context.pipelines.response.push(this.restriction(context))
   }
 
-  private restriction (context: Context) {
+  private restriction(context: Context) {
     return (message: OutgoingMessage): void => {
       // what the gateway built is its own — a code and a message — and a restriction has
       // nothing to say about it; everything else is a reply the operation returned, and is
@@ -45,37 +41,38 @@ export class Output implements Directive {
       const stream = message.body instanceof Stream
       const none = message.body === undefined || message.body === null
 
-      if (this.disabled || error || stream || none)
-        return
+      if (this.disabled || error || stream || none) return
 
       if (typeof message.body !== 'object' || this.permissions.length === 0) {
         if (this.omitted)
-          console.warn('Permissions for \'io:output\' are not specified properly, response omitted',
-            { path: context.url.pathname })
+          console.warn(
+            "Permissions for 'io:output' are not specified properly, response omitted",
+            { path: context.url.pathname }
+          )
 
         delete message.body
 
         return
       }
 
-      schemas.message.validate<Message>(message.body,
-        '\'io:output\' expects response to be an object or array of objects')
+      schemas.message.validate<Message>(
+        message.body,
+        "'io:output' expects response to be an object or array of objects"
+      )
 
       if (Array.isArray(message.body))
         message.body = message.body.map((entity) => this.fit(entity as Message))
-      else
-        message.body = this.fit(message.body)
+      else message.body = this.fit(message.body)
     }
   }
 
   /** Runs per entity of a collection, hence the set and the absence of intermediates. */
-  private fit (message: Message): Message {
+  private fit(message: Message): Message {
     const output: Message = {}
 
     // the keys of the entity, so that the response keeps the order it was built in
     for (const key of Object.keys(message))
-      if (this.allowed.has(key))
-        output[key] = message[key]
+      if (this.allowed.has(key)) output[key] = message[key]
 
     return output
   }

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

@@ -8,8 +8,11 @@ import type { OutgoingMessage } from '../../HTTP/index.js'
 
 const status = new Status('status')
 
-function context (): Context {
-  return { pipelines: { body: [], response: [] }, url: { pathname: '/' } } as unknown as Context
+function context(): Context {
+  return {
+    pipelines: { body: [], response: [] },
+    url: { pathname: '/' }
+  } as unknown as Context
 }
 
 it('should take the status from the property and remove it', () => {
@@ -55,8 +58,7 @@ it('should have a reply it named the status of restricted, whatever that status
 
     status.settle(ctx, response)
 
-    for (const transform of ctx.pipelines.response)
-      transform(response)
+    for (const transform of ctx.pipelines.response) transform(response)
 
     assert.equal(response.status, stated)
     assert.deepEqual(response.body, { code: 'SplxlO', error: 'invalid_grant' })
@@ -76,9 +78,11 @@ it('should leave a failure the gateway built alone, on such a route too', () =>
     body: { code: 'NOT_FOUND', message: 'nope' }
   }
 
-  for (const transform of ctx.pipelines.response)
-    transform(response)
+  for (const transform of ctx.pipelines.response) transform(response)
 
-  assert.deepEqual(response.body, { code: 'NOT_FOUND', message: 'nope' },
-    'a code and a message are not what a restriction has anything to say about')
+  assert.deepEqual(
+    response.body,
+    { code: 'NOT_FOUND', message: 'nope' },
+    'a code and a message are not what a restriction has anything to say about'
+  )
 })

package/source/directives/io/Status.ts

@@ -15,28 +15,29 @@ import type * as http from '../../HTTP/index.js'
 export class Status implements Directive {
   private readonly property: string
 
-  public constructor (property: unknown) {
+  public constructor(property: unknown) {
     this.property = property as string
   }
 
-  public static validate (value: unknown): asserts value is string {
+  public static validate(value: unknown): asserts value is string {
     assert.ok(typeof value === 'string', '`io:status` must be a string')
   }
 
-  public precall (): void {
+  public precall(): void {
     // nothing to do until the operation has answered
   }
 
-  public settle (_: unknown, response: http.OutgoingMessage): void {
+  public settle(_: unknown, response: http.OutgoingMessage): void {
     const body: unknown = response.body
 
-    if (body === null || typeof body !== 'object' || !(this.property in body))
-      return
+    if (body === null || typeof body !== 'object' || !(this.property in body)) return
 
     const value: unknown = (body as Record<string, unknown>)[this.property]
 
-    assert.ok(typeof value === 'number',
-      `\`io:status\` expects '${this.property}' to be a number`)
+    assert.ok(
+      typeof value === 'number',
+      `\`io:status\` expects '${this.property}' to be a number`
+    )
 
     response.status = value
 

package/source/directives/io/Throttle.ts

@@ -8,24 +8,23 @@ import type { Directive } from './Directive.js'
 export class Throttle implements Directive {
   private readonly quotas: Quotas
 
-  public constructor (declaration: Declaration, sync: Sync, route: string) {
+  public constructor(declaration: Declaration, sync: Sync, route: string) {
     this.quotas = Quotas.create(parse(declaration), route)
 
     sync.register(this.quotas)
   }
 
-  public static validate (declaration: unknown): asserts declaration is Declaration {
-    schemas.throttle.validate(declaration, 'Incorrect \'io:throttle\' format')
+  public static validate(declaration: unknown): asserts declaration is Declaration {
+    schemas.throttle.validate(declaration, "Incorrect 'io:throttle' format")
   }
 
-  public precall (context: http.Context, parameters: Parameter[]): void {
+  public precall(context: http.Context, parameters: Parameter[]): void {
     const retry = this.quotas.check(context, parameters)
 
-    if (retry > 0)
-      throw new TooManyRequests(retry)
+    if (retry > 0) throw new TooManyRequests(retry)
   }
 
-  public settle (context: http.Context, output: http.OutgoingMessage): void {
+  public settle(context: http.Context, output: http.OutgoingMessage): void {
     this.quotas.use(context, output)
   }
 }

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

@@ -22,23 +22,29 @@ it('should convert key', () => {
 })
 
 it('should convert condition', () => {
-  assert.partialDeepStrictEqual(parse({ key: ['ip', 'path'], condition: { status: '404' }, ...rest }), {
-    condition: [
-      {
-        method: 'status',
-        options: '404'
-      }
-    ]
-  })
+  assert.partialDeepStrictEqual(
+    parse({ key: ['ip', 'path'], condition: { status: '404' }, ...rest }),
+    {
+      condition: [
+        {
+          method: 'status',
+          options: '404'
+        }
+      ]
+    }
+  )
 
-  assert.partialDeepStrictEqual(parse({ key: 'ip', condition: { status: '404' }, ...rest }), {
-    condition: [
-      {
-        method: 'status',
-        options: '404'
-      }
-    ]
-  })
+  assert.partialDeepStrictEqual(
+    parse({ key: 'ip', condition: { status: '404' }, ...rest }),
+    {
+      condition: [
+        {
+          method: 'status',
+          options: '404'
+        }
+      ]
+    }
+  )
 })
 
 it('should convert a key component that takes an argument', () => {
@@ -53,11 +59,14 @@ it('should convert a key component that takes an argument', () => {
 })
 
 it('should convert a mixed key', () => {
-  assert.partialDeepStrictEqual(parse({ key: ['route', { segment: 'id' }, 'identity'], ...rest }), {
-    key: [
-      { method: 'route' },
-      { method: 'segment', options: 'id' },
-      { method: 'identity' }
-    ]
-  })
+  assert.partialDeepStrictEqual(
+    parse({ key: ['route', { segment: 'id' }, 'identity'], ...rest }),
+    {
+      key: [
+        { method: 'route' },
+        { method: 'segment', options: 'id' },
+        { method: 'identity' }
+      ]
+    }
+  )
 })

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

@@ -21,7 +21,7 @@ type KeyEntry = KeyComponentMethod | { segment: string }
 type KeyDeclaration = KeyEntry | KeyEntry[]
 
 type ConditionDeclaration =
-  Record<KeyConditionMethod, unknown>
+  | Record<KeyConditionMethod, unknown>
   | Array<Record<KeyConditionMethod, unknown>>
 
 export interface Declaration extends Omit<Configuration, 'key' | 'condition'> {
@@ -29,7 +29,7 @@ export interface Declaration extends Omit<Configuration, 'key' | 'condition'> {
   condition?: ConditionDeclaration
 }
 
-export function parse (declaration: Declaration): Configuration {
+export function parse(declaration: Declaration): Configuration {
   const { key, condition, requests, interval } = declaration
 
   return {
@@ -40,24 +40,29 @@ export function parse (declaration: Declaration): Configuration {
   }
 }
 
-function mapKey (declaration: KeyDeclaration): KeyComponent[] {
+function mapKey(declaration: KeyDeclaration): KeyComponent[] {
   const entries = Array.isArray(declaration) ? declaration : [declaration]
 
   // a bare `path`, or `segment: id` for the ones that take an argument
   return entries.flatMap((entry): KeyComponent[] =>
     typeof entry === 'string'
       ? [{ method: entry }]
-      : Object.entries(entry).map(([method, options]) =>
-        ({ method: method as KeyComponentMethod, options })))
+      : Object.entries(entry).map(([method, options]) => ({
+          method: method as KeyComponentMethod,
+          options
+        }))
+  )
 }
 
-function mapCondition (declaration?: ConditionDeclaration): KeyCondition[] | undefined {
-  if (declaration === undefined)
-    return
+function mapCondition(declaration?: ConditionDeclaration): KeyCondition[] | undefined {
+  if (declaration === undefined) return
 
   // reduce to a single object, then map entries to rules
   const conditions = Array.isArray(declaration) ? declaration : [declaration]
   const single = conditions.reduce((acc, condition) => ({ ...acc, ...condition }), {})
 
-  return Object.entries(single).map(([method, options]) => ({ method, options })) as KeyCondition[]
+  return Object.entries(single).map(([method, options]) => ({
+    method,
+    options
+  })) as KeyCondition[]
 }

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)
 }