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

package/features/steps/Map.ts

@@ -11,7 +11,8 @@ 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, Request } from '@toa.io/core'
+import type { Component, Connector } from '@toa.io/core'
+import type { Request } from '@toa.io/core/types'
 
 const { after, before, binding, then, when } = tsflow
 
@@ -23,12 +24,14 @@ export class Map {
   private unidentified: Component | null = null
 
   @when('the `{word}` is called with:')
-  public async call (endpoint: string, yaml: string): Promise<void> {
+  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)
+    await this.invoke(`${namespace}.${component}`, operation, request).catch(
+      () => undefined
+    )
   }
 
   /**
@@ -36,7 +39,7 @@ export class Map {
    * 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> {
+  public async callUnidentified(endpoint: string, yaml: string): Promise<void> {
     const request = parse(yaml) as Request
     const [operation, component, namespace = 'default'] = endpoint.split('.').reverse()
 
@@ -47,34 +50,34 @@ export class Map {
   }
 
   @then('the map contains a node:')
-  public async node (yaml: string): Promise<void> {
+  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> {
+  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> {
+  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> {
+  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> {
+  public async stop(): Promise<void> {
     await this.composition?.disconnect()
 
     this.composition = null
   }
 
   @before('not @ui')
-  public async run (): Promise<void> {
+  public async run(): Promise<void> {
     await clean()
 
     this.service = (await new Factory(boot.host()).service())!
@@ -88,7 +91,7 @@ export class Map {
   }
 
   @after('not @ui')
-  public async shutdown (): Promise<void> {
+  public async shutdown(): Promise<void> {
     this.remotes = {}
 
     await this.unidentified?.disconnect()
@@ -101,14 +104,18 @@ export class Map {
     this.unidentified = null
   }
 
-  private async invoke (id: string, operation: string, request: Request): Promise<unknown> {
+  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> {
+  private async eventually(id: string, expected: object): Promise<void> {
     const deadline = Date.now() + DEADLINE
 
     let records: any[] = []
@@ -116,33 +123,37 @@ export class Map {
     while (Date.now() < deadline) {
       records = await this.list(id)
 
-      if (records.some((record) => match(record, expected)))
-        return
+      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)}`)
+    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> {
+  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)}`)
+    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[]
+  private async list(id: string): Promise<any[]> {
+    return (await this.invoke(id, 'enumerate', { query: { limit: 100 } })) as any[]
   }
 }
 
-async function clean (): Promise<void> {
+async function clean(): Promise<void> {
   const client = new MongoClient(URL)
 
   await client.connect()
@@ -157,7 +168,7 @@ async function clean (): Promise<void> {
   await client.close()
 }
 
-function components (): string[] {
+function components(): string[] {
   const entries = readdirSync(ROOT, { withFileTypes: true })
 
   return entries
@@ -166,7 +177,7 @@ function components (): string[] {
 }
 
 const ROOT = resolve(import.meta.dirname, 'components')
-const URL = 'mongodb://developer:secret@localhost:27017'
+const URL = 'mongodb://developer:secret@localhost:31020'
 const DB = 'toa-dev'
 const DEADLINE = 20_000
 const POLL = 250

package/features/steps/UI.ts

@@ -4,10 +4,15 @@ import { resolve } from 'node:path'
 import tsflow from 'cucumber-tsflow'
 
 import { UI } from '../../source/UI.js'
-import { UI_PORT } from '../../source/const.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.
@@ -18,40 +23,42 @@ export class Site {
   private response: Response | null = null
 
   @given('the UI is published')
-  public async publish (): Promise<void> {
-    this.server = new UI(UI_PORT, resolve(import.meta.dirname, '..', 'site'))
+  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> {
+  public async request(path: string): Promise<void> {
     this.response = await get(path)
   }
 
   @then('the status is {int}')
-  public statusIs (status: number): void {
+  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}'`)
+  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 {
+  public bodyIsEmpty(): void {
     assert.equal(this.response?.body, '')
   }
 
   @then('the {string} header is {string}')
-  public headerIs (name: string, value: string): void {
+  public headerIs(name: string, value: string): void {
     assert.equal(this.response?.headers[name], value)
   }
 
   @after()
-  public async shutdown (): Promise<void> {
+  public async shutdown(): Promise<void> {
     await this.server?.disconnect()
 
     this.server = null
@@ -63,10 +70,10 @@ export class Site {
  * 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> {
+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: UI_PORT, path, agent: false }, (response) => {
+    const request = http.get({ port: PORT, path, agent: false }, (response) => {
       let body = ''
 
       response.setEncoding('utf8')

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

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

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

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

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

@@ -4,14 +4,13 @@ name: source
 entity:
   associated: true
   storage: null
-  schema:
-    properties:
-      value:
-        type: integer
-        default: 0
-      secret:
-        type: string
-    type: object
+  properties:
+    value:
+      type: integer
+    secret:
+      type: string
+  blank:
+    value: 0
 
 operations:
   transit:

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

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

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

@@ -1,4 +1,4 @@
-export function computation (input) {
+export function computation(input) {
   return NOPE
 }
 

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

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

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

@@ -3,12 +3,11 @@ name: target
 
 entity:
   storage: null
-  schema:
-    properties:
-      counted:
-        type: integer
-        default: 0
-    type: object
+  properties:
+    counted:
+      type: integer
+  blank:
+    counted: 0
 
 operations:
   compute:

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.introspection",
-  "version": "1.0.0-alpha.284",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa Introspection",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -18,16 +18,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.284",
-    "@toa.io/generic": "1.0.0-alpha.283",
-    "@toa.io/schemas": "1.0.0-alpha.283",
-    "openspan": "1.0.0-alpha.277"
+    "@toa.io/core": "1.0.0-alpha.286",
+    "@toa.io/generic": "1.0.0-alpha.286",
+    "@toa.io/schemas": "1.0.0-alpha.286",
+    "openspan": "1.0.0-alpha.286"
   },
   "scripts": {
     "transpile": "npx tsc && npx tsc -p ./components/introspection.nodes && npx tsc -p ./components/introspection.edges",
     "build:ui": "npm --prefix ui ci && npm --prefix ui run build",
     "prepack": "npm run build:ui",
-    "features": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags 'not @samples and not @shutdown' && TOA_INTROSPECTION_SAMPLES=1 TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags @samples && TOA_INTROSPECTION_INTERVAL=3600 TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags @shutdown"
+    "features": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags 'not @skip and not @samples and not @shutdown' && TOA_INTROSPECTION_SAMPLES=1 TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags 'not @skip and @samples' && TOA_INTROSPECTION_INTERVAL=3600 TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags 'not @skip and @shutdown'"
   },
-  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf"
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
 }

package/readme.md

@@ -29,13 +29,13 @@ introspection:
 
 All properties are optional.
 
-| Property | Default | Description |
-| --- | --- | --- |
-| `samples` | `false` | Enables collection of call input and outcome samples. |
-| `interval` | `300` | Interval between topology updates, in seconds. |
-| `threshold` | `1024` | Number of distinct observed interactions that triggers an update before the interval expires. |
-| `ui` | `true` | Publishes the web UI. |
-| `resources` | — | Resource requirements for the Introspection deployment. |
+| Property    | Default | Description                                                                                   |
+| ----------- | ------- | --------------------------------------------------------------------------------------------- |
+| `samples`   | `false` | Enables collection of call input and outcome samples.                                         |
+| `interval`  | `300`   | Interval between topology updates, in seconds.                                                |
+| `threshold` | `1024`  | Number of distinct observed interactions that triggers an update before the interval expires. |
+| `ui`        | `true`  | Publishes the web UI.                                                                         |
+| `resources` | —       | Resource requirements for the Introspection deployment.                                       |
 
 Resource requirements can be declared specifically for Introspection:
 

package/schemas/annotation.cos.yaml

@@ -12,7 +12,7 @@ properties:
     type: boolean
   resources:
     # `null` deploys the service without any, which every deployment has to state one way
-    # or the other — see `migrations/263.md`.
+    # or the other — see `migrations/262.md`.
     type: object
     nullable: true
     properties:

package/source/Composition.ts

@@ -8,12 +8,12 @@ import type { Annotation } from './annotation.js'
 export class Composition extends Connector {
   private readonly host: Host
 
-  public constructor (host: Host) {
+  public constructor(host: Host) {
     super()
     this.host = host
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     const paths = find()
     const composition = await this.host.composition(paths)
 
@@ -23,11 +23,11 @@ export class Composition extends Connector {
   }
 }
 
-export function find (): string[] {
+export function find(): string[] {
   return entries().map((entry) => resolve(ROOT, entry.name))
 }
 
-function entries (): Dirent[] {
+function entries(): Dirent[] {
   const entries = readdirSync(ROOT, { withFileTypes: true })
 
   return entries.filter((entry) => entry.isDirectory())
@@ -38,9 +38,8 @@ function entries (): Dirent[] {
  * must not end up with the explorer components — nor with the exposition
  * dependency they bring in.
  */
-export function components (annotation?: Annotation): Components {
-  if (annotation === false)
-    return { labels: [], paths: [] }
+export function components(annotation?: Annotation): Components {
+  if (annotation === false) return { labels: [], paths: [] }
 
   const labels: string[] = []
   const paths: string[] = []

package/source/Explorer.ts

@@ -6,11 +6,11 @@ import { console } from 'openspan'
  * through their own operations — and serves the UI.
  */
 export class Explorer extends Connector {
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     console.info('Introspection explorer started')
   }
 
-  protected override dispose (): void {
+  protected override dispose(): void {
     console.info('Introspection explorer is closed')
   }
 }

package/source/Factory.ts

@@ -1,6 +1,11 @@
 import { Connector } from '@toa.io/core'
-import { DISABLED, environment, component as declaration, settings } from './annotation.js'
-import { NAMESPACE, UI_PORT } from './const.js'
+import {
+  DISABLED,
+  environment,
+  component as declaration,
+  settings
+} from './annotation.js'
+import { NAMESPACE, uiPort } from './const.js'
 import { describe } from './describe.js'
 import { Reporter } from './Reporter.js'
 import { Tenant } from './Tenant.js'
@@ -11,7 +16,8 @@ import { capture, samplable } from './sample.js'
 import type { Declaration, Options, Settings } from './annotation.js'
 import type { Origin, Outcome, Target } from './model.js'
 import type { Manifest } from '@toa.io/norm'
-import type { Component, Locator, Reply, Request, extensions } from '@toa.io/core'
+import type { Component, Locator } from '@toa.io/core'
+import type { Reply, Request, extensions } from '@toa.io/core/types'
 
 export class Factory implements extensions.Factory {
   private readonly host: Host
@@ -19,28 +25,30 @@ export class Factory implements extensions.Factory {
   private readonly settings: Record<string, Settings> = {}
   private reporter: Reporter | null = null
 
-  public constructor (host: Host) {
+  public constructor(host: Host) {
     this.host = host
     this.options = environment()
   }
 
-  public tenant (locator: Locator, decl: Declaration | null, manifest: Manifest): Connector {
-    const resolved = settings(locator.namespace, declaration(decl), this.options)
+  public tenant(
+    locator: Locator,
+    decl: Declaration | null,
+    manifest: Manifest
+  ): Connector {
+    const resolved = settings(locator.namespace!, declaration(decl), this.options)
 
     this.settings[locator.id] = resolved
 
-    if (!resolved.enabled || locator.namespace === NAMESPACE)
-      return new Connector()
+    if (!resolved.enabled || locator.namespace === NAMESPACE) return new Connector()
 
     return new Tenant(this.collector(), describe(manifest))
   }
 
-  public component (component: Component): Component {
+  public component(component: Component): Component {
     const locator = component.locator
     const resolved = this.resolve(locator)
 
-    if (!resolved.enabled)
-      return component
+    if (!resolved.enabled) return component
 
     const reporter = this.collector()
     const invoke = component.invoke.bind(component)
@@ -62,12 +70,17 @@ export class Factory implements extensions.Factory {
         throw error
       } finally {
         // a call that failed is still a connection between two components
-        const src: Origin = request?.source ?? UNKNOWN
-        const dst: Target = { namespace: locator.namespace, component: locator.name, operation: endpoint }
-
-        const sample = resolved.samples && samplable(request?.input)
-          ? capture(request?.input, outcome)
-          : undefined
+        const src: Origin = origin(request?.source)
+        const dst: Target = {
+          namespace: locator.namespace!,
+          component: locator.name,
+          operation: endpoint
+        }
+
+        const sample =
+          resolved.samples && samplable(request?.input)
+            ? capture(request?.input, outcome)
+            : undefined
 
         reporter.observe({ src, dst, sample })
       }
@@ -78,17 +91,15 @@ export class Factory implements extensions.Factory {
     return component
   }
 
-  public service (): Connector | null {
-    if (this.options === null)
-      return null
+  public service(): Connector | null {
+    if (this.options === null) return null
 
     const composition = new Composition(this.host)
     const explorer = new Explorer()
 
     explorer.depends(composition)
 
-    if (this.options.ui)
-      explorer.depends(new UI(UI_PORT))
+    if (this.options.ui) explorer.depends(new UI(uiPort()))
 
     return explorer
   }
@@ -98,15 +109,20 @@ export class Factory implements extensions.Factory {
    * A component booted on its own (without a composition) falls back to
    * the environment, with sampling off.
    */
-  private resolve (locator: Locator): Settings {
-    if (locator.namespace === NAMESPACE)
-      return DISABLED
-
-    return this.settings[locator.id] ??
-      settings(locator.namespace, {}, this.options === null ? null : { ...this.options, samples: false })
+  private resolve(locator: Locator): Settings {
+    if (locator.namespace === NAMESPACE) return DISABLED
+
+    return (
+      this.settings[locator.id] ??
+      settings(
+        locator.namespace!,
+        {},
+        this.options === null ? null : { ...this.options, samples: false }
+      )
+    )
   }
 
-  private collector (): Reporter {
+  private collector(): Reporter {
     this.reporter ??= new Reporter(this.host, this.options!)
 
     return this.reporter
@@ -115,4 +131,22 @@ export class Factory implements extensions.Factory {
 
 const UNKNOWN = { service: 'unknown' } as const
 
+/**
+ * `source` crosses the wire, and what it names is stored as an edge of the map — so what is
+ * read off it is the keys this release knows, and never whatever a peer put beside them.
+ */
+function origin(source: Origin | undefined): Origin {
+  if (source === undefined) return UNKNOWN
+
+  if ('service' in source) return { service: source.service }
+
+  return 'event' in source
+    ? { namespace: source.namespace, component: source.component, event: source.event }
+    : {
+        namespace: source.namespace,
+        component: source.component,
+        operation: source.operation
+      }
+}
+
 export type Host = extensions.Host