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

package/source/RTD/Directives.ts

@@ -2,18 +2,36 @@ import type { Parameter } from './Match.js'
 import type * as syntax from './syntax/index.js'
 import type { Context, OutgoingMessage, Options } from '../HTTP/index.js'
 import type { Output } from '../io.js'
+import type { Introspection } from '../Introspection.js'
 import type { extensions } from '@toa.io/core'
 
 type Host = extensions.Host
 
 export interface Directives {
-  preflight: (context: Context, parameters: Parameter[]) => Promise<Output>
+  /**
+   * The directives of one family on this method, or nothing where it declares none of it.
+   * For a consumer of a declaration rather than of a stage: what a method is published as
+   * is stated on the route, and read where the publishing happens.
+   */
+  declared: <T>(family: string) => T[] | undefined
+
+  precall: (context: Context, parameters: Parameter[]) => Promise<Output>
+
+  /** What this route's directives make of what its method says about itself. */
+  explain: (context: Context, introspection: Introspection) => Promise<Introspection | null>
   settle: (context: Context, response: OutgoingMessage) => Promise<void>
   dispose: () => void
 }
 
 export interface DirectiveFactory {
   create: (directives: syntax.Directive[], route: string) => Directives
+
+  /** Runs every family's `preflight`, which is request-scoped and needs no node. */
+  preflight: (context: Context) => Promise<void>
+
+  /** Runs every family's `depart`, the counterpart of `preflight`. */
+  depart: (context: Context, response: OutgoingMessage) => Promise<void>
+
   dispose: () => void
 }
 
@@ -43,13 +61,45 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
    */
   arrange?: (directives: TDirective[]) => void
 
-  preflight?: (directives: TDirective[],
+  /**
+   * Request-scoped, before anything is routed. It takes no directives: no node is known
+   * yet, and a request that carries several calls has no single node at all. What a
+   * directive declares is call-scoped by definition, so only what a family does on its
+   * own behalf — authenticating a credential — belongs here. It answers nothing: a stage
+   * that runs before a route is known has no reply to make, and refuses by throwing.
+   */
+  preflight?: (request: Context & TExtension) => void | Promise<void>
+
+  /** Call-scoped, with what the node declares. Runs once per call. */
+  precall?: (directives: TDirective[],
     request: Context & TExtension,
     parameters: Parameter[]) => Output | Promise<Output>
 
+  /**
+   * What this family's directives make of what the method says about itself, which is
+   * what `OPTIONS` answers and what a tool is described by. `null` refuses: the method
+   * is not reachable by this caller, and is not described at all.
+   *
+   * There is no request here — no route variable has a value and no body has arrived, which
+   * is why no parameters are passed — so a directive that can only tell from one hands back
+   * what it was given.
+   */
+  explain?: (directives: TDirective[],
+    request: Context & TExtension,
+    introspection: Introspection) => Introspection | null | Promise<Introspection | null>
+
+  /** Call-scoped, on the message that call produced. */
   settle?: (directives: TDirective[],
     request: Context & TExtension,
     response: OutgoingMessage) => void | Promise<void>
 
+  /**
+   * Request-scoped, on the message going back — the counterpart of `preflight`, and
+   * likewise without directives. A reply the whole request carries, such as a re-issued
+   * credential, is written here rather than by a call that would not own it.
+   */
+  depart?: (request: Context & TExtension,
+    response: OutgoingMessage) => void | Promise<void>
+
   dispose?: (directives: TDirective[]) => void
 }

package/source/RTD/Endpoint.ts

@@ -2,11 +2,12 @@ import { type Context } from './Context.js'
 import type * as http from '../HTTP/index.js'
 import type * as syntax from './syntax/index.js'
 import type * as RTD from './index.js'
+import type { Introspection } from '../Introspection.js'
 
 export interface Endpoint {
   call: (context: http.Context, parameters: RTD.Parameter[]) => Promise<http.OutgoingMessage>
 
-  explain: (parameters: RTD.Parameter[]) => Promise<unknown>
+  explain: (parameters: RTD.Parameter[]) => Promise<Introspection>
 
   close: () => Promise<void>
 }

package/source/RTD/Method.ts

@@ -1,29 +1,32 @@
 import type { Parameter } from './Match.js'
 import type { Endpoint } from './Endpoint.js'
 import type { Directives } from './Directives.js'
+import type { Context } from '../HTTP/index.js'
+import { order } from '../Introspection.js'
+import type { Introspection } from '../Introspection.js'
 
 export class Method {
   public readonly endpoint: Endpoint | null
   public readonly directives: Directives
-  private introspection: unknown | null = null
-  private introspecting: Promise<unknown> | null = null
 
   public constructor (endpoint: Endpoint | null, directives: Directives) {
     this.endpoint = endpoint
     this.directives = directives
   }
 
-  public async explain (parameters: Parameter[]): Promise<unknown> {
-    if (this.introspection !== null)
-      return this.introspection
+  /**
+   * What this method says about itself, as its directives leave it, or nothing where they
+   * refuse this caller. A method of no endpoint — one a directive answers on its own —
+   * states nothing of its own, and its directives still have their say.
+   */
+  public async explain (context: Context, parameters: Parameter[]): Promise<Introspection | null> {
+    const introspection = this.endpoint === null
+      ? {}
+      : await this.endpoint.explain(parameters)
 
-    if (this.introspecting === null)
-      // eslint-disable-next-line @typescript-eslint/no-non-null-asserted-optional-chain
-      this.introspecting = this.endpoint?.explain(parameters)!
+    const described = await this.directives.explain(context, introspection)
 
-    this.introspection = await this.introspecting
-
-    return this.introspection
+    return described === null ? null : order(described)
   }
 
   public async close (): Promise<void> {

package/source/RTD/Node.ts

@@ -1,6 +1,9 @@
 import { type Route } from './Route.js'
-import { type Methods } from './Method.js'
+import { type Method, type Methods } from './Method.js'
 import { type Match, type Parameter } from './Match.js'
+import type { Segment } from './segment.js'
+import type { Context } from '../HTTP/index.js'
+import type { Introspection } from '../Introspection.js'
 
 export class Node {
   public intermediate: boolean
@@ -52,14 +55,35 @@ export class Node {
       this.expiration = expiration
   }
 
-  public async explain (parameters: Parameter[]): Promise<Record<string, unknown>> {
-    const methods: Record<string, unknown> = {}
+  /**
+   * Every method under this node, with the template it answers at.
+   *
+   * An intermediate node is skipped: it is never what a path matches, because its `/` route
+   * answers at the same place and is reached instead. The trunk is the exception `match`
+   * makes for it — `'/'` answers the trunk itself, whatever it holds.
+   */
+  public * walk (segments: Segment[], trunk = false): Generator<Mount> {
+    if (trunk || !this.intermediate)
+      for (const [verb, method] of Object.entries(this.methods))
+        yield { segments, verb, method }
+
+    for (const route of this.routes)
+      yield * route.walk(segments)
+  }
 
-    const explained = Object.entries(this.methods)
-      .map(async ([verb, method]) =>
-        (methods[verb] = await method.explain(parameters)))
+  /** Every method of this node that this caller may reach, in the order they were declared. */
+  public async explain (context: Context,
+    parameters: Parameter[]): Promise<Record<string, Introspection>> {
+    const entries = Object.entries(this.methods)
 
-    await Promise.all(explained)
+    const explained = await Promise.all(entries
+      .map(async ([, method]) => await method.explain(context, parameters)))
+
+    const methods: Record<string, Introspection> = {}
+
+    for (let i = 0; i < entries.length; i++)
+      if (explained[i] !== null)
+        methods[entries[i][0]] = explained[i]!
 
     return methods
   }
@@ -119,6 +143,13 @@ export class Node {
   }
 }
 
+/** A method, and the route template it is reached by. */
+export interface Mount {
+  segments: Segment[]
+  verb: string
+  method: Method
+}
+
 export interface Properties {
   protected: boolean
   forward?: string

package/source/RTD/Route.ts

@@ -1,6 +1,6 @@
 import { type Segment } from './segment.js'
 import { type Match, type Parameter } from './Match.js'
-import type { Node } from './Node.js'
+import type { Mount, Node } from './Node.js'
 
 export class Route {
   public readonly root: boolean
@@ -32,10 +32,13 @@ export class Route {
         return null
 
       if (segment.fragment === null && segment.placeholder !== null)
-        parameters.push({ name: segment.placeholder, value: fragments[i] })
+        parameters.push({ name: segment.placeholder, value: decode(fragments[i]) })
 
       if (segment.fragment === null && segment.wildcard === true)
-        parameters.push({ name: '**', value: fragments.slice(this.segments.length - 1).join('/') })
+        parameters.push({
+          name: '**',
+          value: fragments.slice(this.segments.length - 1).map(decode).join('/')
+        })
     }
 
     const exact = this.segments.length === fragments.length
@@ -46,6 +49,14 @@ export class Route {
       return this.matchNested(fragments, parameters)
   }
 
+  public * walk (prefix: Segment[]): Generator<Mount> {
+    // an expired branch is not matched, so nothing under it is reachable to name
+    if (Date.now() >= this.node.expiration)
+      return
+
+    yield * this.node.walk(prefix.concat(this.segments))
+  }
+
   public equals (route: Route): boolean {
     if (route.segments.length !== this.segments.length)
       return false
@@ -67,3 +78,19 @@ export class Route {
     return this.node.match(fragments, parameters)
   }
 }
+
+/**
+ * What the segment says, rather than how it was written: a value is percent-encoded to
+ * survive the path, and an operation reads what a caller meant — a `client_id` that is a
+ * URL arrives as one. A literal segment is matched as written, which is how it is declared.
+ *
+ * An escape that decodes to nothing valid is left as it stands; refusing the route over it
+ * would answer `404` to a request whose only fault is its spelling.
+ */
+function decode (fragment: string): string {
+  try {
+    return decodeURIComponent(fragment)
+  } catch {
+    return fragment
+  }
+}

package/source/RTD/Tree.ts

@@ -1,6 +1,8 @@
+import { console } from 'openspan'
+import { refusal, template } from '../RPC/names.js'
 import { branchTTL, createNode } from './factory.js'
 import { fragment } from './segment.js'
-import type { Node } from './Node.js'
+import type { Mount, Node } from './Node.js'
 import type { Match } from './Match.js'
 import type { Context } from './Context.js'
 import type { DirectiveFactory } from './Directives.js'
@@ -18,6 +20,8 @@ export class Tree {
     this.directives = directives
     this.root = node
     this.trunk = this.createNode(node, PROTECTED)
+
+    unnameable(this.trunk)
   }
 
   public match (path: string): Match | null {
@@ -32,9 +36,16 @@ export class Tree {
     return this.trunk.match(fragments)
   }
 
+  /** Every method in the tree, with the template it answers at. */
+  public walk (): Generator<Mount> {
+    return this.trunk.walk([], TRUNK)
+  }
+
   public merge (node: syntax.Node, extension: unknown): Node[] {
     const branch = this.createNode(node, !PROTECTED, extension)
 
+    unnameable(branch)
+
     return this.trunk.merge(branch)
   }
 
@@ -72,6 +83,30 @@ export class Tree {
   }
 }
 
+/**
+ * What is served but cannot be called by name. Said once per route as it is built, because a
+ * procedure that is missing is otherwise noticed only by the caller who cannot find it.
+ */
+function unnameable (node: Node): void {
+  const said = new Set<string>()
+
+  for (const { segments } of node.walk([], TRUNK)) {
+    const segment = refusal(segments)
+
+    if (segment === null)
+      continue
+
+    const route = template(segments)
+
+    if (said.has(route))
+      continue
+
+    said.add(route)
+
+    console.warn('Route cannot be addressed as a procedure', { route, segment })
+  }
+}
+
 /**
  * A branch's routes are relative to wherever it is merged, and the mount point is not
  * known while it is being built — so the component it came from is what keeps two
@@ -89,3 +124,4 @@ function label (extension: unknown): string {
 }
 
 const PROTECTED = true
+const TRUNK = true

package/source/RTD/expiration.test.ts

@@ -10,7 +10,7 @@ const endpoints = {} as unknown as EndpointsFactory
 
 const directives = {
   create: () => ({
-    preflight: async () => null,
+    precall: async () => null,
     settle: async () => undefined,
     dispose: () => undefined
   }),

package/source/RTD/walk.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Tree } from './Tree.js'
+import { address, name } from '../RPC/names.js'
+import type { EndpointsFactory } from '../Endpoint.js'
+import type { DirectiveFactory } from './Directives.js'
+import type * as syntax from './syntax/index.js'
+
+const endpoints = {} as unknown as EndpointsFactory
+
+const directives = {
+  create: () => ({
+    precall: async () => null,
+    settle: async () => undefined,
+    dispose: () => undefined
+  }),
+  dispose: mock.fn()
+} as unknown as DirectiveFactory
+
+const node = (path: string, verbs: string[] = [], routes: syntax.Route[] = []): syntax.Route => ({
+  path,
+  node: {
+    routes,
+    methods: verbs.map((verb) => ({ verb, directives: [] })),
+    directives: []
+  }
+})
+
+const trunk = (routes: syntax.Route[], verbs: string[] = []): syntax.Node => ({
+  routes,
+  methods: verbs.map((verb) => ({ verb, directives: [] })),
+  directives: []
+})
+
+/** What a walk names, which is what a caller of `/.rpc` would write. */
+function names (tree: Tree): string[] {
+  return [...tree.walk()].map(({ segments, verb }) => name(segments, verb))
+    .filter((named): named is string => named !== null)
+}
+
+describe('walk', () => {
+  it('should name the trunk by its verb alone', () => {
+    const tree = new Tree(trunk([], ['GET']), endpoints, directives)
+
+    assert.deepEqual(names(tree), ['GET'])
+  })
+
+  it('should name every method of every route', () => {
+    const tree = new Tree(trunk([
+      node('/pots', ['GET', 'POST'], [node('/:id', ['GET', 'DELETE'])])
+    ]), endpoints, directives)
+
+    assert.deepEqual(names(tree).sort(), [
+      'pots.GET', 'pots.POST', 'pots._id.DELETE', 'pots._id.GET'
+    ])
+  })
+
+  it('should walk a branch that was merged', () => {
+    const tree = new Tree(trunk([]), endpoints, directives)
+
+    tree.merge(trunk([node('/pots', ['GET'])]), { namespace: 'default', component: 'pots' })
+
+    assert.deepEqual(names(tree), ['pots.GET'])
+  })
+
+  it('should name a tail', () => {
+    const tree = new Tree(trunk([node('/files', [], [node('/**', ['GET'])])]),
+      endpoints, directives)
+
+    assert.deepEqual(names(tree), ['files.__.GET'])
+  })
+
+  it('should skip an intermediate node, whose route answers in its place', () => {
+    const tree = new Tree(trunk([
+      // `/posts` is intermediate: `/posts/` is answered by its `/` route, not by itself
+      node('/posts', ['PATCH'], [node('/', ['PUT'])])
+    ]), endpoints, directives)
+
+    assert.deepEqual(names(tree), ['posts.PUT'])
+  })
+
+  it('should name nothing where a segment cannot be spelled', () => {
+    const tree = new Tree(trunk([node('/v1.0', ['GET']), node('/pots', ['GET'])]),
+      endpoints, directives)
+
+    assert.deepEqual(names(tree), ['pots.GET'])
+  })
+
+  it('should name what the tree then matches', () => {
+    const tree = new Tree(trunk([
+      node('/pots', ['GET'], [node('/:id', ['GET']), node('/hot', ['GET'])]),
+      node('/files', [], [node('/**', ['GET'])])
+    ], ['GET']), endpoints, directives)
+
+    const params = { id: 'a1b2', '**': 'a/b/c' }
+
+    for (const { segments, verb } of tree.walk()) {
+      const named = name(segments, verb)
+
+      assert.notStrictEqual(named, null, 'every walked method has a name')
+
+      const { path } = address(named!, params)
+      const match = tree.match(path)
+
+      assert.notStrictEqual(match, null, `'${named!}' resolves to '${path}', which matches`)
+      assert.ok(verb in match!.node.methods, `'${named!}' matches a node that answers ${verb}`)
+    }
+  })
+})

package/source/const.ts

@@ -2,3 +2,18 @@ export const BRANCH_TTL = 1_800_000
 
 /** The replicas of the gateway decide together, whatever context they serve. */
 export const ATOM_GROUP = 'exposition'
+
+/**
+ * Where JSON-RPC is served, for every procedure at once. Pinned rather than configured: a
+ * path an application could choose is a path it could collide with a route of its own.
+ */
+export const RPC = '/.rpc'
+
+/** Calls one request may carry where the annotation does not say. */
+export const BATCH = 32
+
+/**
+ * Where the Model Context Protocol is served. Pinned for the reason `/.rpc` is: a path an
+ * application could choose is a path it could collide with a route of its own.
+ */
+export const MCP = '/.mcp'

package/source/deployment.ts

@@ -70,6 +70,12 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   if (annotation.oauth !== undefined)
     properties.oauth = annotation.oauth
 
+  if (annotation.rpc !== undefined)
+    properties.rpc = annotation.rpc
+
+  if (annotation.mcp !== undefined)
+    properties.mcp = annotation.mcp
+
   service.variables!.push({
     name: 'TOA_EXPOSITION_PROPERTIES',
     value: JSON.stringify(properties)
@@ -86,4 +92,5 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   return { services: [service] }
 }
 
-type Properties = Pick<Annotation, 'authorities' | 'debug' | 'protocol' | 'bouncer' | 'ip' | 'oauth'>
+type Properties = Pick<Annotation,
+'authorities' | 'debug' | 'protocol' | 'bouncer' | 'ip' | 'oauth' | 'rpc' | 'mcp'>

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

@@ -0,0 +1,38 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Anonymous } from './Anonymous.js'
+import type { Context } from './types.js'
+
+const context = (headers: Record<string, string>, procedural = false): Context =>
+  ({ request: { headers }, procedural }) as unknown as Context
+
+describe('anonymous', () => {
+  it('should admit a request that presents nothing', () => {
+    assert.equal(new Anonymous(true).authorize(null, context({})), true)
+  })
+
+  it('should refuse a request that presents a credential', () => {
+    // it would make the reply uncacheable, which is the whole of the rule
+    assert.equal(new Anonymous(true).authorize(null, context({ authorization: 'Token x' })), false)
+  })
+
+  it('should admit a procedure whatever the request presented', () => {
+    // what a procedure answers is a value in an envelope, and the envelope is `no-store`
+    const procedural = context({ authorization: 'Token x' }, true)
+
+    assert.equal(new Anonymous(true).authorize(null, procedural), true)
+  })
+
+  it('should refuse where it admits nobody', () => {
+    assert.equal(new Anonymous(false).authorize(null, context({})), false)
+    assert.equal(new Anonymous(false).authorize(null, context({}, true)), false)
+  })
+
+  it('should describe a method as it authorizes one', () => {
+    const directive = new Anonymous(true)
+
+    assert.equal(directive.admits(null, context({ authorization: 'Token x' })), false)
+    assert.equal(directive.admits(null, context({ authorization: 'Token x' }, true)), true)
+  })
+})

package/source/directives/auth/Anonymous.ts

@@ -7,9 +7,21 @@ export class Anonymous implements Directive {
     this.allow = allow
   }
 
+  /**
+   * A credential refuses, because it would make the reply uncacheable — which is the whole
+   * of the rule, and none of it applies to a procedure: what a procedure answers is a value
+   * in an envelope, and the envelope is the one thing that is cached or not.
+   */
   public authorize (_: any, context: Context): boolean {
+    if (context.procedural)
+      return this.allow
+
     return 'authorization' in context.request.headers
       ? false
       : this.allow
   }
+
+  public admits (_: any, context: Context): boolean {
+    return this.authorize(_, context)
+  }
 }

package/source/directives/auth/Anyone.ts

@@ -10,4 +10,8 @@ export class Anyone implements Directive {
   public authorize (_: any, context: Context): boolean {
     return context.identity !== null && this.allow
   }
+
+  public admits (_: any, context: Context): boolean {
+    return this.authorize(_, context)
+  }
 }

package/source/directives/auth/Authorization.ts

@@ -21,6 +21,7 @@ import { ATOM_GROUP } from '../../const.js'
 import { Quotas, Sync } from '../io/lib/throttle/index.js'
 import { Keys } from '../io/lib/throttle/Keys.js'
 import type { Output } from '../../io.js'
+import type { Introspection } from '../../Introspection.js'
 import type { Component } from '@toa.io/core'
 import type { Remotes } from '../../Remotes.js'
 import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
@@ -100,11 +101,18 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     directives.sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1))
   }
 
-  public async preflight (directives: Directive[],
-    context: Context,
-    parameters: Parameter[]): Promise<Output> {
+  /**
+   * Authentication: who the credential names, if one is presented. A credential belongs to
+   * the request, so it is read once however many calls the request carries.
+   */
+  public async preflight (context: Context): Promise<void> {
     context.identity = await this.resolve(context)
+  }
 
+  /** Authorization: whether that identity may make this call, which every call asks anew. */
+  public async precall (directives: Directive[],
+    context: Context,
+    parameters: Parameter[]): Promise<Output> {
     for (const directive of directives) {
       const allow = await directive.authorize(context.identity, context, parameters)
 
@@ -121,12 +129,63 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
       throw new http.Forbidden()
   }
 
+  /**
+   * The same disjunction as `precall`, over what can be told without a request. A method no
+   * directive admits, and none is undecided about, is not this caller's to be told about —
+   * `null` takes it out of the answer.
+   *
+   * A permission is matched against a path, and a description is not a request to one, so
+   * `permits` has no say here. The call it describes is still checked, which is where a
+   * token's permissions belong.
+   *
+   * A method that is described is then described by each of them, which is a separate pass:
+   * admission is a disjunction and stops at the first that admits, while what the directives
+   * fill is not any one of them's to state alone.
+   */
+  public async explain (directives: Directive[], context: Context,
+    introspection: Introspection): Promise<Introspection | null> {
+    let untold = false
+    let admitted = false
+
+    for (const directive of directives) {
+      const admits = await directive.admits?.(context.identity, context)
+
+      if (admits === undefined) {
+        untold = true
+
+        continue
+      }
+
+      if (admits) {
+        admitted = true
+
+        break
+      }
+    }
+
+    if (!admitted && !untold)
+      return null
+
+    // whichever of them admitted, a property any of them fills from the identity is filled
+    // from the identity: what a caller sent there would be overwritten or forged
+    for (const directive of directives)
+      introspection = directive.describe?.(introspection) ?? introspection
+
+    return introspection
+  }
+
   public async settle (directives: Directive[],
     context: Context,
     response: http.OutgoingMessage): Promise<void> {
     await Promise.all(directives.map(async (directive) =>
       directive.settle?.(context, response)))
+  }
 
+  /**
+   * Re-issuing a credential, and refusing a ban, are the request's business: the header
+   * carries one token however many calls were made, and a ban refuses all of them.
+   */
+  public async depart (context: Context, response: http.OutgoingMessage): Promise<void> {
     const identity = context.identity
 
     if (identity === null)