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 : }
|