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

package/source/directives/flow/Fetch.ts

@@ -5,7 +5,7 @@ import { NotFound } from '../../HTTP/index.js'
 import type { Directive } from './types.js'
 import type { ReadableStream } from 'node:stream/web'
 import type { Remotes } from '../../Remotes.js'
-import type { Maybe } from '@toa.io/core'
+import type { Maybe } from '@toa.io/core/types'
 import type { Component } from '@toa.io/core'
 import type { Output } from '../../io.js'
 import type { Input } from '../octets/types.js'
@@ -16,7 +16,7 @@ export class Fetch implements Directive {
   private remote: Component | null = null
   private readonly operation: string
 
-  public constructor (endpoint: string, discovery: Remotes) {
+  public constructor(endpoint: string, discovery: Remotes) {
     assert.equal(typeof endpoint, 'string', '`flow:fetch` must be a string')
 
     const [operation, name, namespace = 'default'] = endpoint.split('.').reverse()
@@ -25,9 +25,8 @@ export class Fetch implements Directive {
     this.connecting = discovery.discover(namespace, name)
   }
 
-  public async apply (input: Input, parameters: Parameter[]): Promise<Output> {
-    if ('if-none-match' in input.request.headers)
-      return { status: 304 }
+  public async apply(input: Input, parameters: Parameter[]): Promise<Output> {
+    if ('if-none-match' in input.request.headers) return { status: 304 }
 
     this.remote ??= await this.connecting
 
@@ -39,11 +38,12 @@ export class Fetch implements Directive {
       }
     })
 
-    if (request instanceof Error)
-      throw new NotFound(request)
+    if (request instanceof Error) throw new NotFound(request)
 
-    const { url, options } = match<Request>(request,
-      String, { url: request },
+    const { url, options } = match<Request>(
+      request,
+      String,
+      { url: request },
       (request: Request): Request => ({
         url: request.url,
         options: {
@@ -51,25 +51,25 @@ export class Fetch implements Directive {
           body: request.options?.body,
           headers: request.options?.headers
         }
-      }))
+      })
+    )
 
     const response = await fetch(url, options)
 
-    if (!response.ok)
-      throw new NotFound()
+    if (!response.ok) throw new NotFound()
 
     const headers = new Headers()
 
     for (const header of ['content-type', 'content-length', 'etag']) {
       const value = response.headers.get(header)
 
-      if (value !== null)
-        headers.set(header, value)
+      if (value !== null) headers.set(header, value)
     }
 
     return {
       headers,
-      body: response.body === null ? null : Readable.fromWeb(response.body as ReadableStream)
+      body:
+        response.body === null ? null : Readable.fromWeb(response.body as ReadableStream)
     }
   }
 }

package/source/directives/flow/Flow.ts

@@ -9,7 +9,7 @@ export class Flow implements DirectiveFamily<Directive> {
   public readonly name: string = 'flow'
   public readonly mandatory: boolean = false
 
-  public create (name: string, value: unknown, remotes: Remotes): Directive {
+  public create(name: string, value: unknown, remotes: Remotes): Directive {
     const Class = constructors[name]
 
     if (Class === undefined)
@@ -18,18 +18,19 @@ export class Flow implements DirectiveFamily<Directive> {
     return new Class(value, remotes)
   }
 
-  public async precall (directives: Directive[], input: Input, parameters: Parameter[]): Promise<Output> {
+  public async precall(
+    directives: Directive[],
+    input: Input,
+    parameters: Parameter[]
+  ): Promise<Output> {
     for (const directive of directives) {
-      if (directive.attach !== undefined)
-        directive.attach(input)
+      if (directive.attach !== undefined) directive.attach(input)
 
-      if (directive.apply === undefined)
-        continue
+      if (directive.apply === undefined) continue
 
       const output = await directive.apply(input, parameters)
 
-      if (output !== null)
-        return output
+      if (output !== null) return output
     }
 
     return null

package/source/directives/index.ts

@@ -12,6 +12,15 @@ import { discovery } from './oauth/index.js'
 import type { DirectiveFamily } from '../RTD/index.js'
 import type { Interceptor } from '../Interception.js'
 
-export const families: DirectiveFamily[] =
-  [authorization, io, cache, map, mcp, req, flow, octets, dev]
+export const families: DirectiveFamily[] = [
+  authorization,
+  io,
+  cache,
+  map,
+  mcp,
+  req,
+  flow,
+  octets,
+  dev
+]
 export const interceptors: Interceptor[] = [cors, discovery]

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[]
 }