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

package/features/steps/Realtime.ts

@@ -44,6 +44,8 @@ export class Realtime {
 
     Realtime.instance = await factory.service()
 
+    // not awaited: the routes connect to the components that produce the events, and this
+    // scenario starts the producer after the service, so the connection settles later
     void Realtime.instance.connect()
   }
 
@@ -152,3 +154,4 @@ export class Realtime {
     }
   }
 }
+

package/features/steps/components/echo/manifest.toa.yaml

@@ -31,6 +31,7 @@ operations:
           type: object
       type: object
   parameters:
+    description: Answers with what it was given.
     input:
       type: object
       properties:

package/features/steps/components/pots/manifest.toa.yaml

@@ -24,6 +24,7 @@ entity:
 
 operations:
   create:
+    description: Put a pot on to brew.
     query: false
     forward: transit
     input:
@@ -71,6 +72,7 @@ operations:
           type: number
       type: object
   enumerate:
+    description: Every pot there is.
     output:
       type: array
       items:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.283",
+  "version": "1.0.0-alpha.285",
   "type": "module",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@simplewebauthn/server": "14.0.0",
-    "@toa.io/core": "1.0.0-alpha.283",
+    "@toa.io/core": "1.0.0-alpha.284",
     "@toa.io/generic": "1.0.0-alpha.283",
     "@toa.io/schemas": "1.0.0-alpha.283",
     "bcryptjs": "3.0.3",
@@ -58,5 +58,5 @@
     "@types/cors": "2.8.19",
     "@types/negotiator": "0.6.5"
   },
-  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
+  "gitHead": "44ed1be7e322a5ea8f1a8ed85ba96b9dfaf28224"
 }

package/readme.md

@@ -139,6 +139,9 @@ exposition:
 | `ip`          | Header the client address is read from. See [Client address](documentation/ip.md).                              |
 | `bouncer`     | Meter of failed authentications per address. See [Identity authentication](documentation/identity.md#failed-authentications). |
 | `oauth`       | Authorization server exposed to OAuth clients. See [OAuth](documentation/oauth.md).                               |
+| `protocol`    | `h1` or `h2c`. See [Protocol](documentation/protocol.md).                                                         |
+| `rpc`         | JSON-RPC at `/.rpc`; none is served without it. See [JSON-RPC](documentation/rpc.md).                             |
+| `mcp`         | MCP at `/.mcp`; none is served without it. See [MCP](documentation/mcp.md).                                       |
 
 ### Observability
 

package/schemas/annotation.cos.yaml

@@ -80,6 +80,39 @@ properties:
     required:
       - authorize
     additionalProperties: false
+  rpc:
+    description: JSON-RPC at `/.rpc`; writing it is what turns the endpoint on
+    type: object
+    properties:
+      batch:
+        description: Calls one request may carry
+        type: integer
+        minimum: 1
+    additionalProperties: false
+  mcp:
+    description: MCP at `/.mcp`; writing it is what turns the endpoint on
+    type: object
+    properties:
+      name:
+        description: What the server calls itself
+        type: string
+        minLength: 1
+      instructions:
+        description: What a model is told before it calls anything here
+        type: string
+      origins:
+        description: Browser origins the endpoint answers; none without it
+        type: array
+        items:
+          type: string
+          pattern: ^https?://
+      anonymous:
+        description: Whether the endpoint answers without a credential
+        type: boolean
+        default: false
+    required:
+      - name
+    additionalProperties: false
   /: {}
   authorities:
     type: object

package/schemas/call.cos.yaml

@@ -0,0 +1,18 @@
+description: One JSON-RPC call, as the envelope carries it
+properties:
+  jsonrpc:
+    const: '2.0'
+  method:
+    type: string
+    minLength: 1
+  params:
+    description: By name only, because `io:input` validates an object
+    type: object
+  id:
+    description: Absent makes the call a notification, which answers nothing
+    type: [string, number]
+required:
+  - jsonrpc
+  - method
+additionalProperties: false
+type: object

package/source/Annotation.ts

@@ -26,6 +26,12 @@ export interface Annotation {
 
   /** The authorization server this context exposes; none is exposed without it. */
   oauth?: OAuth
+
+  /** JSON-RPC at `/.rpc`; none is served without it. See `documentation/rpc.md`. */
+  rpc?: RPC
+
+  /** MCP at `/.mcp`; none is served without it. See `documentation/mcp.md`. */
+  mcp?: MCP
   '/'?: object // parsed and validated by RTD.syntax.parse
 }
 
@@ -49,6 +55,31 @@ export interface OAuth {
   registration?: 'open' | 'closed'
 }
 
+export interface RPC {
+  /**
+   * Calls one request may carry, 32 by default. One request is one authentication and one
+   * reply however many calls it makes, so what a caller may ask for at once is bounded.
+   */
+  batch?: number
+}
+
+export interface MCP {
+  /** What the server calls itself, which a client shows a user. */
+  name: string
+
+  /** What a model is told before it calls anything here. */
+  instructions?: string
+
+  /**
+   * Browser origins the endpoint answers, which the revision requires against DNS rebinding.
+   * None are admitted without it; a request carrying no `Origin` is not a browser's.
+   */
+  origins?: string[]
+
+  /** Whether the endpoint answers without a credential. It does not unless it says so. */
+  anonymous?: boolean
+}
+
 export interface Bouncer {
   /** what an address may fail at once, 20 by default */
   attempts?: number

package/source/Directive.test.ts

@@ -16,7 +16,7 @@ const families: Array<DirectiveFamily> = [
     mandatory: true,
     create: mock.fn((_0: any, _1: any, _2: any) => generate() as any),
     arrange: mock.fn(),
-    preflight: mock.fn(() => { sequence.push('foo'); return null }),
+    precall: mock.fn(() => { sequence.push('foo'); return null }),
     settle: mock.fn(),
     dispose: mock.fn()
   },
@@ -25,7 +25,7 @@ const families: Array<DirectiveFamily> = [
     mandatory: true,
     create: mock.fn((_0: any, _1: any, _2: any) => generate() as any),
     arrange: mock.fn(),
-    preflight: mock.fn(() => { sequence.push('qux'); return null }),
+    precall: mock.fn(() => { sequence.push('qux'); return null }),
     settle: mock.fn(),
     dispose: mock.fn()
   },
@@ -34,7 +34,7 @@ const families: Array<DirectiveFamily> = [
     mandatory: false,
     create: mock.fn((_0: string, _1: any, _2: any) => generate() as any),
     arrange: mock.fn(),
-    preflight: mock.fn(() => { sequence.push('bar'); return null }),
+    precall: mock.fn(() => { sequence.push('bar'); return null }),
     settle: mock.fn(),
     dispose: mock.fn()
   }
@@ -47,9 +47,9 @@ beforeEach(() => {
   sequence.length = 0
 
   for (const family of families) {
-    assert.ok(family.preflight !== undefined)
+    assert.ok(family.precall !== undefined)
 
-    family.preflight.mock.mockImplementation(() => { sequence.push(family.name); return null })
+    family.precall.mock.mockImplementation(() => { sequence.push(family.name); return null })
   }
 
   factory = new DirectivesFactory(families, {} as unknown as Remotes, {} as unknown as Host,
@@ -110,25 +110,25 @@ it('should apply directive', async () => {
   const request = generate() as unknown as Context
   const directive = families[0].create.mock.calls[0].result
 
-  await directives.preflight(request, [])
+  await directives.precall(request, [])
 
-  assert.ok(families[0].preflight !== undefined)
+  assert.ok(families[0].precall !== undefined)
 
-  assert.deepStrictEqual(families[0].preflight.mock.calls[0].arguments[0], [directive])
-  assert.deepStrictEqual(families[0].preflight.mock.calls[0].arguments[1], request)
+  assert.deepStrictEqual(families[0].precall.mock.calls[0].arguments[0], [directive])
+  assert.deepStrictEqual(families[0].precall.mock.calls[0].arguments[1], request)
 })
 
 it('should apply mandatory families', async () => {
   const directives = factory.create([])
   const request = generate() as unknown as Context
 
-  await directives.preflight(request, [])
+  await directives.precall(request, [])
 
-  assert.ok(families[0].preflight.mock.callCount() > 0)
+  assert.ok(families[0].precall.mock.callCount() > 0)
 })
 
 describe('order', () => {
-  // the order the families actually ran, as each preflight recorded it
+  // the order the families actually ran, as each precall recorded it
   function order (): string[] {
     return sequence
   }
@@ -140,7 +140,7 @@ describe('order', () => {
       { family: 'foo', name: generate(), value: generate() }
     ])
 
-    await directives.preflight(generate() as unknown as Context, [])
+    await directives.precall(generate() as unknown as Context, [])
 
     assert.deepStrictEqual(order(), ['foo', 'qux'])
   })
@@ -153,7 +153,7 @@ describe('order', () => {
         { family: 'qux', name: generate(), value: generate() }
       ])
 
-      await directives.preflight(generate() as unknown as Context, [])
+      await directives.precall(generate() as unknown as Context, [])
 
       assert.deepStrictEqual(order(), ['foo', 'qux'])
     })
@@ -164,7 +164,7 @@ describe('order', () => {
       { family: 'qux', name: generate(), value: generate() }
     ])
 
-    await directives.preflight(generate() as unknown as Context, [])
+    await directives.precall(generate() as unknown as Context, [])
 
     assert.deepStrictEqual(order(), ['foo', 'qux', 'bar'])
   })

package/source/Directive.ts

@@ -3,6 +3,7 @@ import type { Context, OutgoingMessage, Options } from './HTTP/index.js'
 import type { Remotes } from './Remotes.js'
 import type { Host } from './Factory.js'
 import type { Output } from './io.js'
+import type { Introspection } from './Introspection.js'
 import type * as RTD from './RTD/index.js'
 
 export class Directives implements RTD.Directives {
@@ -14,28 +15,33 @@ export class Directives implements RTD.Directives {
   public constructor (sets: RTD.DirectiveSet[]) {
     this.sets = sets
     this.spans = sets.map((set) => ({
-      preflight: options(set, 'preflight'),
-      settle: options(set, 'settle')
+      precall: options(set, 'precall'),
+      settle: options(set, 'settle'),
+      explain: options(set, 'explain')
     }))
   }
 
-  public async preflight (context: Context, parameters: RTD.Parameter[]): Promise<Output> {
+  public declared<T> (family: string): T[] | undefined {
+    return this.sets.find((set) => set.family.name === family)?.directives as T[] | undefined
+  }
+
+  public async precall (context: Context, parameters: RTD.Parameter[]): Promise<Output> {
     let output = null
 
     for (let i = 0; i < this.sets.length; i++) {
       const set = this.sets[i]
 
-      if (set.family.preflight === undefined)
+      if (set.family.precall === undefined)
         continue
 
-      const out = await console.span(this.spans[i].preflight,
-        async () => await set.family.preflight!(set.directives, context, parameters))
+      const out = await console.span(this.spans[i].precall,
+        async () => await set.family.precall!(set.directives, context, parameters))
 
       if (out === null)
         continue
 
       if (output !== null)
-        throw new Error('Multiple preflight directives responded')
+        throw new Error('Multiple precall directives responded')
       else
         output = out
     }
@@ -43,6 +49,33 @@ export class Directives implements RTD.Directives {
     return output
   }
 
+  /**
+   * What the method says about itself, as its directives leave it. Each family is given
+   * what the one before it returned, and the first to refuse ends it: a method this caller
+   * cannot reach is not described at all.
+   */
+  public async explain (context: Context,
+    introspection: Introspection): Promise<Introspection | null> {
+    let described: Introspection = introspection
+
+    for (let i = 0; i < this.sets.length; i++) {
+      const set = this.sets[i]
+
+      if (set.family.explain === undefined)
+        continue
+
+      const next = await console.span(this.spans[i].explain,
+        async () => await set.family.explain!(set.directives, context, described))
+
+      if (next === null)
+        return null
+
+      described = next
+    }
+
+    return described
+  }
+
   public async settle (context: Context, response: OutgoingMessage): Promise<void> {
     for (let i = 0; i < this.sets.length; i++) {
       const set = this.sets[i]
@@ -65,6 +98,9 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
   private readonly mandatory: string[] = []
   private readonly instances: Directives[] = []
 
+  /** The request-scoped stages, in registration order, with the spans they run in. */
+  private readonly stages: Stage[] = []
+
   // eslint-disable-next-line max-params
   public constructor (families: RTD.DirectiveFamily[], remotes: Remotes, host: Host,
     options: Options) {
@@ -74,11 +110,36 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
 
       if (family.mandatory)
         this.mandatory.push(family.name)
+
+      this.stages.push({
+        family,
+        preflight: { name: `${family.name} preflight` },
+        depart: { name: `${family.name} depart` }
+      })
     }
 
     this.remotes = remotes
   }
 
+  /**
+   * Request-scoped, before anything is routed, so no directives are passed: a family
+   * answers here only for what it does on its own behalf.
+   */
+  public async preflight (context: Context): Promise<void> {
+    for (const stage of this.stages)
+      if (stage.family.preflight !== undefined)
+        await console.span(stage.preflight,
+          async () => { await stage.family.preflight!(context) })
+  }
+
+  /** Request-scoped, on the message going back. */
+  public async depart (context: Context, response: OutgoingMessage): Promise<void> {
+    for (const stage of this.stages)
+      if (stage.family.depart !== undefined)
+        await console.span(stage.depart,
+          async () => { await stage.family.depart!(context, response) })
+  }
+
   public create (declarations: RTD.syntax.Directive[], route: string = ''): Directives {
     const groups: Record<string, any> = {}
     const mandatory = new Set(this.mandatory)
@@ -146,7 +207,7 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
   }
 }
 
-function options (set: RTD.DirectiveSet, stage: 'preflight' | 'settle'): SpanOptions {
+function options (set: RTD.DirectiveSet, stage: 'precall' | 'settle' | 'explain'): SpanOptions {
   const options: SpanOptions = { name: `${set.family.name} ${stage}` }
 
   if (set.names !== undefined && set.names.length > 0)
@@ -156,8 +217,15 @@ function options (set: RTD.DirectiveSet, stage: 'preflight' | 'settle'): SpanOpt
 }
 
 interface Spans {
-  preflight: SpanOptions
+  precall: SpanOptions
   settle: SpanOptions
+  explain: SpanOptions
+}
+
+interface Stage {
+  family: RTD.DirectiveFamily
+  preflight: SpanOptions
+  depart: SpanOptions
 }
 
 export const shortcuts: RTD.syntax.Shortcuts = new Map([

package/source/Endpoint.test.ts

@@ -0,0 +1,67 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Endpoint } from './Endpoint.js'
+import { Mapping } from './Mapping.js'
+import type { Remote } from '@toa.io/core'
+import type { Parameter } from './RTD/index.js'
+
+/**
+ * What `Remote.explain` answers is the contract's own object, the same one every time and
+ * on every route that mounts the endpoint — which is what this stands in for.
+ */
+function remote (): Promise<Remote> {
+  const explanation = {
+    input: {
+      type: 'object',
+      properties: {
+        a: { type: 'string' },
+        b: { type: 'string' }
+      },
+      required: ['a', 'b']
+    },
+    output: null
+  }
+
+  return Promise.resolve({
+    explain: async () => explanation
+  } as unknown as Remote)
+}
+
+const endpoint = (discovery: Promise<Remote>): Endpoint =>
+  new Endpoint('parameters', Mapping.create(), discovery)
+
+const variable: Parameter[] = [{ name: 'a', value: 'a1b2' }]
+
+describe('explain', () => {
+  it('should state a route variable as the route, not as the input', async () => {
+    const introspection = await endpoint(remote()).explain(variable)
+
+    assert.deepEqual(Object.keys(introspection.route ?? {}), ['a'])
+    assert.deepEqual(Object.keys((introspection.input as any).properties), ['b'])
+    assert.deepEqual((introspection.input as any).required, ['b'])
+  })
+
+  it('should leave the operation for the next route that mounts it', async () => {
+    const discovery = remote()
+
+    await endpoint(discovery).explain(variable)
+
+    // a second route on the same endpoint, taking no variable of its own
+    const introspection = await endpoint(discovery).explain([])
+
+    assert.deepEqual(Object.keys((introspection.input as any).properties), ['a', 'b'])
+    assert.deepEqual((introspection.input as any).required, ['a', 'b'])
+  })
+
+  it('should answer a copy, so what one caller narrows the next still sees', async () => {
+    const one = endpoint(remote())
+    const first = await one.explain(variable)
+
+    delete (first.input as any).properties.b
+
+    const second = await one.explain(variable)
+
+    assert.deepEqual(Object.keys((second.input as any).properties), ['b'])
+  })
+})

package/source/Endpoint.ts

@@ -1,6 +1,7 @@
 import { Readable } from 'node:stream'
 import { console } from 'openspan'
 import { Mapping } from './Mapping.js'
+import { take } from './Introspection.js'
 import { redact } from './redact.js'
 import * as http from './HTTP/index.js'
 import type { Introspection, Schema } from './Introspection.js'
@@ -15,6 +16,9 @@ export class Endpoint implements RTD.Endpoint {
   private readonly discovery: Promise<Remote>
   private remote: Remote | null = null
 
+  /** What the operation says, with what the route takes already split out of it. */
+  private introspection: Introspection | null = null
+
   public constructor (endpoint: string, mapping: Mapping, discovery: Promise<Remote>) {
     this.endpoint = endpoint
     this.mapping = mapping
@@ -65,24 +69,40 @@ export class Endpoint implements RTD.Endpoint {
   }
 
   public async explain (parameters: RTD.Parameter[]): Promise<Introspection> {
+    this.introspection ??= await this.introspect(parameters)
+
+    // what a directive narrows is this caller's answer, not the next caller's
+    return structuredClone(this.introspection)
+  }
+
+  /**
+   * `Remote.explain` answers the contract's own object, whose `input` is the manifest's by
+   * reference. What follows takes properties out of it, and two routes mounting one endpoint
+   * share one remote — so the copy is what keeps the second from describing what the first
+   * took away.
+   */
+  private async introspect (parameters: RTD.Parameter[]): Promise<Introspection> {
     this.remote ??= await this.discovery
 
-    const operation = await this.remote.explain(this.endpoint)
+    const operation = structuredClone(await this.remote.explain(this.endpoint))
+
+    // what the operation states it is, is the Introspection's to read and not a resource's:
+    // an operation is written without knowledge of any route, and the same one mounted twice
+    // is two methods. What a method states is what its route states, which `mcp:tool` gives.
+    delete operation.description
 
     let route: Record<string, Schema> | null = null
 
-    if (operation.input?.type === 'object')
-      for (const parameter of parameters) {
-        const schema = operation.input.properties[parameter.name]
+    // a variable the operation names is taken by the path, so it is not the body's to send
+    for (const parameter of parameters) {
+      const schema = take(operation, parameter.name)
 
-        // eslint-disable-next-line max-depth
-        if (schema !== undefined) {
-          route ??= {}
-          route[parameter.name] = schema
+      if (schema === undefined)
+        continue
 
-          delete operation.input.properties[parameter.name]
-        }
-      }
+      route ??= {}
+      route[parameter.name] = schema
+    }
 
     const query = this.mapping.explain(operation)
     const introspection: Introspection = {}

package/source/Factory.ts

@@ -12,6 +12,8 @@ import { Composition } from './Composition.js'
 import * as root from './root.js'
 import { ATOM_GROUP } from './const.js'
 import { Interception } from './Interception.js'
+import { Dispatcher } from './RPC/index.js'
+import { Server as Model } from './MCP/index.js'
 import * as http from './HTTP/index.js'
 import type { Branch } from './Branch.js'
 import type { syntax } from './RTD/index.js'
@@ -58,7 +60,9 @@ export class Factory implements extensions.Factory {
     const tree = new Tree(node, methods, directives)
 
     const composition = new Composition(this.host)
-    const gateway = new Gateway(broadcast, tree, interception)
+    const dispatcher = options.rpc === undefined ? null : new Dispatcher(options.rpc)
+    const mcp = options.mcp === undefined ? null : new Model(options.mcp, tree)
+    const gateway = new Gateway(broadcast, tree, interception, directives, dispatcher, mcp)
 
     gateway.depends(remotes)
     gateway.depends(composition)