@spooky-sync/core 0.0.1-canary.355 → 0.0.1-canary.357

package/src/mutation/write.saga.ts

@@ -2,7 +2,7 @@ import { RecordId } from 'surrealdb';
 import type { MutationEventType, UpdateOptions } from '../types';
 import type { Saga } from '../kernel/saga';
 import { fx } from '../kernel/effects';
-import type { ClientState, PendingWrite } from '../state/client-state';
+import type { ClientState, PeerWrite, PendingWrite } from '../state/client-state';
 import * as R from '../state/reducers';
 import { parseParams } from '../utils/parser';
 import { extractTablePart, parseRecordIdString } from '../utils/index';
@@ -17,6 +17,8 @@ import {
   planDeferredOutboxRowTx,
   planDeleteTx,
   planLocalOnlyUpdateTx,
+  planPeerCreateTx,
+  planPeerUndoTx,
   planUpdateTx,
   type LocalTx,
   type PendingWriteRow,
@@ -266,3 +268,117 @@ export function* adoptPendingWrites(): Saga<void> {
   if (adopted > 0) yield fx.dispatch({ type: 'Drain' });
   if (recheckAt !== Infinity) yield fx.timer.set('adopt-writes', recheckAt - now, { type: 'AdoptPendingWrites' });
 }
+
+// ---- channel peers' creates and deletes ------------------------------------------
+
+/** The row as the local store holds it, or null: what a channel checks its filter against. */
+export function* readRow(recordId: string): Saga<Record<string, unknown> | null> {
+  return yield* readBefore(parseRecordIdString(recordId));
+}
+
+export interface PeerWriteInput {
+  recordId: string;
+  /** The row's fields, for a create. */
+  data?: Record<string, unknown>;
+  /** How long it shows without the server confirming it. */
+  ttlMs: number;
+}
+
+/**
+ * A channel peer created a row: put it in the store and the circuit like an
+ * own optimistic create, minus the outbox entry (the peer pushes it), and
+ * show it through the overlay. `_00_rv` stays unset on purpose: the server's
+ * body (with its computed fields) still downloads and replaces this one.
+ * Refuses an id this client already holds a confirmed row or an own pending
+ * write for, so a peer can never overwrite real data. Returns whether it applied.
+ */
+export function* peerCreate(env: SagaEnv, input: PeerWriteInput): Saga<boolean> {
+  const table = extractTablePart(input.recordId);
+  const columns = columnsFor(env, table);
+  if (!columns) return false;
+  const [confirmed, ownPending, peerPending] = (yield fx.state.read((s) => [
+    s.versions.has(input.recordId),
+    s.outbox.some((i) => i.recordId === input.recordId),
+    s.peerWrites.has(input.recordId),
+  ])) as [boolean, boolean, boolean];
+  if (confirmed || ownPending || peerPending) return false;
+  const rid = parseRecordIdString(input.recordId);
+  const existing = yield* readBefore(rid);
+  let record = existing;
+  if (!existing) {
+    const params = parseParams(columns as never, input.data ?? {});
+    const tx = planPeerCreateTx({ recordId: rid, data: params });
+    try {
+      const res = (yield fx.local.execute(tx.query, tx.vars)) as unknown;
+      record = res && typeof res === 'object' && !Array.isArray(res) ? (res as Record<string, unknown>) : null;
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'debug', message: 'peer create refused by the local store', data: { recordId: input.recordId, error } });
+      return false;
+    }
+  }
+  // An existing unconfirmed row is another tab's copy of the same peer create.
+  if (!record) return false;
+  try {
+    yield fx.ssp.ingest([{ table, op: 'CREATE', id: input.recordId, record: { ...record, _00_rv: 0 } }]);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'error', message: 'circuit ingest failed after a peer create', data: { recordId: input.recordId, error } });
+  }
+  const now = (yield fx.now()) as number;
+  yield fx.state.update(R.setPeerWrite(input.recordId, { kind: 'create', table, expiresAt: now + input.ttlMs }));
+  yield fx.timer.set(`peer:${input.recordId}`, input.ttlMs, { type: 'PeerWriteExpired', id: input.recordId });
+  return true;
+}
+
+/**
+ * A channel peer deleted a row: hide it through the overlay, keep it in the
+ * store. Undoing is then just forgetting the entry; a confirmed delete has
+ * taken the row out of the server's membership by the time it expires.
+ */
+export function* peerDelete(env: SagaEnv, input: PeerWriteInput): Saga<boolean> {
+  const table = extractTablePart(input.recordId);
+  if (!columnsFor(env, table)) return false;
+  const [known, confirmed] = (yield fx.state.read((s) => [s.peerWrites.get(input.recordId), s.versions.has(input.recordId)])) as [
+    PeerWrite | undefined,
+    boolean,
+  ];
+  if (known?.kind === 'create' && !confirmed) {
+    // Deleting a row the same peer created and nobody confirmed: just undo it.
+    yield fx.timer.clear(`peer:${input.recordId}`);
+    yield* undoPeerCreate(table, input.recordId);
+    return true;
+  }
+  const exists = (yield* readBefore(parseRecordIdString(input.recordId))) !== null;
+  if (!exists) return false;
+  const now = (yield fx.now()) as number;
+  yield fx.state.update(R.setPeerWrite(input.recordId, { kind: 'delete', table, expiresAt: now + input.ttlMs }));
+  yield fx.timer.set(`peer:${input.recordId}`, input.ttlMs, { type: 'PeerWriteExpired', id: input.recordId });
+  return true;
+}
+
+/** Timer target: a peer's write stops showing as unconfirmed. */
+export function* peerWriteExpired(id: string): Saga<void> {
+  const [write, confirmed, ownPending] = (yield fx.state.read((s) => [
+    s.peerWrites.get(id),
+    s.versions.has(id),
+    s.outbox.some((i) => i.recordId === id),
+  ])) as [PeerWrite | undefined, boolean, boolean];
+  if (!write) return;
+  if (write.kind === 'create' && !confirmed && !ownPending) {
+    yield* undoPeerCreate(write.table, id);
+    return;
+  }
+  yield fx.state.update(R.clearPeerWrite(id));
+}
+
+function* undoPeerCreate(table: string, id: string): Saga<void> {
+  const rid = parseRecordIdString(id);
+  const before = yield* readBefore(rid);
+  try {
+    const tx = planPeerUndoTx(rid);
+    yield fx.local.execute(tx.query, tx.vars);
+    if (before) yield fx.ssp.ingest([{ table, op: 'DELETE', id, record: before }]);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'could not undo an unconfirmed peer create', data: { recordId: id, error } });
+  }
+  yield fx.state.update(R.clearPeerWrite(id));
+}

package/src/query/materialize.saga.test.ts

@@ -54,6 +54,18 @@ describe('materialize', () => {
     const l = await runPure(materialize('a'), { state: live, handlers: { 'local.select': (e: any) => e.plan.ids.map((id: any) => ({ id: `${id.table}:${id.id}` })) } });
     expect(l.state.queries.get('a')!.records).toEqual([{ id: 'thing:2' }]);
   });
+  it("cold: a peer's unconfirmed delete hides the row the store still holds", async () => {
+    const s = buildState(
+      [buildEntry({ def: { hash: 'a', plan } })],
+      vouch('thing:1', 'thing:2'),
+      R.setPeerWrite('thing:2', { kind: 'delete', table: 'thing', expiresAt: 1 })
+    );
+    const out = await runPure(materialize('a'), {
+      state: s,
+      handlers: { 'local.select': () => [{ id: 'thing:1' }, { id: 'thing:2' }, { name: 'no id' }] },
+    });
+    expect(out.state.queries.get('a')!.records).toEqual([{ id: 'thing:1' }, { name: 'no id' }]);
+  });
   it('cold window renders the SSP local window (orphans dropped); live renders membership with the overlay', async () => {
     const win = buildState(
       [buildEntry({ def: { hash: 'w', plan: { ...plan, offset: 5 }, surql: 'SELECT * FROM thing LIMIT 5 START 5' }, localArray: [['thing:7', 1], ['thing:8', 1]] })],

package/src/query/materialize.saga.ts

@@ -48,7 +48,13 @@ export function* materialize(hash: QueryHash): Saga<void> {
   let rows: Record<string, unknown>[];
   try {
     rows = rowsFromResult(effect, yield effect);
-    if (ids === null) rows = rows.filter((row) => paints(rowKey(row)));
+    // A peer's delete leaves the row in the store until it is confirmed, so
+    // the predicate scan must drop it here (an own delete removed it already).
+    if (ids === null)
+      rows = rows.filter((row) => {
+        const key = rowKey(row);
+        return paints(key) && !(key !== null && ov.deletes.has(key));
+      });
   } catch (error) {
     yield fx.state.update(R.compose(R.recordError(hash), R.clearDirty(hash)));
     yield fx.emit({ type: 'log', level: 'warn', message: 'materialize failed', data: { hash, error } });

package/src/state/client-state.ts

@@ -103,6 +103,18 @@ export interface PendingWrite {
   readonly mirrorId: string | null;
 }
 
+/**
+ * A create or delete a channel peer sent, applied here before the server has
+ * it (see `modules/channel`). Shown like an own optimistic write through the
+ * overlay; when `expiresAt` passes it is either confirmed (the server's body
+ * landed) or undone.
+ */
+export interface PeerWrite {
+  readonly kind: 'create' | 'delete';
+  readonly table: string;
+  readonly expiresAt: number;
+}
+
 export interface SyncSlice {
   readonly health: SyncHealth;
   readonly consecutiveFailures: number;
@@ -151,6 +163,8 @@ export interface ClientState {
   readonly views: ReadonlyMap<string, ReadonlyArray<string>>;
   readonly outbox: ReadonlyArray<OutboxItem>;
   readonly pendingWrites: ReadonlyMap<string, PendingWrite>;
+  /** Channel peers' unconfirmed creates and deletes, by record id. */
+  readonly peerWrites: ReadonlyMap<string, PeerWrite>;
   readonly failedCount: number;
   /** Queries whose render inputs changed since their last materialization. */
   readonly dirty: ReadonlySet<QueryHash>;
@@ -196,6 +210,7 @@ export function emptyState(init: { tabId: string }): ClientState {
     views: new Map(),
     outbox: [],
     pendingWrites: new Map(),
+    peerWrites: new Map(),
     failedCount: 0,
     dirty: new Set(),
     membershipDirty: new Set(),

package/src/state/reducers.test.ts

@@ -317,3 +317,21 @@ describe('durable view index', () => {
     expect(reloaded.views).toEqual(new Map([['va', ['t:new']], ['vb', ['t:b']], ['vc', ['t:c']]]));
   });
 });
+
+describe('peer writes', () => {
+  it('set and clear an entry, dirtying the queries of its table', () => {
+    const s0 = buildState([buildEntry({ def: { hash: 'q', tableName: 'thing' } })], R.clearDirty('q'));
+    const s1 = R.setPeerWrite('thing:1', { kind: 'create', table: 'thing', expiresAt: 5 })(s0);
+    expect(s1.peerWrites.get('thing:1')).toEqual({ kind: 'create', table: 'thing', expiresAt: 5 });
+    expect(s1.dirty.has('q')).toBe(true);
+    const s2 = R.clearPeerWrite('thing:1')(R.clearDirty('q')(s1));
+    expect(s2.peerWrites.size).toBe(0);
+    expect(s2.dirty.has('q')).toBe(true);
+    expect(R.clearPeerWrite('thing:9')(s2)).toBe(s2);
+  });
+
+  it('a bucket switch forgets them', () => {
+    const s = R.setPeerWrite('thing:1', { kind: 'delete', table: 'thing', expiresAt: 5 })(buildState());
+    expect(R.clearBucketState()(s).peerWrites.size).toBe(0);
+  });
+});

package/src/state/reducers.ts

@@ -2,6 +2,7 @@ import type { ConnectionState, QueryHash, RecordVersionArray, SyncHealth } from
 import type {
   ClientState,
   OutboxItem,
+  PeerWrite,
   PendingWrite,
   QueryEntry,
   QueryTelemetry,
@@ -375,6 +376,25 @@ export const outboxReplace =
     return next;
   };
 
+/** A channel peer's create or delete is now showing; its table re-renders. */
+export const setPeerWrite =
+  (id: string, write: PeerWrite): Reducer =>
+  (s) => {
+    const peerWrites = new Map(s.peerWrites);
+    peerWrites.set(id, write);
+    return markTableDirty(write.table)({ ...s, peerWrites });
+  };
+
+export const clearPeerWrite =
+  (id: string): Reducer =>
+  (s) => {
+    const write = s.peerWrites.get(id);
+    if (!write) return s;
+    const peerWrites = new Map(s.peerWrites);
+    peerWrites.delete(id);
+    return markTableDirty(write.table)({ ...s, peerWrites });
+  };
+
 export const outboxPush =
   (item: OutboxItem): Reducer =>
   (s) =>
@@ -505,6 +525,7 @@ export const clearBucketState = (): Reducer => (s) => ({
   views: new Map(),
   outbox: [],
   pendingWrites: new Map(),
+  peerWrites: new Map(),
   dirty: new Set(),
   membershipDirty: new Set(),
   membershipReread: new Map(),

package/src/state/selectors.test.ts

@@ -35,6 +35,21 @@ describe('overlay and outbox counts', () => {
   });
 });
 
+describe('overlay with channel peers', () => {
+  it('shows peer creates as writes and peer deletes as deletes', () => {
+    const s = buildState(
+      [],
+      R.setPeerWrite('thing:1', { kind: 'create', table: 'thing', expiresAt: 1 }),
+      R.setPeerWrite('thing:2', { kind: 'delete', table: 'thing', expiresAt: 1 })
+    );
+    const o = S.overlay(s);
+    expect([...o.writes]).toEqual(['thing:1']);
+    expect([...o.deletes]).toEqual(['thing:2']);
+    // Not an own write: nothing to push.
+    expect(S.pendingMutationCount(s)).toBe(0);
+  });
+});
+
 describe('needed / planFetch / settled', () => {
   const live = { phase: 'live' } as const;
   it('needed compares membership versions against local versions and skips pending deletes', () => {

package/src/state/selectors.ts

@@ -30,9 +30,9 @@ export const queryStatus = (s: ClientState, hash: QueryHash): QueryStatus | unde
 };
 
 export interface Overlay {
-  /** Ids with an unsynced or just-acked create/update. */
+  /** Ids with an unsynced or just-acked create/update (own, or a channel peer's create). */
   readonly writes: ReadonlySet<string>;
-  /** Ids with an unsynced or just-acked delete. */
+  /** Ids with an unsynced or just-acked delete (own, or a channel peer's). */
   readonly deletes: ReadonlySet<string>;
 }
 
@@ -44,6 +44,11 @@ export function overlay(s: ClientState): Overlay {
     if (item.type === 'delete') deletes.add(item.recordId);
     else writes.add(item.recordId);
   }
+  // Channel peers' writes show exactly like our own until confirmed or undone.
+  for (const [id, write] of s.peerWrites) {
+    if (write.kind === 'delete') deletes.add(id);
+    else writes.add(id);
+  }
   return { writes, deletes };
 }
 

package/src/types.ts

@@ -1,5 +1,6 @@
+import type { ChannelHandle, ChannelsConfig } from './modules/channel/index';
 import type { ImpersonationBannerConfig } from './modules/auth/impersonation-banner';
-import type { RecordId, SchemaStructure, QueryPlan } from '@spooky-sync/query-builder';
+import type { FinalQuery, GetTable, QueryBuilder, RecordId, SchemaStructure, QueryPlan, TableModel, TableNames } from '@spooky-sync/query-builder';
 import type { Level, LoggerOptions } from 'pino';
 import type { PushEventOptions } from './events/index';
 import type { LocalEngineChoice } from './services/database/cache-engine';
@@ -280,6 +281,14 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * out of apps that don't use collaboration. Defaults to `false`.
    */
   crdt?: boolean;
+  /**
+   * Peer to peer channels for `-- @channel` tables (see `.channel(peers)` on
+   * a query). `accept` holds the app's rules per table: which peer updates to
+   * apply. `iceServers` configures the default WebRTC transport (a public
+   * STUN server when omitted; add TURN for networks that block direct
+   * connections), `transport` replaces it.
+   */
+  channels?: ChannelsConfig;
   /**
    * Cadence (ms) for the `_00_list_ref` poll that catches cross-session
    * UPDATEs the SurrealDB v3 LIVE-permission gap drops. Lower = faster
@@ -891,3 +900,32 @@ export interface DebounceOptions {
    */
   flushOnHide?: boolean;
 }
+
+/** A query a channel takes its filter from: a builder or a built query, on a `-- @channel` table. */
+export type ChannelQuery<S extends SchemaStructure, T extends TableNames<S>> =
+  | QueryBuilder<S, T, any, any, any>
+  | FinalQuery<S, T, any, any, any, any>;
+
+/**
+ * An open peer to peer channel (`client.channel(queries, peers)`): its
+ * state, plus writes that go to ITS peers only (when the row matches its
+ * filter). Plain `create` / `update` / `delete` reach the peers of every
+ * open channel whose filter the row matches.
+ */
+export interface Sp00kyChannel<S extends SchemaStructure, T extends string> extends Omit<ChannelHandle, 'tables' | 'setScopes'> {
+  /** The tables its queries read. */
+  tables(): ReadonlyArray<T>;
+  /** Replace the queries (their filters changed). */
+  setQueries(queries: ChannelQuery<S, T & TableNames<S>> | ReadonlyArray<ChannelQuery<S, T & TableNames<S>>>): void;
+  update<N extends T>(
+    table: N,
+    id: string,
+    data: Partial<TableModel<GetTable<S, N & TableNames<S>>>>,
+    options?: UpdateOptions
+  ): Promise<Partial<TableModel<GetTable<S, N & TableNames<S>>>>>;
+  create<N extends T>(
+    id: `${N}:${string}`,
+    data: Partial<TableModel<GetTable<S, N & TableNames<S>>>>
+  ): Promise<Partial<TableModel<GetTable<S, N & TableNames<S>>>>>;
+  delete<N extends T>(table: N, id: string): Promise<void>;
+}