@toa.io/extensions.exposition 1.0.0-alpha.292 → 1.0.0-alpha.293

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

@@ -1,227 +0,0 @@
-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

@@ -1,47 +0,0 @@
-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

@@ -1,47 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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,33 +0,0 @@
-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,
-  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,17 +0,0 @@
-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 {
-  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, sync: Sync, route: string): Directive
-}

package/source/directives/io/IO.ts

@@ -1,118 +0,0 @@
-import { restrict } from '../../Introspection.js'
-import { Output } from './Output.js'
-import { Input } from './Input.js'
-import { Throttle } from './Throttle.js'
-import { Status } from './Status.js'
-import { Sync } from './lib/throttle/index.js'
-import type * as http from '../../HTTP/index.js'
-import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
-import type { Remotes } from '../../Remotes.js'
-import type { Constructor, Directive } from './Directive.js'
-import type { Introspection } from '../../Introspection.js'
-import { ATOM_GROUP } from '@toa.io/definitions/extensions.exposition'
-import type { extensions } from '@toa.io/core/types'
-
-export class IO implements DirectiveFamily<Directive> {
-  public readonly name = 'io'
-  public readonly mandatory = true
-
-  private host!: extensions.Host
-
-  /** Throttling reconciles through the atom of the gateways, one for every directive. */
-  private sync: Sync | null = null
-
-  public mount(host: extensions.Host): void {
-    this.host = host
-  }
-
-  // eslint-disable-next-line max-params
-  public create(
-    name: string,
-    value: unknown,
-    remotes: Remotes,
-    route: string
-  ): Directive {
-    if (!(name in constructors))
-      throw new Error(`Directive 'io:${name}' is not implemented`)
-
-    const Directive = constructors[name]
-
-    Directive.validate(value)
-
-    if (name === 'throttle') this.sync ??= new Sync(this.host.atom(ATOM_GROUP))
-
-    return new Directive(value, this.sync!, route)
-  }
-
-  public precall(
-    directives: Directive[],
-    context: http.Context,
-    parameters: Parameter[]
-  ): null {
-    let restricted = false
-
-    for (const directive of directives) {
-      restricted ||= directive instanceof Output
-
-      directive.precall(context, parameters)
-    }
-
-    if (!restricted) DENIAL.precall(context, parameters)
-
-    return null
-  }
-
-  /**
-   * What a whitelist admits is what the schema states. Without an `io:output` the reply is
-   * dropped before it is sent, so there is no output to describe at all.
-   */
-  public explain(
-    directives: Directive[],
-    _: http.Context,
-    introspection: Introspection
-  ): Introspection {
-    let restricted = false
-
-    for (const directive of directives) {
-      if (directive instanceof Input)
-        introspection.input = restrict(introspection.input, directive.allowed)
-
-      if (!(directive instanceof Output)) continue
-
-      restricted = true
-
-      if (!directive.disabled)
-        introspection.output = restrict(introspection.output, directive.allowed)
-    }
-
-    if (!restricted) delete introspection.output
-
-    return introspection
-  }
-
-  public settle(
-    directives: Directive[],
-    context: http.Context,
-    output: http.OutgoingMessage
-  ): void {
-    for (const directive of directives) directive.settle?.(context, output)
-  }
-
-  /**
-   * The ticker belongs to the family rather than to any route's directives, and the
-   * factory disposes every route it made — so this runs once per route at shutdown,
-   * and disposing an already stopped ticker is what makes that harmless.
-   */
-  public dispose(): void {
-    this.sync?.dispose()
-  }
-}
-
-const constructors: Record<string, Constructor> = {
-  input: Input,
-  output: Output,
-  status: Status,
-  throttle: Throttle
-}
-
-const DENIAL: Directive = new Output([])

package/source/directives/io/Input.ts

@@ -1,55 +0,0 @@
-import { BadRequest } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import type { Message } from './Message.js'
-import type { Directive } from './Directive.js'
-import type { Input as Context } from '../../io.js'
-
-export class Input implements Directive {
-  /** what a client may send, which is therefore what the input schema states */
-  public readonly allowed: Set<string>
-
-  public constructor(permissions: Permissions) {
-    this.allowed = new Set(permissions)
-  }
-
-  public static validate(permissions: unknown): asserts permissions is Permissions {
-    schemas.input.validate<Permissions>(permissions, "Incorrect 'io:input' format")
-  }
-
-  public precall(context: Context): void {
-    // Restrictions are on what the client sent, so the check goes to the front of the
-    // pipeline whatever order the families ran in: `auth:delegate` embeds the identity
-    // and `map:*` assigns mapped properties, and those additions are the server's own,
-    // not input to be restricted.
-    context.pipelines.body.unshift((body) => this.check(body))
-  }
-
-  private check(body: unknown): Message | Message[] | undefined {
-    if (body === undefined) return body
-
-    try {
-      schemas.message.validate<Message | Message[]>(body)
-    } catch {
-      throw new BadRequest('Invalid request body')
-    }
-
-    const property = this.violation(body)
-
-    if (property !== undefined) throw new BadRequest(`Unexpected input: ${property}`)
-
-    return body
-  }
-
-  private violation(value: Message | Message[]): string | undefined {
-    if (!Array.isArray(value))
-      return Object.keys(value).find((key) => !this.allowed.has(key))
-
-    for (const item of value) {
-      const property = this.violation(item)
-
-      if (property !== undefined) return property
-    }
-  }
-}
-
-export type Permissions = string[]

package/source/directives/io/Message.ts

@@ -1 +0,0 @@
-export type Message = Record<string, unknown>