@toa.io/extensions.exposition 1.0.0-alpha.292 → 1.0.0-alpha.293

package/source/MCP/tools.ts

@@ -1,144 +0,0 @@
-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 { describing } from '../Introspection.js'
-import { variables } from '../RTD/segment.js'
-import type { 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, request: http.Context): Promise<Tool[]> {
-  const tools: Tool[] = []
-
-  /*
-   * A description, not 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 context = describing(request)
-
-  for (const { segments, verb, method } of tree.walk()) {
-    if (!MCP.published(method.directives.declared<Declaration>(FAMILY))) 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 params = variables(segments)
-    const introspection = await method.explain(context, params)
-
-    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,
-      ...(introspection.title === undefined ? {} : { title: introspection.title }),
-      ...(described === undefined ? {} : { description: described }),
-      inputSchema: input(
-        introspection,
-        params.map((param) => param.name),
-        method.endpoint?.selection() ?? null
-      ),
-      ...(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))
-
-  return false
-}
-
-function result(body: unknown): Result {
-  if (body === undefined || body === null) return { content: [] }
-
-  return {
-    content: [{ type: 'text', text: JSON.stringify(body) }],
-    structuredContent: body
-  }
-}

package/source/MCP/types.ts

@@ -1,84 +0,0 @@
-/** 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 a person is shown where a client lists this tool; a name is an address */
-  title?: string
-
-  /** what the route states this method is */
-  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/Mapping.ts

@@ -1,101 +0,0 @@
-import { type Parameter } from './RTD/index.js'
-import { Query } from './Query.js'
-import type { Introspection, Schema } from './Introspection.js'
-import type { QueryString } from './Query.js'
-import type * as http from './HTTP/index.js'
-import type * as syntax from './RTD/syntax/index.js'
-import type * as core from '@toa.io/core/types'
-
-export abstract class Mapping {
-  protected readonly query: Query
-  public abstract readonly queryable: boolean
-
-  public constructor(query: Query) {
-    this.query = query
-  }
-
-  public static create(query?: syntax.Query | null, paged?: boolean): Mapping {
-    const q = new Query(query!, paged)
-
-    return queryable(query) ? new QueryableMapping(q) : new InputMapping(q)
-  }
-
-  public explain(introspection: Introspection): Record<string, Schema> | null {
-    return this.query.explain(introspection)
-  }
-
-  /** What picks the records a call is about; see `Query.selection`. */
-  public selection(): Record<string, Schema> | null {
-    return this.query.selection()
-  }
-
-  protected assign(input: any, qs: QueryString): void {
-    if (qs.parameters !== null) {
-      if (typeof input !== 'object' || input === null)
-        throw new Error('Input must be an object to embed query parameters')
-
-      Object.assign(input, qs.parameters)
-    }
-  }
-
-  public abstract fit(
-    input: any,
-    query: http.Query,
-    parameters: Parameter[]
-  ): core.Request
-}
-
-class QueryableMapping extends Mapping {
-  public override readonly queryable = true
-
-  public fit(input: any, query: http.Query, parameters: Parameter[]): core.Request {
-    const request: core.Request = {}
-    const qs = this.query.fit(query, parameters)
-
-    if (input === undefined && qs.parameters !== null) input = {}
-
-    this.assign(input, qs)
-
-    if (input !== undefined) request.input = input
-
-    if (qs.query !== null) request.query = qs.query
-
-    return request
-  }
-}
-
-class InputMapping extends Mapping {
-  public override readonly queryable = false
-
-  public fit(input: any, query: http.Query, parameters: Parameter[]): core.Request {
-    const request: core.Request = {}
-    const qs = this.query.fit(query, parameters)
-
-    if (
-      input === undefined &&
-      (this.query.parameterized || parameters.length > 0 || qs.parameters !== null)
-    )
-      input = {}
-
-    if (parameters.length > 0) {
-      if (typeof input !== 'object' || input === null)
-        throw new Error('Input must be an object to embed parameters')
-
-      for (const parameter of parameters) input[parameter.name] = parameter.value
-    }
-
-    this.assign(input, qs)
-
-    if (input !== undefined) request.input = input
-
-    return request
-  }
-}
-
-export function queryable(query?: syntax.Query | null): boolean {
-  if (query === undefined || query === null) return false
-
-  const keys = Object.keys(query)
-
-  return !(keys.length === 1 && keys[0] === 'parameters')
-}

package/source/Query.test.ts

@@ -1,54 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Query } from './Query.js'
-import { type Parameter, type syntax } from './RTD/index.js'
-
-it('should combine request criteria', async () => {
-  const query: syntax.Query = {
-    criteria: 'foo==1;',
-    omit: { range: [0, 1] },
-    limit: { range: [0, 1] }
-  }
-
-  const parameters: Parameter[] = [
-    { name: 'bar', value: '2' },
-    { name: 'baz', value: '3' }
-  ]
-
-  const instance = new Query(query)
-  const result = instance.fit({ criteria: 'qux==4' }, parameters)
-
-  assert.deepStrictEqual(result.query!.criteria, '(bar=="2";baz=="3");(foo==1);(qux==4)')
-})
-
-it('should quote parameter values', async () => {
-  const query: syntax.Query = {
-    omit: { range: [0, 1] },
-    limit: { range: [0, 1] }
-  }
-
-  const parameters: Parameter[] = [{ name: 'user', value: 'me"),(user=="victim' }]
-
-  const instance = new Query(query)
-  const result = instance.fit({}, parameters)
-
-  assert.deepStrictEqual(result.query!.criteria, '(user=="me\\"),(user==\\"victim")')
-})
-
-it('should set id parameter as query.id', async () => {
-  const query: syntax.Query = {
-    omit: { range: [0, 1] },
-    limit: { range: [0, 1] }
-  }
-
-  const id = '87782631058445da81cb82f78b20c223'
-
-  const parameters: Parameter[] = [{ name: 'id', value: id }]
-
-  const instance = new Query(query)
-  const result = instance.fit({}, parameters)
-
-  assert.strictEqual(result.query!.criteria, undefined)
-  assert.deepStrictEqual(result.query!.id, id)
-})

package/source/Query.ts

@@ -1,277 +0,0 @@
-import assert from 'node:assert'
-import { quote } from '@toa.io/generic'
-import * as http from './HTTP/index.js'
-import { type Parameter } from './RTD/index.js'
-import { schemas } from '@toa.io/definitions/extensions.exposition'
-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/types'
-
-export class Query {
-  public readonly parameterized: boolean
-
-  private readonly query: syntax.Query
-  private readonly closed: boolean = false
-  private readonly prepend: ',' | ';' = ';'
-  private readonly queryable: boolean
-  private readonly searchable: boolean
-
-  /** whether a page is taken of what this answers, and so whether `omit` and `limit` apply */
-  private readonly paged: boolean
-
-  public constructor(query: syntax.Query, paged = true) {
-    this.parameterized = query?.parameters !== undefined
-    this.queryable = queryable(query)
-    this.searchable = query?.search === true
-    this.paged = paged
-
-    if (this.queryable) {
-      if (this.paged) {
-        query.omit ??= { value: 0, range: [0, 1000] }
-        query.limit ??= { value: 10, range: [1, 100] }
-      }
-
-      if (query.criteria !== undefined) {
-        // eslint-disable-next-line max-depth
-        if (query.criteria.endsWith(';')) query.criteria = query.criteria.slice(0, -1)
-        else this.closed = true
-
-        // eslint-disable-next-line max-depth
-        if (query.criteria.startsWith(',') || query.criteria.startsWith(';')) {
-          this.prepend = query.criteria[0] as ',' | ';'
-
-          query.criteria = query.criteria.slice(1)
-        }
-      }
-    }
-
-    this.query = query
-  }
-
-  public fit(query: http.Query, parameters: Parameter[]): QueryString {
-    const qs = this.split(query)
-
-    if (qs.query !== null) {
-      const error = schemas.querystring.fit(qs.query)
-
-      if (error !== null) throw new http.BadRequest('Query ' + error.message)
-
-      this.fitCriteria(qs.query, parameters)
-
-      if (this.paged) this.fitRanges(qs.query)
-      else this.refuseRanges(qs.query)
-
-      this.fitSort(qs.query)
-
-      if (this.query.deleted !== undefined)
-        (qs.query as core.Query).deleted = this.query.deleted
-    }
-
-    return {
-      query: qs.query as core.Query,
-      parameters: qs.parameters
-    }
-  }
-
-  /**
-   * 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.
-   */
-  /**
-   * The querystring parameters this resource declares, which are properties of its own
-   * taken out of the input. What selects records is not among them: that is the same of
-   * every queryable resource, and `selection` is where it is stated.
-   */
-  public explain(introspection: Introspection): Record<string, Schema> | null {
-    let query: Record<string, Schema> | null = null
-
-    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
-
-        query ??= {}
-        query[parameter] = schema
-      }
-
-    return query
-  }
-
-  /**
-   * What picks the records a call is about, which is the querystring the gateway reads
-   * rather than anything the resource declares — the same for every queryable resource,
-   * and so not what one says about itself. A procedure states it, because there it is
-   * something the caller sends.
-   */
-  public selection(): Record<string, Schema> | null {
-    if (!this.queryable) return null
-
-    const query: Record<string, Schema> = {}
-
-    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.'
-    )
-
-    if (this.paged) {
-      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
-  }
-
-  private split(query: http.Query): {
-    query: http.Query | null
-    parameters: Record<string, string> | null
-  } {
-    let parameters: Record<string, string> | null = null
-
-    if (this.query?.parameters !== undefined)
-      for (const key in query)
-        // eslint-disable-next-line max-depth
-        if (this.query.parameters.includes(key)) {
-          parameters ??= {}
-          parameters[key] = query[key] as string
-
-          delete query[key]
-        }
-
-    if (!this.queryable) {
-      const keys = Object.keys(query)
-
-      if (keys.length > 0)
-        throw new http.BadRequest(`Query parameter '${keys[0]}' is not allowed`)
-
-      query = null!
-    }
-
-    if (query?.search !== undefined && !this.searchable)
-      throw new http.BadRequest('Query search is not allowed')
-
-    return {
-      query,
-      parameters
-    }
-  }
-
-  private fitCriteria(query: http.Query, parameters: Parameter[]): void {
-    const groups: CriteriaGroup[] = []
-    const idx = parameters.findIndex((parameter) => parameter.name === 'id')
-
-    if (idx !== -1) {
-      query.id = parameters[idx].value
-
-      parameters.splice(idx, 1)
-    }
-
-    if (parameters.length > 0) {
-      // a segment may carry `,` `;` `(` `)` `=`, which is criteria grammar when unquoted
-      const criteria = parameters
-        .map(({ name, value }) => `${name}==${quote(value)}`)
-        .join(';')
-
-      groups.push({ criteria, operator: this.prepend })
-    }
-
-    if (this.query.criteria !== undefined)
-      groups.push({ criteria: this.query.criteria, operator: ';' })
-
-    if (query.criteria !== undefined)
-      if (this.closed) throw new http.BadRequest('Query criteria is closed')
-      else groups.push({ criteria: query.criteria, operator: WHATEVER })
-
-    if (groups.length > 0)
-      query.criteria = groups.reduce((acc, { criteria, operator }, i) => {
-        return i === groups.length - 1
-          ? `${acc}(${criteria})`
-          : `${acc}(${criteria})${operator}`
-      }, '')
-  }
-
-  /** A route that answers one object is not paged, so a request that pages it is a mistake. */
-  private refuseRanges(qs: http.Query): void {
-    for (const name of ['omit', 'limit'] as const)
-      if (qs[name] !== undefined)
-        throw new http.BadRequest(`Query ${name} is not allowed`)
-  }
-
-  private fitRanges(qs: http.Query): void {
-    const query = qs as core.Query
-
-    assert.ok(this.query.limit !== undefined, 'Query limit must be defined')
-    assert.ok(this.query.omit !== undefined, 'Query limit range must be defined')
-
-    if (qs.limit !== undefined)
-      query.limit = fit(qs.limit, this.query.limit.range, 'limit')
-    else query.limit = this.query.limit.value
-
-    if (qs.omit !== undefined) query.omit = fit(qs.omit, this.query.omit.range, 'omit')
-  }
-
-  private fitSort(qs: http.Query): void {
-    const query = qs as core.Query
-
-    if (qs.sort === undefined && this.query.sort === undefined) return
-
-    const sort = (this.query.sort ?? '') + (qs.sort ?? '')
-
-    query.sort = sort.split(';')
-  }
-}
-
-function fit(string: string, range: [number, number], name: string): number {
-  const number = parseInt(string)
-
-  if (number < range[0] || number > range[1])
-    throw new http.BadRequest(
-      `Query ${name} must be between ${range[0]} and ${range[1]} inclusive`
-    )
-
-  return number
-}
-
-const WHATEVER = ';'
-
-interface CriteriaGroup {
-  criteria: string
-  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
-}