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

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) => {

package/source/directives/help/Family.ts

@@ -0,0 +1,118 @@
+import assert from 'node:assert'
+import { Help } from './Help.js'
+import { Parameters } from './Parameters.js'
+import type { Introspection, Schema } from '../../Introspection.js'
+import type { Described } from './described.js'
+import type { Context } from '../../HTTP/index.js'
+import type { DirectiveFamily } from '../../RTD/index.js'
+
+/** The name the family is declared under, and what a consumer of one asks a method for. */
+export const FAMILY = 'help'
+
+export type Directive = Help | Parameters
+
+export class Family implements DirectiveFamily<Directive> {
+  public readonly name = FAMILY
+  public readonly mandatory = false
+
+  /**
+   * What a node says of itself is not said of what is under it: inherited, `help:node`
+   * would describe every resource below as the one it was written for. The rest go with
+   * it — a sentence about one method is not true of the next, and a route variable a
+   * template does not have is not one at all.
+   */
+  public readonly inherited = false
+
+  /** What the nearest declaration says of the method, or nothing where none does. */
+  public static method(directives: Directive[] | undefined): Help | null {
+    return stated(directives, 'method')
+  }
+
+  /** And the same of the resource the method is on. */
+  public static node(directives: Directive[] | undefined): Help | null {
+    return stated(directives, 'node')
+  }
+
+  // eslint-disable-next-line max-params
+  public create(name: string, value: unknown, _: unknown, route: string): Directive {
+    if (name === 'node' || name === 'method') return new Help(name, value)
+
+    assert.ok(name === 'route' || name === 'query', `Unknown directive: help:${name}`)
+
+    return new Parameters(name, value, route)
+  }
+
+  /** What the route states this method and its parameters are. */
+  public explain(
+    directives: Directive[],
+    _: Context,
+    introspection: Introspection
+  ): Introspection {
+    const help = Family.method(directives)
+
+    const described: Introspection = {
+      ...introspection,
+      ...(help?.title === undefined ? {} : { title: help.title }),
+      ...(help?.description === undefined ? {} : { description: help.description })
+    }
+
+    // a schema says `title` and `description` of what it describes, which is where these go
+    for (const subject of PARAMETERS) {
+      const declaration = declared(directives, subject)
+
+      if (declaration === null) continue
+
+      const parameters = declaration.parameters
+
+      for (const [name, stated] of Object.entries(parameters)) {
+        const schema = described[subject]?.[name]
+
+        /*
+         * A route variable is one because the template names it, whether or not the
+         * operation declares it as input — and only then is it answered. `:id` on an
+         * observation is the ordinary case: it is taken by the query, so nothing describes
+         * it and the caller is not told it is a path parameter at all.
+         *
+         * Anything else is described only where it is already answered: a querystring
+         * parameter is one only where the mapping takes it, and a segment `map:segments`
+         * renames is answered under the property it fills.
+         */
+        if (schema === undefined && !declaration.variables.includes(name)) continue
+
+        // written where the shape states it, whatever the schema already said
+        const merged = { ...schema } as Record<string, unknown>
+
+        delete merged.title
+        delete merged.description
+
+        described[subject] ??= {}
+        described[subject]![name] = Object.assign(merged, stated) as unknown as Schema
+      }
+    }
+
+    return described
+  }
+}
+
+const PARAMETERS = ['route', 'query'] as const
+
+function stated(directives: Directive[] | undefined, subject: string): Help | null {
+  const help = directives?.find(
+    (directive) => directive instanceof Help && directive.subject === subject
+  )
+
+  return (help as Help | undefined) ?? null
+}
+
+function declared(
+  directives: Directive[] | undefined,
+  subject: string
+): Parameters | null {
+  const found = directives?.find(
+    (directive) => directive instanceof Parameters && directive.subject === subject
+  )
+
+  return (found as Parameters | undefined) ?? null
+}
+
+export type { Described }

package/source/directives/help/Help.test.ts

@@ -0,0 +1,227 @@
+import assert from 'node:assert'
+import { describe, it } from 'node:test'
+import { Help } from './Help.js'
+import { Family } from './Family.js'
+import { Parameters } from './Parameters.js'
+
+describe('help:method', () => {
+  it('should read a bare value as the title, which is the short thing', () => {
+    const help = new Help('method', 'Hot pots')
+
+    assert.strictEqual(help.title, 'Hot pots')
+    assert.strictEqual(help.description, undefined)
+  })
+
+  it('should take a description beside it', () => {
+    const help = new Help('method', {
+      title: 'Hot pots',
+      description: 'The pots that are too hot to pour.'
+    })
+
+    assert.strictEqual(help.title, 'Hot pots')
+    assert.strictEqual(help.description, 'The pots that are too hot to pour.')
+  })
+
+  it('should take a description alone', () => {
+    const help = new Help('method', { description: 'Every pot there is.' })
+
+    assert.strictEqual(help.title, undefined)
+    assert.strictEqual(help.description, 'Every pot there is.')
+  })
+
+  it('should not accept one that says nothing', () => {
+    assert.throws(() => new Help('method', {}), /says nothing/)
+  })
+
+  it('should not accept what it does not know', () => {
+    assert.throws(() => new Help('method', { summary: 'A pot.' }), /'summary'/)
+  })
+
+  it('should not accept an empty value', () => {
+    assert.throws(() => new Help('method', { title: ' ' }), /title cannot be empty/)
+    assert.throws(
+      () => new Help('method', { description: ' ' }),
+      /description cannot be empty/
+    )
+  })
+
+  it('should not accept a value that is not one', () => {
+    assert.throws(() => new Help('method', ['a']), /the value is a title/)
+  })
+})
+
+describe('help:node', () => {
+  it('should read the value as the title', () => {
+    const help = new Help('node', 'Pots')
+
+    assert.strictEqual(help.title, 'Pots')
+    assert.strictEqual(help.description, undefined)
+  })
+
+  it('should take a description beside it, as a method does', () => {
+    const help = new Help('node', { title: 'Pots', description: 'What is brewing.' })
+
+    assert.strictEqual(help.title, 'Pots')
+    assert.strictEqual(help.description, 'What is brewing.')
+  })
+})
+
+describe('help', () => {
+  const help = new Family()
+
+  it('should not be inherited: a node describes itself, not what is under it', () => {
+    assert.strictEqual(help.inherited, false)
+  })
+
+  it('should take the nearest declaration of each subject', () => {
+    const directives = [
+      new Help('method', 'Nearest'),
+      new Help('node', 'Resource'),
+      new Help('method', 'Further')
+    ]
+
+    assert.strictEqual(Family.method(directives)?.title, 'Nearest')
+    assert.strictEqual(Family.node(directives)?.title, 'Resource')
+  })
+
+  it('should say nothing where nothing is declared', () => {
+    assert.strictEqual(Family.method(undefined), null)
+    assert.strictEqual(Family.node([]), null)
+  })
+
+  it('should describe a method with what the route states', () => {
+    const directives = [new Help('method', { title: 'Hot', description: 'Too hot.' })]
+
+    assert.deepStrictEqual(help.explain(directives, null as never, { errors: ['NO'] }), {
+      errors: ['NO'],
+      title: 'Hot',
+      description: 'Too hot.'
+    })
+  })
+
+  it('should leave a method the node describes alone', () => {
+    // what the resource is, is not what one of its methods is
+    const directives = [new Help('node', 'Pots')]
+
+    assert.deepStrictEqual(help.explain(directives, null as never, {}), {})
+  })
+
+  it('should refuse a directive it does not know', () => {
+    assert.throws(() => help.create('resource', 'Pots'), /Unknown directive/)
+  })
+})
+
+describe('help:route', () => {
+  it('should describe a variable the template names', () => {
+    const stated = new Parameters('route', { id: 'The pot' }, '/pots/:id')
+
+    assert.deepStrictEqual(stated.parameters, { id: { title: 'The pot' } })
+  })
+
+  it('should take a description beside it', () => {
+    const stated = new Parameters(
+      'route',
+      { id: { title: 'The pot', description: 'Which pot to pour.' } },
+      '/pots/:id'
+    )
+
+    assert.deepStrictEqual(stated.parameters.id, {
+      title: 'The pot',
+      description: 'Which pot to pour.'
+    })
+  })
+
+  it('should keep what the template names, which is what may be answered anew', () => {
+    const stated = new Parameters('route', { id: 'The pot' }, '/pots/:id')
+
+    assert.deepStrictEqual(stated.variables, ['id'])
+  })
+
+  it('should not check a name, because the template is not what says them all', () => {
+    // `map:segments` answers a variable under the property it fills, and that name is
+    // nowhere in the template
+    const stated = new Parameters('route', { pot: 'The pot' }, '/pots/:id')
+
+    assert.deepStrictEqual(stated.parameters, { pot: { title: 'The pot' } })
+  })
+
+  it('should name the rest of a path as the template writes it', () => {
+    const stated = new Parameters('route', { '**': 'What is left' }, '/files/**')
+
+    assert.deepStrictEqual(stated.parameters, { '**': { title: 'What is left' } })
+  })
+})
+
+describe('help:query', () => {
+  it('should describe a parameter, which no template names', () => {
+    const stated = new Parameters('query', { since: 'From when' }, '/pots')
+
+    assert.deepStrictEqual(stated.parameters, { since: { title: 'From when' } })
+  })
+
+  it('should refuse a value that names nothing', () => {
+    assert.throws(() => new Parameters('query', 'since', '/pots'), /names each parameter/)
+  })
+
+  it('should refuse one that says nothing', () => {
+    assert.throws(
+      () => new Parameters('query', { since: {} }, '/pots'),
+      /help:query\.since: says nothing/
+    )
+  })
+})
+
+describe('help parameters', () => {
+  const help = new Family()
+
+  it('should say what a parameter is, where its schema is', () => {
+    const directives = [
+      new Parameters('route', { id: 'The pot' }, '/pots/:id'),
+      new Parameters('query', { limit: { description: 'How many.' } }, '/pots/:id')
+    ]
+
+    const explained = help.explain(directives, null as never, {
+      route: { id: { type: 'string' } as never },
+      query: { limit: { type: 'integer' } as never }
+    })
+
+    assert.deepStrictEqual(explained.route, { id: { type: 'string', title: 'The pot' } })
+    assert.deepStrictEqual(explained.query, {
+      limit: { type: 'integer', description: 'How many.' }
+    })
+  })
+
+  it('should leave a parameter the method does not take alone', () => {
+    const directives = [new Parameters('query', { since: 'From when' }, '/pots')]
+
+    assert.deepStrictEqual(help.explain(directives, null as never, {}), {})
+  })
+
+  it('should answer a route variable an operation does not declare', () => {
+    // `:id` on an observation is taken by the query, so nothing else describes it
+    const directives = [new Parameters('route', { id: 'The pot' }, '/pots/:id')]
+
+    assert.deepStrictEqual(help.explain(directives, null as never, {}), {
+      route: { id: { title: 'The pot' } }
+    })
+  })
+
+  it('should describe a segment a mapping renamed, under the name it answers by', () => {
+    const directives = [new Parameters('route', { a: 'Which one' }, '/echo/:first')]
+
+    const explained = help.explain(directives, null as never, {
+      route: { a: { type: 'string' } as never }
+    })
+
+    assert.deepStrictEqual(explained.route, { a: { type: 'string', title: 'Which one' } })
+  })
+
+  it('should not invent a parameter nothing answers', () => {
+    const directives = [new Parameters('route', { typo: 'Nobody' }, '/echo/:first')]
+
+    assert.deepStrictEqual(
+      help.explain(directives, null as never, { route: { a: { type: 'string' } as never } }),
+      { route: { a: { type: 'string' } } }
+    )
+  })
+})

package/source/directives/help/Help.ts

@@ -0,0 +1,26 @@
+import { described, type Described } from './described.js'
+
+/**
+ * What a resource or a method is, in the words an application chooses for it — read by
+ * everything that describes one: `OPTIONS`, discovery, and the tools MCP publishes.
+ *
+ * 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 is not true of both.
+ */
+export class Help {
+  /** `node` says what the resource is; `method` what one of its methods is. */
+  public readonly subject: Subject
+  public readonly title: string | undefined
+  public readonly description: string | undefined
+
+  public constructor(subject: Subject, value: unknown) {
+    const stated: Described = described(`help:${subject}`, value)
+
+    this.subject = subject
+    this.title = stated.title
+    this.description = stated.description
+  }
+}
+
+export type Subject = 'node' | 'method'

package/source/directives/help/Parameters.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert'
+import { segment } from '../../RTD/segment.js'
+import { described, type Described } from './described.js'
+
+/**
+ * What the parameters of a method are, by name: a route variable, or one of the
+ * querystring. Written where the method is, because what a variable means is what the
+ * route it is in makes of it.
+ *
+ * A name is not checked against the template, because the template is not what says them
+ * all: `map:segments` answers a variable under the property it fills instead, and that
+ * name is nowhere here. What matches nothing is not answered.
+ */
+export class Parameters {
+  public readonly subject: Subject
+  public readonly parameters: Record<string, Described>
+
+  /** What the route template names, which is a parameter whether an operation takes it or not. */
+  public readonly variables: string[]
+
+  public constructor(subject: Subject, value: unknown, route: string) {
+    assert.ok(
+      typeof value === 'object' && value !== null && !Array.isArray(value),
+      `Directive help:${subject}: the value names each parameter it describes`
+    )
+
+    const parameters: Record<string, Described> = {}
+
+    for (const [name, stated] of Object.entries(value))
+      parameters[name] = described(`help:${subject}.${name}`, stated)
+
+    this.subject = subject
+    this.parameters = parameters
+    this.variables = subject === 'route' ? names(route) : []
+  }
+}
+
+/** The variables the template names, which are what a route parameter may be called. */
+function names(route: string): string[] {
+  return segment(route)
+    .map((part) =>
+      part.fragment !== null ? null : part.wildcard === true ? '**' : part.placeholder
+    )
+    .filter((name): name is string => name !== null)
+}
+
+export type Subject = 'route' | 'query'

package/source/directives/help/described.ts

@@ -0,0 +1,57 @@
+import assert from 'node:assert'
+
+/** What a resource, a method or a parameter says of itself, in the order it is written. */
+export interface Described {
+  title?: string
+  description?: string
+
+  /** what its methods are guarded by; see `guarded` */
+  authenticated?: boolean
+  private?: boolean
+  protected?: boolean
+  system?: boolean
+}
+
+/**
+ * A bare value is the title: it is the short thing, and the one a client has somewhere to
+ * put — a name is an address and reads as one. A sentence is written as a mapping, beside
+ * the title it explains, and either may stand alone.
+ */
+export function described(subject: string, value: unknown): Described {
+  const stated = typeof value === 'string' ? { title: value } : value
+
+  assert.ok(
+    typeof stated === 'object' && stated !== null && !Array.isArray(stated),
+    `Directive ${subject}: the value is a title, or a \`title\` and a \`description\``
+  )
+
+  const { title, description, ...rest } = stated as Record<string, unknown>
+
+  assert.ok(
+    Object.keys(rest).length === 0,
+    `Directive ${subject}: unknown ${Object.keys(rest)
+      .map((key) => `'${key}'`)
+      .join(', ')}`
+  )
+
+  assert.ok(
+    title === undefined || (typeof title === 'string' && title.trim().length > 0),
+    `Directive ${subject}: a title cannot be empty`
+  )
+
+  assert.ok(
+    description === undefined ||
+      (typeof description === 'string' && description.trim().length > 0),
+    `Directive ${subject}: a description cannot be empty`
+  )
+
+  assert.ok(
+    title !== undefined || description !== undefined,
+    `Directive ${subject}: says nothing`
+  )
+
+  return {
+    ...(title === undefined ? {} : { title: title as string }),
+    ...(description === undefined ? {} : { description: description as string })
+  }
+}

package/source/directives/help/index.ts

@@ -0,0 +1,45 @@
+import { Family, FAMILY } from './Family.js'
+import type { Directive } from './Family.js'
+import type { Described } from './described.js'
+import type { Directives } from '../../RTD/index.js'
+import type { Introspection } from '../../Introspection.js'
+
+export const help = new Family()
+
+/**
+ * What the resource a method is on says of itself, or nothing where it says nothing. Read
+ * from the method because that is what carries a route's directives; every method of one
+ * node carries the same declaration.
+ */
+export function resource(directives: Directives): Described | null {
+  const stated = Family.node(directives.declared<Directive>(FAMILY))
+
+  if (stated === null) return null
+
+  return {
+    ...(stated.title === undefined ? {} : { title: stated.title }),
+    ...(stated.description === undefined ? {} : { description: stated.description })
+  }
+}
+
+/**
+ * What a resource is, taken from what its methods are: the flags are a method's, and a
+ * resource carries whichever of them any of its methods does — which is what a reader picks
+ * one icon by.
+ */
+export function guarded(methods: Record<string, Introspection>): Described {
+  const described: Described = {}
+
+  for (const introspection of Object.values(methods))
+    for (const flag of FLAGS) if (introspection[flag] === true) described[flag] = true
+
+  return described
+}
+
+const FLAGS = ['authenticated', 'private', 'protected', 'system'] as const
+
+export { FAMILY, Family } from './Family.js'
+export { Help } from './Help.js'
+export { Parameters } from './Parameters.js'
+export type { Directive } from './Family.js'
+export type { Described } from './described.js'

package/source/directives/index.ts

@@ -8,7 +8,9 @@ import { map } from './map/index.js'
 import { mcp } from './mcp/index.js'
 import { req } from './require/index.js'
 import { flow } from './flow/index.js'
+import { help } from './help/index.js'
 import { discovery } from './oauth/index.js'
+import { Site } from '../Discovery/index.js'
 import type { DirectiveFamily } from '../RTD/index.js'
 import type { Interceptor } from '../Interception.js'
 
@@ -18,9 +20,14 @@ export const families: DirectiveFamily[] = [
   cache,
   map,
   mcp,
+  help,
   req,
   flow,
   octets,
   dev
 ]
-export const interceptors: Interceptor[] = [cors, discovery]
+/**
+ * `cors` first, so a preflight is answered before anything reads the request; the page is
+ * last, and claims its own prefix.
+ */
+export const interceptors: Interceptor[] = [cors, discovery, new Site()]