@toa.io/extensions.introspection 1.0.0-alpha.291 → 1.0.0-alpha.293

package/features/nodes.feature

@@ -1,70 +0,0 @@
-Feature: Component descriptions
-
-  The static half of the map: what each component is, taken from its manifest
-  when the composition starts. This is where the event graph lives — which events
-  a component publishes, and which event each of its receivers takes — since all
-  of it is declared, and none of it needs traffic to be true.
-
-  Scenario: Describing operations
-    Then the map contains a node:
-      """yaml
-      namespace: probe
-      component: target
-      operations:
-        - endpoint: compute
-          type: computation
-          scope: none
-          input:
-            type: object
-            properties:
-              a: { type: number }
-              b: { type: number }
-          output:
-            type: number
-      """
-
-  Scenario: Describing the entity
-    Then the map contains a node:
-      """yaml
-      namespace: probe
-      component: target
-      entity:
-        storage: "@toa.io/storages.null"
-        schema:
-          properties:
-            counted:
-              type: integer
-      """
-
-  Scenario: Describing events
-    Then the map contains a node:
-      """yaml
-      namespace: probe
-      component: source
-      events:
-        - label: created
-        - label: updated
-        - label: deleted
-        - label: sync
-      """
-
-  Scenario: Describing receivers
-    Then the map contains a node:
-      """yaml
-      namespace: probe
-      component: target
-      receivers:
-        - label: probe.source.created
-          source: probe.source
-          event: created
-          operation: count
-          conditioned: false
-          adaptive: false
-      """
-
-  Scenario: An opted out component is not described
-    Then the map contains no node:
-      """yaml
-      namespace: probe
-      component: quiet
-      """

package/features/samples.feature

@@ -1,75 +0,0 @@
-Feature: Payload samples
-
-  Samples are real user data, so they are captured only when the context and the
-  component both allow it. Either level can veto.
-
-  Scenario: Nothing is captured by default
-    When the `probe.target.compute` is called with:
-      """yaml
-      input:
-        a: 4
-        b: 5
-      """
-    Then the map contains an edge:
-      """yaml
-      dst:
-        namespace: probe
-        component: target
-        operation: compute
-      """
-    And the map contains no edge:
-      """yaml
-      dst:
-        namespace: probe
-        component: target
-        operation: compute
-      sample:
-        input:
-          a: 4
-      """
-
-  @samples
-  Scenario: The context enables capturing
-    When the `probe.target.compute` is called with:
-      """yaml
-      input:
-        a: 4
-        b: 5
-      """
-    Then the map contains an edge:
-      """yaml
-      dst:
-        namespace: probe
-        component: target
-        operation: compute
-      sample:
-        outcome: ok
-        input:
-          a: 4
-          b: 5
-      """
-
-  @samples
-  Scenario: A component vetoes capturing for itself
-    When the `probe.discreet.ping` is called with:
-      """yaml
-      input:
-        a: 7
-      """
-    Then the map contains an edge:
-      """yaml
-      dst:
-        namespace: probe
-        component: discreet
-        operation: ping
-      """
-    And the map contains no edge:
-      """yaml
-      dst:
-        namespace: probe
-        component: discreet
-        operation: ping
-      sample:
-        input:
-          a: 7
-      """

package/features/shutdown.feature

@@ -1,37 +0,0 @@
-@shutdown
-Feature: Graceful shutdown
-
-  A component reports on a timer, so whatever it observed since the last report
-  would be lost on a deploy. Stopping flushes it instead: the collector drains
-  its buffer while its remotes are still connected.
-
-  This suite runs with a flush period long enough that the timer cannot fire,
-  so nothing here reaches the map unless the shutdown does it.
-
-  Scenario: Observations are flushed on shutdown
-    When the `probe.source.relay` is called with:
-      """yaml
-      input:
-        a: 2
-        b: 3
-      """
-    And the components are stopped
-    Then the map contains an edge:
-      """yaml
-      src:
-        namespace: probe
-        component: source
-        operation: relay
-      dst:
-        namespace: probe
-        component: target
-        operation: compute
-      """
-
-  Scenario: Component descriptions are flushed on shutdown
-    When the components are stopped
-    Then the map contains a node:
-      """yaml
-      namespace: probe
-      component: target
-      """

package/features/site/_app/immutable/asset.js

@@ -1 +0,0 @@
-export const hashed = true

package/features/site/index.html

@@ -1,10 +0,0 @@
-<!doctype html>
-<!-- stands in for what `ui` builds; the scenarios are about the server, not the page -->
-<html lang="en">
-  <head>
-    <title>fixture</title>
-  </head>
-  <body>
-    the page
-  </body>
-</html>

package/features/steps/Map.ts

@@ -1,184 +0,0 @@
-import assert from 'node:assert'
-import { resolve } from 'node:path'
-import { readdirSync } from 'node:fs'
-import { setTimeout } from 'node:timers/promises'
-import { MongoClient } from 'mongodb'
-import tsflow from 'cucumber-tsflow'
-
-import { load as parse } from 'js-yaml'
-import { match } from '@toa.io/generic'
-import * as boot from '@toa.io/boot'
-import { Locator } from '@toa.io/core'
-import * as stage from '@toa.io/userland/stage'
-import { Factory } from '../../source/index.js'
-import type { Component, Connector } from '@toa.io/core'
-import type { Request } from '@toa.io/core/types'
-
-const { after, before, binding, then, when } = tsflow
-
-@binding()
-export class Map {
-  private service: Connector | null = null
-  private composition: Connector | null = null
-  private remotes: Record<string, Component> = {}
-  private unidentified: Component | null = null
-
-  @when('the `{word}` is called with:')
-  public async call(endpoint: string, yaml: string): Promise<void> {
-    const request = parse(yaml) as Request
-    const [operation, component, namespace = 'default'] = endpoint.split('.').reverse()
-
-    // an operation may throw, and that is exactly what one of the scenarios is about
-    await this.invoke(`${namespace}.${component}`, operation, request).catch(
-      () => undefined
-    )
-  }
-
-  /**
-   * The stage names itself as the caller, as every entry point does; a call that names
-   * nobody is made past it, straight through a remote of its own.
-   */
-  @when('the `{word}` is called by an unidentified caller with:')
-  public async callUnidentified(endpoint: string, yaml: string): Promise<void> {
-    const request = parse(yaml) as Request
-    const [operation, component, namespace = 'default'] = endpoint.split('.').reverse()
-
-    this.unidentified ??= await boot.remote(new Locator(component, namespace))
-
-    await this.unidentified.connect()
-    await this.unidentified.invoke(operation, request).catch(() => undefined)
-  }
-
-  @then('the map contains a node:')
-  public async node(yaml: string): Promise<void> {
-    await this.eventually('introspection.nodes', parse(yaml) as object)
-  }
-
-  @then('the map contains an edge:')
-  public async edge(yaml: string): Promise<void> {
-    await this.eventually('introspection.edges', parse(yaml) as object)
-  }
-
-  @then('the map contains no node:')
-  public async noNode(yaml: string): Promise<void> {
-    await this.never('introspection.nodes', parse(yaml) as object)
-  }
-
-  @then('the map contains no edge:')
-  public async noEdge(yaml: string): Promise<void> {
-    await this.never('introspection.edges', parse(yaml) as object)
-  }
-
-  @when('the components are stopped')
-  public async stop(): Promise<void> {
-    await this.composition?.disconnect()
-
-    this.composition = null
-  }
-
-  @before('not @ui')
-  public async run(): Promise<void> {
-    await clean()
-
-    this.service = (await new Factory(boot.host()).service())!
-
-    await this.service.connect()
-
-    // booted here rather than through the stage, so that a scenario can stop it on its own
-    this.composition = await boot.composition(components())
-
-    await this.composition.connect()
-  }
-
-  @after('not @ui')
-  public async shutdown(): Promise<void> {
-    this.remotes = {}
-
-    await this.unidentified?.disconnect()
-    await this.composition?.disconnect()
-    await stage.shutdown()
-    await this.service?.disconnect()
-
-    this.composition = null
-    this.service = null
-    this.unidentified = null
-  }
-
-  private async invoke(
-    id: string,
-    operation: string,
-    request: Request
-  ): Promise<unknown> {
-    this.remotes[id] ??= await stage.remote(id)
-
-    return await this.remotes[id].invoke(operation, request)
-  }
-
-  /** The map is eventually consistent: the collector buffers, flushes, and the task is queued. */
-  private async eventually(id: string, expected: object): Promise<void> {
-    const deadline = Date.now() + DEADLINE
-
-    let records: any[] = []
-
-    while (Date.now() < deadline) {
-      records = await this.list(id)
-
-      if (records.some((record) => match(record, expected))) return
-
-      await setTimeout(POLL)
-    }
-
-    assert.fail(
-      `No record in '${id}' matches\n${JSON.stringify(expected, null, 2)}\n\n` +
-        `Present:\n${JSON.stringify(records, null, 2)}`
-    )
-  }
-
-  /** Absence has to outlive a flush, otherwise it only proves the map is slow. */
-  private async never(id: string, expected: object): Promise<void> {
-    await setTimeout(SETTLE)
-
-    const records = await this.list(id)
-    const found = records.find((record) => match(record, expected))
-
-    assert.equal(
-      found,
-      undefined,
-      `Unexpected record in '${id}':\n${JSON.stringify(found, null, 2)}`
-    )
-  }
-
-  private async list(id: string): Promise<any[]> {
-    return (await this.invoke(id, 'enumerate', { query: { limit: 100 } })) as any[]
-  }
-}
-
-async function clean(): Promise<void> {
-  const client = new MongoClient(URL)
-
-  await client.connect()
-
-  const db = client.db(DB)
-
-  await Promise.all([
-    db.collection('introspection_nodes').deleteMany({}),
-    db.collection('introspection_edges').deleteMany({})
-  ])
-
-  await client.close()
-}
-
-function components(): string[] {
-  const entries = readdirSync(ROOT, { withFileTypes: true })
-
-  return entries
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => resolve(ROOT, entry.name))
-}
-
-const ROOT = resolve(import.meta.dirname, 'components')
-const URL = 'mongodb://developer:secret@localhost:31020'
-const DB = 'toa-dev'
-const DEADLINE = 20_000
-const POLL = 250
-const SETTLE = 4_000

package/features/steps/UI.ts

@@ -1,98 +0,0 @@
-import assert from 'node:assert'
-import * as http from 'node:http'
-import { resolve } from 'node:path'
-import tsflow from 'cucumber-tsflow'
-
-import { UI } from '../../source/UI.js'
-
-const { after, binding, given, then, when } = tsflow
-
-/**
- * Not `UI_PORT`, which a deployment serves the page on: an application built on Toa is served
- * on this machine too, and its own explorer holds that one. See CONTRIBUTING.md.
- */
-const PORT = 31002
-
-/**
- * The scenarios are about the server, not about the page: it is pointed at a fixture
- * directory, so that running them never needs a UI build.
- */
-@binding()
-export class Site {
-  private server: UI | null = null
-  private response: Response | null = null
-
-  @given('the UI is published')
-  public async publish(): Promise<void> {
-    this.server = new UI(PORT, resolve(import.meta.dirname, '..', 'site'))
-
-    await this.server.connect()
-  }
-
-  @when('{string} is requested')
-  public async request(path: string): Promise<void> {
-    this.response = await get(path)
-  }
-
-  @then('the status is {int}')
-  public statusIs(status: number): void {
-    assert.equal(this.response?.status, status)
-  }
-
-  @then('the body contains {string}')
-  public bodyContains(text: string): void {
-    assert.ok(
-      this.response?.body.includes(text),
-      `Expected the body to contain '${text}', got '${this.response?.body}'`
-    )
-  }
-
-  @then('the body is empty')
-  public bodyIsEmpty(): void {
-    assert.equal(this.response?.body, '')
-  }
-
-  @then('the {string} header is {string}')
-  public headerIs(name: string, value: string): void {
-    assert.equal(this.response?.headers[name], value)
-  }
-
-  @after()
-  public async shutdown(): Promise<void> {
-    await this.server?.disconnect()
-
-    this.server = null
-    this.response = null
-  }
-}
-
-/**
- * Raw `http`, not `fetch`: the URL parser normalizes `%2e%2e` away, and one of the
- * scenarios is about exactly that segment reaching the server.
- */
-async function get(path: string): Promise<Response> {
-  return await new Promise((resolve, reject) => {
-    // `agent: false` — a keep-alive socket outlives the scenario that opened it
-    const request = http.get({ port: PORT, path, agent: false }, (response) => {
-      let body = ''
-
-      response.setEncoding('utf8')
-      response.on('data', (chunk: string) => (body += chunk))
-      response.on('end', () => {
-        resolve({
-          status: response.statusCode!,
-          headers: response.headers as Record<string, string>,
-          body
-        })
-      })
-    })
-
-    request.on('error', reject)
-  })
-}
-
-interface Response {
-  status: number
-  headers: Record<string, string>
-  body: string
-}

package/features/steps/components/probe.discreet/manifest.toa.yaml

@@ -1,16 +0,0 @@
-namespace: probe
-name: discreet
-
-# on the map, but its payloads are never captured
-introspection:
-  samples: false
-
-operations:
-  ping:
-    input:
-      properties:
-        a:
-          type: number
-      type: object
-    output:
-      type: number

package/features/steps/components/probe.discreet/operations/ping.js

@@ -1,3 +0,0 @@
-export async function computation(input) {
-  return input.a
-}

package/features/steps/components/probe.quiet/manifest.toa.yaml

@@ -1,15 +0,0 @@
-namespace: probe
-name: quiet
-
-# opted out entirely: neither described nor instrumented
-introspection: false
-
-operations:
-  ping:
-    input:
-      properties:
-        a:
-          type: number
-      type: object
-    output:
-      type: number

package/features/steps/components/probe.quiet/operations/ping.js

@@ -1,3 +0,0 @@
-export async function computation(input) {
-  return input.a
-}

package/features/steps/components/probe.source/manifest.toa.yaml

@@ -1,40 +0,0 @@
-namespace: probe
-name: source
-
-entity:
-  associated: true
-  storage: null
-  properties:
-    value:
-      type: integer
-    secret:
-      type: string
-  blank:
-    value: 0
-
-operations:
-  transit:
-    concurrency: retry
-    input:
-      properties:
-        value:
-          type: string
-          default: .
-        secret:
-          type: string
-          default: .
-      type: object
-  relay:
-    input:
-      properties:
-        a:
-          type: number
-        b:
-          type: number
-      type: object
-    output:
-      type: number
-  crash: {}
-  fail:
-    errors:
-      - NOPE

package/features/steps/components/probe.source/operations/crash.js

@@ -1,3 +0,0 @@
-export function computation(input) {
-  throw new Error('crashed on purpose')
-}

package/features/steps/components/probe.source/operations/fail.js

@@ -1,8 +0,0 @@
-export function computation(input) {
-  return NOPE
-}
-
-const NOPE = Object.create(Error.prototype, {
-  code: { value: 'NOPE' },
-  message: { value: 'declined on purpose', enumerable: true }
-})

package/features/steps/components/probe.source/operations/relay.js

@@ -1,3 +0,0 @@
-export async function computation(input, context) {
-  return context.remote.probe.target.compute({ input })
-}

package/features/steps/components/probe.target/manifest.toa.yaml

@@ -1,30 +0,0 @@
-namespace: probe
-name: target
-
-entity:
-  storage: null
-  properties:
-    counted:
-      type: integer
-  blank:
-    counted: 0
-
-operations:
-  compute:
-    input:
-      properties:
-        a:
-          type: number
-        b:
-          type: number
-      type: object
-    output:
-      type: number
-  count:
-    concurrency: retry
-    input:
-      type: object
-      additionalProperties: true
-
-receivers:
-  probe.source.created: count

package/features/steps/components/probe.target/operations/compute.js

@@ -1,3 +0,0 @@
-export async function computation(input) {
-  return input.a + input.b
-}

package/features/steps/components/probe.target/operations/count.js

@@ -1,5 +0,0 @@
-export function transition(input, object) {
-  object.counted++
-
-  return object
-}

package/features/steps/config.ts

@@ -1,27 +0,0 @@
-import { setDefaultTimeout } from '@cucumber/cucumber'
-import { environment } from '@toa.io/generic'
-
-environment.set('TOA_DEV', '1')
-
-// a reply is checked against what the operation declares, so the suite runs Toa under the
-// contract it asks applications to keep
-if (!environment.has('TOA_ENV')) environment.set('TOA_ENV', 'local')
-
-/*
- * The extension factory reads the environment once, and the bootloader caches
- * factories per process — so the context level of the annotation is fixed for
- * a whole run. `npm run features` therefore makes a pass per configuration.
- */
-environment.set(
-  'TOA_INTROSPECTION',
-  JSON.stringify({
-    samples: environment.get('TOA_INTROSPECTION_SAMPLES') === '1',
-    interval: Number(environment.get('TOA_INTROSPECTION_INTERVAL') ?? 1),
-    threshold: 64,
-
-    // `ui.feature` starts its own server; the explorer must not take the port first
-    ui: false
-  })
-)
-
-setDefaultTimeout(60 * 1000)

package/features/steps/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "noEmit": true,
-    "moduleResolution": "node",
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}