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

package/source/directives/map/Headers.ts

@@ -15,11 +15,13 @@ const FORBIDDEN = new Set(['host', 'origin'])
 export class Headers extends Mapping<Record<string, string>> {
   private readonly headers: string[]
 
-  public constructor (map: Record<string, string>) {
+  public constructor(map: Record<string, string>) {
     assert.ok(map.constructor === Object, '`map:headers` must be an object')
 
-    assert.ok(Object.values(map).every((value) => typeof value === 'string'),
-      '`map:headers` must be an object with string values')
+    assert.ok(
+      Object.values(map).every((value) => typeof value === 'string'),
+      '`map:headers` must be an object with string values'
+    )
 
     super(map)
 
@@ -27,7 +29,7 @@ export class Headers extends Mapping<Record<string, string>> {
     this.headers.forEach((header) => cors.allow(header))
   }
 
-  public override explain (introspection: Introspection): void {
+  public override explain(introspection: Introspection): void {
     for (const [property, header] of Object.entries(this.value)) {
       const schema = take(introspection, property)
 
@@ -36,21 +38,23 @@ export class Headers extends Mapping<Record<string, string>> {
     }
   }
 
-  public properties (context: Input): Record<string, string> {
+  public properties(context: Input): Record<string, string> {
     context.pipelines.response.push((response) => {
       response.headers ??= new global.Headers()
 
-      for (const header of this.headers)
-        response.headers.append('vary', header)
+      for (const header of this.headers) response.headers.append('vary', header)
     })
 
-    return Object.entries(this.value).reduce((properties: Record<string, string>, [property, header]) => {
-      const value = context.request.headers[header]
+    return Object.entries(this.value).reduce(
+      (properties: Record<string, string>, [property, header]) => {
+        const value = context.request.headers[header]
 
-      if (value !== undefined)
-        properties[property] = Array.isArray(value) ? value.join(', ') : value
+        if (value !== undefined)
+          properties[property] = Array.isArray(value) ? value.join(', ') : value
 
-      return properties
-    }, {})
+        return properties
+      },
+      {}
+    )
   }
 }

package/source/directives/map/Language.ts

@@ -10,14 +10,18 @@ import type { Directive } from './Directive.js'
 export class Language extends Mapping<string> {
   private languages: string[] | null = null
 
-  public constructor (property: string) {
+  public constructor(property: string) {
     assert.ok(typeof property === 'string', '`map:language` must be a string')
 
     cors.allow('accept-language')
     super(property)
   }
 
-  public properties (context: Input, parameters: Parameter[], directives: Directive[]): Record<string, string> {
+  public properties(
+    context: Input,
+    parameters: Parameter[],
+    directives: Directive[]
+  ): Record<string, string> {
     this.languages ??= this.resolve(directives)
 
     const negotiator = new Negotiator(context.request)
@@ -32,10 +36,9 @@ export class Language extends Mapping<string> {
     return { [this.value]: language }
   }
 
-  private resolve (directives: Directive[]): string[] {
+  private resolve(directives: Directive[]): string[] {
     for (const directive of directives)
-      if (directive instanceof Languages)
-        return directive.value
+      if (directive instanceof Languages) return directive.value
 
     throw new Error('Supported languages are not defined, add `map:languages` directive')
   }

package/source/directives/map/Languages.ts

@@ -2,9 +2,15 @@ import assert from 'node:assert'
 import { Property } from './Properties.js'
 
 export class Languages extends Property<'languages'> {
-  public constructor (value: string[]) {
-    assert.ok(Array.isArray(value) && value.length > 0, '`map:languages` must be a non-empty array of strings')
-    assert.ok(value.every((language) => typeof language === 'string'), '`map:languages` must be an array of strings')
+  public constructor(value: string[]) {
+    assert.ok(
+      Array.isArray(value) && value.length > 0,
+      '`map:languages` must be a non-empty array of strings'
+    )
+    assert.ok(
+      value.every((language) => typeof language === 'string'),
+      '`map:languages` must be an array of strings'
+    )
 
     super('languages', value)
   }

package/source/directives/map/Map.ts

@@ -21,37 +21,50 @@ export class Map implements DirectiveFamily {
 
   private remotes!: Remotes
 
-  public create (name: string, value: unknown, remotes: Remotes): Property | Mapping {
+  public create(name: string, value: unknown, remotes: Remotes): Property | Mapping {
     this.remotes = remotes
 
-    return match(name,
-      () => properties.has(name), (name: PN) => new Property(name, value as PV),
-      () => name in mappings, (name: keyof typeof mappings) => new mappings[name](value, remotes),
+    return match(
+      name,
+      () => properties.has(name),
+      (name: PN) => new Property(name, value as PV),
+      () => name in mappings,
+      (name: keyof typeof mappings) => new mappings[name](value, remotes),
       () => {
         throw new Error(`Directive 'map:${name}' is not implemented`)
-      })
+      }
+    )
   }
 
-  public explain (directives: Directive[], _: Input, introspection: Introspection): Introspection {
+  public explain(
+    directives: Directive[],
+    _: Input,
+    introspection: Introspection
+  ): Introspection {
     for (const directive of directives)
-      if (directive instanceof Mapping)
-        directive.explain(introspection)
+      if (directive instanceof Mapping) directive.explain(introspection)
 
     return introspection
   }
 
-  public async precall (directives: Directive[], context: Input, parameters: Parameter[]): Promise<Output> {
+  public async precall(
+    directives: Directive[],
+    context: Input,
+    parameters: Parameter[]
+  ): Promise<Output> {
     const properties = {}
 
     for (const directive of directives)
       if (directive instanceof Mapping)
-        Object.assign(properties, await directive.properties(context, parameters, directives))
+        Object.assign(
+          properties,
+          await directive.properties(context, parameters, directives)
+        )
 
     context.pipelines.body.push((body: unknown) => {
       if (body === undefined || body === null || typeof body !== 'object')
         return properties
-      else
-        return Object.assign(body, properties)
+      else return Object.assign(body, properties)
     })
 
     return null

package/source/directives/map/Mapping.ts

@@ -9,12 +9,16 @@ export abstract class Mapping<T = unknown> {
   protected value: T
   protected remotes?: Remotes
 
-  protected constructor (value: T, remotes?: Remotes) {
+  protected constructor(value: T, remotes?: Remotes) {
     this.value = value
     this.remotes = remotes
   }
 
-  public abstract properties (context: Input, parameters: Parameter[], directives: Directive[]): Output
+  public abstract properties(
+    context: Input,
+    parameters: Parameter[],
+    directives: Directive[]
+  ): Output
 
   /**
    * What this mapping does to what the method says about itself, which is the reverse of
@@ -25,13 +29,12 @@ export abstract class Mapping<T = unknown> {
    * from the request itself and there is nowhere for a caller to put one; a header and a
    * segment are the caller's, and those say where.
    */
-  public explain (introspection: Introspection): void {
-    for (const property of this.names())
-      take(introspection, property)
+  public explain(introspection: Introspection): void {
+    for (const property of this.names()) take(introspection, property)
   }
 
   /** The input properties this mapping fills, however its value names them. */
-  protected names (): string[] {
+  protected names(): string[] {
     return typeof this.value === 'string'
       ? [this.value]
       : Object.keys(this.value as object)

package/source/directives/map/Properties.ts

@@ -6,7 +6,7 @@ export class Property<K extends keyof Properties = keyof Properties> {
   public readonly name: K
   public readonly value: Properties[K]
 
-  public constructor (name: K, value: Properties[K]) {
+  public constructor(name: K, value: Properties[K]) {
     this.name = name
     this.value = value
   }

package/source/directives/map/Segments.ts

@@ -5,17 +5,19 @@ import type { Parameter } from '../../RTD/index.js'
 import type { Introspection, Schema } from '../../Introspection.js'
 
 export class Segments extends Mapping<Record<string, string>> {
-  public constructor (map: Record<string, string>) {
+  public constructor(map: Record<string, string>) {
     assert.ok(map.constructor === Object, '`map:segments` must be an object')
 
-    assert.ok(Object.values(map).every((value) => typeof value === 'string'),
-      '`map:segments ` must be an object with string values')
+    assert.ok(
+      Object.values(map).every((value) => typeof value === 'string'),
+      '`map:segments ` must be an object with string values'
+    )
 
     super(map)
   }
 
   /** A segment is the caller's, so it moves to the route rather than out of sight. */
-  public override explain (introspection: Introspection): void {
+  public override explain(introspection: Introspection): void {
     for (const property of Object.keys(this.value)) {
       const schema = take(introspection, property)
 
@@ -24,22 +26,27 @@ export class Segments extends Mapping<Record<string, string>> {
     }
   }
 
-  public override properties (_: unknown, parameters: Parameter[]): Record<string, string> {
-    return Object.entries(this.value).reduce((properties: Record<string, string>, [property, parameter]) => {
-      const cut = parameter[0] === '~'
+  public override properties(
+    _: unknown,
+    parameters: Parameter[]
+  ): Record<string, string> {
+    return Object.entries(this.value).reduce(
+      (properties: Record<string, string>, [property, parameter]) => {
+        const cut = parameter[0] === '~'
 
-      if (cut) parameter = parameter.slice(1)
+        if (cut) parameter = parameter.slice(1)
 
-      const index = parameters.findIndex(({ name }) => name === parameter)
+        const index = parameters.findIndex(({ name }) => name === parameter)
 
-      assert.ok(index > -1, `Route parameter '${parameter}' is missing`)
+        assert.ok(index > -1, `Route parameter '${parameter}' is missing`)
 
-      properties[property] = parameters[index].value
+        properties[property] = parameters[index].value
 
-      if (cut)
-        parameters.splice(index, 1)
+        if (cut) parameters.splice(index, 1)
 
-      return properties
-    }, {})
+        return properties
+      },
+      {}
+    )
   }
 }

package/source/directives/mcp/MCP.ts

@@ -12,29 +12,31 @@ export class MCP implements DirectiveFamily<Tool> {
   public readonly mandatory = false
 
   /** What this method is published as, which is what the nearest declaration says. */
-  public static published (directives: Tool[] | undefined): Tool | null {
+  public static published(directives: Tool[] | undefined): Tool | null {
     return directives?.[0] ?? null
   }
 
   // eslint-disable-next-line max-params
-  public create (name: string, value: unknown, _: unknown, route: string): Tool {
+  public create(name: string, value: unknown, _: unknown, route: string): Tool {
     assert.ok(name === 'tool', `Unknown directive: mcp:${name}`)
 
     return new Tool(value, route)
   }
 
   /** What the route states this method is, which is the only thing that states it. */
-  public explain (directives: Tool[], _: Context,
-    introspection: Introspection): Introspection {
+  public explain(
+    directives: Tool[],
+    _: Context,
+    introspection: Introspection
+  ): Introspection {
     const tool = MCP.published(directives)
 
-    if (tool === null)
-      return introspection
+    if (tool === null) return introspection
 
     return {
       ...introspection,
       description: tool.description,
-      ...tool.title === undefined ? {} : { title: tool.title }
+      ...(tool.title === undefined ? {} : { title: tool.title })
     }
   }
 }

package/source/directives/mcp/Tool.test.ts

@@ -12,7 +12,10 @@ describe('mcp:tool', () => {
   })
 
   it('should take a title beside the description', () => {
-    const tool = new Tool({ title: 'Hot pots', description: 'The pots that are hot.' }, '/pots')
+    const tool = new Tool(
+      { title: 'Hot pots', description: 'The pots that are hot.' },
+      '/pots'
+    )
 
     assert.strictEqual(tool.title, 'Hot pots')
     assert.strictEqual(tool.description, 'The pots that are hot.')
@@ -23,13 +26,17 @@ describe('mcp:tool', () => {
   })
 
   it('should not accept an empty title', () => {
-    assert.throws(() => new Tool({ title: ' ', description: 'A pot.' }, '/pots'),
-      /a title cannot be empty/)
+    assert.throws(
+      () => new Tool({ title: ' ', description: 'A pot.' }, '/pots'),
+      /a title cannot be empty/
+    )
   })
 
   it('should not accept what it does not know', () => {
-    assert.throws(() => new Tool({ description: 'A pot.', name: 'pots' }, '/pots'),
-      /unknown 'name'/)
+    assert.throws(
+      () => new Tool({ description: 'A pot.', name: 'pots' }, '/pots'),
+      /unknown 'name'/
+    )
   })
 
   it('should not accept an empty description', () => {
@@ -73,8 +80,11 @@ describe('mcp:tool inheritance', () => {
   })
 
   it('should describe a method with what the route states', () => {
-    const described = family.explain([new Tool('What the route is.', '/pots')], null as never,
-      { description: 'What the operation is.' })
+    const described = family.explain(
+      [new Tool('What the route is.', '/pots')],
+      null as never,
+      { description: 'What the operation is.' }
+    )
 
     assert.strictEqual(described.description, 'What the route is.')
   })
@@ -84,7 +94,9 @@ describe('mcp:tool inheritance', () => {
   })
 
   it('should refuse a directive it does not know', () => {
-    assert.throws(() => family.create('resource', 'A pot.', null, '/pots'),
-      /Unknown directive: mcp:resource/)
+    assert.throws(
+      () => family.create('resource', 'A pot.', null, '/pots'),
+      /Unknown directive: mcp:resource/
+    )
   })
 })

package/source/directives/mcp/Tool.ts

@@ -19,27 +19,39 @@ export class Tool {
   public readonly description: string
   public readonly title: string | undefined
 
-  public constructor (value: unknown, route: string) {
+  public constructor(value: unknown, route: string) {
     const stated = typeof value === 'string' ? { description: value } : value
 
-    assert.ok(typeof stated === 'object' && stated !== null && !Array.isArray(stated),
-      'Directive mcp:tool: the value is what the tool is, or a `title` and a `description`')
+    assert.ok(
+      typeof stated === 'object' && stated !== null && !Array.isArray(stated),
+      'Directive mcp:tool: the value is what the tool is, or a `title` and a `description`'
+    )
 
     const { description, title, ...rest } = stated as Record<string, unknown>
 
-    assert.ok(Object.keys(rest).length === 0,
-      `Directive mcp:tool: unknown ${Object.keys(rest).map((key) => `'${key}'`).join(', ')}`)
+    assert.ok(
+      Object.keys(rest).length === 0,
+      `Directive mcp:tool: unknown ${Object.keys(rest)
+        .map((key) => `'${key}'`)
+        .join(', ')}`
+    )
 
-    assert.ok(typeof description === 'string' && description.trim().length > 0,
-      'Directive mcp:tool: a description cannot be empty')
+    assert.ok(
+      typeof description === 'string' && description.trim().length > 0,
+      'Directive mcp:tool: a description cannot be empty'
+    )
 
-    assert.ok(title === undefined || (typeof title === 'string' && title.trim().length > 0),
-      'Directive mcp:tool: a title cannot be empty')
+    assert.ok(
+      title === undefined || (typeof title === 'string' && title.trim().length > 0),
+      'Directive mcp:tool: a title cannot be empty'
+    )
 
     // a tool is called by name, so a route that cannot be named cannot be one — said where
     // the mistake is, rather than as a tool that is quietly never listed
-    assert.ok(refusal(segment(route)) === null,
-      `Directive mcp:tool: '${route}' holds a segment no tool name can spell`)
+    assert.ok(
+      refusal(segment(route)) === null,
+      `Directive mcp:tool: '${route}' holds a segment no tool name can spell`
+    )
 
     this.description = description
     this.title = title as string | undefined

package/source/directives/oauth/Discovery.ts

@@ -20,11 +20,10 @@ export class Discovery implements Interceptor {
    */
   private readonly authorities = new Map<string, Documents>()
 
-  public mount (options: http.Options): void {
+  public mount(options: http.Options): void {
     this.authorities.clear()
 
-    if (options.oauth === undefined)
-      return
+    if (options.oauth === undefined) return
 
     /*
      * `https` always: RFC 8414 has an issuer be one, and OAuth 2.1 has every endpoint of an
@@ -39,20 +38,18 @@ export class Discovery implements Interceptor {
       this.authorities.set(authority, documents(`https://${host}`, options.oauth))
   }
 
-  public reset (): void {
+  public reset(): void {
     this.authorities.clear()
   }
 
-  public intercept (input: Input): Output {
+  public intercept(input: Input): Output {
     const known = this.authorities.get(input.authority)
 
-    if (known === undefined)
-      return null
+    if (known === undefined) return null
 
     // every reply, not just a document's: the challenge is what points a client here
     input.pipelines.response.push((response) => {
-      if (response.status !== UNAUTHORIZED)
-        return
+      if (response.status !== UNAUTHORIZED) return
 
       response.headers ??= new Headers()
       response.headers.set('www-authenticate', known.challenge(input.url.pathname))
@@ -60,8 +57,7 @@ export class Discovery implements Interceptor {
 
     const body = known.read(input.url.pathname)
 
-    if (body === undefined)
-      return null
+    if (body === undefined) return null
 
     return { body, headers: new Headers({ 'cache-control': 'public, max-age=3600' }) }
   }

package/source/directives/oauth/documents.ts

@@ -9,12 +9,12 @@ export interface Documents {
   challenge: (pathname: string) => string
 }
 
-export function documents (issuer: string, oauth: OAuth): Documents {
+export function documents(issuer: string, oauth: OAuth): Documents {
   const server = authorizationServer(issuer, oauth)
   const resources = protectedResources(issuer, oauth)
   const scope = oauth.scopes === undefined ? '' : `, scope="${oauth.scopes.join(' ')}"`
 
-  function read (pathname: string): object | undefined {
+  function read(pathname: string): object | undefined {
     if (pathname === AUTHORIZATION_SERVER || pathname === OPENID_CONFIGURATION)
       return server
 
@@ -24,7 +24,7 @@ export function documents (issuer: string, oauth: OAuth): Documents {
     return undefined
   }
 
-  function challenge (pathname: string): string {
+  function challenge(pathname: string): string {
     return `Bearer resource_metadata="${issuer}${PROTECTED_RESOURCE}${suffix(oauth, pathname)}"${scope}`
   }
 
@@ -36,7 +36,7 @@ export function documents (issuer: string, oauth: OAuth): Documents {
  * everything else this extension serves. Both flags are load-bearing for a client that
  * prefers Client ID Metadata Documents: without either it falls back to registration.
  */
-function authorizationServer (issuer: string, oauth: OAuth): object {
+function authorizationServer(issuer: string, oauth: OAuth): object {
   const metadata: Record<string, unknown> = {
     issuer,
     authorization_endpoint: oauth.authorize,
@@ -52,8 +52,7 @@ function authorizationServer (issuer: string, oauth: OAuth): object {
   if (oauth.registration === 'open')
     metadata.registration_endpoint = `${issuer}${REGISTRATION}`
 
-  if (oauth.scopes !== undefined)
-    metadata.scopes_supported = oauth.scopes
+  if (oauth.scopes !== undefined) metadata.scopes_supported = oauth.scopes
 
   return metadata
 }
@@ -63,7 +62,7 @@ function authorizationServer (issuer: string, oauth: OAuth): object {
  * `https://host/mcp` reads `/.well-known/oauth-protected-resource/mcp`, and one that names
  * no path reads the document at the origin.
  */
-function protectedResources (issuer: string, oauth: OAuth): Map<string, object> {
+function protectedResources(issuer: string, oauth: OAuth): Map<string, object> {
   const map = new Map<string, object>()
 
   for (const path of oauth.resources ?? [])
@@ -74,26 +73,24 @@ function protectedResources (issuer: string, oauth: OAuth): Map<string, object>
   return map
 }
 
-function resource (issuer: string, path: string, oauth: OAuth): object {
+function resource(issuer: string, path: string, oauth: OAuth): object {
   const metadata: Record<string, unknown> = {
     resource: issuer + path,
     authorization_servers: [issuer],
     bearer_methods_supported: ['header']
   }
 
-  if (oauth.scopes !== undefined)
-    metadata.scopes_supported = oauth.scopes
+  if (oauth.scopes !== undefined) metadata.scopes_supported = oauth.scopes
 
   return metadata
 }
 
 /** The document a request to this path was refused against: the longest resource holding it. */
-function suffix (oauth: OAuth, pathname: string): string {
+function suffix(oauth: OAuth, pathname: string): string {
   let longest = ''
 
   for (const path of oauth.resources ?? [])
-    if (pathname.startsWith(path) && path.length > longest.length)
-      longest = path
+    if (pathname.startsWith(path) && path.length > longest.length) longest = path
 
   return canonical(longest)
 }
@@ -102,7 +99,7 @@ function suffix (oauth: OAuth, pathname: string): string {
  * A resource is identified without its trailing slash — the form MCP asks for — while a
  * route is declared with one, so `/mcp/` identifies `…/mcp`.
  */
-function canonical (path: string): string {
+function canonical(path: string): string {
   return path.endsWith('/') ? path.slice(0, -1) : path
 }
 

package/source/directives/octets/Context.ts

@@ -6,15 +6,18 @@ export class Context extends Directive {
   public readonly targeted = false
   public readonly storage: string
 
-  public constructor (value: unknown) {
+  public constructor(value: unknown) {
     super()
 
-    assert.ok(typeof value === 'string', 'Directive \'octets:context\' must must be a string')
+    assert.ok(
+      typeof value === 'string',
+      "Directive 'octets:context' must must be a string"
+    )
 
     this.storage = value
   }
 
-  public async apply (): Promise<Output> {
+  public async apply(): Promise<Output> {
     return null
   }
 }