@lavitre/apps 1.49.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +121 -0
- package/dist/Common/AiChannel.d.ts +59 -0
- package/dist/Common/AiChannel.js +97 -0
- package/dist/Common/AiChannel.js.map +1 -0
- package/dist/Common/BlobStore.d.ts +44 -0
- package/dist/Common/BlobStore.js +186 -0
- package/dist/Common/BlobStore.js.map +1 -0
- package/dist/Common/Common.Model.d.ts +1020 -0
- package/dist/Common/Common.Model.js +21 -0
- package/dist/Common/Common.Model.js.map +1 -0
- package/dist/Common/CrdtChannel.d.ts +198 -0
- package/dist/Common/CrdtChannel.js +659 -0
- package/dist/Common/CrdtChannel.js.map +1 -0
- package/dist/Common/Version.d.ts +21 -0
- package/dist/Common/Version.js +62 -0
- package/dist/Common/Version.js.map +1 -0
- package/dist/Common/index.d.ts +6 -0
- package/dist/Common/index.js +32 -0
- package/dist/Common/index.js.map +1 -0
- package/dist/CompanionConnector/CompanionConnector.Model.d.ts +85 -0
- package/dist/CompanionConnector/CompanionConnector.Model.js +17 -0
- package/dist/CompanionConnector/CompanionConnector.Model.js.map +1 -0
- package/dist/CompanionConnector/CompanionConnector.d.ts +28 -0
- package/dist/CompanionConnector/CompanionConnector.js +385 -0
- package/dist/CompanionConnector/CompanionConnector.js.map +1 -0
- package/dist/CompanionConnector/index.d.ts +2 -0
- package/dist/CompanionConnector/index.js +3 -0
- package/dist/CompanionConnector/index.js.map +1 -0
- package/dist/CompanionFrame/CompanionFrame.d.ts +103 -0
- package/dist/CompanionFrame/CompanionFrame.js +100 -0
- package/dist/CompanionFrame/CompanionFrame.js.map +1 -0
- package/dist/CompanionFrame/index.d.ts +1 -0
- package/dist/CompanionFrame/index.js +2 -0
- package/dist/CompanionFrame/index.js.map +1 -0
- package/dist/Connector/Connector.Model.d.ts +567 -0
- package/dist/Connector/Connector.Model.js +2 -0
- package/dist/Connector/Connector.Model.js.map +1 -0
- package/dist/Connector/Connector.d.ts +227 -0
- package/dist/Connector/Connector.js +1337 -0
- package/dist/Connector/Connector.js.map +1 -0
- package/dist/Connector/index.d.ts +2 -0
- package/dist/Connector/index.js +3 -0
- package/dist/Connector/index.js.map +1 -0
- package/dist/Frame/Frame.Model.d.ts +533 -0
- package/dist/Frame/Frame.Model.js +2 -0
- package/dist/Frame/Frame.Model.js.map +1 -0
- package/dist/Frame/Frame.d.ts +309 -0
- package/dist/Frame/Frame.js +1408 -0
- package/dist/Frame/Frame.js.map +1 -0
- package/dist/Frame/SyncAdapter.d.ts +75 -0
- package/dist/Frame/SyncAdapter.js +134 -0
- package/dist/Frame/SyncAdapter.js.map +1 -0
- package/dist/Frame/index.d.ts +3 -0
- package/dist/Frame/index.js +4 -0
- package/dist/Frame/index.js.map +1 -0
- package/dist/MediaLink/MediaLink.d.ts +178 -0
- package/dist/MediaLink/MediaLink.js +1432 -0
- package/dist/MediaLink/MediaLink.js.map +1 -0
- package/dist/MediaLink/index.d.ts +1 -0
- package/dist/MediaLink/index.js +2 -0
- package/dist/MediaLink/index.js.map +1 -0
- package/dist/Native/index.d.ts +170 -0
- package/dist/Native/index.js +19 -0
- package/dist/Native/index.js.map +1 -0
- package/dist/Version.d.ts +1 -0
- package/dist/Version.js +2 -0
- package/dist/Version.js.map +1 -0
- package/package.json +76 -0
|
@@ -0,0 +1,659 @@
|
|
|
1
|
+
import * as Y from 'yjs';
|
|
2
|
+
import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate, } from 'y-protocols/awareness';
|
|
3
|
+
// The host-side decoder for the four `crdt*` messages ships in la Vitre
|
|
4
|
+
// 26.5.1. Pre-26.5.1 hosts reject any unknown message type and fail the
|
|
5
|
+
// WHOLE message parse (not just the unknown frame), which would break ALL
|
|
6
|
+
// app messaging — not merely CRDT. Connector and Frame both gate emission
|
|
7
|
+
// on `isMinVersion(hostInformation.version, MIN_CRDT_HOST_VERSION)`; a
|
|
8
|
+
// single shared constant keeps the two connectors from drifting.
|
|
9
|
+
export const MIN_CRDT_HOST_VERSION = '26.5.1';
|
|
10
|
+
// Sentinel origin tag — both directions use it so the outbound listeners
|
|
11
|
+
// don't echo back what they just applied.
|
|
12
|
+
const ORIGIN_REMOTE = 'lavitre:crdt:remote';
|
|
13
|
+
// When an applied update references structs we never received (a causal
|
|
14
|
+
// hole), Yjs parks it in `store.pendingStructs` — invisible, unrendered, and
|
|
15
|
+
// on a broadcast passe-plat with no per-peer retransmit, never refilled on its
|
|
16
|
+
// own. We recover by re-advertising our state vector after this debounce,
|
|
17
|
+
// coalescing a burst of holey updates into a single SyncStep1.
|
|
18
|
+
const PENDING_RECOVERY_DEBOUNCE_MS = 250;
|
|
19
|
+
// Periodic safety-net reconcile. The sync protocol assumes a lossless ordered
|
|
20
|
+
// channel; the broadcast passe-plat can still silently drop (a peer dropped
|
|
21
|
+
// mid-ramp-up, a back-pressure eviction), and a LOST TAIL leaves no
|
|
22
|
+
// `pendingStructs` for the reactive recovery to notice. Re-advertising our
|
|
23
|
+
// state vector on this interval makes convergence eventual no matter which
|
|
24
|
+
// events fired — the role a provider's `resyncInterval` plays.
|
|
25
|
+
const RESYNC_INTERVAL_MS = 20000;
|
|
26
|
+
/**
|
|
27
|
+
* Yjs sync + awareness channel piped over the la Vitre app transport.
|
|
28
|
+
*
|
|
29
|
+
* By default exposes a `doc` and `awareness` already wired to the host —
|
|
30
|
+
* simple apps just use them. Libraries that bring their own `Y.Doc` /
|
|
31
|
+
* `Awareness` (Carbone, etc.) call `attach(doc, awareness)` to swap them in.
|
|
32
|
+
*
|
|
33
|
+
* Sync messages and awareness messages travel on separate envelope types
|
|
34
|
+
* (`crdtUpdate` vs `crdtAwarenessUpdate`), so the F# host can route, throttle
|
|
35
|
+
* and log them independently.
|
|
36
|
+
*/
|
|
37
|
+
export class CrdtChannel {
|
|
38
|
+
constructor(postMessage) {
|
|
39
|
+
Object.defineProperty(this, "postMessage", {
|
|
40
|
+
enumerable: true,
|
|
41
|
+
configurable: true,
|
|
42
|
+
writable: true,
|
|
43
|
+
value: postMessage
|
|
44
|
+
});
|
|
45
|
+
Object.defineProperty(this, "_defaultDoc", {
|
|
46
|
+
enumerable: true,
|
|
47
|
+
configurable: true,
|
|
48
|
+
writable: true,
|
|
49
|
+
value: new Y.Doc()
|
|
50
|
+
});
|
|
51
|
+
Object.defineProperty(this, "_defaultAwareness", {
|
|
52
|
+
enumerable: true,
|
|
53
|
+
configurable: true,
|
|
54
|
+
writable: true,
|
|
55
|
+
value: void 0
|
|
56
|
+
});
|
|
57
|
+
Object.defineProperty(this, "_doc", {
|
|
58
|
+
enumerable: true,
|
|
59
|
+
configurable: true,
|
|
60
|
+
writable: true,
|
|
61
|
+
value: void 0
|
|
62
|
+
});
|
|
63
|
+
Object.defineProperty(this, "_awareness", {
|
|
64
|
+
enumerable: true,
|
|
65
|
+
configurable: true,
|
|
66
|
+
writable: true,
|
|
67
|
+
value: void 0
|
|
68
|
+
});
|
|
69
|
+
Object.defineProperty(this, "_docUpdateHandler", {
|
|
70
|
+
enumerable: true,
|
|
71
|
+
configurable: true,
|
|
72
|
+
writable: true,
|
|
73
|
+
value: null
|
|
74
|
+
});
|
|
75
|
+
Object.defineProperty(this, "_awarenessUpdateHandler", {
|
|
76
|
+
enumerable: true,
|
|
77
|
+
configurable: true,
|
|
78
|
+
writable: true,
|
|
79
|
+
value: null
|
|
80
|
+
});
|
|
81
|
+
Object.defineProperty(this, "_onSyncedListeners", {
|
|
82
|
+
enumerable: true,
|
|
83
|
+
configurable: true,
|
|
84
|
+
writable: true,
|
|
85
|
+
value: new Set()
|
|
86
|
+
});
|
|
87
|
+
// `onSynced` fires once per attach cycle (initial handshake + each
|
|
88
|
+
// re-attach), per its documented contract — NOT on every inbound
|
|
89
|
+
// `crdtSyncComplete`. The periodic reconcile (and any pre-`silent` host)
|
|
90
|
+
// re-send `crdtSyncComplete`; this flag swallows the duplicates so a
|
|
91
|
+
// maintenance resync never re-signals "synced". Reset in `attach()`.
|
|
92
|
+
Object.defineProperty(this, "_syncedFired", {
|
|
93
|
+
enumerable: true,
|
|
94
|
+
configurable: true,
|
|
95
|
+
writable: true,
|
|
96
|
+
value: false
|
|
97
|
+
});
|
|
98
|
+
Object.defineProperty(this, "_onUpdateListeners", {
|
|
99
|
+
enumerable: true,
|
|
100
|
+
configurable: true,
|
|
101
|
+
writable: true,
|
|
102
|
+
value: new Set()
|
|
103
|
+
});
|
|
104
|
+
// Subdoc transport state. Keyed by `subdoc.guid`. Each entry holds the
|
|
105
|
+
// subdoc + its bound update handler so we can detach symmetrically. The
|
|
106
|
+
// SDK is content-blind here: it moves a subdoc's bytes, it does not know
|
|
107
|
+
// (or care) that Carbone uses subdocs for deferred asset blobs.
|
|
108
|
+
Object.defineProperty(this, "_subdocs", {
|
|
109
|
+
enumerable: true,
|
|
110
|
+
configurable: true,
|
|
111
|
+
writable: true,
|
|
112
|
+
value: new Map()
|
|
113
|
+
});
|
|
114
|
+
// Cumulative inbound bytes per subdoc guid — feeds the generic progress
|
|
115
|
+
// signal (a multi-MB blob streaming in wants a loading bar; that's true
|
|
116
|
+
// for any app with heavy media, not just Carbone).
|
|
117
|
+
Object.defineProperty(this, "_subdocBytes", {
|
|
118
|
+
enumerable: true,
|
|
119
|
+
configurable: true,
|
|
120
|
+
writable: true,
|
|
121
|
+
value: new Map()
|
|
122
|
+
});
|
|
123
|
+
Object.defineProperty(this, "_onSubdocBytesListeners", {
|
|
124
|
+
enumerable: true,
|
|
125
|
+
configurable: true,
|
|
126
|
+
writable: true,
|
|
127
|
+
value: new Set()
|
|
128
|
+
});
|
|
129
|
+
// Determinate transfer-progress listeners — fed by host `crdtSubdoc
|
|
130
|
+
// TransferProgress` messages, fired while fragments are still reassembling
|
|
131
|
+
// (before apply). Separate from `_onSubdocBytesListeners` (post-apply).
|
|
132
|
+
Object.defineProperty(this, "_onSubdocTransferProgressListeners", {
|
|
133
|
+
enumerable: true,
|
|
134
|
+
configurable: true,
|
|
135
|
+
writable: true,
|
|
136
|
+
value: new Set()
|
|
137
|
+
});
|
|
138
|
+
Object.defineProperty(this, "_onSubdocSyncedListeners", {
|
|
139
|
+
enumerable: true,
|
|
140
|
+
configurable: true,
|
|
141
|
+
writable: true,
|
|
142
|
+
value: new Map()
|
|
143
|
+
});
|
|
144
|
+
// A handshake is queued for the next microtask. Set whenever we schedule
|
|
145
|
+
// one, cleared when it fires. `attach()` consults this to avoid emitting
|
|
146
|
+
// a second handshake when a caller does `new CrdtChannel()` immediately
|
|
147
|
+
// followed by `attach()` in the same task — both microtasks would
|
|
148
|
+
// otherwise observe the same `_doc` and fire two `crdtRequestSync` (and
|
|
149
|
+
// two `crdtRequestAwareness`), producing duplicate `crdtSyncComplete`
|
|
150
|
+
// events and double-invoking `onSynced` listeners.
|
|
151
|
+
Object.defineProperty(this, "_handshakeScheduled", {
|
|
152
|
+
enumerable: true,
|
|
153
|
+
configurable: true,
|
|
154
|
+
writable: true,
|
|
155
|
+
value: false
|
|
156
|
+
});
|
|
157
|
+
// Tear-down flag. `destroy()` sets it; subsequent `dispose()` calls from
|
|
158
|
+
// outstanding attach handles become no-ops so we don't `_bind()` against
|
|
159
|
+
// a destroyed default doc.
|
|
160
|
+
Object.defineProperty(this, "_destroyed", {
|
|
161
|
+
enumerable: true,
|
|
162
|
+
configurable: true,
|
|
163
|
+
writable: true,
|
|
164
|
+
value: false
|
|
165
|
+
});
|
|
166
|
+
// A pending-structs recovery re-sync is queued. Set when we detect a causal
|
|
167
|
+
// hole after applying an update, cleared when the debounced re-advertise
|
|
168
|
+
// fires. Coalesces a burst of holey updates into one SyncStep1 (see
|
|
169
|
+
// `_recoverIfPending`).
|
|
170
|
+
Object.defineProperty(this, "_recoverScheduled", {
|
|
171
|
+
enumerable: true,
|
|
172
|
+
configurable: true,
|
|
173
|
+
writable: true,
|
|
174
|
+
value: false
|
|
175
|
+
});
|
|
176
|
+
// Periodic reconcile timer (RESYNC_INTERVAL_MS). Browser `setInterval`
|
|
177
|
+
// returns a number; Node returns a Timeout we `unref()` so this maintenance
|
|
178
|
+
// timer never keeps a test process alive.
|
|
179
|
+
Object.defineProperty(this, "_resyncTimer", {
|
|
180
|
+
enumerable: true,
|
|
181
|
+
configurable: true,
|
|
182
|
+
writable: true,
|
|
183
|
+
value: null
|
|
184
|
+
});
|
|
185
|
+
// Subdoc guids with a debounced full re-pull in flight — the subdoc
|
|
186
|
+
// analogue of `_recoverScheduled` (causal-hole recovery per guid).
|
|
187
|
+
Object.defineProperty(this, "_subdocsRecovering", {
|
|
188
|
+
enumerable: true,
|
|
189
|
+
configurable: true,
|
|
190
|
+
writable: true,
|
|
191
|
+
value: new Set()
|
|
192
|
+
});
|
|
193
|
+
this._defaultAwareness = new Awareness(this._defaultDoc);
|
|
194
|
+
this._doc = this._defaultDoc;
|
|
195
|
+
this._awareness = this._defaultAwareness;
|
|
196
|
+
this._bind();
|
|
197
|
+
// Defer the initial handshake to a microtask so callers (Connector /
|
|
198
|
+
// Frame, or any user holding a freshly-constructed channel) have a frame
|
|
199
|
+
// to subscribe via `onSynced` / `onUpdate` before `crdtSyncComplete`
|
|
200
|
+
// arrives — synchronous-transport tests would otherwise miss the event.
|
|
201
|
+
this._scheduleHandshake();
|
|
202
|
+
this._resyncTimer = setInterval(() => this._periodicReconcile(), RESYNC_INTERVAL_MS);
|
|
203
|
+
const timer = this._resyncTimer;
|
|
204
|
+
if (timer && typeof timer.unref === 'function') {
|
|
205
|
+
;
|
|
206
|
+
timer.unref();
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
get doc() {
|
|
210
|
+
return this._doc;
|
|
211
|
+
}
|
|
212
|
+
get awareness() {
|
|
213
|
+
return this._awareness;
|
|
214
|
+
}
|
|
215
|
+
/** Stable numeric identifier for this peer in the Yjs awareness protocol. */
|
|
216
|
+
get clientId() {
|
|
217
|
+
return this._awareness.clientID;
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* Swap the default `Y.Doc` / `Awareness` for caller-provided ones. The
|
|
221
|
+
* default ones remain alive but stop syncing. Call `dispose()` on the
|
|
222
|
+
* returned handle to revert.
|
|
223
|
+
*
|
|
224
|
+
* Typical use: a library like Carbone instantiates its own Y.Doc internally
|
|
225
|
+
* and exposes a `SyncAdapter` API that takes `(doc, awareness)`. The host
|
|
226
|
+
* app forwards them straight to `attach()`.
|
|
227
|
+
*/
|
|
228
|
+
attach(doc, awareness) {
|
|
229
|
+
const realAwareness = awareness ?? new Awareness(doc);
|
|
230
|
+
this._unbind();
|
|
231
|
+
// Carry over any state the SDK already buffered into the new doc.
|
|
232
|
+
// Between channel construction and attach() the initial handshake
|
|
233
|
+
// can deliver peer state that lands in `_defaultDoc`; without this
|
|
234
|
+
// transfer the user's freshly-attached doc would observe an empty
|
|
235
|
+
// store until the post-attach handshake round-trips back. Applying
|
|
236
|
+
// with the remote sentinel keeps the SDK from re-broadcasting it.
|
|
237
|
+
if (doc !== this._defaultDoc) {
|
|
238
|
+
const buffered = Y.encodeStateAsUpdate(this._defaultDoc);
|
|
239
|
+
Y.applyUpdate(doc, buffered, ORIGIN_REMOTE);
|
|
240
|
+
}
|
|
241
|
+
this._doc = doc;
|
|
242
|
+
this._awareness = realAwareness;
|
|
243
|
+
this._bind();
|
|
244
|
+
// Same microtask deferral as the constructor — a caller that calls
|
|
245
|
+
// attach() then immediately subscribes to onSynced needs the handshake
|
|
246
|
+
// to ship after their subscription lands. If the constructor already
|
|
247
|
+
// queued a handshake that hasn't fired yet, `_scheduleHandshake()`
|
|
248
|
+
// skips ours: the pending one will pick up the now-attached doc.
|
|
249
|
+
this._syncedFired = false;
|
|
250
|
+
this._scheduleHandshake();
|
|
251
|
+
return {
|
|
252
|
+
dispose: () => {
|
|
253
|
+
// No-op if the channel has been destroyed or another attach() has
|
|
254
|
+
// swapped the active doc/awareness — this handle is stale and
|
|
255
|
+
// reverting would either bind against a destroyed doc or blow away
|
|
256
|
+
// a newer attachment.
|
|
257
|
+
if (this._destroyed)
|
|
258
|
+
return;
|
|
259
|
+
if (this._doc !== doc || this._awareness !== realAwareness)
|
|
260
|
+
return;
|
|
261
|
+
this._unbind();
|
|
262
|
+
this._doc = this._defaultDoc;
|
|
263
|
+
this._awareness = this._defaultAwareness;
|
|
264
|
+
this._bind();
|
|
265
|
+
},
|
|
266
|
+
};
|
|
267
|
+
}
|
|
268
|
+
/** Subscribe to every sync-complete event — fires once after the initial
|
|
269
|
+
* handshake AND again after each subsequent `attach()` re-handshake.
|
|
270
|
+
* Returns an unsubscribe function. (The listener is NOT auto-removed
|
|
271
|
+
* after the first call.) */
|
|
272
|
+
onSynced(cb) {
|
|
273
|
+
this._onSyncedListeners.add(cb);
|
|
274
|
+
return () => {
|
|
275
|
+
this._onSyncedListeners.delete(cb);
|
|
276
|
+
};
|
|
277
|
+
}
|
|
278
|
+
/** Subscribe to every Yjs doc update — local or remote. */
|
|
279
|
+
onUpdate(cb) {
|
|
280
|
+
this._onUpdateListeners.add(cb);
|
|
281
|
+
return () => {
|
|
282
|
+
this._onUpdateListeners.delete(cb);
|
|
283
|
+
};
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* Connect a yjs SUBDOCUMENT to this transport on its own channel, keyed
|
|
287
|
+
* by `subdoc.guid`. Returns a disposer.
|
|
288
|
+
*
|
|
289
|
+
* Re-attaching the SAME `Y.Doc` instance is a no-op (returns a disposer
|
|
290
|
+
* for it). Re-attaching a DIFFERENT instance under the same guid replaces
|
|
291
|
+
* the entry (off the old handler, on the new) — last attach wins, so a
|
|
292
|
+
* stale disposer never tears down a live doc's handler.
|
|
293
|
+
*
|
|
294
|
+
* `opts.requestSync` (default true) emits the on-demand pull request. The
|
|
295
|
+
* writer of a subdoc (e.g. `BlobStore.put`) already holds the
|
|
296
|
+
* authoritative state and can pass `false` to skip a wasted round-trip.
|
|
297
|
+
*
|
|
298
|
+
* Low-level primitive — the caller drives WHEN to attach and WHAT the
|
|
299
|
+
* subdoc contains. `frame.blobs` is the convenience built on top.
|
|
300
|
+
*/
|
|
301
|
+
attachSubdoc(subdoc, opts) {
|
|
302
|
+
const guid = subdoc.guid;
|
|
303
|
+
if (this._destroyed)
|
|
304
|
+
return () => { };
|
|
305
|
+
const existing = this._subdocs.get(guid);
|
|
306
|
+
if (existing) {
|
|
307
|
+
if (existing.doc === subdoc)
|
|
308
|
+
return () => this.detachSubdoc(guid);
|
|
309
|
+
// Same guid, different Y.Doc instance: swap handlers, last wins.
|
|
310
|
+
existing.doc.off('update', existing.handler);
|
|
311
|
+
}
|
|
312
|
+
const handler = (update, origin) => {
|
|
313
|
+
if (origin === ORIGIN_REMOTE)
|
|
314
|
+
return;
|
|
315
|
+
const buf = this._exactFitBuffer(update);
|
|
316
|
+
this.postMessage({ type: 'crdtSubdocUpdate', guid, update: buf }, [buf]);
|
|
317
|
+
};
|
|
318
|
+
subdoc.on('update', handler);
|
|
319
|
+
this._subdocs.set(guid, { doc: subdoc, handler });
|
|
320
|
+
if (opts?.requestSync !== false) {
|
|
321
|
+
this.postMessage({ type: 'crdtSubdocRequestSync', guid });
|
|
322
|
+
}
|
|
323
|
+
return () => this.detachSubdoc(guid);
|
|
324
|
+
}
|
|
325
|
+
/** Subscribe to cumulative inbound bytes for a subdoc (progress bar).
|
|
326
|
+
* Fires `(guid, totalReceivedBytes)` on every inbound subdoc update. */
|
|
327
|
+
onSubdocBytes(cb) {
|
|
328
|
+
this._onSubdocBytesListeners.add(cb);
|
|
329
|
+
return () => {
|
|
330
|
+
this._onSubdocBytesListeners.delete(cb);
|
|
331
|
+
};
|
|
332
|
+
}
|
|
333
|
+
/** Subscribe to determinate transfer progress for a subdoc whose full state
|
|
334
|
+
* is streaming in (the host reassembles WebRTC fragments and reports bytes
|
|
335
|
+
* as they land). Fires `(guid, receivedBytes, totalBytes)` repeatedly
|
|
336
|
+
* DURING the transfer, BEFORE the update is applied — unlike `onSubdocBytes`
|
|
337
|
+
* which fires once, after apply, for an atomic subdoc that arrives as a
|
|
338
|
+
* single message. `receivedBytes` is monotonic (high-water on the host) and
|
|
339
|
+
* reaches `totalBytes` (the eventual update size, in the same units) on
|
|
340
|
+
* completion → a determinate progress bar. Returns an unsubscribe function.
|
|
341
|
+
*
|
|
342
|
+
* Requires a host that emits `crdtSubdocTransferProgress`; against an older
|
|
343
|
+
* host the callback simply never fires (fall back to an indeterminate
|
|
344
|
+
* spinner gated on `onSubdocSynced`). */
|
|
345
|
+
onSubdocTransferProgress(cb) {
|
|
346
|
+
this._onSubdocTransferProgressListeners.add(cb);
|
|
347
|
+
return () => {
|
|
348
|
+
this._onSubdocTransferProgressListeners.delete(cb);
|
|
349
|
+
};
|
|
350
|
+
}
|
|
351
|
+
/** One-shot-per-handshake: fires when the host reports this subdoc's
|
|
352
|
+
* initial sync is complete. */
|
|
353
|
+
onSubdocSynced(guid, cb) {
|
|
354
|
+
let set = this._onSubdocSyncedListeners.get(guid);
|
|
355
|
+
if (!set) {
|
|
356
|
+
set = new Set();
|
|
357
|
+
this._onSubdocSyncedListeners.set(guid, set);
|
|
358
|
+
}
|
|
359
|
+
set.add(cb);
|
|
360
|
+
return () => {
|
|
361
|
+
this._onSubdocSyncedListeners.get(guid)?.delete(cb);
|
|
362
|
+
};
|
|
363
|
+
}
|
|
364
|
+
/** Stop transporting a subdoc by guid (symmetric to the disposer returned
|
|
365
|
+
* by `attachSubdoc`). Safe to call for an unknown guid.
|
|
366
|
+
*
|
|
367
|
+
* Pending `onSubdocSynced` waiters are FLUSHED (invoked) before the
|
|
368
|
+
* listener set is dropped — otherwise a `BlobStore.get()` awaiting this
|
|
369
|
+
* subdoc would hang forever when the blob is removed mid-flight. The
|
|
370
|
+
* woken callback re-reads and resolves (to null for a gone subdoc). */
|
|
371
|
+
detachSubdoc(guid) {
|
|
372
|
+
const e = this._subdocs.get(guid);
|
|
373
|
+
if (!e)
|
|
374
|
+
return;
|
|
375
|
+
e.doc.off('update', e.handler);
|
|
376
|
+
this._subdocs.delete(guid);
|
|
377
|
+
this._subdocBytes.delete(guid);
|
|
378
|
+
const waiters = this._onSubdocSyncedListeners.get(guid);
|
|
379
|
+
this._onSubdocSyncedListeners.delete(guid);
|
|
380
|
+
if (waiters)
|
|
381
|
+
for (const cb of [...waiters])
|
|
382
|
+
cb();
|
|
383
|
+
}
|
|
384
|
+
/** Internal — dispatched by Connector / Frame on every crdt* message. */
|
|
385
|
+
handleMessage(msg) {
|
|
386
|
+
switch (msg.type) {
|
|
387
|
+
case 'crdtUpdate': {
|
|
388
|
+
if (!msg.update)
|
|
389
|
+
return;
|
|
390
|
+
const bytes = new Uint8Array(msg.update);
|
|
391
|
+
Y.applyUpdate(this._doc, bytes, ORIGIN_REMOTE);
|
|
392
|
+
// Snapshot the listener set before iterating: a callback may
|
|
393
|
+
// unsubscribe (or add a new one) and live-Set mutation during
|
|
394
|
+
// iteration is a sharp edge we don't want callers to step on.
|
|
395
|
+
for (const cb of [...this._onUpdateListeners])
|
|
396
|
+
cb(bytes);
|
|
397
|
+
// The update may depend on structs we never received (causal hole) —
|
|
398
|
+
// recover by re-advertising our state vector. No-op when integrated
|
|
399
|
+
// cleanly, which is the overwhelmingly common case.
|
|
400
|
+
this._recoverIfPending();
|
|
401
|
+
break;
|
|
402
|
+
}
|
|
403
|
+
case 'crdtSyncComplete':
|
|
404
|
+
// Once per attach cycle (see `_syncedFired`): the periodic reconcile
|
|
405
|
+
// and pre-`silent` hosts re-send this; don't re-fire `onSynced`.
|
|
406
|
+
if (this._syncedFired)
|
|
407
|
+
break;
|
|
408
|
+
this._syncedFired = true;
|
|
409
|
+
for (const cb of [...this._onSyncedListeners])
|
|
410
|
+
cb();
|
|
411
|
+
break;
|
|
412
|
+
case 'crdtAwarenessUpdate': {
|
|
413
|
+
if (!msg.update)
|
|
414
|
+
return;
|
|
415
|
+
const bytes = new Uint8Array(msg.update);
|
|
416
|
+
applyAwarenessUpdate(this._awareness, bytes, ORIGIN_REMOTE);
|
|
417
|
+
break;
|
|
418
|
+
}
|
|
419
|
+
case 'crdtSubdocUpdate': {
|
|
420
|
+
if (!msg.update)
|
|
421
|
+
return;
|
|
422
|
+
const entry = this._subdocs.get(msg.guid);
|
|
423
|
+
if (!entry)
|
|
424
|
+
return; // subdoc not attached (yet) — drop, peer will resync
|
|
425
|
+
const bytes = new Uint8Array(msg.update);
|
|
426
|
+
Y.applyUpdate(entry.doc, bytes, ORIGIN_REMOTE);
|
|
427
|
+
const total = (this._subdocBytes.get(msg.guid) ?? 0) + bytes.byteLength;
|
|
428
|
+
this._subdocBytes.set(msg.guid, total);
|
|
429
|
+
for (const cb of [...this._onSubdocBytesListeners])
|
|
430
|
+
cb(msg.guid, total);
|
|
431
|
+
// A subdoc chunk can land on a causal hole too (an earlier chunk
|
|
432
|
+
// dropped) — re-pull the whole subdoc so the hole closes.
|
|
433
|
+
this._recoverSubdocIfPending(msg.guid);
|
|
434
|
+
break;
|
|
435
|
+
}
|
|
436
|
+
case 'crdtSubdocSyncComplete': {
|
|
437
|
+
const set = this._onSubdocSyncedListeners.get(msg.guid);
|
|
438
|
+
if (set)
|
|
439
|
+
for (const cb of [...set])
|
|
440
|
+
cb();
|
|
441
|
+
break;
|
|
442
|
+
}
|
|
443
|
+
case 'crdtSubdocTransferProgress': {
|
|
444
|
+
// Pure notification — no apply, no doc mutation. Snapshot the set so a
|
|
445
|
+
// callback that unsubscribes mid-iteration doesn't trip the loop.
|
|
446
|
+
for (const cb of [...this._onSubdocTransferProgressListeners])
|
|
447
|
+
cb(msg.guid, msg.receivedBytes, msg.totalBytes);
|
|
448
|
+
break;
|
|
449
|
+
}
|
|
450
|
+
case 'crdtRequestSync': {
|
|
451
|
+
// SyncStep2: a peer attached and wants our main doc state. If it
|
|
452
|
+
// advertised a state vector, answer with ONLY the diff it is missing
|
|
453
|
+
// (`encodeStateAsUpdate(doc, theirSV)`); otherwise ship the full
|
|
454
|
+
// snapshot (legacy peer / a host that stripped the field). The host
|
|
455
|
+
// no longer shadows main docs, so each current holder answering is
|
|
456
|
+
// the only way bytes converge at late-join. Multiple/duplicate
|
|
457
|
+
// responses are fine — Yjs merges idempotently. We deliberately do
|
|
458
|
+
// NOT re-advertise our own SV here: both sides emit SyncStep1
|
|
459
|
+
// independently on handshake, so a diff reply cannot start a loop.
|
|
460
|
+
const remoteSv = msg.stateVector && msg.stateVector.byteLength > 0
|
|
461
|
+
? new Uint8Array(msg.stateVector)
|
|
462
|
+
: undefined;
|
|
463
|
+
const diff = Y.encodeStateAsUpdate(this._doc, remoteSv);
|
|
464
|
+
const buf = this._exactFitBuffer(diff);
|
|
465
|
+
this.postMessage({ type: 'crdtUpdate', update: buf }, [buf]);
|
|
466
|
+
break;
|
|
467
|
+
}
|
|
468
|
+
case 'crdtResync': {
|
|
469
|
+
// The host saw a new peer connect and asks us to re-advertise. Re-emit
|
|
470
|
+
// our SyncStep1 so the newcomer's holder set includes us. The leaf has
|
|
471
|
+
// no peer-connect event of its own, which is why the host drives this.
|
|
472
|
+
this._emitInitialHandshake();
|
|
473
|
+
break;
|
|
474
|
+
}
|
|
475
|
+
case 'crdtSubdocRequestSync': {
|
|
476
|
+
// A peer wants this subdoc. If we have it attached, answer with its
|
|
477
|
+
// full state as a normal subdoc update; the host fans it back.
|
|
478
|
+
const entry = this._subdocs.get(msg.guid);
|
|
479
|
+
if (!entry)
|
|
480
|
+
return;
|
|
481
|
+
const full = Y.encodeStateAsUpdate(entry.doc);
|
|
482
|
+
const buf = this._exactFitBuffer(full);
|
|
483
|
+
this.postMessage({ type: 'crdtSubdocUpdate', guid: msg.guid, update: buf }, [buf]);
|
|
484
|
+
break;
|
|
485
|
+
}
|
|
486
|
+
}
|
|
487
|
+
}
|
|
488
|
+
destroy() {
|
|
489
|
+
if (this._destroyed)
|
|
490
|
+
return;
|
|
491
|
+
this._destroyed = true;
|
|
492
|
+
if (this._resyncTimer !== null) {
|
|
493
|
+
clearInterval(this._resyncTimer);
|
|
494
|
+
this._resyncTimer = null;
|
|
495
|
+
}
|
|
496
|
+
this._subdocsRecovering.clear();
|
|
497
|
+
this._unbind();
|
|
498
|
+
for (const guid of [...this._subdocs.keys()])
|
|
499
|
+
this.detachSubdoc(guid);
|
|
500
|
+
this._onSubdocBytesListeners.clear();
|
|
501
|
+
this._onSubdocTransferProgressListeners.clear();
|
|
502
|
+
this._onSubdocSyncedListeners.clear();
|
|
503
|
+
this._subdocBytes.clear();
|
|
504
|
+
this._defaultAwareness.destroy();
|
|
505
|
+
this._defaultDoc.destroy();
|
|
506
|
+
this._onSyncedListeners.clear();
|
|
507
|
+
this._onUpdateListeners.clear();
|
|
508
|
+
}
|
|
509
|
+
_scheduleHandshake() {
|
|
510
|
+
if (this._handshakeScheduled || this._destroyed)
|
|
511
|
+
return;
|
|
512
|
+
this._handshakeScheduled = true;
|
|
513
|
+
queueMicrotask(() => {
|
|
514
|
+
this._handshakeScheduled = false;
|
|
515
|
+
if (this._destroyed)
|
|
516
|
+
return;
|
|
517
|
+
this._emitInitialHandshake();
|
|
518
|
+
});
|
|
519
|
+
}
|
|
520
|
+
_emitInitialHandshake() {
|
|
521
|
+
// SyncStep1: advertise our current state vector so a holder answers with a
|
|
522
|
+
// minimal diff. Host replies with that diff via `crdtUpdate` then
|
|
523
|
+
// `crdtSyncComplete`, and with remote peers' awareness via
|
|
524
|
+
// `crdtAwarenessUpdate`. The SV is small (no doc content) — sent by copy,
|
|
525
|
+
// not transfer. An empty default doc encodes an empty SV ⇒ the holder
|
|
526
|
+
// replies its full state, exactly today's behaviour.
|
|
527
|
+
const sv = Y.encodeStateVector(this._doc);
|
|
528
|
+
this.postMessage({
|
|
529
|
+
type: 'crdtRequestSync',
|
|
530
|
+
stateVector: this._exactFitBuffer(sv),
|
|
531
|
+
});
|
|
532
|
+
this.postMessage({ type: 'crdtRequestAwareness' });
|
|
533
|
+
}
|
|
534
|
+
/** After applying a remote update the doc may hold structs that depend on
|
|
535
|
+
* state we never received — a CAUSAL HOLE. Yjs parks them in
|
|
536
|
+
* `store.pendingStructs`: invisible, unrendered, and on a broadcast
|
|
537
|
+
* passe-plat (no per-peer retransmit) never refilled on their own. Holes
|
|
538
|
+
* form when an earlier update was dropped during connection ramp-up, or
|
|
539
|
+
* when the sender created local structs under a suppressed origin (e.g.
|
|
540
|
+
* derived writes made while applying a remote update, which the anti-loop
|
|
541
|
+
* guard then skips) — both leave a gap in a client's clock sequence.
|
|
542
|
+
* Re-advertise our state vector (SyncStep1); a holder answers with exactly
|
|
543
|
+
* the diff we're missing and the hole closes — the same round-trip as the
|
|
544
|
+
* initial handshake. Debounced so a burst of holey updates triggers one
|
|
545
|
+
* re-sync, and we re-check `pendingStructs` after the delay so a hole that
|
|
546
|
+
* closed on its own (a reordered tail arriving) costs nothing. */
|
|
547
|
+
_recoverIfPending() {
|
|
548
|
+
if (this._destroyed || this._recoverScheduled)
|
|
549
|
+
return;
|
|
550
|
+
if (!this._doc.store.pendingStructs)
|
|
551
|
+
return;
|
|
552
|
+
this._recoverScheduled = true;
|
|
553
|
+
setTimeout(() => {
|
|
554
|
+
this._recoverScheduled = false;
|
|
555
|
+
if (this._destroyed || !this._doc.store.pendingStructs)
|
|
556
|
+
return;
|
|
557
|
+
const sv = Y.encodeStateVector(this._doc);
|
|
558
|
+
this.postMessage({
|
|
559
|
+
type: 'crdtRequestSync',
|
|
560
|
+
stateVector: this._exactFitBuffer(sv),
|
|
561
|
+
silent: true,
|
|
562
|
+
});
|
|
563
|
+
}, PENDING_RECOVERY_DEBOUNCE_MS);
|
|
564
|
+
}
|
|
565
|
+
/** Periodic safety-net reconcile (RESYNC_INTERVAL_MS). Re-advertise our main
|
|
566
|
+
* state vector unconditionally — this is the ONLY thing that catches silent
|
|
567
|
+
* divergence the event path misses (a lost tail with no `pendingStructs`, a
|
|
568
|
+
* back-pressure eviction, a botched reconnect): the holder replies with a
|
|
569
|
+
* diff, normally empty. `silent` keeps it off the `onSynced` path. Subdocs
|
|
570
|
+
* are re-pulled only when they actually hold a hole (a full subdoc fetch is
|
|
571
|
+
* expensive, so we don't poll them blindly). */
|
|
572
|
+
_periodicReconcile() {
|
|
573
|
+
if (this._destroyed || this._doc === this._defaultDoc)
|
|
574
|
+
return;
|
|
575
|
+
const sv = Y.encodeStateVector(this._doc);
|
|
576
|
+
this.postMessage({
|
|
577
|
+
type: 'crdtRequestSync',
|
|
578
|
+
stateVector: this._exactFitBuffer(sv),
|
|
579
|
+
silent: true,
|
|
580
|
+
});
|
|
581
|
+
for (const [guid, entry] of this._subdocs) {
|
|
582
|
+
if (entry.doc.store.pendingStructs)
|
|
583
|
+
this._recoverSubdocIfPending(guid);
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
/** Subdoc analogue of `_recoverIfPending`: a subdoc update can land on a
|
|
587
|
+
* causal hole (a missing earlier chunk) just like the main doc. Debounced
|
|
588
|
+
* per guid; re-requests the subdoc's full state (subdocs carry no SV diff
|
|
589
|
+
* on the wire — `crdtSubdocRequestSync` answers with the whole thing). */
|
|
590
|
+
_recoverSubdocIfPending(guid) {
|
|
591
|
+
if (this._destroyed || this._subdocsRecovering.has(guid))
|
|
592
|
+
return;
|
|
593
|
+
const entry = this._subdocs.get(guid);
|
|
594
|
+
if (!entry || !entry.doc.store.pendingStructs)
|
|
595
|
+
return;
|
|
596
|
+
this._subdocsRecovering.add(guid);
|
|
597
|
+
setTimeout(() => {
|
|
598
|
+
this._subdocsRecovering.delete(guid);
|
|
599
|
+
const e = this._subdocs.get(guid);
|
|
600
|
+
if (this._destroyed || !e || !e.doc.store.pendingStructs)
|
|
601
|
+
return;
|
|
602
|
+
this.postMessage({ type: 'crdtSubdocRequestSync', guid });
|
|
603
|
+
}, PENDING_RECOVERY_DEBOUNCE_MS);
|
|
604
|
+
}
|
|
605
|
+
/** Yjs' `'update'` event currently emits tight Uint8Arrays — but the
|
|
606
|
+
* transferable optimization assumes `update.buffer` IS the payload.
|
|
607
|
+
* Returning an exact-fit buffer (slicing when needed) makes that
|
|
608
|
+
* assumption explicit and survives any future Yjs change that yields
|
|
609
|
+
* a view over a larger backing buffer (e.g. a pooled scratch buffer).
|
|
610
|
+
*/
|
|
611
|
+
_exactFitBuffer(update) {
|
|
612
|
+
if (update.byteOffset === 0 &&
|
|
613
|
+
update.byteLength === update.buffer.byteLength &&
|
|
614
|
+
update.buffer instanceof ArrayBuffer) {
|
|
615
|
+
return update.buffer;
|
|
616
|
+
}
|
|
617
|
+
// `slice()` returns a fresh ArrayBuffer of exactly the right size.
|
|
618
|
+
return update.slice().buffer;
|
|
619
|
+
}
|
|
620
|
+
_bind() {
|
|
621
|
+
this._docUpdateHandler = (update, origin) => {
|
|
622
|
+
if (origin === ORIGIN_REMOTE)
|
|
623
|
+
return;
|
|
624
|
+
// Notify local listeners BEFORE postMessage. The host transport
|
|
625
|
+
// (real window.postMessage, Worker.postMessage) treats the second
|
|
626
|
+
// arg as transferables and detaches the buffer; any listener
|
|
627
|
+
// running after would receive a Uint8Array backed by a detached
|
|
628
|
+
// buffer (length 0 / throws on read). Snapshot the set so an
|
|
629
|
+
// unsubscribe inside a callback doesn't trip iteration.
|
|
630
|
+
for (const cb of [...this._onUpdateListeners])
|
|
631
|
+
cb(update);
|
|
632
|
+
const buf = this._exactFitBuffer(update);
|
|
633
|
+
this.postMessage({ type: 'crdtUpdate', update: buf }, [buf]);
|
|
634
|
+
};
|
|
635
|
+
this._doc.on('update', this._docUpdateHandler);
|
|
636
|
+
this._awarenessUpdateHandler = (change, origin) => {
|
|
637
|
+
if (origin === ORIGIN_REMOTE)
|
|
638
|
+
return;
|
|
639
|
+
const clients = change.added.concat(change.updated, change.removed);
|
|
640
|
+
if (clients.length === 0)
|
|
641
|
+
return;
|
|
642
|
+
const update = encodeAwarenessUpdate(this._awareness, clients);
|
|
643
|
+
const buf = this._exactFitBuffer(update);
|
|
644
|
+
this.postMessage({ type: 'crdtAwarenessUpdate', update: buf }, [buf]);
|
|
645
|
+
};
|
|
646
|
+
this._awareness.on('update', this._awarenessUpdateHandler);
|
|
647
|
+
}
|
|
648
|
+
_unbind() {
|
|
649
|
+
if (this._docUpdateHandler) {
|
|
650
|
+
this._doc.off('update', this._docUpdateHandler);
|
|
651
|
+
this._docUpdateHandler = null;
|
|
652
|
+
}
|
|
653
|
+
if (this._awarenessUpdateHandler) {
|
|
654
|
+
this._awareness.off('update', this._awarenessUpdateHandler);
|
|
655
|
+
this._awarenessUpdateHandler = null;
|
|
656
|
+
}
|
|
657
|
+
}
|
|
658
|
+
}
|
|
659
|
+
//# sourceMappingURL=CrdtChannel.js.map
|