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

package/source/Directive.ts

@@ -1,33 +1,97 @@
-import type { Context, OutgoingMessage } from './HTTP'
-import type { Remotes } from './Remotes'
-import type { Output } from './io'
-import type * as RTD from './RTD'
+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[]
 
-  public constructor (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 preflight (context: Context, parameters: RTD.Parameter[]): Promise<Output> {
-    for (const set of this.sets) {
-      if (set.family.preflight === undefined)
-        continue
+  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)
+      )
 
-      const output = await set.family.preflight(set.directives, context, parameters)
+      if (out === null) continue
 
-      if (output !== null)
-        return output
+      if (output !== null) throw new Error('Multiple precall directives responded')
+      else output = out
     }
 
-    return null
+    return output
   }
 
-  public async settle (context: Context, response: OutgoingMessage): Promise<void> {
-    for (const set of this.sets)
+  /**
+   * 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 set.family.settle(set.directives, context, response)
+        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)
   }
 }
 
@@ -35,35 +99,78 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
   private readonly remotes: Remotes
   private readonly families: Record<string, RTD.DirectiveFamily> = {}
   private readonly mandatory: string[] = []
-
-  public constructor (families: RTD.DirectiveFamily[], remotes: Remotes) {
+  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)
+      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
   }
 
-  public create (declarations: RTD.syntax.Directive[]): Directives {
+  /**
+   * 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)
 
-    declarations.sort((a, b) =>
-      (mandatory.has(b.family) ? 1 : 0) - (mandatory.has(a.family) ? 1 : 0))
+    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.`)
+        throw new Error(`Directive family '${declaration.family}' is not found`)
 
-      const directive = family.create(declaration.name, declaration.value, this.remotes)
+      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)
     }
 
@@ -72,25 +179,70 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
     for (const family of mandatory)
       sets.push({
         family: this.families[family],
-        directives: []
+        directives: [],
+        names: []
       })
 
     for (const [family, directives] of Object.entries(groups))
       sets.push({
         family: this.families[family],
-        directives
+        directives,
+        names: names[family]
       })
 
-    return new Directives(sets)
+    // 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
 }
 
-export const shortcuts: RTD.syntax.Shortcuts = new Map([
-  ['anonymous', 'auth:anonymous'],
-  ['id', 'auth:id'],
-  ['role', 'auth:role'],
-  ['rule', 'auth:rule'],
-  ['incept', 'auth:incept'],
-  ['input', 'io:input'],
-  ['output', 'io:output']
-])

package/source/Discovery/Explorer.ts

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,147 @@
+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)
+  })
+})

package/source/Discovery/Site.ts

@@ -0,0 +1,202 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { Readable } from 'node:stream'
+import { console } from 'openspan'
+import * as http from '../HTTP/index.js'
+import { DISCOVERY } from '@toa.io/definitions/extensions.exposition'
+import type { Input, Output } from '../io.js'
+import type { Interceptor } from '../Interception.js'
+
+/**
+ * The page that reads the tree: the directory `ui` builds, and nothing else.
+ *
+ * An interceptor rather than an endpoint, for the reason the OAuth documents are one — it
+ * runs before a credential is resolved. A page is public, and one served after `auth` would
+ * refuse the client holding a stale token, who is the client most likely to have opened it.
+ * It is also what keeps `depart` off these replies: a re-issued credential sets `no-store`,
+ * which would take the build hash off every asset that carries one.
+ *
+ * It claims the whole prefix, so that nothing under it reaches the router — a crawler
+ * asking for assets that are not there would otherwise have every one of them counted as a
+ * route that has gone missing, and ping discovery about it.
+ *
+ * `OPTIONS` on the prefix itself is the exception it lets through: the tree is what answers
+ * there, and that needs the identity this stage does not have yet.
+ */
+export class Site implements Interceptor {
+  public readonly name = 'discovery'
+
+  /** What a test points at a fixture; the build otherwise. */
+  private readonly override: string | undefined
+  private root: string
+
+  public constructor(root?: string) {
+    this.override = root
+    this.root = root ?? site()
+  }
+
+  /**
+   * Resolved here rather than at construction because this is a module singleton, built
+   * when the module loads and before anything has said where the page is. Said once, too,
+   * because a page that is not built is otherwise a `503` per request and nothing else.
+   */
+  public mount(): void {
+    this.root = this.override ?? site()
+
+    if (!isFile(path.join(this.root, 'index.html')))
+      console.warn('Discovery UI is not built', { root: this.root })
+  }
+
+  public intercept(input: Input): Output {
+    const { pathname } = input.url
+
+    if (pathname !== DISCOVERY && !pathname.startsWith(DISCOVERY + '/')) return null
+
+    // the prefix itself, as opposed to something under it
+    const bare = pathname === DISCOVERY || pathname === DISCOVERY + '/'
+    const method = input.request.method
+
+    if (method !== 'GET' && method !== 'HEAD') {
+      // the tree answers here, and it needs the identity this stage does not have yet
+      if (bare && method === 'OPTIONS') return null
+
+      throw new http.MethodNotAllowed(
+        new Headers({ allow: bare ? 'GET, HEAD, OPTIONS' : 'GET, HEAD' })
+      )
+    }
+
+    // the page is a directory, and every asset it names is relative to it
+    if (pathname === DISCOVERY)
+      return {
+        status: 302,
+        headers: new Headers({ location: DISCOVERY + '/' + input.url.search })
+      }
+
+    const file = this.resolve(pathname)
+
+    if (file === null) throw new http.NotFound()
+
+    return this.send(file, method)
+  }
+
+  /**
+   * The file a request lands on, or `null` when nothing does. A path that exists is served
+   * as it is; anything else that could be a route falls back to the page, because the
+   * client router — not this server — knows what routes there are.
+   */
+  private resolve(pathname: string): string | null {
+    /*
+     * Decoded after the prefix is off, so that an encoded separator cannot smuggle a
+     * segment past the test that put us here. A dot segment never arrives — `..` and
+     * `%2e%2e` alike are collapsed while the URL is parsed — but `%2f` survives that and
+     * decodes to a separator here, which is what the guard below is for.
+     */
+    const relative = decode(pathname.slice(DISCOVERY.length))
+
+    if (relative === null || relative.includes('\0')) return null
+
+    const file = path.join(this.root, relative)
+
+    if (file !== this.root && !file.startsWith(this.root + path.sep)) return null
+
+    if (isFile(file)) return file
+
+    /*
+     * A missing asset is missing, but a route can look like one. What this server would
+     * have served is what it knows how to serve, so anything else is a route and falls
+     * back to the page — as does anything ending in a slash, which is no name for a file.
+     */
+    const asset = !relative.endsWith('/') && path.extname(relative) in TYPES
+
+    return asset ? null : path.join(this.root, 'index.html')
+  }
+
+  /**
+   * Always with a `content-type` of its own: a stream without one is framed as
+   * `multipart/*` and the page arrives as an envelope of JSON-encoded buffers.
+   */
+  private send(file: string, method: string): Output {
+    const stats = fs.statSync(file, { throwIfNoEntry: false })
+
+    if (stats === undefined)
+      return {
+        status: 503,
+        headers: new Headers({ 'content-type': 'text/plain; charset=utf-8' }),
+        body: Readable.from([Buffer.from(NOT_BUILT)])
+      }
+
+    const headers = new Headers({
+      'content-type': TYPES[path.extname(file)] ?? 'application/octet-stream',
+      'content-length': String(stats.size),
+      'cache-control': caching(path.relative(this.root, file))
+    })
+
+    // a HEAD reply carries no body but reports the length a GET would have returned; the
+    // HTTP/2 layer does not drop one written to it, so none is opened
+    if (method === 'HEAD') return { status: 200, headers }
+
+    return { status: 200, headers, body: fs.createReadStream(file) }
+  }
+}
+
+const NOT_BUILT = 'The discovery UI is not built. Run `npm run build:ui`.\n'
+
+function decode(pathname: string): string | null {
+  try {
+    return decodeURIComponent(pathname)
+  } catch {
+    return null
+  }
+}
+
+function isFile(file: string): boolean {
+  return fs.statSync(file, { throwIfNoEntry: false })?.isFile() === true
+}
+
+/**
+ * Where `npm run build:ui` puts the page. Two levels up because this module is a directory
+ * deeper than `source` itself, and `transpiled` mirrors that — so it resolves the same from
+ * either. The variable is the features', which run against a fixture rather than a build.
+ */
+function site(): string {
+  return (
+    process.env.__TESTING_EXPOSITION_DISCOVERY_ROOT ??
+    path.resolve(import.meta.dirname, '..', '..', 'ui', 'dist')
+  )
+}
+
+/** Assets under this prefix carry their build hash in the name. */
+const IMMUTABLE = path.join('_app', 'immutable')
+const FOREVER = 'public, max-age=31536000, immutable'
+
+/** The icons: named without a hash, so they are re-read, but rarely. */
+const ICONS = new Set(['favicon.ico', 'favicon-96x96.png', 'apple-touch-icon.png'])
+const DAY = 'public, max-age=86400'
+
+/**
+ * How long what is served may be held. The page is never cached — it names the assets, and
+ * their names carry the build. An icon is named for what it is rather than for its content,
+ * so it is asked about again, but not on every page load.
+ */
+function caching(relative: string): string {
+  if (relative.startsWith(IMMUTABLE)) return FOREVER
+
+  return ICONS.has(relative) ? DAY : 'no-cache'
+}
+
+const TYPES: Record<string, string> = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.webmanifest': 'application/manifest+json',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+}

package/source/Discovery/index.ts

@@ -0,0 +1,3 @@
+export { Explorer } from './Explorer.js'
+export { Site } from './Site.js'
+export { looking } from './trunk.js'