@toa.io/extensions.exposition 1.0.0-alpha.292 → 1.0.0-alpha.294

package/source/Directive.test.ts

@@ -1,199 +0,0 @@
-import { describe, it, beforeEach, mock } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { generate } from 'randomstring'
-import { DirectivesFactory } from './Directive.js'
-import type { syntax, DirectiveFamily } from './RTD/index.js'
-import type { Remotes } from './Remotes.js'
-import type { Host } from './Factory.js'
-import type { Context } from './HTTP/index.js'
-
-const sequence: string[] = []
-
-const families: Array<DirectiveFamily> = [
-  {
-    name: 'foo',
-    mandatory: true,
-    create: mock.fn((_0: any, _1: any, _2: any) => generate() as any),
-    arrange: mock.fn(),
-    precall: mock.fn(() => {
-      sequence.push('foo')
-      return null
-    }),
-    settle: mock.fn(),
-    dispose: mock.fn()
-  },
-  {
-    name: 'qux',
-    mandatory: true,
-    create: mock.fn((_0: any, _1: any, _2: any) => generate() as any),
-    arrange: mock.fn(),
-    precall: mock.fn(() => {
-      sequence.push('qux')
-      return null
-    }),
-    settle: mock.fn(),
-    dispose: mock.fn()
-  },
-  {
-    name: 'bar',
-    mandatory: false,
-    create: mock.fn((_0: string, _1: any, _2: any) => generate() as any),
-    arrange: mock.fn(),
-    precall: mock.fn(() => {
-      sequence.push('bar')
-      return null
-    }),
-    settle: mock.fn(),
-    dispose: mock.fn()
-  }
-]
-
-let factory: DirectivesFactory
-
-beforeEach(() => {
-  resetCalls()
-  sequence.length = 0
-
-  for (const family of families) {
-    assert.ok(family.precall !== undefined)
-
-    family.precall.mock.mockImplementation(() => {
-      sequence.push(family.name)
-      return null
-    })
-  }
-
-  factory = new DirectivesFactory(
-    families,
-    {} as unknown as Remotes,
-    {} as unknown as Host,
-    { authorities: {} }
-  )
-})
-
-it('should create directive', async () => {
-  const declarations: syntax.Directive[] = [
-    {
-      family: 'foo',
-      name: generate(),
-      value: generate()
-    },
-    {
-      family: 'bar',
-      name: generate(),
-      value: generate()
-    }
-  ]
-
-  factory.create(declarations)
-
-  for (const declaration of declarations) {
-    const family = families.find(({ name }) => name === declaration.family)!
-
-    assert.strictEqual(family.create.mock.calls[0].arguments[0], declaration.name)
-    assert.strictEqual(family.create.mock.calls[0].arguments[1], declaration.value)
-  }
-})
-
-it('should pass the route to the families', async () => {
-  const route = '/' + generate()
-
-  factory.create([{ family: 'foo', name: generate(), value: generate() }], route)
-
-  assert.strictEqual(families[0].create.mock.calls[0].arguments[3], route)
-})
-
-it('should throw error if directive family is not found', async () => {
-  const declaration: syntax.Directive = {
-    family: generate(),
-    name: generate(),
-    value: generate()
-  }
-
-  assert.throws(
-    () => factory.create([declaration]),
-    (error: Error) =>
-      error.message.includes(`Directive family '${declaration.family}' is not found`)
-  )
-})
-
-it('should apply directive', async () => {
-  const declaration: syntax.Directive = {
-    family: 'foo',
-    name: generate(),
-    value: generate()
-  }
-
-  const directives = factory.create([declaration])
-  const request = generate() as unknown as Context
-  const directive = families[0].create.mock.calls[0].result
-
-  await directives.precall(request, [])
-
-  assert.ok(families[0].precall !== undefined)
-
-  assert.deepStrictEqual(families[0].precall.mock.calls[0].arguments[0], [directive])
-  assert.deepStrictEqual(families[0].precall.mock.calls[0].arguments[1], request)
-})
-
-it('should apply mandatory families', async () => {
-  const directives = factory.create([])
-  const request = generate() as unknown as Context
-
-  await directives.precall(request, [])
-
-  assert.ok(families[0].precall.mock.callCount() > 0)
-})
-
-describe('order', () => {
-  // the order the families actually ran, as each precall recorded it
-  function order(): string[] {
-    return sequence
-  }
-
-  it('should run mandatory families in their own order, whatever a manifest says', async () => {
-    // `qux` declared first, but `foo` is registered first and both are mandatory
-    const directives = factory.create([
-      { family: 'qux', name: generate(), value: generate() },
-      { family: 'foo', name: generate(), value: generate() }
-    ])
-
-    await directives.precall(generate() as unknown as Context, [])
-
-    assert.deepStrictEqual(order(), ['foo', 'qux'])
-  })
-
-  it('should run a mandatory family before a declared one it is not declared with', async () => {
-    // only `qux` is declared: `foo` still has to run first, not merely first of
-    // whatever had no declarations
-    const directives = factory.create([
-      { family: 'qux', name: generate(), value: generate() }
-    ])
-
-    await directives.precall(generate() as unknown as Context, [])
-
-    assert.deepStrictEqual(order(), ['foo', 'qux'])
-  })
-
-  it('should run mandatory families before the rest', async () => {
-    const directives = factory.create([
-      { family: 'bar', name: generate(), value: generate() },
-      { family: 'qux', name: generate(), value: generate() }
-    ])
-
-    await directives.precall(generate() as unknown as Context, [])
-
-    assert.deepStrictEqual(order(), ['foo', 'qux', 'bar'])
-  })
-})
-
-function resetCalls(target = [families], seen = new Set()) {
-  if (target === null || typeof target !== 'object' || seen.has(target)) return
-
-  seen.add(target)
-
-  for (const value of Object.values(target))
-    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
-    else resetCalls(value, seen)
-}

package/source/Directive.ts

@@ -1,248 +0,0 @@
-import { console, type SpanOptions } from 'openspan'
-import type { Context, OutgoingMessage, Options } from './HTTP/index.js'
-import type { Remotes } from './Remotes.js'
-import type { Host } from './Factory.js'
-import type { Output } from './io.js'
-import type { Introspection } from './Introspection.js'
-import type * as RTD from './RTD/index.js'
-
-export class Directives implements RTD.Directives {
-  private readonly sets: RTD.DirectiveSet[]
-
-  /** the span of a stage depends only on the set, so it is built once per route */
-  private readonly spans: Spans[]
-
-  public constructor(sets: RTD.DirectiveSet[]) {
-    this.sets = sets
-    this.spans = sets.map((set) => ({
-      precall: options(set, 'precall'),
-      settle: options(set, 'settle'),
-      explain: options(set, 'explain')
-    }))
-  }
-
-  public declared<T>(family: string): T[] | undefined {
-    return this.sets.find((set) => set.family.name === family)?.directives as
-      | T[]
-      | undefined
-  }
-
-  public async precall(context: Context, parameters: RTD.Parameter[]): Promise<Output> {
-    let output = null
-
-    for (let i = 0; i < this.sets.length; i++) {
-      const set = this.sets[i]
-
-      if (set.family.precall === undefined) continue
-
-      const out = await console.span(
-        this.spans[i].precall,
-        async () => await set.family.precall!(set.directives, context, parameters)
-      )
-
-      if (out === null) continue
-
-      if (output !== null) throw new Error('Multiple precall directives responded')
-      else output = out
-    }
-
-    return output
-  }
-
-  /**
-   * What the method says about itself, as its directives leave it. Each family is given
-   * what the one before it returned, and the first to refuse ends it: a method this caller
-   * cannot reach is not described at all.
-   */
-  public async explain(
-    context: Context,
-    introspection: Introspection
-  ): Promise<Introspection | null> {
-    let described: Introspection = introspection
-
-    for (let i = 0; i < this.sets.length; i++) {
-      const set = this.sets[i]
-
-      if (set.family.explain === undefined) continue
-
-      const next = await console.span(
-        this.spans[i].explain,
-        async () => await set.family.explain!(set.directives, context, described)
-      )
-
-      if (next === null) return null
-
-      described = next
-    }
-
-    return described
-  }
-
-  public async settle(context: Context, response: OutgoingMessage): Promise<void> {
-    for (let i = 0; i < this.sets.length; i++) {
-      const set = this.sets[i]
-
-      if (set.family.settle !== undefined)
-        await console.span(
-          this.spans[i].settle,
-          async () => await set.family.settle!(set.directives, context, response)
-        )
-    }
-  }
-
-  public dispose(): void {
-    for (const set of this.sets) set.family.dispose?.(set.directives)
-  }
-}
-
-export class DirectivesFactory implements RTD.DirectiveFactory {
-  private readonly remotes: Remotes
-  private readonly families: Record<string, RTD.DirectiveFamily> = {}
-  private readonly mandatory: string[] = []
-  private readonly instances: Directives[] = []
-
-  /** The request-scoped stages, in registration order, with the spans they run in. */
-  private readonly stages: Stage[] = []
-
-  // eslint-disable-next-line max-params
-  public constructor(
-    families: RTD.DirectiveFamily[],
-    remotes: Remotes,
-    host: Host,
-    options: Options
-  ) {
-    for (const family of families) {
-      family.mount?.(host, options)
-      this.families[family.name] = family
-
-      if (family.mandatory) this.mandatory.push(family.name)
-
-      this.stages.push({
-        family,
-        preflight: { name: `${family.name} preflight` },
-        depart: { name: `${family.name} depart` }
-      })
-    }
-
-    this.remotes = remotes
-  }
-
-  /**
-   * Request-scoped, before anything is routed, so no directives are passed: a family
-   * answers here only for what it does on its own behalf.
-   */
-  public async preflight(context: Context): Promise<void> {
-    for (const stage of this.stages)
-      if (stage.family.preflight !== undefined)
-        await console.span(stage.preflight, async () => {
-          await stage.family.preflight!(context)
-        })
-  }
-
-  /** Request-scoped, on the message going back. */
-  public async depart(context: Context, response: OutgoingMessage): Promise<void> {
-    for (const stage of this.stages)
-      if (stage.family.depart !== undefined)
-        await console.span(stage.depart, async () => {
-          await stage.family.depart!(context, response)
-        })
-  }
-
-  public create(declarations: RTD.syntax.Directive[], route: string = ''): Directives {
-    const groups: Record<string, any> = {}
-    const mandatory = new Set(this.mandatory)
-
-    const names: Record<string, string[]> = {}
-
-    for (const declaration of declarations) {
-      const family = this.families[declaration.family]
-
-      if (family === undefined)
-        throw new Error(`Directive family '${declaration.family}' is not found`)
-
-      const directive = family.create(
-        declaration.name,
-        declaration.value,
-        this.remotes,
-        route
-      )
-
-      groups[family.name] ??= []
-      groups[family.name].push(directive)
-      names[family.name] ??= []
-      names[family.name].push(`${declaration.family}:${declaration.name}`)
-      mandatory.delete(family.name)
-    }
-
-    const sets: RTD.DirectiveSet[] = []
-
-    for (const family of mandatory)
-      sets.push({
-        family: this.families[family],
-        directives: [],
-        names: []
-      })
-
-    for (const [family, directives] of Object.entries(groups))
-      sets.push({
-        family: this.families[family],
-        directives,
-        names: names[family]
-      })
-
-    // Mandatory families run in the order they are registered in, not in the order a
-    // manifest happens to mention them: `auth` must resolve the identity before `io`
-    // can key a quota on it, and a request it denies should not reach `io` at all.
-    // The rest keep the order they were declared in, the sort being stable.
-    sets.sort((a, b) => this.rank(a.family.name) - this.rank(b.family.name))
-
-    // whatever order a family needs among its own directives is fixed here, not per request
-    for (const set of sets) set.family.arrange?.(set.directives)
-
-    const directives = new Directives(sets)
-
-    this.instances.push(directives)
-
-    return directives
-  }
-
-  public inheritable(directive: RTD.syntax.Directive): boolean {
-    return this.families[directive.family]?.inherited !== false
-  }
-
-  public dispose(): void {
-    for (const directives of this.instances) directives.dispose()
-  }
-
-  /** Mandatory families first, in their own order; everything else keeps its own. */
-  private rank(family: string): number {
-    const index = this.mandatory.indexOf(family)
-
-    return index === -1 ? this.mandatory.length : index
-  }
-}
-
-function options(
-  set: RTD.DirectiveSet,
-  stage: 'precall' | 'settle' | 'explain'
-): SpanOptions {
-  const options: SpanOptions = { name: `${set.family.name} ${stage}` }
-
-  if (set.names !== undefined && set.names.length > 0)
-    options.attributes = { directives: Array.from(new Set(set.names)).join(' ') }
-
-  return options
-}
-
-interface Spans {
-  precall: SpanOptions
-  settle: SpanOptions
-  explain: SpanOptions
-}
-
-interface Stage {
-  family: RTD.DirectiveFamily
-  preflight: SpanOptions
-  depart: SpanOptions
-}
-

package/source/Discovery/Explorer.ts

@@ -1,34 +0,0 @@
-import * as http from '../HTTP/index.js'
-import { BRANCH_TTL } from '@toa.io/definitions/extensions.exposition'
-import { describe } from './tree.js'
-import type { Tree } from '../RTD/index.js'
-
-/**
- * What an application serves, for every route at once. Each entry is what `OPTIONS` on that
- * path answers, so a key taken from here is a request that can be made.
- */
-export class Explorer {
-  private readonly tree: Tree
-
-  public constructor(tree: Tree) {
-    this.tree = tree
-  }
-
-  public async process(context: http.Context): Promise<http.OutgoingMessage> {
-    if (context.request.method !== 'OPTIONS')
-      throw new http.MethodNotAllowed(new Headers({ allow: ALLOW }))
-
-    return {
-      body: await describe(this.tree, context),
-      headers: new Headers({
-        allow: ALLOW,
-        // it stands until a branch expires, and it is filtered by who asked
-        'cache-control': `private, max-age=${BRANCH_TTL / 1000}`,
-        vary: 'authorization'
-      })
-    }
-  }
-}
-
-/** The verbs of this path, which are not the verbs of the tree it answers with. */
-const ALLOW = 'GET, HEAD, OPTIONS'

package/source/Discovery/Site.test.ts

@@ -1,147 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-import { Readable } from 'node:stream'
-import * as path from 'node:path'
-import * as fs from 'node:fs'
-import * as os from 'node:os'
-
-import { Site } from './Site.js'
-import * as http from '../HTTP/index.js'
-import type { Input, Output } from '../io.js'
-
-const root = fs.mkdtempSync(path.join(os.tmpdir(), 'discovery-'))
-
-fs.mkdirSync(path.join(root, '_app', 'immutable'), { recursive: true })
-fs.writeFileSync(path.join(root, 'index.html'), 'the page\n')
-fs.writeFileSync(path.join(root, 'favicon.ico'), 'icon')
-fs.writeFileSync(path.join(root, '_app', 'immutable', 'asset.js'), 'export {}\n')
-
-const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'discovery-empty-'))
-
-const site = new Site(root)
-
-const input = (url: string, method = 'GET'): Input =>
-  ({
-    request: { method, headers: {} },
-    url: new URL(url, 'http://nex.toa.io')
-  }) as unknown as Input
-
-const header = (output: Output, name: string): string | null =>
-  output?.headers?.get(name) ?? null
-
-describe('discovery site', () => {
-  it('should leave a path outside its prefix alone', () => {
-    assert.equal(site.intercept(input('/')), null)
-    assert.equal(site.intercept(input('/pots/')), null)
-  })
-
-  it('should not claim a path that merely starts like its own', () => {
-    assert.equal(site.intercept(input('/.discoveryable/')), null)
-  })
-
-  it('should send the bare path to the directory it is', () => {
-    const output = site.intercept(input('/.discovery'))
-
-    assert.equal(output?.status, 302)
-    assert.equal(header(output, 'location'), '/.discovery/')
-  })
-
-  it('should keep the query when it redirects', () => {
-    const output = site.intercept(input('/.discovery?at=/pots'))
-
-    assert.equal(header(output, 'location'), '/.discovery/?at=/pots')
-  })
-
-  it('should serve the page', () => {
-    const output = site.intercept(input('/.discovery/'))
-
-    assert.equal(output?.status, 200)
-    assert.equal(header(output, 'content-type'), 'text/html; charset=utf-8')
-    assert.equal(header(output, 'cache-control'), 'no-cache')
-  })
-
-  it('should always carry a content-type and a stream', () => {
-    // a stream without one is framed as `multipart/*`, and the page arrives as an envelope
-    for (const url of ['/.discovery/', '/.discovery/_app/immutable/asset.js']) {
-      const output = site.intercept(input(url))
-
-      assert.ok(output?.headers?.has('content-type'), url)
-      assert.ok(output?.body instanceof Readable, url)
-    }
-  })
-
-  it('should hold a hashed asset forever and an icon for a day', () => {
-    assert.equal(
-      header(site.intercept(input('/.discovery/_app/immutable/asset.js')), 'cache-control'),
-      'public, max-age=31536000, immutable'
-    )
-    assert.equal(
-      header(site.intercept(input('/.discovery/favicon.ico')), 'cache-control'),
-      'public, max-age=86400'
-    )
-  })
-
-  it('should fall back to the page for anything that could be a route', () => {
-    const output = site.intercept(input('/.discovery/pots/:id'))
-
-    assert.equal(header(output, 'content-type'), 'text/html; charset=utf-8')
-  })
-
-  it('should refuse an asset that is not there', () => {
-    // a missing asset is missing, however much a route can look like one
-    assert.throws(
-      () => site.intercept(input('/.discovery/_app/immutable/gone.js')),
-      http.NotFound
-    )
-  })
-
-  it('should refuse a path that climbs out of the root', () => {
-    /*
-     * An encoded separator is what reaches here: `..` and `%2e%2e` are dot segments and the
-     * URL parser has already collapsed them, but `%2f` keeps a segment whole through it and
-     * decodes to one afterwards.
-     */
-    for (const url of [
-      '/.discovery/%2f%2e%2e%2f%2e%2e%2fpackage.json',
-      '/.discovery/a%2f..%2f..%2fpackage.json',
-      '/.discovery/%2e%2e%2fpackage.json'
-    ])
-      assert.throws(() => site.intercept(input(url)), http.NotFound, url)
-  })
-
-  it('should never see a dot segment, which the URL parser collapses first', () => {
-    // `/.discovery/%2e%2e/x` is `/x`, which is not this prefix and not ours to answer
-    assert.equal(site.intercept(input('/.discovery/%2e%2e/%2e%2e/package.json')), null)
-    assert.equal(site.intercept(input('/.discovery/../../package.json')), null)
-  })
-
-  it('should report the length a GET would have returned, and open no stream', () => {
-    const output = site.intercept(input('/.discovery/', 'HEAD'))
-
-    assert.equal(output?.status, 200)
-    assert.equal(header(output, 'content-length'), '9')
-    assert.equal(output?.body, undefined)
-  })
-
-  it('should leave OPTIONS on the prefix to the tree', () => {
-    // it needs the identity, which is resolved after this stage
-    assert.equal(site.intercept(input('/.discovery', 'OPTIONS')), null)
-    assert.equal(site.intercept(input('/.discovery/', 'OPTIONS')), null)
-  })
-
-  it('should refuse every other method', () => {
-    assert.throws(() => site.intercept(input('/.discovery/', 'POST')), http.MethodNotAllowed)
-    assert.throws(
-      () => site.intercept(input('/.discovery/favicon.ico', 'OPTIONS')),
-      http.MethodNotAllowed
-    )
-  })
-
-  it('should say so where the page is not built', () => {
-    const output = new Site(empty).intercept(input('/.discovery/'))
-
-    assert.equal(output?.status, 503)
-    assert.equal(header(output, 'content-type'), 'text/plain; charset=utf-8')
-    assert.ok(output?.body instanceof Readable)
-  })
-})