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

package/source/directives/auth/Delegate.test.ts

@@ -0,0 +1,36 @@
+import assert from 'node:assert'
+import { describe, it } from 'node:test'
+import { Delegate } from './Delegate.js'
+import type { Introspection } from '../../Introspection.js'
+
+describe('auth:delegate', () => {
+  function explanation (): Introspection {
+    return {
+      input: {
+        type: 'object',
+        properties: {
+          identity: { type: 'object' },
+          title: { type: 'string' }
+        },
+        required: ['identity', 'title']
+      }
+    } as unknown as Introspection
+  }
+
+  it('should take the property it embeds out of the input', () => {
+    const delegate = new Delegate('identity', null as never)
+    const described = delegate.describe(explanation())
+    const input = described.input as { properties: object, required: string[] }
+
+    assert.deepStrictEqual(Object.keys(input.properties), ['title'])
+    assert.deepStrictEqual(input.required, ['title'])
+  })
+
+  it('should leave an input that does not declare it alone', () => {
+    const delegate = new Delegate('originator', null as never)
+    const described = delegate.describe(explanation())
+    const input = described.input as { properties: object }
+
+    assert.deepStrictEqual(Object.keys(input.properties), ['identity', 'title'])
+  })
+})

package/source/directives/auth/Delegate.ts

@@ -1,5 +1,7 @@
 import { BadRequest } from '../../HTTP/index.js'
+import { take } from '../../Introspection.js'
 import { Role } from './Role.js'
+import type { Introspection } from '../../Introspection.js'
 import type { Context, Directive, Identity } from './types.js'
 import type { Component } from '@toa.io/core'
 
@@ -22,6 +24,18 @@ export class Delegate implements Directive {
     return true
   }
 
+  /** It admits whoever there is, and embedding the identity is the request's business. */
+  public admits (identity: Identity | null): boolean {
+    return identity !== null
+  }
+
+  /** The property it embeds is the identity's, so a caller has nothing to put there. */
+  public describe (introspection: Introspection): Introspection {
+    take(introspection, this.property)
+
+    return introspection
+  }
+
   private embed (body: unknown, identity: Identity): Record<string, unknown> {
     if (body === undefined)
       body = {}

package/source/directives/auth/Echo.ts

@@ -12,6 +12,11 @@ export class Echo implements Directive {
     return true
   }
 
+  /** What `authorize` answers, without inventing the identity it would go on to invent. */
+  public admits (identity: Identity | null, context: Context): boolean {
+    return !(identity === null && 'authorization' in context.request.headers)
+  }
+
   public reply (context: Context): OutgoingMessage {
     const body = context.identity!
 

package/source/directives/auth/Incept.ts

@@ -61,8 +61,9 @@ export class Incept implements Directive {
       throw new http.UnprocessableEntity(identity)
 
     identity.scheme = scheme
-    identity.roles = []
 
+    // the roles are read where the token is minted: an Identity incepted as the principal
+    // has one already
     return identity
   }
 

package/source/directives/auth/Role.ts

@@ -36,6 +36,19 @@ export class Role implements Directive {
     return this.match(identity.roles, parameters)
   }
 
+  /** A role naming a route variable cannot be told from a description, which has no values. */
+  public async admits (identity: Identity | null): Promise<boolean | undefined> {
+    if (this.dynamic)
+      return undefined
+
+    if (identity === null)
+      return false
+
+    identity.roles ??= await Role.get(identity, this.discovery)
+
+    return this.match(identity.roles, [])
+  }
+
   private match (roles: string[], parameters: Parameter[]): boolean {
     const required = this.dynamic ? this.substitute(parameters) : this.roles
 

package/source/directives/auth/Rule.ts

@@ -1,4 +1,5 @@
 import { type Parameter } from '../../RTD/index.js'
+import type { Introspection } from '../../Introspection.js'
 import type { Context, Directive, Identity, Create } from './types.js'
 
 export class Rule implements Directive {
@@ -22,4 +23,32 @@ export class Rule implements Directive {
 
     return true
   }
+
+  /** Whatever each of them makes of it, in the order they were declared. */
+  public describe (introspection: Introspection): Introspection {
+    for (const directive of this.directives)
+      introspection = directive.describe?.(introspection) ?? introspection
+
+    return introspection
+  }
+
+  /** All of them, so one that refuses ends it and one that cannot tell leaves it untold. */
+  public async admits (identity: Identity | null, context: Context): Promise<boolean | undefined> {
+    let untold = false
+
+    for (const directive of this.directives) {
+      const admits = await directive.admits?.(identity, context)
+
+      if (admits === undefined) {
+        untold = true
+
+        continue
+      }
+
+      if (!admits)
+        return false
+    }
+
+    return untold ? undefined : true
+  }
 }

package/source/directives/auth/Scheme.ts

@@ -23,4 +23,9 @@ export class Scheme implements Directive {
 
     return false
   }
+
+  /** It admits nobody: it is there to refuse a scheme, not to authorize one. */
+  public admits (): boolean {
+    return false
+  }
 }

package/source/directives/auth/types.ts

@@ -1,6 +1,7 @@
 import { type Component } from '@toa.io/core'
 import { type Maybe } from '@toa.io/core'
 import { type Parameter } from '../../RTD/index.js'
+import type { Introspection } from '../../Introspection.js'
 import type * as http from '../../HTTP/index.js'
 import type * as io from '../../io.js'
 
@@ -13,6 +14,26 @@ export interface Directive {
     parameters: Parameter[]
   ) => boolean | Promise<boolean>
 
+  /**
+   * Whether this admits the identity where that can be told without a request — which is
+   * what describing a method is. `undefined` says it cannot be told: a directive reading a
+   * route variable's value or the body has neither here, and one that is not implemented
+   * says the same by its absence. Nothing here may have an effect on the request.
+   */
+  admits?: (
+    identity: Identity | null,
+    context: Context
+  ) => boolean | undefined | Promise<boolean | undefined>
+
+  /**
+   * What this directive makes of what the method says about itself, which is the reverse of
+   * what it does to a request: a property it fills from the identity is taken out of the
+   * input, because it is not the caller's to send — and a description that offers one invites
+   * a caller to name an identity that is not theirs. Nothing here may have an effect on the
+   * request.
+   */
+  describe?: (introspection: Introspection) => Introspection
+
   reply?: (context: Context) => http.OutgoingMessage | null
 
   settle?: (context: Context, response: http.OutgoingMessage) => Promise<void>

package/source/directives/cache/Cache.ts

@@ -18,7 +18,7 @@ export class Cache implements DirectiveFamily<Directive> {
     return new Class(value)
   }
 
-  public preflight (): Output {
+  public precall (): Output {
     return null
   }
 

package/source/directives/dev/Development.ts

@@ -19,7 +19,7 @@ export class Development implements DirectiveFamily<Directive> {
     return new Class(value)
   }
 
-  public async preflight (directives: Directive[], input: Input): Promise<Output> {
+  public async precall (directives: Directive[], input: Input): Promise<Output> {
     let output = null
 
     for (const directive of directives) {

package/source/directives/flow/Flow.ts

@@ -18,7 +18,7 @@ export class Flow implements DirectiveFamily<Directive> {
     return new Class(value, remotes)
   }
 
-  public async preflight (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)

package/source/directives/index.ts

@@ -5,11 +5,13 @@ import { dev } from './dev/index.js'
 import { octets } from './octets/index.js'
 import { io } from './io/index.js'
 import { map } from './map/index.js'
+import { mcp } from './mcp/index.js'
 import { req } from './require/index.js'
 import { flow } from './flow/index.js'
 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, 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/Directive.ts

@@ -4,7 +4,7 @@ import type { Input as Context } from '../../io.js'
 import type * as http from '../../HTTP/index.js'
 
 export interface Directive {
-  preflight: (context: Context, parameters: Parameter[]) => void
+  precall: (context: Context, parameters: Parameter[]) => void
 
   /** Synchronous by contract: settling holds the response, and none of it needs I/O. */
   settle?: (context: Context, response: http.OutgoingMessage) => void

package/source/directives/io/IO.ts

@@ -1,3 +1,4 @@
+import { restrict } from '../../Introspection.js'
 import { Output } from './Output.js'
 import { Input } from './Input.js'
 import { Throttle } from './Throttle.js'
@@ -7,6 +8,7 @@ import type * as http from '../../HTTP/index.js'
 import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
 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'
 
@@ -38,22 +40,49 @@ export class IO implements DirectiveFamily<Directive> {
     return new Directive(value, this.sync!, route)
   }
 
-  public preflight (directives: Directive[], context: http.Context,
+  public precall (directives: Directive[], context: http.Context,
     parameters: Parameter[]): null {
     let restricted = false
 
     for (const directive of directives) {
       restricted ||= directive instanceof Output
 
-      directive.preflight(context, parameters)
+      directive.precall(context, parameters)
     }
 
     if (!restricted)
-      DENIAL.preflight(context, parameters)
+      DENIAL.precall(context, parameters)
 
     return null
   }
 
+  /**
+   * 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 {
+    let restricted = false
+
+    for (const directive of directives) {
+      if (directive instanceof Input)
+        introspection.input = restrict(introspection.input, directive.allowed)
+
+      if (!(directive instanceof Output))
+        continue
+
+      restricted = true
+
+      if (!directive.disabled)
+        introspection.output = restrict(introspection.output, directive.allowed)
+    }
+
+    if (!restricted)
+      delete introspection.output
+
+    return introspection
+  }
+
   public settle (directives: Directive[], context: http.Context,
     output: http.OutgoingMessage): void {
     for (const directive of directives)

package/source/directives/io/Input.ts

@@ -5,7 +5,8 @@ import type { Directive } from './Directive.js'
 import type { Input as Context } from '../../io.js'
 
 export class Input implements Directive {
-  private readonly allowed: Set<string>
+  /** what a client may send, which is therefore what the input schema states */
+  public readonly allowed: Set<string>
 
   public constructor (permissions: Permissions) {
     this.allowed = new Set(permissions)
@@ -15,7 +16,7 @@ export class Input implements Directive {
     schemas.input.validate<Permissions>(permissions, 'Incorrect \'io:input\' format')
   }
 
-  public preflight (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,

package/source/directives/io/Output.ts

@@ -7,10 +7,13 @@ import type { Input as Context } from '../../io.js'
 import type { OutgoingMessage } from '../../HTTP/index.js'
 
 export class Output implements Directive {
-  private readonly disabled: boolean = false
+  /** whether the reply passes whole, which is when the schema is the operation's own */
+  public readonly disabled: boolean = false
+
+  /** what a reply may carry, which is therefore what the output schema states */
+  public readonly allowed: Set<string>
   private readonly omitted: boolean = true
   private readonly permissions: string[] = []
-  private readonly allowed: Set<string>
 
   public constructor (permissions: Permissions) {
     if (typeof permissions === 'boolean')
@@ -29,7 +32,7 @@ export class Output implements Directive {
     schemas.output.validate(permissions, 'Incorrect \'io:output\' format')
   }
 
-  public preflight (context: Context): void {
+  public precall (context: Context): void {
     context.pipelines.response.push(this.restriction(context))
   }
 

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

@@ -47,7 +47,7 @@ it('should have a reply it named the status of restricted, whatever that status
     const ctx = context()
     const output = new Output(['code', 'error'])
 
-    output.preflight(ctx, [])
+    output.precall(ctx, [])
 
     const response: OutgoingMessage = {
       body: { status: stated, code: 'SplxlO', error: 'invalid_grant', secret: 'x' }
@@ -67,7 +67,7 @@ it('should leave a failure the gateway built alone, on such a route too', () =>
   const ctx = context()
   const output = new Output(['code'])
 
-  output.preflight(ctx, [])
+  output.precall(ctx, [])
 
   // what `Server.fail` builds out of an exception, on a route that also declares `io:status`
   const response: OutgoingMessage = {

package/source/directives/io/Status.ts

@@ -23,7 +23,7 @@ export class Status implements Directive {
     assert.ok(typeof value === 'string', '`io:status` must be a string')
   }
 
-  public preflight (): void {
+  public precall (): void {
     // nothing to do until the operation has answered
   }
 

package/source/directives/io/Throttle.ts

@@ -18,7 +18,7 @@ export class Throttle implements Directive {
     schemas.throttle.validate(declaration, 'Incorrect \'io:throttle\' format')
   }
 
-  public preflight (context: http.Context, parameters: Parameter[]): void {
+  public precall (context: http.Context, parameters: Parameter[]): void {
     const retry = this.quotas.check(context, parameters)
 
     if (retry > 0)

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

@@ -34,7 +34,7 @@ export class Quotas {
   private readonly entries = new Map<string, Entry>()
 
   /**
-   * The key computed at preflight, for settle to charge against.
+   * The key computed at precall, for settle to charge against.
    *
    * `segment` reads the route parameters, which settle is not given, and `identity`
    * can be refreshed between the two — so recomputing there would key a request
@@ -97,7 +97,7 @@ export class Quotas {
     if (!this.conditional || !this.keys.matches(input, output))
       return
 
-    // preflight always runs first, and a request it refuses never reaches settle
+    // 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)

package/source/directives/map/Headers.ts

@@ -1,7 +1,9 @@
 import assert from 'node:assert'
 import { cors } from '../cors/index.js'
 import { Mapping } from './Mapping.js'
+import { take } from '../../Introspection.js'
 import type { Input } from '../../io.js'
+import type { Introspection } from '../../Introspection.js'
 
 /**
  * Forbidden request header names: the browser sets them itself and a script cannot
@@ -25,6 +27,15 @@ export class Headers extends Mapping<Record<string, string>> {
     this.headers.forEach((header) => cors.allow(header))
   }
 
+  public override explain (introspection: Introspection): void {
+    for (const [property, header] of Object.entries(this.value)) {
+      const schema = take(introspection, property)
+
+      introspection.headers ??= {}
+      introspection.headers[property] = { ...schema, header }
+    }
+  }
+
   public properties (context: Input): Record<string, string> {
     context.pipelines.response.push((response) => {
       response.headers ??= new global.Headers()

package/source/directives/map/Map.ts

@@ -12,6 +12,7 @@ import type { Directive } from './Directive.js'
 import type { Properties } from './Properties.js'
 import type { DirectiveFamily, Parameter } from '../../RTD/index.js'
 import type { Input, Output } from '../../io.js'
+import type { Introspection } from '../../Introspection.js'
 import type { Remotes } from '../../Remotes.js'
 
 export class Map implements DirectiveFamily {
@@ -31,7 +32,15 @@ export class Map implements DirectiveFamily {
       })
   }
 
-  public async preflight (directives: Directive[], context: Input, parameters: Parameter[]): Promise<Output> {
+  public explain (directives: Directive[], _: Input, introspection: Introspection): Introspection {
+    for (const directive of directives)
+      if (directive instanceof Mapping)
+        directive.explain(introspection)
+
+    return introspection
+  }
+
+  public async precall (directives: Directive[], context: Input, parameters: Parameter[]): Promise<Output> {
     const properties = {}
 
     for (const directive of directives)

package/source/directives/map/Mapping.ts

@@ -1,7 +1,9 @@
+import { take } from '../../Introspection.js'
 import type { Remotes } from '../../Remotes.js'
 import type { Directive } from './Directive.js'
 import type { Input } from '../../io.js'
 import type { Parameter } from '../../RTD/index.js'
+import type { Introspection } from '../../Introspection.js'
 
 export abstract class Mapping<T = unknown> {
   protected value: T
@@ -13,6 +15,27 @@ export abstract class Mapping<T = unknown> {
   }
 
   public abstract properties (context: Input, parameters: Parameter[], directives: Directive[]): Output
+
+  /**
+   * What this mapping does to what the method says about itself, which is the reverse of
+   * what it does to a request: a property the gateway fills is taken out of the input,
+   * because it is not the caller's to send.
+   *
+   * The default says nothing more than that. A claim, an authority and a language come
+   * from the request itself and there is nowhere for a caller to put one; a header and a
+   * segment are the caller's, and those say where.
+   */
+  public explain (introspection: Introspection): void {
+    for (const property of this.names())
+      take(introspection, property)
+  }
+
+  /** The input properties this mapping fills, however its value names them. */
+  protected names (): string[] {
+    return typeof this.value === 'string'
+      ? [this.value]
+      : Object.keys(this.value as object)
+  }
 }
 
 type Properties = Record<string, unknown> | null

package/source/directives/map/Segments.ts

@@ -1,6 +1,8 @@
 import assert from 'node:assert'
 import { Mapping } from './Mapping.js'
+import { take } from '../../Introspection.js'
 import type { Parameter } from '../../RTD/index.js'
+import type { Introspection, Schema } from '../../Introspection.js'
 
 export class Segments extends Mapping<Record<string, string>> {
   public constructor (map: Record<string, string>) {
@@ -12,6 +14,16 @@ export class Segments extends Mapping<Record<string, string>> {
     super(map)
   }
 
+  /** A segment is the caller's, so it moves to the route rather than out of sight. */
+  public override explain (introspection: Introspection): void {
+    for (const property of Object.keys(this.value)) {
+      const schema = take(introspection, property)
+
+      introspection.route ??= {}
+      introspection.route[property] = schema ?? ({ type: 'string' } as unknown as Schema)
+    }
+  }
+
   public override properties (_: unknown, parameters: Parameter[]): Record<string, string> {
     return Object.entries(this.value).reduce((properties: Record<string, string>, [property, parameter]) => {
       const cut = parameter[0] === '~'

package/source/directives/mcp/MCP.ts

@@ -0,0 +1,40 @@
+import assert from 'node:assert'
+import { Tool } from './Tool.js'
+import type { Context } from '../../HTTP/index.js'
+import type { Introspection } from '../../Introspection.js'
+import type { DirectiveFamily } from '../../RTD/index.js'
+
+/** The name the family is declared under, and what `MCP` asks a method for. */
+export const FAMILY = 'mcp'
+
+export class MCP implements DirectiveFamily<Tool> {
+  public readonly name = FAMILY
+  public readonly mandatory = false
+
+  /** What this method is published as, which is what the nearest declaration says. */
+  public static published (directives: Tool[] | undefined): Tool | null {
+    return directives?.[0] ?? null
+  }
+
+  // eslint-disable-next-line max-params
+  public create (name: string, value: unknown, _: unknown, route: string): Tool {
+    assert.ok(name === 'tool', `Unknown directive: mcp:${name}`)
+
+    return new Tool(value, route)
+  }
+
+  /** What the route states this method is, which is the only thing that states it. */
+  public explain (directives: Tool[], _: Context,
+    introspection: Introspection): Introspection {
+    const tool = MCP.published(directives)
+
+    if (tool === null)
+      return introspection
+
+    return {
+      ...introspection,
+      description: tool.description,
+      ...tool.title === undefined ? {} : { title: tool.title }
+    }
+  }
+}