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

package/source/Query.ts

@@ -1,45 +1,177 @@
-import * as http from './HTTP'
-import { type Parameter } from './RTD'
-import * as schemas from './schemas'
-import type * as syntax from './RTD/syntax'
-import type * as core from '@toa.io/core'
+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
 
-  public constructor (query: syntax.Query) {
-    if (query.criteria !== undefined) {
-      if (query.criteria.endsWith(';'))
-        query.criteria = query.criteria.slice(0, -1)
-      else
-        this.closed = true
+  /** whether a page is taken of what this answers, and so whether `omit` and `limit` apply */
+  private readonly paged: boolean
 
-      if (query.criteria.startsWith(',') || query.criteria.startsWith(';')) {
-        this.prepend = query.criteria[0] as ',' | ';'
+  public constructor(query: syntax.Query, paged = true) {
+    this.parameterized = query?.parameters !== undefined
+    this.queryable = queryable(query)
+    this.searchable = query?.search === true
+    this.paged = paged
 
-        query.criteria = query.criteria.slice(1)
+    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[]): core.Query {
-    const error = schemas.querystring.fit(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 (error !== null)
-      throw new http.BadRequest('Query ' + error.message)
+    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
 
-    this.fitCriteria(query, parameters)
-    this.fitRanges(query)
-    this.fitSort(query)
+          delete query[key]
+        }
 
-    return query as core.Query
+    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 {
+  private fitCriteria(query: http.Query, parameters: Parameter[]): void {
     const groups: CriteriaGroup[] = []
     const idx = parameters.findIndex((parameter) => parameter.name === 'id')
 
@@ -50,8 +182,9 @@ export class Query {
     }
 
     if (parameters.length > 0) {
+      // a segment may carry `,` `;` `(` `)` `=`, which is criteria grammar when unquoted
       const criteria = parameters
-        .map(({ name, value }) => `${name}==${value}`)
+        .map(({ name, value }) => `${name}==${quote(value)}`)
         .join(';')
 
       groups.push({ criteria, operator: this.prepend })
@@ -61,10 +194,8 @@ export class Query {
       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 (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) => {
@@ -74,23 +205,30 @@ export class Query {
       }, '')
   }
 
-  private fitRanges (qs: http.Query): void {
+  /** 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
+    else query.limit = this.query.limit.value
 
-    if (qs.omit !== undefined)
-      query.omit = fit(qs.omit, this.query.omit.range, 'omit')
+    if (qs.omit !== undefined) query.omit = fit(qs.omit, this.query.omit.range, 'omit')
   }
 
-  private fitSort (qs: http.Query): void {
+  private fitSort(qs: http.Query): void {
     const query = qs as core.Query
 
-    if (qs.sort === undefined && this.query.sort === undefined)
-      return
+    if (qs.sort === undefined && this.query.sort === undefined) return
 
     const sort = (this.query.sort ?? '') + (qs.sort ?? '')
 
@@ -98,12 +236,13 @@ export class Query {
   }
 }
 
-function fit (string: string, range: [number, number], name: string): number {
+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`)
+    throw new http.BadRequest(
+      `Query ${name} must be between ${range[0]} and ${range[1]} inclusive`
+    )
 
   return number
 }
@@ -114,3 +253,25 @@ 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

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

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