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

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,12 +12,13 @@ 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 } from '../Annotation.js'
+import type { Bouncer, MCP, OAuth, RPC } from '../Annotation.js'
 
 export class Server extends Connector {
   private readonly server: http.Server | http2.Http2Server
   private readonly properties: Properties
-  private readonly authorities: Record<string, string>
+  /** Host to authority. A map: a `Host` of `constructor` names what a plain object answers. */
+  private readonly authorities: Map<string, string>
 
   /** Tracked for the drain: `Http2Server` has no `closeIdleConnections`. */
   private readonly sessions = new Set<http2.ServerHttp2Session>()
@@ -30,7 +31,7 @@ export class Server extends Connector {
     super()
 
     this.properties = properties
-    this.authorities = Object.fromEntries(Object.entries(properties.authorities).map(([key, value]) => [value, key]))
+    this.authorities = new Map(Object.entries(properties.authorities).map(([key, value]) => [value, key]))
     this.server = instantiate(properties.protocol)
     this.probe = new Probe(properties.probe)
 
@@ -162,7 +163,7 @@ export class Server extends Connector {
 
     assert(this.process !== undefined, 'Request processor is not attached')
 
-    const authority = this.authorities[host] ?? host
+    const authority = this.authorities.get(host) ?? host
 
     // if the request carries no trace context, the trace starts here
     const remote = trace(request.headers)
@@ -239,7 +240,7 @@ export class Server extends Connector {
         if (!response.writableEnded) {
           response.statusCode = status
 
-          const message: OutgoingMessage = { status: response.statusCode }
+          const message: OutgoingMessage = { status: response.statusCode, authentic: true }
 
           // eslint-disable-next-line max-depth
           if (exception instanceof Exception && exception.headers !== undefined)
@@ -385,6 +386,15 @@ interface Properties {
 
   /** Failed authentications an address may make; none are metered unless set. */
   bouncer?: Bouncer
+
+  /** 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/formats/form.ts

@@ -0,0 +1,21 @@
+export const type = 'application/x-www-form-urlencoded'
+
+/**
+ * A form is read and never written: it is what an HTML form and a handful of protocols send,
+ * and nothing asks for a reply in it.
+ *
+ * A name repeated in a form is a list, which is how a form says one — `URLSearchParams` keeps
+ * every value, and a name given once stays the string it was written as.
+ */
+export function decode (buffer: Buffer, charset = 'utf-8'): any {
+  const params = new URLSearchParams(buffer.toString(charset as BufferEncoding))
+  const value: Record<string, string | string[]> = {}
+
+  for (const name of new Set(params.keys())) {
+    const values = params.getAll(name)
+
+    value[name] = values.length === 1 ? values[0] : values
+  }
+
+  return value
+}

package/source/HTTP/formats/index.ts

@@ -2,7 +2,9 @@ import * as json from './json.js'
 import * as yaml from './yaml.js'
 import * as msgpack from './msgpack.js'
 import * as text from './text.js'
+import * as form from './form.js'
 
+/** What a reply may be encoded as, and so what `accept` is negotiated against. */
 export const formats: Record<string, Format> = {
   [json.type]: json,
   [yaml.type]: yaml,
@@ -12,10 +14,23 @@ export const formats: Record<string, Format> = {
 
 export const types = Object.keys(formats)
 
-export interface Format {
+/**
+ * What a request body may arrive as. Everything a reply may be, and a form besides — which
+ * is read and never written, so it is not something a reply can be asked for.
+ */
+export const decoders: Record<string, Decoder> = {
+  ...formats,
+  [form.type]: form
+}
+
+export interface Decoder {
   readonly type: string
+
+  decode: (buffer: Buffer, charset?: string) => any
+}
+
+export interface Format extends Decoder {
   readonly multipart: string
 
   encode: (value: any) => Buffer
-  decode: (buffer: Buffer, charset?: string) => any
 }

package/source/HTTP/messages.test.ts

@@ -7,7 +7,7 @@ import { generate } from 'randomstring'
 import * as msgpack from 'msgpackr'
 import { multipart, read, type OutgoingMessage } from './messages.js'
 import { BadRequest, UnsupportedMediaType } from './exceptions.js'
-import { formats } from './formats/index.js'
+import { formats, types } from './formats/index.js'
 import { Timing } from './Timing.js'
 import type * as http from 'node:http'
 import type { Context } from './Context.js'
@@ -87,6 +87,30 @@ describe('read', () => {
     await assert.rejects(read(request), BadRequest)
   })
 
+  it('should parse application/x-www-form-urlencoded', async () => {
+    const headers = { 'content-type': 'application/x-www-form-urlencoded' }
+    const form = 'grant_type=authorization_code&code=SplxlO&scope=a+b'
+    const request = createContext(generate(), headers, form)
+
+    assert.deepStrictEqual(await read(request), {
+      grant_type: 'authorization_code',
+      code: 'SplxlO',
+      scope: 'a b'
+    })
+  })
+
+  it('should read a repeated form name as the list it is', async () => {
+    const headers = { 'content-type': 'application/x-www-form-urlencoded' }
+    const request = createContext(generate(), headers, 'resource=one&resource=two')
+
+    assert.deepStrictEqual(await read(request), { resource: ['one', 'two'] })
+  })
+
+  it('should not offer a form as a reply encoding', () => {
+    assert.ok(!types.includes('application/x-www-form-urlencoded'),
+      'a form is read and never written')
+  })
+
   it('should output correct mulitpart format', async () => {
     const response = new class extends PassThrough {
       public readonly headers = new Headers()

package/source/HTTP/messages.ts

@@ -4,7 +4,7 @@ import { pipeline } from 'node:stream/promises'
 import { createHash } from 'node:crypto'
 import * as contentType from 'content-type'
 import { console } from 'openspan'
-import { type Format, formats } from './formats/index.js'
+import { type Format, decoders } from './formats/index.js'
 import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions.js'
 import type { Context } from './Context.js'
 import type { ServerResponse } from './types.js'
@@ -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
@@ -49,10 +58,10 @@ export async function read (context: Context): Promise<any> {
 
   const { type, parameters } = contentType.parse(header)
 
-  if (!(type in formats))
+  if (!(type in decoders))
     throw new UnsupportedMediaType()
 
-  const format = formats[type]
+  const format = decoders[type]
   const buf = await context.buffer()
 
   try {
@@ -201,6 +210,13 @@ export interface OutgoingMessage {
 
   /** tag the response with a hash of the encoded body, see `conditional` */
   etag?: boolean
+
+  /**
+   * Built by the gateway rather than returned by an operation, as a request is `authentic`
+   * when it was made by one: what is in it is the gateway's own, and the checks that answer
+   * for what an operation returns have nothing to say about it.
+   */
+  authentic?: boolean
 }
 
 export interface Query {

package/source/Interception.ts

@@ -1,15 +1,18 @@
+import type * as http from './HTTP/index.js'
 import type { Input, Output } from './io.js'
 
 export class Interception implements Interceptor {
   private readonly interceptors: Interceptor[]
 
-  public constructor (interceptors: Interceptor[]) {
+  public constructor (interceptors: Interceptor[], options: http.Options) {
     this.interceptors = interceptors
 
     // interceptors are module singletons, so a second gateway in one process —
     // which is how the features run — would otherwise inherit the first one's state
-    for (const interceptor of interceptors)
+    for (const interceptor of interceptors) {
       interceptor.reset?.()
+      interceptor.mount?.(options)
+    }
   }
 
   public async intercept (input: Input): Promise<Output> {
@@ -29,4 +32,7 @@ export interface Interceptor {
 
   /** Discards whatever the interceptor accumulated while serving. */
   reset?: () => void
+
+  /** What the annotation says, for an interceptor that answers from it. */
+  mount?: (options: http.Options) => void
 }

package/source/Introspection.ts

@@ -1,11 +1,113 @@
 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
   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 = ['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
+}