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

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 '../../const.js'
-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>

package/source/directives/io/Output.ts

@@ -1,81 +0,0 @@
-import { Stream } from 'node:stream'
-import { console } from 'openspan'
-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'
-import type { OutgoingMessage } from '../../HTTP/index.js'
-
-export class Output implements Directive {
-  /** whether the reply passes whole, which is when the schema is the operation's own */
-  public readonly disabled: boolean = false
-
-  /** what a reply may carry, which is therefore what the output schema states */
-  public readonly allowed: Set<string>
-  private readonly omitted: boolean = true
-  private readonly permissions: string[] = []
-
-  public constructor(permissions: Permissions) {
-    if (typeof permissions === 'boolean')
-      if (permissions) this.disabled = true
-      else this.omitted = false
-    else this.permissions = permissions
-
-    this.allowed = new Set(this.permissions)
-  }
-
-  public static validate(permissions: unknown): asserts permissions is Permissions {
-    schemas.output.validate(permissions, "Incorrect 'io:output' format")
-  }
-
-  public precall(context: Context): void {
-    context.pipelines.response.push(this.restriction(context))
-  }
-
-  private restriction(context: Context) {
-    return (message: OutgoingMessage): void => {
-      // what the gateway built is its own — a code and a message — and a restriction has
-      // nothing to say about it; everything else is a reply the operation returned, and is
-      // restricted whatever status it carries
-      const error = message.authentic === true
-      const stream = message.body instanceof Stream
-      const none = message.body === undefined || message.body === null
-
-      if (this.disabled || error || stream || none) return
-
-      if (typeof message.body !== 'object' || this.permissions.length === 0) {
-        if (this.omitted)
-          console.warn(
-            "Permissions for 'io:output' are not specified properly, response omitted",
-            { path: context.url.pathname }
-          )
-
-        delete message.body
-
-        return
-      }
-
-      schemas.message.validate<Message>(
-        message.body,
-        "'io:output' expects response to be an object or array of objects"
-      )
-
-      if (Array.isArray(message.body))
-        message.body = message.body.map((entity) => this.fit(entity as Message))
-      else message.body = this.fit(message.body)
-    }
-  }
-
-  /** Runs per entity of a collection, hence the set and the absence of intermediates. */
-  private fit(message: Message): Message {
-    const output: Message = {}
-
-    // the keys of the entity, so that the response keeps the order it was built in
-    for (const key of Object.keys(message))
-      if (this.allowed.has(key)) output[key] = message[key]
-
-    return output
-  }
-}
-
-export type Permissions = string[] | boolean

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

@@ -1,88 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Status } from './Status.js'
-import { Output } from './Output.js'
-import type { Input as Context } from '../../io.js'
-import type { OutgoingMessage } from '../../HTTP/index.js'
-
-const status = new Status('status')
-
-function context(): Context {
-  return {
-    pipelines: { body: [], response: [] },
-    url: { pathname: '/' }
-  } as unknown as Context
-}
-
-it('should take the status from the property and remove it', () => {
-  const response: OutgoingMessage = { body: { status: 400, error: 'invalid_request' } }
-
-  status.settle(context(), response)
-
-  assert.equal(response.status, 400)
-  assert.deepEqual(response.body, { error: 'invalid_request' })
-})
-
-it('should leave a reply that states no status alone', () => {
-  const response: OutgoingMessage = { body: { id: 'x' } }
-
-  status.settle(context(), response)
-
-  assert.equal(response.status, undefined)
-  assert.deepEqual(response.body, { id: 'x' })
-})
-
-it('should refuse a status that is not one', () => {
-  for (const value of ['400', null, {}, true])
-    assert.throws(() => {
-      status.settle(context(), { body: { status: value } } as OutgoingMessage)
-    }, /`io:status` expects 'status' to be a number/)
-})
-
-it('should refuse a declaration that is not a property name', () => {
-  for (const value of [1, null, {}, ['status']])
-    assert.throws(() => Status.validate(value), /`io:status` must be a string/)
-})
-
-it('should have a reply it named the status of restricted, whatever that status is', () => {
-  for (const stated of [200, 400]) {
-    const ctx = context()
-    const output = new Output(['code', 'error'])
-
-    output.precall(ctx, [])
-
-    const response: OutgoingMessage = {
-      body: { status: stated, code: 'SplxlO', error: 'invalid_grant', secret: 'x' }
-    }
-
-    status.settle(ctx, response)
-
-    for (const transform of ctx.pipelines.response) transform(response)
-
-    assert.equal(response.status, stated)
-    assert.deepEqual(response.body, { code: 'SplxlO', error: 'invalid_grant' })
-  }
-})
-
-it('should leave a failure the gateway built alone, on such a route too', () => {
-  const ctx = context()
-  const output = new Output(['code'])
-
-  output.precall(ctx, [])
-
-  // what `Server.fail` builds out of an exception, on a route that also declares `io:status`
-  const response: OutgoingMessage = {
-    status: 422,
-    authentic: true,
-    body: { code: 'NOT_FOUND', message: 'nope' }
-  }
-
-  for (const transform of ctx.pipelines.response) transform(response)
-
-  assert.deepEqual(
-    response.body,
-    { code: 'NOT_FOUND', message: 'nope' },
-    'a code and a message are not what a restriction has anything to say about'
-  )
-})

package/source/directives/io/Status.ts

@@ -1,47 +0,0 @@
-import assert from 'node:assert'
-import type { Directive } from './Directive.js'
-import type * as http from '../../HTTP/index.js'
-
-/**
- * The status of the reply, taken from a property of what the operation returned and removed
- * from it — an outcome the operation knows and the transport does not, like a protocol that
- * states its error as a body rather than as a status of its own.
- *
- * Settled rather than transformed, so the status is set before anything reads it. A reply of
- * 300 or above is left as the operation built it, which `io:output` does not restrict: a
- * failure and a success are different shapes, and one list of permitted properties does not
- * describe both.
- */
-export class Status implements Directive {
-  private readonly property: string
-
-  public constructor(property: unknown) {
-    this.property = property as string
-  }
-
-  public static validate(value: unknown): asserts value is string {
-    assert.ok(typeof value === 'string', '`io:status` must be a string')
-  }
-
-  public precall(): void {
-    // nothing to do until the operation has answered
-  }
-
-  public settle(_: unknown, response: http.OutgoingMessage): void {
-    const body: unknown = response.body
-
-    if (body === null || typeof body !== 'object' || !(this.property in body)) return
-
-    const value: unknown = (body as Record<string, unknown>)[this.property]
-
-    assert.ok(
-      typeof value === 'number',
-      `\`io:status\` expects '${this.property}' to be a number`
-    )
-
-    response.status = value
-
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-    delete (body as Record<string, unknown>)[this.property]
-  }
-}

package/source/directives/io/Throttle.ts

@@ -1,30 +0,0 @@
-import { TooManyRequests } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import { parse, Quotas, type Declaration, type Sync } from './lib/throttle/index.js'
-import type * as http from '../../HTTP/index.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Directive } from './Directive.js'
-
-export class Throttle implements Directive {
-  private readonly quotas: Quotas
-
-  public constructor(declaration: Declaration, sync: Sync, route: string) {
-    this.quotas = Quotas.create(parse(declaration), route)
-
-    sync.register(this.quotas)
-  }
-
-  public static validate(declaration: unknown): asserts declaration is Declaration {
-    schemas.throttle.validate(declaration, "Incorrect 'io:throttle' format")
-  }
-
-  public precall(context: http.Context, parameters: Parameter[]): void {
-    const retry = this.quotas.check(context, parameters)
-
-    if (retry > 0) throw new TooManyRequests(retry)
-  }
-
-  public settle(context: http.Context, output: http.OutgoingMessage): void {
-    this.quotas.use(context, output)
-  }
-}

package/source/directives/io/index.ts

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

package/source/directives/io/lib/throttle/Configuration.test.ts

@@ -1,72 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { parse, type Configuration } from './Configuration.js'
-
-const rest: Omit<Configuration, 'key' | 'condition'> = {
-  interval: 1,
-  requests: 1
-}
-
-it('should convert key', () => {
-  const result: Partial<Configuration> = {
-    key: [
-      {
-        method: 'ip'
-      }
-    ]
-  }
-
-  assert.partialDeepStrictEqual(parse({ key: 'ip', ...rest }), result)
-  assert.partialDeepStrictEqual(parse({ key: ['ip'], ...rest }), result)
-})
-
-it('should convert condition', () => {
-  assert.partialDeepStrictEqual(
-    parse({ key: ['ip', 'path'], condition: { status: '404' }, ...rest }),
-    {
-      condition: [
-        {
-          method: 'status',
-          options: '404'
-        }
-      ]
-    }
-  )
-
-  assert.partialDeepStrictEqual(
-    parse({ key: 'ip', condition: { status: '404' }, ...rest }),
-    {
-      condition: [
-        {
-          method: 'status',
-          options: '404'
-        }
-      ]
-    }
-  )
-})
-
-it('should convert a key component that takes an argument', () => {
-  assert.partialDeepStrictEqual(parse({ key: { segment: 'id' }, ...rest }), {
-    key: [
-      {
-        method: 'segment',
-        options: 'id'
-      }
-    ]
-  })
-})
-
-it('should convert a mixed key', () => {
-  assert.partialDeepStrictEqual(
-    parse({ key: ['route', { segment: 'id' }, 'identity'], ...rest }),
-    {
-      key: [
-        { method: 'route' },
-        { method: 'segment', options: 'id' },
-        { method: 'identity' }
-      ]
-    }
-  )
-})