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

package/source/Introspection.ts

@@ -1,179 +0,0 @@
-import type { Remote } from '@toa.io/core'
-import type { Context } from './HTTP/index.js'
-
-export interface Introspection {
-  /**
-   * What the route states this method is. The operation states what it is too, and that is
-   * not this: an operation is written without knowledge of any route, and a method is an
-   * operation and a route together — the same operation mounted twice is two methods, and
-   * one sentence cannot be true of both. The operation's own is for the Introspection.
-   */
-  description?: string
-
-  /** what a person is shown where a client lists this method, which a name is not */
-  title?: string
-
-  /**
-   * whether reaching it takes nothing at all — `auth:anonymous`. Said rather than left
-   * unsaid, because it is also what refuses a caller presenting a credential: a client
-   * cannot know that from an answer that says nothing.
-   */
-  anonymous?: boolean
-
-  /** whether reaching it takes being someone, whoever — `auth:anyone` and its like */
-  authenticated?: boolean
-
-  /** whether reaching it is being the identity it is about — `auth:id` */
-  private?: boolean
-
-  /** whether reaching it takes a role — `auth:role` */
-  protected?: boolean
-
-  /** and whether that role is one of the `system` scope */
-  system?: boolean
-
-  /** whether the route publishes this method to a model — [`mcp:tool`](mcp.md) */
-  mcp?: boolean
-  route?: Record<string, Schema>
-  query?: Record<string, Schema>
-
-  /** what the body is, where it is a file rather than a value — [`octets:put`](octets.md) */
-  octets?: Octets
-  input?: Schema
-  output?: Schema
-  errors?: string[]
-}
-
-/** What sending a file to a resource takes, which is not something a schema states. */
-export interface Octets {
-  /** what may be sent, in the syntax of an `accept` header; anything where unstated */
-  accept?: string
-
-  /** the largest body it takes, as it is written and as a refusal reports it */
-  limit: string
-
-  /**
-   * Whether the reply arrives as a stream of parts rather than as one object: a workflow
-   * runs on what was stored, and each step answers as it finishes. The first part is the
-   * entry itself, which is what a caller that wants nothing else reads and stops.
-   */
-  stream?: boolean
-}
-
-export type Schema = Awaited<ReturnType<Remote['explain']>>['input']
-
-/**
- * The same request, as a description of a resource rather than a call to one. A directive
- * that answers differently to the two reads `exploratory` — `Anonymous` is the one that
- * does, because the rule refusing a credential at an `anonymous` route is about a reply a
- * cache would hold, and a description is not one.
- */
-export function describing(context: Context): Context {
-  return Object.create(context, {
-    exploratory: { value: true, enumerable: true }
-  }) as Context
-}
-
-/**
- * The same, in the order the shape states — whatever order the families that filled it ran
- * in. What a resource says about itself is read, so it is written the way it is documented.
- */
-export function order(introspection: Introspection): Introspection {
-  const ordered: Introspection = {}
-
-  for (const key of KEYS)
-    if (introspection[key] !== undefined) (ordered[key] as unknown) = introspection[key]
-
-  return ordered
-}
-
-const KEYS = [
-  'title',
-  'description',
-  'anonymous',
-  'authenticated',
-  'private',
-  'protected',
-  'system',
-  'mcp',
-  'route',
-  'query',
-  'octets',
-  'input',
-  'output',
-  'errors'
-] as const
-
-/**
- * The schema of one input property, taken out of it: a property another family fills is
- * not the caller's to send, and what took it says where it comes from instead.
- */
-export function take(carrier: Carrier, property: string): Schema | undefined {
-  const input = carrier.input as Shape | null | undefined
-  const properties = input?.properties
-
-  if (
-    input === undefined ||
-    input === null ||
-    properties === undefined ||
-    !(property in properties)
-  )
-    return undefined
-
-  const schema = properties[property]
-
-  delete properties[property]
-
-  if (input.required !== undefined)
-    input.required = input.required.filter((name) => name !== property)
-
-  return schema
-}
-
-/**
- * A schema restricted to the properties a whitelist admits, and an array's items where it
- * describes an array. What is not an object of properties is left alone: a whitelist has
- * nothing to say about a string.
- */
-export function restrict(
-  schema: Schema | undefined,
-  allowed: Set<string>
-): Schema | undefined {
-  const shape = schema as Shape | null | undefined
-
-  if (shape === undefined || shape === null) return schema
-
-  if (shape.items !== undefined)
-    return { ...shape, items: restrict(shape.items, allowed) } as unknown as Schema
-
-  if (shape.properties === undefined) return schema
-
-  const properties: Record<string, Schema> = {}
-
-  for (const [name, property] of Object.entries(shape.properties))
-    if (allowed.has(name)) properties[name] = property
-
-  const restricted: Shape = { ...shape, properties }
-
-  if (shape.required !== undefined)
-    restricted.required = shape.required.filter((name) => allowed.has(name))
-
-  return restricted as unknown as Schema
-}
-
-/**
- * What a schema is read as here: the keywords these narrow, and whatever else it carries.
- * `Schema` as core declares it requires `properties`, which a schema of a string has not,
- * so the two are cast through rather than assigned.
- */
-/** Whatever states an input: an explanation as the operation gave it, or as a route left it. */
-interface Carrier {
-  input?: Schema
-}
-
-interface Shape {
-  properties?: Record<string, Schema>
-  required?: string[]
-  items?: Schema
-  [keyword: string]: unknown
-}

package/source/MCP/Server.ts

@@ -1,335 +0,0 @@
-import { console } from 'openspan'
-import { BRANCH_TTL } from '../const.js'
-import * as http from '../HTTP/index.js'
-import { discovery, type Discovery } from './discover.js'
-import { call, list, type Scope } from './tools.js'
-import {
-  HEADER_MISMATCH,
-  INVALID_PARAMS,
-  INVALID_REQUEST,
-  METHOD_NOT_FOUND,
-  PARSE,
-  UNSUPPORTED_VERSION,
-  failure,
-  response
-} from './errors.js'
-import {
-  CLIENT_CAPABILITIES,
-  JSONRPC,
-  LEGACY,
-  MODERN,
-  PROTOCOL_VERSION,
-  SERVER_INFO,
-  VERSIONS,
-  type Cache,
-  type Message,
-  type Params
-} from './types.js'
-import type { Tree } from '../RTD/index.js'
-import type { MCP } from '../Annotation.js'
-
-/**
- * The Model Context Protocol, as one endpoint that remembers nothing between requests.
- *
- * Two revisions are answered from it. The modern one carries the version and the client's
- * capabilities in every request; the one before it opens with `initialize`, which is what
- * most clients still send. Neither needs a session, and neither needs a stream: every method
- * here answers one object, which is why this can exist in a package that serves no SSE.
- */
-export class Server {
-  private readonly options: MCP
-  private readonly tree: Tree
-  private readonly discovery: Discovery
-  private readonly origins: Set<string>
-
-  public constructor(options: MCP, tree: Tree) {
-    this.options = options
-    this.tree = tree
-    this.discovery = discovery(options)
-    this.origins = new Set(options.origins ?? [])
-  }
-
-  public async process(
-    context: http.Context,
-    route: http.Processor
-  ): Promise<http.OutgoingMessage> {
-    if (context.request.method !== 'POST')
-      throw new http.MethodNotAllowed(new Headers({ allow: 'POST' }))
-
-    this.admit(context)
-
-    const message = await this.read(context)
-    const version = this.version(context, message)
-    const modern = version === MODERN
-
-    if (modern) this.mirrored(context, message)
-
-    const result = await this.answer({ context, route, tree: this.tree }, message, modern)
-
-    // a notification is answered by not answering, and there is nothing here to remember
-    if (message.id === undefined) return { status: ACCEPTED }
-
-    return {
-      status: OK,
-      body: { jsonrpc: JSONRPC, id: message.id, result },
-      headers: new Headers({ 'cache-control': 'no-store' })
-    }
-  }
-
-  /** Who may reach the endpoint at all, before anything it carries is read. */
-  private admit(context: http.Context): void {
-    const origin = context.request.headers.origin
-
-    // the revision requires this against DNS rebinding; a request without one is no browser's
-    if (origin !== undefined && !this.origins.has(origin))
-      throw new http.Forbidden('Origin is not allowed')
-
-    if (this.options.anonymous === true) return
-
-    if ((context as { identity?: unknown }).identity == null)
-      throw new http.Unauthorized()
-  }
-
-  private async answer(
-    scope: Scope,
-    message: Message,
-    modern: boolean
-  ): Promise<unknown> {
-    const params = message.params ?? {}
-
-    switch (message.method) {
-      case 'server/discover':
-        return this.complete(this.discovery.modern, modern, DISCOVERY_CACHE)
-
-      case 'tools/list':
-        return this.complete(
-          { tools: await list(this.tree, scope.context) },
-          modern,
-          TOOLS_CACHE
-        )
-
-      case 'tools/call':
-        return this.complete(await this.tool(scope, params), modern)
-
-      // what a client of an earlier revision opens with; no session is made and none is named
-      case 'initialize':
-        return this.discovery.legacy(declared(params))
-
-      case 'notifications/initialized':
-        return null
-
-      case 'ping':
-        return {}
-
-      default:
-        throw new http.NotFound(
-          response(
-            message.id ?? null,
-            failure(
-              METHOD_NOT_FOUND,
-              `'${message.method}' is not a method this server answers`
-            )
-          )
-        )
-    }
-  }
-
-  private async tool(scope: Scope, params: Params): Promise<object> {
-    const named = params.name
-
-    if (typeof named !== 'string')
-      throw new http.BadRequest(
-        response(
-          null,
-          failure(INVALID_PARAMS, '`tools/call` states the tool it calls by name')
-        )
-      )
-
-    const args = params.arguments ?? {}
-
-    if (typeof args !== 'object' || args === null || Array.isArray(args))
-      throw new http.BadRequest(
-        response(null, failure(INVALID_PARAMS, '`arguments` must be an object'))
-      )
-
-    return await console.span(
-      { name: named },
-      async () => await call(scope, named, args as Params)
-    )
-  }
-
-  /**
-   * Every result of the modern revision says what kind it is, and who answered it. Where the
-   * revision names the operation as one whose result may be held, it says that too, and must.
-   */
-  private complete(result: object, modern: boolean, cache?: Cache): object {
-    return modern
-      ? {
-          ...result,
-          ...cache,
-          resultType: 'complete',
-          _meta: { [SERVER_INFO]: this.serverInfo() }
-        }
-      : result
-  }
-
-  private serverInfo(): unknown {
-    return (this.discovery.modern as { _meta: Record<string, unknown> })._meta[
-      SERVER_INFO
-    ]
-  }
-
-  /**
-   * Which revision this request is of. `initialize` is one by itself; otherwise the header
-   * says, and a request that names none is of a revision that did not send one.
-   */
-  private version(context: http.Context, message: Message): string {
-    if (message.method === 'initialize') return LEGACY
-
-    const header = context.request.headers['mcp-protocol-version']
-    const stated = declared(message.params ?? {})
-
-    if (header !== undefined && stated !== undefined && header !== stated)
-      throw new http.BadRequest(
-        response(
-          message.id ?? null,
-          failure(
-            HEADER_MISMATCH,
-            `'MCP-Protocol-Version' says '${String(header)}' and the body says '${stated}'`
-          )
-        )
-      )
-
-    const value = (header as string | undefined) ?? stated
-
-    if (value === undefined) return LEGACY
-
-    if (!VERSIONS.includes(value))
-      throw new http.BadRequest(
-        response(
-          message.id ?? null,
-          failure(UNSUPPORTED_VERSION, 'Unsupported protocol version', {
-            supported: VERSIONS,
-            requested: value
-          })
-        )
-      )
-
-    return value
-  }
-
-  /**
-   * What the modern revision mirrors into headers, so that what routes a request and what
-   * answers it cannot be told two different things.
-   */
-  private mirrored(context: http.Context, message: Message): void {
-    const meta = metadata(message.params ?? {})
-
-    if (meta?.[PROTOCOL_VERSION] === undefined || meta[CLIENT_CAPABILITIES] === undefined)
-      throw new http.BadRequest(
-        response(
-          message.id ?? null,
-          failure(
-            INVALID_PARAMS,
-            `'_meta' states '${PROTOCOL_VERSION}' and '${CLIENT_CAPABILITIES}'`
-          )
-        )
-      )
-
-    const id = message.id ?? null
-
-    mirrors(context, { id, header: 'mcp-method', value: message.method })
-
-    if (message.method === 'tools/call')
-      mirrors(context, { id, header: 'mcp-name', value: (message.params ?? {}).name })
-  }
-
-  /** 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<Message> {
-    let body: unknown
-
-    try {
-      body = await context.body()
-    } catch (exception) {
-      if (exception instanceof http.BadRequest)
-        throw new http.BadRequest(response(null, failure(PARSE, 'Parse error')))
-
-      throw exception
-    }
-
-    if (
-      typeof body !== 'object' ||
-      body === null ||
-      Array.isArray(body) ||
-      (body as Message).jsonrpc !== JSONRPC ||
-      typeof (body as Message).method !== 'string'
-    )
-      throw new http.BadRequest(
-        response(null, failure(INVALID_REQUEST, 'A request carries one JSON-RPC message'))
-      )
-
-    return body as Message
-  }
-}
-
-/** What a header says must be what the body says, or what routes and what answers differ. */
-function mirrors(context: http.Context, mirror: Mirror): void {
-  const { id, header, value } = mirror
-  const stated = context.request.headers[header]
-
-  if (stated === undefined)
-    throw new http.BadRequest(
-      response(id, failure(HEADER_MISMATCH, `'${header}' is required`))
-    )
-
-  if (decode(String(stated)) !== value)
-    throw new http.BadRequest(
-      response(
-        id,
-        failure(
-          HEADER_MISMATCH,
-          `'${header}' says '${String(stated)}' and the body says '${String(value)}'`
-        )
-      )
-    )
-}
-
-interface Mirror {
-  id: string | number | null
-  header: string
-  value: unknown
-}
-
-function metadata(params: Params): Record<string, unknown> | undefined {
-  const meta = params._meta
-
-  return typeof meta === 'object' && meta !== null
-    ? (meta as Record<string, unknown>)
-    : undefined
-}
-
-function declared(params: Params): string | undefined {
-  const stated = metadata(params)?.[PROTOCOL_VERSION]
-
-  return typeof stated === 'string' ? stated : undefined
-}
-
-/** What a header value that could not be written as ASCII was encoded as. */
-function decode(value: string): string {
-  if (!value.startsWith(SENTINEL) || !value.endsWith(TERMINATOR)) return value
-
-  const encoded = value.slice(SENTINEL.length, -TERMINATOR.length)
-
-  return Buffer.from(encoded, 'base64').toString('utf8')
-}
-
-/** A tool list is what the tree holds, which stands until a branch of it expires. */
-const TOOLS_CACHE: Cache = { ttlMs: BRANCH_TTL, cacheScope: 'private' }
-
-/** What the annotation says, which is the same for every caller until the application is redeployed. */
-const DISCOVERY_CACHE: Cache = { ttlMs: BRANCH_TTL, cacheScope: 'public' }
-
-const OK = 200
-const ACCEPTED = 202
-const SENTINEL = '=?base64?'
-const TERMINATOR = '?='

package/source/MCP/discover.ts

@@ -1,51 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { LEGACY, MODERN, SERVER_INFO, VERSIONS } from './types.js'
-import type { MCP } from '../Annotation.js'
-
-/**
- * What a client is told before it calls anything: the revisions served, what is served, and
- * who serves it. It is a function of the annotation alone, so it is built once and answered
- * as it is.
- */
-export interface Discovery {
-  /** `server/discover`, which the modern revision has replaced the handshake with. */
-  modern: object
-
-  /** `initialize`, in the shape a client of an earlier revision reads. */
-  legacy: (offered: string | undefined) => object
-}
-
-export function discovery(options: MCP): Discovery {
-  const info = { name: options.name, version: VERSION }
-
-  // `listChanged` is a stream a client holds open, and this endpoint holds none
-  const capabilities = { tools: {} }
-
-  const modern: Record<string, unknown> = {
-    supportedVersions: VERSIONS,
-    capabilities,
-    _meta: { [SERVER_INFO]: info }
-  }
-
-  if (options.instructions !== undefined) modern.instructions = options.instructions
-
-  function legacy(offered: string | undefined): object {
-    const value: Record<string, unknown> = {
-      // what the client asked for where that is served, and the newest handshake otherwise
-      protocolVersion: offered !== undefined && offered !== MODERN ? offered : LEGACY,
-      capabilities,
-      serverInfo: info
-    }
-
-    if (options.instructions !== undefined) value.instructions = options.instructions
-
-    return value
-  }
-
-  return { modern, legacy }
-}
-
-/** What this gateway is, which is what answers however an application names itself. */
-const VERSION: string = JSON.parse(
-  readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
-).version

package/source/MCP/errors.ts

@@ -1,80 +0,0 @@
-import * as http from '../HTTP/index.js'
-import { JSONRPC, type Failure, type Response } from './types.js'
-
-/* The five JSON-RPC 2.0 fixes, which mean the same to every client. */
-export const PARSE = -32700
-export const INVALID_REQUEST = -32600
-export const METHOD_NOT_FOUND = -32601
-export const INVALID_PARAMS = -32602
-export const INTERNAL = -32603
-
-/*
- * MCP's own. It reserves -32020 to -32099 for the specification and tells an implementation
- * to use nothing of -32000 to -32019 at all — which is where this gateway's JSON-RPC codes
- * sit, so none of them is answered here.
- */
-export const HEADER_MISMATCH = -32020
-export const MISSING_CAPABILITY = -32021
-export const UNSUPPORTED_VERSION = -32022
-
-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: JSONRPC, 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.NotFound || exception instanceof http.MethodNotAllowed)
-    return failure(METHOD_NOT_FOUND, text(exception, 'Method not found'))
-
-  if (exception instanceof http.BadRequest)
-    return failure(INVALID_PARAMS, text(exception, 'Invalid params'))
-
-  return failure(INTERNAL, 'Internal error')
-}
-
-/**
- * What the call was refused with, which a model reads and may correct itself by: what the
- * operation said, where it said anything, and otherwise what the status means here.
- */
-export function refusal(exception: http.ClientError): string {
-  const body = exception.body
-
-  if (typeof body !== 'object' || body === null || typeof body.code !== 'string')
-    return text(exception, REFUSALS[exception.status] ?? 'Refused')
-
-  const message = body.message as unknown
-
-  return typeof message === 'string' && message !== '' ? message : (body.code as string)
-}
-
-/**
- * A refusal a model can act on, where the reply carried no words of its own. `auth` does
- * not say which of its directives refused, and `auth:id` is what most of them are: a call
- * naming a record that is not the caller's is the likeliest thing to have gone wrong.
- */
-const REFUSALS: Record<number, string> = {
-  400: 'The arguments were refused',
-  403: "Not authorized. If an argument names an identity or a record, it may not be the caller's own",
-  404: 'There is nothing at that address',
-  409: 'The record changed while the call was made',
-  429: 'Too many calls'
-}
-
-function text(exception: http.Exception, fallback: string): string {
-  return typeof exception.body === 'string' && exception.body !== ''
-    ? exception.body
-    : fallback
-}

package/source/MCP/index.ts

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