@toa.io/extensions.exposition 1.0.0-alpha.29 → 1.0.0-alpha.291

package/source/directives/help/Family.ts

@@ -0,0 +1,122 @@
+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 | null {
+    const help = Family.method(directives)
+
+    // what is hidden is hidden from every answer at once, this being the one place they
+    // all read; the method itself is reached as it always was
+    if (help?.hidden === true) return null
+
+    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,47 @@
+import assert from 'node:assert'
+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
+
+  /**
+   * Whether the method is described at all. `help:method: null` takes it out of every
+   * answer — `OPTIONS`, discovery and the tools MCP publishes — and leaves it as callable
+   * as it was: a route something else reaches for, and nobody is meant to go looking for.
+   */
+  public readonly hidden: boolean
+
+  public constructor(subject: Subject, value: unknown) {
+    assert.ok(
+      value !== null || subject === 'method',
+      `Directive help:${subject}: only a method is hidden`
+    )
+
+    if (value === null) {
+      this.subject = subject
+      this.hidden = true
+
+      return
+    }
+
+    const stated: Described = described(`help:${subject}`, value)
+
+    this.subject = subject
+    this.hidden = false
+    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

@@ -1,13 +1,33 @@
-import { authorization } from './auth'
-import { cache } from './cache'
-import { cors } from './cors'
-import { dev } from './dev'
-import { octets } from './octets'
-import { io } from './io'
-import { vary } from './vary'
-import { req } from './require'
-import type { DirectiveFamily } from '../RTD'
-import type { Interceptor } from '../Interception'
+import { authorization } from './auth/index.js'
+import { cache } from './cache/index.js'
+import { cors } from './cors/index.js'
+import { dev } from './dev/index.js'
+import { octets } from './octets/index.js'
+import { io } from './io/index.js'
+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'
 
-export const families: DirectiveFamily[] = [authorization, io, cache, vary, req, octets, dev]
-export const interceptors: Interceptor[] = [cors]
+export const families: DirectiveFamily[] = [
+  authorization,
+  io,
+  cache,
+  map,
+  mcp,
+  help,
+  req,
+  flow,
+  octets,
+  dev
+]
+/**
+ * `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()]

package/source/directives/io/Directive.ts

@@ -1,11 +1,17 @@
-import type { Input } from '../../io'
+import type { Sync } from './lib/throttle/index.js'
+import type { Parameter } from '../../RTD/index.js'
+import type { Input as Context } from '../../io.js'
+import type * as http from '../../HTTP/index.js'
 
 export interface Directive {
-  attach: (context: Input) => void
+  precall: (context: Context, parameters: Parameter[]) => void
+
+  /** Synchronous by contract: settling holds the response, and none of it needs I/O. */
+  settle?: (context: Context, response: http.OutgoingMessage) => void
 }
 
 export interface Constructor {
   validate: (value: unknown) => void
 
-  new (value: any): Directive
+  new (value: any, sync: Sync, route: string): Directive
 }