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

package/source/Query.ts

@@ -1,277 +0,0 @@
-import assert from 'node:assert'
-import { quote } from '@toa.io/generic'
-import * as http from './HTTP/index.js'
-import { type Parameter } from './RTD/index.js'
-import * as schemas from './schemas.js'
-import { queryable } from './Mapping.js'
-import { take } from './Introspection.js'
-import type { Introspection, Schema } from './Introspection.js'
-import type * as syntax from './RTD/syntax/index.js'
-import type * as core from '@toa.io/core/types'
-
-export class Query {
-  public readonly parameterized: boolean
-
-  private readonly query: syntax.Query
-  private readonly closed: boolean = false
-  private readonly prepend: ',' | ';' = ';'
-  private readonly queryable: boolean
-  private readonly searchable: boolean
-
-  /** whether a page is taken of what this answers, and so whether `omit` and `limit` apply */
-  private readonly paged: boolean
-
-  public constructor(query: syntax.Query, paged = true) {
-    this.parameterized = query?.parameters !== undefined
-    this.queryable = queryable(query)
-    this.searchable = query?.search === true
-    this.paged = paged
-
-    if (this.queryable) {
-      if (this.paged) {
-        query.omit ??= { value: 0, range: [0, 1000] }
-        query.limit ??= { value: 10, range: [1, 100] }
-      }
-
-      if (query.criteria !== undefined) {
-        // eslint-disable-next-line max-depth
-        if (query.criteria.endsWith(';')) query.criteria = query.criteria.slice(0, -1)
-        else this.closed = true
-
-        // eslint-disable-next-line max-depth
-        if (query.criteria.startsWith(',') || query.criteria.startsWith(';')) {
-          this.prepend = query.criteria[0] as ',' | ';'
-
-          query.criteria = query.criteria.slice(1)
-        }
-      }
-    }
-
-    this.query = query
-  }
-
-  public fit(query: http.Query, parameters: Parameter[]): QueryString {
-    const qs = this.split(query)
-
-    if (qs.query !== null) {
-      const error = schemas.querystring.fit(qs.query)
-
-      if (error !== null) throw new http.BadRequest('Query ' + error.message)
-
-      this.fitCriteria(qs.query, parameters)
-
-      if (this.paged) this.fitRanges(qs.query)
-      else this.refuseRanges(qs.query)
-
-      this.fitSort(qs.query)
-
-      if (this.query.deleted !== undefined)
-        (qs.query as core.Query).deleted = this.query.deleted
-    }
-
-    return {
-      query: qs.query as core.Query,
-      parameters: qs.parameters
-    }
-  }
-
-  /**
-   * What the querystring carries: the parameters this method declares, taken out of the
-   * input because they are not the body's, and what a queryable method accepts besides.
-   *
-   * Only what it actually accepts — a criteria the declaration closes is refused, and so is
-   * a search where none was asked for.
-   */
-  /**
-   * The querystring parameters this resource declares, which are properties of its own
-   * taken out of the input. What selects records is not among them: that is the same of
-   * every queryable resource, and `selection` is where it is stated.
-   */
-  public explain(introspection: Introspection): Record<string, Schema> | null {
-    let query: Record<string, Schema> | null = null
-
-    if (this.query?.parameters !== undefined)
-      for (const parameter of this.query.parameters) {
-        const schema = take(introspection, parameter)
-
-        // eslint-disable-next-line max-depth
-        if (schema === undefined) continue
-
-        query ??= {}
-        query[parameter] = schema
-      }
-
-    return query
-  }
-
-  /**
-   * What picks the records a call is about, which is the querystring the gateway reads
-   * rather than anything the resource declares — the same for every queryable resource,
-   * and so not what one says about itself. A procedure states it, because there it is
-   * something the caller sends.
-   */
-  public selection(): Record<string, Schema> | null {
-    if (!this.queryable) return null
-
-    const query: Record<string, Schema> = {}
-
-    if (!this.closed)
-      query.criteria = keyword(
-        'string',
-        'What to match, in RSQL: `state==hot`, `rank=gt=5;name==*tea*`.'
-      )
-
-    query.sort = keyword(
-      'string',
-      'What to order by: `rank:desc`, or `rank` for ascending.'
-    )
-
-    if (this.paged) {
-      query.limit = bounded('How many at once.', this.query.limit!)
-      query.omit = bounded('How many to skip.', this.query.omit!)
-    }
-
-    if (this.searchable)
-      query.search = keyword('string', 'What to search the text index for.')
-
-    return query
-  }
-
-  private split(query: http.Query): {
-    query: http.Query | null
-    parameters: Record<string, string> | null
-  } {
-    let parameters: Record<string, string> | null = null
-
-    if (this.query?.parameters !== undefined)
-      for (const key in query)
-        // eslint-disable-next-line max-depth
-        if (this.query.parameters.includes(key)) {
-          parameters ??= {}
-          parameters[key] = query[key] as string
-
-          delete query[key]
-        }
-
-    if (!this.queryable) {
-      const keys = Object.keys(query)
-
-      if (keys.length > 0)
-        throw new http.BadRequest(`Query parameter '${keys[0]}' is not allowed`)
-
-      query = null!
-    }
-
-    if (query?.search !== undefined && !this.searchable)
-      throw new http.BadRequest('Query search is not allowed')
-
-    return {
-      query,
-      parameters
-    }
-  }
-
-  private fitCriteria(query: http.Query, parameters: Parameter[]): void {
-    const groups: CriteriaGroup[] = []
-    const idx = parameters.findIndex((parameter) => parameter.name === 'id')
-
-    if (idx !== -1) {
-      query.id = parameters[idx].value
-
-      parameters.splice(idx, 1)
-    }
-
-    if (parameters.length > 0) {
-      // a segment may carry `,` `;` `(` `)` `=`, which is criteria grammar when unquoted
-      const criteria = parameters
-        .map(({ name, value }) => `${name}==${quote(value)}`)
-        .join(';')
-
-      groups.push({ criteria, operator: this.prepend })
-    }
-
-    if (this.query.criteria !== undefined)
-      groups.push({ criteria: this.query.criteria, operator: ';' })
-
-    if (query.criteria !== undefined)
-      if (this.closed) throw new http.BadRequest('Query criteria is closed')
-      else groups.push({ criteria: query.criteria, operator: WHATEVER })
-
-    if (groups.length > 0)
-      query.criteria = groups.reduce((acc, { criteria, operator }, i) => {
-        return i === groups.length - 1
-          ? `${acc}(${criteria})`
-          : `${acc}(${criteria})${operator}`
-      }, '')
-  }
-
-  /** A route that answers one object is not paged, so a request that pages it is a mistake. */
-  private refuseRanges(qs: http.Query): void {
-    for (const name of ['omit', 'limit'] as const)
-      if (qs[name] !== undefined)
-        throw new http.BadRequest(`Query ${name} is not allowed`)
-  }
-
-  private fitRanges(qs: http.Query): void {
-    const query = qs as core.Query
-
-    assert.ok(this.query.limit !== undefined, 'Query limit must be defined')
-    assert.ok(this.query.omit !== undefined, 'Query limit range must be defined')
-
-    if (qs.limit !== undefined)
-      query.limit = fit(qs.limit, this.query.limit.range, 'limit')
-    else query.limit = this.query.limit.value
-
-    if (qs.omit !== undefined) query.omit = fit(qs.omit, this.query.omit.range, 'omit')
-  }
-
-  private fitSort(qs: http.Query): void {
-    const query = qs as core.Query
-
-    if (qs.sort === undefined && this.query.sort === undefined) return
-
-    const sort = (this.query.sort ?? '') + (qs.sort ?? '')
-
-    query.sort = sort.split(';')
-  }
-}
-
-function fit(string: string, range: [number, number], name: string): number {
-  const number = parseInt(string)
-
-  if (number < range[0] || number > range[1])
-    throw new http.BadRequest(
-      `Query ${name} must be between ${range[0]} and ${range[1]} inclusive`
-    )
-
-  return number
-}
-
-const WHATEVER = ';'
-
-interface CriteriaGroup {
-  criteria: string
-  operator: ',' | ';'
-}
-
-function keyword(type: string, description: string): Schema {
-  return { type, description } as unknown as Schema
-}
-
-function bounded(description: string, bounds: syntax.Range): Schema {
-  const schema: Record<string, unknown> = {
-    type: 'integer',
-    description,
-    minimum: bounds.range[0],
-    maximum: bounds.range[1]
-  }
-
-  if (bounds.value !== undefined) schema.default = bounds.value
-
-  return schema as unknown as Schema
-}
-
-export interface QueryString {
-  query: core.Query | null
-  parameters: Record<string, string> | null
-}

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 * 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

@@ -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'