LCOV - code coverage report
Current view: top level - src/workbench/extensions/agent/crdt - devPanelLog.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 20.9 % 91 19
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : import { shallowRef, triggerRef } from 'vue'
       2              : 
       3              : import { reportError } from '@comfyorg/telemetry/reportError'
       4              : 
       5              : import { isCrdtDebugEnabled } from './crdtDebugGate'
       6              : import type { CrdtLogLevel } from './crdtDebugGate'
       7              : 
       8              : /**
       9              :  * In-memory ring buffer feeding the CRDT debug panel. Deliberately
      10              :  * module-level (one buffer per page, like the follower gate) so the panel
      11              :  * component and the follower composable never need a shared injection seam.
      12              :  *
      13              :  * Every entry carries the same four axes the console logger uses — kind,
      14              :  * scope, level, detail — so "what the panel shows" and "what the console
      15              :  * printed" are the same record read two ways, and a copied report is a
      16              :  * faithful transcript rather than a second, drifting summary.
      17              :  */
      18              : 
      19              : /**
      20              :  * The layer an event came from. Filtering by scope is how the panel offers
      21              :  * "varying levels of abstraction": `wire` is bytes on the socket and `doc`
      22              :  * is document lineage.
      23              :  */
      24              : export type CrdtLogScope = 'wire' | 'doc'
      25              : 
      26         2355 : export const DEV_EVENT_KINDS = [
      27              :   'ws_out',
      28              :   'doc_subscribed',
      29              :   'doc_update',
      30              :   'doc_ops_result',
      31              :   'doc_ops_result_dropped',
      32              :   'human_ops_settled',
      33              :   'mint_divergence',
      34              :   'host_rejected',
      35              :   'doc_reset',
      36              :   'doc_nodes_changed',
      37              :   'schema_error',
      38              :   'reconnected',
      39              :   'subscribe_retry',
      40              :   'subscribe_ack_timeout',
      41              :   'subscribe_refused_permanent',
      42              :   'doc_reseed_sent',
      43              :   'doc_reseed_result',
      44              :   'stale_probe',
      45              :   'catchup_probe',
      46              :   'rebind',
      47              :   'doc_gap',
      48              :   'doc_stale',
      49              :   'frame_send_failed',
      50              :   'agent_node_adapters_materialized',
      51              :   'local_widget_write_held',
      52              :   'agent_write_overwritten'
      53              : ] as const
      54              : 
      55              : export type DevEventKind = (typeof DEV_EVENT_KINDS)[number]
      56              : 
      57              : export interface DevEvent {
      58              :   seq: number
      59              :   at: number
      60              :   kind: DevEventKind
      61              :   scope: CrdtLogScope
      62              :   level: CrdtLogLevel
      63              :   detail: unknown
      64              : }
      65              : 
      66              : export interface DevEventOptions {
      67              :   scope?: CrdtLogScope
      68              :   level?: CrdtLogLevel
      69              : }
      70              : 
      71         2355 : const CAPACITY = 500
      72         2355 : const REDACTED = '[REDACTED]'
      73         2355 : const MAX_SANITIZE_DEPTH = 12
      74         2355 : const SENSITIVE_KEY =
      75              :   /(^|_)(token|accesstoken|secret|password|passwd|credential|api_key|apikey|authorization|auth|bearer|session|cookie|signature|jwt|prompt|text)$/
      76         2355 : const CONTENT_KEYS = new Set([
      77              :   'value',
      78              :   'old',
      79              :   'widgets_values',
      80              :   'widgets_values_named',
      81              :   'signed_url',
      82              :   'node',
      83              :   'workflow'
      84              : ])
      85              : 
      86              : // Strings are the only place free-form producer or user content can reach the
      87              : // buffer, so string retention is an ALLOW-LIST, not a deny-list: a string
      88              : // survives verbatim only under a key this module knows to be structural, and
      89              : // only when it also has a structural shape. Everything else is summarized by
      90              : // length. Enumerating sensitive content cannot work — a `description` holding
      91              : // user prose and an unlisted credential format are both retained verbatim by a
      92              : // deny-list, whatever shapes it knows about.
      93         2355 : const STRUCTURAL_STRING_KEYS = new Set([
      94              :   'actor',
      95              :   'added',
      96              :   'class_type',
      97              :   'code',
      98              :   'context',
      99              :   'doc_id',
     100              :   'failed',
     101              :   'frame_type',
     102              :   'graph_id',
     103              :   'id',
     104              :   'kind',
     105              :   'level',
     106              :   'name',
     107              :   'node_id',
     108              :   'op',
     109              :   'op_id',
     110              :   'op_ids',
     111              :   'operations',
     112              :   'outcome',
     113              :   'phase',
     114              :   'prompt_id',
     115              :   'reason',
     116              :   'removed',
     117              :   'scope',
     118              :   'seq',
     119              :   'session_id',
     120              :   'skipped',
     121              :   'source',
     122              :   'state',
     123              :   'status',
     124              :   'subscribed_workflow_id',
     125              :   'tab',
     126              :   'tab_id',
     127              :   'target',
     128              :   'type',
     129              :   'v',
     130              :   'workflow_id'
     131              : ])
     132              : 
     133              : // An identifier, enum member or opaque id: bounded, and with no whitespace it
     134              : // cannot carry a sentence. A value that fails this is summarized even under an
     135              : // allow-listed key, so a producer that starts putting prose in `code` does not
     136              : // silently reopen the leak.
     137         2355 : const STRUCTURAL_VALUE = /^[A-Za-z0-9_.:@+/-]{0,64}$/
     138              : 
     139              : // Defense in depth for the strings the allow-list does retain: a short opaque
     140              : // id can still be a credential or a presigned URL.
     141         2355 : const URL_LIKE = /\b(?:https?|wss?):\/\/[^\s"'<>]+/gi
     142         2355 : const AUTH_SCHEME_TOKEN = /\b(?:Bearer|Basic|Token)\s+[\w.~+/=-]{8,}/gi
     143         2355 : const PREFIXED_SECRET =
     144              :   /\b(?:sk|pk|rk|ghp|gho|ghs|xox[abprs])[-_][\w.-]{8,}\b/gi
     145              : 
     146         2355 : let nextSeq = 1
     147         2355 : let buffer: DevEvent[] | undefined
     148              : 
     149              : /**
     150              :  * Keeps a URL's scheme, host and path (the part that says which endpoint a
     151              :  * frame was about) and drops userinfo and the whole query, because that is
     152              :  * where a presigned URL carries its signature and access token.
     153              :  */
     154            0 : function sanitizeUrl(raw: string): string {
     155            0 :   let url
     156            0 :   try {
     157            0 :     url = new URL(raw)
     158              :   } catch {
     159            0 :     return REDACTED
     160              :   }
     161            0 :   url.username = ''
     162            0 :   url.password = ''
     163            0 :   url.hash = ''
     164            0 :   const query = url.search === '' ? '' : `?${REDACTED}`
     165            0 :   url.search = ''
     166            0 :   return `${url.toString()}${query}`
     167              : }
     168              : 
     169            0 : function sanitizeString(value: string): string {
     170            0 :   return value
     171              :     .replace(URL_LIKE, (match) => sanitizeUrl(match))
     172              :     .replace(AUTH_SCHEME_TOKEN, REDACTED)
     173              :     .replace(PREFIXED_SECRET, REDACTED)
     174              : }
     175              : 
     176              : /**
     177              :  * What a free-form string degrades to. Length is the one property a reader can
     178              :  * use (empty vs. truncated vs. a whole prompt) that the string's content cannot
     179              :  * leak, and it reads like the other summaries the buffer already emits
     180              :  * (`Uint8Array(3)`, `Map(1)`).
     181              :  */
     182            0 : function summarizeString(value: string): string {
     183            0 :   return `String(${value.length})`
     184              : }
     185              : 
     186              : /**
     187              :  * `key` is the nearest enclosing object key, which an array passes down to its
     188              :  * items so `skipped: ['op-1']` is judged as `skipped`. A string with no
     189              :  * enclosing key — a bare `detail` — is never structural.
     190              :  */
     191            0 : function sanitizeStringValue(value: string, key: string | undefined): string {
     192            0 :   if (key !== undefined && STRUCTURAL_STRING_KEYS.has(key)) {
     193            0 :     if (STRUCTURAL_VALUE.test(value)) return sanitizeString(value)
     194              :   }
     195            0 :   return summarizeString(value)
     196              : }
     197              : 
     198            0 : function normalizeKey(key: string): string {
     199            0 :   return key
     200              :     .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
     201              :     .replace(/[^a-zA-Z0-9]+/g, '_')
     202              :     .toLowerCase()
     203              : }
     204              : 
     205            0 : function sanitizeObject(
     206              :   value: object,
     207              :   depth: number,
     208              :   ancestors: readonly object[],
     209              :   key: string | undefined
     210              : ): unknown {
     211            0 :   const nextAncestors = [...ancestors, value]
     212            0 :   if (Array.isArray(value)) {
     213            0 :     return value.map((item) =>
     214              :       sanitizeDetail(item, depth + 1, nextAncestors, key)
     215              :     )
     216              :   }
     217            0 :   if (value instanceof Error) {
     218              :     // `name` is the structural half of an Error; `message` is producer prose
     219              :     // and gets the same treatment as any other free-form string.
     220            0 :     return {
     221              :       name: sanitizeStringValue(value.name, 'name'),
     222              :       message: summarizeString(value.message)
     223              :     }
     224              :   }
     225            0 :   if (value instanceof Map) return `Map(${value.size})`
     226            0 :   if (value instanceof Set) return `Set(${value.size})`
     227            0 :   if (value instanceof Date) {
     228            0 :     return Number.isNaN(value.getTime()) ? null : value.toISOString()
     229              :   }
     230              : 
     231            0 :   return Object.fromEntries(
     232              :     Object.entries(value).map(([entryKey, item]) => {
     233            0 :       const normalizedKey = normalizeKey(entryKey)
     234            0 :       if (
     235              :         SENSITIVE_KEY.test(normalizedKey) ||
     236              :         CONTENT_KEYS.has(normalizedKey)
     237              :       ) {
     238            0 :         return [entryKey, REDACTED]
     239              :       }
     240            0 :       return [
     241              :         entryKey,
     242              :         sanitizeDetail(item, depth + 1, nextAncestors, normalizedKey)
     243              :       ]
     244              :     })
     245              :   )
     246              : }
     247              : 
     248            0 : function sanitizeDetail(
     249              :   value: unknown,
     250              :   depth = 0,
     251              :   ancestors: readonly object[] = [],
     252              :   key?: string
     253              : ): unknown {
     254            0 :   if (depth > MAX_SANITIZE_DEPTH) return REDACTED
     255            0 :   if (ArrayBuffer.isView(value)) {
     256            0 :     return `${value.constructor.name}(${value.byteLength})`
     257              :   }
     258            0 :   if (Object.prototype.toString.call(value) === '[object ArrayBuffer]') {
     259            0 :     return `ArrayBuffer(${(value as ArrayBuffer).byteLength})`
     260              :   }
     261            0 :   if (typeof value === 'string') return sanitizeStringValue(value, key)
     262            0 :   if (value === null || typeof value !== 'object') return value
     263            0 :   if (ancestors.includes(value)) return '[Circular]'
     264              : 
     265            0 :   return sanitizeObject(value, depth, ancestors, key)
     266              : }
     267              : 
     268              : /**
     269              :  * Shallow ref over the lazily allocated ring buffer. Production sessions that
     270              :  * never enable the debug instrument retain no event buffer. Once recording is
     271              :  * enabled, consumers get a stable array identity and mutations are announced
     272              :  * via triggerRef so a 500-entry log never churns deep reactivity.
     273              :  */
     274         2355 : export const devEvents = shallowRef<readonly DevEvent[]>([])
     275              : 
     276            1 : export function recordDevEvent(
     277              :   kind: DevEventKind,
     278              :   detail: unknown,
     279              :   options: DevEventOptions = {}
     280              : ): void {
     281            1 :   if (!isCrdtDebugEnabled()) return
     282            1 :   const events = buffer ?? (buffer = [])
     283            1 :   events.push({
     284              :     seq: nextSeq++,
     285              :     at: Date.now(),
     286              :     kind,
     287              :     scope: options.scope ?? 'doc',
     288              :     level: options.level ?? 'info',
     289              :     detail: sanitizeDevEventDetail(detail)
     290              :   })
     291            1 :   if (events.length > CAPACITY) events.splice(0, events.length - CAPACITY)
     292            0 :   if (devEvents.value !== events) devEvents.value = events
     293            0 :   else triggerRef(devEvents)
     294              : }
     295              : 
     296            0 : export function sanitizeDevEventDetail(detail: unknown): unknown {
     297            0 :   try {
     298            0 :     return sanitizeDetail(detail)
     299              :   } catch {
     300            0 :     reportError(new Error('Failed to sanitize CRDT dev event detail'), {
     301              :       surface: 'agent',
     302              :       errorType: 'crdt_dev_event_sanitization_failed'
     303              :     })
     304            0 :     return REDACTED
     305              :   }
     306              : }
     307              : 
     308            0 : export function clearDevEvents(): void {
     309            0 :   if (!buffer) return
     310            0 :   buffer.length = 0
     311            0 :   triggerRef(devEvents)
     312              : }
     313              : 
     314              : /**
     315              :  * Serializes an event detail defensively (typed arrays / ArrayBuffer don't
     316              :  * JSON well). Intentionally broad: any `ArrayBuffer.isView` value (not just
     317              :  * `Uint8Array`) collapses to `"<TypedArrayName>(byteLength)"`, and raw
     318              :  * `ArrayBuffer` collapses to `"ArrayBuffer(byteLength)"`. Dev-panel-only
     319              :  * output — see `devPanelLog.test.ts` "stringifies binary payloads
     320              :  * defensively" for the covered cases. (Follow-up to
     321              :  * https://github.com/Comfy-Org/ComfyUI_frontend/pull/16344 review comment.)
     322              :  */
     323            0 : export function stringifyDevEvents(events: readonly DevEvent[]): string {
     324            0 :   return JSON.stringify(events, devEventReplacer(), 2)
     325              : }
     326              : 
     327              : /**
     328              :  * JSON replacer shared by the panel's copy actions and the debug report.
     329              :  *
     330              :  * A binary payload is summarized by length rather than dumped: the bytes are
     331              :  * a Yjs update, unreadable to a human and large enough to push the interesting
     332              :  * fields out of a paste. Cyclic values degrade to a marker instead of
     333              :  * throwing, because the report must survive whatever the doc happens to hold.
     334              :  */
     335            0 : export function devEventReplacer(): (
     336              :   this: unknown,
     337              :   key: string,
     338              :   value: unknown
     339              : ) => unknown {
     340              :   // Tracks the ANCESTOR chain, not everything visited: a doc snapshot legally
     341              :   // references one object from two sibling positions, and a visited-set would
     342              :   // report the second as `[Circular]` and silently drop real data.
     343            0 :   const ancestors: unknown[] = []
     344            0 :   return function (this: unknown, _key, value) {
     345            0 :     while (ancestors.length > 0 && ancestors.at(-1) !== this) ancestors.pop()
     346            0 :     if (ArrayBuffer.isView(value)) {
     347            0 :       return `${value.constructor.name}(${value.byteLength})`
     348              :     }
     349            0 :     if (Object.prototype.toString.call(value) === '[object ArrayBuffer]') {
     350            0 :       return `ArrayBuffer(${(value as ArrayBuffer).byteLength})`
     351              :     }
     352            0 :     if (typeof value === 'bigint') return value.toString()
     353            0 :     if (typeof value === 'object' && value !== null) {
     354            0 :       if (ancestors.includes(value)) return '[Circular]'
     355            0 :       ancestors.push(value)
     356              :     }
     357            0 :     return value
     358              :   }
     359              : }
        

Generated by: LCOV version 2.0-1