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

package/source/directives/flow/Compose.ts

@@ -1,98 +0,0 @@
-import { once } from 'node:events'
-import * as assert from 'node:assert'
-import { Readable } from 'node:stream'
-import { console } from 'openspan'
-import type { Directive } from './types.js'
-import type { Input as Context } from '../../io.js'
-import type { OutgoingMessage } from '../../HTTP/index.js'
-
-export class Compose implements Directive {
-  private readonly expressions: Expression[]
-
-  public constructor(composition: any) {
-    this.expressions = build(composition)
-  }
-
-  public attach(context: Context): void {
-    context.pipelines.response.push(async (message: OutgoingMessage) => {
-      if (!(message.body instanceof Readable)) {
-        console.warn('Response body is not a stream, skipping composition')
-
-        return
-      }
-
-      assert.ok(message.body instanceof Readable, 'Response body is not a stream')
-
-      assert.ok(
-        // @ts-expect-error -- objectMode is not defined in the type definition
-        message.body._readableState.objectMode,
-        'Response stream is not in object mode'
-      )
-
-      const $ = await this.compose(message.body)
-
-      message.body = this.execute($)
-    })
-  }
-
-  private async compose(stream: Readable): Promise<unknown[]> {
-    const $: unknown[] = []
-
-    stream.on('data', (data) => $.push(data))
-
-    await once(stream, 'end')
-
-    return $
-  }
-
-  private execute($: unknown[]): unknown {
-    let exception: Error | undefined
-
-    for (const expression of this.expressions)
-      try {
-        return expression($)
-      } catch (e: unknown) {
-        exception = e as Error
-        console.debug('Chunks composition failed', { cause: exception.message })
-      }
-
-    throw exception!
-  }
-}
-
-function build(composition: any): Expression[] {
-  return Array.isArray(composition)
-    ? composition.map((variant) => compile(variant as object | string))
-    : [compile(composition as object | string)]
-}
-
-function compile(composition: object | string): Expression {
-  const text =
-    typeof composition === 'string'
-      ? `return ${composition}`
-      : `return ${json(composition)}`
-
-  // eslint-disable-next-line @typescript-eslint/no-implied-eval,no-new-func
-  return new Function('$', text) as Expression
-}
-
-function json(node: object | string): string {
-  if (typeof node === 'string')
-    if (node.startsWith('\\')) return `"${node}"`
-    else return node
-
-  if (Array.isArray(node))
-    return `[${node.map((v) => json(v as object | string)).join(',')}]`
-
-  if (node.constructor !== Object) return JSON.stringify(node)
-
-  return (
-    '{' +
-    Object.entries(node)
-      .map(([key, value]) => `"${key}": ${json(value as object | string)}`)
-      .join(',') +
-    '}'
-  )
-}
-
-type Expression = ($: unknown[]) => unknown

package/source/directives/flow/Fetch.ts

@@ -1,86 +0,0 @@
-import { Readable } from 'node:stream'
-import assert from 'node:assert'
-import { match } from 'matchacho'
-import { NotFound } from '../../HTTP/index.js'
-import type { Directive } from './types.js'
-import type { ReadableStream } from 'node:stream/web'
-import type { Remotes } from '../../Remotes.js'
-import type { Maybe } from '@toa.io/core/types'
-import type { Component } from '@toa.io/core'
-import type { Output } from '../../io.js'
-import type { Input } from '../octets/types.js'
-import type { Parameter } from '../../RTD/index.js'
-
-export class Fetch implements Directive {
-  private readonly connecting: Promise<Component>
-  private remote: Component | null = null
-  private readonly operation: string
-
-  public constructor(endpoint: string, discovery: Remotes) {
-    assert.equal(typeof endpoint, 'string', '`flow:fetch` must be a string')
-
-    const [operation, name, namespace = 'default'] = endpoint.split('.').reverse()
-
-    this.operation = operation
-    this.connecting = discovery.discover(namespace, name)
-  }
-
-  public async apply(input: Input, parameters: Parameter[]): Promise<Output> {
-    if ('if-none-match' in input.request.headers) return { status: 304 }
-
-    this.remote ??= await this.connecting
-
-    const request = await this.remote.invoke<Maybe<Request | string>>(this.operation, {
-      input: {
-        authority: input.authority,
-        path: input.request.url,
-        parameters: Object.fromEntries(parameters.map(({ name, value }) => [name, value]))
-      }
-    })
-
-    if (request instanceof Error) throw new NotFound(request)
-
-    const { url, options } = match<Request>(
-      request,
-      String,
-      { url: request },
-      (request: Request): Request => ({
-        url: request.url,
-        options: {
-          method: request.options?.method ?? 'GET',
-          body: request.options?.body,
-          headers: request.options?.headers
-        }
-      })
-    )
-
-    const response = await fetch(url, options)
-
-    if (!response.ok) throw new NotFound()
-
-    const headers = new Headers()
-
-    for (const header of ['content-type', 'content-length', 'etag']) {
-      const value = response.headers.get(header)
-
-      if (value !== null) headers.set(header, value)
-    }
-
-    return {
-      headers,
-      body:
-        response.body === null ? null : Readable.fromWeb(response.body as ReadableStream)
-    }
-  }
-}
-
-interface Request {
-  url: string
-  options?: RequestOptions
-}
-
-interface RequestOptions {
-  method?: string
-  body?: string
-  headers?: Record<string, string>
-}

package/source/directives/flow/Flow.ts

@@ -1,43 +0,0 @@
-import { Fetch } from './Fetch.js'
-import { Compose } from './Compose.js'
-import type { Directive } from './types.js'
-import type { Input, Output } from '../../io.js'
-import type { DirectiveFamily, Parameter } from '../../RTD/index.js'
-import type { Remotes } from '../../Remotes.js'
-
-export class Flow implements DirectiveFamily<Directive> {
-  public readonly name: string = 'flow'
-  public readonly mandatory: boolean = false
-
-  public create(name: string, value: unknown, remotes: Remotes): Directive {
-    const Class = constructors[name]
-
-    if (Class === undefined)
-      throw new Error(`Directive '${this.name}:${name}' is not implemented`)
-
-    return new Class(value, remotes)
-  }
-
-  public async precall(
-    directives: Directive[],
-    input: Input,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    for (const directive of directives) {
-      if (directive.attach !== undefined) directive.attach(input)
-
-      if (directive.apply === undefined) continue
-
-      const output = await directive.apply(input, parameters)
-
-      if (output !== null) return output
-    }
-
-    return null
-  }
-}
-
-const constructors: Record<string, new (value: any, discovery: Remotes) => Directive> = {
-  fetch: Fetch,
-  compose: Compose
-}

package/source/directives/flow/index.ts

@@ -1,3 +0,0 @@
-import { Flow } from './Flow.js'
-
-export const flow = new Flow()

package/source/directives/flow/types.ts

@@ -1,7 +0,0 @@
-import type { Input as Context, Input, Output } from '../../io.js'
-import type { Parameter } from '../../RTD/index.js'
-
-export interface Directive {
-  apply?: (input: Input, parameters: Parameter[]) => Promise<Output>
-  attach?: (context: Context) => void
-}

package/source/directives/help/Family.ts

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

@@ -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'