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

package/source/RPC/Context.ts

@@ -1,75 +0,0 @@
-import * as http from '../HTTP/index.js'
-import type { Params } from './types.js'
-
-/**
- * One call, as a request the rest of the gateway can serve.
- *
- * The clone is the transport context except for what the call decides, so nothing
- * downstream — the router, the directives, the endpoint, the mapping — knows it is one.
- * It is derived from the context rather than built beside it, so everything not named
- * here, `identity` included, is read through.
- */
-// eslint-disable-next-line max-params
-export function fork(
-  context: http.Context,
-  path: string,
-  verb: string,
-  query: Params | undefined,
-  input: unknown
-): http.Context {
-  const url = new URL(path, context.url)
-
-  if (query !== undefined)
-    for (const [name, value] of Object.entries(query))
-      url.searchParams.set(name, String(value))
-
-  const headers = { ...context.request.headers }
-
-  // a conditional is the envelope's, and a call would answer 304 to a question nobody asked
-  delete headers['if-match']
-  delete headers['if-none-match']
-
-  const request = Object.create(context.request, {
-    method: { value: verb, enumerable: true },
-    headers: { value: headers, enumerable: true }
-  })
-
-  // its own, so an `io:output` restriction shapes this call's reply and no other
-  const pipelines: Pipelines = { body: [], response: [] }
-
-  return Object.create(context, {
-    /*
-     * A credential refuses an `anonymous` route because it would make the reply
-     * uncacheable. What a procedure answers is not a reply: it is a value in an envelope
-     * this gateway answers `no-store`, and the procedure's own headers are discarded.
-     */
-    procedural: { value: true, enumerable: true },
-    url: { value: url, enumerable: true },
-    request: { value: request, enumerable: true },
-    pipelines: { value: pipelines, enumerable: true },
-    body: {
-      value: async () => {
-        let value = input
-
-        for (const transform of pipelines.body) value = await transform(value)
-
-        return value
-      }
-    },
-    /*
-     * The raw request is the envelope, and it has been read. `map:buffer` is the one
-     * directive that asks for it, and answering with a spent stream would hand the
-     * operation an empty string; refusing says what is actually the matter.
-     */
-    buffer: {
-      value: () => {
-        throw new http.BadRequest('`map:buffer` reads the request, which a call is not')
-      }
-    }
-  }) as http.Context
-}
-
-interface Pipelines {
-  body: Array<(input: unknown) => unknown>
-  response: Array<(output: http.OutgoingMessage) => void | Promise<void>>
-}

package/source/RPC/Dispatcher.ts

@@ -1,150 +0,0 @@
-import { console } from 'openspan'
-import * as http from '../HTTP/index.js'
-import { schemas } from '@toa.io/definitions/extensions.exposition'
-import { BATCH } from '@toa.io/definitions/extensions.exposition'
-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 { RPCAnnotation as RPC } from '@toa.io/definitions/extensions.exposition'
-
-/**
- * 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

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

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

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

package/source/RPC/names.test.ts

@@ -1,141 +0,0 @@
-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')
-  })
-})