@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/sync/sync-adapter.d.ts

@@ -0,0 +1,243 @@
+import type { DiagramModel } from '../models/DiagramModel';
+import { Replica } from '../collab/replica';
+import { type ActorId, type Op } from '../collab/op';
+import { Awareness, type AwarenessState } from './awareness';
+import { type OpBatcherOptions } from './batcher';
+import type { SyncTransport } from './transport';
+import { type VersionVectorJSON } from './version-vector';
+export interface SyncAdapterOptions {
+    /** Batching. `false` sends every op the instant it happens — legal, and a bad idea. */
+    batch?: Omit<OpBatcherOptions, 'onFlush'> | false;
+    /**
+     * Forward ops that were NEW to us on to our other peers.
+     *
+     * OFF by default, because every transport shipped here is a BROADCAST bus — everyone
+     * already got the message, so relaying it doubles the traffic to deliver nothing. Turn
+     * it ON for a point-to-point mesh (WebRTC, a chain of relays) where a peer may be
+     * reachable only through us. It terminates because `Replica.receive()` returns the ops
+     * that were genuinely new, and a re-delivery is new to nobody.
+     */
+    relay?: boolean;
+    /** Periodic anti-entropy, ms. 0 disables it (the tests drive `sync()` by hand). */
+    syncIntervalMs?: number;
+    /** Re-publish our awareness this often so peers do not time us out while we sit still. */
+    heartbeatMs?: number;
+    /** Minimum ms between awareness sends. 60Hz in, ~20Hz out. */
+    awarenessThrottleMs?: number;
+    /** Drop a peer's presence after this long without a word. */
+    awarenessTimeoutMs?: number;
+    /** Injectables, so every timing test is deterministic instead of a race. */
+    setTimer?: (cb: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    setInterval?: (cb: () => void, ms: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+    now?: () => number;
+}
+/** Counters. Every one of them is something a test asserts on, not decoration. */
+export interface SyncStats {
+    /** Messages handed to the transport. */
+    messagesSent: number;
+    /** Messages taken from the transport. */
+    messagesReceived: number;
+    /** Ops we put on the wire (post-coalescing). */
+    opsSent: number;
+    /** Ops that arrived. */
+    opsReceived: number;
+    /** …of which the log had already seen: duplicate delivery, absorbed. */
+    opsDuplicate: number;
+    /** Ops currently HELD by the causal buffer, waiting for an `add`. */
+    opsHeld: number;
+    /** Anti-entropy rounds we asked for. */
+    syncsRequested: number;
+    /**
+     * Times a peer's frontier turned out to have a HOLE and we resent an actor's history.
+     *
+     * The number that proves the hostile-transport fuzz is not vacuous. If this is 0 after
+     * a thousand lossy trials, the repair path never ran and the test proved nothing.
+     */
+    repairs: number;
+    /** Ops the batcher swallowed because a later write superseded them. */
+    opsCoalesced: number;
+    /** Reconnects observed. */
+    reconnects: number;
+}
+/**
+ * Binds one `Replica` to one `SyncTransport`.
+ *
+ * The replica must be constructed with `onLocalOp` pointing at `adapter.publish` — use
+ * {@link createSyncSession}, which does that wiring for you and cannot get it backwards.
+ */
+export declare class SyncAdapter {
+    readonly replica: Replica;
+    private readonly transport;
+    private readonly options;
+    readonly awareness: Awareness;
+    private readonly buffer;
+    private readonly vv;
+    /**
+     * Ops we COALESCED AWAY and will therefore never transmit — to anyone, ever.
+     *
+     * They are in our LOG (they really happened) but not in the history we SHARE, so they must
+     * not appear in our frontier or in any catch-up delta we serve. See `sharedHistory()` for
+     * the bug this prevents; it is the difference between "one op per drag" and "the entire
+     * document history, resent on every sync round, forever".
+     */
+    private readonly suppressed;
+    private readonly batcher;
+    private readonly unsubs;
+    private syncTimer;
+    private heartbeatTimer;
+    private awarenessTimer;
+    private awarenessPending;
+    private lastAwarenessSend;
+    private joined;
+    /** Have we ever successfully announced? Distinguishes the first connect from a RECONNECT. */
+    private announced;
+    private disposed;
+    private readonly nowFn;
+    private readonly setTimerFn;
+    private readonly clearTimerFn;
+    private readonly setIntervalFn;
+    private readonly clearIntervalFn;
+    readonly stats: SyncStats;
+    constructor(replica: Replica, transport: SyncTransport, options?: SyncAdapterOptions);
+    get actor(): ActorId;
+    get diagram(): DiagramModel;
+    /** Ops still waiting on an `add` that has not arrived. Should return to 0. */
+    get pendingOps(): Op[];
+    /**
+     * What we tell peers we have.
+     *
+     * THE INVARIANT, and it is worth stating as one because it is the whole correctness
+     * condition of this layer in a single line:
+     *
+     *     frontier() === VersionVector.fromOps(sharedHistory())     — ALWAYS.
+     *
+     * SHARED history, not the local log — an op coalescing withheld is not part of the history
+     * we share with anyone, and advertising it would make every peer chase a hole that can
+     * never be filled. That distinction IS the bug documented on `sharedHistory()`.
+     *
+     * The frontier is a CACHE of that summary, maintained incrementally so we do not rescan
+     * the history on every sync. A cache that disagrees with its source is not a performance
+     * detail; it is a peer lying to the network about what it holds. Claim too much and you
+     * never receive the op you are missing (silent data loss); claim too little and every
+     * round resends an actor's entire history (a silent O(history) amplifier on the flakiest
+     * connections, which is precisely where you can least afford it).
+     *
+     * `sync-adapter.spec.ts` asserts this equality after a full hostile session, which is what
+     * makes it a checked invariant rather than a comment.
+     */
+    frontier(): VersionVectorJSON;
+    /**
+     * Announce ourselves and ask for what we are missing.
+     *
+     * `hello` carries our frontier, so an existing peer can push us the history we lack
+     * without a second round trip — a joining peer should see the document on the first
+     * message, not the third.
+     */
+    join(): void;
+    /** Say goodbye and stop. Best-effort — the peers' TTL is what actually guarantees it. */
+    leave(): void;
+    /**
+     * An anti-entropy round: "here is my frontier; send me what I lack, and tell me yours."
+     *
+     * Called on join, on RECONNECT, and (optionally) on a timer. The timer is not paranoia:
+     * a transport that can drop a message can drop an op, and the ONLY thing that ever
+     * repairs that is asking again.
+     */
+    sync(): void;
+    /** Push any queued local ops onto the wire now. */
+    flush(): void;
+    /**
+     * Our own edits. Wired to `Replica.onLocalOp` — see {@link createSyncSession}.
+     *
+     * The local op is ALREADY in our log and already applied (the Replica did both before
+     * calling us). Our job is only to get it to the others, so a failure to send is not a
+     * failure to edit — it is a divergence the next sync round will close.
+     */
+    publish(op: Op): void;
+    /**
+     * THE LOG AS THE NETWORK SEES IT — our history, minus everything coalescing withheld.
+     *
+     * ---------------------------------------------------------------------------
+     * THE BUG THIS EXISTS TO FIX, WHICH WAS MINE, AND WHICH ONLY THE BROWSER FOUND
+     * ---------------------------------------------------------------------------
+     * A 20-frame drag puts ONE op on the wire and leaves TWENTY in the local log — that is
+     * coalescing working exactly as designed, and the two peers' documents agree perfectly.
+     *
+     * But anti-entropy compares FRONTIERS DERIVED FROM LOGS. So on the next sync round my
+     * frontier said "I hold 20 ops from alice" and the peer's said "I hold 1", and the digest
+     * — which cannot tell a withheld op from a lost one — declared a HOLE and repaired it by
+     * resending my entire history. Measured: `opsSent` went from 1 to 21 on the first sync
+     * after a single drag. And it never settles, because the peer can NEVER obtain the 19 ops
+     * I have deliberately decided never to send. Every sync round, forever, for the rest of
+     * the session, on the most common interaction in the product.
+     *
+     * It is invisible to a convergence oracle — the document is perfectly correct throughout —
+     * and it was invisible to my own frontier-invariant test, which flushed after every single
+     * op and therefore never once coalesced anything while syncing. It took driving a real drag
+     * through a real browser to compose the two.
+     *
+     * THE FIX is a definition, not a patch: THE FRONTIER DESCRIBES THE SHARED LOG. An op we
+     * chose never to transmit is not part of the history we share with anyone, so it is not in
+     * our frontier and it is not in the catch-up delta we serve — to ANY peer, including one
+     * that joins tomorrow. Every peer therefore holds the same shared set, every digest agrees,
+     * and the fast path stays fast.
+     */
+    sharedHistory(): Op[];
+    /**
+     * Publish our cursor / selection / name.
+     *
+     * THROTTLED, not debounced. A debounce would send nothing at all while the mouse keeps
+     * moving — the cursor would only appear once you stopped, which is the exact opposite
+     * of the feature. A throttle sends the newest sample at a bounded rate and drops the
+     * ones in between, which is precisely correct for a value where only the latest matters.
+     */
+    setAwareness(patch: Partial<AwarenessState>): void;
+    private sendAwareness;
+    private send;
+    private sendOps;
+    private onStatus;
+    /**
+     * "Here I am; here is what I have."
+     *
+     * Fired on the first connect and on every RECONNECT, and it is the same two messages
+     * both times — because "I have been away for 30 seconds" and "I have just arrived" are
+     * the same question from the network's point of view, and answering them with one code
+     * path is why the reconnect case cannot rot: it is exercised by every single join.
+     *
+     * Everything both sides did while apart is sitting in their logs. Nothing was lost; it
+     * was only undelivered. `deltaFor` works out exactly what each side missed.
+     */
+    private announce;
+    private onMessage;
+    /** Ship a peer exactly the ops its frontier says it does not have. */
+    private answer;
+    /**
+     * The receive path, in the only order that works.
+     *
+     *   CausalBuffer → Replica → VersionVector → relay
+     *
+     * The buffer FIRST, and that ordering is the load-bearing part: an op that reaches the
+     * Replica before its `add` is logged, stamped, and silently dropped, and no later
+     * delivery can ever resurrect it (the log de-duplicates it, and the LWW gate now refuses
+     * it as superseded by itself). Once it is past the Replica it is too late. See
+     * causal-buffer.ts.
+     */
+    private ingest;
+    private stopTimers;
+    dispose(): void;
+}
+export interface SyncSessionOptions extends SyncAdapterOptions {
+    actor: ActorId;
+    /** Resume the Lamport clock from a persisted tail. */
+    startClock?: number;
+}
+/**
+ * Build a Replica and a SyncAdapter, correctly wired to each other.
+ *
+ * The wiring is one line and it is easy to forget, and forgetting it produces the exact
+ * failure this codebase is famous for: everything green, every unit test passing, and not
+ * one edit ever reaching the wire — because `onLocalOp` went nowhere.
+ */
+export declare function createSyncSession(diagram: DiagramModel, transport: SyncTransport, options: SyncSessionOptions): SyncAdapter;