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

package/features/steps/Captures.ts

@@ -1,20 +0,0 @@
-import * as http from '@toa.io/agent'
-import tsflow from 'cucumber-tsflow'
-
-const { binding } = tsflow
-
-@binding()
-export class Captures extends http.Captures {
-  public constructor() {
-    super(functions)
-  }
-}
-
-const functions: http.Functions = {
-  otp: function (this: Captures, value: string, arg: string): string {
-    const identity = this.get(arg + '.id')
-    const code = this.get(arg + '.code')
-
-    return Buffer.from(`${identity}:${code}`).toString('base64')
-  }
-}

package/features/steps/Cloudinary.ts

@@ -1,12 +0,0 @@
-import { Before } from '@cucumber/cucumber'
-
-/**
- * The Cloudinary scenarios upload to a real account, named by `features/steps/.env` — the
- * environment and the keys `.env.example` lists. A checkout carries none, and an account is
- * not something a run can stand up for itself, the way the compose file stands up a database.
- * Without one the scenarios are skipped rather than failed, so `npm run features` answers on a
- * fresh machine; with one they run, no flag to remember.
- */
-Before({ tags: '@cloudinary' }, function () {
-  if (process.env.CLOUDINARY_ENVIRONMENT === undefined) return 'skipped'
-})

package/features/steps/Common.ts

@@ -1,38 +0,0 @@
-import * as assert from 'node:assert'
-import tsflow from 'cucumber-tsflow'
-import { timeout } from '@toa.io/generic'
-import { Captures } from './Captures.js'
-
-const { binding, given } = tsflow
-
-@binding([Captures])
-export class Common {
-  private readonly captures: Captures
-
-  public constructor(captures: Captures) {
-    this.captures = captures
-  }
-
-  @given('after {float} second(s)')
-  public async timeout(interval: number): Promise<void> {
-    await timeout(interval * 1000)
-  }
-
-  @given('the process is running')
-  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> {
-    const response = await fetch(url)
-
-    assert.equal(response.status, 200, `${url} answered ${response.status}`)
-
-    const body = await response.arrayBuffer()
-
-    this.captures.set(name, String(body.byteLength))
-  }
-}

package/features/steps/Components.ts

@@ -1,115 +0,0 @@
-import { createRequire } from 'node:module'
-import * as assert from 'node:assert'
-import { dirname, join } from 'node:path'
-import tsflow from 'cucumber-tsflow'
-
-import * as boot from '@toa.io/boot'
-import { type Connector } from '@toa.io/core'
-import { environment } from '@toa.io/generic'
-
-import { load as parse } from 'js-yaml'
-import { Gateway } from './Gateway.js'
-import { Workspace } from './Workspace.js'
-import { components as map } from './map.js'
-
-const { after, binding, given } = tsflow
-
-const require = createRequire(import.meta.url)
-
-const MAP = 'introspection'
-const VALUES = 'configuration'
-
-@binding([Workspace, Gateway])
-export class Components {
-  private readonly workspace: Workspace
-  private readonly gateway: Gateway
-  private compositions: Record<string, Connector> = {}
-
-  public constructor(workspace: Workspace, gateway: Gateway) {
-    this.workspace = workspace
-    this.gateway = gateway
-  }
-
-  @given('the `{word}` is running')
-  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> {
-    const manifest = parse(yaml) as object
-
-    await this.runComponent(name, manifest)
-  }
-
-  /** One composition, as the explorer hosts them. */
-  @given('the introspection components are running')
-  public async runMap(): Promise<void> {
-    assert.ok(!(MAP in this.compositions), `Composition '${MAP}' is already running`)
-
-    this.compositions[MAP] = await boot.composition(map())
-
-    await this.compositions[MAP].connect()
-  }
-
-  /** 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`
-    )
-
-    await this.gateway.start()
-
-    this.compositions[VALUES] = await boot.composition([values()])
-
-    await this.compositions[VALUES].connect()
-  }
-
-  /** What the deployment would tell the values service, as the scenario needs it. */
-  @given('the configuration values are deployed:')
-  public deployValues(yaml: string): void {
-    environment.set('TOA_CONFIGURATION_VALUES', JSON.stringify(parse(yaml)))
-  }
-
-  @given('the `{word}` is stopped')
-  public async stop(name: string): Promise<void> {
-    assert.ok(name in this.compositions, `Composition '${name}' is not running`)
-
-    await this.compositions[name].disconnect()
-    delete this.compositions[name]
-  }
-
-  @after()
-  public async shutdown(): Promise<void> {
-    const promises = Object.values(this.compositions).map((composition) =>
-      composition.disconnect()
-    )
-
-    await Promise.all(promises)
-
-    environment.delete('TOA_CONFIGURATION_VALUES')
-  }
-
-  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
-    // reaches a gateway that is already listening. Started the other way round, the
-    // component waits for a knock, which the request that follows does not.
-    await this.gateway.start()
-
-    const path = await this.workspace.addComponent(name, manifest)
-
-    this.compositions[name] = await boot.composition([path])
-
-    await this.compositions[name].connect()
-  }
-}
-
-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

@@ -1,106 +0,0 @@
-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> {
-    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 = {} 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
-      }
-
-      /*
-       * 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)
-    }
-
-    /*
-     * 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.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> {
-    await this.collection(id).deleteMany({})
-  }
-
-  @beforeAll()
-  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> {
-    await this.client.close()
-  }
-
-  private collection(id: string): Collection<Document> {
-    const [name, namespace = 'default'] = id.split('.').reverse()
-    const collection = `${namespace}_${name}`.toLowerCase()
-
-    return Database.client.db('toa-dev').collection(collection)
-  }
-}
-
-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,239 +0,0 @@
-import tsflow from 'cucumber-tsflow'
-
-import * as boot from '@toa.io/boot'
-import { type Connector } from '@toa.io/core'
-import { environment } from '@toa.io/generic'
-
-import { load as parse } from 'js-yaml'
-import { Factory } from '../../source/index.js'
-import { shortcuts, syntax } from '@toa.io/definitions/extensions.exposition'
-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 written: string[] = []
-
-  @given('the annotation:')
-  public async annotate(yaml: string): Promise<void> {
-    const annotation = parse(yaml) as Partial<http.Options> & { '/'?: object }
-
-    if (annotation['/'] !== undefined) {
-      const tree = syntax.parse(annotation['/'], shortcuts)
-
-      environment.set('TOA_EXPOSITION', JSON.stringify(tree))
-    }
-
-    const { debug, authorities, bouncer, ip, oauth, rpc, mcp } = annotation
-    const properties = Object.assign({}, DEFAULT_PROPERTIES)
-
-    if (debug !== undefined) properties.debug = debug
-
-    if (bouncer !== undefined) properties.bouncer = bouncer
-
-    if (ip !== undefined) properties.ip = ip
-
-    if (authorities !== undefined) properties.authorities = authorities
-
-    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
-
-      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> {
-    const [name, namespace = 'default'] = id.split('.').reverse()
-    const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
-    const def = DEFAULT_CONFIGURATION[id] ?? {}
-    const patch = parse(yaml) as object
-    const configuration = Object.assign({}, def, patch)
-
-    // 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))
-  }
-
-  /** 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>
-
-    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 (!environment.has('TOA_EXPOSITION'))
-      environment.set('TOA_EXPOSITION', DEFAULT_TREE)
-
-    if (!environment.has('TOA_EXPOSITION_PROPERTIES'))
-      environment.set('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('?')
-
-    instance = service
-
-    await service.connect()
-
-    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> {
-    delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
-
-    for (const key of this.written) environment.delete(key)
-
-    this.written = []
-
-    environment.delete('TOA_EXPOSITION')
-    environment.delete('TOA_EXPOSITION_PROPERTIES')
-  }
-
-  @afterAll()
-  public static async stop(): Promise<void> {
-    await instance?.disconnect()
-    instance = null
-    deployment = null
-  }
-
-  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()}`
-
-      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 EXPOSITION = '@toa.io/extensions.exposition'
-const SECRET = 'TOA_CONFIGURATION__'
-
-const DEFAULT_TREE = JSON.stringify({
-  routes: [],
-  methods: [],
-  directives: [
-    {
-      family: 'auth',
-      name: 'anonymous',
-      value: true
-    }
-  ]
-} satisfies syntax.Node)
-
-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': {
-    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,96 +0,0 @@
-import * as assert from 'node:assert'
-import * as fs from 'node:fs'
-import * as path from 'node:path'
-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.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
-
-  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> {
-    await this.gateway.start()
-
-    await super.request(input)
-  }
-
-  @then('the following reply is sent:')
-  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.bytes !== null, 'Response body is not available')
-
-    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 {
-    super.responseExcludes(expected)
-  }
-
-  @when('the stream of `{word}` is received with the following headers:')
-  public async streamRequest(filename: string, head: string): Promise<any> {
-    const stream = open(filename)
-
-    await this.gateway.start()
-    await super.stream(head, stream)
-  }
-
-  @then('the stream equals to `{word}` is sent with the following headers:')
-  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 FILES_DIR = path.resolve(import.meta.dirname, '../../../storages/source/test')
-
-function open(filename: string): Readable {
-  return fs.createReadStream(path.join(FILES_DIR, filename))
-}
-
-const encoders: Record<string, (buf: Buffer | Uint8Array) => any> = {
-  MessagePack: msgpack.decode
-}