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

package/source/Mapping.ts

@@ -4,29 +4,27 @@ import type { Introspection, Schema } from './Introspection.js'
 import type { QueryString } from './Query.js'
 import type * as http from './HTTP/index.js'
 import type * as syntax from './RTD/syntax/index.js'
-import type * as core from '@toa.io/core'
+import type * as core from '@toa.io/core/types'
 
 export abstract class Mapping {
   protected readonly query: Query
   public abstract readonly queryable: boolean
 
-  public constructor (query: Query) {
+  public constructor(query: Query) {
     this.query = query
   }
 
-  public static create (query?: syntax.Query | null): Mapping {
-    const q = new Query(query!)
+  public static create(query?: syntax.Query | null, paged?: boolean): Mapping {
+    const q = new Query(query!, paged)
 
-    return queryable(query)
-      ? new QueryableMapping(q)
-      : new InputMapping(q)
+    return queryable(query) ? new QueryableMapping(q) : new InputMapping(q)
   }
 
-  public explain (introspection: Introspection): Record<string, Schema> | null {
+  public explain(introspection: Introspection): Record<string, Schema> | null {
     return this.query.explain(introspection)
   }
 
-  protected assign (input: any, qs: QueryString): void {
+  protected assign(input: any, qs: QueryString): void {
     if (qs.parameters !== null) {
       if (typeof input !== 'object' || input === null)
         throw new Error('Input must be an object to embed query parameters')
@@ -35,26 +33,27 @@ export abstract class Mapping {
     }
   }
 
-  public abstract fit (input: any, query: http.Query, parameters: Parameter[]): core.Request
+  public abstract fit(
+    input: any,
+    query: http.Query,
+    parameters: Parameter[]
+  ): core.Request
 }
 
 class QueryableMapping extends Mapping {
   public override readonly queryable = true
 
-  public fit (input: any, query: http.Query, parameters: Parameter[]): core.Request {
+  public fit(input: any, query: http.Query, parameters: Parameter[]): core.Request {
     const request: core.Request = {}
     const qs = this.query.fit(query, parameters)
 
-    if (input === undefined && qs.parameters !== null)
-      input = {}
+    if (input === undefined && qs.parameters !== null) input = {}
 
     this.assign(input, qs)
 
-    if (input !== undefined)
-      request.input = input
+    if (input !== undefined) request.input = input
 
-    if (qs.query !== null)
-      request.query = qs.query
+    if (qs.query !== null) request.query = qs.query
 
     return request
   }
@@ -63,34 +62,33 @@ class QueryableMapping extends Mapping {
 class InputMapping extends Mapping {
   public override readonly queryable = false
 
-  public fit (input: any, query: http.Query, parameters: Parameter[]): core.Request {
+  public fit(input: any, query: http.Query, parameters: Parameter[]): core.Request {
     const request: core.Request = {}
     const qs = this.query.fit(query, parameters)
 
-    if (input === undefined &&
-      (this.query.parameterized || parameters.length > 0 || qs.parameters !== null))
+    if (
+      input === undefined &&
+      (this.query.parameterized || parameters.length > 0 || qs.parameters !== null)
+    )
       input = {}
 
     if (parameters.length > 0) {
       if (typeof input !== 'object' || input === null)
         throw new Error('Input must be an object to embed parameters')
 
-      for (const parameter of parameters)
-        input[parameter.name] = parameter.value
+      for (const parameter of parameters) input[parameter.name] = parameter.value
     }
 
     this.assign(input, qs)
 
-    if (input !== undefined)
-      request.input = input
+    if (input !== undefined) request.input = input
 
     return request
   }
 }
 
-export function queryable (query?: syntax.Query | null): boolean {
-  if (query === undefined || query === null)
-    return false
+export function queryable(query?: syntax.Query | null): boolean {
+  if (query === undefined || query === null) return false
 
   const keys = Object.keys(query)
 

package/source/Query.ts

@@ -7,7 +7,7 @@ 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'
+import type * as core from '@toa.io/core/types'
 
 export class Query {
   public readonly parameterized: boolean
@@ -18,21 +18,25 @@ export class Query {
   private readonly queryable: boolean
   private readonly searchable: boolean
 
-  public constructor (query: syntax.Query) {
+  /** 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) {
-      query.omit ??= { value: 0, range: [0, 1000] }
-      query.limit ??= { value: 10, range: [1, 100] }
+      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
+        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(';')) {
@@ -46,17 +50,19 @@ export class Query {
     this.query = query
   }
 
-  public fit (query: http.Query, parameters: Parameter[]): QueryString {
+  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)
+      if (error !== null) throw new http.BadRequest('Query ' + error.message)
 
       this.fitCriteria(qs.query, parameters)
-      this.fitRanges(qs.query)
+
+      if (this.paged) this.fitRanges(qs.query)
+      else this.refuseRanges(qs.query)
+
       this.fitSort(qs.query)
 
       if (this.query.deleted !== undefined)
@@ -76,7 +82,7 @@ export class Query {
    * Only what it actually accepts — a criteria the declaration closes is refused, and so is
    * a search where none was asked for.
    */
-  public explain (introspection: Introspection): Record<string, Schema> | null {
+  public explain(introspection: Introspection): Record<string, Schema> | null {
     let query: Record<string, Schema> | null = null
 
     if (this.query?.parameters !== undefined)
@@ -84,25 +90,31 @@ export class Query {
         const schema = take(introspection, parameter)
 
         // eslint-disable-next-line max-depth
-        if (schema === undefined)
-          continue
+        if (schema === undefined) continue
 
         query ??= {}
         query[parameter] = schema
       }
 
-    if (!this.queryable)
-      return query
+    if (!this.queryable) return query
 
     query ??= {}
 
     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.')
-    query.limit = bounded('How many at once.', this.query.limit!)
-    query.omit = bounded('How many to skip.', this.query.omit!)
+      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.')
@@ -110,7 +122,7 @@ export class Query {
     return query
   }
 
-  private split (query: http.Query): {
+  private split(query: http.Query): {
     query: http.Query | null
     parameters: Record<string, string> | null
   } {
@@ -144,7 +156,7 @@ export class Query {
     }
   }
 
-  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')
 
@@ -167,10 +179,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) => {
@@ -180,7 +190,14 @@ 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')
@@ -188,18 +205,15 @@ export class Query {
 
     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 ?? '')
 
@@ -207,12 +221,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
 }
@@ -224,11 +239,11 @@ interface CriteriaGroup {
   operator: ',' | ';'
 }
 
-function keyword (type: string, description: string): Schema {
+function keyword(type: string, description: string): Schema {
   return { type, description } as unknown as Schema
 }
 
-function bounded (description: string, bounds: syntax.Range): Schema {
+function bounded(description: string, bounds: syntax.Range): Schema {
   const schema: Record<string, unknown> = {
     type: 'integer',
     description,
@@ -236,8 +251,7 @@ function bounded (description: string, bounds: syntax.Range): Schema {
     maximum: bounds.range[1]
   }
 
-  if (bounds.value !== undefined)
-    schema.default = bounds.value
+  if (bounds.value !== undefined) schema.default = bounds.value
 
   return schema as unknown as Schema
 }

package/source/RPC/Context.ts

@@ -1,5 +1,4 @@
 import * as http from '../HTTP/index.js'
-import { Timing } from '../HTTP/Timing.js'
 import type { Params } from './types.js'
 
 /**
@@ -11,8 +10,13 @@ import type { Params } from './types.js'
  * 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 {
+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)
@@ -43,18 +47,11 @@ export function fork (context: http.Context, path: string, verb: string,
     url: { value: url, enumerable: true },
     request: { value: request, enumerable: true },
     pipelines: { value: pipelines, enumerable: true },
-    /*
-     * Its own, so that what the stages of a call take is measured per call and stays there.
-     * `server-timing` is a header, and a request carrying thirty-two calls would otherwise
-     * write ninety-six values into one — where a trace says the same thing, per call.
-     */
-    timing: { value: new Timing(), enumerable: true },
     body: {
       value: async () => {
         let value = input
 
-        for (const transform of pipelines.body)
-          value = await transform(value)
+        for (const transform of pipelines.body) value = await transform(value)
 
         return value
       }

package/source/RPC/Dispatcher.ts

@@ -4,7 +4,14 @@ 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 {
+  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'
 
@@ -19,12 +26,14 @@ import type { RPC } from '../Annotation.js'
 export class Dispatcher {
   private readonly batch: number
 
-  public constructor (options: RPC) {
+  public constructor(options: RPC) {
     this.batch = options.batch ?? BATCH
   }
 
-  public async dispatch (context: http.Context,
-    route: http.Processor): Promise<http.OutgoingMessage> {
+  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' }))
 
@@ -33,12 +42,17 @@ export class Dispatcher {
     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')))
+      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`)))
+      throw new http.BadRequest(
+        response(
+          null,
+          failure(BATCH_TOO_LARGE, `A request carries at most ${this.batch} calls`)
+        )
+      )
 
     const answers: Response[] = []
 
@@ -46,13 +60,11 @@ export class Dispatcher {
     for (const call of calls) {
       const answer = await this.answer(call, context, route)
 
-      if (answer !== null)
-        answers.push(answer)
+      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 }
+    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 {
@@ -62,19 +74,24 @@ export class Dispatcher {
     }
   }
 
-  private async answer (input: unknown, context: http.Context,
-    route: http.Processor): Promise<Response | null> {
+  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))
+    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> {
+  private async call(
+    call: Call,
+    context: http.Context,
+    route: http.Processor
+  ): Promise<Response | null> {
     const notification = call.id === undefined
 
     try {
@@ -84,14 +101,15 @@ export class Dispatcher {
       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))
+      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
+      if (notification) return null
 
       return { jsonrpc: VERSION, id: call.id!, result: message.body ?? null }
     } catch (exception) {
@@ -100,11 +118,13 @@ export class Dispatcher {
        * 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 (exception instanceof http.Unauthorized) throw exception
 
       if (notification) {
-        console.debug('Notification failed', { method: call.method, error: of(exception) })
+        console.debug('Notification failed', {
+          method: call.method,
+          error: of(exception)
+        })
 
         return null
       }
@@ -114,7 +134,7 @@ export class Dispatcher {
   }
 
   /** 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> {
+  private async read(context: http.Context): Promise<unknown> {
     try {
       return await context.body()
     } catch (exception) {

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