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

package/source/RPC/names.test.ts

@@ -0,0 +1,141 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import * as http from '../HTTP/index.js'
+import { segment } from '../RTD/segment.js'
+import { address, name, refusal } from './names.js'
+
+describe('address', () => {
+  it('should resolve a name without variables', () => {
+    assert.deepEqual(address('pots.GET', {}), {
+      path: '/pots/',
+      verb: 'GET',
+      variables: []
+    })
+  })
+
+  it('should resolve the trunk', () => {
+    assert.deepEqual(address('GET', {}), { path: '/', verb: 'GET', variables: [] })
+  })
+
+  it('should substitute a variable and report it taken', () => {
+    assert.deepEqual(address('pots._id.GET', { id: 'a1b2', title: 'Kettle' }), {
+      path: '/pots/a1b2/',
+      verb: 'GET',
+      variables: ['id']
+    })
+  })
+
+  it('should substitute every variable', () => {
+    assert.deepEqual(address('users._user.pots._id.PATCH', { user: 'bob', id: 'a1b2' }), {
+      path: '/users/bob/pots/a1b2/',
+      verb: 'PATCH',
+      variables: ['user', 'id']
+    })
+  })
+
+  it('should let a tail carry separators', () => {
+    assert.deepEqual(address('files.__.GET', { '**': 'a/b/c' }), {
+      path: '/files/a/b/c/',
+      verb: 'GET',
+      variables: ['**']
+    })
+  })
+
+  it('should not confuse a trailing literal with a verb', () => {
+    assert.deepEqual(address('pots.GET.POST', {}), {
+      path: '/pots/GET/',
+      verb: 'POST',
+      variables: []
+    })
+  })
+
+  it('should refuse a name that states no verb', () => {
+    assert.throws(() => address('pots._id', { id: 'a1b2' }), http.NotFound)
+  })
+
+  it('should refuse a verb no method uses', () => {
+    assert.throws(() => address('pots.FETCH', {}), http.NotFound)
+  })
+
+  it('should refuse a segment no name can spell', () => {
+    assert.throws(() => address('pots/v1.GET', {}), http.NotFound)
+    assert.throws(() => address('a_b.GET', {}), http.NotFound)
+    assert.throws(() => address('pots..GET', {}), http.NotFound)
+  })
+
+  it('should refuse a variable of no name', () => {
+    assert.throws(() => address('pots._.GET', { '': 'a1b2' }), http.NotFound)
+  })
+
+  it('should refuse a missing variable', () => {
+    assert.throws(() => address('pots._id.GET', {}), http.BadRequest)
+  })
+
+  it('should refuse a variable that would divide the path', () => {
+    assert.throws(() => address('pots._id.GET', { id: 'a/b' }), http.BadRequest)
+    assert.throws(() => address('pots._id.GET', { id: 'a?b' }), http.BadRequest)
+    assert.throws(() => address('pots._id.GET', { id: 'a#b' }), http.BadRequest)
+  })
+
+  it('should refuse a tail that would end the path', () => {
+    assert.throws(() => address('files.__.GET', { '**': 'a?b' }), http.BadRequest)
+  })
+})
+
+describe('name', () => {
+  it('should name the trunk by its verb alone', () => {
+    assert.equal(name(segment('/'), 'GET'), 'GET')
+  })
+
+  it('should name a route', () => {
+    assert.equal(name(segment('/pots'), 'GET'), 'pots.GET')
+    assert.equal(name(segment('/identity/tokens'), 'POST'), 'identity.tokens.POST')
+  })
+
+  it('should mark a variable', () => {
+    assert.equal(name(segment('/pots/:id'), 'GET'), 'pots._id.GET')
+    assert.equal(
+      name(segment('/identity/tokens/:identity'), 'POST'),
+      'identity.tokens._identity.POST'
+    )
+  })
+
+  it('should mark a tail', () => {
+    assert.equal(name(segment('/files/**'), 'GET'), 'files.__.GET')
+  })
+
+  it('should keep a hyphen', () => {
+    assert.equal(name(segment('/jpeg-or-png'), 'GET'), 'jpeg-or-png.GET')
+  })
+
+  it('should name nothing where a segment cannot be spelled', () => {
+    assert.equal(name(segment('/v1.0/pots'), 'GET'), null)
+    assert.equal(name(segment('/a_b'), 'GET'), null)
+    assert.equal(name(segment('/pots/*'), 'GET'), null)
+    assert.equal(name(segment('/messages/:sender-:recipient'), 'GET'), null)
+  })
+
+  it('should round-trip what it names', () => {
+    const named = name(segment('/pots/:id'), 'GET')!
+
+    assert.deepEqual(address(named, { id: 'a1b2' }), {
+      path: '/pots/a1b2/',
+      verb: 'GET',
+      variables: ['id']
+    })
+  })
+})
+
+describe('refusal', () => {
+  it('should name nothing where every segment can be spelled', () => {
+    assert.equal(refusal(segment('/pots/:id')), null)
+  })
+
+  it('should name the segment as it was declared', () => {
+    assert.equal(refusal(segment('/v1.0/pots')), 'v1.0')
+    assert.equal(refusal(segment('/pots/a_b')), 'a_b')
+    assert.equal(refusal(segment('/pots/*')), '*')
+    assert.equal(refusal(segment('/messages/:sender-:recipient')), ':sender-:recipient')
+  })
+})

package/source/RPC/names.ts

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

@@ -0,0 +1,34 @@
+/** 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,6 +1,6 @@
-import { type DirectiveFactory } from './Directives'
-import { type EndpointsFactory } from './Endpoint'
-import type { Directive } from './syntax'
+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
@@ -9,5 +9,8 @@ export interface Context<TExtension = any> {
     readonly factory: DirectiveFactory
     stack: Directive[]
   }
-  readonly extension?: TExtension
+
+  /** 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,33 +1,126 @@
-import type { Parameter } from './Match'
-import type * as syntax from './syntax'
-import type { Context, OutgoingMessage } from '../HTTP'
-import type { Output } from '../io'
+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 {
-  preflight: (context: Context, parameters: Parameter[]) => Promise<Output>
+  /**
+   * 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[]) => Directives
+  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
 
-  preflight?: (directives: 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,
-    parameters: Parameter[]) => Output | Promise<Output>
+    response: OutgoingMessage
+  ) => void | Promise<void>
 
-  settle?: (directives: TDirective[],
+  /**
+   * 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>
+    response: OutgoingMessage
+  ) => void | Promise<void>
+
+  dispose?: (directives: TDirective[]) => void
 }

package/source/RTD/Endpoint.ts

@@ -1,10 +1,24 @@
-import { type Context } from './Context'
-import type * as http from '../HTTP'
-import type * as syntax from './syntax'
-import type * as RTD from './index'
+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>
+  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>
 }
 

package/source/RTD/Match.ts

@@ -1,4 +1,4 @@
-import { type Node } from './Node'
+import { type Node } from './Node.js'
 
 export interface Match {
   node: Node

package/source/RTD/Method.ts

@@ -1,16 +1,37 @@
-import type { Endpoint } from './Endpoint'
-import type { Directives } from './Directives'
+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) {
+  public constructor(endpoint: Endpoint | null, directives: Directives) {
     this.endpoint = endpoint
     this.directives = directives
   }
 
-  public async close (): Promise<void> {
+  /**
+   * 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()
   }
 }