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

package/source/UI.ts

@@ -1,213 +0,0 @@
-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.js'
-
-/**
- * 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': caching(path.relative(this.root, file))
-    })
-
-    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(import.meta.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'
-
-/** The icons: named without a hash, so they are re-read, but rarely. */
-const ICONS = new Set(['favicon.ico', 'favicon-96x96.png', 'apple-touch-icon.png'])
-const DAY = 'public, max-age=86400'
-
-/**
- * How long what is served may be held. The page is never cached — it names the assets,
- * and their names carry the build. An icon is named for what it is rather than for its
- * content, so it is asked about again, but not on every page load.
- */
-function caching(relative: string): string {
-  if (relative.startsWith(IMMUTABLE)) return FOREVER
-
-  return ICONS.has(relative) ? DAY : 'no-cache'
-}
-
-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'
-}

package/source/annotation.ts

@@ -1,87 +0,0 @@
-import { DEFAULT_INTERVAL, DEFAULT_THRESHOLD, DENIED, ENV } from './const.js'
-import { environment as variables } from '@toa.io/generic'
-import type { Resources } from '@toa.io/operations'
-
-/** `context.toa.yaml` */
-export type Annotation =
-  | false
-  | {
-      /** Capture real payloads. Off by default: this is production data. */
-      samples?: boolean
-      /** Flush period, seconds. */
-      interval?: number
-      /** Flush as soon as this many distinct edges are buffered. */
-      threshold?: number
-      /** Publish the UI. On by default. */
-      ui?: boolean
-      resources?: Resources
-    }
-
-/** `manifest.toa.yaml` */
-export type Declaration =
-  | false
-  | {
-      samples?: boolean
-    }
-
-/** What `deployment()` encodes into the environment. */
-export interface Options {
-  samples: boolean
-  interval: number
-  threshold: number
-  ui: boolean
-}
-
-/** The effective per-component decision. */
-export interface Settings {
-  enabled: boolean
-  samples: boolean
-}
-
-export const DISABLED: Settings = { enabled: false, samples: false }
-
-export function options(annotation?: Annotation): Options {
-  const declaration = annotation === undefined || annotation === false ? {} : annotation
-
-  return {
-    samples: declaration.samples === true,
-    interval: declaration.interval ?? DEFAULT_INTERVAL,
-    threshold: declaration.threshold ?? DEFAULT_THRESHOLD,
-    ui: declaration.ui !== false
-  }
-}
-
-/** Reads what `deployment()` has put into the environment. */
-export function environment(): Options | null {
-  const value = variables.get(ENV)
-
-  if (value === undefined) return null
-
-  return JSON.parse(value) as Options
-}
-
-export function component(declaration: Declaration | null | undefined): Declaration {
-  if (declaration === false) return false
-
-  // predefined extensions arrive as null for components that say nothing
-  if (declaration === null || declaration === undefined) return {}
-
-  return declaration.samples === undefined ? {} : { samples: declaration.samples }
-}
-
-/**
- * Both levels must agree, and either can veto: the context is the environment
- * ceiling, the manifest is the component's own call. A component handling
- * personal data opts out for good, and no context flag overrides that.
- */
-export function settings(
-  namespace: string,
-  declaration: Declaration,
-  opts: Options | null
-): Settings {
-  if (opts === null || declaration === false) return DISABLED
-
-  const samples = opts.samples && declaration.samples !== false && !DENIED.has(namespace)
-
-  return { enabled: true, samples }
-}

package/source/const.ts

@@ -1,46 +0,0 @@
-import { environment } from '@toa.io/generic'
-
-export const ID = 'introspection'
-export const NAMESPACE = 'introspection'
-
-export const ENV = 'TOA_INTROSPECTION'
-
-export const NODES = 'nodes'
-export const EDGES = 'edges'
-
-/** Where the UI is mounted; `/introspection/*` belongs to the components' own API. */
-export const UI_PATH = '/.introspection'
-export const UI_PORT = 8002
-
-/**
- * The port the UI is served on. `UI_PORT` is what a deployment publishes and what the chart
- * renders; the variable is for a machine that runs more than one Toa process — a Toa checkout
- * beside an application, or two applications — where one of them has to give it up.
- */
-export const UI_PORT_ENV = 'TOA_INTROSPECTION_UI_PORT'
-export function uiPort(): number {
-  const value = environment.get(UI_PORT_ENV)
-
-  return value === undefined ? UI_PORT : Number(value)
-}
-
-export const DEFAULT_INTERVAL = 300
-export const DEFAULT_THRESHOLD = 1024
-
-/** How often a component re-announces its description, so that removed components fade out. */
-export const ANNOUNCE_INTERVAL = 1_800_000
-
-/**
- * `source` arrives over the wire, so the number of distinct edges a process
- * can hold must be bounded regardless of what peers send.
- */
-export const MAX_EDGES = 4096
-
-/** Never capture samples for these namespaces, whatever the annotation says. */
-export const DENIED = new Set(['identity', 'introspection'])
-
-/** Keys never stored in a sample, even when sampling is on. */
-export const REDACTED = /^(password|secret|token|credentials?|key|authorization|cookie)$/i
-
-/** Serialized size cap of a single sample. */
-export const SAMPLE_LIMIT = 4096

package/source/describe.ts

@@ -1,75 +0,0 @@
-import type { Node, Operation, Event, Receiver } from './model.js'
-import type { Manifest } from '@toa.io/norm'
-
-/**
- * Turns a normalized component manifest into the node of the map.
- *
- * Everything here is already normalized by norm: the prototype chain is collapsed,
- * so this is the shape the runtime actually runs.
- */
-export function describe(manifest: Manifest): Node {
-  return {
-    namespace: manifest.namespace,
-    component: manifest.name,
-    version: manifest.version,
-    entity: entity(manifest),
-    operations: operations(manifest),
-    events: events(manifest),
-    receivers: receivers(manifest),
-
-    // names only: extension declarations carry configuration and secrets
-    extensions: Object.keys(manifest.extensions ?? {})
-  }
-}
-
-function entity(manifest: Manifest): Node['entity'] {
-  if (manifest.entity === undefined) return null
-
-  const { properties, required } = manifest.entity
-
-  // the map publishes a schema, which is what a tool reading it can validate against;
-  // a manifest declares the properties and assembles no envelope
-  return {
-    schema: { type: 'object', properties, required },
-    storage: manifest.entity.storage,
-    associated: manifest.entity.associated === true
-  }
-}
-
-function operations(manifest: Manifest): Operation[] {
-  return Object.entries(manifest.operations ?? {}).map(
-    ([endpoint, definition]: [string, any]) => ({
-      endpoint,
-      type: definition.type,
-      description: definition.description,
-      scope: definition.scope,
-      query: definition.query,
-      input: definition.input ?? null,
-      output: definition.output ?? null,
-      errors: definition.errors ?? []
-    })
-  )
-}
-
-function events(manifest: Manifest): Event[] {
-  return Object.entries(manifest.events ?? {}).map(
-    ([label, definition]: [string, any]) => ({ label, binding: definition.binding })
-  )
-}
-
-/*
- * Receiver labels contain dots (`identity.bans.created`), which is why nodes keep
- * these as arrays rather than maps — a dot in a document key is a hazard in Mongo.
- */
-function receivers(manifest: Manifest): Receiver[] {
-  return Object.entries(manifest.receivers ?? {}).map(
-    ([label, definition]: [string, any]) => ({
-      label,
-      source: definition.source ?? label.split('.').slice(0, 2).join('.'),
-      event: label.split('.').pop()!,
-      operation: definition.operation,
-      conditioned: definition.conditioned === true,
-      adaptive: definition.adaptive === true
-    })
-  )
-}

package/source/extension.ts

@@ -1,49 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { options } from './annotation.js'
-import { components } from './Composition.js'
-import { ENV, UI_PATH, UI_PORT } from './const.js'
-import * as schemas from './schemas.js'
-import type { Annotation } from './annotation.js'
-import type { Dependency, Instances, Service } from '@toa.io/operations'
-
-/** Where Toa's release publishes this service's image. An application takes it
- *  instead of building one when its context says `registry.services: published`. */
-export const image = 'ghcr.io/toa-io/extension-introspection-explorer'
-
-export const standalone = true
-
-/**
- * The explorer hosts the introspection components, exactly as the exposition
- * gateway hosts the identity ones. Collection is on unless the context says
- * `introspection: false`, and the environment variable is emitted together
- * with the service — never on its own, or tasks would pile up in a queue
- * nothing consumes.
- */
-export function deployment(_: Instances<unknown>, annotation?: Annotation): Dependency {
-  if (annotation === false) return {}
-
-  if (annotation !== undefined) schemas.annotation.validate(annotation)
-
-  const opts = options(annotation)
-
-  const service: Service = {
-    group: 'introspection',
-    name: 'explorer',
-    image,
-    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
-      .version,
-    components: components().labels,
-    resources: annotation?.resources,
-    variables: []
-  }
-
-  if (opts.ui) {
-    service.port = UI_PORT
-    service.ingress = { path: UI_PATH }
-  }
-
-  return {
-    services: [service],
-    variables: { global: [{ name: ENV, value: JSON.stringify(opts) }] }
-  }
-}

package/source/index.ts

@@ -1,7 +0,0 @@
-export { Factory } from './Factory.js'
-export { manifest } from './manifest.js'
-export { components } from './Composition.js'
-export * from './extension.js'
-
-export type { Annotation, Declaration, Options, Settings } from './annotation.js'
-export type * from './model.js'

package/source/manifest.ts

@@ -1,18 +0,0 @@
-import { component } from './annotation.js'
-import * as schemas from './schemas.js'
-import type { Declaration } from './annotation.js'
-
-/**
- * The component level of the annotation.
- *
- * The extension is predefined, so most components say nothing and the
- * declaration arrives as `null` — which still has to produce a value,
- * or norm rejects the extension.
- */
-export function manifest(declaration: Declaration | null | undefined): Declaration {
-  const normalized = component(declaration)
-
-  if (normalized !== false) schemas.declaration.validate(normalized)
-
-  return normalized
-}

package/source/model.ts

@@ -1,83 +0,0 @@
-import type { Source } from '@toa.io/core/types'
-
-export type { Source }
-
-/**
- * The caller side of an edge: the operation that made the call, the event that
- * caused it, or the service the call came from.
- */
-export type Origin = Source
-
-/** The callee side of an edge. */
-export interface Target {
-  namespace: string
-  component: string
-  operation: string
-}
-
-export interface Operation {
-  endpoint: string
-  type: string
-  description?: string
-  scope?: string
-  query?: boolean
-  input?: object | null
-  output?: object | null
-  errors?: string[]
-}
-
-export interface Event {
-  label: string
-  binding?: string
-}
-
-export interface Receiver {
-  label: string
-  source: string
-  event: string
-  operation: string
-  conditioned: boolean
-  adaptive: boolean
-}
-
-export interface Entity {
-  schema: object
-  storage?: string
-  associated: boolean
-}
-
-/**
- * The static description of a component, derived from its manifest.
- * Sent to `introspection.nodes`.
- */
-export interface Node {
-  namespace: string
-  component: string
-  version: string
-  entity: Entity | null
-  operations: Operation[]
-  events: Event[]
-  receivers: Receiver[]
-  extensions: string[]
-}
-
-export interface Sample {
-  at: number
-  input?: unknown
-  outcome: Outcome
-}
-
-export type Outcome = 'ok' | 'error' | 'exception'
-
-/**
- * A call observed in a process between flushes. What the application declares —
- * which events exist, and which receiver takes which — is a node's business;
- * an edge is what actually happened.
- *
- * Sent to `introspection.edges`.
- */
-export interface Edge {
-  src: Origin
-  dst: Target
-  sample?: Sample
-}

package/source/sample.ts

@@ -1,47 +0,0 @@
-import { Readable } from 'node:stream'
-import { REDACTED, SAMPLE_LIMIT } from './const.js'
-import type { Outcome, Sample } from './model.js'
-
-/**
- * Captures the payload of a call. Only reached when both the context and the
- * component have opted in, and never for a denied namespace.
- */
-export function capture(input: unknown, outcome: Outcome): Sample {
-  return { at: Date.now(), input: redact(input), outcome }
-}
-
-export function samplable(input: unknown): boolean {
-  return !(input instanceof Readable)
-}
-
-function redact(value: unknown): unknown {
-  if (value === null || value === undefined || typeof value !== 'object')
-    return truncate(value)
-
-  if (Array.isArray(value)) return truncate(value.map(redact))
-
-  const result: Record<string, unknown> = {}
-
-  for (const [key, property] of Object.entries(value))
-    result[key] = REDACTED.test(key) ? '***' : redact(property)
-
-  return truncate(result)
-}
-
-/**
- * The map holds one sample per edge indefinitely, so a single oversized
- * payload must not become a permanent tenant of the collection.
- */
-function truncate(value: unknown): unknown {
-  let serialized: string
-
-  try {
-    serialized = JSON.stringify(value) ?? ''
-  } catch {
-    return '[unserializable]'
-  }
-
-  if (serialized.length <= SAMPLE_LIMIT) return value
-
-  return '[truncated]'
-}

package/source/schemas.ts

@@ -1,12 +0,0 @@
-import { resolve } from 'node:path'
-import * as schemas from '@toa.io/schemas'
-import type { Schema } from '@toa.io/schemas'
-import type { Annotation, Declaration } from './annotation.js'
-
-const path = resolve(import.meta.dirname, '../schemas')
-const namespace = schemas.namespace(path)
-
-export const annotation: Schema<Exclude<Annotation, false>> =
-  namespace.schema('annotation')
-export const declaration: Schema<Exclude<Declaration, false>> =
-  namespace.schema('declaration')

package/transpiled/annotation.d.ts

@@ -1,40 +0,0 @@
-import type { Resources } from '@toa.io/operations';
-/** `context.toa.yaml` */
-export type Annotation = false | {
-    /** Capture real payloads. Off by default: this is production data. */
-    samples?: boolean;
-    /** Flush period, seconds. */
-    interval?: number;
-    /** Flush as soon as this many distinct edges are buffered. */
-    threshold?: number;
-    /** Publish the UI. On by default. */
-    ui?: boolean;
-    resources?: Resources;
-};
-/** `manifest.toa.yaml` */
-export type Declaration = false | {
-    samples?: boolean;
-};
-/** What `deployment()` encodes into the environment. */
-export interface Options {
-    samples: boolean;
-    interval: number;
-    threshold: number;
-    ui: boolean;
-}
-/** The effective per-component decision. */
-export interface Settings {
-    enabled: boolean;
-    samples: boolean;
-}
-export declare const DISABLED: Settings;
-export declare function options(annotation?: Annotation): Options;
-/** Reads what `deployment()` has put into the environment. */
-export declare function environment(): Options | null;
-export declare function component(declaration: Declaration | null | undefined): Declaration;
-/**
- * Both levels must agree, and either can veto: the context is the environment
- * ceiling, the manifest is the component's own call. A component handling
- * personal data opts out for good, and no context flag overrides that.
- */
-export declare function settings(namespace: string, declaration: Declaration, opts: Options | null): Settings;