@spooky-sync/core 0.0.1-canary.34 → 0.0.1-canary.341

package/src/modules/crdt/acceptance.ts

@@ -0,0 +1,75 @@
+import type * as Loro from 'loro-crdt';
+
+/**
+ * Which edit-log rows may enter a document.
+ *
+ * Every client and the SSP fold (`packages/ssp-node/src/crdt/acceptance.rs`)
+ * apply this exact rule before importing a row, so they import the same rows
+ * and converge on the same document: a row one side accepted and another
+ * refused would leave them different forever (a CRDT never forgets an op).
+ *
+ * - the blob decodes as a Loro **update** (a snapshot could smuggle in
+ *   arbitrary history from any peer);
+ * - it is no larger than the column allows;
+ * - every op in it was made by the row's `peer`, which the database already
+ *   checked belongs to the row's author (`_00_crdt_peer`).
+ *
+ * Loro's decoder can trap on crafted input with a valid checksum, so a raw
+ * header check rejects non-update blobs before decoding, and decoding runs
+ * under `try`.
+ */
+
+export type Rejection =
+  | 'empty'
+  | 'too_large'
+  | 'bad_peer'
+  | 'header'
+  | 'undecodable'
+  | 'not_an_update'
+  | 'no_ops'
+  | 'foreign_peer';
+
+export interface Accepted {
+  peer: `${number}`;
+  /** Exclusive end counter of the row's ops for `peer`. */
+  end: number;
+}
+
+export type Verdict = { ok: true; accepted: Accepted } | { ok: false; reason: Rejection };
+
+/** The largest blob a row may carry (the generated column's cap). */
+export const MAX_DELTA_BYTES = 256 * 1024;
+
+const PEER = /^\d{1,20}$/;
+/** `"loro"`: every Loro blob starts with it. */
+const MAGIC = [0x6c, 0x6f, 0x72, 0x6f];
+/** Header bytes 20..22 (big-endian) carry the encoding mode; 4 is an update. */
+const MODE_UPDATES = 4;
+
+export function check(
+  loro: Pick<typeof Loro, 'decodeImportBlobMeta'>,
+  blob: Uint8Array | undefined,
+  peer: unknown,
+  maxBytes = MAX_DELTA_BYTES
+): Verdict {
+  if (!blob || blob.length === 0) return { ok: false, reason: 'empty' };
+  if (blob.length > maxBytes) return { ok: false, reason: 'too_large' };
+  if (typeof peer !== 'string' || !PEER.test(peer)) return { ok: false, reason: 'bad_peer' };
+  if (blob.length < 22 || MAGIC.some((b, i) => blob[i] !== b)) return { ok: false, reason: 'header' };
+  if (((blob[20] << 8) | blob[21]) !== MODE_UPDATES) return { ok: false, reason: 'not_an_update' };
+  let meta: ReturnType<typeof Loro.decodeImportBlobMeta>;
+  try {
+    meta = loro.decodeImportBlobMeta(blob, true);
+  } catch {
+    return { ok: false, reason: 'undecodable' };
+  }
+  if (meta.mode !== 'update') return { ok: false, reason: 'not_an_update' };
+  const start = meta.partialStartVersionVector.toJSON();
+  const authors: Array<[string, number]> = [];
+  for (const [p, end] of meta.partialEndVersionVector.toJSON()) {
+    if (end > (start.get(p) ?? 0)) authors.push([String(p), end]);
+  }
+  if (authors.length === 0) return { ok: false, reason: 'no_ops' };
+  if (authors.length > 1 || BigInt(authors[0][0]) !== BigInt(peer)) return { ok: false, reason: 'foreign_peer' };
+  return { ok: true, accepted: { peer: peer as `${number}`, end: authors[0][1] } };
+}

package/src/modules/crdt/bytes.ts

@@ -0,0 +1,50 @@
+/**
+ * Byte columns reach the client in several shapes depending on the engine and
+ * the path: `Uint8Array` (SQLite, a fresh local write), `ArrayBuffer` (the
+ * surrealdb SDK's CBOR decode), a typed-array view, or a `number[]` (bytes
+ * nested in a FLEXIBLE object on the SurrealDB-WASM engine). Normalize all of
+ * them; anything else is not bytes.
+ */
+export function asBytes(value: unknown): Uint8Array | undefined {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (Array.isArray(value) && value.length > 0 && value.every((n) => typeof n === 'number')) {
+    return Uint8Array.from(value as number[]);
+  }
+  return undefined;
+}
+
+export function decodeBase64(b64: string): Uint8Array {
+  if (typeof atob === 'function') {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  }
+  return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+
+export function encodeBase64(bytes: Uint8Array): string {
+  if (typeof btoa === 'function') {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+  }
+  return Buffer.from(bytes).toString('base64');
+}
+
+/**
+ * A random Loro peer id below 2^53 (so it is exact as a JS number), as the
+ * decimal string Loro uses for `PeerID`. Each tab picks a new one per session
+ * and claims it in `_00_crdt_peer` before any of its edits are sent.
+ */
+export function randomPeer(): `${number}` {
+  const words = new Uint32Array(2);
+  crypto.getRandomValues(words);
+  const high = words[0] & 0x1fffff; // 21 bits
+  const id = high * 0x100000000 + words[1];
+  return String(id === 0 ? 1 : id) as `${number}`;
+}

package/src/modules/crdt/crdt-field.ts

@@ -0,0 +1,125 @@
+import type { LoroDoc } from 'loro-crdt';
+import type { CrdtKind } from './mirror';
+
+// ==================== CURSOR UTILITIES ====================
+
+export const CURSOR_COLORS = [
+  '#3b82f6', '#ef4444', '#22c55e', '#f59e0b',
+  '#8b5cf6', '#ec4899', '#14b8a6', '#f97316',
+];
+
+export function cursorColorFromName(name: string): string {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = ((hash << 5) - hash + name.charCodeAt(i)) | 0;
+  }
+  return CURSOR_COLORS[Math.abs(hash) % CURSOR_COLORS.length];
+}
+
+export { decodeBase64, encodeBase64 } from './bytes';
+
+// ==================== CRDT FIELD ====================
+
+/** What a field handle needs from the manager that owns its session. */
+export interface CrdtFieldHost {
+  pushPresence(state: Uint8Array): void;
+}
+
+/**
+ * An open collaborative field: the Loro document an editor binds to. Edits
+ * made on it are sent as the client's own edit-log rows; other clients' rows
+ * are imported into it as they arrive. Every open of the same field in one tab
+ * shares this document.
+ */
+export class CrdtField {
+  private _onCursorUpdate: ((data: Uint8Array) => void) | null = null;
+  private pendingCursorUpdate: Uint8Array | null = null;
+  private loaded = false;
+  private loadedListeners = new Set<() => void>();
+
+  constructor(
+    readonly table: string,
+    readonly recordId: string,
+    readonly fieldName: string,
+    readonly kind: CrdtKind,
+    readonly cursorsEnabled: boolean,
+    private readonly doc: LoroDoc,
+    private readonly host: CrdtFieldHost
+  ) {}
+
+  getDoc(): LoroDoc {
+    return this.doc;
+  }
+
+  /** Whether the document holds anything yet (local state or edits). */
+  hasContent(): boolean {
+    return this.doc.oplogVersion().length() > 0;
+  }
+
+  /**
+   * Whether the document is known: this device had it, it was handed a draft,
+   * or the server answered (with content, or that it has none yet). Until then
+   * an empty document means "not loaded", not "empty": show the column's text
+   * instead, and do not bind an editor (an editor binding an empty document
+   * creates structure that competes with the real one).
+   */
+  isLoaded(): boolean {
+    return this.loaded;
+  }
+
+  /** Runs `cb` once the field is loaded (at once if it already is). Returns
+   *  an unsubscribe. */
+  onLoaded(cb: () => void): () => void {
+    if (this.loaded) {
+      cb();
+      return () => {};
+    }
+    this.loadedListeners.add(cb);
+    return () => this.loadedListeners.delete(cb);
+  }
+
+  /** @internal The manager calls this when the document became known. */
+  markLoaded(): void {
+    if (this.loaded) return;
+    this.loaded = true;
+    for (const cb of [...this.loadedListeners]) {
+      try {
+        cb();
+      } catch {
+        /* a listener's failure is its own */
+      }
+    }
+    this.loadedListeners.clear();
+  }
+
+  /** Publish this session's presence (an `EphemeralStore` encoding, e.g. the
+   *  editor's cursor). No-op unless the field is `@cursor`. */
+  pushCursorState(encoded: Uint8Array): void {
+    if (this.cursorsEnabled) this.host.pushPresence(encoded);
+  }
+
+  /** Called with every other session's presence blob. A blob that arrives
+   *  before the editor sets this is replayed when it does. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null) {
+    this._onCursorUpdate = cb;
+    if (cb && this.pendingCursorUpdate) {
+      const data = this.pendingCursorUpdate;
+      this.pendingCursorUpdate = null;
+      try {
+        cb(data);
+      } catch {
+        /* the editor logs its own apply failures */
+      }
+    }
+  }
+
+  get onCursorUpdate() {
+    return this._onCursorUpdate;
+  }
+
+  /** @internal Deliver one remote presence blob. */
+  deliverPresence(data: Uint8Array): void {
+    if (this._onCursorUpdate) this._onCursorUpdate(data);
+    else this.pendingCursorUpdate = data;
+  }
+}