@toa.io/extensions.exposition 1.0.0-alpha.28 → 1.0.0-alpha.283

package/source/io.ts

@@ -1,4 +1,4 @@
-import type { Context, OutgoingMessage } from './HTTP'
+import type { Context, OutgoingMessage } from './HTTP/index.js'
 
 export type Input = Context
 export type Output = OutgoingMessage | null

package/source/manifest.test.ts

@@ -1,6 +1,9 @@
+import { it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
 import { type Manifest } from '@toa.io/norm'
 import { generate } from 'randomstring'
-import { manifest } from './manifest'
+import { manifest } from './manifest.js'
 
 const name = 'cm-' + generate()
 const namespace = 'ns' + generate()
@@ -20,9 +23,9 @@ const declaration = {
 it('should create branch', async () => {
   const node = manifest(declaration, mf)
 
-  expect(node).toBeDefined()
-  expect(node.routes).toHaveLength(1)
-  expect(node.routes[0].path).toBe('/' + namespace + '/' + name)
+  assert.notStrictEqual(node, undefined)
+  assert.strictEqual(node.routes.length, 1)
+  assert.strictEqual(node.routes[0].path, '/' + namespace + '/' + name)
 })
 
 it('should not create node for default namespace', async () => {
@@ -30,13 +33,12 @@ it('should not create node for default namespace', async () => {
 
   const node = manifest(declaration, mf)
 
-  expect(node.routes).toHaveLength(1)
-  expect(node.routes[0].path).toBe('/' + name)
+  assert.strictEqual(node.routes.length, 1)
+  assert.strictEqual(node.routes[0].path, '/' + name)
 })
 
 it('should throw on invalid declaration type', async () => {
-  expect(() => manifest('hello' as unknown as object, mf))
-    .toThrow('Exposition declaration must be an object')
+  assert.throws(() => manifest('hello' as unknown as object, mf), (error: any) => /Exposition declaration must be an object/.test(error.message))
 })
 
 it('should set namespace and component', async () => {
@@ -46,6 +48,6 @@ it('should set namespace and component', async () => {
   const intemediate = root.routes[0].node
   const GET = intemediate.methods[0]
 
-  expect(GET.mapping?.namespace).toBe(namespace)
-  expect(GET.mapping?.component).toBe(name)
+  assert.strictEqual(GET.mapping?.namespace, namespace)
+  assert.strictEqual(GET.mapping?.component, name)
 })

package/source/manifest.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert'
-import { parse, type Node, type Method, type Query } from './RTD/syntax'
-import { shortcuts } from './Directive'
-import * as schemas from './schemas'
+import { parse, type Node, type Method, type Query } from './RTD/syntax/index.js'
+import { shortcuts } from './Directive.js'
+import * as schemas from './schemas.js'
 import type { Manifest } from '@toa.io/norm'
 
 export function manifest (declaration: object, manifest: Manifest): Node {
@@ -12,7 +12,7 @@ export function manifest (declaration: object, manifest: Manifest): Node {
 
   const node = parse(declaration, shortcuts)
 
-  concretize(node, manifest)
+  specify(node, manifest)
   schemas.node.validate(node)
 
   return node
@@ -22,29 +22,28 @@ function wrap (declaration: object, namespace: string, name: string): object {
   const path = (namespace === undefined || namespace === 'default' ? '' : '/' + namespace) +
     '/' + name
 
-  return { [path]: { protected: true, ...declaration } }
+  return { [path]: declaration }
 }
 
-function concretize (node: Node, manifest: Manifest): void {
+function specify (node: Node, manifest: Manifest): void {
   for (const route of node.routes) {
     for (const method of route.node.methods)
-      concretizeMethod(method, manifest)
+      specifyMethod(method, manifest)
 
-    concretize(route.node, manifest)
+    specify(route.node, manifest)
   }
 }
 
-function concretizeMethod (method: Method, manifest: Manifest): void {
-  if (method.mapping === undefined)
+function specifyMethod (method: Method, manifest: Manifest): void {
+  if (method.mapping?.endpoint === undefined)
     return
 
   const operation = manifest.operations[method.mapping.endpoint]
 
-  if (operation === undefined)
-    throw new Error(`Operation '${method.mapping.endpoint}' not found`)
+  assert.ok(operation !== undefined, `Operation '${method.mapping.endpoint}' not found`)
 
-  if (method.mapping.query === undefined && operation.query !== false)
-    method.mapping.query = {} as unknown as Query // schema will substitute default values
+  if (method.mapping.query === undefined)
+    method.mapping.query = operation.query === false ? null : {} as unknown as Query
 
   method.mapping.namespace = manifest.namespace
   method.mapping.component = manifest.name

package/source/octets.d.ts

@@ -0,0 +1,17 @@
+export interface WorkflowInput<
+  TParameters extends Record<string, string> = Record<string, string>,
+  TSteps extends Record<string, unknown> = Record<string, unknown>,
+> {
+  authority: string
+  identity?: string
+  storage: string
+  path: string
+  entry: {
+    id: string
+    type: string
+    size: number
+    meta: Record<string, unknown>
+  }
+  parameters: TParameters
+  steps: TSteps
+}

package/source/redact.test.ts

@@ -0,0 +1,27 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { redact } from './redact.js'
+
+it('should replace credential values at any depth', () => {
+  const input = { input: { username: 'bob', password: 'secret', nested: [{ token: 't' }] }, query: { id: '1' } }
+
+  assert.deepEqual(redact(input), {
+    input: { username: 'bob', password: '[redacted]', nested: [{ token: '[redacted]' }] },
+    query: { id: '1' }
+  })
+})
+
+it('should leave an error and its code alone', () => {
+  const error = Object.assign(new Error('nope'), { code: 'NOT_FOUND' })
+
+  assert.equal(redact(error), error)
+})
+
+it('should not modify the original', () => {
+  const input = { password: 'secret' }
+
+  redact(input)
+
+  assert.equal(input.password, 'secret')
+})

package/source/redact.ts

@@ -0,0 +1,21 @@
+/**
+ * A copy of a request or a reply fit for a log line: the values under the names a
+ * credential travels by are replaced, whatever their depth.
+ */
+export function redact<T> (value: T): T {
+  if (value === null || typeof value !== 'object' || value instanceof Error)
+    return value
+
+  if (Array.isArray(value))
+    return value.map(redact) as T
+
+  const copy: Record<string, unknown> = {}
+
+  for (const [key, item] of Object.entries(value))
+    copy[key] = SENSITIVE.has(key) ? REDACTED : redact(item)
+
+  return copy as T
+}
+
+const SENSITIVE = new Set(['password', 'credentials', 'token', 'key', 'secret', 'code'])
+const REDACTED = '[redacted]'

package/source/root.ts

@@ -1,9 +1,9 @@
-import { decode, merge } from '@toa.io/generic'
-import { syntax } from './RTD'
+import { merge } from '@toa.io/generic'
+import { syntax } from './RTD/index.js'
 
 export function resolve (): syntax.Node {
   const value = process.env.TOA_EXPOSITION
-  const root = value !== undefined ? decode<syntax.Node>(value) : syntax.createNode()
+  const root = value !== undefined ? JSON.parse(value) as syntax.Node : syntax.createNode()
 
   merge(root, PREDEFINED)
 
@@ -21,15 +21,30 @@ const PREDEFINED: syntax.Node = {
           {
             verb: 'GET',
             directives: [
+              {
+                family: 'io',
+                name: 'output',
+                value: ['id', 'roles']
+              },
               {
                 family: 'auth',
                 name: 'echo',
                 value: null
-              },
+              }
+            ]
+          },
+          {
+            verb: 'POST',
+            directives: [
               {
                 family: 'io',
                 name: 'output',
                 value: ['id', 'roles']
+              },
+              {
+                family: 'auth',
+                name: 'incept',
+                value: null
               }
             ]
           }

package/source/schemas.test.ts

@@ -0,0 +1,17 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import * as schemas from './schemas.js'
+
+const authorities = { nex: 'nex.toa.io' }
+
+it('should require ip with bouncer', () => {
+  assert.throws(() => schemas.annotation.validate({ authorities, bouncer: {} }))
+  assert.doesNotThrow(() => schemas.annotation.validate({ authorities, bouncer: {}, ip: 'x-real-ip' }))
+  assert.doesNotThrow(() => schemas.annotation.validate({ authorities, ip: 'x-real-ip' }))
+})
+
+it('should default nothing in bouncer', () => {
+  assert.doesNotThrow(() => schemas.annotation.validate({ authorities, ip: 'x-real-ip', bouncer: { attempts: 5 } }))
+  assert.throws(() => schemas.annotation.validate({ authorities, ip: 'x-real-ip', bouncer: { attempts: 0 } }))
+})

package/source/schemas.ts

@@ -1,11 +1,11 @@
 import { resolve } from 'node:path'
-import schemas from '@toa.io/schemas'
-import type { Query } from './HTTP'
-import type { Node } from './RTD'
+import * as schemas from '@toa.io/schemas'
+import type { Query } from './HTTP/index.js'
+import type { Node } from './RTD/index.js'
 import type { Schema } from '@toa.io/schemas'
-import type { Annotation } from './Annotation'
+import type { Annotation } from './Annotation.js'
 
-const path = resolve(__dirname, '../schemas')
+const path = resolve(import.meta.dirname, '../schemas')
 const namespace = schemas.namespace(path)
 
 export const querystring: Schema<Query> = namespace.schema('querystring')

package/source/userland.ts

@@ -0,0 +1,47 @@
+/**
+ * What Exposition puts into an operation's input, for the operation to be written against.
+ *
+ * The gateway's own types are its business; these are the application's.
+ */
+
+/**
+ * The identity behind the call, as `auth:delegate` embeds it:
+ *
+ * ```yaml
+ * /echo:
+ *   GET:
+ *     auth:assert: true
+ *     auth:delegate: identity
+ *     endpoint: echo
+ * ```
+ *
+ * ```javascript
+ * export async function computation ({ identity }, context) { }
+ * ```
+ */
+export interface Identity {
+  readonly id: string
+
+  /** What the identity holds. Delegation resolves them, so they are always here. */
+  roles: string[]
+
+  permissions?: Record<string, string[]>
+
+  /** How the identity was authenticated; `null` for a transient one. */
+  scheme: string | null
+
+  /** Whether the credentials presented are due to be exchanged. */
+  refresh: boolean
+
+  /** The token's claims, where the identity was federated. */
+  claims?: Claims
+}
+
+/** A federated token's payload: what it must carry, and whatever else the issuer put there. */
+export interface Claims {
+  iss: string
+  sub: string
+  aud?: string | string[]
+
+  [claim: string]: unknown
+}

package/transpiled/Annotation.d.ts

@@ -1,8 +1,46 @@
+import type { Resources } from '@toa.io/operations';
+import type { Protocol } from './HTTP/index.js';
 export interface Annotation {
     authorities: Record<string, string>;
+    /**
+     * `h2c` requires an ingress controller that proxies cleartext HTTP/2 upstream.
+     * See `documentation/protocol.md`.
+     */
+    protocol?: Protocol;
     class?: string;
+    resources?: Resources;
     annotations?: Record<string, string>;
+    /** The Service, as opposed to the Ingress that `annotations` above describes. */
+    service?: {
+        annotations?: Record<string, string>;
+    };
     debug?: boolean;
-    trace?: boolean;
+    /** The header the client address is read from; the connection's without one. See `ip.md`. */
+    ip?: string;
+    /** Failed authentications an address may make; none are metered unless set. See `identity.md`. */
+    bouncer?: Bouncer;
+    /** The authorization server this context exposes; none is exposed without it. */
+    oauth?: OAuth;
     '/'?: object;
 }
+export interface OAuth {
+    /**
+     * Where a client sends the user to consent. The one endpoint of the flow that needs a
+     * person, and so the one this extension does not serve: an application builds it.
+     */
+    authorize: string;
+    /** Paths a token may be restricted to, each advertised as a protected resource. */
+    resources?: string[];
+    /** What a client may ask for. Each is a role, or a scope within one. */
+    scopes?: string[];
+    /** Origins whose Client ID Metadata Documents may be read. None are without it. */
+    trust?: string[];
+    /** Dynamic Client Registration, off unless opened. */
+    registration?: 'open' | 'closed';
+}
+export interface Bouncer {
+    /** what an address may fail at once, 20 by default */
+    attempts?: number;
+    /** seconds it takes to earn them back, 60 by default */
+    interval?: number;
+}

package/transpiled/Annotation.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=Annotation.js.map

package/transpiled/Branch.d.ts

@@ -1,7 +1,31 @@
-import type * as RTD from './RTD/syntax';
+import type * as RTD from './RTD/syntax/index.js';
+import type { Node } from './RTD/index.js';
 export interface Branch {
     namespace: string;
     component: string;
     isolated: boolean;
     node: RTD.Node;
+    version: string;
+    /**
+     * When the tenant that announced it started, by its own clock. A replica on its way
+     * out announces the same component with an older stamp than the one replacing it, and
+     * that is what tells the two apart when their versions differ.
+     */
+    timestamp: number;
 }
+/** A branch the gateway has merged, and the tenant it came from. */
+export interface Exposed {
+    version: string;
+    /** The start time of the tenant this branch came from. */
+    timestamp: number;
+    nodes: Node[];
+}
+/**
+ * What to do with an announcement about a component that already has a branch exposed.
+ *
+ * - `refresh`: the same version, so its expiration is extended and its endpoints left alone
+ * - `superseded`: it came from a tenant that started before the one exposed now
+ * - `merge`: everything else
+ */
+export declare function decide(exposed: Exposed, branch: Branch): Decision;
+export type Decision = 'merge' | 'refresh' | 'superseded';

package/transpiled/Branch.js

@@ -1,3 +1,15 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * What to do with an announcement about a component that already has a branch exposed.
+ *
+ * - `refresh`: the same version, so its expiration is extended and its endpoints left alone
+ * - `superseded`: it came from a tenant that started before the one exposed now
+ * - `merge`: everything else
+ */
+export function decide(exposed, branch) {
+    if (exposed.version === branch.version)
+        return 'refresh';
+    if (branch.timestamp < exposed.timestamp)
+        return 'superseded';
+    return 'merge';
+}
 //# sourceMappingURL=Branch.js.map

package/transpiled/Branch.js.map

@@ -1 +1 @@
-{"version":3,"file":"Branch.js","sourceRoot":"","sources":["../source/Branch.ts"],"names":[],"mappings":""}
+{"version":3,"file":"Branch.js","sourceRoot":"","sources":["../source/Branch.ts"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAE,OAAgB,EAAE,MAAc;IACtD,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO;QACpC,OAAO,SAAS,CAAA;IAElB,IAAI,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS;QACtC,OAAO,YAAY,CAAA;IAErB,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/transpiled/Composition.d.ts

@@ -1,10 +1,9 @@
 import { Connector } from '@toa.io/core';
-import { type Bootloader } from './Factory';
+import { type Host } from './Factory.js';
 export declare class Composition extends Connector {
-    private readonly boot;
-    constructor(boot: Bootloader);
+    private readonly host;
+    constructor(host: Host);
     protected open(): Promise<void>;
-    protected dispose(): void;
 }
 export declare function components(): Components;
 interface Components {

package/transpiled/Composition.js

@@ -1,43 +1,34 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.components = exports.Composition = void 0;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const core_1 = require("@toa.io/core");
-class Composition extends core_1.Connector {
-    boot;
-    constructor(boot) {
+import { readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Connector } from '@toa.io/core';
+export class Composition extends Connector {
+    host;
+    constructor(host) {
         super();
-        this.boot = boot;
+        this.host = host;
     }
     async open() {
         const paths = find();
-        const composition = await this.boot.composition(paths);
+        const composition = await this.host.composition(paths);
         await composition.connect();
         this.depends(composition);
-        console.info('Composition complete.');
-    }
-    dispose() {
-        console.info('Composition shutdown complete.');
     }
 }
-exports.Composition = Composition;
 function find() {
-    return entries().map((entry) => (0, node_path_1.resolve)(ROOT, entry.name));
+    return entries().map((entry) => resolve(ROOT, entry.name));
 }
 function entries() {
-    const entries = (0, node_fs_1.readdirSync)(ROOT, { withFileTypes: true });
+    const entries = readdirSync(ROOT, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory());
 }
-function components() {
+export function components() {
     const labels = [];
     const paths = [];
     for (const entry of entries()) {
         labels.push(entry.name.replace('.', '-'));
-        paths.push((0, node_path_1.resolve)(ROOT, entry.name));
+        paths.push(resolve(ROOT, entry.name));
     }
     return { labels, paths };
 }
-exports.components = components;
-const ROOT = (0, node_path_1.resolve)(__dirname, '../components/');
+const ROOT = resolve(import.meta.dirname, '../components/');
 //# sourceMappingURL=Composition.js.map

package/transpiled/Composition.js.map

@@ -1 +1 @@
-{"version":3,"file":"Composition.js","sourceRoot":"","sources":["../source/Composition.ts"],"names":[],"mappings":";;;AAAA,qCAAkD;AAClD,yCAAmC;AACnC,uCAAwC;AAGxC,MAAa,WAAY,SAAQ,gBAAS;IACvB,IAAI,CAAY;IAEjC,YAAoB,IAAgB;QAClC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,MAAM,KAAK,GAAG,IAAI,EAAE,CAAA;QACpB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;QAEtD,MAAM,WAAW,CAAC,OAAO,EAAE,CAAA;QAE3B,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;QAEzB,OAAO,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAA;IACvC,CAAC;IAEkB,OAAO;QACxB,OAAO,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAA;IAChD,CAAC;CACF;AAtBD,kCAsBC;AAED,SAAS,IAAI;IACX,OAAO,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAA,mBAAO,EAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;AAC5D,CAAC;AAED,SAAS,OAAO;IACd,MAAM,OAAO,GAAG,IAAA,qBAAW,EAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;IAE1D,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;AACvD,CAAC;AAED,SAAgB,UAAU;IACxB,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;QACzC,KAAK,CAAC,IAAI,CAAC,IAAA,mBAAO,EAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC;AAVD,gCAUC;AAOD,MAAM,IAAI,GAAG,IAAA,mBAAO,EAAC,SAAS,EAAE,gBAAgB,CAAC,CAAA"}
+{"version":3,"file":"Composition.js","sourceRoot":"","sources":["../source/Composition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAGxC,MAAM,OAAO,WAAY,SAAQ,SAAS;IACvB,IAAI,CAAM;IAE3B,YAAoB,IAAU;QAC5B,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,MAAM,KAAK,GAAG,IAAI,EAAE,CAAA;QACpB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;QAEtD,MAAM,WAAW,CAAC,OAAO,EAAE,CAAA;QAE3B,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3B,CAAC;CACF;AAED,SAAS,IAAI;IACX,OAAO,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;AAC5D,CAAC;AAED,SAAS,OAAO;IACd,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;IAE1D,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;AACvD,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;QACzC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC;AAOD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAA"}

package/transpiled/Context.d.ts

@@ -1,7 +1,8 @@
-import type * as RTD from './RTD';
-export type Context = RTD.Context<Extension>;
+import type * as RTD from './RTD/index.js';
+export type Context = RTD.Context<Extension | undefined>;
 interface Extension {
     namespace: string;
     component: string;
+    version: string;
 }
 export {};

package/transpiled/Context.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=Context.js.map

package/transpiled/Directive.d.ts

@@ -1,18 +1,26 @@
-import type { Context, OutgoingMessage } from './HTTP';
-import type { Remotes } from './Remotes';
-import type { Output } from './io';
-import type * as RTD from './RTD';
+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 * as RTD from './RTD/index.js';
 export declare class Directives implements RTD.Directives {
     private readonly sets;
+    /** the span of a stage depends only on the set, so it is built once per route */
+    private readonly spans;
     constructor(sets: RTD.DirectiveSet[]);
     preflight(context: Context, parameters: RTD.Parameter[]): Promise<Output>;
     settle(context: Context, response: OutgoingMessage): Promise<void>;
+    dispose(): void;
 }
 export declare class DirectivesFactory implements RTD.DirectiveFactory {
     private readonly remotes;
     private readonly families;
     private readonly mandatory;
-    constructor(families: RTD.DirectiveFamily[], remotes: Remotes);
-    create(declarations: RTD.syntax.Directive[]): Directives;
+    private readonly instances;
+    constructor(families: RTD.DirectiveFamily[], remotes: Remotes, host: Host, options: Options);
+    create(declarations: RTD.syntax.Directive[], route?: string): Directives;
+    dispose(): void;
+    /** Mandatory families first, in their own order; everything else keeps its own. */
+    private rank;
 }
 export declare const shortcuts: RTD.syntax.Shortcuts;