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

package/source/MCP/tools.ts

@@ -0,0 +1,156 @@
+import * as http from '../HTTP/index.js'
+import { fork } from '../RPC/Context.js'
+import { address, name, split } from '../RPC/names.js'
+import { METHOD_NOT_FOUND, failure, refusal, response } from './errors.js'
+import { annotations, input, output } from './schema.js'
+import { FAMILY, MCP, type Tool as Declaration } from '../directives/mcp/index.js'
+import type { Segment } from '../RTD/segment.js'
+import type { Parameter, Tree } from '../RTD/index.js'
+import type { Params, Result, Tool } from './types.js'
+
+/**
+ * Every method this caller may reach that is published as a tool, named as the procedure
+ * it is.
+ *
+ * A method is a tool where it says so with `mcp:tool`, and a default denies: a tree holds
+ * what an application serves, and most of it is machinery a model has no business reading.
+ * What a caller may then do with one is what `auth` says. The tree is walked once and each
+ * method describes itself, which is where that is decided and where `io` and `map` say what
+ * may be sent.
+ *
+ * Sorted, because the revision asks for an order a client can cache on.
+ */
+export async function list (tree: Tree, context: http.Context): Promise<Tool[]> {
+  const tools: Tool[] = []
+
+  /*
+   * Each method is described as the procedure it would be, not as the request asking. What
+   * refuses a credentialed request at an `anonymous` route does not refuse the call a tool
+   * makes, and a list that says otherwise disagrees with what `tools/call` then does.
+   */
+  const describing: http.Context = Object.create(context,
+    { procedural: { value: true, enumerable: true } })
+
+  for (const { segments, verb, method } of tree.walk()) {
+    if (MCP.published(method.directives.declared<Declaration>(FAMILY)) === null)
+      continue
+
+    const named = name(segments, verb)
+
+    // a route a name cannot spell is a route nothing addresses, here or at `/.rpc`
+    if (named === null)
+      continue
+
+    const variables = parameters(segments)
+    const introspection = await method.explain(describing, variables)
+
+    if (introspection === null)
+      continue
+
+    const described = introspection.description
+    const schema = output(introspection)
+    const hints = annotations(verb)
+
+    // in the order the revision documents one, which is the order it is read in
+    const tool: Tool = {
+      name: named,
+      ...described === undefined ? {} : { description: described },
+      inputSchema: input(introspection, variables.map((variable) => variable.name)),
+      ...schema === undefined ? {} : { outputSchema: schema },
+      ...hints === undefined ? {} : { annotations: hints }
+    }
+
+    tools.push(tool)
+  }
+
+  return tools.sort((one, other) => one.name < other.name ? -1 : 1)
+}
+
+/**
+ * The call the tool is. Its arguments are the procedure's parameters, taken apart the way a
+ * request carries them, and what answers is the same `route` an ordinary request goes to.
+ *
+ * A name that is not a published tool is answered as no tool at all, whether or not a route
+ * would have taken it: what an application did not publish is not reachable here by guessing
+ * its name. What the caller may then do with one that is published is still `auth`'s to say.
+ */
+export async function call (scope: Scope, named: string, args: Params): Promise<Result> {
+  if (!published(scope.tree, named))
+    throw new http.NotFound(response(null,
+      failure(METHOD_NOT_FOUND, `'${named}' is not a tool this server publishes`)))
+
+  const { path, verb, variables } = address(named, args)
+  const { query, input: body } = split(args, variables)
+  const clone = fork(scope.context, path, verb, query, body)
+
+  try {
+    const message = await scope.route(clone)
+
+    // what `io:output` restricts, over this call's reply rather than the envelope
+    await http.shape(clone, message)
+
+    return result(message.body)
+  } catch (exception) {
+    /*
+     * What the route made of this call is a value a model reads and may correct itself by:
+     * an operation that refused, an argument `io:input` would not take, a record that is
+     * not there, an identity `auth` would not let it act on. A credential is none of those
+     * — that is the client's to fix and not the model's, so it is answered as it is — and
+     * neither is a fault of this server, which is a protocol error and stays one.
+     */
+    if (exception instanceof http.ClientError && !(exception instanceof http.Unauthorized))
+      return { content: [{ type: 'text', text: refusal(exception) }], isError: true }
+
+    throw exception
+  }
+}
+
+/** Everything a call needs that is not the call: the request it is of, and what answers it. */
+export interface Scope {
+  context: http.Context
+  route: http.Processor
+  tree: Tree
+}
+
+/**
+ * Whether the tree publishes this name as a tool. What `auth` makes of the caller is not
+ * asked here — the declaration is the route's and does not vary by who is calling, and the
+ * call that follows is authorized as any request to that route is.
+ */
+function published (tree: Tree, named: string): boolean {
+  for (const { segments, verb, method } of tree.walk())
+    if (name(segments, verb) === named)
+      return MCP.published(method.directives.declared<Declaration>(FAMILY)) !== null
+
+  return false
+}
+
+function result (body: unknown): Result {
+  if (body === undefined || body === null)
+    return { content: [] }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(body) }],
+    structuredContent: body
+  }
+}
+
+/**
+ * What a route template takes, by name. Describing has no values for them — a template is
+ * not a path — and nothing that describes a method reads one.
+ */
+function parameters (segments: Segment[]): Parameter[] {
+  const params: Parameter[] = []
+
+  for (const segment of segments) {
+    if (segment.fragment !== null)
+      continue
+
+    if (segment.wildcard === true)
+      params.push({ name: '**', value: '' })
+    else if (segment.placeholder !== null)
+      params.push({ name: segment.placeholder, value: '' })
+  }
+
+  return params
+}

package/source/MCP/types.ts

@@ -0,0 +1,81 @@
+/** The revision this endpoint serves, where a request carries its own metadata. */
+export const MODERN = '2026-07-28'
+
+/** The newest revision reached by an `initialize` handshake, which is what clients still send. */
+export const LEGACY = '2025-11-25'
+
+export const VERSIONS = [MODERN, LEGACY]
+
+/** The version every JSON-RPC message states, which is not the protocol's. */
+export const JSONRPC = '2.0'
+
+/** The prefix the revision reserves for itself in `_meta`. */
+export const RESERVED = 'io.modelcontextprotocol/'
+
+export const PROTOCOL_VERSION = RESERVED + 'protocolVersion'
+export const CLIENT_CAPABILITIES = RESERVED + 'clientCapabilities'
+export const SERVER_INFO = RESERVED + 'serverInfo'
+
+export type Params = Record<string, unknown>
+
+export interface Message {
+  jsonrpc: string
+  method: string
+  params?: Params
+
+  /** Absent makes this a notification, which is answered by not answering. */
+  id?: string | number
+}
+
+export interface Failure {
+  code: number
+  message: string
+  data?: unknown
+}
+
+export interface Response {
+  jsonrpc: string
+  id: string | number | null
+  result?: unknown
+  error?: Failure
+}
+
+/**
+ * How long a complete result may be held, and by whom. `private` is a result that is the
+ * caller's alone — a list `auth` filtered for their identity is not another caller's list.
+ */
+export interface Cache {
+  ttlMs: number
+  cacheScope: 'public' | 'private'
+}
+
+/** What a tool answers with: what a model reads, and the reply itself. */
+export interface Result {
+  content: Content[]
+  structuredContent?: unknown
+
+  /** The operation refused, which is something a model can read and correct. */
+  isError?: boolean
+}
+
+export interface Content {
+  type: 'text'
+  text: string
+}
+
+export interface Tool {
+  name: string
+
+  /** what the operation states it is; absent where it states nothing */
+  description?: string
+  inputSchema: object
+  outputSchema?: object
+  annotations?: Annotations
+}
+
+/** What the verb says about the call, which the revision asks a client to treat as a hint. */
+export interface Annotations {
+  readOnlyHint?: boolean
+  destructiveHint?: boolean
+  idempotentHint?: boolean
+}

package/source/Query.ts

@@ -4,6 +4,7 @@ import * as http from './HTTP/index.js'
 import { type Parameter } from './RTD/index.js'
 import * as schemas from './schemas.js'
 import { queryable } from './Mapping.js'
+import { take } from './Introspection.js'
 import type { Introspection, Schema } from './Introspection.js'
 import type * as syntax from './RTD/syntax/index.js'
 import type * as core from '@toa.io/core'
@@ -68,22 +69,43 @@ export class Query {
     }
   }
 
+  /**
+   * What the querystring carries: the parameters this method declares, taken out of the
+   * input because they are not the body's, and what a queryable method accepts besides.
+   *
+   * Only what it actually accepts — a criteria the declaration closes is refused, and so is
+   * a search where none was asked for.
+   */
   public explain (introspection: Introspection): Record<string, Schema> | null {
-    if (this.query?.parameters === undefined || introspection.input?.type !== 'object')
-      return null
-
     let query: Record<string, Schema> | null = null
 
-    for (const parameter of this.query.parameters) {
-      const schema = introspection.input.properties[parameter]
+    if (this.query?.parameters !== undefined)
+      for (const parameter of this.query.parameters) {
+        const schema = take(introspection, parameter)
+
+        // eslint-disable-next-line max-depth
+        if (schema === undefined)
+          continue
 
-      if (schema !== undefined) {
         query ??= {}
         query[parameter] = schema
       }
 
-      delete introspection.input.properties[parameter]
-    }
+    if (!this.queryable)
+      return query
+
+    query ??= {}
+
+    if (!this.closed)
+      query.criteria = keyword('string',
+        'What to match, in RSQL: `state==hot`, `rank=gt=5;name==*tea*`.')
+
+    query.sort = keyword('string', 'What to order by: `rank:desc`, or `rank` for ascending.')
+    query.limit = bounded('How many at once.', this.query.limit!)
+    query.omit = bounded('How many to skip.', this.query.omit!)
+
+    if (this.searchable)
+      query.search = keyword('string', 'What to search the text index for.')
 
     return query
   }
@@ -202,6 +224,24 @@ interface CriteriaGroup {
   operator: ',' | ';'
 }
 
+function keyword (type: string, description: string): Schema {
+  return { type, description } as unknown as Schema
+}
+
+function bounded (description: string, bounds: syntax.Range): Schema {
+  const schema: Record<string, unknown> = {
+    type: 'integer',
+    description,
+    minimum: bounds.range[0],
+    maximum: bounds.range[1]
+  }
+
+  if (bounds.value !== undefined)
+    schema.default = bounds.value
+
+  return schema as unknown as Schema
+}
+
 export interface QueryString {
   query: core.Query | null
   parameters: Record<string, string> | null

package/source/RPC/Context.ts

@@ -0,0 +1,78 @@
+import * as http from '../HTTP/index.js'
+import { Timing } from '../HTTP/Timing.js'
+import type { Params } from './types.js'
+
+/**
+ * One call, as a request the rest of the gateway can serve.
+ *
+ * The clone is the transport context except for what the call decides, so nothing
+ * downstream — the router, the directives, the endpoint, the mapping — knows it is one.
+ * It is derived from the context rather than built beside it, so everything not named
+ * here, `identity` included, is read through.
+ */
+// eslint-disable-next-line max-params
+export function fork (context: http.Context, path: string, verb: string,
+  query: Params | undefined, input: unknown): http.Context {
+  const url = new URL(path, context.url)
+
+  if (query !== undefined)
+    for (const [name, value] of Object.entries(query))
+      url.searchParams.set(name, String(value))
+
+  const headers = { ...context.request.headers }
+
+  // a conditional is the envelope's, and a call would answer 304 to a question nobody asked
+  delete headers['if-match']
+  delete headers['if-none-match']
+
+  const request = Object.create(context.request, {
+    method: { value: verb, enumerable: true },
+    headers: { value: headers, enumerable: true }
+  })
+
+  // its own, so an `io:output` restriction shapes this call's reply and no other
+  const pipelines: Pipelines = { body: [], response: [] }
+
+  return Object.create(context, {
+    /*
+     * A credential refuses an `anonymous` route because it would make the reply
+     * uncacheable. What a procedure answers is not a reply: it is a value in an envelope
+     * this gateway answers `no-store`, and the procedure's own headers are discarded.
+     */
+    procedural: { value: true, enumerable: true },
+    url: { value: url, enumerable: true },
+    request: { value: request, enumerable: true },
+    pipelines: { value: pipelines, enumerable: true },
+    /*
+     * Its own, so that what the stages of a call take is measured per call and stays there.
+     * `server-timing` is a header, and a request carrying thirty-two calls would otherwise
+     * write ninety-six values into one — where a trace says the same thing, per call.
+     */
+    timing: { value: new Timing(), enumerable: true },
+    body: {
+      value: async () => {
+        let value = input
+
+        for (const transform of pipelines.body)
+          value = await transform(value)
+
+        return value
+      }
+    },
+    /*
+     * The raw request is the envelope, and it has been read. `map:buffer` is the one
+     * directive that asks for it, and answering with a spent stream would hand the
+     * operation an empty string; refusing says what is actually the matter.
+     */
+    buffer: {
+      value: () => {
+        throw new http.BadRequest('`map:buffer` reads the request, which a call is not')
+      }
+    }
+  }) as http.Context
+}
+
+interface Pipelines {
+  body: Array<(input: unknown) => unknown>
+  response: Array<(output: http.OutgoingMessage) => void | Promise<void>>
+}

package/source/RPC/Dispatcher.ts

@@ -0,0 +1,130 @@
+import { console } from 'openspan'
+import * as http from '../HTTP/index.js'
+import * as schemas from '../schemas.js'
+import { BATCH } from '../const.js'
+import { address, split } from './names.js'
+import { fork } from './Context.js'
+import { BATCH_TOO_LARGE, INVALID_REQUEST, PARSE, failure, of, response } from './errors.js'
+import { VERSION, type Call, type Response } from './types.js'
+import type { RPC } from '../Annotation.js'
+
+/**
+ * JSON-RPC, as the calls a request carries.
+ *
+ * It clones the context per call and hands each clone back to the gateway: it holds no
+ * tree, no index and no knowledge of routing. Whether a name resolves, what it resolves
+ * to, and what the directives of that route do are answered by the same `route` an
+ * ordinary request goes through.
+ */
+export class Dispatcher {
+  private readonly batch: number
+
+  public constructor (options: RPC) {
+    this.batch = options.batch ?? BATCH
+  }
+
+  public async dispatch (context: http.Context,
+    route: http.Processor): Promise<http.OutgoingMessage> {
+    if (context.request.method !== 'POST')
+      throw new http.MethodNotAllowed(new Headers({ allow: 'POST' }))
+
+    const envelope = await this.read(context)
+    const batched = Array.isArray(envelope)
+    const calls = batched ? envelope : [envelope]
+
+    if (calls.length === 0)
+      throw new http.BadRequest(response(null,
+        failure(INVALID_REQUEST, 'A request carries at least one call')))
+
+    if (calls.length > this.batch)
+      throw new http.BadRequest(response(null,
+        failure(BATCH_TOO_LARGE, `A request carries at most ${this.batch} calls`)))
+
+    const answers: Response[] = []
+
+    // one after another: a request the caller writes should not become a fan-out they own
+    for (const call of calls) {
+      const answer = await this.answer(call, context, route)
+
+      if (answer !== null)
+        answers.push(answer)
+    }
+
+    // every call was a notification, and a notification is answered by not answering
+    if (answers.length === 0)
+      return { status: NO_CONTENT }
+
+    // a reply assembled from several is not one of them, and is not stored as if it were
+    return {
+      status: OK,
+      body: batched ? answers : answers[0],
+      headers: new Headers({ 'cache-control': 'no-store' })
+    }
+  }
+
+  private async answer (input: unknown, context: http.Context,
+    route: http.Processor): Promise<Response | null> {
+    const invalid = schemas.call.fit(input)
+
+    // it may have carried an id, but nothing about it is trustworthy enough to answer to
+    if (invalid !== null)
+      return response(null, failure(INVALID_REQUEST, invalid.message))
+
+    return await this.call(input as Call, context, route)
+  }
+
+  private async call (call: Call, context: http.Context,
+    route: http.Processor): Promise<Response | null> {
+    const notification = call.id === undefined
+
+    try {
+      const params = call.params ?? {}
+      const { path, verb, variables } = address(call.method, params)
+      const { query, input } = split(params, variables)
+      const clone = fork(context, path, verb, query, input)
+
+      // one span per call, so what the directives of that call open has somewhere to hang
+      const message = await console.span({ name: call.method, attributes: { id: call.id } },
+        async () => await route(clone))
+
+      // what `io:output` restricts, over this call's reply rather than the envelope
+      await http.shape(clone, message)
+
+      if (notification)
+        return null
+
+      return { jsonrpc: VERSION, id: call.id!, result: message.body ?? null }
+    } catch (exception) {
+      /*
+       * A credential belongs to the request. Refusing one call for it would leave the
+       * reply a 200, and the challenge that tells a client where to authenticate is
+       * attached to a 401 — so the whole envelope is refused instead.
+       */
+      if (exception instanceof http.Unauthorized)
+        throw exception
+
+      if (notification) {
+        console.debug('Notification failed', { method: call.method, error: of(exception) })
+
+        return null
+      }
+
+      return { jsonrpc: VERSION, id: call.id!, error: of(exception) }
+    }
+  }
+
+  /** A body the decoder refuses is a parse error; a media type it does not know is not. */
+  private async read (context: http.Context): Promise<unknown> {
+    try {
+      return await context.body()
+    } catch (exception) {
+      if (exception instanceof http.BadRequest)
+        throw new http.BadRequest(response(null, failure(PARSE, 'Parse error')))
+
+      throw exception
+    }
+  }
+}
+
+const OK = 200
+const NO_CONTENT = 204

package/source/RPC/errors.test.ts

@@ -0,0 +1,52 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import * as http from '../HTTP/index.js'
+import {
+  FORBIDDEN, INTERNAL, INVALID_PARAMS, METHOD_NOT_FOUND, REFUSED, of
+} from './errors.js'
+
+describe('of', () => {
+  it('should read a missing route as a missing method', () => {
+    assert.deepEqual(of(new http.NotFound('pots/_id/FETCH names no method')),
+      { code: METHOD_NOT_FOUND, message: 'pots/_id/FETCH names no method' })
+  })
+
+  it('should read a verb the node does not declare as a missing method', () => {
+    assert.deepEqual(of(new http.MethodNotAllowed()),
+      { code: METHOD_NOT_FOUND, message: 'Method not found' })
+  })
+
+  it('should read a refused authorization as forbidden', () => {
+    assert.deepEqual(of(new http.Forbidden()), { code: FORBIDDEN, message: 'Forbidden' })
+  })
+
+  it('should read a bad request as invalid params', () => {
+    assert.deepEqual(of(new http.BadRequest('Query limit must be between 1 and 100')),
+      { code: INVALID_PARAMS, message: 'Query limit must be between 1 and 100' })
+  })
+
+  it('should carry the code an operation refused with', () => {
+    const error = Object.assign(new Error(), { code: 'WONT_CREATE', message: 'Volume is out of range' })
+
+    assert.deepEqual(of(new http.UnprocessableEntity(error)),
+      { code: REFUSED, message: 'Volume is out of range', data: { code: 'WONT_CREATE' } })
+  })
+
+  it('should stand the code in for a message the operation did not declare', () => {
+    const error = Object.assign(new Error(), { code: 'WONT_CREATE' })
+
+    assert.deepEqual(of(new http.UnprocessableEntity(error)),
+      { code: REFUSED, message: 'WONT_CREATE', data: { code: 'WONT_CREATE' } })
+  })
+
+  it('should say what any other client error was refused with', () => {
+    assert.deepEqual(of(new http.Conflict()),
+      { code: REFUSED, message: 'Refused', data: { status: 409 } })
+  })
+
+  it('should say nothing of what it did not mean to answer', () => {
+    assert.deepEqual(of(new Error('the connection dropped')),
+      { code: INTERNAL, message: 'Internal error' })
+  })
+})

package/source/RPC/errors.ts

@@ -0,0 +1,83 @@
+import * as http from '../HTTP/index.js'
+import { VERSION, type Failure, type Response } from './types.js'
+
+/*
+ * The five the specification fixes (JSON-RPC 2.0 §5.1). A client reads these the same
+ * whoever answers.
+ */
+export const PARSE = -32700
+export const INVALID_REQUEST = -32600
+export const METHOD_NOT_FOUND = -32601
+export const INVALID_PARAMS = -32602
+export const INTERNAL = -32603
+
+/*
+ * Ours. The specification reserves -32000 to -32099 for implementation-defined server
+ * errors and defines nothing in it, so these mean nothing outside Toa — which is why
+ * `REFUSED` carries the operation's own code in `data`.
+ */
+export const FORBIDDEN = -32000
+export const REFUSED = -32001
+export const BATCH_TOO_LARGE = -32002
+
+export function failure (code: number, message: string, data?: unknown): Failure {
+  const value: Failure = { code, message }
+
+  if (data !== undefined)
+    value.data = data
+
+  return value
+}
+
+export function response (id: string | number | null, error: Failure): Response {
+  return { jsonrpc: VERSION, id, error }
+}
+
+/**
+ * What an exception says as a JSON-RPC error.
+ *
+ * The readable text is `body`, never `message`: `http.Exception` calls `super()` with no
+ * argument, so every one of them carries an empty `message`.
+ */
+export function of (exception: unknown): Failure {
+  if (exception instanceof http.UnprocessableEntity)
+    return refusal(exception)
+
+  if (exception instanceof http.NotFound || exception instanceof http.MethodNotAllowed)
+    return failure(METHOD_NOT_FOUND, text(exception, 'Method not found'))
+
+  if (exception instanceof http.Forbidden)
+    return failure(FORBIDDEN, text(exception, 'Forbidden'))
+
+  if (exception instanceof http.BadRequest)
+    return failure(INVALID_PARAMS, text(exception, 'Invalid params'))
+
+  // a conflict, a precondition, a throttle: the call was refused, and by what is worth saying
+  if (exception instanceof http.ClientError)
+    return failure(REFUSED, text(exception, 'Refused'), { status: exception.status })
+
+  return failure(INTERNAL, 'Internal error')
+}
+
+/**
+ * An operation that declares its errors answers with one rather than throwing, and the
+ * reply contract states `{ code, message? }` — the message optional. The number says the
+ * operation refused; `data.code` says what it refused with, and is what a caller branches on.
+ */
+function refusal (exception: http.UnprocessableEntity): Failure {
+  const body = exception.body
+
+  if (typeof body !== 'object' || body === null || typeof body.code !== 'string')
+    return failure(REFUSED, text(exception, 'Refused'))
+
+  const code = body.code as string
+  const message = typeof body.message === 'string' && body.message !== '' ? body.message : code
+
+  return failure(REFUSED, message, { code })
+}
+
+function text (exception: http.Exception, fallback: string): string {
+  return typeof exception.body === 'string' && exception.body !== ''
+    ? exception.body
+    : fallback
+}

package/source/RPC/index.ts

@@ -0,0 +1 @@
+export { Dispatcher } from './Dispatcher.js'