@toa.io/extensions.exposition 1.0.0-alpha.285 → 1.0.0-alpha.286

package/source/RPC/errors.test.ts

@@ -3,18 +3,27 @@ import assert from 'node:assert/strict'
 
 import * as http from '../HTTP/index.js'
 import {
-  FORBIDDEN, INTERNAL, INVALID_PARAMS, METHOD_NOT_FOUND, REFUSED, of
+  FORBIDDEN,
+  INTERNAL,
+  INVALID_PARAMS,
+  METHOD_NOT_FOUND,
+  REFUSED,
+  of
 } from './errors.js'
 
 describe('of', () => {
   it('should read a missing route as a missing method', () => {
-    assert.deepEqual(of(new http.NotFound('pots/_id/FETCH names no method')),
-      { code: METHOD_NOT_FOUND, message: 'pots/_id/FETCH names no method' })
+    assert.deepEqual(of(new http.NotFound('pots/_id/FETCH names no method')), {
+      code: METHOD_NOT_FOUND,
+      message: 'pots/_id/FETCH names no method'
+    })
   })
 
   it('should read a verb the node does not declare as a missing method', () => {
-    assert.deepEqual(of(new http.MethodNotAllowed()),
-      { code: METHOD_NOT_FOUND, message: 'Method not found' })
+    assert.deepEqual(of(new http.MethodNotAllowed()), {
+      code: METHOD_NOT_FOUND,
+      message: 'Method not found'
+    })
   })
 
   it('should read a refused authorization as forbidden', () => {
@@ -22,31 +31,47 @@ describe('of', () => {
   })
 
   it('should read a bad request as invalid params', () => {
-    assert.deepEqual(of(new http.BadRequest('Query limit must be between 1 and 100')),
-      { code: INVALID_PARAMS, message: 'Query limit must be between 1 and 100' })
+    assert.deepEqual(of(new http.BadRequest('Query limit must be between 1 and 100')), {
+      code: INVALID_PARAMS,
+      message: 'Query limit must be between 1 and 100'
+    })
   })
 
   it('should carry the code an operation refused with', () => {
-    const error = Object.assign(new Error(), { code: 'WONT_CREATE', message: 'Volume is out of range' })
+    const error = Object.assign(new Error(), {
+      code: 'WONT_CREATE',
+      message: 'Volume is out of range'
+    })
 
-    assert.deepEqual(of(new http.UnprocessableEntity(error)),
-      { code: REFUSED, message: 'Volume is out of range', data: { code: 'WONT_CREATE' } })
+    assert.deepEqual(of(new http.UnprocessableEntity(error)), {
+      code: REFUSED,
+      message: 'Volume is out of range',
+      data: { code: 'WONT_CREATE' }
+    })
   })
 
   it('should stand the code in for a message the operation did not declare', () => {
     const error = Object.assign(new Error(), { code: 'WONT_CREATE' })
 
-    assert.deepEqual(of(new http.UnprocessableEntity(error)),
-      { code: REFUSED, message: 'WONT_CREATE', data: { code: 'WONT_CREATE' } })
+    assert.deepEqual(of(new http.UnprocessableEntity(error)), {
+      code: REFUSED,
+      message: 'WONT_CREATE',
+      data: { code: 'WONT_CREATE' }
+    })
   })
 
   it('should say what any other client error was refused with', () => {
-    assert.deepEqual(of(new http.Conflict()),
-      { code: REFUSED, message: 'Refused', data: { status: 409 } })
+    assert.deepEqual(of(new http.Conflict()), {
+      code: REFUSED,
+      message: 'Refused',
+      data: { status: 409 }
+    })
   })
 
   it('should say nothing of what it did not mean to answer', () => {
-    assert.deepEqual(of(new Error('the connection dropped')),
-      { code: INTERNAL, message: 'Internal error' })
+    assert.deepEqual(of(new Error('the connection dropped')), {
+      code: INTERNAL,
+      message: 'Internal error'
+    })
   })
 })

package/source/RPC/errors.ts

@@ -20,16 +20,15 @@ export const FORBIDDEN = -32000
 export const REFUSED = -32001
 export const BATCH_TOO_LARGE = -32002
 
-export function failure (code: number, message: string, data?: unknown): Failure {
+export function failure(code: number, message: string, data?: unknown): Failure {
   const value: Failure = { code, message }
 
-  if (data !== undefined)
-    value.data = data
+  if (data !== undefined) value.data = data
 
   return value
 }
 
-export function response (id: string | number | null, error: Failure): Response {
+export function response(id: string | number | null, error: Failure): Response {
   return { jsonrpc: VERSION, id, error }
 }
 
@@ -39,9 +38,8 @@ export function response (id: string | number | null, error: Failure): Response
  * The readable text is `body`, never `message`: `http.Exception` calls `super()` with no
  * argument, so every one of them carries an empty `message`.
  */
-export function of (exception: unknown): Failure {
-  if (exception instanceof http.UnprocessableEntity)
-    return refusal(exception)
+export function of(exception: unknown): Failure {
+  if (exception instanceof http.UnprocessableEntity) return refusal(exception)
 
   if (exception instanceof http.NotFound || exception instanceof http.MethodNotAllowed)
     return failure(METHOD_NOT_FOUND, text(exception, 'Method not found'))
@@ -64,19 +62,20 @@ export function of (exception: unknown): Failure {
  * reply contract states `{ code, message? }` — the message optional. The number says the
  * operation refused; `data.code` says what it refused with, and is what a caller branches on.
  */
-function refusal (exception: http.UnprocessableEntity): Failure {
+function refusal(exception: http.UnprocessableEntity): Failure {
   const body = exception.body
 
   if (typeof body !== 'object' || body === null || typeof body.code !== 'string')
     return failure(REFUSED, text(exception, 'Refused'))
 
   const code = body.code as string
-  const message = typeof body.message === 'string' && body.message !== '' ? body.message : code
+  const message =
+    typeof body.message === 'string' && body.message !== '' ? body.message : code
 
   return failure(REFUSED, message, { code })
 }
 
-function text (exception: http.Exception, fallback: string): string {
+function text(exception: http.Exception, fallback: string): string {
   return typeof exception.body === 'string' && exception.body !== ''
     ? exception.body
     : fallback

package/source/RPC/names.test.ts

@@ -7,33 +7,47 @@ 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: [] })
+    assert.deepEqual(address('pots.GET', {}), {
+      path: '/pots/',
+      verb: 'GET',
+      variables: []
+    })
   })
 
   it('should resolve the trunk', () => {
-    assert.deepEqual(address('GET', {}),
-      { path: '/', verb: 'GET', variables: [] })
+    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'] })
+    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'] })
+    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: ['**'] })
+    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: [] })
+    assert.deepEqual(address('pots.GET.POST', {}), {
+      path: '/pots/GET/',
+      verb: 'POST',
+      variables: []
+    })
   })
 
   it('should refuse a name that states no verb', () => {
@@ -81,8 +95,10 @@ describe('name', () => {
 
   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')
+    assert.equal(
+      name(segment('/identity/tokens/:identity'), 'POST'),
+      'identity.tokens._identity.POST'
+    )
   })
 
   it('should mark a tail', () => {
@@ -103,8 +119,11 @@ describe('name', () => {
   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'] })
+    assert.deepEqual(address(named, { id: 'a1b2' }), {
+      path: '/pots/a1b2/',
+      verb: 'GET',
+      variables: ['id']
+    })
   })
 })
 

package/source/RPC/names.ts

@@ -19,12 +19,11 @@ export interface Address {
   variables: string[]
 }
 
-export function address (method: string, params: Params): Address {
+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`)
+  if (!verbs.has(verb)) throw new http.NotFound(`'${method}' names no method`)
 
   const variables: string[] = []
   const fragments: string[] = []
@@ -66,13 +65,15 @@ export function address (method: string, params: Params): Address {
  * 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 } {
+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 (variables.includes(key)) continue
 
     if (key !== QUERY) {
       input[key] = value
@@ -91,30 +92,27 @@ export function split (params: Params, variables: string[]): { query?: Params, i
 }
 
 /** 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
+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`)
+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 {
+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
+    if (part === null) return null
 
     parts.push(part)
   }
@@ -125,39 +123,34 @@ export function name (segments: Segment[], verb: string): string | null {
 }
 
 /** The segment that leaves a route unnameable, as it was declared, or nothing where none does. */
-export function refusal (segments: Segment[]): string | null {
+export function refusal(segments: Segment[]): string | null {
   for (const segment of segments)
-    if (component(segment) === null)
-      return declared(segment)
+    if (component(segment) === null) return declared(segment)
 
   return null
 }
 
-function component (segment: Segment): string | 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
+  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
+  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 {
+export function template(segments: Segment[]): string {
   return '/' + segments.map(declared).join('/')
 }
 
-function declared (segment: Segment): string {
-  if (segment.fragment !== null)
-    return segment.fragment
+function declared(segment: Segment): string {
+  if (segment.fragment !== null) return segment.fragment
 
-  if (segment.wildcard === true)
-    return '**'
+  if (segment.wildcard === true) return '**'
 
   return segment.placeholder === null ? '*' : ':' + segment.placeholder
 }

package/source/RTD/Directives.ts

@@ -3,7 +3,7 @@ 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'
+import type { extensions } from '@toa.io/core/types'
 
 type Host = extensions.Host
 
@@ -18,7 +18,10 @@ export interface Directives {
   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>
+  explain: (
+    context: Context,
+    introspection: Introspection
+  ) => Promise<Introspection | null>
   settle: (context: Context, response: OutgoingMessage) => Promise<void>
   dispose: () => void
 }
@@ -71,9 +74,11 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
   preflight?: (request: Context & TExtension) => void | Promise<void>
 
   /** Call-scoped, with what the node declares. Runs once per call. */
-  precall?: (directives: TDirective[],
+  precall?: (
+    directives: TDirective[],
     request: Context & TExtension,
-    parameters: Parameter[]) => Output | Promise<Output>
+    parameters: Parameter[]
+  ) => Output | Promise<Output>
 
   /**
    * What this family's directives make of what the method says about itself, which is
@@ -84,22 +89,28 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
    * is why no parameters are passed — so a directive that can only tell from one hands back
    * what it was given.
    */
-  explain?: (directives: TDirective[],
+  explain?: (
+    directives: TDirective[],
     request: Context & TExtension,
-    introspection: Introspection) => Introspection | null | Promise<Introspection | null>
+    introspection: Introspection
+  ) => Introspection | null | Promise<Introspection | null>
 
   /** Call-scoped, on the message that call produced. */
-  settle?: (directives: TDirective[],
+  settle?: (
+    directives: TDirective[],
     request: Context & TExtension,
-    response: OutgoingMessage) => void | Promise<void>
+    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>
+  depart?: (
+    request: Context & TExtension,
+    response: OutgoingMessage
+  ) => void | Promise<void>
 
   dispose?: (directives: TDirective[]) => void
 }

package/source/RTD/Endpoint.ts

@@ -5,7 +5,10 @@ import type * as RTD from './index.js'
 import type { Introspection } 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>
 

package/source/RTD/Method.ts

@@ -9,7 +9,7 @@ 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
   }
@@ -19,17 +19,19 @@ export class Method {
    * 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)
+  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> {
+  public async close(): Promise<void> {
     await this.endpoint?.close()
   }
 }

package/source/RTD/Node.ts

@@ -13,7 +13,7 @@ export class Node {
   private readonly protected: boolean
   private routes: Route[]
 
-  public constructor (routes: Route[], methods: Methods, properties: Properties) {
+  public constructor(routes: Route[], methods: Methods, properties: Properties) {
     this.routes = routes
     this.methods = methods
     this.protected = properties.protected
@@ -24,13 +24,16 @@ export class Node {
     this.sort()
   }
 
-  public match (fragments: string[], parameters: Parameter[] = []): Match | null {
+  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 params = parameters.slice()
-      const match = route.match(fragments, params)
+      const match = route.match(fragments, parameters)
+
+      if (match !== null) return match
 
-      if (match !== null)
-        return match
+      parameters.length = mark
     }
 
     return null
@@ -40,7 +43,7 @@ export class Node {
    * 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[] {
+  public merge(node: Node): Node[] {
     this.intermediate = node.intermediate
 
     const nodes = this.protected ? this.append(node) : this.replace(node)
@@ -50,9 +53,8 @@ export class Node {
     return nodes
   }
 
-  public touch (expiration: number): void {
-    if (!this.protected)
-      this.expiration = expiration
+  public touch(expiration: number): void {
+    if (!this.protected) this.expiration = expiration
   }
 
   /**
@@ -62,33 +64,34 @@ export class Node {
    * 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> {
+  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)
+    for (const route of this.routes) yield* route.walk(segments)
   }
 
   /** Every method of this node that this caller may reach, in the order they were declared. */
-  public async explain (context: Context,
-    parameters: Parameter[]): Promise<Record<string, Introspection>> {
+  public async explain(
+    context: Context,
+    parameters: Parameter[]
+  ): Promise<Record<string, Introspection>> {
     const entries = Object.entries(this.methods)
 
-    const explained = await Promise.all(entries
-      .map(async ([, method]) => await method.explain(context, parameters)))
+    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]!
+      if (explained[i] !== null) methods[entries[i][0]] = explained[i]!
 
     return methods
   }
 
-  private replace (node: Node): Node[] {
+  private replace(node: Node): Node[] {
     const methods = Object.values(this.methods)
 
     this.routes = node.routes
@@ -97,44 +100,39 @@ export class Node {
     this.forward = node.forward
 
     // race condition is really unlikely
-    for (const method of methods)
-      void method.close()
+    for (const method of methods) void method.close()
 
     return this.nodes()
   }
 
-  private append (node: Node): Node[] {
+  private append(node: Node): Node[] {
     const nodes: Node[] = []
 
-    for (const route of node.routes)
-      nodes.push(...this.route(route))
+    for (const route of node.routes) nodes.push(...this.route(route))
 
-    for (const [verb, method] of Object.entries(node.methods))
-      this.methods[verb] = method
+    for (const [verb, method] of Object.entries(node.methods)) this.methods[verb] = method
 
     return nodes
   }
 
-  private route (candidate: Route): Node[] {
+  private route(candidate: Route): Node[] {
     for (const route of this.routes)
-      if (candidate.equals(route))
-        return route.merge(candidate)
+      if (candidate.equals(route)) return route.merge(candidate)
 
     this.routes.push(candidate)
 
     return candidate.node.nodes()
   }
 
-  private nodes (): Node[] {
+  private nodes(): Node[] {
     const nodes: Node[] = [this]
 
-    for (const route of this.routes)
-      nodes.push(...route.node.nodes())
+    for (const route of this.routes) nodes.push(...route.node.nodes())
 
     return nodes
   }
 
-  private sort (): void {
+  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