@toa.io/extensions.exposition 1.0.0-alpha.286 → 1.0.0-alpha.288

package/source/MCP/schema.ts

@@ -8,7 +8,12 @@ import type { Annotations } from './types.js'
  * A `map:headers` property is not here: a call carries no headers of its own, so there is
  * nowhere for a model to put one.
  */
-export function input(introspection: Introspection, variables: string[]): object {
+// eslint-disable-next-line max-params
+export function input(
+  introspection: Introspection,
+  variables: string[],
+  selection: Record<string, Schema> | null
+): object {
   const properties: Record<string, unknown> = {}
   const required: string[] = []
 
@@ -23,15 +28,21 @@ export function input(introspection: Introspection, variables: string[]): object
     required.push(variable)
   }
 
-  // it is a querystring on the wire, which is nothing a model knows or needs to; what it
-  // is to a caller is the part of a call that picks what the call is about
-  if (introspection.query !== undefined)
+  /*
+   * It is a querystring on the wire, which is nothing a model knows or needs to; what it is
+   * to a caller is the part of a call that picks what the call is about. What selects
+   * records is stated here and not in the resource's own description, where it would be the
+   * same sentence on every queryable resource there is.
+   */
+  const query = { ...introspection.query, ...selection }
+
+  if (Object.keys(query).length > 0)
     properties.query = {
       type: 'object',
       description:
         'Which records the call works on: what to match, in what order, ' +
         'and how many at once.',
-      properties: introspection.query
+      properties: query
     }
 
   const body = introspection.input as Shape | null | undefined

package/source/MCP/tools.ts

@@ -4,8 +4,9 @@ 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 { 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'
 
 /**
@@ -20,28 +21,26 @@ import type { Params, Result, Tool } from './types.js'
  *
  * Sorted, because the revision asks for an order a client can cache on.
  */
-export async function list(tree: Tree, context: http.Context): Promise<Tool[]> {
+export async function list(tree: Tree, request: 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.
+   * 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 describing: http.Context = Object.create(context, {
-    procedural: { value: true, enumerable: true }
-  })
+  const context = describing(request)
 
   for (const { segments, verb, method } of tree.walk()) {
-    if (MCP.published(method.directives.declared<Declaration>(FAMILY)) === null) continue
+    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 variables = parameters(segments)
-    const introspection = await method.explain(describing, variables)
+    const params = variables(segments)
+    const introspection = await method.explain(context, params)
 
     if (introspection === null) continue
 
@@ -56,7 +55,8 @@ export async function list(tree: Tree, context: http.Context): Promise<Tool[]> {
       ...(described === undefined ? {} : { description: described }),
       inputSchema: input(
         introspection,
-        variables.map((variable) => variable.name)
+        params.map((param) => param.name),
+        method.endpoint?.selection() ?? null
       ),
       ...(schema === undefined ? {} : { outputSchema: schema }),
       ...(hints === undefined ? {} : { annotations: hints })
@@ -129,7 +129,7 @@ export interface Scope {
 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 MCP.published(method.directives.declared<Declaration>(FAMILY))
 
   return false
 }
@@ -142,21 +142,3 @@ function result(body: unknown): Result {
     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/Mapping.ts

@@ -24,6 +24,11 @@ export abstract class Mapping {
     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)

package/source/Query.ts

@@ -82,6 +82,11 @@ export class Query {
    * 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
 
@@ -96,9 +101,19 @@ export class Query {
         query[parameter] = schema
       }
 
-    if (!this.queryable) return query
+    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
 
-    query ??= {}
+    const query: Record<string, Schema> = {}
 
     if (!this.closed)
       query.criteria = keyword(

package/source/RTD/Directives.ts

@@ -29,6 +29,9 @@ export interface Directives {
 export interface DirectiveFactory {
   create: (directives: syntax.Directive[], route: string) => Directives
 
+  /** Whether this declaration is carried into the nodes below the one it is on. */
+  inheritable: (directive: syntax.Directive) => boolean
+
   /** Runs every family's `preflight`, which is request-scoped and needs no node. */
   preflight: (context: Context) => Promise<void>
 
@@ -50,6 +53,13 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
   readonly name: string
   readonly mandatory: boolean
 
+  /**
+   * Whether a declaration applies to everything below the node it is on, as every directive
+   * does unless it says otherwise. A family that describes what one node *is* sets this
+   * `false`: inherited, it would say the same thing of every resource under it.
+   */
+  readonly inherited?: boolean
+
   create: (name: string, ...rest: any[]) => TDirective
 
   /**

package/source/RTD/Endpoint.ts

@@ -2,7 +2,7 @@ import { type Context } from './Context.js'
 import type * as http from '../HTTP/index.js'
 import type * as syntax from './syntax/index.js'
 import type * as RTD from './index.js'
-import type { Introspection } from '../Introspection.js'
+import type { Introspection, Schema } from '../Introspection.js'
 
 export interface Endpoint {
   call: (
@@ -12,6 +12,13 @@ export interface Endpoint {
 
   explain: (parameters: RTD.Parameter[]) => Promise<Introspection>
 
+  /**
+   * What picks the records a call is about — `criteria`, `sort` and the rest. Not part of
+   * what the resource says about itself: it is the same of every queryable one. A
+   * procedure carries it, because there it is something the caller sends.
+   */
+  selection: () => Record<string, Schema> | null
+
   close: () => Promise<void>
 }
 

package/source/RTD/Node.ts

@@ -3,6 +3,7 @@ import { type Method, type Methods } from './Method.js'
 import { type Match, type Parameter } from './Match.js'
 import type { Segment } from './segment.js'
 import type { Context } from '../HTTP/index.js'
+import { guarded, resource, type Described } from '../directives/help/index.js'
 import type { Introspection } from '../Introspection.js'
 
 export class Node {
@@ -72,11 +73,11 @@ export class Node {
     for (const route of this.routes) yield* route.walk(segments)
   }
 
-  /** Every method of this node that this caller may reach, in the order they were declared. */
-  public async explain(
-    context: Context,
-    parameters: Parameter[]
-  ): Promise<Record<string, Introspection>> {
+  /**
+   * What this resource is, and every method of it this caller may reach, in the order they
+   * were declared. The two are answered apart because only the methods are `Allow`.
+   */
+  public async explain(context: Context, parameters: Parameter[]): Promise<Explained> {
     const entries = Object.entries(this.methods)
 
     const explained = await Promise.all(
@@ -88,7 +89,14 @@ export class Node {
     for (let i = 0; i < entries.length; i++)
       if (explained[i] !== null) methods[entries[i][0]] = explained[i]!
 
-    return methods
+    // every method of a node carries the same declaration, so the first that is there says it
+    const stated = entries.length === 0 ? null : resource(entries[0][1].directives)
+    const described = { ...stated, ...guarded(methods) }
+
+    return {
+      described: Object.keys(described).length === 0 ? null : described,
+      methods
+    }
   }
 
   private replace(node: Node): Node[] {
@@ -141,6 +149,12 @@ export class Node {
   }
 }
 
+/** What a resource says of itself, and what it serves. */
+export interface Explained {
+  described: Described | null
+  methods: Record<string, Introspection>
+}
+
 /** A method, and the route template it is reached by. */
 export interface Mount {
   segments: Segment[]

package/source/RTD/Tree.ts

@@ -1,5 +1,6 @@
 import { console } from 'openspan'
 import { refusal, template } from '../RPC/names.js'
+import { DISCOVERY } from '../const.js'
 import { branchTTL, createNode } from './factory.js'
 import { fragment } from './segment.js'
 import type { Mount, Node } from './Node.js'
@@ -25,7 +26,7 @@ export class Tree {
     this.root = node
     this.trunk = this.createNode(node, PROTECTED)
 
-    unnameable(this.trunk)
+    announce(this.trunk)
   }
 
   public match(path: string): Match | null {
@@ -48,7 +49,7 @@ export class Tree {
   public merge(node: syntax.Node, extension: unknown): Node[] {
     const branch = this.createNode(node, !PROTECTED, extension)
 
-    unnameable(branch)
+    announce(branch)
 
     return this.trunk.merge(branch)
   }
@@ -87,21 +88,30 @@ export class Tree {
 }
 
 /**
- * What is served but cannot be called by name. Said once per route as it is built, because a
- * procedure that is missing is otherwise noticed only by the caller who cannot find it.
+ * What is served but cannot be reached as it reads. Said once per route as it is built,
+ * because either of these is otherwise noticed only by the caller who cannot find it.
  */
-function unnameable(node: Node): void {
+function announce(node: Node): void {
   const said = new Set<string>()
 
   for (const { segments } of node.walk([], TRUNK)) {
-    const segment = refusal(segments)
-
-    if (segment === null) continue
-
     const route = template(segments)
 
     if (said.has(route)) continue
 
+    // the page is served under this prefix, before a request is routed at all
+    if (route === DISCOVERY || route.startsWith(DISCOVERY + '/')) {
+      said.add(route)
+
+      console.warn('Route is shadowed by the discovery endpoint', { route })
+
+      continue
+    }
+
+    const segment = refusal(segments)
+
+    if (segment === null) continue
+
     said.add(route)
 
     console.warn('Route cannot be addressed as a procedure', { route, segment })

package/source/RTD/factory.ts

@@ -1,7 +1,8 @@
+import assert from 'node:assert'
 import { BRANCH_TTL } from '../const.js'
 import { Node, type Properties } from './Node.js'
 import { Route } from './Route.js'
-import { segment } from './segment.js'
+import { fragment, segment } from './segment.js'
 import { Method, type Methods } from './Method.js'
 import type { Context } from './Context.js'
 import type * as syntax from './syntax/index.js'
@@ -10,6 +11,8 @@ export function createNode(node: syntax.Node, context: Context): Node {
   if (node.isolated === true) context.directives.stack = node.directives
   else context.directives.stack = node.directives.concat(context.directives.stack)
 
+  described(node, context)
+
   const routes: Route[] = node.routes.map((route) => createRoute(route, context))
   const methods: Methods = {}
 
@@ -43,6 +46,16 @@ function createRoute(route: syntax.Route, context: Context): Route {
 
   context.path = join(path, route.path)
 
+  /*
+   * What a node says of itself is not said of what is under it. Its own `/` is the
+   * exception: an intermediate node is never what a path matches, because that route
+   * answers in its place — so the two are one resource and what describes it carries.
+   */
+  if (route.path !== ROOT)
+    context.directives.stack = stack.filter((directive) =>
+      context.directives.factory.inheritable(directive)
+    )
+
   const node = createNode(route.node, context)
 
   context.directives.stack = stack // restore
@@ -67,3 +80,26 @@ function createMethod(method: syntax.Method, context: Context): Method {
 
   return new Method(endpoint, directives)
 }
+
+/**
+ * A resource is what it is described beside: a node with no methods of its own is never
+ * what a path answers, so nothing would carry what it says about itself. Refused where the
+ * declaration is, rather than left to be noticed by whoever cannot find it in the answer.
+ */
+function described(node: syntax.Node, context: Context): void {
+  const help = node.directives.find(
+    (directive) => directive.family === HELP && directive.name === 'node'
+  )
+
+  if (help === undefined || node.methods.length > 0) return
+
+  // an intermediate node's `/` answers in its place, and carries what it says
+  if (node.routes.some((route) => route.path === ROOT)) return
+
+  const route = '/' + fragment(context.path).join('/')
+
+  assert.fail(`Directive help:node: '${route}' serves no methods`)
+}
+
+const ROOT = '/'
+const HELP = 'help'

package/source/RTD/segment.ts

@@ -1,3 +1,5 @@
+import type { Parameter } from './Match.js'
+
 export function segment(path: string): Segment[] {
   return fragment(path).map(parse)
 }
@@ -28,3 +30,22 @@ export type Segment =
       placeholder: string | null
       wildcard?: boolean
     }
+
+/**
+ * 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. A `*` is skipped: it stands
+ * for a segment the caller cannot name, so there is nothing to substitute.
+ */
+export function variables(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/const.ts

@@ -17,3 +17,11 @@ export const BATCH = 32
  * application could choose is a path it could collide with a route of its own.
  */
 export const MCP = '/.mcp'
+
+/**
+ * Where the resource tree and the page that reads it are served. Pinned for the reason
+ * `/.rpc` is: a path an application could choose is a path it could collide with a route of
+ * its own. Unlike those two it is not annotated — every entry it carries is what `OPTIONS`
+ * on that path already answers to the same caller, and what it adds is the enumeration.
+ */
+export const DISCOVERY = '/.discovery'

package/source/directives/auth/Anonymous.test.ts

@@ -4,8 +4,16 @@ import assert from 'node:assert/strict'
 import { Anonymous } from './Anonymous.js'
 import type { Context } from './types.js'
 
-const context = (headers: Record<string, string>, procedural = false): Context =>
-  ({ request: { headers }, procedural }) as unknown as Context
+const context = (
+  headers: Record<string, string>,
+  flags: { procedural?: boolean; exploratory?: boolean } = {}
+): Context =>
+  ({
+    request: { headers },
+    procedural: false,
+    exploratory: false,
+    ...flags
+  }) as unknown as Context
 
 describe('anonymous', () => {
   it('should admit a request that presents nothing', () => {
@@ -22,14 +30,28 @@ describe('anonymous', () => {
 
   it('should admit a procedure whatever the request presented', () => {
     // what a procedure answers is a value in an envelope, and the envelope is `no-store`
-    const procedural = context({ authorization: 'Token x' }, true)
+    const procedural = context({ authorization: 'Token x' }, { procedural: true })
 
     assert.equal(new Anonymous(true).authorize(null, procedural), true)
   })
 
+  it('should admit a description whatever the request presented', () => {
+    // a description is not the reply a cache would hold, and varies by who asked in any case
+    const exploratory = context({ authorization: 'Token x' }, { exploratory: true })
+
+    assert.equal(new Anonymous(true).authorize(null, exploratory), true)
+  })
+
   it('should refuse where it admits nobody', () => {
     assert.equal(new Anonymous(false).authorize(null, context({})), false)
-    assert.equal(new Anonymous(false).authorize(null, context({}, true)), false)
+    assert.equal(
+      new Anonymous(false).authorize(null, context({}, { procedural: true })),
+      false
+    )
+    assert.equal(
+      new Anonymous(false).authorize(null, context({}, { exploratory: true })),
+      false
+    )
   })
 
   it('should describe a method as it authorizes one', () => {
@@ -37,7 +59,11 @@ describe('anonymous', () => {
 
     assert.equal(directive.admits(null, context({ authorization: 'Token x' })), false)
     assert.equal(
-      directive.admits(null, context({ authorization: 'Token x' }, true)),
+      directive.admits(null, context({ authorization: 'Token x' }, { procedural: true })),
+      true
+    )
+    assert.equal(
+      directive.admits(null, context({ authorization: 'Token x' }, { exploratory: true })),
       true
     )
   })

package/source/directives/auth/Anonymous.ts

@@ -9,11 +9,13 @@ export class Anonymous implements Directive {
 
   /**
    * A credential refuses, because it would make the reply uncacheable — which is the whole
-   * of the rule, and none of it applies to a procedure: what a procedure answers is a value
-   * in an envelope, and the envelope is the one thing that is cached or not.
+   * of the rule, and none of it applies to a procedure, nor to a description. What a
+   * procedure answers is a value in an envelope, and the envelope is the one thing that is
+   * cached or not; what a description answers is what the resource is, which is not the
+   * reply a cache would hold and varies by who asked in any case.
    */
   public authorize(_: any, context: Context): boolean {
-    if (context.procedural) return this.allow
+    if (context.procedural || context.exploratory) return this.allow
 
     return 'authorization' in context.request.headers ? false : this.allow
   }

package/source/directives/auth/Anyone.ts

@@ -1,4 +1,5 @@
 import { type Directive, type Context } from './types.js'
+import type { Introspection } from '../../Introspection.js'
 
 export class Anyone implements Directive {
   private readonly allow: boolean
@@ -14,4 +15,9 @@ export class Anyone implements Directive {
   public admits(_: any, context: Context): boolean {
     return this.authorize(_, context)
   }
+
+  /** Whoever asks, as long as they are somebody. */
+  public describe(introspection: Introspection): Introspection {
+    return this.allow ? { ...introspection, authenticated: true } : introspection
+  }
 }

package/source/directives/auth/Assert.ts

@@ -16,6 +16,11 @@ export class Assert implements Directive {
     this.disabled = !enabled
   }
 
+  /** It admits nobody: it is there to require a credential, not to authorize one. */
+  public admits(): boolean {
+    return false
+  }
+
   public async authorize(identity: Identity | null, context: Context): Promise<boolean> {
     if (!this.disabled) await this.incept(context, identity)
 

package/source/directives/auth/Delegate.ts

@@ -28,11 +28,14 @@ export class Delegate implements Directive {
     return identity !== null
   }
 
-  /** The property it embeds is the identity's, so a caller has nothing to put there. */
+  /**
+   * It takes an identity, and the property it embeds is that identity's — so a caller has
+   * nothing to put there.
+   */
   public describe(introspection: Introspection): Introspection {
     take(introspection, this.property)
 
-    return introspection
+    return { ...introspection, authenticated: true }
   }
 
   private embed(body: unknown, identity: Identity): Record<string, unknown> {

package/source/directives/auth/Federation.ts

@@ -1,5 +1,6 @@
 import assert from 'node:assert'
 import type { Directive, Identity, Context } from './types.js'
+import type { Introspection } from '../../Introspection.js'
 import type { Parameter } from '../../RTD/index.js'
 
 export class Federation implements Directive {
@@ -16,6 +17,16 @@ export class Federation implements Directive {
     )
   }
 
+  /** Which claims it takes needs the request; that it takes an identity does not. */
+  public admits(identity: Identity | null): boolean | undefined {
+    return identity === null ? false : undefined
+  }
+
+  /** Which claims is the application's business; that it takes an identity is the caller's. */
+  public describe(introspection: Introspection): Introspection {
+    return { ...introspection, authenticated: true }
+  }
+
   public authorize(
     identity: Identity | null,
     context: Context,

package/source/directives/auth/Id.ts

@@ -1,5 +1,6 @@
 import { type Parameter } from '../../RTD/index.js'
 import { type Directive, type Identity } from './types.js'
+import type { Introspection } from '../../Introspection.js'
 
 export class Id implements Directive {
   private readonly parameter: string
@@ -8,6 +9,20 @@ export class Id implements Directive {
     this.parameter = parameter
   }
 
+  /**
+   * Whether it is *this* identity's cannot be told from a description, which has no route
+   * variable to read — but that there must be an identity at all can, and a caller with
+   * none is refused whatever the value would have been.
+   */
+  public admits(identity: Identity | null): boolean | undefined {
+    return identity === null ? false : undefined
+  }
+
+  /** Reaching it is being the identity it is about, which is what `private` says. */
+  public describe(introspection: Introspection): Introspection {
+    return { ...introspection, private: true }
+  }
+
   public authorize(
     identity: Identity | null,
     _: unknown,

package/source/directives/auth/Input.ts

@@ -12,6 +12,11 @@ export class Input implements Directive {
     )
   }
 
+  /** It admits nobody: it says what a body may carry, not who may send one. */
+  public admits(): boolean {
+    return false
+  }
+
   public async authorize(
     identity: Identity | null,
     context: Context,