@toa.io/extensions.exposition 1.0.0-alpha.284 → 1.0.0-alpha.286

package/features/rpc.feature

@@ -43,7 +43,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 1, "method": "pots/_id/GET",
+      {"jsonrpc": "2.0", "id": 1, "method": "pots._id.GET",
        "params": {"id": "4c4759e6f9c74da989d64511df42d6f4"}}
       """
     Then the following reply is sent:
@@ -67,7 +67,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 2, "method": "pots/POST",
+      {"jsonrpc": "2.0", "id": 2, "method": "pots.POST",
        "params": {"title": "Kettle", "volume": 1.7}}
       """
     Then the following reply is sent:
@@ -88,7 +88,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 3, "method": "pots/GET",
+      {"jsonrpc": "2.0", "id": 3, "method": "pots.GET",
        "params": {"query": {"limit": 1}}}
       """
     Then the following reply is sent:
@@ -108,7 +108,7 @@ Feature: JSON-RPC
       host: nex.toa.io
       content-type: application/json
 
-      {"jsonrpc": "2.0", "method": "pots/POST", "params": {"title": "Pot", "volume": 1}}
+      {"jsonrpc": "2.0", "method": "pots.POST", "params": {"title": "Pot", "volume": 1}}
       """
     Then the following reply is sent:
       """
@@ -123,7 +123,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 4, "method": "kettles/GET", "params": {}}
+      {"jsonrpc": "2.0", "id": 4, "method": "kettles.GET", "params": {}}
       """
     Then the following reply is sent:
       """
@@ -163,7 +163,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 17, "method": "pots/GET", "params": {}}
+      {"jsonrpc": "2.0", "id": 17, "method": "pots.GET", "params": {}}
       """
     Then the following reply is sent:
       """
@@ -216,7 +216,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 5, "method": "pots/_id/GET", "params": {}}
+      {"jsonrpc": "2.0", "id": 5, "method": "pots._id.GET", "params": {}}
       """
     Then the following reply is sent:
       """
@@ -236,7 +236,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 6, "method": "pots/faulty/GET", "params": {}}
+      {"jsonrpc": "2.0", "id": 6, "method": "pots.faulty.GET", "params": {}}
       """
     Then the following reply is sent:
       """
@@ -256,7 +256,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 7, "method": "pots/guarded/GET", "params": {}}
+      {"jsonrpc": "2.0", "id": 7, "method": "pots.guarded.GET", "params": {}}
       """
     Then the following reply is sent:
       """
@@ -271,10 +271,10 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      [{"jsonrpc": "2.0", "id": 8, "method": "pots/_id/GET",
+      [{"jsonrpc": "2.0", "id": 8, "method": "pots._id.GET",
         "params": {"id": "4c4759e6f9c74da989d64511df42d6f4"}},
-       {"jsonrpc": "2.0", "id": 9, "method": "kettles/GET", "params": {}},
-       {"jsonrpc": "2.0", "method": "pots/POST", "params": {"title": "Pot", "volume": 1}}]
+       {"jsonrpc": "2.0", "id": 9, "method": "kettles.GET", "params": {}},
+       {"jsonrpc": "2.0", "method": "pots.POST", "params": {"title": "Pot", "volume": 1}}]
       """
     Then the following reply is sent:
       """
@@ -299,9 +299,9 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      [{"jsonrpc": "2.0", "id": 13, "method": "pots/GET", "params": {}},
-       {"jsonrpc": "2.0", "id": 14, "method": "pots/GET", "params": {}},
-       {"jsonrpc": "2.0", "id": 15, "method": "pots/GET", "params": {}}]
+      [{"jsonrpc": "2.0", "id": 13, "method": "pots.GET", "params": {}},
+       {"jsonrpc": "2.0", "id": 14, "method": "pots.GET", "params": {}},
+       {"jsonrpc": "2.0", "id": 15, "method": "pots.GET", "params": {}}]
       """
     Then the following reply is sent:
       """
@@ -320,8 +320,8 @@ Feature: JSON-RPC
       host: nex.toa.io
       content-type: application/json
 
-      [{"jsonrpc": "2.0", "method": "pots/POST", "params": {"title": "One", "volume": 1}},
-       {"jsonrpc": "2.0", "method": "pots/POST", "params": {"title": "Two", "volume": 2}}]
+      [{"jsonrpc": "2.0", "method": "pots.POST", "params": {"title": "One", "volume": 1}},
+       {"jsonrpc": "2.0", "method": "pots.POST", "params": {"title": "Two", "volume": 2}}]
       """
     Then the following reply is sent:
       """
@@ -356,7 +356,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "1.0", "id": 10, "method": "pots/GET"}
+      {"jsonrpc": "1.0", "id": 10, "method": "pots.GET"}
       """
     Then the following reply is sent:
       """
@@ -394,8 +394,8 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      [{"jsonrpc": "2.0", "id": 11, "method": "pots/GET", "params": {}},
-       {"jsonrpc": "2.0", "id": 12, "method": "pots/GET", "params": {}}]
+      [{"jsonrpc": "2.0", "id": 11, "method": "pots.GET", "params": {}},
+       {"jsonrpc": "2.0", "id": 12, "method": "pots.GET", "params": {}}]
       """
     Then the following reply is sent:
       """
@@ -421,7 +421,7 @@ Feature: JSON-RPC
       accept: application/yaml
       content-type: application/json
 
-      {"jsonrpc": "2.0", "id": 9, "method": "pots/GET", "params": {}}
+      {"jsonrpc": "2.0", "id": 9, "method": "pots.GET", "params": {}}
       """
     Then the following reply is sent:
       """

package/features/steps/Captures.ts

@@ -5,7 +5,7 @@ const { binding } = tsflow
 
 @binding()
 export class Captures extends http.Captures {
-  public constructor () {
+  public constructor() {
     super(functions)
   }
 }

package/features/steps/Cloudinary.ts

@@ -8,6 +8,5 @@ import { Before } from '@cucumber/cucumber'
  * fresh machine; with one they run, no flag to remember.
  */
 Before({ tags: '@cloudinary' }, function () {
-  if (process.env.CLOUDINARY_ENVIRONMENT === undefined)
-    return 'skipped'
+  if (process.env.CLOUDINARY_ENVIRONMENT === undefined) return 'skipped'
 })

package/features/steps/Common.ts

@@ -9,25 +9,24 @@ const { binding, given } = tsflow
 export class Common {
   private readonly captures: Captures
 
-  public constructor (captures: Captures) {
+  public constructor(captures: Captures) {
     this.captures = captures
   }
 
   @given('after {float} second(s)')
-  public async timeout (interval: number): Promise<void> {
+  public async timeout(interval: number): Promise<void> {
     await timeout(interval * 1000)
   }
 
   @given('the process is running')
-  public async noop (): Promise<void> {
-  }
+  public async noop(): Promise<void> {}
 
   /**
    * A remote resource is whatever it is today. A scenario downloading one compares the reply
    * against what the origin actually serves, not against a literal that goes stale when it changes.
    */
   @given('the length of `{}` is captured as `{word}`')
-  public async length (url: string, name: string): Promise<void> {
+  public async length(url: string, name: string): Promise<void> {
     const response = await fetch(url)
 
     assert.equal(response.status, 200, `${url} answered ${response.status}`)

package/features/steps/Components.ts

@@ -23,18 +23,18 @@ export class Components {
   private readonly gateway: Gateway
   private compositions: Record<string, Connector> = {}
 
-  public constructor (workspace: Workspace, gateway: Gateway) {
+  public constructor(workspace: Workspace, gateway: Gateway) {
     this.workspace = workspace
     this.gateway = gateway
   }
 
   @given('the `{word}` is running')
-  public async run (name: string): Promise<void> {
+  public async run(name: string): Promise<void> {
     await this.runComponent(name)
   }
 
   @given('the `{word}` is running with the following manifest:')
-  public async patchAndRun (name: string, yaml: string): Promise<void> {
+  public async patchAndRun(name: string, yaml: string): Promise<void> {
     const manifest = parse(yaml) as object
 
     await this.runComponent(name, manifest)
@@ -42,7 +42,7 @@ export class Components {
 
   /** One composition, as the explorer hosts them. */
   @given('the introspection components are running')
-  public async runMap (): Promise<void> {
+  public async runMap(): Promise<void> {
     assert.ok(!(MAP in this.compositions), `Composition '${MAP}' is already running`)
 
     this.compositions[MAP] = await boot.composition(map())
@@ -52,8 +52,11 @@ export class Components {
 
   /** The values component, as the configuration extension ships it; the service hosts it alone. */
   @given('the configuration values are running')
-  public async runValues (): Promise<void> {
-    assert.ok(!(VALUES in this.compositions), `Composition '${VALUES}' is already running`)
+  public async runValues(): Promise<void> {
+    assert.ok(
+      !(VALUES in this.compositions),
+      `Composition '${VALUES}' is already running`
+    )
 
     await this.gateway.start()
 
@@ -64,12 +67,12 @@ export class Components {
 
   /** What the deployment would tell the values service, as the scenario needs it. */
   @given('the configuration values are deployed:')
-  public deployValues (yaml: string): void {
+  public deployValues(yaml: string): void {
     process.env.TOA_CONFIGURATION_VALUES = JSON.stringify(parse(yaml))
   }
 
   @given('the `{word}` is stopped')
-  public async stop (name: string): Promise<void> {
+  public async stop(name: string): Promise<void> {
     assert.ok(name in this.compositions, `Composition '${name}' is not running`)
 
     await this.compositions[name].disconnect()
@@ -77,15 +80,17 @@ export class Components {
   }
 
   @after()
-  public async shutdown (): Promise<void> {
-    const promises = Object.values(this.compositions).map((composition) => composition.disconnect())
+  public async shutdown(): Promise<void> {
+    const promises = Object.values(this.compositions).map((composition) =>
+      composition.disconnect()
+    )
 
     await Promise.all(promises)
 
     delete process.env.TOA_CONFIGURATION_VALUES
   }
 
-  private async runComponent (name: string, manifest?: object): Promise<void> {
+  private async runComponent(name: string, manifest?: object): Promise<void> {
     assert.ok(!(name in this.compositions), `Composition '${name}' is already running`)
 
     // the gateway first: a component announces itself when it opens, and that only
@@ -101,7 +106,7 @@ export class Components {
   }
 }
 
-function values (): string {
+function values(): string {
   const root = dirname(require.resolve('@toa.io/extensions.configuration/package.json'))
 
   return join(root, 'components', 'configuration.values')

package/features/steps/Database.ts

@@ -11,66 +11,84 @@ export class Database {
   private static client: MongoClient
 
   @given('the `{word}` database contains:')
-  public async upsert (id: string, table: DataTable): Promise<void> {
+  public async upsert(id: string, table: DataTable): Promise<void> {
     const collection = this.collection(id)
     const columns = table.raw()[0]
     const rows = table.rows()
     const documents: Document[] = []
 
     for (let r = 0; r < rows.length; r++) {
-      const document: Document = {}
+      const document = {} as Document
 
       for (let c = 0; c < columns.length; c++) {
         const str = rows[r][c]
         const int = parseInt(str)
 
-        document[columns[c]] = int.toString() === str
-          ? int
-          : str === 'null'
-            ? null
-            : str === 'true'
-              ? true
-              : str === 'false'
-                ? false
-                : str
+        document[columns[c]] =
+          int.toString() === str
+            ? int
+            : str === 'null'
+              ? null
+              : str === 'true'
+                ? true
+                : str === 'false'
+                  ? false
+                  : str
       }
 
       /*
        * A record that has never been written carries no timestamps, and the entity stamps
        * the ones it is missing as it is read — with the time it was read. The same row then
-       * enumerates differently on every request, which is a moving `etag` and a collection
-       * that is never unmodified.
+       * enumerates differently on every request, which is a `last-modified` that moves and a
+       * collection that is never unmodified.
        */
-      document._created ??= Date.now()
-      document._updated ??= document._created
+      document.CREATED ??= Date.now()
+      document.UPDATED ??= document.CREATED
 
       documents.push(document)
     }
 
-    await collection.deleteMany({})
+    /*
+     * A component the scenario has already started writes to this collection too, and it may
+     * write the very row named here — introspection records a node under the same `_id` this
+     * derives. Emptying the collection and inserting leaves a window for it to land in
+     * between, and the insert then fails on a duplicate key. Replacing each row named, and
+     * deleting only what is not, has no such window.
+     */
+    const ids = documents.map((document) => document._id)
+
+    await collection.deleteMany({ _id: { $nin: ids } })
 
     if (documents.length > 0)
-      await collection.insertMany(documents)
+      await collection.bulkWrite(
+        documents.map((document) => ({
+          replaceOne: {
+            filter: { _id: document._id },
+            replacement: document,
+            upsert: true
+          }
+        }))
+      )
   }
 
   @given('the `{word}` database is empty')
-  public async truncate (id: string): Promise<void> {
+  public async truncate(id: string): Promise<void> {
     await this.collection(id).deleteMany({})
   }
 
   @beforeAll()
-  public static async connect (): Promise<void> {
-    this.client = new MongoClient('mongodb://developer:secret@localhost:27017')
+  public static async connect(): Promise<void> {
+    this.client = new MongoClient('mongodb://developer:secret@localhost:31020')
 
     await this.client.connect()
   }
 
   @afterAll()
-  public static async disconnect (): Promise<void> {
+  public static async disconnect(): Promise<void> {
     await this.client.close()
   }
 
-  private collection (id: string): Collection {
+  private collection(id: string): Collection<Document> {
     const [name, namespace = 'default'] = id.split('.').reverse()
     const collection = `${namespace}_${name}`.toLowerCase()
 
@@ -78,4 +96,5 @@ export class Database {
   }
 }
 
-type Document = Record<string, string | number | boolean | null>
+/** Every fixture table names an `_id`, which is what a row is replaced by. */
+type Document = Record<string, string | number | boolean | null> & { _id: string }

package/features/steps/Gateway.ts

@@ -3,24 +3,24 @@ import tsflow from 'cucumber-tsflow'
 import * as boot from '@toa.io/boot'
 import { type Connector } from '@toa.io/core'
 import { load as parse } from 'js-yaml'
-import { timeout } from '@toa.io/generic'
 import { Factory } from '../../source/index.js'
 import * as syntax from '../../source/RTD/syntax/index.js'
 import { shortcuts } from '../../source/Directive.js'
 import { manifests } from './map.js'
+import { PORT, PROBE } from './Parameters.js'
 import type * as http from '../../source/HTTP/index.js'
 
 const { after, afterAll, binding, given } = tsflow
 
 let instance: Connector | null = null
+let deployment: string | null = null
 
 @binding()
 export class Gateway {
-  private default: boolean = true
   private written: string[] = []
 
   @given('the annotation:')
-  public async annotate (yaml: string): Promise<void> {
+  public async annotate(yaml: string): Promise<void> {
     const annotation = parse(yaml) as Partial<http.Options> & { '/'?: object }
 
     if (annotation['/'] !== undefined) {
@@ -32,32 +32,21 @@ export class Gateway {
     const { debug, authorities, bouncer, ip, oauth, rpc, mcp } = annotation
     const properties = Object.assign({}, DEFAULT_PROPERTIES)
 
-    if (debug !== undefined)
-      properties.debug = debug
+    if (debug !== undefined) properties.debug = debug
 
-    if (bouncer !== undefined)
-      properties.bouncer = bouncer
+    if (bouncer !== undefined) properties.bouncer = bouncer
 
-    if (ip !== undefined)
-      properties.ip = ip
+    if (ip !== undefined) properties.ip = ip
 
-    if (authorities !== undefined)
-      properties.authorities = authorities
+    if (authorities !== undefined) properties.authorities = authorities
 
-    if (oauth !== undefined)
-      properties.oauth = oauth
+    if (oauth !== undefined) properties.oauth = oauth
 
-    if (rpc !== undefined)
-      properties.rpc = rpc
+    if (rpc !== undefined) properties.rpc = rpc
 
-    if (mcp !== undefined)
-      properties.mcp = mcp
+    if (mcp !== undefined) properties.mcp = mcp
 
     process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(properties)
-
-    await Gateway.stop()
-
-    this.default = false
   }
 
   /**
@@ -65,16 +54,17 @@ export class Gateway {
    * exposition extension over them, so what lands here is what a deployment would carry.
    */
   @given('the annotation of the introspection map')
-  public async annotateMap (): Promise<void> {
+  public async annotateMap(): Promise<void> {
     await this.annotateMapUnder()
   }
 
   /** The same routes under a root of the scenario's own: what an application declares around the map. */
   @given('the annotation of the introspection map under:')
-  public async annotateMapUnder (yaml?: string): Promise<void> {
-    const tree: syntax.Node = yaml === undefined
-      ? { routes: [], methods: [], directives: [] }
-      : syntax.parse((parse(yaml) as { '/': object })['/'], shortcuts)
+  public async annotateMapUnder(yaml?: string): Promise<void> {
+    const tree: syntax.Node =
+      yaml === undefined
+        ? { routes: [], methods: [], directives: [] }
+        : syntax.parse((parse(yaml) as { '/': object })['/'], shortcuts)
 
     for (const manifest of await manifests()) {
       const node = manifest.extensions?.[EXPOSITION] as syntax.Node | undefined
@@ -87,14 +77,10 @@ export class Gateway {
 
     process.env.TOA_EXPOSITION = JSON.stringify(tree)
     process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(DEFAULT_PROPERTIES)
-
-    await Gateway.stop()
-
-    this.default = false
   }
 
   @given('the `{word}` configuration:')
-  public async configure (id: string, yaml: string): Promise<void> {
+  public async configure(id: string, yaml: string): Promise<void> {
     const [name, namespace = 'default'] = id.split('.').reverse()
     const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
     const def = DEFAULT_CONFIGURATION[id] ?? {}
@@ -105,90 +91,89 @@ export class Gateway {
     // outlives the secrets it points at, and the next scenario cannot resolve them
     this.written.push(key)
     process.env[key] = JSON.stringify(configuration)
-
-    await Gateway.stop()
-
-    this.default = false
   }
 
   /** The secrets a scenario's configuration refers to. */
   @given('the configuration secrets:')
-  public async secrets (yaml: string): Promise<void> {
+  public async secrets(yaml: string): Promise<void> {
     const secrets = parse(yaml) as Record<string, string>
 
     for (const [name, value] of Object.entries(secrets)) {
       this.written.push(SECRET + name)
       process.env[SECRET + name] = value
     }
-
-    await Gateway.stop()
-
-    this.default = false
   }
 
   @given('the branch TTL is {float} second(s)')
-  public async setBranchTTL (seconds: number): Promise<void> {
+  public async setBranchTTL(seconds: number): Promise<void> {
     process.env.__TESTING_EXPOSITION_BRANCH_TTL = String(seconds * 1000)
-
-    await Gateway.stop()
-
-    this.default = false
   }
 
   @given('the Gateway is running')
-  public async start (): Promise<void> {
-    if (instance !== null)
-      return
-
+  public async start(): Promise<void> {
     process.env.TOA_EXPOSITION ??= DEFAULT_TREE
     process.env.TOA_EXPOSITION_PROPERTIES ??= JSON.stringify(DEFAULT_PROPERTIES)
 
     this.writeConfiguration()
 
+    const signature = Gateway.signature()
+
+    /*
+     * A component is published without restarting the gateway, and a scenario that asks for
+     * the deployment already running gets that one. Only a different deployment is a restart,
+     * which is what an annotation, a configuration or a branch TTL of its own amounts to.
+     */
+    if (instance !== null && signature === deployment) return
+
+    await Gateway.stop()
+
     const factory = new Factory(boot.host())
     const service = await factory.service()
 
-    if (service === null)
-      throw new Error('?')
+    if (service === null) throw new Error('?')
 
     instance = service
 
     await service.connect()
 
-    /*
-     * The gateway waits for the branches it discovers, but a component's own resources —
-     * a storage, a queue — are still connecting when it answers. Fifty milliseconds was
-     * enough until the composition grew; a scenario that asks too early reads the 404 that
-     * precedes the route.
-     */
-    await timeout(DISCOVERY)
+    deployment = signature
+  }
+
+  /** What the running gateway was built from: a different value is a different deployment. */
+  private static signature(): string {
+    const configuration = Object.keys(process.env)
+      .filter((key) => key.startsWith('TOA_CONFIGURATION_'))
+      .sort()
+      .map((key) => [key, process.env[key]])
+
+    return JSON.stringify([
+      process.env.TOA_EXPOSITION,
+      process.env.TOA_EXPOSITION_PROPERTIES,
+      process.env.__TESTING_EXPOSITION_BRANCH_TTL,
+      configuration
+    ])
   }
 
   @after()
-  public async cleanup (): Promise<void> {
+  public async cleanup(): Promise<void> {
     delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
 
-    for (const key of this.written)
-      delete process.env[key]
+    for (const key of this.written) delete process.env[key]
 
     this.written = []
 
-    if (this.default)
-      return
-
     delete process.env.TOA_EXPOSITION
     delete process.env.TOA_EXPOSITION_PROPERTIES
-
-    await Gateway.stop()
   }
 
   @afterAll()
-  public static async stop (): Promise<void> {
+  public static async stop(): Promise<void> {
     await instance?.disconnect()
     instance = null
+    deployment = null
   }
 
-  private writeConfiguration (): void {
+  private writeConfiguration(): void {
     for (const [id, configuration] of Object.entries(DEFAULT_CONFIGURATION)) {
       const [name, namespace = 'default'] = id.split('.').reverse()
       const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
@@ -216,13 +201,12 @@ const DEFAULT_TREE = JSON.stringify({
   ]
 } satisfies syntax.Node)
 
-/** Milliseconds a composition is given to finish connecting what it needs. */
-const DISCOVERY = 100
-
 const DEFAULT_PROPERTIES: Partial<http.Options> = {
   authorities: {
     nex: 'nex.toa.io'
   },
+  port: PORT,
+  probe: PROBE,
   // `npm run features:h2c` runs the whole suite over cleartext HTTP/2
   protocol: process.env.TOA_EXPOSITION_PROTOCOL === 'h2c' ? 'h2c' : 'h1'
 }