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

package/source/MCP/tools.ts

@@ -20,7 +20,7 @@ import type { Params, Result, Tool } from './types.js'
  *
  * Sorted, because the revision asks for an order a client can cache on.
  */
-export async function list (tree: Tree, context: http.Context): Promise<Tool[]> {
+export async function list(tree: Tree, context: http.Context): Promise<Tool[]> {
   const tools: Tool[] = []
 
   /*
@@ -28,24 +28,22 @@ export async function list (tree: Tree, context: http.Context): Promise<Tool[]>
    * refuses a credentialed request at an `anonymous` route does not refuse the call a tool
    * makes, and a list that says otherwise disagrees with what `tools/call` then does.
    */
-  const describing: http.Context = Object.create(context,
-    { procedural: { value: true, enumerable: true } })
+  const describing: http.Context = Object.create(context, {
+    procedural: { value: true, enumerable: true }
+  })
 
   for (const { segments, verb, method } of tree.walk()) {
-    if (MCP.published(method.directives.declared<Declaration>(FAMILY)) === null)
-      continue
+    if (MCP.published(method.directives.declared<Declaration>(FAMILY)) === null) continue
 
     const named = name(segments, verb)
 
     // a route a name cannot spell is a route nothing addresses, here or at `/.rpc`
-    if (named === null)
-      continue
+    if (named === null) continue
 
     const variables = parameters(segments)
     const introspection = await method.explain(describing, variables)
 
-    if (introspection === null)
-      continue
+    if (introspection === null) continue
 
     const described = introspection.description
     const schema = output(introspection)
@@ -54,17 +52,20 @@ export async function list (tree: Tree, context: http.Context): Promise<Tool[]>
     // in the order the revision documents one, which is the order it is read in
     const tool: Tool = {
       name: named,
-      ...introspection.title === undefined ? {} : { title: introspection.title },
-      ...described === undefined ? {} : { description: described },
-      inputSchema: input(introspection, variables.map((variable) => variable.name)),
-      ...schema === undefined ? {} : { outputSchema: schema },
-      ...hints === undefined ? {} : { annotations: hints }
+      ...(introspection.title === undefined ? {} : { title: introspection.title }),
+      ...(described === undefined ? {} : { description: described }),
+      inputSchema: input(
+        introspection,
+        variables.map((variable) => variable.name)
+      ),
+      ...(schema === undefined ? {} : { outputSchema: schema }),
+      ...(hints === undefined ? {} : { annotations: hints })
     }
 
     tools.push(tool)
   }
 
-  return tools.sort((one, other) => one.name < other.name ? -1 : 1)
+  return tools.sort((one, other) => (one.name < other.name ? -1 : 1))
 }
 
 /**
@@ -75,10 +76,14 @@ export async function list (tree: Tree, context: http.Context): Promise<Tool[]>
  * would have taken it: what an application did not publish is not reachable here by guessing
  * its name. What the caller may then do with one that is published is still `auth`'s to say.
  */
-export async function call (scope: Scope, named: string, args: Params): Promise<Result> {
+export async function call(scope: Scope, named: string, args: Params): Promise<Result> {
   if (!published(scope.tree, named))
-    throw new http.NotFound(response(null,
-      failure(METHOD_NOT_FOUND, `'${named}' is not a tool this server publishes`)))
+    throw new http.NotFound(
+      response(
+        null,
+        failure(METHOD_NOT_FOUND, `'${named}' is not a tool this server publishes`)
+      )
+    )
 
   const { path, verb, variables } = address(named, args)
   const { query, input: body } = split(args, variables)
@@ -99,7 +104,10 @@ export async function call (scope: Scope, named: string, args: Params): Promise<
      * — that is the client's to fix and not the model's, so it is answered as it is — and
      * neither is a fault of this server, which is a protocol error and stays one.
      */
-    if (exception instanceof http.ClientError && !(exception instanceof http.Unauthorized))
+    if (
+      exception instanceof http.ClientError &&
+      !(exception instanceof http.Unauthorized)
+    )
       return { content: [{ type: 'text', text: refusal(exception) }], isError: true }
 
     throw exception
@@ -118,7 +126,7 @@ export interface Scope {
  * asked here — the declaration is the route's and does not vary by who is calling, and the
  * call that follows is authorized as any request to that route is.
  */
-function published (tree: Tree, named: string): boolean {
+function published(tree: Tree, named: string): boolean {
   for (const { segments, verb, method } of tree.walk())
     if (name(segments, verb) === named)
       return MCP.published(method.directives.declared<Declaration>(FAMILY)) !== null
@@ -126,9 +134,8 @@ function published (tree: Tree, named: string): boolean {
   return false
 }
 
-function result (body: unknown): Result {
-  if (body === undefined || body === null)
-    return { content: [] }
+function result(body: unknown): Result {
+  if (body === undefined || body === null) return { content: [] }
 
   return {
     content: [{ type: 'text', text: JSON.stringify(body) }],
@@ -140,15 +147,13 @@ function result (body: unknown): Result {
  * What a route template takes, by name. Describing has no values for them — a template is
  * not a path — and nothing that describes a method reads one.
  */
-function parameters (segments: Segment[]): Parameter[] {
+function parameters(segments: Segment[]): Parameter[] {
   const params: Parameter[] = []
 
   for (const segment of segments) {
-    if (segment.fragment !== null)
-      continue
+    if (segment.fragment !== null) continue
 
-    if (segment.wildcard === true)
-      params.push({ name: '**', value: '' })
+    if (segment.wildcard === true) params.push({ name: '**', value: '' })
     else if (segment.placeholder !== null)
       params.push({ name: segment.placeholder, value: '' })
   }

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) {