@mocanvas/sync 1.0.0 → 4.0.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Signal } from '@mocanvas/state';
 import { Store, UnknownRecord, RecordsDiff } from '@mocanvas/store';
-import { InstancePresence, InstancePresenceId, Editor } from '@mocanvas/editor';
+import { UserId, InstancePresence, InstancePresenceId, Editor } from '@mocanvas/editor';
 import * as react from 'react';
 
 /** Presence is sent at most this often (30 Hz). */
@@ -22,7 +22,7 @@ interface PresenceEditor {
         };
     };
     readonly user: {
-        getId(): string;
+        getId(): UserId;
         getName(): string;
         getColor(): string;
     };
@@ -45,7 +45,7 @@ interface PresenceEditor {
             h: number;
         } | null;
         scribbles: readonly unknown[];
-        followingUserId: string | null;
+        followingUserId: UserId | null;
     };
     /** Optional: used to sample the cursor, which is not itself a signal. */
     on?(name: "event", fn: () => void): () => void;
@@ -99,20 +99,196 @@ declare class PresenceRoom<R extends UnknownRecord> {
     private removeRecord;
 }
 
-/** Bumped when the wire format changes incompatibly. */
-declare const PROTOCOL_VERSION = 1;
 /**
- * Every message is one JSON object with a `type` discriminator.
+ * A state-based CRDT over record fields.
+ *
+ * Every leaf field of every record is its own last-writer-wins register,
+ * keyed by a dotted path (`x`, `props.w`, `meta.notes.title`). A write carries
+ * a Lamport stamp; the greater stamp wins, and equal Lamport values are broken
+ * by client id so that both sides of a race reach the same answer from the
+ * same pair. Deletion is a stamped tombstone rather than a removal, so a late
+ * message cannot resurrect a record that was deleted after it was written.
+ *
+ * Consequences worth knowing before reading the code:
+ *
+ * - Arrays are opaque. `props.points` is one register holding the whole array,
+ *   not one register per element. Two concurrent edits to one array pick a
+ *   winner instead of merging; splitting arrays into elements would need
+ *   element identity, which record data does not carry.
+ * - A stamp covers a whole subtree. Writing `meta` (setting it, or deleting
+ *   the key) dominates `meta.a`: the claim loses to any stamp at or above its
+ *   own path, and dropping a subtree keeps descendants stamped later than the
+ *   write. Without that, `delete meta` racing `set meta.a` lands differently
+ *   depending on arrival order.
+ * - A record also has one `base` register: the stamp at which some sender's
+ *   whole record body was current. Fields nobody holds a stamp for — a record
+ *   materialized without its creation message, or one that came back from
+ *   under a tombstone, which erases field stamps — are governed by that single
+ *   register, so every replica takes its body from the same message instead of
+ *   from whichever one happened to arrive first.
+ * - Merging is idempotent (the same message twice is a no-op the second time)
+ *   and commutative (per path the result is the maximum stamp, which does not
+ *   depend on arrival order).
+ * - The merge is a pure function of the stamps; values only ever ride along.
+ */
+/** Version of the `CrdtState` blob on the wire. */
+declare const CRDT_STATE_VERSION = 1;
+/** How many collected-and-gone records keep a tombstone before it is dropped. */
+declare const DEFAULT_TOMBSTONE_LIMIT = 5000;
+/** How long a tombstone for a vanished record is kept. */
+declare const DEFAULT_TOMBSTONE_MAX_AGE_MS: number;
+/** A point in the partial order of writes, made total by the client tiebreak. */
+interface Stamp {
+    readonly lamport: number;
+    readonly client: string;
+}
+/**
+ * A total order on stamps: Lamport first, then client id. Two peers holding
+ * the same pair always agree, which is what makes the merge deterministic.
+ */
+declare function compareStamps(a: Stamp, b: Stamp): number;
+interface LamportClock {
+    /** The current value. */
+    get(): number;
+    /** Advance for a local write and return the new value. */
+    tick(): number;
+    /** Fold in a stamp seen from a peer: `max(local, remote) + 1`. */
+    observe(remote: number): void;
+}
+declare function createLamportClock(start?: number): LamportClock;
+/**
+ * One record's changed fields. `record` is the whole record as the sender saw
+ * it after the change; `fields` says which paths this message actually claims.
+ * A receiver that already has the record takes only the winning paths out of
+ * `record`; a receiver that does not have it materializes from `record` whole.
+ */
+interface StampedPut<R extends UnknownRecord = UnknownRecord> {
+    record: R;
+    fields: Record<string, Stamp>;
+    /**
+     * The stamp at which `record` was the sender's whole view of that record.
+     * Paths the receiver holds no stamp for are taken from `record` when this is
+     * the greatest such stamp it has seen, and left alone otherwise.
+     */
+    base?: Stamp;
+}
+interface StampedRemove {
+    id: string;
+    stamp: Stamp;
+}
+/** What a `diff` message carries: puts and removes, each field stamped. */
+interface StampedDiff<R extends UnknownRecord = UnknownRecord> {
+    puts: StampedPut<R>[];
+    removes: StampedRemove[];
+}
+declare function createEmptyStampedDiff<R extends UnknownRecord = UnknownRecord>(): StampedDiff<R>;
+declare function isStampedDiffEmpty<R extends UnknownRecord>(diff: StampedDiff<R>): boolean;
+/** What one record's registers look like once serialized. */
+interface CrdtRecordState {
+    fields: Record<string, Stamp>;
+    /** The stamp of the message this record's unstamped fields came from. */
+    base?: Stamp;
+    deleted?: Stamp;
+    /** Local wall clock at the time the tombstone was taken, for collection. */
+    deletedAt?: number;
+}
+/** The whole replica's stamps, as carried by a `snapshot` message. */
+interface CrdtState {
+    version: number;
+    clock: number;
+    records: Record<string, CrdtRecordState>;
+}
+declare function createEmptyCrdtState(): CrdtState;
+interface CrdtOptions<R extends UnknownRecord = UnknownRecord> {
+    /** Identifies this replica; also the tiebreak in `compareStamps`. */
+    clientId: string;
+    /**
+     * Read the replica's current value for a record. The CRDT owns the stamps,
+     * never the values: the store stays the source of truth and a merge is
+     * expressed as a diff against whatever `getRecord` reports.
+     */
+    getRecord?: ((id: string) => R | undefined) | undefined;
+    /** Tombstones kept for records that are gone. Default 5000. */
+    tombstoneLimit?: number | undefined;
+    /** How long such a tombstone lives. Default one hour. */
+    tombstoneMaxAgeMs?: number | undefined;
+    /** Injectable wall clock, for tests. */
+    now?: (() => number) | undefined;
+}
+interface Crdt<R extends UnknownRecord = UnknownRecord> {
+    readonly clientId: string;
+    readonly clock: LamportClock;
+    /**
+     * Stamp a diff the local user just made and return the message to send.
+     * The whole diff shares one stamp: it was one operation.
+     */
+    stampLocal(diff: RecordsDiff<R>): StampedDiff<R>;
+    /**
+     * Merge a peer's message. The returned diff holds only the fields that won,
+     * as whole records the store can apply — never a blind overwrite.
+     */
+    mergeRemote(stamped: StampedDiff<R>): RecordsDiff<R>;
+    /** This replica's stamps, for a `snapshot` message. */
+    getState(): CrdtState;
+    /**
+     * Adopt a peer's stamps wholesale. This is what a replica that is joining
+     * with no state of its own does, together with that peer's records: it takes
+     * the peer's stamps instead of starting blank, so its own later writes sort
+     * after everything already in the room. The returned diff removes whatever
+     * the peer has tombstoned and we still hold. Only for a replica holding no
+     * stamps at all: the caller adopts the peer's records wholesale alongside it,
+     * so a replica with work of its own must merge the snapshot through
+     * `stampedDiffFromSnapshot` instead of taking it.
+     */
+    applyState(state: CrdtState): RecordsDiff<R>;
+    /**
+     * Writes this replica minted while merging, which the caller must broadcast.
+     * A record kept alive by an edit that outranks a delete is re-claimed whole
+     * under a fresh stamp: the tombstone leaves the fields it dominates with no
+     * provenance at all, and only a stamped body can put every replica on the
+     * same one. Empty when there is nothing to send.
+     */
+    takeOutgoing(): StampedDiff<R> | null;
+    /** Number of records the state currently tracks (tests and diagnostics). */
+    size(): number;
+    /** Drop tombstones past the count or age bound. Called after every merge. */
+    collectTombstones(): void;
+}
+declare function createCrdt<R extends UnknownRecord = UnknownRecord>(options: CrdtOptions<R>): Crdt<R>;
+/**
+ * Turn a peer's snapshot into a message the ordinary merge can eat: its
+ * records supply the values, its state supplies the stamps. Paths the state
+ * says nothing about are not claimed, so a snapshot can never overwrite a
+ * field the receiver has a stamp for.
+ */
+declare function stampedDiffFromSnapshot<R extends UnknownRecord>(records: readonly R[], state: CrdtState): StampedDiff<R>;
+
+/**
+ * Bumped when the wire format changes incompatibly.
+ *
+ * 2: `diff` carries a `StampedDiff` (per-field Lamport stamps) instead of a
+ *    plain `RecordsDiff`, `snapshot` carries the CRDT state next to the
+ *    records, and every message carries `version`.
+ * 3: a put carries `base`, the stamp its whole record body is current as of,
+ *    and a record kept alive by an edit that outranks a delete is re-claimed
+ *    whole under a fresh stamp. A version 2 peer merges the same messages to a
+ *    different answer, so the two must not share a room.
+ */
+declare const PROTOCOL_VERSION = 3;
+/**
+ * Every message is one JSON object with a `type` discriminator and a
+ * `version`, which `encodeMessage` stamps on and `decodeMessage` checks.
  *
  * ```
- * hello     a client joined; existing peers answer with a snapshot
- * snapshot  the document-scope records as the sender currently sees them
- * diff      one squashed store diff, in document scope
- * presence  one presence record (cursor, camera, selection)
- * bye       the client is leaving; drop its presence
+ * hello        a client joined; existing peers answer with a snapshot
+ * snapshot     the document-scope records plus the sender's CRDT stamps
+ * diff         one squashed store diff, stamped field by field
+ * presence     one presence record (cursor, camera, selection)
+ * bye          the client is leaving; drop its presence
+ * unsupported  synthesised locally for a peer on another protocol version
  * ```
  */
-type SyncMessage<R extends UnknownRecord = UnknownRecord> = HelloMessage | SnapshotMessage<R> | DiffMessage<R> | PresenceMessage<R> | ByeMessage;
+type SyncMessage<R extends UnknownRecord = UnknownRecord> = HelloMessage | SnapshotMessage<R> | DiffMessage<R> | PresenceMessage<R> | ByeMessage | UnsupportedMessage;
 interface HelloMessage {
     type: "hello";
     clientId: string;
@@ -121,13 +297,15 @@ interface HelloMessage {
 interface SnapshotMessage<R extends UnknownRecord = UnknownRecord> {
     type: "snapshot";
     records: R[];
+    /** The stamps that go with those records, so a joiner does not start blank. */
+    state: CrdtState;
 }
 interface DiffMessage<R extends UnknownRecord = UnknownRecord> {
     type: "diff";
     clientId: string;
     /** Per-client counter; only used for logging and de-duplication. */
     seq: number;
-    diff: RecordsDiff<R>;
+    diff: StampedDiff<R>;
 }
 interface PresenceMessage<R extends UnknownRecord = UnknownRecord> {
     type: "presence";
@@ -138,10 +316,21 @@ interface ByeMessage {
     type: "bye";
     clientId: string;
 }
+/**
+ * Never sent: `decodeMessage` returns this instead of guessing at a message
+ * whose `version` is not ours, so a peer on another protocol is reported once
+ * rather than half-parsed.
+ */
+interface UnsupportedMessage {
+    type: "unsupported";
+    version: number;
+    clientId?: string;
+}
 declare function encodeMessage<R extends UnknownRecord>(message: SyncMessage<R>): string;
 /**
- * Parse a message off the wire. Returns `null` for anything malformed: a peer
- * on a newer protocol must never be able to crash this one.
+ * Parse a message off the wire. Returns `null` for anything malformed and an
+ * `unsupported` message for a peer on another protocol version: neither can
+ * crash this client, and neither is ever mistaken for a message we understand.
  */
 declare function decodeMessage<R extends UnknownRecord = UnknownRecord>(data: unknown): SyncMessage<R> | null;
 
@@ -216,6 +405,10 @@ interface SyncClientOptions<R extends UnknownRecord = UnknownRecord> {
     /** Upper bound on presence send rate. Default 34ms (~30 Hz). */
     presenceThrottleMs?: number | undefined;
     presenceHeartbeatMs?: number | undefined;
+    /** How many tombstones for vanished records to keep. See `crdt.ts`. */
+    tombstoneLimit?: number | undefined;
+    /** How long such a tombstone lives, in ms. */
+    tombstoneMaxAgeMs?: number | undefined;
     /** Called for protocol-level problems (a peer on another version, say). */
     onError?: ((error: Error) => void) | undefined;
 }
@@ -231,9 +424,12 @@ interface SyncClient {
 /**
  * Joins one room over `transport` and keeps `store` in step with its peers.
  *
- * Document changes made locally by the user are broadcast as diffs; incoming
- * diffs are applied as remote changes so they neither echo back nor land in
- * the undo stack. Conflicts are resolved last-writer-wins per record.
+ * Document changes made locally by the user are stamped by the CRDT (see
+ * `crdt.ts`) and broadcast; incoming messages are merged field by field and
+ * only the fields that won are applied, as remote changes, so they neither
+ * echo back nor land in the undo stack. Concurrent edits to different fields
+ * of one record all survive, and replicas converge whatever order messages
+ * arrive in.
  */
 declare function createSyncClient<R extends UnknownRecord = UnknownRecord>(options: SyncClientOptions<R>): SyncClient;
 
@@ -275,4 +471,4 @@ interface UseSyncResult {
  */
 declare function useSync(editor: Editor | null, options: UseSyncOptions): UseSyncResult;
 
-export { type BroadcastChannelTransportOptions, type ByeMessage, CollaboratorCursors, type CollaboratorCursorsProps, DEFAULT_PRESENCE_HEARTBEAT_MS, DEFAULT_PRESENCE_THROTTLE_MS, DEFAULT_PRESENCE_TIMEOUT_MS, type DiffMessage, type HelloMessage, type MemoryHub, PROTOCOL_VERSION, type PresenceEditor, type PresenceMessage, PresenceRoom, type PresenceSync, type PresenceSyncOptions, type SnapshotMessage, type SyncClient, type SyncClientOptions, type SyncMessage, type SyncStatus, type Transport, type UseSyncOptions, type UseSyncResult, type WebSocketTransportOptions, createBroadcastChannelTransport, createMemoryHub, createMemoryTransportPair, createPresenceSync, createSyncClient, createWebSocketTransport, decodeMessage, encodeMessage, isSamePresence, presenceIdForClient, useSync };
+export { type BroadcastChannelTransportOptions, type ByeMessage, CRDT_STATE_VERSION, CollaboratorCursors, type CollaboratorCursorsProps, type Crdt, type CrdtOptions, type CrdtRecordState, type CrdtState, DEFAULT_PRESENCE_HEARTBEAT_MS, DEFAULT_PRESENCE_THROTTLE_MS, DEFAULT_PRESENCE_TIMEOUT_MS, DEFAULT_TOMBSTONE_LIMIT, DEFAULT_TOMBSTONE_MAX_AGE_MS, type DiffMessage, type HelloMessage, type LamportClock, type MemoryHub, PROTOCOL_VERSION, type PresenceEditor, type PresenceMessage, PresenceRoom, type PresenceSync, type PresenceSyncOptions, type SnapshotMessage, type Stamp, type StampedDiff, type StampedPut, type StampedRemove, type SyncClient, type SyncClientOptions, type SyncMessage, type SyncStatus, type Transport, type UnsupportedMessage, type UseSyncOptions, type UseSyncResult, type WebSocketTransportOptions, compareStamps, createBroadcastChannelTransport, createCrdt, createEmptyCrdtState, createEmptyStampedDiff, createLamportClock, createMemoryHub, createMemoryTransportPair, createPresenceSync, createSyncClient, createWebSocketTransport, decodeMessage, encodeMessage, isSamePresence, isStampedDiffEmpty, presenceIdForClient, stampedDiffFromSnapshot, useSync };