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

package/source/RTD/Node.ts

@@ -1,169 +0,0 @@
-import { type Route } from './Route.js'
-import { type Method, type Methods } from './Method.js'
-import { type Match, type Parameter } from './Match.js'
-import type { Segment } from './segment.js'
-import type { Context } from '../HTTP/index.js'
-import { guarded, resource, type Described } from '../directives/help/index.js'
-import type { Introspection } from '../Introspection.js'
-
-export class Node {
-  public intermediate: boolean
-  public forward: string | null
-  public expiration: number
-  public methods: Methods
-  private readonly protected: boolean
-  private routes: Route[]
-
-  public constructor(routes: Route[], methods: Methods, properties: Properties) {
-    this.routes = routes
-    this.methods = methods
-    this.protected = properties.protected
-    this.forward = properties.forward ?? null
-    this.expiration = properties.expiration ?? Infinity
-    this.intermediate = this.routes.findIndex((route) => route.root) !== -1
-
-    this.sort()
-  }
-
-  public match(fragments: string[], parameters: Parameter[] = []): Match | null {
-    // a route only pushes, so what a failed one added is cut off rather than the array copied
-    const mark = parameters.length
-
-    for (const route of this.routes) {
-      const match = route.match(fragments, parameters)
-
-      if (match !== null) return match
-
-      parameters.length = mark
-    }
-
-    return null
-  }
-
-  /**
-   * Returns the nodes the merged branch has landed on, so that its expiration
-   * can later be extended without rebuilding anything.
-   */
-  public merge(node: Node): Node[] {
-    this.intermediate = node.intermediate
-
-    const nodes = this.protected ? this.append(node) : this.replace(node)
-
-    this.sort()
-
-    return nodes
-  }
-
-  public touch(expiration: number): void {
-    if (!this.protected) this.expiration = expiration
-  }
-
-  /**
-   * Every method under this node, with the template it answers at.
-   *
-   * An intermediate node is skipped: it is never what a path matches, because its `/` route
-   * answers at the same place and is reached instead. The trunk is the exception `match`
-   * makes for it — `'/'` answers the trunk itself, whatever it holds.
-   */
-  public *walk(segments: Segment[], trunk = false): Generator<Mount> {
-    if (trunk || !this.intermediate)
-      for (const [verb, method] of Object.entries(this.methods))
-        yield { segments, verb, method }
-
-    for (const route of this.routes) yield* route.walk(segments)
-  }
-
-  /**
-   * What this resource is, and every method of it this caller may reach, in the order they
-   * were declared. The two are answered apart because only the methods are `Allow`.
-   */
-  public async explain(context: Context, parameters: Parameter[]): Promise<Explained> {
-    const entries = Object.entries(this.methods)
-
-    const explained = await Promise.all(
-      entries.map(async ([, method]) => await method.explain(context, parameters))
-    )
-
-    const methods: Record<string, Introspection> = {}
-
-    for (let i = 0; i < entries.length; i++)
-      if (explained[i] !== null) methods[entries[i][0]] = explained[i]!
-
-    // every method of a node carries the same declaration, so the first that is there says it
-    const stated = entries.length === 0 ? null : resource(entries[0][1].directives)
-    const described = { ...stated, ...guarded(methods) }
-
-    return {
-      described: Object.keys(described).length === 0 ? null : described,
-      methods
-    }
-  }
-
-  private replace(node: Node): Node[] {
-    const methods = Object.values(this.methods)
-
-    this.routes = node.routes
-    this.methods = node.methods
-    this.expiration = node.expiration
-    this.forward = node.forward
-
-    // race condition is really unlikely
-    for (const method of methods) void method.close()
-
-    return this.nodes()
-  }
-
-  private append(node: Node): Node[] {
-    const nodes: Node[] = []
-
-    for (const route of node.routes) nodes.push(...this.route(route))
-
-    for (const [verb, method] of Object.entries(node.methods)) this.methods[verb] = method
-
-    return nodes
-  }
-
-  private route(candidate: Route): Node[] {
-    for (const route of this.routes)
-      if (candidate.equals(route)) return route.merge(candidate)
-
-    this.routes.push(candidate)
-
-    return candidate.node.nodes()
-  }
-
-  private nodes(): Node[] {
-    const nodes: Node[] = [this]
-
-    for (const route of this.routes) nodes.push(...route.node.nodes())
-
-    return nodes
-  }
-
-  private sort(): void {
-    this.routes.sort((a, b) => {
-      return a.variables === b.variables
-        ? b.segments.length - a.segments.length // routes with more segments should be matched first
-        : a.variables - b.variables // routes with more variables should be matched last
-    })
-  }
-}
-
-/** What a resource says of itself, and what it serves. */
-export interface Explained {
-  described: Described | null
-  methods: Record<string, Introspection>
-}
-
-/** A method, and the route template it is reached by. */
-export interface Mount {
-  segments: Segment[]
-  verb: string
-  method: Method
-}
-
-export interface Properties {
-  protected: boolean
-  forward?: string
-  expiration?: number
-}

package/source/RTD/Route.ts

@@ -1,93 +0,0 @@
-import { type Segment } from './segment.js'
-import { type Match, type Parameter } from './Match.js'
-import type { Mount, Node } from './Node.js'
-
-export class Route {
-  public readonly root: boolean
-  public readonly variables: number = 0
-  public readonly segments: Segment[]
-  public readonly node: Node
-  private readonly wildcard: boolean = false
-
-  public constructor(segments: Segment[], node: Node) {
-    this.root = segments.length === 0
-    this.segments = segments
-    this.node = node
-
-    for (const segment of segments)
-      if (segment.fragment === null) {
-        this.variables++
-        this.wildcard ||= segment.wildcard === true
-      }
-  }
-
-  public match(fragments: string[], parameters: Parameter[]): Match | null {
-    if (Date.now() >= this.node.expiration) return null
-
-    for (let i = 0; i < this.segments.length; i++) {
-      const segment = this.segments[i]
-
-      if (segment.fragment !== null && segment.fragment !== fragments[i]) return null
-
-      if (segment.fragment === null && segment.placeholder !== null)
-        parameters.push({ name: segment.placeholder, value: decode(fragments[i]) })
-
-      if (segment.fragment === null && segment.wildcard === true)
-        parameters.push({
-          name: '**',
-          value: fragments
-            .slice(this.segments.length - 1)
-            .map(decode)
-            .join('/')
-        })
-    }
-
-    const exact = this.segments.length === fragments.length
-
-    if ((exact && !this.node.intermediate) || this.wildcard)
-      return { node: this.node, parameters }
-    else return this.matchNested(fragments, parameters)
-  }
-
-  public *walk(prefix: Segment[]): Generator<Mount> {
-    // an expired branch is not matched, so nothing under it is reachable to name
-    if (Date.now() >= this.node.expiration) return
-
-    yield* this.node.walk(prefix.concat(this.segments))
-  }
-
-  public equals(route: Route): boolean {
-    if (route.segments.length !== this.segments.length) return false
-
-    for (let i = 0; i < this.segments.length; i++)
-      if (this.segments[i].fragment !== route.segments[i].fragment) return false
-
-    return true
-  }
-
-  public merge(route: Route): Node[] {
-    return this.node.merge(route.node)
-  }
-
-  private matchNested(fragments: string[], parameters: Parameter[]): Match | null {
-    fragments = fragments.slice(this.segments.length)
-
-    return this.node.match(fragments, parameters)
-  }
-}
-
-/**
- * What the segment says, rather than how it was written: a value is percent-encoded to
- * survive the path, and an operation reads what a caller meant — a `client_id` that is a
- * URL arrives as one. A literal segment is matched as written, which is how it is declared.
- *
- * An escape that decodes to nothing valid is left as it stands; refusing the route over it
- * would answer `404` to a request whose only fault is its spelling.
- */
-function decode(fragment: string): string {
-  try {
-    return decodeURIComponent(fragment)
-  } catch {
-    return fragment
-  }
-}

package/source/RTD/Tree.ts

@@ -1,137 +0,0 @@
-import { console } from 'openspan'
-import { refusal, template } from '../RPC/names.js'
-import { DISCOVERY } from '../const.js'
-import { branchTTL, createNode } from './factory.js'
-import { fragment } from './segment.js'
-import type { Mount, Node } from './Node.js'
-import type { Match } from './Match.js'
-import type { Context } from './Context.js'
-import type { DirectiveFactory } from './Directives.js'
-import type { EndpointsFactory } from './Endpoint.js'
-import type * as syntax from './syntax/index.js'
-
-export class Tree {
-  private readonly root: syntax.Node
-  private readonly trunk: Node
-  private readonly endpoints: EndpointsFactory
-  private readonly directives: DirectiveFactory
-
-  public constructor(
-    node: syntax.Node,
-    endpoints: EndpointsFactory,
-    directives: DirectiveFactory
-  ) {
-    this.endpoints = endpoints
-    this.directives = directives
-    this.root = node
-    this.trunk = this.createNode(node, PROTECTED)
-
-    announce(this.trunk)
-  }
-
-  public match(path: string): Match | null {
-    if (path === '/')
-      return {
-        node: this.trunk,
-        parameters: []
-      }
-
-    const fragments = fragment(path)
-
-    return this.trunk.match(fragments)
-  }
-
-  /** Every method in the tree, with the template it answers at. */
-  public walk(): Generator<Mount> {
-    return this.trunk.walk([], TRUNK)
-  }
-
-  public merge(node: syntax.Node, extension: unknown): Node[] {
-    const branch = this.createNode(node, !PROTECTED, extension)
-
-    announce(branch)
-
-    return this.trunk.merge(branch)
-  }
-
-  /**
-   * Extends the expiration of an already merged branch, leaving its endpoints
-   * and their remotes intact.
-   */
-  public refresh(nodes: Node[]): void {
-    const expiration = Date.now() + branchTTL()
-
-    for (const node of nodes) node.touch(expiration)
-  }
-
-  public dispose(): void {
-    this.directives.dispose()
-  }
-
-  private createNode(node: syntax.Node, protect: boolean, extension?: unknown): Node {
-    const context: Context = {
-      protected: protect,
-      endpoints: this.endpoints,
-      directives: {
-        factory: this.directives,
-        // A merged branch is mounted under the root, so it inherits the root's
-        // directives. The trunk is the root: createNode adds them itself, and
-        // seeding them here too would apply every one of them twice.
-        stack: node === this.root ? [] : (this.root.directives ?? [])
-      },
-      path: label(extension),
-      extension
-    }
-
-    return createNode(node, context)
-  }
-}
-
-/**
- * What is served but cannot be reached as it reads. Said once per route as it is built,
- * because either of these is otherwise noticed only by the caller who cannot find it.
- */
-function announce(node: Node): void {
-  const said = new Set<string>()
-
-  for (const { segments } of node.walk([], TRUNK)) {
-    const route = template(segments)
-
-    if (said.has(route)) continue
-
-    // the page is served under this prefix, before a request is routed at all
-    if (route === DISCOVERY || route.startsWith(DISCOVERY + '/')) {
-      said.add(route)
-
-      console.warn('Route is shadowed by the discovery endpoint', { route })
-
-      continue
-    }
-
-    const segment = refusal(segments)
-
-    if (segment === null) continue
-
-    said.add(route)
-
-    console.warn('Route cannot be addressed as a procedure', { route, segment })
-  }
-}
-
-/**
- * A branch's routes are relative to wherever it is merged, and the mount point is not
- * known while it is being built — so the component it came from is what keeps two
- * branches from looking like the same route.
- */
-function label(extension: unknown): string {
-  if (extension === null || typeof extension !== 'object') return ''
-
-  const { namespace, component } = extension as Record<string, unknown>
-
-  return typeof namespace === 'string' && typeof component === 'string'
-    ? `${namespace}.${component}`
-    : ''
-}
-
-const PROTECTED = true
-const TRUNK = true

package/source/RTD/expiration.test.ts

@@ -1,81 +0,0 @@
-import { it, mock } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Tree } from './Tree.js'
-import type { EndpointsFactory } from '../Endpoint.js'
-import type { DirectiveFactory } from './Directives.js'
-import type * as syntax from './syntax/index.js'
-
-const endpoints = {} as unknown as EndpointsFactory
-
-const directives = {
-  create: () => ({
-    precall: async () => null,
-    settle: async () => undefined,
-    dispose: () => undefined
-  }),
-  dispose: mock.fn()
-} as unknown as DirectiveFactory
-
-const root: syntax.Node = {
-  routes: [],
-  methods: [],
-  directives: []
-}
-
-const pots: syntax.Node = {
-  routes: [
-    {
-      path: '/pots',
-      node: {
-        routes: [],
-        methods: [{ verb: 'GET', directives: [] }],
-        directives: []
-      }
-    }
-  ],
-  methods: [],
-  directives: []
-}
-
-it('should extend expiration without rebuilding the branch', () => {
-  process.env.__TESTING_EXPOSITION_BRANCH_TTL = '1000'
-
-  const now = mock.method(Date, 'now', () => 10_000)
-  const tree = new Tree(root, endpoints, directives)
-  const nodes = tree.merge(pots, { namespace: 'default', component: 'pots' })
-  const match = tree.match('/pots/')
-
-  assert.notStrictEqual(match, null)
-
-  now.mock.mockImplementation(() => 10_900)
-  tree.refresh(nodes)
-
-  now.mock.mockImplementation(() => 11_500)
-
-  const refreshed = tree.match('/pots/')
-
-  assert.notStrictEqual(refreshed, null)
-  assert.strictEqual(refreshed?.node, match?.node)
-
-  now.mock.restore()
-  delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
-})
-
-it('should ignore expired nodes during match', () => {
-  process.env.__TESTING_EXPOSITION_BRANCH_TTL = '1000'
-
-  const now = mock.method(Date, 'now', () => 10_000)
-  const tree = new Tree(root, endpoints, directives)
-
-  tree.merge(pots, { namespace: 'default', component: 'pots' })
-
-  assert.notStrictEqual(tree.match('/pots/'), null)
-
-  now.mock.mockImplementation(() => 11_000)
-
-  assert.strictEqual(tree.match('/pots/'), null)
-
-  now.mock.restore()
-  delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
-})

package/source/RTD/factory.ts

@@ -1,105 +0,0 @@
-import assert from 'node:assert'
-import { BRANCH_TTL } from '../const.js'
-import { Node, type Properties } from './Node.js'
-import { Route } from './Route.js'
-import { fragment, segment } from './segment.js'
-import { Method, type Methods } from './Method.js'
-import type { Context } from './Context.js'
-import type * as syntax from './syntax/index.js'
-
-export function createNode(node: syntax.Node, context: Context): Node {
-  if (node.isolated === true) context.directives.stack = node.directives
-  else context.directives.stack = node.directives.concat(context.directives.stack)
-
-  described(node, context)
-
-  const routes: Route[] = node.routes.map((route) => createRoute(route, context))
-  const methods: Methods = {}
-
-  for (const method of node.methods) methods[method.verb] = createMethod(method, context)
-
-  const protect = node.protected ?? context.protected
-
-  const properties: Properties = {
-    protected: protect,
-    forward: node.forward,
-    expiration: protect ? Infinity : Date.now() + branchTTL()
-  }
-
-  return new Node(routes, methods, properties)
-}
-
-export function branchTTL(): number {
-  const value = process.env.__TESTING_EXPOSITION_BRANCH_TTL
-
-  if (value === undefined || value === '') return BRANCH_TTL
-
-  const parsed = Number(value)
-
-  return Number.isFinite(parsed) ? parsed : BRANCH_TTL
-}
-
-function createRoute(route: syntax.Route, context: Context): Route {
-  const stack = context.directives.stack.slice()
-  const path = context.path
-  const segments = segment(route.path)
-
-  context.path = join(path, route.path)
-
-  /*
-   * What a node says of itself is not said of what is under it. Its own `/` is the
-   * exception: an intermediate node is never what a path matches, because that route
-   * answers in its place — so the two are one resource and what describes it carries.
-   */
-  if (route.path !== ROOT)
-    context.directives.stack = stack.filter((directive) =>
-      context.directives.factory.inheritable(directive)
-    )
-
-  const node = createNode(route.node, context)
-
-  context.directives.stack = stack // restore
-  context.path = path
-
-  return new Route(segments, node)
-}
-
-function join(base: string, path: string): string {
-  // '/one/' and '/two/' would otherwise read as '/one//two/'
-  return (base + path).replace(/\/+/g, '/').replace(/(.)\/$/, '$1')
-}
-
-function createMethod(method: syntax.Method, context: Context): Method {
-  const stack = method.directives.concat(context.directives.stack)
-  const directives = context.directives.factory.create(stack, context.path)
-
-  const endpoint =
-    method.mapping?.endpoint === undefined
-      ? null
-      : context.endpoints.create(method, context)
-
-  return new Method(endpoint, directives)
-}
-
-/**
- * A resource is what it is described beside: a node with no methods of its own is never
- * what a path answers, so nothing would carry what it says about itself. Refused where the
- * declaration is, rather than left to be noticed by whoever cannot find it in the answer.
- */
-function described(node: syntax.Node, context: Context): void {
-  const help = node.directives.find(
-    (directive) => directive.family === HELP && directive.name === 'node'
-  )
-
-  if (help === undefined || node.methods.length > 0) return
-
-  // an intermediate node's `/` answers in its place, and carries what it says
-  if (node.routes.some((route) => route.path === ROOT)) return
-
-  const route = '/' + fragment(context.path).join('/')
-
-  assert.fail(`Directive help:node: '${route}' serves no methods`)
-}
-
-const ROOT = '/'
-const HELP = 'help'

package/source/RTD/index.ts

@@ -1,8 +0,0 @@
-export * from './Tree.js'
-export * from './Node.js'
-export * from './Match.js'
-export * from './Method.js'
-export * from './Context.js'
-export * from './Endpoint.js'
-export * from './Directives.js'
-export * as syntax from './syntax/index.js'

package/source/RTD/segment.test.ts

@@ -1,35 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { segment, fragment } from './segment.js'
-
-it('should return segments', async () => {
-  const segments = segment('/foo/bar/')
-
-  assert.strictEqual(segments.length, 2)
-  assert.strictEqual(segments[0].fragment, 'foo')
-  assert.strictEqual(segments[1].fragment, 'bar')
-})
-
-it('should parse placeholders', async () => {
-  const segments = segment('/foo/:id/')
-
-  assert.strictEqual(segments.length, 2)
-  assert.strictEqual(segments[0].fragment, 'foo')
-  assert.strictEqual(segments[1].fragment, null)
-
-  // helping typescript
-  if (segments[1].fragment !== null) throw new Error('?')
-
-  assert.strictEqual(segments[1].placeholder, 'id')
-})
-
-it('should handle root path', async () => {
-  assert.deepStrictEqual(segment('/'), [])
-})
-
-it('should split', async () => {
-  const parts = fragment('/foo/bar/')
-
-  assert.deepStrictEqual(parts, ['foo', 'bar'])
-})

package/source/RTD/segment.ts

@@ -1,51 +0,0 @@
-import type { Parameter } from './Match.js'
-
-export function segment(path: string): Segment[] {
-  return fragment(path).map(parse)
-}
-
-export function fragment(path: string): string[] {
-  const parts = path.split('/')
-
-  // trailing slash
-  if (parts[parts.length - 1] === '') parts.length--
-
-  // leading slash
-  return parts.splice(1)
-}
-
-function parse(segment: string): Segment {
-  if (segment[0] === ':') return { fragment: null, placeholder: segment.substring(1) }
-  else if (segment === '*') return { fragment: null, placeholder: null }
-  else if (segment === '**') return { fragment: null, placeholder: null, wildcard: true }
-  else return { fragment: segment }
-}
-
-export type Segment =
-  | {
-      fragment: string
-    }
-  | {
-      fragment: null
-      placeholder: string | null
-      wildcard?: boolean
-    }
-
-/**
- * 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. A `*` is skipped: it stands
- * for a segment the caller cannot name, so there is nothing to substitute.
- */
-export function variables(segments: Segment[]): Parameter[] {
-  const params: Parameter[] = []
-
-  for (const segment of segments) {
-    if (segment.fragment !== null) continue
-
-    if (segment.wildcard === true) params.push({ name: '**', value: '' })
-    else if (segment.placeholder !== null)
-      params.push({ name: segment.placeholder, value: '' })
-  }
-
-  return params
-}

package/source/RTD/syntax/index.ts

@@ -1,2 +0,0 @@
-export * from './parse.js'
-export * from './types.js'