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

package/source/Gateway.ts

@@ -3,10 +3,13 @@ import { setTimeout } from 'node:timers/promises'
 import { console } from 'openspan'
 import { type bindings, Connector } from '@toa.io/core'
 import * as http from './HTTP/index.js'
+import { MCP, RPC } from './const.js'
 import { rethrow } from './exceptions.js'
 import { decide } from './Branch.js'
 import type { Interception } from './Interception.js'
-import type { Method, Node, Parameter, Tree, Match } from './RTD/index.js'
+import type { Dispatcher } from './RPC/index.js'
+import type { Server } from './MCP/index.js'
+import type { DirectiveFactory, Method, Node, Parameter, Tree, Match } from './RTD/index.js'
 import type { Label } from './discovery.js'
 import type { Branch, Exposed } from './Branch.js'
 
@@ -14,6 +17,13 @@ export class Gateway extends Connector {
   private readonly broadcast: Broadcast
   private readonly tree: Tree
   private readonly interceptor: Interception
+  private readonly directives: DirectiveFactory
+
+  /** JSON-RPC is served only where the annotation asked for it. */
+  private readonly dispatcher: Dispatcher | null
+
+  /** And the same of MCP. */
+  private readonly mcp: Server | null
   private readonly branches = new Map<string, Exposed>()
   private lastMerge = 0
   private widestGap = 0
@@ -21,12 +31,17 @@ export class Gateway extends Connector {
   private stopped = false
   private resolveFirstMerge: (() => void) | null = null
 
-  public constructor (broadcast: Broadcast, tree: Tree, interception: Interception) {
+  // eslint-disable-next-line max-params
+  public constructor (broadcast: Broadcast, tree: Tree, interception: Interception,
+    directives: DirectiveFactory, dispatcher: Dispatcher | null, mcp: Server | null) {
     super()
 
     this.broadcast = broadcast
     this.tree = tree
     this.interceptor = interception
+    this.directives = directives
+    this.dispatcher = dispatcher
+    this.mcp = mcp
 
     this.depends(broadcast)
   }
@@ -38,10 +53,44 @@ export class Gateway extends Connector {
     if (interception !== null)
       return interception
 
+    // request-scoped, before anything is routed: this is where a credential is read
+    await context.timing.capture('preflight',
+      this.directives.preflight(context)).catch(rethrow)
+
+    const response = await this.endpoint(context)
+
+    // request-scoped, on whatever is going back: this is where a credential is re-issued
+    await context.timing.capture('depart',
+      this.directives.depart(context, response)).catch(rethrow)
+
+    return response
+  }
+
+  /**
+   * What answers the request: a pinned endpoint that makes calls of its own, or the route
+   * the path names.
+   */
+  private async endpoint (context: http.Context): Promise<http.OutgoingMessage> {
+    const route: http.Processor = async (call) => await this.route(call)
+
+    if (this.dispatcher !== null && context.url.pathname === RPC)
+      return await context.timing.capture('rpc', this.dispatcher.dispatch(context, route))
+
+    if (this.mcp !== null && context.url.pathname === MCP)
+      return await context.timing.capture('mcp', this.mcp.process(context, route))
+
+    return await this.route(context)
+  }
+
+  /**
+   * One call: everything that needs a node. A request makes one of these, and a request
+   * that carries several calls makes one per call.
+   */
+  private async route (context: http.Context): Promise<http.OutgoingMessage> {
     const { node, parameters } = this.match(context)
 
     if (context.request.method === 'OPTIONS')
-      return await this.explain(node, parameters)
+      return await this.explain(context, node, parameters)
 
     let verb = context.request.method
 
@@ -53,8 +102,8 @@ export class Gateway extends Connector {
 
     const method = node.methods[verb]
 
-    const interruption = await context.timing.capture('preflight',
-      method.directives.preflight(context, parameters)).catch(rethrow)
+    const interruption = await context.timing.capture('precall',
+      method.directives.precall(context, parameters)).catch(rethrow)
 
     const response = interruption ??
       await context.timing.capture('call', this.call(method, context, parameters))
@@ -68,7 +117,16 @@ export class Gateway extends Connector {
   protected override async open (): Promise<void> {
     await this.discover()
 
-    console.info('Gateway started')
+    // what is served besides the tree, so that turning one on can be seen to have worked
+    const pinned: string[] = []
+
+    if (this.dispatcher !== null)
+      pinned.push(RPC)
+
+    if (this.mcp !== null)
+      pinned.push(MCP)
+
+    console.info('Gateway started', { endpoints: pinned.length === 0 ? 'none' : pinned.join(' ') })
   }
 
   /**
@@ -131,12 +189,16 @@ export class Gateway extends Connector {
       .catch(rethrow) as http.OutgoingMessage
   }
 
-  private async explain (node: Node, parameters: Parameter[]): Promise<http.OutgoingMessage> {
-    const body = await node.explain(parameters)
-    const allow = [...Object.keys(node.methods)].join(', ')
-    const headers = new Headers({ allow })
+  private async explain (context: http.Context, node: Node,
+    parameters: Parameter[]): Promise<http.OutgoingMessage> {
+    const body = await node.explain(context, parameters)
+    const verbs = Object.keys(body)
+
+    // what a caller may not use is not a resource to them, and describing it would be the leak
+    if (verbs.length === 0 && Object.keys(node.methods).length > 0)
+      throw new http.Forbidden()
 
-    return { body, headers }
+    return { body, headers: new Headers({ allow: verbs.join(', ') }) }
   }
 
   private async discover (): Promise<void> {

package/source/HTTP/Context.ts

@@ -22,6 +22,13 @@ export class Context {
   public readonly timing: Timing
   public readonly debug: boolean
 
+  /**
+   * Whether this is a procedure a request made, rather than the request. What forks one
+   * says so, and a directive that answers differently to a procedure than to a request
+   * reads it here.
+   */
+  public readonly procedural: boolean = false
+
   public readonly pipelines: Pipelines = {
     body: [],
     response: []

package/source/HTTP/Server.ts

@@ -12,7 +12,7 @@ import { ClientError, Exception } from './exceptions.js'
 import { Context } from './Context.js'
 import { PROBE, Probe } from './Probe.js'
 import type { IncomingMessage, Protocol, ServerResponse } from './types.js'
-import type { Bouncer, OAuth } from '../Annotation.js'
+import type { Bouncer, MCP, OAuth, RPC } from '../Annotation.js'
 
 export class Server extends Connector {
   private readonly server: http.Server | http2.Http2Server
@@ -389,6 +389,12 @@ interface Properties {
 
   /** The authorization server this context exposes; none is exposed without it. */
   oauth?: OAuth
+
+  /** JSON-RPC at `/.rpc`; none is served without it. */
+  rpc?: RPC
+
+  /** MCP at `/.mcp`; none is served without it. */
+  mcp?: MCP
 }
 
 export type Options = { authorities: Properties['authorities'] } & {

package/source/HTTP/exceptions.ts

@@ -41,8 +41,8 @@ export class NotFound extends ClientError {
 }
 
 export class MethodNotAllowed extends ClientError {
-  public constructor () {
-    super(405)
+  public constructor (headers?: Headers) {
+    super(405, undefined, headers)
   }
 }
 

package/source/HTTP/messages.ts

@@ -15,9 +15,18 @@ const server = `Exposition/${JSON.parse(readFileSync(new URL('../../package.json
 
 const pending = new Map<string, PendingStream>()
 
-export async function write (context: Context, response: ServerResponse, message: OutgoingMessage): Promise<void> {
+/**
+ * Applies what the request accumulated in `pipelines.response` — an `io:output` restriction,
+ * a `vary` a `map` directive owes. Separate from `write` because a message is not always
+ * written: one call of several produces a value the reply is assembled from.
+ */
+export async function shape (context: Context, message: OutgoingMessage): Promise<void> {
   for (const transform of context.pipelines.response)
     await transform(message)
+}
+
+export async function write (context: Context, response: ServerResponse, message: OutgoingMessage): Promise<void> {
+  await shape(context, message)
 
   if (message?.status !== undefined)
     response.statusCode = message.status

package/source/Introspection.ts

@@ -1,11 +1,116 @@
 import type { Remote } from '@toa.io/core'
 
 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
   route?: Record<string, Schema>
   query?: Record<string, Schema>
+
+  /** what a request header carries, which is therefore not the body's to send */
+  headers?: Record<string, Sourced>
   input?: Schema
   output?: Schema
   errors?: string[]
 }
 
+/** A property the gateway reads from somewhere else, and the schema it was declared with. */
+export interface Sourced {
+  header: string
+  [keyword: string]: unknown
+}
+
 export type Schema = Awaited<ReturnType<Remote['explain']>>['input']
+
+/**
+ * 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', 'route', 'query', 'headers', '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

@@ -0,0 +1,275 @@
+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

@@ -0,0 +1,52 @@
+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