@spooky-sync/core 0.0.1-canary.38 → 0.0.1-canary.381

package/src/modules/channel/webrtc.ts

@@ -0,0 +1,472 @@
+import type { Surreal, Uuid } from 'surrealdb';
+import type { ConnectionState } from '../../types';
+import type { Logger } from '../../services/logger/index';
+import { parseRecordIdString } from '../../utils/index';
+import type { ChannelMessage, ChannelTransport, PeerRef, TransportHooks } from './index';
+import { idKey, peerKey } from './index';
+
+/**
+ * The default channel transport: one WebRTC data channel per pair of tabs,
+ * set up through signaling rows in the database.
+ *
+ * Signaling (all rows of `_00_channel_signal`, read through one raw LIVE):
+ *
+ * 1. A tab that wants user U writes `hello` to U. Every tab of U hears it.
+ * 2. Of each pair of tabs, the one with the lower `user#peer` key offers.
+ *    A tab that hears a hello from a higher key offers at once; one that
+ *    hears it from a lower key answers with a `hello` addressed back to that
+ *    tab, which then offers. So both orders of arrival connect, and nobody
+ *    loops.
+ * 3. `offer` / `answer` carry the SDPs, `ice` batches of candidates
+ *    (trickled, so nothing waits for gathering to finish).
+ *
+ * A tab only ever reacts to signals from users it wants itself, so a
+ * connection needs both sides to list each other. The database stamps every
+ * row's `sender`, and the offer carries the DTLS fingerprint of the
+ * connection, so the user on the other end of a data channel is proven.
+ */
+
+export type SignalKind = 'hello' | 'offer' | 'answer' | 'ice';
+
+export interface Signal {
+  readonly from: string;
+  readonly fromPeer: string;
+  readonly toPeer: string | null;
+  readonly kind: SignalKind;
+  readonly payload: string | null;
+}
+
+export interface OutgoingSignal {
+  readonly to: string;
+  readonly toPeer: string | null;
+  readonly fromPeer: string;
+  readonly kind: SignalKind;
+  readonly payload: string | null;
+}
+
+/** Where signals go and come from. The database by default. */
+export interface SignalPort {
+  send(signal: OutgoingSignal): Promise<void>;
+  listen(self: PeerRef, cb: (signal: Signal) => void): () => void;
+}
+
+export interface WebRtcOptions {
+  signal: SignalPort;
+  iceServers?: RTCIceServer[];
+  logger?: Pick<Logger, 'debug' | 'warn'>;
+  /** Injectable for tests and non-browser runtimes. */
+  RTCPeerConnection?: typeof RTCPeerConnection;
+  /** Give up on one attempt after this long. Default 15000. */
+  connectTimeoutMs?: number;
+}
+
+const DEFAULT_ICE: RTCIceServer[] = [{ urls: 'stun:stun.cloudflare.com:3478' }];
+const ICE_FLUSH_MS = 20;
+const RETRY_BASE_MS = 2000;
+const RETRY_MAX_MS = 30_000;
+
+interface Link {
+  readonly ref: PeerRef;
+  readonly key: string;
+  readonly offerer: boolean;
+  /** One negotiation: answers and candidates of another are ignored. */
+  readonly sid: string;
+  readonly pc: RTCPeerConnection;
+  dc: RTCDataChannel | null;
+  open: boolean;
+  remoteSet: boolean;
+  pendingIce: RTCIceCandidateInit[];
+  outIce: RTCIceCandidateInit[];
+  iceTimer: ReturnType<typeof setTimeout> | null;
+  connectTimer: ReturnType<typeof setTimeout> | null;
+  /** Signals of this link go out in order (offer before its candidates). */
+  queue: Promise<void>;
+  closed: boolean;
+}
+
+const randomSid = (): string => Math.random().toString(36).slice(2, 10);
+
+export function webrtcTransport(hooks: TransportHooks, opts: WebRtcOptions): ChannelTransport {
+  const PC = opts.RTCPeerConnection ?? (globalThis as { RTCPeerConnection?: typeof RTCPeerConnection }).RTCPeerConnection;
+  const log = opts.logger;
+  const connectTimeoutMs = opts.connectTimeoutMs ?? 15_000;
+  const links = new Map<string, Link>();
+  const retries = new Map<string, { attempts: number; timer: ReturnType<typeof setTimeout> | null }>();
+  let wanted = new Set<string>();
+  let stopListen: (() => void) | null = null;
+  let listeningAs: string | null = null;
+  let closed = false;
+
+  const selfKey = (): string | null => {
+    const self = hooks.self();
+    return self ? peerKey(self) : null;
+  };
+
+  const send = (link: Link | null, signal: Omit<OutgoingSignal, 'fromPeer'>): void => {
+    const self = hooks.self();
+    if (!self) return;
+    const out: OutgoingSignal = { ...signal, fromPeer: self.peer };
+    const run = () =>
+      opts.signal.send(out).catch((error) => {
+        log?.debug({ error, kind: signal.kind, Category: 'sp00ky-client::channel' }, 'channel signal failed');
+      });
+    if (link) link.queue = link.queue.then(run);
+    else void run();
+  };
+
+  const dropLink = (link: Link, failed: boolean): void => {
+    if (link.closed) return;
+    link.closed = true;
+    if (link.iceTimer) clearTimeout(link.iceTimer);
+    if (link.connectTimer) clearTimeout(link.connectTimer);
+    try {
+      link.dc?.close();
+      link.pc.close();
+    } catch {
+      // already gone
+    }
+    if (links.get(link.key) === link) links.delete(link.key);
+    if (link.open) {
+      link.open = false;
+      hooks.onPeer(link.ref, false);
+    }
+    if (failed && wanted.has(link.ref.user) && !closed) {
+      const anyOpen = [...links.values()].some((l) => l.ref.user === link.ref.user && l.open);
+      if (!anyOpen) hooks.onStatus(link.ref.user, 'failed');
+      scheduleRetry(link.ref);
+    }
+  };
+
+  const scheduleRetry = (ref: PeerRef): void => {
+    const key = peerKey(ref);
+    const r = retries.get(key) ?? { attempts: 0, timer: null };
+    if (r.timer) return;
+    const delay = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** r.attempts);
+    r.attempts++;
+    r.timer = setTimeout(() => {
+      r.timer = null;
+      if (closed || !wanted.has(ref.user) || links.has(key)) return;
+      const mine = selfKey();
+      if (!mine) return;
+      if (mine < key) startOffer(ref);
+      else send(null, { to: ref.user, toPeer: ref.peer, kind: 'hello', payload: null });
+    }, delay);
+    retries.set(key, r);
+  };
+
+  const attachChannel = (link: Link, dc: RTCDataChannel): void => {
+    link.dc = dc;
+    dc.onopen = () => {
+      if (link.closed) return;
+      link.open = true;
+      if (link.connectTimer) clearTimeout(link.connectTimer);
+      link.connectTimer = null;
+      retries.delete(link.key);
+      hooks.onPeer(link.ref, true);
+      hooks.onStatus(link.ref.user, 'connected');
+    };
+    dc.onclose = () => dropLink(link, true);
+    dc.onmessage = (event) => {
+      if (typeof event.data !== 'string') return;
+      let message: unknown;
+      try {
+        message = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      hooks.onMessage(link.ref, message);
+    };
+  };
+
+  const newLink = (ref: PeerRef, offerer: boolean, sid: string): Link | null => {
+    if (!PC) return null;
+    const key = peerKey(ref);
+    const prev = links.get(key);
+    if (prev) dropLink(prev, false);
+    const pc = new PC({ iceServers: opts.iceServers ?? DEFAULT_ICE });
+    const link: Link = {
+      ref,
+      key,
+      offerer,
+      sid,
+      pc,
+      dc: null,
+      open: false,
+      remoteSet: false,
+      pendingIce: [],
+      outIce: [],
+      iceTimer: null,
+      connectTimer: null,
+      queue: Promise.resolve(),
+      closed: false,
+    };
+    links.set(key, link);
+    pc.onicecandidate = (event) => {
+      if (!event.candidate || link.closed) return;
+      link.outIce.push(event.candidate.toJSON());
+      link.iceTimer ??= setTimeout(() => {
+        link.iceTimer = null;
+        const candidates = link.outIce.splice(0);
+        if (candidates.length === 0 || link.closed) return;
+        send(link, { to: ref.user, toPeer: ref.peer, kind: 'ice', payload: JSON.stringify({ sid, candidates }) });
+      }, ICE_FLUSH_MS);
+    };
+    pc.onconnectionstatechange = () => {
+      if (pc.connectionState === 'failed' || pc.connectionState === 'closed') dropLink(link, true);
+    };
+    if (!offerer) pc.ondatachannel = (event) => attachChannel(link, event.channel);
+    link.connectTimer = setTimeout(() => {
+      if (!link.open) dropLink(link, true);
+    }, connectTimeoutMs);
+    hooks.onStatus(ref.user, 'connecting');
+    return link;
+  };
+
+  const startOffer = (ref: PeerRef): void => {
+    const link = newLink(ref, true, randomSid());
+    if (!link) return;
+    attachChannel(link, link.pc.createDataChannel('sp00ky', { ordered: true }));
+    void (async () => {
+      try {
+        const offer = await link.pc.createOffer();
+        await link.pc.setLocalDescription(offer);
+        send(link, {
+          to: ref.user,
+          toPeer: ref.peer,
+          kind: 'offer',
+          payload: JSON.stringify({ sid: link.sid, sdp: link.pc.localDescription?.sdp ?? offer.sdp }),
+        });
+      } catch (error) {
+        log?.debug({ error, Category: 'sp00ky-client::channel' }, 'channel offer failed');
+        dropLink(link, true);
+      }
+    })();
+  };
+
+  const addIce = async (link: Link, candidates: RTCIceCandidateInit[]): Promise<void> => {
+    for (const c of candidates) {
+      try {
+        await link.pc.addIceCandidate(c);
+      } catch {
+        // a candidate of a torn-down negotiation, or one the browser rejects
+      }
+    }
+  };
+
+  const onSignal = (s: Signal): void => {
+    if (closed) return;
+    const self = hooks.self();
+    if (!self) return;
+    const from = idKey(s.from);
+    if (!from || !wanted.has(from)) return;
+    if (s.toPeer !== null && s.toPeer !== self.peer) return;
+    const ref: PeerRef = { user: from, peer: s.fromPeer };
+    const key = peerKey(ref);
+    const mine = peerKey(self);
+    if (key === mine) return;
+    const payload = parsePayload(s.payload);
+    const link = links.get(key);
+
+    switch (s.kind) {
+      case 'hello': {
+        if (link && !link.closed) return;
+        if (mine < key) startOffer(ref);
+        else if (s.toPeer === null) send(null, { to: from, toPeer: ref.peer, kind: 'hello', payload: null });
+        return;
+      }
+      case 'offer': {
+        if (mine < key || typeof payload?.sdp !== 'string' || typeof payload.sid !== 'string') return;
+        const answerer = newLink(ref, false, payload.sid);
+        if (!answerer) return;
+        void (async () => {
+          try {
+            await answerer.pc.setRemoteDescription({ type: 'offer', sdp: payload.sdp as string });
+            answerer.remoteSet = true;
+            await addIce(answerer, answerer.pendingIce.splice(0));
+            const answer = await answerer.pc.createAnswer();
+            await answerer.pc.setLocalDescription(answer);
+            send(answerer, {
+              to: from,
+              toPeer: ref.peer,
+              kind: 'answer',
+              payload: JSON.stringify({ sid: answerer.sid, sdp: answerer.pc.localDescription?.sdp ?? answer.sdp }),
+            });
+          } catch (error) {
+            log?.debug({ error, Category: 'sp00ky-client::channel' }, 'channel answer failed');
+            dropLink(answerer, true);
+          }
+        })();
+        return;
+      }
+      case 'answer': {
+        if (!link || !link.offerer || link.remoteSet || payload?.sid !== link.sid || typeof payload.sdp !== 'string') return;
+        link.remoteSet = true;
+        void link.pc
+          .setRemoteDescription({ type: 'answer', sdp: payload.sdp })
+          .then(() => addIce(link, link.pendingIce.splice(0)))
+          .catch(() => dropLink(link, true));
+        return;
+      }
+      case 'ice': {
+        if (!link || payload?.sid !== link.sid || !Array.isArray(payload.candidates)) return;
+        const candidates = payload.candidates as RTCIceCandidateInit[];
+        if (link.remoteSet) void addIce(link, candidates);
+        else link.pendingIce.push(...candidates);
+        return;
+      }
+    }
+  };
+
+  const ensureListening = (): void => {
+    const self = hooks.self();
+    const as = self ? peerKey(self) : null;
+    if (as === listeningAs) return;
+    stopListen?.();
+    stopListen = null;
+    listeningAs = as;
+    if (self) stopListen = opts.signal.listen(self, onSignal);
+  };
+
+  return {
+    supported: PC !== undefined,
+    want(users) {
+      if (closed || !PC) {
+        wanted = new Set(users);
+        return;
+      }
+      const before = wanted;
+      wanted = new Set(users);
+      if (wanted.size > 0) ensureListening();
+      for (const link of [...links.values()]) if (!wanted.has(link.ref.user)) dropLink(link, false);
+      for (const [key, r] of retries) {
+        if (!wanted.has(key.slice(0, key.lastIndexOf('#'))) && r.timer) clearTimeout(r.timer);
+      }
+      for (const user of wanted) {
+        if (before.has(user)) continue;
+        send(null, { to: user, toPeer: null, kind: 'hello', payload: null });
+        hooks.onStatus(user, 'connecting');
+      }
+    },
+    send(to, message: ChannelMessage) {
+      const link = links.get(peerKey(to));
+      if (!link?.open || !link.dc || link.dc.readyState !== 'open') return;
+      try {
+        link.dc.send(JSON.stringify(message));
+      } catch (error) {
+        log?.debug({ error, Category: 'sp00ky-client::channel' }, 'channel send failed');
+      }
+    },
+    close() {
+      closed = true;
+      for (const r of retries.values()) if (r.timer) clearTimeout(r.timer);
+      retries.clear();
+      for (const link of [...links.values()]) dropLink(link, false);
+      stopListen?.();
+      stopListen = null;
+    },
+  };
+}
+
+function parsePayload(payload: string | null): Record<string, unknown> | null {
+  if (!payload) return null;
+  try {
+    const v = JSON.parse(payload);
+    return v !== null && typeof v === 'object' ? (v as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---- signaling over SurrealDB ----------------------------------------------------
+
+/** The bits of the remote service signaling needs. */
+export interface SignalRemote {
+  query<T extends unknown[]>(sql: string, vars?: Record<string, unknown>): Promise<T>;
+  getClient(): Pick<Surreal, 'liveOf'>;
+}
+
+export interface SignalConnection {
+  subscribe(cb: (state: ConnectionState) => void): () => void;
+}
+
+const SIGNAL_TABLE = '_00_channel_signal';
+const LISTEN_RETRY_MS = 3000;
+
+/**
+ * Signals as rows of `_00_channel_signal` (generated for schemas with a
+ * `@channel` table): a CREATE to send, one raw `LIVE SELECT` on rows
+ * addressed to this user to receive. Not the outbox and not a synced query:
+ * each signal costs one round trip, which is what keeps connection setup
+ * short. The LIVE is re-armed whenever the socket reconnects.
+ */
+export function surrealSignal(
+  remote: SignalRemote,
+  connection: SignalConnection,
+  logger?: Pick<Logger, 'debug' | 'warn'>
+): SignalPort {
+  return {
+    async send(s) {
+      const content: Record<string, unknown> = {
+        recipient: parseRecordIdString(s.to),
+        sender_peer: s.fromPeer,
+        kind: s.kind,
+      };
+      if (s.toPeer !== null) content.recipient_peer = s.toPeer;
+      if (s.payload !== null) content.payload = s.payload;
+      await remote.query(`CREATE ${SIGNAL_TABLE} CONTENT $c RETURN NONE`, { c: content });
+    },
+    listen(self, cb) {
+      let stopped = false;
+      let uuid: Uuid | null = null;
+      let retry: ReturnType<typeof setTimeout> | null = null;
+      let state: ConnectionState | null = null;
+      const arm = async () => {
+        if (stopped) return;
+        if (retry) clearTimeout(retry);
+        retry = null;
+        const old = uuid;
+        uuid = null;
+        if (old) void remote.query('KILL $u', { u: old }).catch(() => {});
+        try {
+          const [id] = await remote.query<[Uuid]>(`LIVE SELECT * FROM ${SIGNAL_TABLE} WHERE recipient = $me`, {
+            me: parseRecordIdString(self.user),
+          });
+          if (stopped) {
+            void remote.query('KILL $u', { u: id }).catch(() => {});
+            return;
+          }
+          uuid = id;
+          const live = await remote.getClient().liveOf(id);
+          live.subscribe((message) => {
+            if (stopped || message.action !== 'CREATE') return;
+            const v = message.value as Record<string, unknown>;
+            const from = idKey(v.sender);
+            if (!from || typeof v.sender_peer !== 'string' || typeof v.kind !== 'string') return;
+            cb({
+              from,
+              fromPeer: v.sender_peer,
+              toPeer: typeof v.recipient_peer === 'string' ? v.recipient_peer : null,
+              kind: v.kind as SignalKind,
+              payload: typeof v.payload === 'string' ? v.payload : null,
+            });
+          });
+        } catch (error) {
+          logger?.debug({ error, Category: 'sp00ky-client::channel' }, 'channel signal listen failed; retrying');
+          if (!stopped) retry = setTimeout(() => void arm(), LISTEN_RETRY_MS);
+        }
+      };
+      const unsubscribe = connection.subscribe((next) => {
+        const was = state;
+        state = next;
+        if (next === 'connected' && was !== null && was !== 'connected') void arm();
+      });
+      void arm();
+      return () => {
+        stopped = true;
+        unsubscribe();
+        if (retry) clearTimeout(retry);
+        if (uuid) void remote.query('KILL $u', { u: uuid }).catch(() => {});
+      };
+    },
+  };
+}

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}`;
+}