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

package/source/directives/io/schemas.test.ts

@@ -1,40 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import * as schemas from './schemas.js'
-
-describe('throttle', () => {
-  const rest = { requests: 1, interval: 1 }
-
-  it('should validate key', () => {
-    assert.doesNotThrow(() => schemas.throttle.validate({ key: 'ip', ...rest }))
-  })
-
-  it('should validate every key component', () => {
-    for (const key of ['ip', 'path', 'route', 'identity'])
-      assert.doesNotThrow(() => schemas.throttle.validate({ key, ...rest }))
-
-    assert.doesNotThrow(() =>
-      schemas.throttle.validate({ key: { segment: 'id' }, ...rest })
-    )
-    assert.doesNotThrow(() =>
-      schemas.throttle.validate({
-        key: ['route', { segment: 'id' }],
-        ...rest
-      })
-    )
-  })
-
-  it('should reject an unknown key component', () => {
-    assert.throws(() => schemas.throttle.validate({ key: 'header', ...rest }))
-    assert.throws(() =>
-      schemas.throttle.validate({ key: { header: 'x-real-ip' }, ...rest })
-    )
-  })
-
-  it('should reject a declaration it no longer honours', () => {
-    // metering earns the budget back rather than locking a key out, so a `cooldown`
-    // left behind is not something to ignore quietly
-    assert.throws(() => schemas.throttle.validate({ key: 'ip', cooldown: 1, ...rest }))
-  })
-})

package/source/directives/io/schemas.ts

@@ -1,16 +0,0 @@
-import { resolve } from 'node:path'
-import * as schemas from '@toa.io/schemas'
-import type { Schema } from '@toa.io/schemas'
-import type { Permissions as InputPermissions } from './Input.js'
-import type { Permissions as OutputPermissions } from './Output.js'
-import type { Declaration as ThrottleDeclaration } from './lib/throttle/index.js'
-
-import type { Message } from './Message.js'
-
-const path = resolve(import.meta.dirname, '../../../schemas/io')
-const namespace = schemas.namespace(path)
-
-export const message: Schema<Message | Message[]> = namespace.schema('message')
-export const input: Schema<InputPermissions> = namespace.schema('input')
-export const output: Schema<OutputPermissions> = namespace.schema('output')
-export const throttle: Schema<ThrottleDeclaration> = namespace.schema('throttle')

package/source/directives/map/Authority.ts

@@ -1,15 +0,0 @@
-import assert from 'node:assert'
-import { Mapping } from './Mapping.js'
-import type { Input } from '../../io.js'
-
-export class Authority extends Mapping<string> {
-  public constructor(property: string) {
-    assert.ok(typeof property === 'string', '`map:authority` must be a string')
-
-    super(property)
-  }
-
-  public properties(context: Input): Record<string, string> {
-    return { [this.value]: context.authority }
-  }
-}

package/source/directives/map/Buffer.ts

@@ -1,15 +0,0 @@
-import assert from 'node:assert'
-import { Mapping } from './Mapping.js'
-import type { Input } from '../../io.js'
-
-export class BufferMapping extends Mapping<string> {
-  public constructor(property: string) {
-    assert.ok(typeof property === 'string', '`map:buffer` must be a string')
-
-    super(property)
-  }
-
-  public override async properties(context: Input): Promise<Record<string, string>> {
-    return { [this.value]: (await context.buffer()).toString('utf8') }
-  }
-}

package/source/directives/map/Claims.ts

@@ -1,63 +0,0 @@
-import assert from 'node:assert'
-import { Mapping } from './Mapping.js'
-import type { Component } from '@toa.io/core'
-import type { Remotes } from '../../Remotes.js'
-import type { Input } from '../../io.js'
-
-export class Claims extends Mapping<Record<string, string>> {
-  private readonly discovery!: Promise<Component>
-  private federation: Component | null = null
-
-  public constructor(map: Record<string, string>, remotes: Remotes) {
-    assert.ok(map.constructor === Object, '`map:claims` must be an object')
-
-    assert.ok(
-      Object.values(map).every((value) => typeof value === 'string'),
-      '`map:claims ` must be an object with string values'
-    )
-
-    super(map, remotes)
-
-    this.discovery = remotes.discover('identity', 'federation')
-  }
-
-  public override async properties(
-    context: Input
-  ): Promise<Record<string, string> | null> {
-    const authentication = context.request.headers.authorization
-
-    if (authentication === undefined) return null
-
-    const claims = await this.claims(authentication)
-
-    if (claims === null) return null
-
-    return Object.entries(this.value).reduce(
-      (properties: Record<string, string>, [property, claim]) => {
-        const value = claims[claim]
-
-        if (value !== undefined) properties[property] = value
-
-        return properties
-      },
-      {}
-    )
-  }
-
-  private async claims(authentication: string): Promise<Record<string, string> | null> {
-    const [scheme, credentials] = authentication.split(' ')
-
-    if (scheme !== 'Bearer' || credentials === undefined) return null
-
-    this.federation ??= await this.discovery
-
-    const claims = await this.federation.invoke<Record<string, string> | Error>(
-      'decode',
-      { input: credentials }
-    )
-
-    if (claims instanceof Error) return null
-
-    return claims
-  }
-}

package/source/directives/map/Directive.ts

@@ -1,4 +0,0 @@
-import type { Mapping } from './Mapping.js'
-import type { Property } from './Properties.js'
-
-export type Directive = Mapping | Property

package/source/directives/map/Headers.ts

@@ -1,60 +0,0 @@
-import assert from 'node:assert'
-import { cors } from '../cors/index.js'
-import { Mapping } from './Mapping.js'
-import { take } from '../../Introspection.js'
-import type { Input } from '../../io.js'
-import type { Introspection } from '../../Introspection.js'
-
-/**
- * Forbidden request header names: the browser sets them itself and a script cannot
- * list them in `Access-Control-Request-Headers`, so there is nothing to advertise
- * or vary on. The value is still read, it just never reaches CORS.
- */
-const FORBIDDEN = new Set(['host', 'origin'])
-
-export class Headers extends Mapping<Record<string, string>> {
-  private readonly headers: string[]
-
-  public constructor(map: Record<string, string>) {
-    assert.ok(map.constructor === Object, '`map:headers` must be an object')
-
-    assert.ok(
-      Object.values(map).every((value) => typeof value === 'string'),
-      '`map:headers` must be an object with string values'
-    )
-
-    super(map)
-
-    this.headers = Object.values(map).filter((header) => !FORBIDDEN.has(header))
-    this.headers.forEach((header) => cors.allow(header))
-  }
-
-  /**
-   * The property is filled from a request header, so it is not the body's to send. Which
-   * header, and that there is one at all, is not answered: what an application reads off a
-   * request is its own, and a caller has nowhere to put one anyway.
-   */
-  public override explain(introspection: Introspection): void {
-    for (const property of Object.keys(this.value)) take(introspection, property)
-  }
-
-  public properties(context: Input): Record<string, string> {
-    context.pipelines.response.push((response) => {
-      response.headers ??= new global.Headers()
-
-      for (const header of this.headers) response.headers.append('vary', header)
-    })
-
-    return Object.entries(this.value).reduce(
-      (properties: Record<string, string>, [property, header]) => {
-        const value = context.request.headers[header]
-
-        if (value !== undefined)
-          properties[property] = Array.isArray(value) ? value.join(', ') : value
-
-        return properties
-      },
-      {}
-    )
-  }
-}

package/source/directives/map/Language.ts

@@ -1,45 +0,0 @@
-import assert from 'node:assert'
-import Negotiator from 'negotiator'
-import { cors } from '../cors/index.js'
-import { Mapping } from './Mapping.js'
-import { Languages } from './Languages.js'
-import type { Input } from '../../io.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Directive } from './Directive.js'
-
-export class Language extends Mapping<string> {
-  private languages: string[] | null = null
-
-  public constructor(property: string) {
-    assert.ok(typeof property === 'string', '`map:language` must be a string')
-
-    cors.allow('accept-language')
-    super(property)
-  }
-
-  public properties(
-    context: Input,
-    parameters: Parameter[],
-    directives: Directive[]
-  ): Record<string, string> {
-    this.languages ??= this.resolve(directives)
-
-    const negotiator = new Negotiator(context.request)
-    const language = negotiator.language(this.languages) ?? this.languages[0]
-
-    context.pipelines.response.push((response) => {
-      response.headers ??= new Headers()
-      response.headers.set('content-language', language)
-      response.headers.append('vary', 'accept-language')
-    })
-
-    return { [this.value]: language }
-  }
-
-  private resolve(directives: Directive[]): string[] {
-    for (const directive of directives)
-      if (directive instanceof Languages) return directive.value
-
-    throw new Error('Supported languages are not defined, add `map:languages` directive')
-  }
-}

package/source/directives/map/Languages.ts

@@ -1,17 +0,0 @@
-import assert from 'node:assert'
-import { Property } from './Properties.js'
-
-export class Languages extends Property<'languages'> {
-  public constructor(value: string[]) {
-    assert.ok(
-      Array.isArray(value) && value.length > 0,
-      '`map:languages` must be a non-empty array of strings'
-    )
-    assert.ok(
-      value.every((language) => typeof language === 'string'),
-      '`map:languages` must be an array of strings'
-    )
-
-    super('languages', value)
-  }
-}

package/source/directives/map/Map.ts

@@ -1,85 +0,0 @@
-import { match } from 'matchacho'
-import { properties, Property } from './Properties.js'
-import { Mapping } from './Mapping.js'
-import { Headers } from './Headers.js'
-import { Languages } from './Languages.js'
-import { Language } from './Language.js'
-import { Segments } from './Segments.js'
-import { Authority } from './Authority.js'
-import { BufferMapping } from './Buffer.js'
-import { Claims } from './Claims.js'
-import type { Directive } from './Directive.js'
-import type { Properties } from './Properties.js'
-import type { DirectiveFamily, Parameter } from '../../RTD/index.js'
-import type { Input, Output } from '../../io.js'
-import type { Introspection } from '../../Introspection.js'
-import type { Remotes } from '../../Remotes.js'
-
-export class Map implements DirectiveFamily {
-  public readonly name = 'map'
-  public readonly mandatory = false
-
-  private remotes!: Remotes
-
-  public create(name: string, value: unknown, remotes: Remotes): Property | Mapping {
-    this.remotes = remotes
-
-    return match(
-      name,
-      () => properties.has(name),
-      (name: PN) => new Property(name, value as PV),
-      () => name in mappings,
-      (name: keyof typeof mappings) => new mappings[name](value, remotes),
-      () => {
-        throw new Error(`Directive 'map:${name}' is not implemented`)
-      }
-    )
-  }
-
-  public explain(
-    directives: Directive[],
-    _: Input,
-    introspection: Introspection
-  ): Introspection {
-    for (const directive of directives)
-      if (directive instanceof Mapping) directive.explain(introspection)
-
-    return introspection
-  }
-
-  public async precall(
-    directives: Directive[],
-    context: Input,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    const properties = {}
-
-    for (const directive of directives)
-      if (directive instanceof Mapping)
-        Object.assign(
-          properties,
-          await directive.properties(context, parameters, directives)
-        )
-
-    context.pipelines.body.push((body: unknown) => {
-      if (body === undefined || body === null || typeof body !== 'object')
-        return properties
-      else return Object.assign(body, properties)
-    })
-
-    return null
-  }
-}
-
-type PN = keyof Properties
-type PV = Properties[PN]
-
-const mappings: Record<string, new (value: any, remotes: Remotes) => Directive> = {
-  authority: Authority,
-  buffer: BufferMapping,
-  headers: Headers,
-  languages: Languages,
-  language: Language,
-  segments: Segments,
-  claims: Claims
-}

package/source/directives/map/Mapping.ts

@@ -1,45 +0,0 @@
-import { take } from '../../Introspection.js'
-import type { Remotes } from '../../Remotes.js'
-import type { Directive } from './Directive.js'
-import type { Input } from '../../io.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-
-export abstract class Mapping<T = unknown> {
-  protected value: T
-  protected remotes?: Remotes
-
-  protected constructor(value: T, remotes?: Remotes) {
-    this.value = value
-    this.remotes = remotes
-  }
-
-  public abstract properties(
-    context: Input,
-    parameters: Parameter[],
-    directives: Directive[]
-  ): Output
-
-  /**
-   * What this mapping does to what the method says about itself, which is the reverse of
-   * what it does to a request: a property the gateway fills is taken out of the input,
-   * because it is not the caller's to send.
-   *
-   * The default says nothing more than that. A claim, an authority and a language come
-   * from the request itself and there is nowhere for a caller to put one; a header and a
-   * segment are the caller's, and those say where.
-   */
-  public explain(introspection: Introspection): void {
-    for (const property of this.names()) take(introspection, property)
-  }
-
-  /** The input properties this mapping fills, however its value names them. */
-  protected names(): string[] {
-    return typeof this.value === 'string'
-      ? [this.value]
-      : Object.keys(this.value as object)
-  }
-}
-
-type Properties = Record<string, unknown> | null
-type Output = Properties | Promise<Properties>

package/source/directives/map/Properties.ts

@@ -1,15 +0,0 @@
-export interface Properties {
-  languages: string[]
-}
-
-export class Property<K extends keyof Properties = keyof Properties> {
-  public readonly name: K
-  public readonly value: Properties[K]
-
-  public constructor(name: K, value: Properties[K]) {
-    this.name = name
-    this.value = value
-  }
-}
-
-export const properties = new Set('languages')

package/source/directives/map/Segments.ts

@@ -1,52 +0,0 @@
-import assert from 'node:assert'
-import { Mapping } from './Mapping.js'
-import { take } from '../../Introspection.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Introspection, Schema } from '../../Introspection.js'
-
-export class Segments extends Mapping<Record<string, string>> {
-  public constructor(map: Record<string, string>) {
-    assert.ok(map.constructor === Object, '`map:segments` must be an object')
-
-    assert.ok(
-      Object.values(map).every((value) => typeof value === 'string'),
-      '`map:segments ` must be an object with string values'
-    )
-
-    super(map)
-  }
-
-  /** A segment is the caller's, so it moves to the route rather than out of sight. */
-  public override explain(introspection: Introspection): void {
-    for (const property of Object.keys(this.value)) {
-      const schema = take(introspection, property)
-
-      introspection.route ??= {}
-      introspection.route[property] = schema ?? ({ type: 'string' } as unknown as Schema)
-    }
-  }
-
-  public override properties(
-    _: unknown,
-    parameters: Parameter[]
-  ): Record<string, string> {
-    return Object.entries(this.value).reduce(
-      (properties: Record<string, string>, [property, parameter]) => {
-        const cut = parameter[0] === '~'
-
-        if (cut) parameter = parameter.slice(1)
-
-        const index = parameters.findIndex(({ name }) => name === parameter)
-
-        assert.ok(index > -1, `Route parameter '${parameter}' is missing`)
-
-        properties[property] = parameters[index].value
-
-        if (cut) parameters.splice(index, 1)
-
-        return properties
-      },
-      {}
-    )
-  }
-}

package/source/directives/map/index.ts

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

package/source/directives/mcp/MCP.ts

@@ -1,33 +0,0 @@
-import assert from 'node:assert'
-import { Tool } from './Tool.js'
-import type { DirectiveFamily } from '../../RTD/index.js'
-import type { Context } from '../../HTTP/index.js'
-import type { Introspection } from '../../Introspection.js'
-
-/** The name the family is declared under, and what `MCP` asks a method for. */
-export const FAMILY = 'mcp'
-
-export class MCP implements DirectiveFamily<Tool> {
-  public readonly name = FAMILY
-  public readonly mandatory = false
-
-  /** Whether this method is published, which is what the nearest declaration says. */
-  public static published(directives: Tool[] | undefined): boolean {
-    return directives?.[0]?.published ?? false
-  }
-
-  /**
-   * Whether this method is published to a model, which is what the route declares. Whether
-   * one is served at all is the annotation's, and a route says nothing of that.
-   */
-  public explain(directives: Tool[], _: Context, introspection: Introspection): Introspection {
-    return MCP.published(directives) ? { ...introspection, mcp: true } : introspection
-  }
-
-  // eslint-disable-next-line max-params
-  public create(name: string, value: unknown, _: unknown, route: string): Tool {
-    assert.ok(name === 'tool', `Unknown directive: mcp:${name}`)
-
-    return new Tool(value, route)
-  }
-}

package/source/directives/mcp/Tool.test.ts

@@ -1,56 +0,0 @@
-import assert from 'node:assert'
-import { describe, it } from 'node:test'
-import { Tool } from './Tool.js'
-import { MCP } from './MCP.js'
-
-describe('mcp:tool', () => {
-  it('should publish a method', () => {
-    assert.strictEqual(new Tool(true, '/pots/hot').published, true)
-  })
-
-  it('should withdraw one, because a declaration is inherited', () => {
-    assert.strictEqual(new Tool(false, '/pots/hot').published, false)
-  })
-
-  it('should not accept what a tool is, which is `help:method`', () => {
-    assert.throws(() => new Tool('The pots that are hot.', '/pots'), /`help:method`/)
-    assert.throws(() => new Tool({ title: 'Hot pots' }, '/pots'), /`help:method`/)
-  })
-
-  it('should not accept a value that is not one', () => {
-    assert.throws(() => new Tool(undefined, '/pots'), /whether the method is published/)
-    assert.throws(() => new Tool(null, '/pots'), /whether the method is published/)
-  })
-
-  it('should refuse a route no name can spell', () => {
-    assert.throws(() => new Tool(true, '/pots/v1.0'), /no tool name can spell/)
-  })
-
-  it('should name the route it refuses', () => {
-    assert.throws(() => new Tool(true, '/pots/v1.0'), /'\/pots\/v1\.0'/)
-  })
-
-  it('should not ask a route it does not publish to be spellable', () => {
-    assert.strictEqual(new Tool(false, '/pots/v1.0').published, false)
-  })
-})
-
-describe('mcp:tool inheritance', () => {
-  const mcp = new MCP()
-
-  it('should take the nearest declaration', () => {
-    const nearest = new Tool(false, '/pots')
-    const further = new Tool(true, '/pots')
-
-    assert.strictEqual(MCP.published([nearest, further]), false)
-  })
-
-  it('should publish nothing where nothing is declared', () => {
-    assert.strictEqual(MCP.published(undefined), false)
-    assert.strictEqual(MCP.published([]), false)
-  })
-
-  it('should refuse a directive it does not know', () => {
-    assert.throws(() => mcp.create('tools', true, null, '/pots'), /Unknown directive/)
-  })
-})

package/source/directives/mcp/Tool.ts

@@ -1,32 +0,0 @@
-import assert from 'node:assert'
-import { refusal } from '../../RPC/names.js'
-import { segment } from '../../RTD/segment.js'
-
-/**
- * Whether one method is published to a model. Declaring it is what publishes it, and it
- * says nothing else — what a tool is, is [`help:method`](../help/Help.ts), which is what
- * describes the method to everything else as well.
- *
- * `false` withdraws one: the declaration is inherited, as every directive is, and a node
- * publishing what is under it is how a subtree is published at all.
- */
-export class Tool {
-  public readonly published: boolean
-
-  public constructor(value: unknown, route: string) {
-    assert.ok(
-      typeof value === 'boolean',
-      'Directive mcp:tool: the value is whether the method is published; what it is, is `help:method`'
-    )
-
-    // a tool is called by name, so a route that cannot be named cannot be one — said where
-    // the mistake is, rather than as a tool that is quietly never listed
-    if (value)
-      assert.ok(
-        refusal(segment(route)) === null,
-        `Directive mcp:tool: '${route}' holds a segment no tool name can spell`
-      )
-
-    this.published = value
-  }
-}

package/source/directives/mcp/index.ts

@@ -1,6 +0,0 @@
-import { MCP } from './MCP.js'
-
-export const mcp = new MCP()
-
-export { FAMILY, MCP } from './MCP.js'
-export type { Tool } from './Tool.js'