Line data Source code
1 : import { assert } from '@/base/assert'
2 : import { reportError } from '@comfyorg/telemetry/reportError'
3 :
4 : import type {
5 : DocFrameClient,
6 : DocOp,
7 : DocReseedResult,
8 : DocReset,
9 : DocSubscribed,
10 : DocUpdate
11 : } from './docFrameClient'
12 : import { wireLog } from './crdtLog'
13 : import { RESEED_CONFLICT, STALE_SCHEMA_RESEED_REQUIRED } from './docFrameCodes'
14 : import { FollowerDoc } from './followerDoc'
15 : import { FollowerSchemaError, assertReadableSchema } from './schemaGuard'
16 :
17 : /** A document update after the follower bridge has classified its provenance. */
18 : export interface ClassifiedDocUpdate extends DocUpdate {
19 : catchUp: boolean
20 : }
21 :
22 0 : export function isLiveAgentUpdate(
23 : update: Pick<DocUpdate, 'actor'> &
24 : Partial<Pick<ClassifiedDocUpdate, 'catchUp'>>
25 : ): boolean {
26 0 : return update.catchUp === false && update.actor?.startsWith('agent:') === true
27 : }
28 :
29 0 : function trySend(send: () => boolean): boolean {
30 0 : try {
31 0 : return send()
32 : } catch (error) {
33 0 : reportError(error, {
34 : surface: 'agent',
35 : errorType: 'failure_sending_agent_doc_frame',
36 : logToConsole: false,
37 : tags: {
38 : failure_kind: 'caught_unexpected',
39 : feature_area: 'agent',
40 : operation: 'sync',
41 : outcome: 'recovered'
42 : },
43 : level: 'error'
44 : })
45 0 : wireLog.warn('frame_send_failed', 'outbound doc frame dropped', error)
46 0 : return false
47 : }
48 : }
49 :
50 : /**
51 : * Bridges server doc frames to the follower's semantic {@link FollowerDoc} and
52 : * re-dispatches them. It does NOT touch the layout store: the semantic doc is
53 : * applied to the domain stores by the ECS follower adapter. It never merges the
54 : * semantic update into layoutStore: semantic and layout state remain separate
55 : * Y.Docs.
56 : *
57 : * Subscription is modelled as INTENT reconciled against transport REALITY, and
58 : * teardown is failure-tolerant; see the two id fields and {@link destroy}.
59 : */
60 1 : export class LayoutFollowerBridge extends EventTarget {
61 : /**
62 : * Reassigned only on a lineage break — an explicit `doc_reset`
63 : * ({@link onDocReset}) or a subscribe to a DIFFERENT workflow
64 : * ({@link subscribe}) — because folding one document's history into another
65 : * merges two unrelated lineages: the next subscribe would carry the old
66 : * doc's state vector, the host would compute a nonsense delta against it,
67 : * and both workflows' nodes would land on one canvas (FEB-5).
68 : */
69 : private followerDoc = new FollowerDoc()
70 : /**
71 : * The workflow whose lineage {@link followerDoc} holds — the id passed to
72 : * the most recent {@link subscribe}. Unlike {@link desiredWorkflowId} it
73 : * survives {@link unsubscribe}, because detaching does not empty the doc:
74 : * a later subscribe to a DIFFERENT workflow must still re-mint it.
75 : */
76 : private lineageWorkflowId: string | null = null
77 : private lineageSeq: number | null = null
78 : /**
79 : * Subscription INTENT — the workflow the app wants followed. Set
80 : * synchronously by the caller; independent of whether any frame has left the
81 : * transport yet.
82 : */
83 : private desiredWorkflowId: string | null = null
84 : /**
85 : * Subscription REALITY — the workflow a `doc_subscribe` frame actually left
86 : * the transport for. Only this gates inbound updates.
87 : *
88 : * Splitting the two is the fix for the "panel mounted before the socket
89 : * opened" trap: the old single `workflowId` field was set BEFORE the send,
90 : * so a send that could not go out still latched the field and the
91 : * `if (this.workflowId === workflowId) return` guard blocked every retry —
92 : * permanently, because `api` only dispatches `reconnected` on a RE-connect,
93 : * never on the first successful open.
94 : */
95 : private sentWorkflowId: string | null = null
96 : /**
97 : * The most recent KA-11 read-gate failure, while the merged doc is still
98 : * unreadable. Cleared by a lineage break ({@link dropDocForNewLineage}) or
99 : * by a later same-lineage frame that merges and leaves the doc readable
100 : * again — see {@link onDocUpdate}.
101 : */
102 : private schemaError: FollowerSchemaError | null = null
103 : private lastSeq: number | null = null
104 : private attemptFirstSeq: number | null = null
105 : private attemptLastSeq: number | null = null
106 : private integratedSeq: number | null = null
107 : private ackSeq: number | null = null
108 : /**
109 : * Armed by the ack, disarmed by the first applied frame whose seq equals
110 : * {@link ackSeq}. The relay joins the fanout BEFORE it acks, so a live frame
111 : * N+1 can reach the follower ahead of `doc_subscribed(seq=N)` and the
112 : * catch-up `doc_update(seq=N)`. The catch-up is the only frame carrying what
113 : * this follower's state vector lacked; if the stale check judged it against
114 : * the already-applied N+1 it would be dropped and the hole would never show
115 : * up as a gap. While armed, exactly one frame at seq == ackSeq bypasses the
116 : * stale check (Yjs integration is idempotent, so a true duplicate is
117 : * harmless). It never moves {@link lastSeq} backwards.
118 : */
119 : private catchUpPending = false
120 : private pendingReseedWorkflowId: string | null = null
121 : private reseedToken: { workflowId: string; expectedSeq: number } | null = null
122 : private reseedBlockedUntilConfirmedWorkflowId: string | null = null
123 :
124 1 : constructor(private readonly client: DocFrameClient) {
125 1 : super()
126 1 : client.addEventListener('doc_update', this.onDocUpdate)
127 1 : client.addEventListener('doc_reset', this.onDocReset)
128 1 : client.addEventListener('doc_subscribed', this.onDocSubscribed)
129 1 : client.addEventListener('doc_ops_result', this.forwardFrame)
130 1 : client.addEventListener('doc_reseed_result', this.onDocReseedResult)
131 : }
132 :
133 : /** The semantic doc this bridge currently follows. */
134 : get follower(): FollowerDoc {
135 0 : return this.followerDoc
136 : }
137 :
138 : /** The workflow a subscribe frame actually went out for, if any. */
139 : get subscribedWorkflowId(): string | null {
140 0 : return this.sentWorkflowId
141 : }
142 :
143 : /** The higher of the last applied doc seq and the current subscribe's ack. */
144 : get lastSequence(): number {
145 0 : return Math.max(this.lastSeq ?? 0, this.ackSeq ?? 0)
146 : }
147 :
148 : /** True from a subscribe until its catch-up, if any, has been integrated. */
149 : get isCatchingUp(): boolean {
150 0 : return (
151 : this.sentWorkflowId !== null &&
152 : (this.ackSeq === null || this.catchUpPending)
153 : )
154 : }
155 :
156 : get isSubscribeBaselineIntegrated(): boolean {
157 0 : return (
158 : this.ackSeq !== null &&
159 : this.integratedSeq !== null &&
160 : this.integratedSeq >= this.ackSeq &&
161 : this.schemaError === null
162 : )
163 : }
164 :
165 : /** The KA-11 read-gate failure that closed this bridge's read path, if any. */
166 : get lastSchemaError(): FollowerSchemaError | null {
167 0 : return this.schemaError
168 : }
169 :
170 : /** True while intent and reality disagree — i.e. a retry is still owed. */
171 : get hasPendingSubscribe(): boolean {
172 0 : return (
173 : this.desiredWorkflowId !== null &&
174 : this.sentWorkflowId !== this.desiredWorkflowId
175 : )
176 : }
177 :
178 : /**
179 : * Follow a workflow. Subscribing to a DIFFERENT workflow than the one this
180 : * bridge's doc holds is a lineage break (FEB-5): the doc is re-minted so
181 : * the subscribe carries an empty state vector, and `follower_replaced` is
182 : * dispatched — unconditionally, even when the send could not leave a closed
183 : * socket — so consumers rebind their observers to the new doc rather than
184 : * staying attached to the destroyed one. Re-subscribing to the SAME
185 : * workflow keeps the doc: that is the same-lineage catch-up path
186 : * (ADR-GRAPH-DOCUMENT-0024), where the state vector makes the delta cheap.
187 : */
188 : subscribe(workflowId: string, knownLineageSeq: number | null = null): void {
189 0 : const lineage = this.lineageWorkflowId
190 0 : if (this.desiredWorkflowId !== workflowId) {
191 0 : this.reseedBlockedUntilConfirmedWorkflowId = null
192 0 : this.reseedToken = null
193 : }
194 0 : this.lineageWorkflowId = workflowId
195 0 : this.desiredWorkflowId = workflowId
196 0 : if (lineage !== null && lineage !== workflowId) {
197 0 : this.dropDocForNewLineage()
198 0 : this.lineageSeq = knownLineageSeq
199 0 : this.dispatchEvent(
200 : new CustomEvent('follower_replaced', { detail: { workflowId } })
201 : )
202 0 : this.reconcile()
203 0 : return
204 : }
205 0 : this.lineageSeq ??= knownLineageSeq
206 0 : this.reconcile()
207 : }
208 :
209 : /** Drive intent at the transport. Idempotent and safe to call at any time. */
210 : reconcile(): boolean {
211 2 : const desired = this.desiredWorkflowId
212 2 : if (this.sentWorkflowId !== null && this.sentWorkflowId !== desired) {
213 0 : const sent = this.sentWorkflowId
214 0 : this.sentWorkflowId = null
215 0 : trySend(() => this.client.unsubscribe(sent))
216 : }
217 2 : if (desired === null || this.sentWorkflowId === desired) return false
218 0 : if (
219 : trySend(() =>
220 : this.client.subscribe(
221 : desired,
222 : this.follower.stateVector(),
223 : this.lineageSeq ?? 0
224 : )
225 : )
226 : ) {
227 0 : this.sentWorkflowId = desired
228 0 : this.attemptFirstSeq = null
229 0 : this.attemptLastSeq = null
230 0 : this.ackSeq = null
231 0 : this.catchUpPending = false
232 0 : this.dispatchEvent(
233 : new CustomEvent('doc_subscribe_sent', {
234 : detail: { workflowId: desired }
235 : })
236 : )
237 0 : return true
238 : }
239 0 : return false
240 : }
241 :
242 : resubscribe(): boolean {
243 1 : this.sentWorkflowId = null
244 1 : return this.reconcile()
245 : }
246 :
247 : reconnect(): void {
248 1 : this.reseedBlockedUntilConfirmedWorkflowId = null
249 1 : this.reseedToken = null
250 1 : this.resubscribe()
251 : }
252 :
253 : unsubscribe(): void {
254 1 : this.desiredWorkflowId = null
255 1 : this.reconcile()
256 : }
257 :
258 : reseed(workflowId: string, workflow: Record<string, unknown>): boolean {
259 0 : const expectedSeq = this.reseedSequenceFor(workflowId)
260 0 : if (expectedSeq === null) {
261 0 : assert(
262 : false,
263 : 'followers send a whole canvas only to answer a current stale-schema refusal — see ADR-CRDT-FOLLOWER-0025',
264 : { workflowId }
265 : )
266 0 : return false
267 : }
268 0 : this.reseedToken = null
269 0 : if (!trySend(() => this.client.reseed(workflowId, expectedSeq, workflow)))
270 0 : return false
271 0 : this.pendingReseedWorkflowId = workflowId
272 0 : return true
273 : }
274 :
275 : canReseed(workflowId: string): boolean {
276 0 : return this.reseedSequenceFor(workflowId) !== null
277 : }
278 :
279 : private reseedSequenceFor(workflowId: string): number | null {
280 0 : const token = this.reseedToken
281 0 : return token?.workflowId === workflowId &&
282 : workflowId === this.desiredWorkflowId &&
283 : workflowId !== this.reseedBlockedUntilConfirmedWorkflowId
284 : ? token.expectedSeq
285 : : null
286 : }
287 :
288 : sendHumanOps(tab: string, ops: DocOp[]): void {
289 0 : const workflowId = this.sentWorkflowId
290 0 : if (workflowId === null || ops.length === 0) return
291 0 : trySend(() => this.client.sendOps(workflowId, tab, ops))
292 : }
293 :
294 : /**
295 : * Release everything this bridge owns. Teardown is failure-tolerant: the
296 : * unsubscribe is best-effort and can never prevent the listener detach or the
297 : * Y.Doc destroy, because a bridge that survives its composable keeps applying
298 : * remote updates through an adapter still wired to the live stores.
299 : */
300 : destroy(): void {
301 0 : try {
302 0 : this.unsubscribe()
303 : } finally {
304 0 : this.client.removeEventListener('doc_update', this.onDocUpdate)
305 0 : this.client.removeEventListener('doc_reset', this.onDocReset)
306 0 : this.client.removeEventListener('doc_subscribed', this.onDocSubscribed)
307 0 : this.client.removeEventListener('doc_ops_result', this.forwardFrame)
308 0 : this.client.removeEventListener(
309 : 'doc_reseed_result',
310 : this.onDocReseedResult
311 : )
312 0 : this.desiredWorkflowId = null
313 0 : this.sentWorkflowId = null
314 0 : this.followerDoc.destroy()
315 : }
316 : }
317 :
318 : private readonly onDocUpdate: EventListener = (event) => {
319 0 : if (!(event instanceof CustomEvent)) return
320 0 : const update = event.detail as DocUpdate
321 0 : if (update.workflowId !== this.sentWorkflowId) return
322 0 : if (this.rejectForeignLineageUpdate(update)) return
323 :
324 0 : const isCatchUp = this.catchUpPending && update.seq === this.ackSeq
325 0 : if (this.rejectStaleUpdate(update, isCatchUp)) return
326 :
327 0 : if (this.rejectSequenceGap(update)) return
328 0 : this.recordAppliedSequence(update.seq)
329 0 : this.follower.applyRemoteUpdate(update.update)
330 0 : this.recordIntegratedSequence(update.seq, isCatchUp)
331 :
332 0 : if (!this.isReadableUpdate(update)) return
333 :
334 0 : const classifiedUpdate: ClassifiedDocUpdate = {
335 : ...update,
336 : catchUp: isCatchUp
337 : }
338 0 : this.dispatchEvent(
339 : new CustomEvent('doc_update', {
340 : detail: classifiedUpdate
341 : })
342 : )
343 : }
344 :
345 : private rejectForeignLineageUpdate(update: DocUpdate): boolean {
346 0 : if (
347 : update.lineageSeq !== undefined &&
348 : this.lineageSeq !== null &&
349 : update.lineageSeq !== this.lineageSeq
350 : ) {
351 0 : const reset: DocReset = {
352 : workflowId: update.workflowId,
353 : seq: update.seq,
354 : lineageSeq: update.lineageSeq,
355 : actor: update.actor
356 : }
357 0 : this.dispatchEvent(new CustomEvent('doc_reset', { detail: reset }))
358 0 : this.dropDocForNewLineage()
359 0 : this.lineageSeq = update.lineageSeq
360 0 : this.resubscribe()
361 0 : this.dispatchEvent(
362 : new CustomEvent('follower_replaced', { detail: reset })
363 : )
364 0 : return true
365 : }
366 0 : this.lineageSeq ??= update.lineageSeq ?? null
367 0 : return false
368 : }
369 :
370 : private rejectStaleUpdate(update: DocUpdate, isCatchUp: boolean): boolean {
371 0 : if (isCatchUp || this.lastSeq === null || update.seq > this.lastSeq)
372 0 : return false
373 0 : this.dispatchEvent(
374 : new CustomEvent('doc_stale', {
375 : detail: { workflowId: update.workflowId, seq: update.seq }
376 : })
377 : )
378 0 : return true
379 : }
380 :
381 : private recordAppliedSequence(seq: number): void {
382 0 : this.lastSeq = Math.max(this.lastSeq ?? seq, seq)
383 0 : this.attemptFirstSeq ??= seq
384 0 : this.attemptLastSeq = Math.max(this.attemptLastSeq ?? seq, seq)
385 : }
386 :
387 : private rejectSequenceGap(update: DocUpdate): boolean {
388 0 : const baseline =
389 : this.ackSeq === null
390 : ? this.attemptLastSeq
391 : : Math.max(this.attemptLastSeq ?? 0, this.ackSeq)
392 0 : if (baseline === null || update.seq <= baseline + 1) return false
393 0 : this.reportGap(update.workflowId, baseline + 1, update.seq)
394 0 : return true
395 : }
396 :
397 : private rejectPreAckGap(workflowId: string): void {
398 0 : if (
399 : this.ackSeq === null ||
400 : this.attemptFirstSeq === null ||
401 : this.attemptFirstSeq <= this.ackSeq + 1
402 : )
403 0 : return
404 0 : this.reportGap(workflowId, this.ackSeq + 1, this.attemptFirstSeq)
405 : }
406 :
407 : private reportGap(workflowId: string, expected: number, received: number) {
408 0 : this.dispatchEvent(
409 : new CustomEvent('doc_gap', { detail: { workflowId, expected, received } })
410 : )
411 0 : this.resubscribe()
412 : }
413 :
414 : private isReadableUpdate(update: DocUpdate): boolean {
415 0 : try {
416 0 : assertReadableSchema(this.follower.doc)
417 0 : this.schemaError = null
418 0 : return true
419 : } catch (error) {
420 0 : if (!(error instanceof FollowerSchemaError)) throw error
421 0 : this.schemaError = error
422 0 : this.dispatchEvent(
423 : new CustomEvent('schema_error', {
424 : detail: { workflowId: update.workflowId, found: error.found }
425 : })
426 : )
427 0 : return false
428 : }
429 : }
430 :
431 : /**
432 : * Lineage break (`doc_reset`): dispatch while the old doc is still readable,
433 : * then replace it exactly once and pull the new lineage from an empty vector.
434 : * `follower_replaced` lets consumers rebind Yjs observers after replacement.
435 : */
436 : private readonly onDocReset: EventListener = (event) => {
437 0 : if (!(event instanceof CustomEvent)) return
438 0 : const reset = event.detail as DocReset
439 0 : if (reset.workflowId !== this.sentWorkflowId) return
440 0 : this.dispatchEvent(new CustomEvent('doc_reset', { detail: reset }))
441 0 : this.dropDocForNewLineage()
442 0 : this.lineageSeq = reset.lineageSeq
443 0 : this.resubscribe()
444 0 : this.dispatchEvent(new CustomEvent('follower_replaced', { detail: reset }))
445 : }
446 :
447 : private dropDocForNewLineage(): void {
448 0 : this.followerDoc.destroy()
449 0 : this.followerDoc = new FollowerDoc()
450 0 : this.schemaError = null
451 0 : this.lastSeq = null
452 0 : this.attemptFirstSeq = null
453 0 : this.attemptLastSeq = null
454 0 : this.integratedSeq = null
455 0 : this.ackSeq = null
456 0 : this.catchUpPending = false
457 : }
458 :
459 : private readonly onDocSubscribed: EventListener = (event) => {
460 0 : if (!(event instanceof CustomEvent)) return
461 0 : const subscribed = event.detail as DocSubscribed
462 0 : if (subscribed.workflowId !== this.sentWorkflowId) return
463 0 : this.reseedToken =
464 : subscribed.workflowId !== this.reseedBlockedUntilConfirmedWorkflowId &&
465 : !subscribed.ok &&
466 : subscribed.code === STALE_SCHEMA_RESEED_REQUIRED &&
467 : subscribed.expectedSeq
468 : ? {
469 : workflowId: subscribed.workflowId,
470 : expectedSeq: subscribed.expectedSeq
471 : }
472 : : null
473 0 : if (!subscribed.ok) {
474 0 : this.ackSeq = null
475 0 : this.catchUpPending = false
476 0 : this.sentWorkflowId = null
477 0 : this.dispatchEvent(new CustomEvent(event.type, { detail: event.detail }))
478 0 : return
479 : }
480 0 : this.adoptSubscribedLineage(subscribed)
481 0 : this.reseedBlockedUntilConfirmedWorkflowId = null
482 0 : this.ackSeq = subscribed.seq ?? 0
483 0 : this.catchUpPending = this.ackSeq > 0
484 0 : this.dispatchEvent(new CustomEvent(event.type, { detail: event.detail }))
485 0 : this.rejectPreAckGap(subscribed.workflowId)
486 : }
487 :
488 : private adoptSubscribedLineage(subscribed: DocSubscribed): void {
489 0 : const lineageSeq = subscribed.lineageSeq
490 0 : if (
491 : lineageSeq !== undefined &&
492 : this.lineageSeq !== null &&
493 : lineageSeq !== this.lineageSeq
494 : ) {
495 0 : const reset: DocReset = {
496 : workflowId: subscribed.workflowId,
497 : seq: subscribed.seq ?? 0,
498 : lineageSeq
499 : }
500 0 : this.dispatchEvent(new CustomEvent('doc_reset', { detail: reset }))
501 0 : this.dropDocForNewLineage()
502 0 : this.dispatchEvent(
503 : new CustomEvent('follower_replaced', { detail: reset })
504 : )
505 : }
506 0 : this.lineageSeq = lineageSeq ?? this.lineageSeq
507 : }
508 :
509 : private recordIntegratedSequence(seq: number, isCatchUp: boolean): void {
510 0 : if (isCatchUp) {
511 0 : this.catchUpPending = false
512 0 : this.integratedSeq = Math.max(
513 : this.integratedSeq ?? 0,
514 : this.lastSeq ?? seq
515 : )
516 0 : } else if (
517 : (this.integratedSeq !== null && seq === this.integratedSeq + 1) ||
518 : (this.ackSeq === 0 && seq === 1)
519 : ) {
520 0 : this.integratedSeq = seq
521 : }
522 : }
523 :
524 : private readonly onDocReseedResult: EventListener = (event) => {
525 0 : if (!(event instanceof CustomEvent)) return
526 0 : const result = event.detail as DocReseedResult
527 0 : if (result.workflowId !== this.pendingReseedWorkflowId) return
528 0 : this.pendingReseedWorkflowId = null
529 0 : this.dispatchEvent(new CustomEvent(event.type, { detail: result }))
530 0 : if (result.workflowId !== this.desiredWorkflowId) return
531 0 : if (!result.ok && result.code !== RESEED_CONFLICT) return
532 0 : this.reseedBlockedUntilConfirmedWorkflowId = result.workflowId
533 0 : const reset: DocReset = {
534 : workflowId: result.workflowId,
535 : seq: result.seq ?? 0,
536 : lineageSeq: result.seq ?? 0,
537 : actor: 'system:client-seed'
538 : }
539 0 : this.dispatchEvent(new CustomEvent('doc_reset', { detail: reset }))
540 0 : this.dropDocForNewLineage()
541 0 : this.lineageSeq = reset.lineageSeq
542 0 : this.resubscribe()
543 0 : this.dispatchEvent(new CustomEvent('follower_replaced', { detail: reset }))
544 : }
545 :
546 : private readonly forwardFrame: EventListener = (event) => {
547 0 : if (!(event instanceof CustomEvent)) return
548 0 : this.dispatchEvent(new CustomEvent(event.type, { detail: event.detail }))
549 : }
550 : }
|