@spooky-sync/core 0.0.1-canary.13 → 0.0.1-canary.131

package/src/modules/sync/scheduler.ts

@@ -1,5 +1,5 @@
-import { Logger } from '../../services/logger/index';
-import { UpQueue, DownQueue, DownEvent, UpEvent, RollbackCallback } from './queue/index';
+import type { Logger } from '../../services/logger/index';
+import type { UpQueue, DownQueue, DownEvent, UpEvent, RollbackCallback } from './queue/index';
 import { SyncQueueEventTypes } from './events/index';
 
 /**
@@ -9,6 +9,8 @@ import { SyncQueueEventTypes } from './events/index';
 export class SyncScheduler {
   private isSyncingUp: boolean = false;
   private isSyncingDown: boolean = false;
+  private paused: boolean = false;
+  private pauseWaiters: Array<() => void> = [];
 
   constructor(
     private upQueue: UpQueue,
@@ -16,7 +18,12 @@ export class SyncScheduler {
     private onProcessUp: (event: UpEvent) => Promise<void>,
     private onProcessDown: (event: DownEvent) => Promise<void>,
     private logger: Logger,
-    private onRollback?: RollbackCallback
+    private onRollback?: RollbackCallback,
+    // Reports the outcome of each drained sync round (one syncUp/syncDown pass
+    // that actually processed ≥1 item): `ok=true` on a clean drain, `ok=false`
+    // with the error when the round halted on a failure. Drives the consumer's
+    // sync-health tracking; empty/no-op rounds report nothing.
+    private onSyncOutcome?: (ok: boolean, error?: unknown) => void
   ) {}
 
   async init() {
@@ -44,18 +51,60 @@ export class SyncScheduler {
     this.downQueue.push(event);
   }
 
+  /**
+   * Suspend syncing for a local-bucket switch. Refuses new rounds and resolves
+   * once any in-flight round has finished — the pause point is BETWEEN queue
+   * items, never between an item's remote push and its outbox-row delete, so a
+   * processed mutation's `DELETE _00_pending_mutations` always lands in the
+   * store it was read from.
+   */
+  pause(): Promise<void> {
+    this.paused = true;
+    if (!this.isSyncingUp && !this.isSyncingDown) return Promise.resolve();
+    return new Promise<void>((resolve) => this.pauseWaiters.push(resolve));
+  }
+
+  resume(): void {
+    this.paused = false;
+    void this.syncUp();
+  }
+
+  private maybeResolvePause() {
+    if (!this.paused || this.isSyncingUp || this.isSyncingDown) return;
+    const waiters = this.pauseWaiters;
+    this.pauseWaiters = [];
+    for (const resolve of waiters) resolve();
+  }
+
   /**
    * Process upload queue
    */
   async syncUp() {
-    if (this.isSyncingUp) return;
+    if (this.isSyncingUp || this.paused) return;
     this.isSyncingUp = true;
+    let processedAny = false;
     try {
-      while (this.upQueue.size > 0) {
+      while (this.upQueue.size > 0 && !this.paused) {
         await this.upQueue.next(this.onProcessUp, this.onRollback);
+        processedAny = true;
       }
+      if (processedAny) this.onSyncOutcome?.(true);
+    } catch (error) {
+      this.onSyncOutcome?.(false, error);
+      // syncUp runs fire-and-forget — it's wired to the MutationEnqueued event
+      // (broadcast synchronously, return value dropped) and is also kicked off
+      // via `void this.syncDown()` below. A rejection escaping here therefore
+      // surfaces as an *unhandled promise rejection* in the console rather than
+      // anything a caller can catch. UpQueue.next already logs the failing item
+      // (and re-queues it for retry on the next trigger), so swallow here to
+      // keep the failure contained instead of leaking it globally.
+      this.logger.debug(
+        { error, Category: 'sp00ky-client::SyncScheduler::syncUp' },
+        'syncUp halted on a queue error; item re-queued, will retry on next trigger'
+      );
     } finally {
       this.isSyncingUp = false;
+      this.maybeResolvePause();
       void this.syncDown();
     }
   }
@@ -64,17 +113,34 @@ export class SyncScheduler {
    * Process download queue
    */
   async syncDown() {
-    if (this.isSyncingDown) return;
+    if (this.isSyncingDown || this.paused) return;
     if (this.upQueue.size > 0) return;
 
     this.isSyncingDown = true;
+    let processedAny = false;
     try {
-      while (this.downQueue.size > 0) {
+      while (this.downQueue.size > 0 && !this.paused) {
         if (this.upQueue.size > 0) break;
         await this.downQueue.next(this.onProcessDown);
+        processedAny = true;
       }
+      if (processedAny) this.onSyncOutcome?.(true);
+    } catch (error) {
+      this.onSyncOutcome?.(false, error);
+      // Same fire-and-forget story as syncUp: this is the QueryItemEnqueued
+      // subscriber (and is also called via `void this.syncDown()`), so a thrown
+      // error here becomes an unhandled rejection. The canonical case is a
+      // transient remote 500 on `fn::query::register` — DownQueue.next logs it
+      // and re-queues the event at the head; we just stop draining this pass and
+      // let the next enqueue retry, without spamming the console with an
+      // "Uncaught (in promise) ... 500 Internal Server Error".
+      this.logger.debug(
+        { error, Category: 'sp00ky-client::SyncScheduler::syncDown' },
+        'syncDown halted on a queue error; item re-queued, will retry on next trigger'
+      );
     } finally {
       this.isSyncingDown = false;
+      this.maybeResolvePause();
     }
   }
 

package/src/modules/sync/sync.health.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Sp00kySync } from './sync';
+
+// The idle list-ref poll is the only health signal that runs on a quiet page.
+// These tests exercise `pollListRefForActiveQueries` -> `recordSyncOutcome` in
+// isolation: a run of network-failed cycles degrades, and a single clean cycle
+// recovers WITHOUT any mutation (the reported bug). Construction is cheap —
+// Sp00kySync's constructor only stores refs and calls logger.child; no timers or
+// I/O start until init(), which we never call.
+
+const CONNECTION_UNAVAILABLE =
+  'You must be connected to a SurrealDB instance before performing this operation';
+
+function makeSync(hashes: string[]) {
+  const logger: any = {
+    child: () => logger,
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    trace: () => {},
+  };
+  const remote: any = { query: vi.fn().mockResolvedValue([true]) };
+  const dataModule: any = { getActiveQueryHashes: () => hashes };
+
+  const sync = new Sp00kySync(
+    {} as any,
+    remote,
+    {} as any,
+    dataModule,
+    {} as any,
+    logger,
+    { degradeAfterConsecutiveFailures: 3 }
+  );
+
+  // `refetchListRefForQuery` is what the poll calls per active hash; stub it so
+  // the test controls per-cycle reachability. `poll` invokes the private method.
+  const refetch = vi.fn();
+  (sync as any).refetchListRefForQuery = refetch;
+  const poll = () => (sync as any).pollListRefForActiveQueries() as Promise<boolean>;
+
+  return { sync, remote, refetch, poll };
+}
+
+describe('sync health via idle poll', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('degrades after N consecutive network-failed poll cycles', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+    expect(sync.syncHealth.kind).toBe('network');
+  });
+
+  it('recovers on the next clean poll cycle — no mutation needed', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+
+    // Connectivity returns; a plain idle poll (no user action) clears it.
+    refetch.mockResolvedValue(true);
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+  });
+
+  it('does not degrade on application errors (server was reached)', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+    refetch.mockRejectedValue(new Error('Permission denied'));
+    await poll();
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+  });
+
+  it('counts a mixed cycle (one reachable hash) as reached', async () => {
+    const { sync, refetch, poll } = makeSync(['h1', 'h2']);
+    // First degrade via all-network cycles.
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+
+    // Now one hash succeeds, the other still network-fails → reached → healthy.
+    refetch.mockReset();
+    refetch
+      .mockResolvedValueOnce(true)
+      .mockRejectedValueOnce(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+  });
+
+  it('probes RETURN true when there are no active queries', async () => {
+    const { sync, remote, poll } = makeSync([]);
+    remote.query.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(remote.query).toHaveBeenCalledWith('RETURN true');
+    expect(sync.syncHealth.status).toBe('degraded');
+
+    remote.query.mockResolvedValue([true]);
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+  });
+
+  it('leaves everConnected false through a cold-start failure run', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+    expect(sync.syncHealth.everConnected).toBe(false);
+
+    // Server never reached: 3 failed cycles degrade, but this is the initial
+    // "connecting" phase, not a lost connection — everConnected stays false.
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+    expect(sync.syncHealth.everConnected).toBe(false);
+  });
+
+  it('latches everConnected on the first success and keeps it through a later degrade', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+
+    // First successful round reaches the server: connecting phase is over.
+    refetch.mockResolvedValue(true);
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+    expect(sync.syncHealth.everConnected).toBe(true);
+
+    // Connection later drops: degraded now reflects a REAL lost connection.
+    refetch.mockReset();
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+    expect(sync.syncHealth.everConnected).toBe(true);
+  });
+});

package/src/modules/sync/sync.subquery.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { Sp00kySync } from './sync';
+import { buildSubqueryListRefSelect } from './utils';
+import { encodeRecordId } from '../../utils/index';
+
+// Guards the CLIENT half of `.related()` (author/comments) delivery: given
+// subquery-child edges on the server (`_00_list_ref…` rows with
+// `parent IS NOT NONE`), `syncSubqueryChildren` MUST pull the child bodies
+// through the sync engine so a later re-materialization attaches them to the
+// parent. If this stops forwarding the child ids, related fields come back
+// empty (threads render with an "Anonymous" author, comments vanish) even
+// though the server wrote the edges correctly.
+
+function makeSync() {
+  const logger: any = {
+    child: () => logger,
+    debug: () => {}, info: () => {}, warn: () => {}, error: () => {}, trace: () => {},
+  };
+  const remote: any = { query: vi.fn() };
+  const queryId = new RecordId('_00_query', 'h1');
+  const queryState: any = { config: { id: queryId, subqueryRemoteArray: [] } };
+  const dataModule: any = { getQueryByHash: vi.fn().mockReturnValue(queryState) };
+
+  const sync = new Sp00kySync(
+    {} as any, remote, {} as any, dataModule, {} as any, logger,
+  );
+
+  // syncEngine is constructed internally; replace it with a spy.
+  const syncRecords = vi.fn().mockResolvedValue(undefined);
+  (sync as any).syncEngine = { syncRecords };
+  // Pin the resolved per-user list_ref table (auth routing is out of scope here).
+  (sync as any).listRefTable = () => '_00_list_ref_user_x';
+
+  const run = (hash: string) => (sync as any).syncSubqueryChildren(hash) as Promise<void>;
+  return { remote, syncRecords, queryState, queryId, run };
+}
+
+describe('syncSubqueryChildren — related-child delivery', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('reads the subquery edges (parent IS NOT NONE) scoped to the query id', async () => {
+    const { remote, run, queryId } = makeSync();
+    remote.query.mockResolvedValue([[]]);
+
+    await run('h1');
+
+    expect(remote.query).toHaveBeenCalledWith(
+      buildSubqueryListRefSelect('_00_list_ref_user_x'),
+      { in: queryId }
+    );
+  });
+
+  it('forwards each subquery child id to the sync engine so its body is cached', async () => {
+    const { remote, syncRecords, run } = makeSync();
+    // Server has one author child edge for this query.
+    remote.query.mockResolvedValue([[
+      { out: new RecordId('user', 'u'), version: 1 },
+    ]]);
+
+    await run('h1');
+
+    expect(syncRecords).toHaveBeenCalledTimes(1);
+    const arg = syncRecords.mock.calls[0][0];
+    expect(arg.added).toHaveLength(1);
+    expect(encodeRecordId(arg.added[0].id)).toBe('user:u');
+    expect(arg.added[0].version).toBe(1);
+    expect(arg.removed).toEqual([]); // shared child bodies are never deleted here
+  });
+
+  it('is idempotent: unchanged edges do not refetch bodies', async () => {
+    const { remote, syncRecords, run, queryState } = makeSync();
+    queryState.config.subqueryRemoteArray = [['user:u', 1]];
+    remote.query.mockResolvedValue([[
+      { out: new RecordId('user', 'u'), version: 1 },
+    ]]);
+
+    await run('h1');
+
+    expect(syncRecords).not.toHaveBeenCalled();
+  });
+});