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

package/source/directives/dev/Development.ts

@@ -1,41 +0,0 @@
-import { Stub } from './Stub.js'
-import { Throw } from './Throw.js'
-import { Sleep } from './Sleep.js'
-import { Faulty } from './Faulty.js'
-import { type Directive } from './types.js'
-import type { Input, Output } from '../../io.js'
-import type { DirectiveFamily } from '../../RTD/index.js'
-
-export class Development implements DirectiveFamily<Directive> {
-  public readonly name: string = 'dev'
-  public readonly mandatory: boolean = false
-
-  public create(name: string, value: unknown): Directive {
-    const Class = constructors[name]
-
-    if (Class === undefined) throw new Error(`Directive 'dev:${name}' is not implemented`)
-
-    return new Class(value)
-  }
-
-  public async precall(directives: Directive[], input: Input): Promise<Output> {
-    let output = null
-
-    for (const directive of directives) {
-      const out = await directive.apply(input)
-
-      if (out !== null)
-        if (output !== null) throw new Error('`dev` directives ambiguous output')
-        else output = out
-    }
-
-    return output
-  }
-}
-
-const constructors: Record<string, new (value: any) => Directive> = {
-  stub: Stub,
-  throw: Throw,
-  sleep: Sleep,
-  faulty: Faulty
-}

package/source/directives/dev/Faulty.ts

@@ -1,31 +0,0 @@
-import assert from 'node:assert'
-import { ServiceUnavailable } from '../../HTTP/index.js'
-import { cors } from '../cors/index.js'
-import type { Output } from '../../io.js'
-import type { Directive } from './types.js'
-
-export class Faulty implements Directive {
-  private static readonly warned = false
-  private readonly probability: number
-
-  public constructor(probability: number) {
-    assert.ok(
-      typeof probability === 'number',
-      '`dev:faulty` directive value must be a number'
-    )
-    assert.ok(
-      probability > 0 && probability <= 1,
-      '`dev:faulty` directive value must be in the range (0, 1]'
-    )
-
-    this.probability = probability
-
-    cors.allow('faulty')
-  }
-
-  public async apply(): Promise<Output> {
-    if (Math.random() > this.probability) return null
-
-    throw new ServiceUnavailable()
-  }
-}

package/source/directives/dev/Sleep.ts

@@ -1,53 +0,0 @@
-import assert from 'node:assert'
-import { setTimeout } from 'node:timers/promises'
-import { console } from 'openspan'
-import { cors } from '../cors/index.js'
-import { BadRequest } from '../../HTTP/index.js'
-import type { Directive } from './types.js'
-import type { Input, Output } from '../../io.js'
-
-export class Sleep implements Directive {
-  private static warned = false
-  private readonly maximum: number
-
-  public constructor(value: number) {
-    assert.ok(Number.isInteger(value), '`dev:sleep` directive value must be an integer')
-
-    if (!Sleep.warned) {
-      console.warn('Sleep directive is enabled', { maximum: value })
-      Sleep.warned = true
-    }
-
-    cors.allow('sleep')
-    this.maximum = value
-  }
-
-  public async apply(input: Input): Promise<Output> {
-    const value = input.request.headers.sleep as string | undefined
-
-    if (value === undefined) return null
-
-    const [min, max] = this.parse(value)
-
-    if (min < 0 || max < 0 || min > max || max > this.maximum)
-      throw new BadRequest('Invalid sleep duration')
-
-    const duration = Math.floor(Math.random() * (max - min)) + min
-
-    await setTimeout(duration)
-
-    return null
-  }
-
-  private parse(value: string): [number, number] {
-    try {
-      const pair = JSON.parse(value) as [number, number]
-
-      if (!Array.isArray(pair) || pair.length !== 2) throw new Error()
-
-      return pair
-    } catch {
-      throw new BadRequest('Invalid sleep duration value')
-    }
-  }
-}

package/source/directives/dev/Stub.ts

@@ -1,14 +0,0 @@
-import type { Output } from '../../io.js'
-import type { Directive } from './types.js'
-
-export class Stub implements Directive {
-  private readonly value: unknown
-
-  public constructor(value: unknown) {
-    this.value = value
-  }
-
-  public apply(): Output {
-    return { body: this.value }
-  }
-}

package/source/directives/dev/Throw.ts

@@ -1,14 +0,0 @@
-import type { Output } from '../../io.js'
-import type { Directive } from './types.js'
-
-export class Throw implements Directive {
-  private readonly message: string
-
-  public constructor(message: string) {
-    this.message = message
-  }
-
-  public apply(): Output {
-    throw new Error(this.message)
-  }
-}

package/source/directives/dev/index.ts

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

package/source/directives/dev/types.ts

@@ -1,5 +0,0 @@
-import type { Input, Output } from '../../io.js'
-
-export interface Directive {
-  apply: (input: Input) => Promise<Output> | Output
-}

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 }