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

package/source/RPC/Dispatcher.ts

@@ -0,0 +1,130 @@
+import { console } from 'openspan'
+import * as http from '../HTTP/index.js'
+import * as schemas from '../schemas.js'
+import { BATCH } from '../const.js'
+import { address, split } from './names.js'
+import { fork } from './Context.js'
+import { BATCH_TOO_LARGE, INVALID_REQUEST, PARSE, failure, of, response } from './errors.js'
+import { VERSION, type Call, type Response } from './types.js'
+import type { RPC } from '../Annotation.js'
+
+/**
+ * JSON-RPC, as the calls a request carries.
+ *
+ * It clones the context per call and hands each clone back to the gateway: it holds no
+ * tree, no index and no knowledge of routing. Whether a name resolves, what it resolves
+ * to, and what the directives of that route do are answered by the same `route` an
+ * ordinary request goes through.
+ */
+export class Dispatcher {
+  private readonly batch: number
+
+  public constructor (options: RPC) {
+    this.batch = options.batch ?? BATCH
+  }
+
+  public async dispatch (context: http.Context,
+    route: http.Processor): Promise<http.OutgoingMessage> {
+    if (context.request.method !== 'POST')
+      throw new http.MethodNotAllowed(new Headers({ allow: 'POST' }))
+
+    const envelope = await this.read(context)
+    const batched = Array.isArray(envelope)
+    const calls = batched ? envelope : [envelope]
+
+    if (calls.length === 0)
+      throw new http.BadRequest(response(null,
+        failure(INVALID_REQUEST, 'A request carries at least one call')))
+
+    if (calls.length > this.batch)
+      throw new http.BadRequest(response(null,
+        failure(BATCH_TOO_LARGE, `A request carries at most ${this.batch} calls`)))
+
+    const answers: Response[] = []
+
+    // one after another: a request the caller writes should not become a fan-out they own
+    for (const call of calls) {
+      const answer = await this.answer(call, context, route)
+
+      if (answer !== null)
+        answers.push(answer)
+    }
+
+    // every call was a notification, and a notification is answered by not answering
+    if (answers.length === 0)
+      return { status: NO_CONTENT }
+
+    // a reply assembled from several is not one of them, and is not stored as if it were
+    return {
+      status: OK,
+      body: batched ? answers : answers[0],
+      headers: new Headers({ 'cache-control': 'no-store' })
+    }
+  }
+
+  private async answer (input: unknown, context: http.Context,
+    route: http.Processor): Promise<Response | null> {
+    const invalid = schemas.call.fit(input)
+
+    // it may have carried an id, but nothing about it is trustworthy enough to answer to
+    if (invalid !== null)
+      return response(null, failure(INVALID_REQUEST, invalid.message))
+
+    return await this.call(input as Call, context, route)
+  }
+
+  private async call (call: Call, context: http.Context,
+    route: http.Processor): Promise<Response | null> {
+    const notification = call.id === undefined
+
+    try {
+      const params = call.params ?? {}
+      const { path, verb, variables } = address(call.method, params)
+      const { query, input } = split(params, variables)
+      const clone = fork(context, path, verb, query, input)
+
+      // one span per call, so what the directives of that call open has somewhere to hang
+      const message = await console.span({ name: call.method, attributes: { id: call.id } },
+        async () => await route(clone))
+
+      // what `io:output` restricts, over this call's reply rather than the envelope
+      await http.shape(clone, message)
+
+      if (notification)
+        return null
+
+      return { jsonrpc: VERSION, id: call.id!, result: message.body ?? null }
+    } catch (exception) {
+      /*
+       * A credential belongs to the request. Refusing one call for it would leave the
+       * reply a 200, and the challenge that tells a client where to authenticate is
+       * attached to a 401 — so the whole envelope is refused instead.
+       */
+      if (exception instanceof http.Unauthorized)
+        throw exception
+
+      if (notification) {
+        console.debug('Notification failed', { method: call.method, error: of(exception) })
+
+        return null
+      }
+
+      return { jsonrpc: VERSION, id: call.id!, error: of(exception) }
+    }
+  }
+
+  /** A body the decoder refuses is a parse error; a media type it does not know is not. */
+  private async read (context: http.Context): Promise<unknown> {
+    try {
+      return await context.body()
+    } catch (exception) {
+      if (exception instanceof http.BadRequest)
+        throw new http.BadRequest(response(null, failure(PARSE, 'Parse error')))
+
+      throw exception
+    }
+  }
+}
+
+const OK = 200
+const NO_CONTENT = 204

package/source/RPC/errors.test.ts

@@ -0,0 +1,52 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import * as http from '../HTTP/index.js'
+import {
+  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' })
+  })
+
+  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' })
+  })
+
+  it('should read a refused authorization as forbidden', () => {
+    assert.deepEqual(of(new http.Forbidden()), { code: FORBIDDEN, message: 'Forbidden' })
+  })
+
+  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' })
+  })
+
+  it('should carry the code an operation refused with', () => {
+    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' } })
+  })
+
+  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' } })
+  })
+
+  it('should say what any other client error was refused with', () => {
+    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' })
+  })
+})

package/source/RPC/errors.ts

@@ -0,0 +1,83 @@
+import * as http from '../HTTP/index.js'
+import { VERSION, type Failure, type Response } from './types.js'
+
+/*
+ * The five the specification fixes (JSON-RPC 2.0 §5.1). A client reads these the same
+ * whoever answers.
+ */
+export const PARSE = -32700
+export const INVALID_REQUEST = -32600
+export const METHOD_NOT_FOUND = -32601
+export const INVALID_PARAMS = -32602
+export const INTERNAL = -32603
+
+/*
+ * Ours. The specification reserves -32000 to -32099 for implementation-defined server
+ * errors and defines nothing in it, so these mean nothing outside Toa — which is why
+ * `REFUSED` carries the operation's own code in `data`.
+ */
+export const FORBIDDEN = -32000
+export const REFUSED = -32001
+export const BATCH_TOO_LARGE = -32002
+
+export function failure (code: number, message: string, data?: unknown): Failure {
+  const value: Failure = { code, message }
+
+  if (data !== undefined)
+    value.data = data
+
+  return value
+}
+
+export function response (id: string | number | null, error: Failure): Response {
+  return { jsonrpc: VERSION, id, error }
+}
+
+/**
+ * What an exception says as a JSON-RPC error.
+ *
+ * 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)
+
+  if (exception instanceof http.NotFound || exception instanceof http.MethodNotAllowed)
+    return failure(METHOD_NOT_FOUND, text(exception, 'Method not found'))
+
+  if (exception instanceof http.Forbidden)
+    return failure(FORBIDDEN, text(exception, 'Forbidden'))
+
+  if (exception instanceof http.BadRequest)
+    return failure(INVALID_PARAMS, text(exception, 'Invalid params'))
+
+  // a conflict, a precondition, a throttle: the call was refused, and by what is worth saying
+  if (exception instanceof http.ClientError)
+    return failure(REFUSED, text(exception, 'Refused'), { status: exception.status })
+
+  return failure(INTERNAL, 'Internal error')
+}
+
+/**
+ * An operation that declares its errors answers with one rather than throwing, and the
+ * 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 {
+  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
+
+  return failure(REFUSED, message, { code })
+}
+
+function text (exception: http.Exception, fallback: string): string {
+  return typeof exception.body === 'string' && exception.body !== ''
+    ? exception.body
+    : fallback
+}

package/source/RPC/index.ts

@@ -0,0 +1 @@
+export { Dispatcher } from './Dispatcher.js'

package/source/RPC/names.test.ts

@@ -0,0 +1,122 @@
+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,183 @@
+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
+}