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

package/source/Discovery/tree.test.ts

@@ -1,175 +0,0 @@
-import { describe as suite, it, afterEach } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { describe } from './tree.js'
-import { Tree } from '../RTD/Tree.js'
-import type * as http from '../HTTP/index.js'
-import type { Introspection } from '../Introspection.js'
-import type { EndpointsFactory } from '../Endpoint.js'
-import type { DirectiveFactory } from '../RTD/Directives.js'
-import type * as syntax from '../RTD/syntax/index.js'
-
-/** A method with no mapping has no endpoint, so what it says is its directives' alone. */
-const endpoints = {} as unknown as EndpointsFactory
-
-/** What a method marked with this describes as, standing for a directive that refuses. */
-const REFUSE = 'refuse'
-
-const directives = {
-  create: (stack: syntax.Directive[]) => ({
-    declared: () => undefined,
-    precall: async () => null,
-    settle: async () => undefined,
-    dispose: () => undefined,
-    explain: async (_: unknown, introspection: Introspection) => {
-      const mark = stack.find((directive) => directive.family === 'test')?.value
-
-      if (mark === REFUSE) return null
-
-      return mark === undefined ? introspection : { ...introspection, description: mark }
-    }
-  }),
-  preflight: async () => undefined,
-  depart: async () => undefined,
-  dispose: () => undefined
-} as unknown as DirectiveFactory
-
-const method = (verb: string, mark?: string): syntax.Method => ({
-  verb,
-  directives: mark === undefined ? [] : [{ family: 'test', name: 'mark', value: mark }]
-})
-
-const node = (
-  path: string,
-  methods: syntax.Method[] = [],
-  routes: syntax.Route[] = []
-): syntax.Route => ({ path, node: { routes, methods, directives: [] } })
-
-const trunk = (routes: syntax.Route[], methods: syntax.Method[] = []): syntax.Node => ({
-  routes,
-  methods,
-  directives: []
-})
-
-const request = {} as unknown as http.Context
-
-afterEach(() => {
-  delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
-})
-
-suite('discovery tree', () => {
-  it('should key the trunk by the root', async () => {
-    const tree = new Tree(trunk([], [method('GET')]), endpoints, directives)
-
-    assert.deepEqual(Object.keys((await describe(tree, request)).routes), ['/'])
-  })
-
-  it('should key every route by the template it answers at', async () => {
-    const tree = new Tree(
-      trunk([
-        node('/pots', [method('GET'), method('POST')], [node('/:id', [method('GET')])])
-      ]),
-      endpoints,
-      directives
-    )
-
-    const { routes: resources } = await describe(tree, request)
-
-    assert.deepEqual(Object.keys(resources), ['/pots', '/pots/:id'])
-    assert.deepEqual(Object.keys(resources['/pots']), ['GET', 'POST'])
-  })
-
-  it('should include a route no name can spell', async () => {
-    // `/.rpc` and `/.mcp` leave these out; HTTP addresses a route by its path
-    const tree = new Tree(
-      trunk([
-        node('/v1.0', [method('GET')]),
-        node('/files', [], [node('/**', [method('GET')])]),
-        node('/any', [], [node('/*', [method('GET')])])
-      ]),
-      endpoints,
-      directives
-    )
-
-    assert.deepEqual(Object.keys((await describe(tree, request)).routes), [
-      '/any/*',
-      '/files/**',
-      '/v1.0'
-    ])
-  })
-
-  it('should skip an intermediate node, whose route answers in its place', async () => {
-    const tree = new Tree(
-      trunk([node('/posts', [method('PATCH')], [node('/', [method('PUT')])])]),
-      endpoints,
-      directives
-    )
-
-    assert.deepEqual(Object.keys((await describe(tree, request)).routes), ['/posts'])
-  })
-
-  it('should omit a resource this caller may reach no method of', async () => {
-    const tree = new Tree(
-      trunk([
-        node('/open', [method('GET')]),
-        node('/closed', [method('GET', REFUSE), method('POST', REFUSE)])
-      ]),
-      endpoints,
-      directives
-    )
-
-    assert.deepEqual(Object.keys((await describe(tree, request)).routes), ['/open'])
-  })
-
-  it('should carry only the verbs this caller may reach', async () => {
-    const tree = new Tree(
-      trunk([node('/pots', [method('GET'), method('POST', REFUSE)])]),
-      endpoints,
-      directives
-    )
-
-    const { routes: resources } = await describe(tree, request)
-
-    assert.deepEqual(Object.keys(resources['/pots']), ['GET'])
-  })
-
-  it('should answer the declaration a request would reach where two share a template', async () => {
-    // `/a/b` and `/a: { /b: }` are two routes and one template; the more specific matches
-    const tree = new Tree(
-      trunk([
-        node('/a/b', [method('GET', 'nested')]),
-        node('/a', [], [node('/b', [method('GET', 'adjacent')])])
-      ]),
-      endpoints,
-      directives
-    )
-
-    const { routes: resources } = await describe(tree, request)
-
-    assert.deepEqual(Object.keys(resources), ['/a/b'])
-    assert.equal(resources['/a/b'].GET.description, 'nested')
-  })
-
-  it('should drop a branch that has expired', async () => {
-    process.env.__TESTING_EXPOSITION_BRANCH_TTL = '-1'
-
-    const tree = new Tree(trunk([]), endpoints, directives)
-
-    tree.merge(trunk([node('/pots', [method('GET')])]), {
-      namespace: 'default',
-      component: 'pots'
-    })
-
-    assert.deepEqual(Object.keys((await describe(tree, request)).routes), [])
-  })
-
-  it('should sort, because branches merge in the order their tenants answer', async () => {
-    const tree = new Tree(
-      trunk([node('/zed', [method('GET')]), node('/alpha', [method('GET')])]),
-      endpoints,
-      directives
-    )
-
-    assert.deepEqual(Object.keys((await describe(tree, request)).routes), ['/alpha', '/zed'])
-  })
-})

package/source/Discovery/tree.ts

@@ -1,77 +0,0 @@
-import { describing } from '../Introspection.js'
-import { template } from '../RPC/names.js'
-import { variables } from '../RTD/segment.js'
-import { guarded, resource, type Described } from '../directives/help/index.js'
-import type * as http from '../HTTP/index.js'
-import type { Tree } from '../RTD/index.js'
-import type { Introspection } from '../Introspection.js'
-
-/**
- * Every route in the tree this caller may reach, keyed by the template it answers at, and
- * each described exactly as `OPTIONS` on that path describes it — so a key can be taken
- * from the answer and sent back as a request.
- *
- * A route a name cannot spell is here, unlike at `/.rpc` and `/.mcp`: HTTP addresses a
- * route by its path, so leaving one out would make this disagree with the router. A
- * resource no method of which this caller may reach is not here at all — `OPTIONS` answers
- * `403` to one, and an empty entry would still say it exists.
- *
- * Sorted, because a branch is merged whenever its tenant answers and two replicas would
- * otherwise order the same tree differently. Verbs keep the order they were declared in,
- * which is the order `OPTIONS` answers them in.
- */
-export async function describe(tree: Tree, request: http.Context): Promise<Discovered> {
-  const context = describing(request)
-  const routes = new Map<string, Mounted>()
-
-  /*
-   * Sequentially: there is no I/O to overlap — an endpoint's own description is read once
-   * and memoized — so awaiting the whole tree at once would only allocate every clone of
-   * it at the same moment.
-   */
-  for (const { segments, verb, method } of tree.walk()) {
-    const introspection = await method.explain(context, variables(segments))
-
-    if (introspection === null) continue
-
-    const route = template(segments)
-    let mounted = routes.get(route)
-
-    if (mounted === undefined) {
-      mounted = { described: resource(method.directives), methods: {} }
-      routes.set(route, mounted)
-    }
-
-    // two declarations can walk to one template — `/a/b` and `/a: { /b: }` — and the walk
-    // is in the order `match` tries them, so the first is the one a request would reach
-    mounted.methods[verb] ??= introspection
-  }
-
-  const described: Record<string, Resource> = {}
-
-  for (const route of Array.from(routes.keys()).sort()) {
-    const { described: stated, methods } = routes.get(route)!
-
-    // what the resource is, beside the methods it serves; a verb is upper case and cannot
-    // collide with either key
-    described[route] = { ...stated, ...guarded(methods), ...methods }
-  }
-
-  return { routes: described }
-}
-
-/** What the tree answers. An object, so that what is said of the whole of it has somewhere to go. */
-export interface Discovered {
-  routes: Record<string, Resource>
-}
-
-/** What one resource is, and what it serves; a verb is upper case, and nothing else here is. */
-export interface Resource extends Described {
-  [verb: string]: unknown
-}
-
-/** One route template as the walk found it, before the two are answered as one. */
-interface Mounted {
-  described: Described | null
-  methods: Record<string, Introspection>
-}

package/source/Discovery/trunk.ts

@@ -1,33 +0,0 @@
-import Negotiator from 'negotiator'
-import { types } from '../HTTP/formats/index.js'
-import { DISCOVERY } from '../const.js'
-import type { Context, OutgoingMessage } from '../HTTP/index.js'
-
-/** What a browser asks for, and what nothing else here answers with. */
-const HTML = 'text/html'
-
-/**
- * Where a browser that asked for the trunk is sent. An application serves what it declares,
- * and `/` is usually not one of those — a person who typed the address into a browser is
- * looking for something to look at, and the page is the only thing here that is one.
- *
- * A client that asked for something in particular gets what it asked for: only an `accept`
- * that prefers a page, or one that names no preference at all, is sent here. The second is
- * what an unfurler sends — several ask for anything, and a link to an application would
- * otherwise show nothing — and what `curl` sends, which the page serves no worse than the
- * `405` it used to get.
- */
-export function looking(context: Context): OutgoingMessage | null {
-  if (context.request.method !== 'GET' || context.procedural) return null
-
-  const accept = context.request.headers.accept
-
-  if (accept !== undefined && accept.trim() !== ANYTHING) {
-    if (new Negotiator(context.request).mediaType([...types, HTML]) !== HTML) return null
-  }
-
-  return { status: 302, headers: new Headers({ location: DISCOVERY + '/' }) }
-}
-
-/** An `accept` that names nothing, which is the same as naming none. */
-const ANYTHING = '*/*'

package/source/Endpoint.test.ts

@@ -1,67 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Endpoint } from './Endpoint.js'
-import { Mapping } from './Mapping.js'
-import type { Remote } from '@toa.io/core'
-import type { Parameter } from './RTD/index.js'
-
-/**
- * What `Remote.explain` answers is the contract's own object, the same one every time and
- * on every route that mounts the endpoint — which is what this stands in for.
- */
-function remote(): Promise<Remote> {
-  const explanation = {
-    input: {
-      type: 'object',
-      properties: {
-        a: { type: 'string' },
-        b: { type: 'string' }
-      },
-      required: ['a', 'b']
-    },
-    output: null
-  }
-
-  return Promise.resolve({
-    explain: async () => explanation
-  } as unknown as Remote)
-}
-
-const endpoint = (discovery: Promise<Remote>): Endpoint =>
-  new Endpoint('parameters', Mapping.create(), discovery)
-
-const variable: Parameter[] = [{ name: 'a', value: 'a1b2' }]
-
-describe('explain', () => {
-  it('should state a route variable as the route, not as the input', async () => {
-    const introspection = await endpoint(remote()).explain(variable)
-
-    assert.deepEqual(Object.keys(introspection.route ?? {}), ['a'])
-    assert.deepEqual(Object.keys((introspection.input as any).properties), ['b'])
-    assert.deepEqual((introspection.input as any).required, ['b'])
-  })
-
-  it('should leave the operation for the next route that mounts it', async () => {
-    const discovery = remote()
-
-    await endpoint(discovery).explain(variable)
-
-    // a second route on the same endpoint, taking no variable of its own
-    const introspection = await endpoint(discovery).explain([])
-
-    assert.deepEqual(Object.keys((introspection.input as any).properties), ['a', 'b'])
-    assert.deepEqual((introspection.input as any).required, ['a', 'b'])
-  })
-
-  it('should answer a copy, so what one caller narrows the next still sees', async () => {
-    const one = endpoint(remote())
-    const first = await one.explain(variable)
-
-    delete (first.input as any).properties.b
-
-    const second = await one.explain(variable)
-
-    assert.deepEqual(Object.keys((second.input as any).properties), ['b'])
-  })
-})

package/source/Endpoint.ts

@@ -1,157 +0,0 @@
-import { Readable } from 'node:stream'
-import { Mapping } from './Mapping.js'
-import { take } from './Introspection.js'
-import { parse } from './directives/cache/etag.js'
-import * as http from './HTTP/index.js'
-import type { Introspection, Schema } from './Introspection.js'
-import type { Remote } from '@toa.io/core'
-import type { Remotes } from './Remotes.js'
-import type { Context } from './Context.js'
-import type * as RTD from './RTD/index.js'
-
-export class Endpoint implements RTD.Endpoint {
-  private readonly endpoint: string
-  private readonly mapping: Mapping
-  private readonly discovery: Promise<Remote>
-  private remote: Remote | null = null
-
-  /** What the operation says, with what the route takes already split out of it. */
-  private introspection: Introspection | null = null
-
-  public constructor(endpoint: string, mapping: Mapping, discovery: Promise<Remote>) {
-    this.endpoint = endpoint
-    this.mapping = mapping
-    this.discovery = discovery
-  }
-
-  public async call(
-    context: http.Context,
-    parameters: RTD.Parameter[]
-  ): Promise<http.OutgoingMessage> {
-    const body = await context.body()
-    const query = this.query(context)
-    const request = this.mapping.fit(body, query, parameters)
-
-    this.remote ??= await this.discovery
-
-    const reply = await this.remote.invoke(this.endpoint, request)
-
-    if (reply instanceof Error) throw new http.UnprocessableEntity(reply)
-
-    const message: http.OutgoingMessage = { body: reply }
-
-    // what the reply carries for a cache to validate by; the `cache` family sets the headers
-    if (typeof reply === 'object' && reply !== null && !(reply instanceof Readable)) {
-      if ('VERSION' in reply) message.version = reply.VERSION
-
-      const modified = reply.UPDATED ?? reply.CREATED
-
-      if (modified !== undefined) message.modified = modified
-    }
-
-    return message
-  }
-
-  public selection(): Record<string, Schema> | null {
-    return this.mapping.selection()
-  }
-
-  public async explain(parameters: RTD.Parameter[]): Promise<Introspection> {
-    this.introspection ??= await this.introspect(parameters)
-
-    // what a directive narrows is this caller's answer, not the next caller's
-    return structuredClone(this.introspection)
-  }
-
-  /**
-   * `Remote.explain` answers the contract's own object, whose `input` is the manifest's by
-   * reference. What follows takes properties out of it, and two routes mounting one endpoint
-   * share one remote — so the copy is what keeps the second from describing what the first
-   * took away.
-   */
-  private async introspect(parameters: RTD.Parameter[]): Promise<Introspection> {
-    this.remote ??= await this.discovery
-
-    const operation = structuredClone(await this.remote.explain(this.endpoint))
-
-    // what the operation states it is, is the Introspection's to read and not a resource's:
-    // an operation is written without knowledge of any route, and the same one mounted twice
-    // is two methods. What a method states is what its route states, which `mcp:tool` gives.
-    delete operation.description
-
-    let route: Record<string, Schema> | null = null
-
-    // a variable the operation names is taken by the path, so it is not the body's to send
-    for (const parameter of parameters) {
-      const schema = take(operation, parameter.name)
-
-      if (schema === undefined) continue
-
-      route ??= {}
-      route[parameter.name] = schema
-    }
-
-    const query = this.mapping.explain(operation)
-    const introspection: Introspection = {}
-
-    if (route !== null) introspection.route = route
-
-    if (query !== null) introspection.query = query
-
-    Object.assign(introspection, operation)
-
-    return introspection
-  }
-
-  public async close(): Promise<void> {
-    this.remote ??= await this.discovery
-
-    await this.remote.disconnect(INTERRUPT)
-  }
-
-  private query(context: http.Context): http.Query {
-    const query: http.Query = Object.fromEntries(context.url.searchParams)
-    const etag = context.request.headers['if-match']
-
-    if (etag !== undefined && this.mapping.queryable) query.version = this.version(etag)
-
-    return query
-  }
-
-  private version(etag: string): number {
-    const version = parse(etag)
-
-    if (version === null) throw new http.BadRequest('Invalid ETag')
-
-    return version
-  }
-}
-
-export class EndpointsFactory implements RTD.EndpointsFactory {
-  private readonly remotes: Remotes
-
-  public constructor(remotes: Remotes) {
-    this.remotes = remotes
-  }
-
-  public create(method: RTD.syntax.Method, context: Context): Endpoint {
-    if (method.mapping === undefined)
-      throw new Error('Cannot create Endpoint without mapping')
-
-    const mapping = Mapping.create(method.mapping.query, method.mapping.paged)
-
-    const branch = context.extension
-
-    const namespace = method.mapping.namespace ?? branch?.namespace
-    const component = method.mapping.component ?? branch?.component
-
-    if (namespace === undefined || component === undefined)
-      throw new Error('Annotation endpoints must be fully qualified')
-
-    const discovery = this.remotes.discover(namespace, component, branch?.version)
-
-    return new Endpoint(method.mapping.endpoint, mapping, discovery)
-  }
-}
-
-const INTERRUPT = true

package/source/Factory.ts

@@ -1,42 +0,0 @@
-import { createHash } from 'node:crypto'
-import { Tenant } from './Tenant.js'
-import { CHANNEL } from './const.js'
-import type { Branch } from './Branch.js'
-import type { syntax } from './RTD/index.js'
-import type { Broadcast } from './Gateway.js'
-import type { Connector, Locator } from '@toa.io/core'
-import type { extensions } from '@toa.io/core/types'
-
-export class Factory implements extensions.Factory {
-  private readonly host: Host
-
-  public constructor(host: Host) {
-    this.host = host
-  }
-
-  public async tenant(locator: Locator, node: syntax.Node): Promise<Connector> {
-    const broadcast: Broadcast = await this.host.broadcast(CHANNEL, locator.id)
-    const hash = createHash('sha256').update(JSON.stringify(node)).digest('hex')
-
-    // no timestamp: the tenant stamps each announcement with its own start time
-    const branch: Omit<Branch, 'timestamp'> = {
-      // boot only ever hands a tenant a component's locator, which always has a namespace
-      namespace: locator.namespace!,
-      component: locator.name,
-      isolated: locator.namespace === 'identity',
-      node,
-      version: hash
-    }
-
-    return new Tenant(broadcast, branch)
-  }
-
-  public async service(): Promise<Connector | null> {
-    const { service } = await import('./service.js')
-
-    return await service(this.host)
-  }
-}
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-export type Host = extensions.Host