@syncular/relay 0.0.1 → 0.0.2-126

package/src/__tests__/relay.test.ts

@@ -4,6 +4,8 @@
 
 import Database from 'bun:sqlite';
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import type { SyncCombinedRequest, SyncCombinedResponse } from '@syncular/core';
+import { TableRegistry } from '@syncular/server';
 import { createSqliteServerDialect } from '@syncular/server-dialect-sqlite';
 import type { Dialect, QueryResult } from 'kysely';
 import {
@@ -11,12 +13,16 @@ import {
   SqliteAdapter,
   SqliteIntrospector,
   SqliteQueryCompiler,
+  sql,
 } from 'kysely';
+import { PullEngine } from '../client-role/pull-engine';
 import { SequenceMapper } from '../client-role/sequence-mapper';
 import { ensureRelaySchema } from '../migrate';
 import { ModeManager, type RelayMode } from '../mode-manager';
 import { createRelayWebSocketConnection, RelayRealtime } from '../realtime';
+import { RelayServer } from '../relay';
 import type { RelayDatabase } from '../schema';
+import { relayPushCommit } from '../server-role/push';
 
 // Helper to create in-memory SQLite database
 function createTestDb() {
@@ -133,6 +139,317 @@ describe('ModeManager', () => {
     manager.reportSuccess();
     expect(manager.getMode()).toBe('online');
   });
+
+  it('should transition from offline to reconnecting on initial failure', async () => {
+    const manager = new ModeManager({
+      healthCheckIntervalMs: 100,
+      reconnectBackoffMs: 50,
+    });
+
+    manager.start(async () => false);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(manager.getMode()).toBe('reconnecting');
+    manager.stop();
+  });
+});
+
+describe('RelayServer health check', () => {
+  let db: Kysely<RelayDatabase>;
+  let sqlite: Database;
+
+  beforeEach(() => {
+    const setup = createTestDb();
+    db = setup.db;
+    sqlite = setup.sqlite;
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+    sqlite.close();
+  });
+
+  it('uses a protocol-valid pull limit during startup health checks', async () => {
+    const syncCalls: SyncCombinedRequest[] = [];
+    const mainServerTransport = {
+      async sync(request: SyncCombinedRequest): Promise<SyncCombinedResponse> {
+        syncCalls.push(request);
+        return {};
+      },
+      async fetchSnapshotChunk(): Promise<Uint8Array> {
+        return new Uint8Array();
+      },
+    };
+
+    const relay = new RelayServer({
+      db,
+      dialect: createSqliteServerDialect(),
+      mainServerTransport,
+      mainServerClientId: 'relay-main-client',
+      mainServerActorId: 'relay-main-actor',
+      tables: [],
+      scopes: {},
+      handlers: new TableRegistry<RelayDatabase>(),
+      healthCheckIntervalMs: 50,
+      pullIntervalMs: 10_000,
+      forwardRetryIntervalMs: 10_000,
+      pruneIntervalMs: 0,
+    });
+
+    await relay.start();
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    await relay.stop();
+
+    expect(
+      syncCalls.some(
+        (request) =>
+          request.pull?.subscriptions.length === 0 &&
+          request.pull.limitCommits === 1
+      )
+    ).toBe(true);
+  });
+});
+
+describe('relayPushCommit atomic enqueue', () => {
+  let db: Kysely<RelayDatabase>;
+  let sqlite: Database;
+
+  beforeEach(async () => {
+    const setup = createTestDb();
+    db = setup.db;
+    sqlite = setup.sqlite;
+    await ensureRelaySchema(db, createSqliteServerDialect());
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+    sqlite.close();
+  });
+
+  it('rolls back local commit when forwarding enqueue fails', async () => {
+    const now = Date.now();
+    await sql`
+      insert into ${sql.table('relay_forward_outbox')} (
+        id,
+        local_commit_seq,
+        client_id,
+        client_commit_id,
+        operations_json,
+        schema_version,
+        status,
+        main_commit_seq,
+        error,
+        last_response_json,
+        created_at,
+        updated_at,
+        attempt_count
+      )
+      values (
+        ${'fixed-outbox-id'},
+        ${999},
+        ${'seed-client'},
+        ${'seed-commit'},
+        ${'[]'},
+        ${1},
+        ${'pending'},
+        ${null},
+        ${null},
+        ${null},
+        ${now},
+        ${now},
+        ${0}
+      )
+    `.execute(db);
+
+    const handlers = new TableRegistry<RelayDatabase>();
+    handlers.register({
+      table: 'tasks',
+      scopePatterns: ['user:{user_id}'],
+      resolveScopes: async () => ({ user_id: ['u1'] }),
+      extractScopes: () => ({ user_id: 'u1' }),
+      snapshot: async () => ({ rows: [], nextCursor: null }),
+      async applyOperation(_ctx, op, opIndex) {
+        return {
+          result: {
+            opIndex,
+            status: 'applied',
+          },
+          emittedChanges: [
+            {
+              table: 'tasks',
+              row_id: op.row_id,
+              op: op.op,
+              row_json: op.payload,
+              row_version: 1,
+              scopes: { user_id: 'u1' },
+            },
+          ],
+        };
+      },
+    });
+
+    const originalRandomUUID = crypto.randomUUID;
+    crypto.randomUUID = () => 'fixed-outbox-id';
+    try {
+      await expect(
+        relayPushCommit({
+          db,
+          dialect: createSqliteServerDialect(),
+          handlers,
+          actorId: 'u1',
+          request: {
+            clientId: 'relay-client-1',
+            clientCommitId: 'relay-commit-1',
+            schemaVersion: 1,
+            operations: [
+              {
+                table: 'tasks',
+                row_id: 'task-1',
+                op: 'upsert',
+                payload: { id: 'task-1', title: 'hello' },
+                base_version: null,
+              },
+            ],
+          },
+        })
+      ).rejects.toThrow();
+    } finally {
+      crypto.randomUUID = originalRandomUUID;
+    }
+
+    const commitRows = await sql<{ count: number | bigint }>`
+      select count(*) as count
+      from ${sql.table('sync_commits')}
+      where ${sql.ref('client_id')} = ${'relay-client-1'}
+        and ${sql.ref('client_commit_id')} = ${'relay-commit-1'}
+    `.execute(db);
+    expect(Number(commitRows.rows[0]?.count ?? 0)).toBe(0);
+  });
+});
+
+describe('PullEngine cursor safety', () => {
+  let db: Kysely<RelayDatabase>;
+  let sqlite: Database;
+
+  beforeEach(async () => {
+    const setup = createTestDb();
+    db = setup.db;
+    sqlite = setup.sqlite;
+    await ensureRelaySchema(db, createSqliteServerDialect());
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+    sqlite.close();
+  });
+
+  it('does not advance cursor when a pulled commit is rejected locally', async () => {
+    const syncCalls: SyncCombinedRequest[] = [];
+    const transport = {
+      async sync(request: SyncCombinedRequest): Promise<SyncCombinedResponse> {
+        syncCalls.push(request);
+        return {
+          pull: {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'tasks',
+                status: 'active',
+                scopes: {},
+                bootstrap: false,
+                nextCursor: 25,
+                commits: [
+                  {
+                    commitSeq: 25,
+                    createdAt: new Date(0).toISOString(),
+                    actorId: 'main-actor',
+                    changes: [
+                      {
+                        table: 'tasks',
+                        row_id: 'task-1',
+                        op: 'upsert',
+                        row_json: { id: 'task-1', title: 'from-main' },
+                        row_version: 1,
+                        scopes: {},
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        };
+      },
+      async fetchSnapshotChunk(): Promise<Uint8Array> {
+        return new Uint8Array();
+      },
+    };
+
+    const handlers = new TableRegistry<RelayDatabase>();
+    handlers.register({
+      table: 'tasks',
+      scopePatterns: ['user:{user_id}'],
+      resolveScopes: async () => ({}),
+      extractScopes: () => ({}),
+      snapshot: async () => ({ rows: [], nextCursor: null }),
+      async applyOperation(_ctx, _op, opIndex) {
+        return {
+          result: {
+            opIndex,
+            status: 'conflict',
+            message: 'reject locally',
+            server_version: 1,
+            server_row: {},
+          },
+          emittedChanges: [],
+        };
+      },
+    });
+
+    const pullErrors: Error[] = [];
+    const pullEngine = new PullEngine({
+      db,
+      dialect: createSqliteServerDialect(),
+      transport,
+      clientId: 'relay-client',
+      tables: ['tasks'],
+      scopes: {},
+      handlers,
+      sequenceMapper: new SequenceMapper({ db }),
+      realtime: new RelayRealtime({ heartbeatIntervalMs: 0 }),
+      onError: (error) => pullErrors.push(error),
+    });
+
+    await pullEngine.pullOnce();
+    await pullEngine.pullOnce();
+
+    expect(pullErrors.length).toBe(2);
+    expect(syncCalls.length).toBe(2);
+    expect(syncCalls[0]?.pull?.subscriptions[0]?.cursor).toBe(-1);
+    expect(syncCalls[1]?.pull?.subscriptions[0]?.cursor).toBe(-1);
+
+    const rowResult = await sql<{ value_json: string }>`
+      select value_json
+      from ${sql.table('relay_config')}
+      where key = 'main_cursors'
+      limit 1
+    `.execute(db);
+    const row = rowResult.rows[0];
+
+    const cursorState: Record<string, number> = {};
+    if (row?.value_json) {
+      const parsed = JSON.parse(row.value_json);
+      if (typeof parsed === 'object' && parsed !== null) {
+        for (const [key, value] of Object.entries(parsed)) {
+          if (typeof value === 'number') {
+            cursorState[key] = value;
+          }
+        }
+      }
+    }
+
+    expect(cursorState.tasks).toBeUndefined();
+  });
 });
 
 describe('RelayRealtime', () => {

package/src/client-role/forward-engine.ts

@@ -10,6 +10,7 @@ import type {
   SyncPushResponse,
   SyncTransport,
 } from '@syncular/core';
+import { randomId } from '@syncular/core';
 import type { Kysely } from 'kysely';
 import { sql } from 'kysely';
 import type {
@@ -20,16 +21,6 @@ import type {
 } from '../schema';
 import type { SequenceMapper } from './sequence-mapper';
 
-function randomId(): string {
-  if (
-    typeof crypto !== 'undefined' &&
-    typeof crypto.randomUUID === 'function'
-  ) {
-    return crypto.randomUUID();
-  }
-  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
-}
-
 /**
  * Forward engine options.
  */
@@ -140,12 +131,18 @@ export class ForwardEngine<DB extends RelayDatabase = RelayDatabase> {
 
     let response: SyncPushResponse;
     try {
-      response = await this.transport.push({
+      const combined = await this.transport.sync({
         clientId: next.client_id,
-        clientCommitId: next.client_commit_id,
-        operations: next.operations,
-        schemaVersion: next.schema_version,
+        push: {
+          clientCommitId: next.client_commit_id,
+          operations: next.operations,
+          schemaVersion: next.schema_version,
+        },
       });
+      if (!combined.push) {
+        throw new Error('Server returned no push response');
+      }
+      response = combined.push;
     } catch (err) {
       // Network error - mark as pending for retry
       await this.markPending(next.id, String(err));

package/src/client-role/pull-engine.ts

@@ -31,7 +31,7 @@ export interface PullEngineOptions<DB extends RelayDatabase = RelayDatabase> {
   tables: string[];
   /** Scope values for subscriptions */
   scopes: ScopeValues;
-  shapes: TableRegistry<DB>;
+  handlers: TableRegistry<DB>;
   sequenceMapper: SequenceMapper<DB>;
   realtime: RelayRealtime;
   intervalMs?: number;
@@ -49,7 +49,7 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
   private readonly clientId: string;
   private readonly tables: string[];
   private readonly scopes: ScopeValues;
-  private readonly shapes: TableRegistry<DB>;
+  private readonly handlers: TableRegistry<DB>;
   private readonly sequenceMapper: SequenceMapper<DB>;
   private readonly realtime: RelayRealtime;
   private readonly intervalMs: number;
@@ -67,7 +67,7 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
     this.clientId = options.clientId;
     this.tables = options.tables;
     this.scopes = options.scopes;
-    this.shapes = options.shapes;
+    this.handlers = options.handlers;
     this.sequenceMapper = options.sequenceMapper;
     this.realtime = options.realtime;
     this.intervalMs = options.intervalMs ?? 10000;
@@ -81,9 +81,17 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
   start(): void {
     if (this.running) return;
     this.running = true;
-    this.loadCursors().then(() => {
-      this.scheduleNext(0);
-    });
+    void this.loadCursors()
+      .catch((error) => {
+        this.onError?.(
+          error instanceof Error ? error : new Error(String(error))
+        );
+      })
+      .finally(() => {
+        if (this.running) {
+          this.scheduleNext(0);
+        }
+      });
   }
 
   /**
@@ -169,7 +177,7 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
     const subscriptionRequests: SyncSubscriptionRequest[] = this.tables.map(
       (table) => ({
         id: table,
-        shape: table,
+        table,
         scopes: this.scopes,
         cursor: this.cursors.get(table) ?? -1,
       })
@@ -177,11 +185,17 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
 
     let response: SyncPullResponse;
     try {
-      response = await this.transport.pull({
+      const combined = await this.transport.sync({
         clientId: this.clientId,
-        subscriptions: subscriptionRequests,
-        limitCommits: 100,
+        pull: {
+          subscriptions: subscriptionRequests,
+          limitCommits: 100,
+        },
       });
+      if (!combined.pull) {
+        return false;
+      }
+      response = combined.pull;
     } catch {
       // Network error - will retry
       return false;
@@ -200,16 +214,24 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
       const table = sub.id;
 
       // Process commits
+      let canAdvanceCursor = true;
       for (const commit of sub.commits) {
-        const applied = await this.applyCommitLocally(commit, table);
-        if (applied) {
+        const outcome = await this.applyCommitLocally(commit, table);
+        if (outcome === 'applied') {
           hasChanges = true;
           affectedTables.add(table);
         }
+        if (outcome === 'rejected') {
+          canAdvanceCursor = false;
+          break;
+        }
       }
 
       // Update cursor
-      if (sub.nextCursor > (this.cursors.get(table) ?? -1)) {
+      if (
+        canAdvanceCursor &&
+        sub.nextCursor > (this.cursors.get(table) ?? -1)
+      ) {
         this.cursors.set(table, sub.nextCursor);
       }
     }
@@ -232,14 +254,14 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
   /**
    * Apply a commit from main server locally.
    *
-   * This re-applies the commit through the local shape handlers
+   * This re-applies the commit through the local table handlers
    * to ensure proper indexing and scope assignment.
    */
   private async applyCommitLocally(
     commit: SyncCommit,
     table: string
-  ): Promise<boolean> {
-    if (commit.changes.length === 0) return false;
+  ): Promise<'applied' | 'cached' | 'rejected'> {
+    if (commit.changes.length === 0) return 'cached';
 
     // Convert changes to operations
     const operations = commit.changes.map((change) => ({
@@ -256,7 +278,7 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
     const result = await pushCommit({
       db: this.db,
       dialect: this.dialect,
-      shapes: this.shapes,
+      handlers: this.handlers,
       actorId: commit.actorId,
       request: {
         clientId: `relay:${this.clientId}`,
@@ -276,20 +298,24 @@ export class PullEngine<DB extends RelayDatabase = RelayDatabase> {
         result.response.commitSeq,
         commit.commitSeq
       );
-      return true;
+      return 'applied';
     }
 
     // Already applied (cached) - that's fine
     if (result.response.status === 'cached') {
-      return false;
+      return 'cached';
     }
 
     // Rejected - this shouldn't happen for pulls from main
-    // Log but don't fail
+    // Do not advance cursor; signal error so caller can react.
+    const error = new Error(
+      `Relay: Failed to apply commit ${commit.commitSeq} locally (status=${result.response.status})`
+    );
     console.warn(
       `Relay: Failed to apply commit ${commit.commitSeq} locally:`,
       result.response
     );
-    return false;
+    this.onError?.(error);
+    return 'rejected';
   }
 }

package/src/index.ts

@@ -16,12 +16,12 @@
  *   mainServerClientId: 'relay-branch-001',
  *   mainServerActorId: 'relay-service',
  *   scopeKeys: ['client:acme'],
- *   shapes: shapeRegistry,
+ *   handlers: shapeRegistry,
  *   subscriptions: subscriptionRegistry,
  * });
  *
  * // Mount routes for local clients
- * app.route('/sync', relay.getRoutes());
+ * app.route('/sync', await relay.getRoutes());
  *
  * // Start background sync with main
  * await relay.start();

package/src/mode-manager.ts

@@ -94,7 +94,7 @@ export class ModeManager {
   reportFailure(): void {
     this.consecutiveFailures++;
 
-    if (this.mode === 'online') {
+    if (this.mode !== 'reconnecting') {
       this.setMode('reconnecting');
     }
 

package/src/relay.ts

@@ -48,8 +48,8 @@ export interface RelayServerOptions<DB extends RelayDatabase = RelayDatabase> {
   tables: string[];
   /** Scope values for subscriptions to the main server */
   scopes: ScopeValues;
-  /** Shape registry for handling operations */
-  shapes: TableRegistry<DB>;
+  /** Handler registry for handling operations */
+  handlers: TableRegistry<DB>;
   /** Optional: WebSocket heartbeat interval in milliseconds (default: 30000) */
   heartbeatIntervalMs?: number;
   /** Optional: Forward engine retry interval in milliseconds (default: 5000) */
@@ -91,11 +91,11 @@ type EventHandler<K extends keyof RelayEvents> = RelayEvents[K];
  *   mainServerActorId: 'relay-service',
  *   tables: ['tasks', 'projects'],
  *   scopes: { project_id: 'acme' },
- *   shapes: shapeRegistry,
+ *   handlers: shapeRegistry,
  * });
  *
  * // Mount routes for local clients
- * app.route('/sync', relay.getRoutes());
+ * app.route('/sync', await relay.getRoutes());
  *
  * // Start background sync with main
  * await relay.start();
@@ -113,7 +113,7 @@ export class RelayServer<DB extends RelayDatabase = RelayDatabase> {
   private readonly mainServerActorId: string;
   private readonly tables: string[];
   private readonly scopes: ScopeValues;
-  private readonly shapes: TableRegistry<DB>;
+  private readonly handlers: TableRegistry<DB>;
 
   private readonly modeManager: ModeManager;
   private readonly sequenceMapper: SequenceMapper<DB>;
@@ -134,6 +134,7 @@ export class RelayServer<DB extends RelayDatabase = RelayDatabase> {
   private started = false;
   private schemaInitialized = false;
   private routes: Hono | null = null;
+  private routesPromise: Promise<Hono> | null = null;
 
   constructor(options: RelayServerOptions<DB>) {
     this.db = options.db;
@@ -143,7 +144,7 @@ export class RelayServer<DB extends RelayDatabase = RelayDatabase> {
     this.mainServerActorId = options.mainServerActorId;
     this.tables = options.tables;
     this.scopes = options.scopes;
-    this.shapes = options.shapes;
+    this.handlers = options.handlers;
 
     this.pruneIntervalMs = options.pruneIntervalMs ?? 3600000;
     this.pruneMaxAgeMs = options.pruneMaxAgeMs ?? 7 * 24 * 60 * 60 * 1000;
@@ -183,7 +184,7 @@ export class RelayServer<DB extends RelayDatabase = RelayDatabase> {
       clientId: this.mainServerClientId,
       tables: this.tables,
       scopes: this.scopes,
-      shapes: this.shapes,
+      handlers: this.handlers,
       sequenceMapper: this.sequenceMapper,
       realtime: this.realtime,
       intervalMs: options.pullIntervalMs ?? 10000,
@@ -264,10 +265,12 @@ export class RelayServer<DB extends RelayDatabase = RelayDatabase> {
     this.modeManager.start(async () => {
       // Health check: try an empty pull
       try {
-        await this.mainServerTransport.pull({
+        await this.mainServerTransport.sync({
           clientId: this.mainServerClientId,
-          subscriptions: [],
-          limitCommits: 0,
+          pull: {
+            subscriptions: [],
+            limitCommits: 1,
+          },
         });
         return true;
       } catch {
@@ -370,28 +373,30 @@ export class RelayServer<DB extends RelayDatabase = RelayDatabase> {
    * - POST /push
    * - GET /realtime (WebSocket)
    */
-  getRoutes(): Hono {
+  async getRoutes(): Promise<Hono> {
     if (this.routes) return this.routes;
+    if (this.routesPromise) return this.routesPromise;
+
+    this.routesPromise = (async () => {
+      const { createRelayRoutes } = await import('./server-role');
+
+      const routes = createRelayRoutes({
+        db: this.db,
+        dialect: this.dialect,
+        handlers: this.handlers,
+        realtime: this.realtime,
+        onCommit: async (localCommitSeq: number, affectedTables: string[]) => {
+          this.realtime.notifyScopeKeys(affectedTables, localCommitSeq);
+          this.forwardEngine.wakeUp();
+        },
+      });
+
+      this.routes = routes;
+      this.routesPromise = null;
+      return routes;
+    })();
 
-    // Lazy import to avoid requiring hono as a hard dependency
-    const { createRelayRoutes } = require('./server-role');
-
-    const routes = createRelayRoutes({
-      db: this.db,
-      dialect: this.dialect,
-      shapes: this.shapes,
-      realtime: this.realtime,
-      onCommit: async (localCommitSeq: number, affectedTables: string[]) => {
-        // Notify local clients via WebSocket
-        this.realtime.notifyScopeKeys(affectedTables, localCommitSeq);
-
-        // Wake up forward engine to send to main
-        this.forwardEngine.wakeUp();
-      },
-    });
-
-    this.routes = routes;
-    return routes;
+    return this.routesPromise;
   }
 
   private emit<K extends keyof RelayEvents>(