@toa.io/extensions.introspection 1.0.0-alpha.259

package/schemas/declaration.cos.yaml

@@ -0,0 +1,2 @@
+# manifest.toa.yaml introspection declaration
+samples: boolean

package/source/Composition.ts

@@ -0,0 +1,61 @@
+import { readdirSync, type Dirent } from 'node:fs'
+import { resolve } from 'node:path'
+import { Connector } from '@toa.io/core'
+import { type Bootloader } from './Factory'
+import type { Annotation } from './annotation'
+
+/** Hosts the introspection components in the explorer process. */
+export class Composition extends Connector {
+  private readonly boot: Bootloader
+
+  public constructor (boot: Bootloader) {
+    super()
+    this.boot = boot
+  }
+
+  protected override async open (): Promise<void> {
+    const paths = find()
+    const composition = await this.boot.composition(paths)
+
+    await composition.connect()
+
+    this.depends(composition)
+  }
+}
+
+export function find (): string[] {
+  return entries().map((entry) => resolve(ROOT, entry.name))
+}
+
+function entries (): Dirent[] {
+  const entries = readdirSync(ROOT, { withFileTypes: true })
+
+  return entries.filter((entry) => entry.isDirectory())
+}
+
+/**
+ * The extension is predefined, so an application that turns introspection off
+ * 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: [] }
+
+  const labels: string[] = []
+  const paths: string[] = []
+
+  for (const entry of entries()) {
+    labels.push(entry.name.replace('.', '-'))
+    paths.push(resolve(ROOT, entry.name))
+  }
+
+  return { labels, paths }
+}
+
+interface Components {
+  labels: string[]
+  paths: string[]
+}
+
+const ROOT = resolve(__dirname, '../components/')

package/source/Explorer.ts

@@ -0,0 +1,16 @@
+import { Connector } from '@toa.io/core'
+import { console } from 'openspan'
+
+/**
+ * The explorer process. It hosts the introspection components — the map is read
+ * through their own operations — and serves the UI.
+ */
+export class Explorer extends Connector {
+  protected override async open (): Promise<void> {
+    console.info('Introspection explorer started')
+  }
+
+  protected override dispose (): void {
+    console.info('Introspection explorer is closed')
+  }
+}

package/source/Factory.ts

@@ -0,0 +1,119 @@
+import { Connector } from '@toa.io/core'
+import { DISABLED, environment, component as declaration, settings } from './annotation'
+import { NAMESPACE, UI_PORT } from './const'
+import { describe } from './describe'
+import { Reporter } from './Reporter'
+import { Tenant } from './Tenant'
+import { Composition } from './Composition'
+import { Explorer } from './Explorer'
+import { UI } from './UI'
+import { capture, samplable } from './sample'
+import type { Declaration, Options, Settings } from './annotation'
+import type { Origin, Outcome, Target } from './model'
+import type { Manifest } from '@toa.io/norm'
+import type { Component, Locator, Reply, Request, extensions } from '@toa.io/core'
+
+export class Factory implements extensions.Factory {
+  private readonly boot: Bootloader
+  private readonly options: Options | null
+  private readonly settings: Record<string, Settings> = {}
+  private reporter: Reporter | null = null
+
+  public constructor (boot: Bootloader) {
+    this.boot = boot
+    this.options = environment()
+  }
+
+  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()
+
+    return new Tenant(this.collector(), describe(manifest))
+  }
+
+  public component (component: Component): Component {
+    const locator = component.locator
+    const resolved = this.resolve(locator)
+
+    if (!resolved.enabled)
+      return component
+
+    const reporter = this.collector()
+    const invoke = component.invoke.bind(component)
+
+    component.invoke = async (endpoint: string, request: Request): Promise<any> => {
+      let outcome: Outcome = 'ok'
+      let reply: Reply | undefined
+
+      try {
+        reply = await invoke(endpoint, request)
+
+        if (reply?.exception !== undefined) outcome = 'exception'
+        else if (reply?.error !== undefined) outcome = 'error'
+
+        return reply
+      } catch (error) {
+        outcome = 'exception'
+
+        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
+
+        reporter.observe({ src, dst, sample })
+      }
+    }
+
+    component.depends(reporter)
+
+    return component
+  }
+
+  public service (): Connector | null {
+    if (this.options === null)
+      return null
+
+    const composition = new Composition(this.boot)
+    const explorer = new Explorer()
+
+    explorer.depends(composition)
+
+    if (this.options.ui)
+      explorer.depends(new UI(UI_PORT))
+
+    return explorer
+  }
+
+  /**
+   * `tenant()` runs before any component is created, so settings are warm.
+   * 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 collector (): Reporter {
+    this.reporter ??= new Reporter(this.boot, this.options!)
+
+    return this.reporter
+  }
+}
+
+const UNKNOWN = { service: 'unknown' } as const
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+export type Bootloader = typeof import('@toa.io/boot')

package/source/Reporter.ts

@@ -0,0 +1,210 @@
+import { Connector, Locator } from '@toa.io/core'
+import { console } from 'openspan'
+import { EDGES, MAX_EDGES, NAMESPACE, NODES } from './const'
+import * as keys from './keys'
+import type { Bootloader } from './Factory'
+import type { Options } from './annotation'
+import type { Edge, Node } from './model'
+import type { Remote } from '@toa.io/core'
+
+/**
+ * Buffers what a process observes and flushes it into the introspection
+ * components.
+ *
+ * Nothing here is on the critical path. Reaching the explorer is a discovery,
+ * which waits as long as it takes, so the collector never holds up a component
+ * starting, running or stopping: it buffers until the connection is there, and
+ * when it has to choose it gives up on the data rather than on the application.
+ */
+export class Reporter extends Connector {
+  private readonly boot: Bootloader
+  private readonly options: Options
+  private readonly nodes = new Map<string, Node>()
+  private readonly edges = new Map<string, Edge>()
+
+  /** Holds a remote only once it is connected and usable. */
+  private readonly remotes: Record<string, Remote> = {}
+
+  private timer: NodeJS.Timeout | null = null
+  private flushing: Promise<void> | null = null
+  private acquiring = false
+  private dropped = 0
+
+  public constructor (boot: Bootloader, options: Options) {
+    super()
+
+    this.boot = boot
+    this.options = options
+  }
+
+  /** The static description of a component. */
+  public expose (node: Node): void {
+    this.nodes.set(keys.node(node.namespace, node.component), node)
+
+    void this.flush()
+  }
+
+  /** A call between two components. */
+  public observe (observed: Edge): void {
+    const id = keys.edge(observed.src, observed.dst)
+    const edge = this.edges.get(id)
+
+    if (edge === undefined) {
+      /*
+       * `source` arrives over the wire, so the number of distinct edges a process
+       * can hold has to be bounded regardless of what peers send — and of whether
+       * anyone is there to take them.
+       */
+      if (this.edges.size >= MAX_EDGES) {
+        this.dropped++
+
+        return
+      }
+
+      this.edges.set(id, observed)
+    } else if (observed.sample !== undefined)
+      edge.sample = observed.sample
+
+    if (this.edges.size >= this.options.threshold)
+      void this.flush()
+  }
+
+  protected override async open (): Promise<void> {
+    // deliberately not awaited: the explorer may not be there yet, or at all
+    this.acquire()
+
+    this.timer = setInterval(() => void this.flush(), this.options.interval * 1000)
+    this.timer.unref()
+  }
+
+  protected override async close (): Promise<void> {
+    if (this.timer !== null) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+
+    await this.flushing
+
+    if (!this.ready()) {
+      this.discard('the explorer was never reached')
+
+      return
+    }
+
+    // the remotes are still up: dependencies are disconnected after this returns
+    await this.dispatch().catch((error: Error) => {
+      console.debug('Introspection final flush failed', { message: error.message })
+    })
+  }
+
+  private ready (): boolean {
+    return NODES in this.remotes && EDGES in this.remotes
+  }
+
+  private async flush (): Promise<void> {
+    // a dispatch in flight keeps observations buffered, they join the next batch
+    if (this.flushing !== null)
+      return
+
+    if (this.nodes.size === 0 && this.edges.size === 0)
+      return
+
+    if (!this.ready()) {
+      this.acquire()
+
+      if (this.edges.size >= MAX_EDGES)
+        this.discard('the explorer is not reachable')
+
+      return
+    }
+
+    this.flushing = this.dispatch()
+      .catch((error: Error) => {
+        console.debug('Introspection flush failed', { message: error.message })
+      })
+      .finally(() => {
+        this.flushing = null
+      })
+
+    await this.flushing
+  }
+
+  private discard (reason: string): void {
+    const nodes = this.nodes.size
+    const edges = this.edges.size + this.dropped
+
+    this.nodes.clear()
+    this.edges.clear()
+    this.dropped = 0
+
+    if (nodes === 0 && edges === 0)
+      return
+
+    console.warn(`Introspection data discarded, ${reason}`, { nodes, edges })
+  }
+
+  private async dispatch (): Promise<void> {
+    const nodes = [...this.nodes.entries()]
+    const edges = [...this.edges.entries()]
+
+    this.nodes.clear()
+    this.edges.clear()
+
+    if (this.dropped > 0) {
+      console.warn('Introspection edges dropped', { dropped: this.dropped, limit: MAX_EDGES })
+      this.dropped = 0
+    }
+
+    await Promise.all([
+      this.merge(NODES, 'nodes', nodes),
+      this.merge(EDGES, 'edges', edges)
+    ])
+  }
+
+  /**
+   * A mass transition: every affected object is acquired and committed at once,
+   * so a flush is one call per component whatever it carries.
+   */
+  private async merge (name: string, property: string,
+    observed: Array<[string, Node | Edge]>): Promise<void> {
+    if (observed.length === 0)
+      return
+
+    const objects: Record<string, Node | Edge> = {}
+
+    for (const [id, object] of observed)
+      objects[id] = object
+
+    await this.remotes[name].invoke('merge', {
+      query: { ids: observed.map(([id]) => id) },
+      input: { [property]: objects },
+      task: true
+    })
+  }
+
+  /** Runs in the background: discovery waits for the explorer as long as it takes. */
+  private acquire (): void {
+    if (this.acquiring)
+      return
+
+    this.acquiring = true
+
+    void this.reach().catch((error: Error) => {
+      this.acquiring = false
+
+      console.error('Introspection cannot reach its explorer', { message: error.message })
+    })
+  }
+
+  private async reach (): Promise<void> {
+    await Promise.all([NODES, EDGES].map(async (name) => {
+      const remote = await this.boot.remote(new Locator(name, NAMESPACE))
+
+      this.depends(remote)
+
+      await remote.connect()
+
+      this.remotes[name] = remote
+    }))
+  }
+}

package/source/Tenant.ts

@@ -0,0 +1,47 @@
+import { setTimeout } from 'node:timers/promises'
+import { Connector } from '@toa.io/core'
+import { ANNOUNCE_INTERVAL } from './const'
+import type { Reporter } from './Reporter'
+import type { Node } from './model'
+
+/**
+ * Announces the static description of a component.
+ *
+ * Delivery is guaranteed, so the repeat is not about reliability — it keeps
+ * `_updated` fresh, which is how a removed component fades off the map.
+ */
+export class Tenant extends Connector {
+  private readonly reporter: Reporter
+  private readonly node: Node
+  private stopped = false
+
+  public constructor (reporter: Reporter, node: Node) {
+    super()
+
+    this.reporter = reporter
+    this.node = node
+
+    this.depends(reporter)
+  }
+
+  protected override async open (): Promise<void> {
+    this.reporter.expose(this.node)
+
+    void this.announce()
+  }
+
+  protected override dispose (): void {
+    this.stopped = true
+  }
+
+  private async announce (): Promise<void> {
+    while (!this.stopped) {
+      await setTimeout(ANNOUNCE_INTERVAL, undefined, { ref: false })
+
+      if (this.stopped)
+        break
+
+      this.reporter.expose(this.node)
+    }
+  }
+}

package/source/UI.ts

@@ -0,0 +1,197 @@
+import * as fs from 'node:fs'
+import * as http from 'node:http'
+import * as path from 'node:path'
+import { Connector } from '@toa.io/core'
+import { console } from 'openspan'
+import { UI_PATH } from './const'
+
+/**
+ * Serves the introspection UI: the directory `ui` builds, and nothing else.
+ *
+ * The page is a single-page application whose mount path is baked into the bundle,
+ * so this server routes relative to `UI_PATH` — which is also what the ingress
+ * forwards. `/introspection/*` is left alone: that is the components' own API.
+ */
+export class UI extends Connector {
+  private readonly server: http.Server = http.createServer()
+  private readonly port: number
+  private readonly root: string
+
+  public constructor (port: number, root: string = SITE) {
+    super()
+
+    this.port = port
+    this.root = root
+    this.server.on('request', (request, response) => {
+      this.listen(request, response)
+    })
+  }
+
+  protected override async open (): Promise<void> {
+    /*
+     * A taken port is a real error: uniqueness across services is settled at export
+     * time, so nothing here has to negotiate for one.
+     */
+    await new Promise<void>((resolve, reject) => {
+      const failed = (error: Error): void => {
+        this.server.off('listening', listening)
+        reject(error)
+      }
+
+      const listening = (): void => {
+        this.server.off('error', failed)
+        resolve()
+      }
+
+      this.server.once('error', failed)
+      this.server.once('listening', listening)
+      this.server.listen(this.port)
+    })
+
+    if (!isFile(path.join(this.root, 'index.html')))
+      console.warn('Introspection UI is not built', { root: this.root })
+
+    console.info('Introspection UI started', { port: this.port, path: UI_PATH + '/' })
+  }
+
+  protected override async close (): Promise<void> {
+    const closed = new Promise<void>((resolve) => this.server.once('close', () => {
+      resolve()
+    }))
+
+    this.server.close()
+    this.server.closeAllConnections()
+
+    await closed
+  }
+
+  private listen (request: http.IncomingMessage, response: http.ServerResponse): void {
+    void this.respond(request, response).catch((error: Error) => {
+      console.error('Introspection UI failure', { message: error.message })
+
+      if (!response.writableEnded)
+        response.writeHead(500).end()
+    })
+  }
+
+  private async respond (request: http.IncomingMessage, response: http.ServerResponse): Promise<void> {
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      response.writeHead(405, { allow: 'GET, HEAD' }).end()
+
+      return
+    }
+
+    const pathname = decode(request.url ?? '/')
+
+    if (pathname === null) {
+      response.writeHead(400).end()
+
+      return
+    }
+
+    // the port is the explorer's alone, so the root is the way in
+    if (pathname === '/') {
+      response.writeHead(302, { location: UI_PATH + '/' }).end()
+
+      return
+    }
+
+    const file = this.resolve(pathname)
+
+    if (file === null)
+      response.writeHead(404).end()
+    else
+      await this.send(file, request, response)
+  }
+
+  /**
+   * The file a request lands on, or `null` when nothing does. A path that exists is
+   * served as it is; anything else that could be a route falls back to the page,
+   * because the client router — not this server — knows what routes there are.
+   */
+  private resolve (pathname: string): string | null {
+    if (!pathname.startsWith(UI_PATH))
+      return null
+
+    const relative = pathname.slice(UI_PATH.length)
+
+    if (relative !== '' && !relative.startsWith('/'))
+      return null
+
+    const file = path.join(this.root, relative)
+
+    if (file !== this.root && !file.startsWith(this.root + path.sep))
+      return null
+
+    if (isFile(file))
+      return file
+
+    /*
+     * A missing asset is missing, but a route can look like one: `identity.passkeys` is a
+     * component, not a file with an extension. What this server would have served is what
+     * it knows how to serve, so anything else is a route and falls back to the page — as
+     * does anything ending in a slash, which is no name for a file at all.
+     */
+    const asset = !relative.endsWith('/') && path.extname(relative) in TYPES
+
+    return asset ? null : path.join(this.root, 'index.html')
+  }
+
+  private async send (file: string, request: http.IncomingMessage, response: http.ServerResponse): Promise<void> {
+    const stats = await fs.promises.stat(file).catch(() => null)
+
+    if (stats === null) {
+      response.writeHead(503, { 'content-type': 'text/plain' })
+        .end('The introspection UI is not built. Run `npm run build:ui`.\n')
+
+      return
+    }
+
+    response.writeHead(200, {
+      'content-type': TYPES[path.extname(file)] ?? 'application/octet-stream',
+      'content-length': stats.size,
+      'cache-control': file.startsWith(path.join(this.root, IMMUTABLE)) ? FOREVER : 'no-cache'
+    })
+
+    if (request.method === 'HEAD')
+      response.end()
+    else
+      fs.createReadStream(file).pipe(response)
+  }
+}
+
+function decode (url: string): string | null {
+  try {
+    return decodeURIComponent(url.split('?')[0])
+  } catch {
+    return null
+  }
+}
+
+function isFile (file: string): boolean {
+  return fs.existsSync(file) && fs.statSync(file).isFile()
+}
+
+/** Where `npm run build:ui` puts the page, from both `source` and `transpiled`. */
+const SITE = path.resolve(__dirname, '..', 'ui', 'dist')
+
+/** Assets under this prefix carry their build hash in the name. */
+const IMMUTABLE = path.join('_app', 'immutable')
+const FOREVER = 'public, max-age=31536000, immutable'
+
+const TYPES: Record<string, string> = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.webmanifest': 'application/manifest+json',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+}