Line data Source code
1 : import { SCHEMA_VERSION } from '@comfyorg/comfy-multi-player'
2 : import type { DocOpsResultData, DocResetData } from '@comfyorg/ingest-types'
3 : import { zDocSubscribedData, zDocUpdateData } from '@comfyorg/ingest-types/zod'
4 :
5 : import { reportError } from '@comfyorg/telemetry/reportError'
6 :
7 : import { SERVER_DOC_FRAME_TYPES } from './docFrameCodes'
8 :
9 : export const DOC_PROTOCOL_VERSION = 1
10 : /** Keep this encoded-field cap aligned with cloud's `MaxDocFrameB64Len`. */
11 1 : const MAX_DOC_UPDATE_B64_LENGTH = 8 << 20
12 1 : const MAX_WORKFLOW_ID_LENGTH = 128
13 1 : const MAX_ACTOR_LENGTH = 256
14 1 : const MAX_AWARENESS_STATE_BYTES = 8 << 10
15 1 : const MAX_DOC_OPS_PER_FRAME = 256
16 1 : const MAX_OP_ID_LENGTH = 128
17 1 : const MAX_ERROR_CODE_LENGTH = 128
18 1 : const MAX_ERROR_MESSAGE_LENGTH = 8 << 10
19 1 : const BASE64_SINGLE_PADDING_END = /[AEIMQUYcgkosw048]=$/
20 1 : const BASE64_DOUBLE_PADDING_END = /[AQgw]==$/
21 1 : const utf8 = new TextEncoder()
22 :
23 : export interface DocOp {
24 : op_id: string
25 : actor: string
26 : [key: string]: unknown
27 : }
28 :
29 : export interface DocUpdate {
30 : workflowId: string
31 : seq: number
32 : lineageSeq?: number
33 : update: Uint8Array
34 : actor?: string
35 : /** Accepted semantic op identities folded into this effect frame (DQ-9). */
36 : opIds?: string[]
37 : }
38 :
39 : export interface DocSubscribed {
40 : workflowId: string
41 : ok: boolean
42 : seq?: number
43 : lineageSeq?: number
44 : expectedSeq?: number
45 : code?: string
46 : message?: string
47 : }
48 :
49 : export interface DocOpFailure {
50 : index: number
51 : /** Absent when the relay cannot map the failing index to an op id. */
52 : op_id?: string
53 : code: string
54 : message: string
55 : }
56 :
57 : export interface DocOpsResult {
58 : workflowId: string
59 : ok: boolean
60 : seq?: number
61 : applied: string[]
62 : skipped: string[]
63 : lwwDropped?: DocOpsResultData['lww_dropped']
64 : code?: string
65 : message?: string
66 : /** Validated diagnostics for the first rejected operation in a batch. */
67 : failed?: DocOpFailure
68 : }
69 :
70 : export interface DocReseedResult {
71 : workflowId: string
72 : ok: boolean
73 : seq?: number
74 : outcome?: string
75 : code?: string
76 : message?: string
77 : }
78 :
79 : interface DocAwareness {
80 : workflowId: string
81 : actor: string
82 : state?: Record<string, unknown>
83 : expiresAt?: number
84 : }
85 :
86 : /**
87 : * Host→follower lineage break: the document was re-minted, so updates from
88 : * before this frame do NOT compose with what comes after. Deliberately
89 : * payload-less — the fresh state arrives through the ordinary subscribe
90 : * catch-up path, never a second snapshot channel.
91 : */
92 : export interface DocReset {
93 : workflowId: string
94 : seq: number
95 : lineageSeq: number
96 : actor?: string
97 : }
98 :
99 : export type ServerDocFrame =
100 : | { type: 'doc_update'; data: DocUpdate }
101 : | { type: 'doc_subscribed'; data: DocSubscribed }
102 : | { type: 'doc_ops_result'; data: DocOpsResult }
103 : | { type: 'doc_reset'; data: DocReset }
104 : | { type: 'doc_reseed_result'; data: DocReseedResult }
105 : | { type: 'awareness'; data: DocAwareness }
106 :
107 : /** A frame as it travels the wire, before {@link parseServerDocFrame} reads it. */
108 : export interface DocFrameTransport {
109 : /**
110 : * Best-effort send. Returns `true` when the frame left the transport and
111 : * `false` when the transport cannot currently carry it (socket not OPEN).
112 : *
113 : * It MUST NOT throw. "The socket is not connected yet" is a normal,
114 : * recoverable state of a follower that mounted while `createSocket` was still
115 : * awaiting its auth token — not an exception. Throwing here aborted the
116 : * `watch(..., { immediate: true })` subscribe (leaving the follower
117 : * permanently inert) and aborted `onBeforeUnmount` before `client.destroy()`
118 : * (leaking listeners and a live projector). Callers reconcile intent against
119 : * the returned boolean instead.
120 : */
121 : send(frame: string): boolean
122 : addEventListener(type: string, listener: EventListener): void
123 : removeEventListener(type: string, listener: EventListener): void
124 : }
125 :
126 : interface WireData {
127 : v?: unknown
128 : workflow_id?: unknown
129 : seq?: unknown
130 : expected_seq?: unknown
131 : update_b64?: unknown
132 : actor?: unknown
133 : op_ids?: unknown
134 : ok?: unknown
135 : code?: unknown
136 : message?: unknown
137 : applied?: unknown
138 : skipped?: unknown
139 : lww_dropped?: unknown
140 : failed?: unknown
141 : state?: unknown
142 : expires_at?: unknown
143 : index?: unknown
144 : op_id?: unknown
145 : outcome?: unknown
146 : lineage_seq?: unknown
147 : }
148 :
149 0 : function decodeBase64(value: string): Uint8Array | null {
150 0 : if (value === '' || value.length % 4 !== 0) return null
151 0 : const padding = value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0
152 0 : if (value.length > MAX_DOC_UPDATE_B64_LENGTH) return null
153 :
154 : // `atob` is permissive about missing padding, so require canonical standard
155 : // base64 before decoding the untrusted wire value.
156 0 : if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return null
157 :
158 0 : if (padding === 2 && !BASE64_DOUBLE_PADDING_END.test(value)) return null
159 0 : if (padding === 1 && !BASE64_SINGLE_PADDING_END.test(value)) return null
160 :
161 0 : try {
162 0 : const binary = atob(value)
163 0 : return Uint8Array.from(binary, (character) => character.charCodeAt(0))
164 : } catch {
165 0 : return null
166 : }
167 : }
168 :
169 0 : export function encodeBase64(value: Uint8Array): string {
170 0 : let binary = ''
171 0 : for (const byte of value) binary += String.fromCharCode(byte)
172 0 : return btoa(binary)
173 : }
174 :
175 0 : function parseWireData(value: unknown): WireData | null {
176 0 : return typeof value === 'object' && value !== null ? value : null
177 : }
178 :
179 0 : function parseRecord(value: unknown): Record<string, unknown> | null {
180 0 : return typeof value === 'object' && value !== null && !Array.isArray(value)
181 : ? Object.fromEntries(Object.entries(value))
182 : : null
183 : }
184 :
185 0 : function isAbsent(value: unknown): value is null | undefined {
186 0 : return value === null || value === undefined
187 : }
188 :
189 0 : function hasBoundedUtf8Length(value: string, maxBytes: number): boolean {
190 0 : return value.length <= maxBytes && utf8.encode(value).length <= maxBytes
191 : }
192 :
193 0 : function isValidWorkflowId(value: string): boolean {
194 0 : return (
195 : value.length > 0 &&
196 : hasBoundedUtf8Length(value, MAX_WORKFLOW_ID_LENGTH) &&
197 : !/[\0\n\r\t :*?[\]]/.test(value)
198 : )
199 : }
200 :
201 0 : function isValidActor(value: string): boolean {
202 0 : if (
203 : value.length === 0 ||
204 : !hasBoundedUtf8Length(value, MAX_ACTOR_LENGTH) ||
205 : /[\0\n\r\t ]/.test(value)
206 : )
207 0 : return false
208 0 : if (value === 'system:mint') return true
209 : const match = /^(?:agent|human):([^:]+):([^:]+)$/.exec(value)
210 0 : return match !== null
211 : }
212 :
213 : /**
214 : * Attribution on effect frames is advisory, unlike awareness's actor key.
215 : * Preserve the load-bearing effect and omit attribution that fails grammar.
216 : */
217 0 : function parseAdvisoryActor(value: unknown): string | undefined {
218 0 : return typeof value === 'string' && isValidActor(value) ? value : undefined
219 : }
220 :
221 0 : function isSequence(value: unknown): value is number {
222 0 : return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
223 : }
224 :
225 0 : function parseSequence(value: unknown): number | null {
226 0 : if (isSequence(value)) return value
227 0 : if (
228 : typeof value === 'bigint' &&
229 : value >= 0n &&
230 : value <= BigInt(Number.MAX_SAFE_INTEGER)
231 : )
232 0 : return Number(value)
233 0 : return null
234 : }
235 :
236 0 : function isValidOpId(value: unknown): value is string {
237 0 : return (
238 : typeof value === 'string' &&
239 : value.length > 0 &&
240 : hasBoundedUtf8Length(value, MAX_OP_ID_LENGTH) &&
241 : !/[\0\n\r\t]/.test(value)
242 : )
243 : }
244 :
245 0 : function isStringArray(value: unknown): value is string[] {
246 0 : return (
247 : Array.isArray(value) &&
248 : value.length <= MAX_DOC_OPS_PER_FRAME &&
249 : value.every(isValidOpId)
250 : )
251 : }
252 :
253 0 : function parseBoundedString(
254 : value: unknown,
255 : maxBytes: number
256 : ): string | undefined {
257 0 : return typeof value === 'string' && hasBoundedUtf8Length(value, maxBytes)
258 : ? value
259 : : undefined
260 : }
261 :
262 : /**
263 : * The relay serialises `applied`/`skipped` with `omitempty`, so an empty list
264 : * arrives as an absent field. Absent means empty; present-but-malformed is a
265 : * protocol violation.
266 : */
267 0 : function parseOptionalStringArray(value: unknown): string[] | null {
268 0 : if (isAbsent(value)) return []
269 0 : return isStringArray(value) ? value : null
270 : }
271 :
272 0 : function parseDocOpFailure(value: unknown): DocOpFailure | null {
273 0 : const failure = parseWireData(value)
274 0 : if (
275 : failure === null ||
276 : !isSequence(failure.index) ||
277 : (!isAbsent(failure.op_id) && !isValidOpId(failure.op_id)) ||
278 : typeof failure.code !== 'string' ||
279 : !hasBoundedUtf8Length(failure.code, MAX_ERROR_CODE_LENGTH) ||
280 : typeof failure.message !== 'string' ||
281 : !hasBoundedUtf8Length(failure.message, MAX_ERROR_MESSAGE_LENGTH)
282 : )
283 0 : return null
284 :
285 0 : return {
286 : index: failure.index,
287 : ...(!isAbsent(failure.op_id) && { op_id: failure.op_id }),
288 : code: failure.code,
289 : message: failure.message
290 : }
291 : }
292 :
293 : // Defence in depth behind the server's identical cap. The counts are not
294 : // byte-identical: Go's json.Marshal HTML-escapes `<`, `>` and `&`, so the
295 : // server always counts >= this and is the stricter of the two.
296 0 : function encodedJsonSize(value: Record<string, unknown>): number | null {
297 0 : try {
298 0 : const encoded = JSON.stringify(value)
299 0 : if (encoded.length > MAX_AWARENESS_STATE_BYTES) return encoded.length
300 0 : return utf8.encode(encoded).length
301 : } catch {
302 0 : return null
303 : }
304 : }
305 :
306 0 : function parseDocReseedResult(
307 : workflowId: string,
308 : ok: boolean,
309 : data: WireData
310 : ): DocReseedResult {
311 0 : const outcome = parseBoundedString(data.outcome, MAX_ERROR_CODE_LENGTH)
312 0 : const code = parseBoundedString(data.code, MAX_ERROR_CODE_LENGTH)
313 0 : const message = parseBoundedString(data.message, MAX_ERROR_MESSAGE_LENGTH)
314 0 : return {
315 : workflowId,
316 : ok,
317 : ...(isSequence(data.seq) && { seq: data.seq }),
318 : ...(outcome !== undefined && { outcome }),
319 : ...(code !== undefined && { code }),
320 : ...(message !== undefined && { message })
321 : }
322 : }
323 :
324 : // The generated contract defines an accepted ack's omitted lineage_seq as
325 : // lineage 0, which is what the host's omitempty encoding sends for a
326 : // document whose lineage began at 0.
327 0 : function parseSubscribedLineage(value: unknown): number | null {
328 0 : const parsed = zDocSubscribedData.shape.lineage_seq.safeParse(value)
329 0 : if (!parsed.success) return null
330 0 : return parsed.data === undefined ? 0 : parseSequence(parsed.data)
331 : }
332 :
333 0 : function parseDocSubscribed(
334 : workflowId: string,
335 : ok: boolean,
336 : data: WireData
337 : ): DocSubscribed | null {
338 0 : const lineageSeq = ok ? parseSubscribedLineage(data.lineage_seq) : undefined
339 0 : if (lineageSeq === null) return null
340 0 : const code = parseBoundedString(data.code, MAX_ERROR_CODE_LENGTH)
341 0 : const message = parseBoundedString(data.message, MAX_ERROR_MESSAGE_LENGTH)
342 0 : return {
343 : workflowId,
344 : ok,
345 : ...(isSequence(data.seq) && { seq: data.seq }),
346 : ...(lineageSeq !== undefined && { lineageSeq }),
347 : ...(isSequence(data.expected_seq) && { expectedSeq: data.expected_seq }),
348 : ...(code !== undefined && { code }),
349 : ...(message !== undefined && { message })
350 : }
351 : }
352 :
353 : type ServerFrameParsers = {
354 : [K in ServerDocFrame['type']]: (
355 : workflowId: string,
356 : data: WireData
357 : ) => Extract<ServerDocFrame, { type: K }> | null
358 : }
359 :
360 0 : function parseResultMetadata(data: WireData) {
361 0 : const code = parseBoundedString(data.code, MAX_ERROR_CODE_LENGTH)
362 0 : const message = parseBoundedString(data.message, MAX_ERROR_MESSAGE_LENGTH)
363 0 : const seq = parseSequence(data.seq)
364 0 : return {
365 : ...(seq !== null && { seq }),
366 : ...(code !== undefined && { code }),
367 : ...(message !== undefined && { message })
368 : }
369 : }
370 :
371 0 : function fitsAwarenessBudget(state: Record<string, unknown>): boolean {
372 0 : const stateSize = encodedJsonSize(state)
373 0 : return stateSize !== null && stateSize <= MAX_AWARENESS_STATE_BYTES
374 : }
375 :
376 : type AwarenessStateResult =
377 : | { kind: 'present'; state: Record<string, unknown> }
378 : | { kind: 'absent' }
379 : | { kind: 'invalid' }
380 :
381 0 : function parseAwarenessState(value: unknown): AwarenessStateResult {
382 0 : if (isAbsent(value)) return { kind: 'absent' }
383 0 : const state = parseRecord(value)
384 0 : if (state === null || !fitsAwarenessBudget(state)) return { kind: 'invalid' }
385 0 : return { kind: 'present', state }
386 : }
387 :
388 0 : function parseDocUpdateLineage(value: unknown): number | null {
389 0 : const parsed = zDocUpdateData.shape.lineage_seq.safeParse(value)
390 0 : return parsed.success ? parseSequence(parsed.data) : null
391 : }
392 :
393 0 : function parseDocUpdateBytes(value: unknown): Uint8Array | null {
394 0 : return typeof value === 'string' ? decodeBase64(value) : null
395 : }
396 :
397 0 : function parseDocUpdateFrame(
398 : workflowId: string,
399 : data: WireData
400 : ): Extract<ServerDocFrame, { type: 'doc_update' }> | null {
401 0 : const seq = parseSequence(data.seq)
402 0 : const lineageSeq = parseDocUpdateLineage(data.lineage_seq)
403 0 : const update = parseDocUpdateBytes(data.update_b64)
404 0 : if (seq === null || lineageSeq === null || update === null) return null
405 0 : if (!isAbsent(data.op_ids) && !isStringArray(data.op_ids)) return null
406 0 : const actor = parseAdvisoryActor(data.actor)
407 0 : return {
408 : type: 'doc_update',
409 : data: {
410 : workflowId,
411 : seq,
412 : lineageSeq,
413 : update,
414 : ...(actor !== undefined && { actor }),
415 : ...(isStringArray(data.op_ids) && { opIds: data.op_ids })
416 : }
417 : }
418 : }
419 :
420 1 : const serverFrameParsers: ServerFrameParsers = {
421 : doc_update: parseDocUpdateFrame,
422 : doc_subscribed: (workflowId, data) => {
423 0 : if (typeof data.ok !== 'boolean') return null
424 0 : const subscribed = parseDocSubscribed(workflowId, data.ok, data)
425 0 : return subscribed && { type: 'doc_subscribed', data: subscribed }
426 : },
427 : doc_ops_result: (workflowId, data) => {
428 0 : if (typeof data.ok !== 'boolean') return null
429 0 : const applied = parseOptionalStringArray(data.applied)
430 0 : const skipped = parseOptionalStringArray(data.skipped)
431 0 : const lwwDropped = parseOptionalStringArray(data.lww_dropped)
432 0 : if (applied === null || skipped === null || lwwDropped === null) return null
433 0 : const skippedIds = new Set(skipped)
434 0 : if (lwwDropped.some((opId) => !skippedIds.has(opId))) return null
435 0 : const failed = parseDocOpFailure(data.failed) ?? undefined
436 0 : return {
437 : type: 'doc_ops_result',
438 : data: {
439 : workflowId,
440 : ok: data.ok,
441 : applied,
442 : skipped,
443 : ...(lwwDropped.length > 0 && { lwwDropped }),
444 : ...parseResultMetadata(data),
445 : ...(failed !== undefined && { failed })
446 : }
447 : }
448 : },
449 : doc_reset: (workflowId, data) => {
450 0 : const reset: Partial<Record<keyof DocResetData, unknown>> = data
451 0 : const seq = parseSequence(reset.seq)
452 0 : const lineageSeq = parseSequence(reset.lineage_seq)
453 0 : if (seq === null || lineageSeq === null) return null
454 0 : const actor = parseAdvisoryActor(reset.actor)
455 0 : return {
456 : type: 'doc_reset',
457 : data: {
458 : workflowId,
459 : seq,
460 : lineageSeq,
461 : ...(actor !== undefined && { actor })
462 : }
463 : }
464 : },
465 : doc_reseed_result: (workflowId, data) =>
466 : typeof data.ok === 'boolean'
467 : ? {
468 : type: 'doc_reseed_result',
469 : data: parseDocReseedResult(workflowId, data.ok, data)
470 : }
471 : : null,
472 : awareness: (workflowId, data) => {
473 0 : if (typeof data.actor !== 'string' || !isValidActor(data.actor)) return null
474 0 : const parsed = parseAwarenessState(data.state)
475 0 : if (parsed.kind === 'invalid') return null
476 0 : if (!isAbsent(data.expires_at) && !isSequence(data.expires_at)) return null
477 0 : return {
478 : type: 'awareness',
479 : data: {
480 : workflowId,
481 : actor: data.actor,
482 : ...(parsed.kind === 'present' && { state: parsed.state }),
483 : ...(isSequence(data.expires_at) && { expiresAt: data.expires_at })
484 : }
485 : }
486 : }
487 : }
488 :
489 0 : export function parseServerDocFrame(value: unknown): ServerDocFrame | null {
490 0 : if (typeof value !== 'object' || value === null) return null
491 0 : const frame = value as { type?: unknown; data?: unknown }
492 0 : const data = parseWireData(frame.data)
493 0 : if (
494 : data === null ||
495 : data.v !== DOC_PROTOCOL_VERSION ||
496 : typeof data.workflow_id !== 'string' ||
497 : !isValidWorkflowId(data.workflow_id)
498 : )
499 0 : return null
500 :
501 0 : if (typeof frame.type !== 'string' || !isServerFrameType(frame.type))
502 0 : return null
503 0 : return serverFrameParsers[frame.type](data.workflow_id, data)
504 : }
505 :
506 0 : function isServerFrameType(type: string): type is ServerDocFrame['type'] {
507 0 : return Object.hasOwn(serverFrameParsers, type)
508 : }
509 :
510 1 : export class DocFrameClient extends EventTarget {
511 : private readonly listeners = new Map<string, EventListener>()
512 :
513 1 : constructor(private readonly transport: DocFrameTransport) {
514 1 : super()
515 1 : const reportedTypes = new Set<string>()
516 1 : for (const type of SERVER_DOC_FRAME_TYPES) {
517 6 : const listener: EventListener = (event) => {
518 0 : if (!(event instanceof CustomEvent)) return
519 0 : const parsed = parseServerDocFrame({ type, data: event.detail })
520 0 : if (parsed) {
521 0 : this.dispatchEvent(new CustomEvent(type, { detail: parsed.data }))
522 0 : return
523 : }
524 0 : if (reportedTypes.has(type)) return
525 0 : reportedTypes.add(type)
526 0 : reportError(new Error('Discarded invalid server document frame'), {
527 : surface: 'agent',
528 : errorType: 'agent_crdt_invalid_server_frame',
529 : tags: { frame_type: type },
530 : level: 'warning'
531 : })
532 : }
533 6 : this.listeners.set(type, listener)
534 6 : transport.addEventListener(type, listener)
535 : }
536 : }
537 :
538 : /** @returns whether the subscribe frame actually left the transport. */
539 : subscribe(
540 : workflowId: string,
541 : stateVector: Uint8Array,
542 : knownLineageSeq = 0
543 : ): boolean {
544 0 : return this.send('doc_subscribe', {
545 : v: DOC_PROTOCOL_VERSION,
546 : workflow_id: workflowId,
547 : state_vector_b64: encodeBase64(stateVector),
548 : known_lineage_seq: knownLineageSeq,
549 : supports_reseed: true,
550 : schema_version: SCHEMA_VERSION
551 : })
552 : }
553 :
554 : reseed(
555 : workflowId: string,
556 : expectedSeq: number,
557 : workflow: Record<string, unknown>
558 : ): boolean {
559 0 : return this.send('doc_reseed', {
560 : v: DOC_PROTOCOL_VERSION,
561 : workflow_id: workflowId,
562 : expected_seq: expectedSeq,
563 : workflow
564 : })
565 : }
566 :
567 : /** @returns whether the unsubscribe frame actually left the transport. */
568 : unsubscribe(workflowId: string): boolean {
569 0 : return this.send('doc_unsubscribe', {
570 : v: DOC_PROTOCOL_VERSION,
571 : workflow_id: workflowId
572 : })
573 : }
574 :
575 : /** @returns whether the ops frame actually left the transport. */
576 : sendOps(workflowId: string, tab: string, ops: readonly DocOp[]): boolean {
577 0 : return this.send('doc_ops', {
578 : v: DOC_PROTOCOL_VERSION,
579 : workflow_id: workflowId,
580 : tab,
581 : ops
582 : })
583 : }
584 :
585 : destroy(): void {
586 0 : for (const [type, listener] of this.listeners)
587 0 : this.transport.removeEventListener(type, listener)
588 0 : this.listeners.clear()
589 : }
590 :
591 : private send(type: string, data: Record<string, unknown>): boolean {
592 0 : return this.transport.send(JSON.stringify({ type, data }))
593 : }
594 : }
|