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

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

@@ -1,5 +1,8 @@
 export const BRANCH_TTL = 1_800_000
 
+/** The broadcast the gateway and its tenants share. */
+export const CHANNEL = 'exposition'
+
 /** The replicas of the gateway decide together, whatever context they serve. */
 export const ATOM_GROUP = 'exposition'
 
@@ -17,3 +20,26 @@ 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'
+
+/** Where the gateway serves. */
+export const PORT = 8000
+
+/**
+ * Reserved for the readiness 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
+
+/**
+ * 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/deployment.ts

@@ -3,10 +3,10 @@ import assert from 'node:assert'
 import { type Dependency, type Service } from '@toa.io/operations'
 import { type Annotation } from './Annotation.js'
 import * as schemas from './schemas.js'
-import { shortcuts } from './Directive.js'
+import { shortcuts } from './shortcuts.js'
 import { components } from './Composition.js'
 import { parse } from './RTD/syntax/index.js'
-import { DELAY, PORT, PROBE } from './HTTP/index.js'
+import { DELAY, PORT, PROBE } from './const.js'
 
 /** Where Toa's release publishes this service's image. An application takes it
  *  instead of building one when its context says `registry.services: published`. */

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

@@ -1,4 +1,5 @@
 import { type Directive, type Context } from './types.js'
+import type { Introspection } from '../../Introspection.js'
 
 export class Anonymous implements Directive {
   private readonly allow: boolean
@@ -9,11 +10,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
   }
@@ -21,4 +24,13 @@ export class Anonymous implements Directive {
   public admits(_: any, context: Context): boolean {
     return this.authorize(_, context)
   }
+
+  /**
+   * That nothing guards it is something said rather than something left unsaid: it is also
+   * what refuses a caller presenting a credential, and a client with one has to know which
+   * methods not to present it to.
+   */
+  public describe(introspection: Introspection): Introspection {
+    return this.allow ? { ...introspection, anonymous: true } : introspection
+  }
 }

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,

package/source/directives/auth/Role.ts

@@ -4,6 +4,7 @@ import { type Component } from '@toa.io/core'
 import type { Query } from '@toa.io/core/types'
 import { type Directive, type Identity } from './types.js'
 import type { Parameter } from '../../RTD/index.js'
+import type { Introspection } from '../../Introspection.js'
 
 export class Role implements Directive {
   public static remote: Component | null = null
@@ -31,6 +32,19 @@ export class Role implements Directive {
     return await this.remote.invoke('list', { query })
   }
 
+  /**
+   * Reaching it takes a role, which is what `protected` says. A role of the `system` scope
+   * says so besides: what it guards is the machinery an application runs on rather than
+   * anything it serves, and a reader has no business being offered it as one.
+   */
+  public describe(introspection: Introspection): Introspection {
+    const system = this.roles.some(
+      (role) => role === SYSTEM || role.startsWith(SYSTEM + ':')
+    )
+
+    return { ...introspection, protected: true, ...(system ? { system: true } : {}) }
+  }
+
   public async authorize(
     identity: Identity | null,
     _: unknown,
@@ -80,3 +94,6 @@ export class Role implements Directive {
     )
   }
 }
+
+/** The scope of what an application runs on, as opposed to what it serves. */
+const SYSTEM = 'system'

package/source/directives/cors/CORS.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { CORS } from './CORS.js'
+import type { Input } from '../../io.js'
+
+const input = (method: string, headers: Record<string, string>): Input =>
+  ({
+    request: { method, headers },
+    pipelines: { body: [], response: [] }
+  }) as unknown as Input
+
+describe('cors', () => {
+  let cors: CORS
+
+  beforeEach(() => {
+    cors = new CORS()
+    cors.reset()
+  })
+
+  it('should answer a preflight', () => {
+    const output = cors.intercept(
+      input('OPTIONS', {
+        origin: 'https://hello.world',
+        'access-control-request-method': 'GET'
+      })
+    )
+
+    assert.equal(output?.status, 204)
+    assert.equal(output?.headers?.get('access-control-allow-origin'), 'https://hello.world')
+  })
+
+  it('should allow OPTIONS, so that one can be preflighted at all', () => {
+    const output = cors.intercept(
+      input('OPTIONS', {
+        origin: 'https://hello.world',
+        'access-control-request-method': 'OPTIONS'
+      })
+    )
+
+    assert.match(output?.headers?.get('access-control-allow-methods') ?? '', /\bOPTIONS\b/)
+  })
+
+  it('should pass an OPTIONS that is not a preflight through', () => {
+    /*
+     * A browser puts `Origin` on every request whose method is not `GET` or `HEAD`, its own
+     * `OPTIONS` included — so answering this one here would put introspection out of reach
+     * of any page. Do not restore the `Origin`-only test.
+     */
+    const output = cors.intercept(input('OPTIONS', { origin: 'https://hello.world' }))
+
+    assert.equal(output, null)
+  })
+
+  it('should decorate a reply that is not a preflight', () => {
+    const request = input('OPTIONS', { origin: 'https://hello.world' })
+
+    cors.intercept(request)
+
+    const message = {}
+
+    for (const transform of request.pipelines.response) transform(message)
+
+    const headers = (message as { headers?: Headers }).headers
+
+    assert.equal(headers?.get('access-control-allow-origin'), 'https://hello.world')
+    assert.equal(headers?.get('access-control-allow-credentials'), 'true')
+    assert.equal(headers?.get('vary'), 'origin')
+  })
+
+  it('should pass a request carrying no origin through', () => {
+    assert.equal(cors.intercept(input('OPTIONS', {})), null)
+    assert.equal(cors.intercept(input('GET', {})), null)
+  })
+})

package/source/directives/cors/CORS.ts

@@ -16,7 +16,7 @@ export class CORS implements Interceptor {
   private requestHeaders = new Set<string>(REQUEST_HEADERS)
 
   private readonly headers = new Headers({
-    'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK',
+    'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK, OPTIONS',
     'access-control-allow-credentials': 'true',
     'access-control-allow-headers': this.allowedHeaders(),
     'access-control-max-age': '3600',
@@ -26,8 +26,15 @@ export class CORS implements Interceptor {
 
   public intercept(input: Input): Output {
     const origin = input.request.headers.origin
-
-    if (origin !== undefined && input.request.method === 'OPTIONS')
+    const requested = input.request.headers['access-control-request-method']
+
+    /*
+     * A preflight is `OPTIONS` carrying `Access-Control-Request-Method`, and only that. A
+     * browser puts `Origin` on every request whose method is not `GET` or `HEAD` — its own
+     * `OPTIONS` included, same-origin or not — so answering that one here would put
+     * introspection out of reach of any page.
+     */
+    if (origin !== undefined && requested !== undefined && input.request.method === 'OPTIONS')
       return this.preflightResponse(origin)
 
     input.pipelines.response.push((output) => {