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

package/features/steps/Database.ts

@@ -1,60 +1,98 @@
-import { afterAll, beforeAll, binding, given } from 'cucumber-tsflow'
+import tsflow from 'cucumber-tsflow'
+
 import { MongoClient } from 'mongodb'
 import type { Collection } from 'mongodb'
 import type { DataTable } from '@cucumber/cucumber'
 
+const { afterAll, beforeAll, binding, given } = tsflow
+
 @binding()
 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
+        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 `last-modified` that moves and a
+       * collection that is never unmodified.
+       */
+      document.CREATED ??= Date.now()
+      document.UPDATED ??= document.CREATED
+
+      // a table states a timestamp as the entity carries it; the storage holds it as a date
+      for (const name of TIMESTAMPS)
+        if (typeof document[name] === 'number') document[name] = new Date(document[name])
+
       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()
 
@@ -62,4 +100,7 @@ export class Database {
   }
 }
 
-type Document = Record<string, string | number | null>
+const TIMESTAMPS = ['CREATED', 'UPDATED', 'DELETED']
+
+/** Every fixture table names an `_id`, which is what a row is replaced by. */
+type Document = Record<string, string | number | boolean | Date | null> & { _id: string }

package/features/steps/Gateway.ts

@@ -1,113 +1,197 @@
-import { after, afterAll, binding, given } from 'cucumber-tsflow'
+import tsflow from 'cucumber-tsflow'
+
 import * as boot from '@toa.io/boot'
 import { type Connector } from '@toa.io/core'
-import { parse } from '@toa.io/yaml'
-import { encode, timeout } from '@toa.io/generic'
-import { Factory } from '../../source'
-import * as syntax from '../../source/RTD/syntax'
-import { shortcuts } from '../../source/Directive'
-import type * as http from '../../source/HTTP'
+import { environment } from '@toa.io/generic'
+
+import { load as parse } from 'js-yaml'
+import { Factory } from '../../source/index.js'
+import * as syntax from '../../source/RTD/syntax/index.js'
+import { shortcuts } from '../../source/shortcuts.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> {
-    const annotation = parse(yaml)
+  public async annotate(yaml: string): Promise<void> {
+    const annotation = parse(yaml) as Partial<http.Options> & { '/'?: object }
 
-    if ('/' in annotation) {
+    if (annotation['/'] !== undefined) {
       const tree = syntax.parse(annotation['/'], shortcuts)
 
-      process.env.TOA_EXPOSITION = encode(tree)
+      environment.set('TOA_EXPOSITION', JSON.stringify(tree))
     }
 
-    const { debug, trace, authorities } = annotation
+    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 (trace !== undefined)
-      properties.trace = trace
+    if (bouncer !== undefined) properties.bouncer = bouncer
 
-    if (authorities !== undefined)
-      properties.authorities = authorities
+    if (ip !== undefined) properties.ip = ip
 
-    process.env.TOA_EXPOSITION_PROPERTIES = encode(properties)
+    if (authorities !== undefined) properties.authorities = authorities
 
-    await Gateway.stop()
+    if (oauth !== undefined) properties.oauth = oauth
+
+    if (rpc !== undefined) properties.rpc = rpc
+
+    if (mcp !== undefined) properties.mcp = mcp
+
+    environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(properties))
+  }
+
+  /**
+   * The routes of the introspection map, taken from its own manifests. `norm` runs the
+   * 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> {
+    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)
+
+    for (const manifest of await manifests()) {
+      const node = manifest.extensions?.[EXPOSITION] as syntax.Node | undefined
 
-    this.default = false
+      if (node === undefined)
+        throw new Error(`'${manifest.namespace}.${manifest.name}' declares no exposition`)
+
+      tree.routes.push(...node.routes)
+    }
+
+    environment.set('TOA_EXPOSITION', JSON.stringify(tree))
+    environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(DEFAULT_PROPERTIES))
   }
 
   @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] ?? {}
-    const patch: object = parse(yaml)
+    const patch = parse(yaml) as object
     const configuration = Object.assign({}, def, patch)
 
-    process.env[key] = encode(configuration)
+    // scenario-scoped, as the secrets it may refer to are: a configuration left behind
+    // outlives the secrets it points at, and the next scenario cannot resolve them
+    this.written.push(key)
+    environment.set(key, JSON.stringify(configuration))
+  }
 
-    await Gateway.stop()
+  /** The secrets a scenario's configuration refers to. */
+  @given('the configuration secrets:')
+  public async secrets(yaml: string): Promise<void> {
+    const secrets = parse(yaml) as Record<string, string>
 
-    this.default = false
+    for (const [name, value] of Object.entries(secrets)) {
+      this.written.push(SECRET + name)
+      environment.set(SECRET + name, value)
+    }
+  }
+
+  @given('the branch TTL is {float} second(s)')
+  public async setBranchTTL(seconds: number): Promise<void> {
+    process.env.__TESTING_EXPOSITION_BRANCH_TTL = String(seconds * 1000)
   }
 
   @given('the Gateway is running')
-  public async start (): Promise<void> {
-    if (instance !== null)
-      return
+  public async start(): Promise<void> {
+    if (!environment.has('TOA_EXPOSITION'))
+      environment.set('TOA_EXPOSITION', DEFAULT_TREE)
 
-    process.env.TOA_EXPOSITION ??= DEFAULT_TREE
-    process.env.TOA_EXPOSITION_PROPERTIES ??= encode(DEFAULT_PROPERTIES)
+    if (!environment.has('TOA_EXPOSITION_PROPERTIES'))
+      environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(DEFAULT_PROPERTIES))
 
     this.writeConfiguration()
 
-    const factory = new Factory(boot)
-    const service = factory.service()
+    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()
 
-    if (service === null)
-      throw new Error('?')
+    const factory = new Factory(boot.host())
+    const service = await factory.service()
+
+    if (service === null) throw new Error('?')
 
     instance = service
 
     await service.connect()
-    await timeout(50) // resource discovery
+
+    deployment = signature
+  }
+
+  /** What the running gateway was built from: a different value is a different deployment. */
+  private static signature(): string {
+    const configuration = Object.entries(environment.entries('TOA_CONFIGURATION_')).sort()
+
+    return JSON.stringify([
+      environment.get('TOA_EXPOSITION'),
+      environment.get('TOA_EXPOSITION_PROPERTIES'),
+      process.env.__TESTING_EXPOSITION_BRANCH_TTL,
+      configuration
+    ])
   }
 
   @after()
-  public async cleanup (): Promise<void> {
-    if (this.default)
-      return
+  public async cleanup(): Promise<void> {
+    delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
 
-    delete process.env.TOA_EXPOSITION
-    delete process.env.TOA_EXPOSITION_PROPERTIES
+    for (const key of this.written) environment.delete(key)
 
-    await Gateway.stop()
+    this.written = []
+
+    environment.delete('TOA_EXPOSITION')
+    environment.delete('TOA_EXPOSITION_PROPERTIES')
   }
 
   @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()}`
 
-      process.env[key] ??= encode(configuration)
+      if (!environment.has(key)) environment.set(key, JSON.stringify(configuration))
     }
+
+    for (const [name, value] of Object.entries(DEFAULT_SECRETS))
+      if (!environment.has(SECRET + name)) environment.set(SECRET + name, value)
   }
 }
 
-const DEFAULT_TREE = encode({
+const EXPOSITION = '@toa.io/extensions.exposition'
+const SECRET = 'TOA_CONFIGURATION__'
+
+const DEFAULT_TREE = JSON.stringify({
   routes: [],
   methods: [],
   directives: [
@@ -122,11 +206,35 @@ const DEFAULT_TREE = encode({
 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: environment.get('TOA_EXPOSITION_PROTOCOL') === 'h2c' ? 'h2c' : 'h1'
 }
 
+// the identity components boot inside the gateway, and without a variable each would wait
+// for the values service, which these features do not run
 const DEFAULT_CONFIGURATION: Record<string, object> = {
+  // a component declaring configuration waits for `configuration.values`, which these
+  // features do not run; the variable is the local override that stands in for it
+  'realtime.streams': {},
+  'identity.basic': {},
+  'identity.clients': {},
+  'identity.grants': {},
+  'identity.federation': {},
+  'identity.otp': {},
+  'identity.passkeys': {},
   'identity.tokens': {
-    key0: 'k3.local.pIZT8-9Fa6U_QtfQHOSStfGtmyzPINyKQq2Xk-hd7vA'
+    keys: [
+      { id: 'key0', key: '$IDENTITY_TOKENS_KEY0' },
+      { id: 'legacy0', key: '$IDENTITY_TOKENS_LEGACY0', format: 'paseto' }
+    ]
   }
 }
+
+// a secret is given as a reference, and comes to the component as an object
+const DEFAULT_SECRETS: Record<string, string> = {
+  IDENTITY_TOKENS_KEY0: 'sTxL6qVOadKkUJwh3FveU53XgTEo3Sdfg7k2FfiIKfs',
+  IDENTITY_TOKENS_LEGACY0: 'k3.local.pIZT8-9Fa6U_QtfQHOSStfGtmyzPINyKQq2Xk-hd7vA'
+}

package/features/steps/HTTP.ts

@@ -1,54 +1,56 @@
 import * as assert from 'node:assert'
 import * as fs from 'node:fs'
 import * as path from 'node:path'
-import { binding, then, when } from 'cucumber-tsflow'
+import tsflow from 'cucumber-tsflow'
+
 import * as http from '@toa.io/agent'
 import * as msgpack from 'msgpackr'
 import * as YAML from 'js-yaml'
-import { Captures } from './Captures'
-import { Parameters } from './Parameters'
-import { Gateway } from './Gateway'
+import { Captures } from './Captures.js'
+import { Parameters } from './Parameters.js'
+import { Gateway } from './Gateway.js'
 import type { Readable } from 'node:stream'
 
+const { binding, then, when } = tsflow
+
 @binding([Gateway, Parameters, Captures])
 export class HTTP extends http.Agent {
   private readonly gateway: Gateway
-  private fetched: Response | null = null
 
-  public constructor (gateway: Gateway, parameters: Parameters, captures: Captures) {
+  public constructor(gateway: Gateway, parameters: Parameters, captures: Captures) {
     super(parameters.origin, captures)
     this.gateway = gateway
   }
 
   @when('the following request is received:')
-  public override async request (input: string): Promise<any> {
+  public override async request(input: string): Promise<any> {
     await this.gateway.start()
-    this.fetched = await super.request(input)
+
+    await super.request(input)
   }
 
   @then('the following reply is sent:')
-  public override responseIncludes (expected: string): void {
+  public override responseIncludes(expected: string): void {
     super.responseIncludes(expected)
   }
 
   @then('response body contains {word}-encoded value:')
-  public async bodyIs (format: string, yaml: string): Promise<void> {
-    assert.ok(this.fetched !== null, 'Response is null')
+  public async bodyIs(format: string, yaml: string): Promise<void> {
+    assert.ok(this.bytes !== null, 'Response body is not available')
 
-    const buf = await this.fetched.arrayBuffer()
-    const value = encoders[format]?.(buf as Buffer)
+    const value = encoders[format]?.(this.bytes)
     const expected = YAML.load(yaml)
 
     assert.deepEqual(value, expected, 'Values are not equal')
   }
 
   @then('the reply does not contain:')
-  public override responseExcludes (expected: string): void {
+  public override responseExcludes(expected: string): void {
     super.responseExcludes(expected)
   }
 
   @when('the stream of `{word}` is received with the following headers:')
-  public async streamRequest (filename: string, head: string): Promise<any> {
+  public async streamRequest(filename: string, head: string): Promise<any> {
     const stream = open(filename)
 
     await this.gateway.start()
@@ -56,17 +58,37 @@ export class HTTP extends http.Agent {
   }
 
   @then('the stream equals to `{word}` is sent with the following headers:')
-  public async responseStreamMatch (filename: string, head: string): Promise<any> {
+  public async responseStreamMatch(filename: string, head: string): Promise<any> {
     const stream = open(filename)
 
     await super.streamMatch(head, stream)
   }
+
+  @when('the following request is interrupted after {float} second(s):')
+  public async interrupt(delay: number, input: string): Promise<any> {
+    const controller = new AbortController()
+
+    await this.gateway.start()
+
+    setTimeout(() => {
+      if (pending) controller.abort()
+      else console.error('Request cannot be interrupted as it is already completed')
+    }, delay * 1000)
+
+    let pending = true
+
+    await super.fetch(input, { signal: controller.signal }).catch((e) => {
+      if (e.name !== 'AbortError') throw e
+    })
+
+    pending = false
+  }
 }
 
-const FILEDIR = path.resolve(__dirname, '../../../storages/source/test')
+const FILES_DIR = path.resolve(import.meta.dirname, '../../../storages/source/test')
 
-function open (filename: string): Readable {
-  return fs.createReadStream(path.join(FILEDIR, filename))
+function open(filename: string): Readable {
+  return fs.createReadStream(path.join(FILES_DIR, filename))
 }
 
 const encoders: Record<string, (buf: Buffer | Uint8Array) => any> = {