@toa.io/extensions.exposition 1.0.0-alpha.287 → 1.0.0-alpha.289

package/source/Discovery/tree.ts

@@ -0,0 +1,77 @@
+import { describing } from '../Introspection.js'
+import { template } from '../RPC/names.js'
+import { variables } from '../RTD/segment.js'
+import { guarded, resource, type Described } from '../directives/help/index.js'
+import type * as http from '../HTTP/index.js'
+import type { Tree } from '../RTD/index.js'
+import type { Introspection } from '../Introspection.js'
+
+/**
+ * Every route in the tree this caller may reach, keyed by the template it answers at, and
+ * each described exactly as `OPTIONS` on that path describes it — so a key can be taken
+ * from the answer and sent back as a request.
+ *
+ * A route a name cannot spell is here, unlike at `/.rpc` and `/.mcp`: HTTP addresses a
+ * route by its path, so leaving one out would make this disagree with the router. A
+ * resource no method of which this caller may reach is not here at all — `OPTIONS` answers
+ * `403` to one, and an empty entry would still say it exists.
+ *
+ * Sorted, because a branch is merged whenever its tenant answers and two replicas would
+ * otherwise order the same tree differently. Verbs keep the order they were declared in,
+ * which is the order `OPTIONS` answers them in.
+ */
+export async function describe(tree: Tree, request: http.Context): Promise<Discovered> {
+  const context = describing(request)
+  const routes = new Map<string, Mounted>()
+
+  /*
+   * Sequentially: there is no I/O to overlap — an endpoint's own description is read once
+   * and memoized — so awaiting the whole tree at once would only allocate every clone of
+   * it at the same moment.
+   */
+  for (const { segments, verb, method } of tree.walk()) {
+    const introspection = await method.explain(context, variables(segments))
+
+    if (introspection === null) continue
+
+    const route = template(segments)
+    let mounted = routes.get(route)
+
+    if (mounted === undefined) {
+      mounted = { described: resource(method.directives), methods: {} }
+      routes.set(route, mounted)
+    }
+
+    // two declarations can walk to one template — `/a/b` and `/a: { /b: }` — and the walk
+    // is in the order `match` tries them, so the first is the one a request would reach
+    mounted.methods[verb] ??= introspection
+  }
+
+  const described: Record<string, Resource> = {}
+
+  for (const route of Array.from(routes.keys()).sort()) {
+    const { described: stated, methods } = routes.get(route)!
+
+    // what the resource is, beside the methods it serves; a verb is upper case and cannot
+    // collide with either key
+    described[route] = { ...stated, ...guarded(methods), ...methods }
+  }
+
+  return { routes: described }
+}
+
+/** What the tree answers. An object, so that what is said of the whole of it has somewhere to go. */
+export interface Discovered {
+  routes: Record<string, Resource>
+}
+
+/** What one resource is, and what it serves; a verb is upper case, and nothing else here is. */
+export interface Resource extends Described {
+  [verb: string]: unknown
+}
+
+/** One route template as the walk found it, before the two are answered as one. */
+interface Mounted {
+  described: Described | null
+  methods: Record<string, Introspection>
+}

package/source/Discovery/trunk.ts

@@ -0,0 +1,33 @@
+import Negotiator from 'negotiator'
+import { types } from '../HTTP/formats/index.js'
+import { DISCOVERY } from '../const.js'
+import type { Context, OutgoingMessage } from '../HTTP/index.js'
+
+/** What a browser asks for, and what nothing else here answers with. */
+const HTML = 'text/html'
+
+/**
+ * Where a browser that asked for the trunk is sent. An application serves what it declares,
+ * and `/` is usually not one of those — a person who typed the address into a browser is
+ * looking for something to look at, and the page is the only thing here that is one.
+ *
+ * A client that asked for something in particular gets what it asked for: only an `accept`
+ * that prefers a page, or one that names no preference at all, is sent here. The second is
+ * what an unfurler sends — several ask for anything, and a link to an application would
+ * otherwise show nothing — and what `curl` sends, which the page serves no worse than the
+ * `405` it used to get.
+ */
+export function looking(context: Context): OutgoingMessage | null {
+  if (context.request.method !== 'GET' || context.procedural) return null
+
+  const accept = context.request.headers.accept
+
+  if (accept !== undefined && accept.trim() !== ANYTHING) {
+    if (new Negotiator(context.request).mediaType([...types, HTML]) !== HTML) return null
+  }
+
+  return { status: 302, headers: new Headers({ location: DISCOVERY + '/' }) }
+}
+
+/** An `accept` that names nothing, which is the same as naming none. */
+const ANYTHING = '*/*'

package/source/Endpoint.ts

@@ -52,6 +52,10 @@ export class Endpoint implements RTD.Endpoint {
     return message
   }
 
+  public selection(): Record<string, Schema> | null {
+    return this.mapping.selection()
+  }
+
   public async explain(parameters: RTD.Parameter[]): Promise<Introspection> {
     this.introspection ??= await this.introspect(parameters)
 

package/source/Factory.ts

@@ -1,20 +1,6 @@
-import assert from 'node:assert'
 import { createHash } from 'node:crypto'
-import { console, traces, type LevelName, type TracesOptions } from 'openspan'
 import { Tenant } from './Tenant.js'
-import { Gateway } from './Gateway.js'
-import { Remotes } from './Remotes.js'
-import { Tree } from './RTD/index.js'
-import { EndpointsFactory } from './Endpoint.js'
-import { families, interceptors } from './directives/index.js'
-import { DirectivesFactory } from './Directive.js'
-import { Composition } from './Composition.js'
-import * as root from './root.js'
-import { ATOM_GROUP } from './const.js'
-import { Interception } from './Interception.js'
-import { Dispatcher } from './RPC/index.js'
-import { Server as Model } from './MCP/index.js'
-import * as http from './HTTP/index.js'
+import { CHANNEL } from './const.js'
 import type { Branch } from './Branch.js'
 import type { syntax } from './RTD/index.js'
 import type { Broadcast } from './Gateway.js'
@@ -46,80 +32,11 @@ export class Factory implements extensions.Factory {
   }
 
   public async service(): Promise<Connector | null> {
-    assert.ok(
-      process.env.TOA_EXPOSITION_PROPERTIES,
-      'TOA_EXPOSITION_PROPERTIES is undefined'
-    )
+    const { service } = await import('./service.js')
 
-    configureLogs()
-
-    const options = JSON.parse(process.env.TOA_EXPOSITION_PROPERTIES) as http.Options
-    const broadcast: Broadcast = await this.host.broadcast(CHANNEL)
-    const server = http.Server.create({ ...options })
-    const remotes = new Remotes(this.host)
-    const node = root.resolve()
-    const methods = new EndpointsFactory(remotes)
-    const directives = new DirectivesFactory(families, remotes, this.host, options)
-    const interception = new Interception(interceptors, options)
-    const tree = new Tree(node, methods, directives)
-
-    const composition = new Composition(this.host)
-    const dispatcher = options.rpc === undefined ? null : new Dispatcher(options.rpc)
-    const mcp = options.mcp === undefined ? null : new Model(options.mcp, tree)
-    const gateway = new Gateway(
-      broadcast,
-      tree,
-      interception,
-      directives,
-      dispatcher,
-      mcp
-    )
-
-    gateway.depends(remotes)
-    gateway.depends(composition)
-    // what the directives meter through; one atom per process, connected once
-    gateway.depends(this.host.atom(ATOM_GROUP))
-
-    server.attach(gateway.process.bind(gateway))
-    server.depends(gateway)
-
-    return server
+    return await service(this.host)
   }
 }
 
-const CHANNEL = 'exposition'
-const LOGS_PREFIX = 'TOA_TELEMETRY_LOGS'
-const TRACES_ENV = 'TOA_TELEMETRY_TRACES'
-
-function configureLogs(): void {
-  const globEnv = process.env[LOGS_PREFIX]
-  const level: LevelName = process.env.TOA_DEV === '1' ? 'trace' : 'info'
-  const options =
-    globEnv === undefined ? { level } : (JSON.parse(globEnv) as { level?: LevelName })
-
-  console.configure({ level: options.level ?? level })
-
-  const tracesEnv = process.env[TRACES_ENV]
-
-  traces(
-    tracesEnv === undefined ? development() : (JSON.parse(tracesEnv) as TracesOptions)
-  )
-}
-
-/**
- * Tracing is off unless it is configured. The console exporter is a local development
- * mechanism, so it is turned on for `toa dev` and for a boot trace the CLI has already
- * asked for (`runtime/boot/src/span.js`), and nowhere else — a deployment that wants
- * traces annotates `telemetry.traces.exporters`.
- *
- * The gateway boots without the telemetry extension, hence the copy of
- * `extensions/telemetry/source/extension.ts`.
- */
-function development(): TracesOptions {
-  const local = process.env.TOA_DEV === '1' || process.env.TOA_BOOT_TRACE === '1'
-
-  return local ? { exporters: { console: {} } } : {}
-}
-
 // eslint-disable-next-line @typescript-eslint/consistent-type-imports
 export type Host = extensions.Host

package/source/Gateway.ts

@@ -4,9 +4,11 @@ import { console } from 'openspan'
 import { Connector } from '@toa.io/core'
 import type { bindings } from '@toa.io/core/types'
 import * as http from './HTTP/index.js'
-import { MCP, RPC } from './const.js'
+import { DISCOVERY, MCP, RPC } from './const.js'
 import { rethrow } from './exceptions.js'
 import { decide } from './Branch.js'
+import { describing } from './Introspection.js'
+import { Explorer, looking } from './Discovery/index.js'
 import type { Interception } from './Interception.js'
 import type { Dispatcher } from './RPC/index.js'
 import type { Server } from './MCP/index.js'
@@ -32,6 +34,9 @@ export class Gateway extends Connector {
 
   /** And the same of MCP. */
   private readonly mcp: Server | null
+
+  /** The tree, for every route at once. Served always, and so not nullable. */
+  private readonly explorer: Explorer
   private readonly branches = new Map<string, Exposed>()
   private lastMerge = 0
   private widestGap = 0
@@ -56,6 +61,7 @@ export class Gateway extends Connector {
     this.directives = directives
     this.dispatcher = dispatcher
     this.mcp = mcp
+    this.explorer = new Explorer(tree)
 
     this.depends(broadcast)
   }
@@ -89,9 +95,28 @@ export class Gateway extends Connector {
     if (this.mcp !== null && context.url.pathname === MCP)
       return await this.mcp.process(context, route)
 
+    // the page under this prefix is an interceptor's, and has already answered
+    if (context.url.pathname === DISCOVERY || context.url.pathname === DISCOVERY + '/')
+      return await this.explorer.process(context)
+
+    // a browser that asked for the trunk of an API is looking for the page, and where the
+    // application answers there itself, that is what answers
+    if (context.url.pathname === '/' && !this.serves(context)) {
+      const page = looking(context)
+
+      if (page !== null) return page
+    }
+
     return await this.route(context)
   }
 
+  /** Whether the application serves the trunk with the verb the request was made with. */
+  private serves(context: http.Context): boolean {
+    const match = this.tree.match('/')
+
+    return match !== null && context.request.method in match.node.methods
+  }
+
   /**
    * One call: everything that needs a node. A request makes one of these, and a request
    * that carries several calls makes one per call.
@@ -200,14 +225,19 @@ export class Gateway extends Connector {
     node: Node,
     parameters: Parameter[]
   ): Promise<http.OutgoingMessage> {
-    const body = await node.explain(context, parameters)
-    const verbs = Object.keys(body)
+    const { described, methods } = await node.explain(describing(context), parameters)
+    const verbs = Object.keys(methods)
 
     // 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: new Headers({ allow: verbs.join(', ') }) }
+    // what the resource is, beside the methods it serves; a verb is upper case and cannot
+    // collide with either key
+    return {
+      body: { ...described, ...methods },
+      headers: new Headers({ allow: verbs.join(', ') })
+    }
   }
 
   private async discover(): Promise<void> {

package/source/HTTP/Context.ts

@@ -26,6 +26,13 @@ export class Context {
    */
   public readonly procedural: boolean = false
 
+  /**
+   * Whether this describes a resource rather than calling one. What builds a describing
+   * context says so, and a directive that answers differently to a description than to a
+   * call reads it here.
+   */
+  public readonly exploratory: boolean = false
+
   public readonly pipelines: Pipelines = {
     body: [],
     response: []

package/source/HTTP/Probe.ts

@@ -96,15 +96,4 @@ export class Probe {
   }
 }
 
-/**
- * Reserved for this probe. `8001` is the Telemetry readiness probe's, and `toa export` refuses a
- * port claimed twice — `toa mono` and a local run put every service in one process.
- */
-export const PROBE = 8004
 export const PATH = '/.ready'
-
-/**
- * The initial delay of the readiness probe. The server does not sleep for it: whoever
- * probes is the one that waits, and doing it here as well only delayed the process twice.
- */
-export const DELAY = 3 // seconds

package/source/HTTP/Server.ts

@@ -10,7 +10,8 @@ import { Connector } from '@toa.io/core'
 import { type OutgoingMessage, write } from './messages.js'
 import { ClientError, Exception } from './exceptions.js'
 import { Context } from './Context.js'
-import { PROBE, Probe } from './Probe.js'
+import { Probe } from './Probe.js'
+import { PORT, PROBE } from '../const.js'
 import type { IncomingMessage, Protocol, ServerResponse } from './types.js'
 import type { Bouncer, MCP, OAuth, RPC } from '../Annotation.js'
 
@@ -331,8 +332,6 @@ function errorAttributes(
   return attributes
 }
 
-export const PORT = 8000
-
 export const DRAIN = 10 // seconds
 
 /** Megabytes a single HTTP/2 session may hold, over Node's default of 10. */

package/source/HTTP/messages.ts

@@ -5,13 +5,15 @@ import * as contentType from 'content-type'
 import { console } from 'openspan'
 import { type Format, decoders } from './formats/index.js'
 import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions.js'
+import { environment } from '@toa.io/generic'
 import type { Context } from './Context.js'
 import type { ServerResponse } from './types.js'
 
+const context = environment.get('TOA_CONTEXT')
+const env = environment.get('TOA_ENV')
 const server =
   `Exposition/${JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version}` +
-  ((process.env.TOA_CONTEXT === undefined ? '' : ` ${process.env.TOA_CONTEXT}`) +
-    (process.env.TOA_ENV === undefined ? '' : `/${process.env.TOA_ENV}`))
+  ((context === undefined ? '' : ` ${context}`) + (env === undefined ? '' : `/${env}`))
 
 /**
  * Applies what the request accumulated in `pipelines.response` — an `io:output` restriction,

package/source/Introspection.ts

@@ -1,4 +1,5 @@
 import type { Remote } from '@toa.io/core'
+import type { Context } from './HTTP/index.js'
 
 export interface Introspection {
   /**
@@ -11,24 +12,68 @@ export interface Introspection {
 
   /** 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 a request header carries, which is therefore not the body's to send */
-  headers?: Record<string, Sourced>
+  /** 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[]
 }
 
-/** A property the gateway reads from somewhere else, and the schema it was declared with. */
-export interface Sourced {
-  header: string
-  [keyword: string]: unknown
+/** 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.
@@ -45,9 +90,15 @@ export function order(introspection: Introspection): Introspection {
 const KEYS = [
   'title',
   'description',
+  'anonymous',
+  'authenticated',
+  'private',
+  'protected',
+  'system',
+  'mcp',
   'route',
   'query',
-  'headers',
+  'octets',
   'input',
   'output',
   'errors'

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(