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

package/source/RPC/names.ts

@@ -1,176 +0,0 @@
-import * as http from '../HTTP/index.js'
-import { verbs } from '../RTD/syntax/index.js'
-import type { Segment } from '../RTD/segment.js'
-import { QUERY, type Params } from './types.js'
-
-/**
- * What a name resolves to: the path the call is made at, and the verb it is made with.
- *
- * A name is the route template with its variables marked and the verb appended as a segment
- * of its own — `pots._id.GET`. The revision names the characters a tool's name may hold, and
- * `/` is not among them, so segments are joined by `.` — which a segment cannot hold either,
- * so nothing in a name can be mistaken for anything else, and the verb is always last.
- */
-export interface Address {
-  path: string
-  verb: string
-
-  /** the `params` the path took, which are therefore not the operation's input */
-  variables: string[]
-}
-
-export function address(method: string, params: Params): Address {
-  const parts = method.split(SEPARATOR)
-  const verb = parts.pop()!
-
-  if (!verbs.has(verb)) throw new http.NotFound(`'${method}' names no method`)
-
-  const variables: string[] = []
-  const fragments: string[] = []
-
-  for (const part of parts) {
-    const key = parameter(part)
-
-    if (key === null) {
-      fragments.push(literal(part, method))
-
-      continue
-    }
-
-    if (part !== TAIL && !NAMEABLE.test(key))
-      throw new http.NotFound(`'${method}' names no procedure`)
-
-    const value = params[key]
-
-    if (value === undefined || value === null)
-      throw new http.BadRequest(`'${method}' requires the parameter '${key}'`)
-
-    const fragment = String(value)
-
-    // `__` stands for the rest of the path and may carry separators; a variable is one segment
-    if (!(part === TAIL ? TAILED : OPAQUE).test(fragment))
-      throw new http.BadRequest(`The parameter '${key}' cannot be a path of its own`)
-
-    variables.push(key)
-    fragments.push(fragment)
-  }
-
-  // a route is matched with its trailing slash, and the trunk is the bare one
-  const path = fragments.length === 0 ? '/' : `/${fragments.join('/')}/`
-
-  return { path, verb, variables }
-}
-
-/**
- * What the call carries, as a request carries it: the path took its variables, `query` is
- * the querystring, and the rest is the body.
- */
-export function split(
-  params: Params,
-  variables: string[]
-): { query?: Params; input?: Params } {
-  const input: Params = {}
-  let query: Params | undefined
-
-  for (const [key, value] of Object.entries(params)) {
-    if (variables.includes(key)) continue
-
-    if (key !== QUERY) {
-      input[key] = value
-
-      continue
-    }
-
-    if (typeof value !== 'object' || value === null || Array.isArray(value))
-      throw new http.BadRequest(`'${QUERY}' must be an object`)
-
-    query = value as Params
-  }
-
-  // an absent body is what a request without one has, and the mapping fills it as it does
-  return { query, input: Object.keys(input).length === 0 ? undefined : input }
-}
-
-/** The parameter a part reads, or nothing where the part is a literal segment. */
-function parameter(part: string): string | null {
-  if (part === TAIL) return WILDCARD
-
-  return part[0] === VARIABLE ? part.slice(1) : null
-}
-
-/** A segment a name cannot spell is a segment no name has, so this one names nothing. */
-function literal(part: string, method: string): string {
-  if (!NAMEABLE.test(part)) throw new http.NotFound(`'${method}' names no procedure`)
-
-  return part
-}
-
-/** The name of a method on this route, or nothing where the route has none. */
-export function name(segments: Segment[], verb: string): string | null {
-  const parts: string[] = []
-
-  for (const segment of segments) {
-    const part = component(segment)
-
-    if (part === null) return null
-
-    parts.push(part)
-  }
-
-  parts.push(verb)
-
-  return parts.join(SEPARATOR)
-}
-
-/** The segment that leaves a route unnameable, as it was declared, or nothing where none does. */
-export function refusal(segments: Segment[]): string | null {
-  for (const segment of segments)
-    if (component(segment) === null) return declared(segment)
-
-  return null
-}
-
-function component(segment: Segment): string | null {
-  if (segment.fragment !== null)
-    return NAMEABLE.test(segment.fragment) ? segment.fragment : null
-
-  if (segment.wildcard === true) return TAIL
-
-  // it stands for a segment the caller cannot name, so there is nothing to substitute
-  if (segment.placeholder === null) return null
-
-  return NAMEABLE.test(segment.placeholder) ? VARIABLE + segment.placeholder : null
-}
-
-/** The route as it was declared, which is how a message about it should read. */
-export function template(segments: Segment[]): string {
-  return '/' + segments.map(declared).join('/')
-}
-
-function declared(segment: Segment): string {
-  if (segment.fragment !== null) return segment.fragment
-
-  if (segment.wildcard === true) return '**'
-
-  return segment.placeholder === null ? '*' : ':' + segment.placeholder
-}
-
-const SEPARATOR = '.'
-const VARIABLE = '_'
-const TAIL = '__'
-
-/** How the RTD names the rest of a path, wherever a parameter of it is read. */
-const WILDCARD = '**'
-
-/**
- * What a segment may hold to have a name. `_` is the convention's own, and every other
- * character a client leaves alone is here: a client shows a model the name with the rest
- * turned into `_`, and two names must not become one.
- */
-const NAMEABLE = /^[A-Za-z0-9-]+$/
-
-/** A segment ends at what divides or ends a path. */
-const OPAQUE = /^[^/?#]*$/
-
-/** A tail is several segments, so it keeps the divider and loses only what ends a path. */
-const TAILED = /^[^?#]*$/

package/source/RPC/types.ts

@@ -1,34 +0,0 @@
-/** The version every call and every response states. */
-export const VERSION = '2.0'
-
-/**
- * The member `params` reserves for what a querystring would carry. An operation's input is
- * free to have an `id` or a `limit` of its own, so the two cannot share one object.
- */
-export const QUERY = 'query'
-
-export type Params = Record<string, unknown>
-
-export interface Call {
-  jsonrpc: string
-  method: string
-  params?: Params
-
-  /** Absent makes this a notification: it runs, and nothing is returned for it. */
-  id?: string | number
-}
-
-export interface Response {
-  jsonrpc: string
-
-  /** `null` where the request was not readable enough to carry one. */
-  id: string | number | null
-  result?: unknown
-  error?: Failure
-}
-
-export interface Failure {
-  code: number
-  message: string
-  data?: unknown
-}

package/source/RTD/Context.ts

@@ -1,16 +0,0 @@
-import { type DirectiveFactory } from './Directives.js'
-import { type EndpointsFactory } from './Endpoint.js'
-import type { Directive } from './syntax/index.js'
-
-export interface Context<TExtension = any> {
-  readonly protected: boolean
-  readonly endpoints: EndpointsFactory
-  readonly directives: {
-    readonly factory: DirectiveFactory
-    stack: Directive[]
-  }
-
-  /** The route being built, accumulated on the way down and restored on the way up. */
-  path: string
-  readonly extension: TExtension
-}

package/source/RTD/Directives.ts

@@ -1,126 +0,0 @@
-import type { Parameter } from './Match.js'
-import type * as syntax from './syntax/index.js'
-import type { Context, OutgoingMessage, Options } from '../HTTP/index.js'
-import type { Output } from '../io.js'
-import type { Introspection } from '../Introspection.js'
-import type { extensions } from '@toa.io/core/types'
-
-type Host = extensions.Host
-
-export interface Directives {
-  /**
-   * The directives of one family on this method, or nothing where it declares none of it.
-   * For a consumer of a declaration rather than of a stage: what a method is published as
-   * is stated on the route, and read where the publishing happens.
-   */
-  declared: <T>(family: string) => T[] | undefined
-
-  precall: (context: Context, parameters: Parameter[]) => Promise<Output>
-
-  /** What this route's directives make of what its method says about itself. */
-  explain: (
-    context: Context,
-    introspection: Introspection
-  ) => Promise<Introspection | null>
-  settle: (context: Context, response: OutgoingMessage) => Promise<void>
-  dispose: () => void
-}
-
-export interface DirectiveFactory {
-  create: (directives: syntax.Directive[], route: string) => Directives
-
-  /** Whether this declaration is carried into the nodes below the one it is on. */
-  inheritable: (directive: syntax.Directive) => boolean
-
-  /** Runs every family's `preflight`, which is request-scoped and needs no node. */
-  preflight: (context: Context) => Promise<void>
-
-  /** Runs every family's `depart`, the counterpart of `preflight`. */
-  depart: (context: Context, response: OutgoingMessage) => Promise<void>
-
-  dispose: () => void
-}
-
-export interface DirectiveSet {
-  family: DirectiveFamily
-  directives: any[]
-
-  /** qualified directive names, e.g. `auth:id` */
-  names?: string[]
-}
-
-export interface DirectiveFamily<TDirective = any, TExtension = any> {
-  readonly name: string
-  readonly mandatory: boolean
-
-  /**
-   * Whether a declaration applies to everything below the node it is on, as every directive
-   * does unless it says otherwise. A family that describes what one node *is* sets this
-   * `false`: inherited, it would say the same thing of every resource under it.
-   */
-  readonly inherited?: boolean
-
-  create: (name: string, ...rest: any[]) => TDirective
-
-  /**
-   * Called once per gateway with what the host provides and how the gateway is configured,
-   * before any directive is created.
-   */
-  mount?: (host: Host, options: Options) => void
-
-  /**
-   * Puts the directives of one route in the order they must run in. Called once, when
-   * the set is built — the order cannot depend on the request.
-   */
-  arrange?: (directives: TDirective[]) => void
-
-  /**
-   * Request-scoped, before anything is routed. It takes no directives: no node is known
-   * yet, and a request that carries several calls has no single node at all. What a
-   * directive declares is call-scoped by definition, so only what a family does on its
-   * own behalf — authenticating a credential — belongs here. It answers nothing: a stage
-   * that runs before a route is known has no reply to make, and refuses by throwing.
-   */
-  preflight?: (request: Context & TExtension) => void | Promise<void>
-
-  /** Call-scoped, with what the node declares. Runs once per call. */
-  precall?: (
-    directives: TDirective[],
-    request: Context & TExtension,
-    parameters: Parameter[]
-  ) => Output | Promise<Output>
-
-  /**
-   * What this family's directives make of what the method says about itself, which is
-   * what `OPTIONS` answers and what a tool is described by. `null` refuses: the method
-   * is not reachable by this caller, and is not described at all.
-   *
-   * There is no request here — no route variable has a value and no body has arrived, which
-   * is why no parameters are passed — so a directive that can only tell from one hands back
-   * what it was given.
-   */
-  explain?: (
-    directives: TDirective[],
-    request: Context & TExtension,
-    introspection: Introspection
-  ) => Introspection | null | Promise<Introspection | null>
-
-  /** Call-scoped, on the message that call produced. */
-  settle?: (
-    directives: TDirective[],
-    request: Context & TExtension,
-    response: OutgoingMessage
-  ) => void | Promise<void>
-
-  /**
-   * Request-scoped, on the message going back — the counterpart of `preflight`, and
-   * likewise without directives. A reply the whole request carries, such as a re-issued
-   * credential, is written here rather than by a call that would not own it.
-   */
-  depart?: (
-    request: Context & TExtension,
-    response: OutgoingMessage
-  ) => void | Promise<void>
-
-  dispose?: (directives: TDirective[]) => void
-}

package/source/RTD/Endpoint.ts

@@ -1,27 +0,0 @@
-import { type Context } from './Context.js'
-import type * as http from '../HTTP/index.js'
-import type * as syntax from './syntax/index.js'
-import type * as RTD from './index.js'
-import type { Introspection, Schema } from '../Introspection.js'
-
-export interface Endpoint {
-  call: (
-    context: http.Context,
-    parameters: RTD.Parameter[]
-  ) => Promise<http.OutgoingMessage>
-
-  explain: (parameters: RTD.Parameter[]) => Promise<Introspection>
-
-  /**
-   * What picks the records a call is about — `criteria`, `sort` and the rest. Not part of
-   * what the resource says about itself: it is the same of every queryable one. A
-   * procedure carries it, because there it is something the caller sends.
-   */
-  selection: () => Record<string, Schema> | null
-
-  close: () => Promise<void>
-}
-
-export interface EndpointsFactory {
-  create: (method: syntax.Method, context: Context) => Endpoint
-}

package/source/RTD/Match.ts

@@ -1,11 +0,0 @@
-import { type Node } from './Node.js'
-
-export interface Match {
-  node: Node
-  parameters: Parameter[]
-}
-
-export interface Parameter {
-  name: string
-  value: string
-}

package/source/RTD/Method.ts

@@ -1,39 +0,0 @@
-import type { Parameter } from './Match.js'
-import type { Endpoint } from './Endpoint.js'
-import type { Directives } from './Directives.js'
-import type { Context } from '../HTTP/index.js'
-import { order } from '../Introspection.js'
-import type { Introspection } from '../Introspection.js'
-
-export class Method {
-  public readonly endpoint: Endpoint | null
-  public readonly directives: Directives
-
-  public constructor(endpoint: Endpoint | null, directives: Directives) {
-    this.endpoint = endpoint
-    this.directives = directives
-  }
-
-  /**
-   * What this method says about itself, as its directives leave it, or nothing where they
-   * refuse this caller. A method of no endpoint — one a directive answers on its own —
-   * states nothing of its own, and its directives still have their say.
-   */
-  public async explain(
-    context: Context,
-    parameters: Parameter[]
-  ): Promise<Introspection | null> {
-    const introspection =
-      this.endpoint === null ? {} : await this.endpoint.explain(parameters)
-
-    const described = await this.directives.explain(context, introspection)
-
-    return described === null ? null : order(described)
-  }
-
-  public async close(): Promise<void> {
-    await this.endpoint?.close()
-  }
-}
-
-export type Methods = Record<string, Method>

package/source/RTD/Node.ts

@@ -1,169 +0,0 @@
-import { type Route } from './Route.js'
-import { type Method, type Methods } from './Method.js'
-import { type Match, type Parameter } from './Match.js'
-import type { Segment } from './segment.js'
-import type { Context } from '../HTTP/index.js'
-import { guarded, resource, type Described } from '../directives/help/index.js'
-import type { Introspection } from '../Introspection.js'
-
-export class Node {
-  public intermediate: boolean
-  public forward: string | null
-  public expiration: number
-  public methods: Methods
-  private readonly protected: boolean
-  private routes: Route[]
-
-  public constructor(routes: Route[], methods: Methods, properties: Properties) {
-    this.routes = routes
-    this.methods = methods
-    this.protected = properties.protected
-    this.forward = properties.forward ?? null
-    this.expiration = properties.expiration ?? Infinity
-    this.intermediate = this.routes.findIndex((route) => route.root) !== -1
-
-    this.sort()
-  }
-
-  public match(fragments: string[], parameters: Parameter[] = []): Match | null {
-    // a route only pushes, so what a failed one added is cut off rather than the array copied
-    const mark = parameters.length
-
-    for (const route of this.routes) {
-      const match = route.match(fragments, parameters)
-
-      if (match !== null) return match
-
-      parameters.length = mark
-    }
-
-    return null
-  }
-
-  /**
-   * Returns the nodes the merged branch has landed on, so that its expiration
-   * can later be extended without rebuilding anything.
-   */
-  public merge(node: Node): Node[] {
-    this.intermediate = node.intermediate
-
-    const nodes = this.protected ? this.append(node) : this.replace(node)
-
-    this.sort()
-
-    return nodes
-  }
-
-  public touch(expiration: number): void {
-    if (!this.protected) this.expiration = expiration
-  }
-
-  /**
-   * Every method under this node, with the template it answers at.
-   *
-   * An intermediate node is skipped: it is never what a path matches, because its `/` route
-   * answers at the same place and is reached instead. The trunk is the exception `match`
-   * makes for it — `'/'` answers the trunk itself, whatever it holds.
-   */
-  public *walk(segments: Segment[], trunk = false): Generator<Mount> {
-    if (trunk || !this.intermediate)
-      for (const [verb, method] of Object.entries(this.methods))
-        yield { segments, verb, method }
-
-    for (const route of this.routes) yield* route.walk(segments)
-  }
-
-  /**
-   * What this resource is, and every method of it this caller may reach, in the order they
-   * were declared. The two are answered apart because only the methods are `Allow`.
-   */
-  public async explain(context: Context, parameters: Parameter[]): Promise<Explained> {
-    const entries = Object.entries(this.methods)
-
-    const explained = await Promise.all(
-      entries.map(async ([, method]) => await method.explain(context, parameters))
-    )
-
-    const methods: Record<string, Introspection> = {}
-
-    for (let i = 0; i < entries.length; i++)
-      if (explained[i] !== null) methods[entries[i][0]] = explained[i]!
-
-    // every method of a node carries the same declaration, so the first that is there says it
-    const stated = entries.length === 0 ? null : resource(entries[0][1].directives)
-    const described = { ...stated, ...guarded(methods) }
-
-    return {
-      described: Object.keys(described).length === 0 ? null : described,
-      methods
-    }
-  }
-
-  private replace(node: Node): Node[] {
-    const methods = Object.values(this.methods)
-
-    this.routes = node.routes
-    this.methods = node.methods
-    this.expiration = node.expiration
-    this.forward = node.forward
-
-    // race condition is really unlikely
-    for (const method of methods) void method.close()
-
-    return this.nodes()
-  }
-
-  private append(node: Node): Node[] {
-    const nodes: Node[] = []
-
-    for (const route of node.routes) nodes.push(...this.route(route))
-
-    for (const [verb, method] of Object.entries(node.methods)) this.methods[verb] = method
-
-    return nodes
-  }
-
-  private route(candidate: Route): Node[] {
-    for (const route of this.routes)
-      if (candidate.equals(route)) return route.merge(candidate)
-
-    this.routes.push(candidate)
-
-    return candidate.node.nodes()
-  }
-
-  private nodes(): Node[] {
-    const nodes: Node[] = [this]
-
-    for (const route of this.routes) nodes.push(...route.node.nodes())
-
-    return nodes
-  }
-
-  private sort(): void {
-    this.routes.sort((a, b) => {
-      return a.variables === b.variables
-        ? b.segments.length - a.segments.length // routes with more segments should be matched first
-        : a.variables - b.variables // routes with more variables should be matched last
-    })
-  }
-}
-
-/** What a resource says of itself, and what it serves. */
-export interface Explained {
-  described: Described | null
-  methods: Record<string, Introspection>
-}
-
-/** A method, and the route template it is reached by. */
-export interface Mount {
-  segments: Segment[]
-  verb: string
-  method: Method
-}
-
-export interface Properties {
-  protected: boolean
-  forward?: string
-  expiration?: number
-}

package/source/RTD/Route.ts

@@ -1,93 +0,0 @@
-import { type Segment } from './segment.js'
-import { type Match, type Parameter } from './Match.js'
-import type { Mount, Node } from './Node.js'
-
-export class Route {
-  public readonly root: boolean
-  public readonly variables: number = 0
-  public readonly segments: Segment[]
-  public readonly node: Node
-  private readonly wildcard: boolean = false
-
-  public constructor(segments: Segment[], node: Node) {
-    this.root = segments.length === 0
-    this.segments = segments
-    this.node = node
-
-    for (const segment of segments)
-      if (segment.fragment === null) {
-        this.variables++
-        this.wildcard ||= segment.wildcard === true
-      }
-  }
-
-  public match(fragments: string[], parameters: Parameter[]): Match | null {
-    if (Date.now() >= this.node.expiration) return null
-
-    for (let i = 0; i < this.segments.length; i++) {
-      const segment = this.segments[i]
-
-      if (segment.fragment !== null && segment.fragment !== fragments[i]) return null
-
-      if (segment.fragment === null && segment.placeholder !== null)
-        parameters.push({ name: segment.placeholder, value: decode(fragments[i]) })
-
-      if (segment.fragment === null && segment.wildcard === true)
-        parameters.push({
-          name: '**',
-          value: fragments
-            .slice(this.segments.length - 1)
-            .map(decode)
-            .join('/')
-        })
-    }
-
-    const exact = this.segments.length === fragments.length
-
-    if ((exact && !this.node.intermediate) || this.wildcard)
-      return { node: this.node, parameters }
-    else return this.matchNested(fragments, parameters)
-  }
-
-  public *walk(prefix: Segment[]): Generator<Mount> {
-    // an expired branch is not matched, so nothing under it is reachable to name
-    if (Date.now() >= this.node.expiration) return
-
-    yield* this.node.walk(prefix.concat(this.segments))
-  }
-
-  public equals(route: Route): boolean {
-    if (route.segments.length !== this.segments.length) return false
-
-    for (let i = 0; i < this.segments.length; i++)
-      if (this.segments[i].fragment !== route.segments[i].fragment) return false
-
-    return true
-  }
-
-  public merge(route: Route): Node[] {
-    return this.node.merge(route.node)
-  }
-
-  private matchNested(fragments: string[], parameters: Parameter[]): Match | null {
-    fragments = fragments.slice(this.segments.length)
-
-    return this.node.match(fragments, parameters)
-  }
-}
-
-/**
- * What the segment says, rather than how it was written: a value is percent-encoded to
- * survive the path, and an operation reads what a caller meant — a `client_id` that is a
- * URL arrives as one. A literal segment is matched as written, which is how it is declared.
- *
- * An escape that decodes to nothing valid is left as it stands; refusing the route over it
- * would answer `404` to a request whose only fault is its spelling.
- */
-function decode(fragment: string): string {
-  try {
-    return decodeURIComponent(fragment)
-  } catch {
-    return fragment
-  }
-}