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

package/source/Reporter.ts

@@ -30,7 +30,7 @@ export class Reporter extends Connector {
   private acquiring = false
   private dropped = 0
 
-  public constructor (host: Host, options: Options) {
+  public constructor(host: Host, options: Options) {
     super()
 
     this.host = host
@@ -38,14 +38,14 @@ export class Reporter extends Connector {
   }
 
   /** The static description of a component. */
-  public expose (node: Node): void {
+  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 {
+  public observe(observed: Edge): void {
     const id = keys.edge(observed.src, observed.dst)
     const edge = this.edges.get(id)
 
@@ -62,14 +62,12 @@ export class Reporter extends Connector {
       }
 
       this.edges.set(id, observed)
-    } else if (observed.sample !== undefined)
-      edge.sample = observed.sample
+    } else if (observed.sample !== undefined) edge.sample = observed.sample
 
-    if (this.edges.size >= this.options.threshold)
-      void this.flush()
+    if (this.edges.size >= this.options.threshold) void this.flush()
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     // deliberately not awaited: the explorer may not be there yet, or at all
     this.acquire()
 
@@ -77,7 +75,7 @@ export class Reporter extends Connector {
     this.timer.unref()
   }
 
-  protected override async close (): Promise<void> {
+  protected override async close(): Promise<void> {
     if (this.timer !== null) {
       clearInterval(this.timer)
       this.timer = null
@@ -97,23 +95,20 @@ export class Reporter extends Connector {
     })
   }
 
-  private ready (): boolean {
+  private ready(): boolean {
     return NODES in this.remotes && EDGES in this.remotes
   }
 
-  private async flush (): Promise<void> {
+  private async flush(): Promise<void> {
     // a dispatch in flight keeps observations buffered, they join the next batch
-    if (this.flushing !== null)
-      return
+    if (this.flushing !== null) return
 
-    if (this.nodes.size === 0 && this.edges.size === 0)
-      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')
+      if (this.edges.size >= MAX_EDGES) this.discard('the explorer is not reachable')
 
       return
     }
@@ -129,7 +124,7 @@ export class Reporter extends Connector {
     await this.flushing
   }
 
-  private discard (reason: string): void {
+  private discard(reason: string): void {
     const nodes = this.nodes.size
     const edges = this.edges.size + this.dropped
 
@@ -137,13 +132,12 @@ export class Reporter extends Connector {
     this.edges.clear()
     this.dropped = 0
 
-    if (nodes === 0 && edges === 0)
-      return
+    if (nodes === 0 && edges === 0) return
 
     console.warn(`Introspection data discarded, ${reason}`, { nodes, edges })
   }
 
-  private async dispatch (): Promise<void> {
+  private async dispatch(): Promise<void> {
     const nodes = [...this.nodes.entries()]
     const edges = [...this.edges.entries()]
 
@@ -151,7 +145,10 @@ export class Reporter extends Connector {
     this.edges.clear()
 
     if (this.dropped > 0) {
-      console.warn('Introspection edges dropped', { dropped: this.dropped, limit: MAX_EDGES })
+      console.warn('Introspection edges dropped', {
+        dropped: this.dropped,
+        limit: MAX_EDGES
+      })
       this.dropped = 0
     }
 
@@ -165,15 +162,16 @@ export class Reporter extends Connector {
    * 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
+  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
+    for (const [id, object] of observed) objects[id] = object
 
     await this.remotes[name].invoke('merge', {
       query: { ids: observed.map(([id]) => id) },
@@ -183,9 +181,8 @@ export class Reporter extends Connector {
   }
 
   /** Runs in the background: discovery waits for the explorer as long as it takes. */
-  private acquire (): void {
-    if (this.acquiring)
-      return
+  private acquire(): void {
+    if (this.acquiring) return
 
     this.acquiring = true
 
@@ -196,15 +193,17 @@ export class Reporter extends Connector {
     })
   }
 
-  private async reach (): Promise<void> {
-    await Promise.all([NODES, EDGES].map(async (name) => {
-      const remote = await this.host.remote(new Locator(name, NAMESPACE))
+  private async reach(): Promise<void> {
+    await Promise.all(
+      [NODES, EDGES].map(async (name) => {
+        const remote = await this.host.remote(new Locator(name, NAMESPACE))
 
-      this.depends(remote)
+        this.depends(remote)
 
-      await remote.connect()
+        await remote.connect()
 
-      this.remotes[name] = remote
-    }))
+        this.remotes[name] = remote
+      })
+    )
   }
 }

package/source/Tenant.ts

@@ -8,14 +8,14 @@ import type { Node } from './model.js'
  * 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.
+ * `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) {
+  public constructor(reporter: Reporter, node: Node) {
     super()
 
     this.reporter = reporter
@@ -24,22 +24,21 @@ export class Tenant extends Connector {
     this.depends(reporter)
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     this.reporter.expose(this.node)
 
     void this.announce()
   }
 
-  protected override dispose (): void {
+  protected override dispose(): void {
     this.stopped = true
   }
 
-  private async announce (): Promise<void> {
+  private async announce(): Promise<void> {
     while (!this.stopped) {
       await setTimeout(ANNOUNCE_INTERVAL, undefined, { ref: false })
 
-      if (this.stopped)
-        break
+      if (this.stopped) break
 
       this.reporter.expose(this.node)
     }

package/source/UI.ts

@@ -17,7 +17,7 @@ export class UI extends Connector {
   private readonly port: number
   private readonly root: string
 
-  public constructor (port: number, root: string = SITE) {
+  public constructor(port: number, root: string = SITE) {
     super()
 
     this.port = port
@@ -27,7 +27,7 @@ export class UI extends Connector {
     })
   }
 
-  protected override async open (): Promise<void> {
+  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.
@@ -54,10 +54,12 @@ export class UI extends Connector {
     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()
-    }))
+  protected override async close(): Promise<void> {
+    const closed = new Promise<void>((resolve) =>
+      this.server.once('close', () => {
+        resolve()
+      })
+    )
 
     this.server.close()
     this.server.closeAllConnections()
@@ -65,16 +67,18 @@ export class UI extends Connector {
     await closed
   }
 
-  private listen (request: http.IncomingMessage, response: http.ServerResponse): void {
+  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()
+      if (!response.writableEnded) response.writeHead(500).end()
     })
   }
 
-  private async respond (request: http.IncomingMessage, response: http.ServerResponse): Promise<void> {
+  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()
 
@@ -98,10 +102,8 @@ export class UI extends Connector {
 
     const file = this.resolve(pathname)
 
-    if (file === null)
-      response.writeHead(404).end()
-    else
-      await this.send(file, request, response)
+    if (file === null) response.writeHead(404).end()
+    else await this.send(file, request, response)
   }
 
   /**
@@ -109,22 +111,18 @@ export class UI extends Connector {
    * 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
+  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
+    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 (file !== this.root && !file.startsWith(this.root + path.sep)) return null
 
-    if (isFile(file))
-      return file
+    if (isFile(file)) return file
 
     /*
      * A missing asset is missing, but a route can look like one: `identity.passkeys` is a
@@ -137,11 +135,16 @@ export class UI extends Connector {
     return asset ? null : path.join(this.root, 'index.html')
   }
 
-  private async send (file: string, request: http.IncomingMessage, response: http.ServerResponse): Promise<void> {
+  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' })
+      response
+        .writeHead(503, { 'content-type': 'text/plain' })
         .end('The introspection UI is not built. Run `npm run build:ui`.\n')
 
       return
@@ -153,14 +156,12 @@ export class UI extends Connector {
       'cache-control': caching(path.relative(this.root, file))
     })
 
-    if (request.method === 'HEAD')
-      response.end()
-    else
-      fs.createReadStream(file).pipe(response)
+    if (request.method === 'HEAD') response.end()
+    else fs.createReadStream(file).pipe(response)
   }
 }
 
-function decode (url: string): string | null {
+function decode(url: string): string | null {
   try {
     return decodeURIComponent(url.split('?')[0])
   } catch {
@@ -168,7 +169,7 @@ function decode (url: string): string | null {
   }
 }
 
-function isFile (file: string): boolean {
+function isFile(file: string): boolean {
   return fs.existsSync(file) && fs.statSync(file).isFile()
 }
 
@@ -188,7 +189,7 @@ const DAY = 'public, max-age=86400'
  * 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 {
+function caching(relative: string): string {
   if (relative.startsWith(IMMUTABLE)) return FOREVER
 
   return ICONS.has(relative) ? DAY : 'no-cache'

package/source/annotation.ts

@@ -2,22 +2,26 @@ import { DEFAULT_INTERVAL, DEFAULT_THRESHOLD, DENIED, ENV } from './const.js'
 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
-}
+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
-}
+export type Declaration =
+  | false
+  | {
+      samples?: boolean
+    }
 
 /** What `deployment()` encodes into the environment. */
 export interface Options {
@@ -35,7 +39,7 @@ export interface Settings {
 
 export const DISABLED: Settings = { enabled: false, samples: false }
 
-export function options (annotation?: Annotation): Options {
+export function options(annotation?: Annotation): Options {
   const declaration = annotation === undefined || annotation === false ? {} : annotation
 
   return {
@@ -47,22 +51,19 @@ export function options (annotation?: Annotation): Options {
 }
 
 /** Reads what `deployment()` has put into the environment. */
-export function environment (): Options | null {
+export function environment(): Options | null {
   const value = process.env[ENV]
 
-  if (value === undefined)
-    return null
+  if (value === undefined) return null
 
   return JSON.parse(value) as Options
 }
 
-export function component (declaration: Declaration | null | undefined): Declaration {
-  if (declaration === false)
-    return false
+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 {}
+  if (declaration === null || declaration === undefined) return {}
 
   return declaration.samples === undefined ? {} : { samples: declaration.samples }
 }
@@ -72,9 +73,12 @@ export function component (declaration: Declaration | null | undefined): Declara
  * 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
+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)
 

package/source/const.ts

@@ -10,6 +10,18 @@ export const EDGES = 'edges'
 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 = process.env[UI_PORT_ENV]
+
+  return value === undefined ? UI_PORT : Number(value)
+}
+
 export const DEFAULT_INTERVAL = 300
 export const DEFAULT_THRESHOLD = 1024
 

package/source/describe.ts

@@ -7,7 +7,7 @@ import type { Manifest } from '@toa.io/norm'
  * 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 {
+export function describe(manifest: Manifest): Node {
   return {
     namespace: manifest.namespace,
     component: manifest.name,
@@ -22,20 +22,23 @@ export function describe (manifest: Manifest): Node {
   }
 }
 
-function entity (manifest: Manifest): Node['entity'] {
-  if (manifest.entity === undefined)
-    return null
+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: manifest.entity.schema,
+    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]) => ({
+function operations(manifest: Manifest): Operation[] {
+  return Object.entries(manifest.operations ?? {}).map(
+    ([endpoint, definition]: [string, any]) => ({
       endpoint,
       type: definition.type,
       description: definition.description,
@@ -44,26 +47,29 @@ function operations (manifest: Manifest): Operation[] {
       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 }))
+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]) => ({
+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

@@ -6,6 +6,10 @@ 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
 
 /**
@@ -15,19 +19,19 @@ export const standalone = true
  * 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 {}
+export function deployment(_: Instances<unknown>, annotation?: Annotation): Dependency {
+  if (annotation === false) return {}
 
-  if (annotation !== undefined)
-    schemas.annotation.validate(annotation)
+  if (annotation !== undefined) schemas.annotation.validate(annotation)
 
   const opts = options(annotation)
 
   const service: Service = {
     group: 'introspection',
     name: 'explorer',
-    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+    image,
+    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+      .version,
     components: components().labels,
     resources: annotation?.resources,
     variables: []

package/source/manifest.ts

@@ -9,11 +9,10 @@ import type { Declaration } from './annotation.js'
  * declaration arrives as `null` — which still has to produce a value,
  * or norm rejects the extension.
  */
-export function manifest (declaration: Declaration | null | undefined): Declaration {
+export function manifest(declaration: Declaration | null | undefined): Declaration {
   const normalized = component(declaration)
 
-  if (normalized !== false)
-    schemas.declaration.validate(normalized)
+  if (normalized !== false) schemas.declaration.validate(normalized)
 
   return normalized
 }

package/source/model.ts

@@ -1,4 +1,4 @@
-import type { Source } from '@toa.io/core'
+import type { Source } from '@toa.io/core/types'
 
 export type { Source }
 

package/source/sample.ts

@@ -6,20 +6,19 @@ 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 {
+export function capture(input: unknown, outcome: Outcome): Sample {
   return { at: Date.now(), input: redact(input), outcome }
 }
 
-export function samplable (input: unknown): boolean {
+export function samplable(input: unknown): boolean {
   return !(input instanceof Readable)
 }
 
-function redact (value: unknown): unknown {
+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))
+  if (Array.isArray(value)) return truncate(value.map(redact))
 
   const result: Record<string, unknown> = {}
 
@@ -33,7 +32,7 @@ function redact (value: unknown): unknown {
  * 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 {
+function truncate(value: unknown): unknown {
   let serialized: string
 
   try {
@@ -42,8 +41,7 @@ function truncate (value: unknown): unknown {
     return '[unserializable]'
   }
 
-  if (serialized.length <= SAMPLE_LIMIT)
-    return value
+  if (serialized.length <= SAMPLE_LIMIT) return value
 
   return '[truncated]'
 }

package/source/schemas.ts

@@ -6,5 +6,7 @@ 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')
+export const annotation: Schema<Exclude<Annotation, false>> =
+  namespace.schema('annotation')
+export const declaration: Schema<Exclude<Declaration, false>> =
+  namespace.schema('declaration')