@toa.io/extensions.exposition 1.0.0-alpha.271 → 1.0.0-alpha.273

package/schemas/octets/put.cos.yaml

@@ -18,11 +18,14 @@ properties:
       type: string
   workflow:
     anyOf:
-      - &unit
-        type: object
+      - type: object
         patternProperties:
           ^.+$:
             type: string
       - type: array
-        items: *unit
+        items:
+          type: object
+          patternProperties:
+            ^.+$:
+              type: string
 additionalProperties: false

package/schemas/octets/workflow.cos.yaml

@@ -4,7 +4,6 @@ definitions:
     patternProperties:
       ^[a-zA-Z0-9_]+$:
         type: string
-
 oneOf:
   - $ref: '#/definitions/unit'
   - type: array

package/schemas/query.cos.yaml

@@ -1,14 +1,31 @@
-id?: string
-criteria?: string
-sort?: string
-search?: boolean
-sample?: integer
-omit?:
-  $ref: range
-limit?:
-  $ref: range
-selectors?: [string]
-projection?: [string]
-parameters?: [string]
-deleted?: boolean
-_: true
+properties:
+  id:
+    type: string
+  criteria:
+    type: string
+  sort:
+    type: string
+  search:
+    type: boolean
+  sample:
+    type: integer
+  omit:
+    $ref: range
+  limit:
+    $ref: range
+  selectors:
+    type: array
+    items:
+      type: string
+  projection:
+    type: array
+    items:
+      type: string
+  parameters:
+    type: array
+    items:
+      type: string
+  deleted:
+    type: boolean
+nullable: true
+type: object

package/schemas/querystring.cos.yaml

@@ -1,7 +1,19 @@
-id: string
-criteria: string
-search: string
-sort: string
-omit: number
-limit: number
-version: number
+properties:
+  id:
+    type: string
+  criteria:
+    type: string
+  search:
+    type: string
+  sample:
+    type: number
+  sort:
+    type: string
+  omit:
+    type: number
+  limit:
+    type: number
+  version:
+    type: number
+additionalProperties: false
+type: object

package/schemas/range.cos.yaml

@@ -1,2 +1,10 @@
-value?: number
-range: [number]
+properties:
+  range:
+    type: array
+    items:
+      type: number
+  value:
+    type: number
+type: object
+required:
+  - range

package/schemas/route.cos.yaml

@@ -1,2 +1,6 @@
-path: string
-node: ref:node
+properties:
+  path:
+    type: string
+  node:
+    $ref: node
+type: object

package/source/Branch.test.ts

@@ -0,0 +1,37 @@
+import { decide } from './Branch'
+import type { Branch, Exposed } from './Branch'
+
+function branch (version: string, timestamp: number): Branch {
+  return {
+    namespace: 'default',
+    component: 'one',
+    isolated: false,
+    node: { routes: [], methods: [], directives: [] },
+    version,
+    timestamp
+  }
+}
+
+function exposed (version: string, timestamp: number): Exposed {
+  return { version, timestamp, nodes: [] }
+}
+
+it('should refresh the same version', () => {
+  expect(decide(exposed('a', 1), branch('a', 2))).toStrictEqual('refresh')
+})
+
+it('should refresh the same version announced by an older tenant', () => {
+  expect(decide(exposed('a', 2), branch('a', 1))).toStrictEqual('refresh')
+})
+
+it('should merge a newer tenant', () => {
+  expect(decide(exposed('a', 1), branch('b', 2))).toStrictEqual('merge')
+})
+
+it('should not merge a tenant that started earlier', () => {
+  expect(decide(exposed('b', 2), branch('a', 1))).toStrictEqual('superseded')
+})
+
+it('should merge when tenants started at the same time', () => {
+  expect(decide(exposed('a', 1), branch('b', 1))).toStrictEqual('merge')
+})

package/source/Branch.ts

@@ -1,4 +1,5 @@
 import type * as RTD from './RTD/syntax'
+import type { Node } from './RTD'
 
 export interface Branch {
   namespace: string
@@ -6,4 +7,40 @@ export interface Branch {
   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 function decide (exposed: Exposed, branch: Branch): Decision {
+  if (exposed.version === branch.version)
+    return 'refresh'
+
+  if (branch.timestamp < exposed.timestamp)
+    return 'superseded'
+
+  return 'merge'
+}
+
+export type Decision = 'merge' | 'refresh' | 'superseded'

package/source/Factory.ts

@@ -1,7 +1,6 @@
 import assert from 'node:assert'
 import { createHash } from 'node:crypto'
 import { console, traces, type LevelName, type TracesOptions } from 'openspan'
-import { decode } from '@toa.io/generic'
 import { Tenant } from './Tenant'
 import { Gateway } from './Gateway'
 import { Remotes } from './Remotes'
@@ -29,7 +28,8 @@ export class Factory implements extensions.Factory {
     const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id)
     const hash = createHash('sha256').update(JSON.stringify(node)).digest('hex')
 
-    const branch: Branch = {
+    // no timestamp: the tenant stamps each announcement with its own start time
+    const branch: Omit<Branch, 'timestamp'> = {
       namespace: locator.namespace,
       component: locator.name,
       isolated: locator.namespace === 'identity',
@@ -46,7 +46,7 @@ export class Factory implements extensions.Factory {
 
     configureLogs()
 
-    const options = decode<http.Options>(process.env.TOA_EXPOSITION_PROPERTIES)
+    const options = JSON.parse(process.env.TOA_EXPOSITION_PROPERTIES) as http.Options
     const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL)
     const server = http.Server.create({ ...options })
     const remotes = new Remotes(this.boot)
@@ -76,13 +76,13 @@ const TRACES_ENV = 'TOA_TELEMETRY_TRACES'
 function configureLogs (): void {
   const globEnv = process.env[LOGS_PREFIX]
   const level: LevelName = process.env.TOA_DEV === '1' ? 'trace' : 'info'
-  const options = globEnv === undefined ? { level } : decode<{ level?: LevelName }>(globEnv)
+  const options = globEnv === undefined ? { level } : JSON.parse(globEnv) as { level?: LevelName }
 
   console.configure({ level: options.level ?? level })
 
   const tracesEnv = process.env[TRACES_ENV]
 
-  traces(tracesEnv === undefined ? development() : decode<TracesOptions>(tracesEnv))
+  traces(tracesEnv === undefined ? development() : JSON.parse(tracesEnv) as TracesOptions)
 }
 
 /**

package/source/Gateway.ts

@@ -4,10 +4,11 @@ import { console } from 'openspan'
 import { type bindings, Connector } from '@toa.io/core'
 import * as http from './HTTP'
 import { rethrow } from './exceptions'
+import { decide } from './Branch'
 import type { Interception } from './Interception'
 import type { Method, Node, Parameter, Tree, Match } from './RTD'
 import type { Label } from './discovery'
-import type { Branch } from './Branch'
+import type { Branch, Exposed } from './Branch'
 
 export class Gateway extends Connector {
   private readonly broadcast: Broadcast
@@ -70,11 +71,19 @@ export class Gateway extends Connector {
     console.info('Gateway started')
   }
 
-  protected override dispose (): void {
+  /**
+   * Both of these reach into components, and a dependency is torn down only once this has
+   * returned — where `dispose` runs after every one of them already has. The throttling
+   * ticker firing in between calls an endpoint that has just been unbound, and reports the
+   * refusal as a failure to reconcile.
+   */
+  protected override async close (): Promise<void> {
     this.stopped = true
 
     this.tree.dispose()
+  }
 
+  protected override dispose (): void {
     console.info('Gateway is closed')
   }
 
@@ -223,13 +232,24 @@ export class Gateway extends Connector {
 
     const exposed = this.branches.get(id)
 
-    // rebuilding an identical branch would only tear down its live endpoints
-    if (exposed?.version === branch.version) {
-      this.tree.refresh(exposed.nodes)
-      console.debug('Branch refreshed', attributes)
+    if (exposed !== undefined)
+      switch (decide(exposed, branch)) {
+        // rebuilding an identical branch would only tear down its live endpoints
+        case 'refresh':
+          this.tree.refresh(exposed.nodes)
+          console.trace('Branch refreshed', attributes)
 
-      return
-    }
+          return
+
+        case 'superseded':
+          console.debug('Branch superseded', {
+            ...attributes,
+            timestamp: branch.timestamp,
+            exposed: exposed.timestamp
+          })
+
+          return
+      }
 
     let nodes: Node[]
 
@@ -243,7 +263,7 @@ export class Gateway extends Connector {
       return
     }
 
-    this.branches.set(id, { version: branch.version, nodes })
+    this.branches.set(id, { version: branch.version, timestamp: branch.timestamp, nodes })
 
     if (this.lastMerge !== 0)
       this.widestGap = Math.max(this.widestGap, Date.now() - this.lastMerge)
@@ -258,11 +278,6 @@ export class Gateway extends Connector {
 
 export type Broadcast = bindings.Broadcast<Label>
 
-interface Exposed {
-  version: string
-  nodes: Node[]
-}
-
 const SETTLE_QUIET_MIN = 500
 const SETTLE_QUIET_MAX = 10_000
 const SETTLE_QUIET_FACTOR = 2

package/source/HTTP/formats/yaml.test.ts

@@ -1,8 +1,10 @@
-import { Err } from 'error-value'
 import { encode } from './yaml'
 
 it('encodes error values as their public properties', () => {
-  const value = new Err('INVALID_USERNAME', 'Username is not meeting the requirements')
+  const value = new (class InvalidUsernameError extends Error {
+    public readonly code = 'INVALID_USERNAME'
+    public override readonly message = 'Username is not meeting the requirements'
+  })()
 
   expect(encode(value).toString())
     .toBe('code: INVALID_USERNAME\nmessage: Username is not meeting the requirements\n')

package/source/RTD/Tree.ts

@@ -59,7 +59,10 @@ export class Tree {
       endpoints: this.endpoints,
       directives: {
         factory: this.directives,
-        stack: this.root.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

package/source/Tenant.ts

@@ -7,11 +7,11 @@ import type { Branch } from './Branch'
 
 export class Tenant extends Connector {
   private readonly broadcast: Broadcast
-  private readonly branch: Branch
+  private readonly branch: Omit<Branch, 'timestamp'>
   private started = 0
   private stopped = false
 
-  public constructor (broadcast: Broadcast, branch: Branch) {
+  public constructor (broadcast: Broadcast, branch: Omit<Branch, 'timestamp'>) {
     super()
 
     this.broadcast = broadcast
@@ -29,7 +29,13 @@ export class Tenant extends Connector {
     void this.announce()
   }
 
-  protected override dispose (): void {
+  /**
+   * Announcing is stopped where the teardown begins, not in `dispose`, which a connector
+   * runs after every one of its dependencies has gone. A component on its way out that
+   * announces itself once more has its routes held open by whoever is listening, and the
+   * requests that follow reach nothing.
+   */
+  protected override async close (): Promise<void> {
     this.stopped = true
   }
 
@@ -47,7 +53,12 @@ export class Tenant extends Connector {
   }
 
   private async expose (): Promise<void> {
-    await this.broadcast.transmit('expose', this.branch)
+    // the ping subscription outlives the announcing loop, and answering one on the way out
+    // is the same announcement by another route
+    if (this.stopped)
+      return
+
+    await this.broadcast.transmit('expose', { ...this.branch, timestamp: this.started })
   }
 }
 

package/source/deployment.ts

@@ -1,6 +1,5 @@
 import assert from 'node:assert'
 import { type Dependency, type Service } from '@toa.io/operations'
-import { encode } from '@toa.io/generic'
 import { type Annotation } from './Annotation'
 import * as schemas from './schemas'
 import { shortcuts } from './Directive'
@@ -35,7 +34,7 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
 
     service.variables!.push({
       name: 'TOA_EXPOSITION',
-      value: encode(tree)
+      value: JSON.stringify(tree)
     })
   }
 
@@ -57,13 +56,13 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
 
   service.variables!.push({
     name: 'TOA_EXPOSITION_PROPERTIES',
-    value: encode(properties)
+    value: JSON.stringify(properties)
   })
 
   // Nested identity composition shares this process; gateway already exposes /.ready.
   service.variables!.push({
     name: 'TOA_TELEMETRY_READY',
-    value: encode(false)
+    value: JSON.stringify(false)
   })
 
   return { services: [service] }

package/source/directives/io/IO.ts

@@ -11,7 +11,7 @@ export class IO implements DirectiveFamily<Directive> {
   public readonly name = 'io'
   public readonly mandatory = true
 
-  /** Throttling reconciles through a component, because only a component has a stash aspect. */
+  /** Throttling reconciles through a component, because only a component has an atom aspect. */
   private sync: Sync | null = null
 
   // eslint-disable-next-line max-params
@@ -25,7 +25,7 @@ export class IO implements DirectiveFamily<Directive> {
 
     // discovering boots the component, so nothing is discovered until something throttles
     if (name === 'throttle')
-      this.sync ??= new Sync(remotes.discover('exposition', 'stash'))
+      this.sync ??= new Sync(remotes.discover('exposition', 'atom'))
 
     return new Directive(value, this.sync!, route)
   }

package/source/directives/io/lib/throttle/Sync.ts

@@ -11,7 +11,7 @@ import type { Remote } from '@toa.io/core'
  * the debt the whole group has reached, which the quotas then decide on locally.
  */
 export class Sync {
-  private readonly stash: Promise<Remote>
+  private readonly atom: Promise<Remote>
   private readonly quotas: Quotas[] = []
   private remote: Remote | null = null
   private timer: NodeJS.Timeout | null = null
@@ -20,8 +20,8 @@ export class Sync {
   /** Ticks do not overlap: a slow round trip delays reconciling, it does not double it. */
   private reconciling = false
 
-  public constructor (stash: Promise<Remote>) {
-    this.stash = stash
+  public constructor (atom: Promise<Remote>) {
+    this.atom = atom
   }
 
   public register (quotas: Quotas): void {
@@ -74,7 +74,7 @@ export class Sync {
 
   private async reconcile (batch: Batch[]): Promise<void> {
     try {
-      this.remote ??= await this.stash
+      this.remote ??= await this.atom
 
       const keys = batch.map((entry) => entry.quotas.name(entry.key))
       const deltas = batch.map((entry) => entry.delta)

package/source/directives/map/Headers.ts

@@ -3,6 +3,13 @@ import { cors } from '../cors'
 import { Mapping } from './Mapping'
 import type { Input } from '../../io'
 
+/**
+ * Forbidden request header names: the browser sets them itself and a script cannot
+ * list them in `Access-Control-Request-Headers`, so there is nothing to advertise
+ * or vary on. The value is still read, it just never reaches CORS.
+ */
+const FORBIDDEN = new Set(['host', 'origin'])
+
 export class Headers extends Mapping<Record<string, string>> {
   private readonly headers: string[]
 
@@ -14,7 +21,7 @@ export class Headers extends Mapping<Record<string, string>> {
 
     super(map)
 
-    this.headers = Object.values(map).filter((header) => header !== 'host')
+    this.headers = Object.values(map).filter((header) => !FORBIDDEN.has(header))
     this.headers.forEach((header) => cors.allow(header))
   }
 

package/source/directives/octets/Put.ts

@@ -11,7 +11,6 @@ import type { Parameter } from '../../RTD'
 import type { Unit, Location } from './workflows'
 import type { Entry } from '@toa.io/extensions.storages'
 import type { Remotes } from '../../Remotes'
-import type { Err } from 'error-value'
 import type { Component } from '@toa.io/core'
 import type { Output } from '../../io'
 import type { Input } from './types'
@@ -73,7 +72,7 @@ export class Put extends Directive {
     const entry = await this.storage.invoke<Entry>('put', request)
 
     return match<Output>(entry,
-      Error, (error: Err) => this.throw(error),
+      Error, (error: CodedError) => this.throw(error),
       () => this.reply(input, storage, entry, parameters))
   }
 
@@ -104,7 +103,7 @@ export class Put extends Directive {
     return stream
   }
 
-  private throw (error: Err): never {
+  private throw (error: CodedError): never {
     throw match(error.code,
       'NOT_ACCEPTABLE', () => new http.UnsupportedMediaType(),
       'TYPE_MISMATCH', () => new http.BadRequest(),
@@ -136,3 +135,7 @@ interface StoreRequest {
     attributes?: Record<string, string>
   }
 }
+
+interface CodedError extends Error {
+  code: string
+}

package/source/root.ts

@@ -1,9 +1,9 @@
-import { decode, merge } from '@toa.io/generic'
+import { merge } from '@toa.io/generic'
 import { syntax } from './RTD'
 
 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)
 

package/transpiled/Branch.d.ts

@@ -1,8 +1,31 @@
 import type * as RTD from './RTD/syntax';
+import type { Node } from './RTD';
 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,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.decide = void 0;
+/**
+ * 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
+ */
+function decide(exposed, branch) {
+    if (exposed.version === branch.version)
+        return 'refresh';
+    if (branch.timestamp < exposed.timestamp)
+        return 'superseded';
+    return 'merge';
+}
+exports.decide = decide;
 //# 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,SAAgB,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;AARD,wBAQC"}

package/transpiled/Factory.js

@@ -30,7 +30,6 @@ exports.Factory = void 0;
 const node_assert_1 = __importDefault(require("node:assert"));
 const node_crypto_1 = require("node:crypto");
 const openspan_1 = require("openspan");
-const generic_1 = require("@toa.io/generic");
 const Tenant_1 = require("./Tenant");
 const Gateway_1 = require("./Gateway");
 const Remotes_1 = require("./Remotes");
@@ -50,6 +49,7 @@ class Factory {
     tenant(locator, node) {
         const broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id);
         const hash = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(node)).digest('hex');
+        // no timestamp: the tenant stamps each announcement with its own start time
         const branch = {
             namespace: locator.namespace,
             component: locator.name,
@@ -62,7 +62,7 @@ class Factory {
     service() {
         node_assert_1.default.ok(process.env.TOA_EXPOSITION_PROPERTIES, 'TOA_EXPOSITION_PROPERTIES is undefined');
         configureLogs();
-        const options = (0, generic_1.decode)(process.env.TOA_EXPOSITION_PROPERTIES);
+        const options = JSON.parse(process.env.TOA_EXPOSITION_PROPERTIES);
         const broadcast = this.boot.bindings.broadcast(CHANNEL);
         const server = http.Server.create({ ...options });
         const remotes = new Remotes_1.Remotes(this.boot);
@@ -87,10 +87,10 @@ const TRACES_ENV = 'TOA_TELEMETRY_TRACES';
 function configureLogs() {
     const globEnv = process.env[LOGS_PREFIX];
     const level = process.env.TOA_DEV === '1' ? 'trace' : 'info';
-    const options = globEnv === undefined ? { level } : (0, generic_1.decode)(globEnv);
+    const options = globEnv === undefined ? { level } : JSON.parse(globEnv);
     openspan_1.console.configure({ level: options.level ?? level });
     const tracesEnv = process.env[TRACES_ENV];
-    (0, openspan_1.traces)(tracesEnv === undefined ? development() : (0, generic_1.decode)(tracesEnv));
+    (0, openspan_1.traces)(tracesEnv === undefined ? development() : JSON.parse(tracesEnv));
 }
 /**
  * Tracing is off unless it is configured. The console exporter is a local development