@syncular/relay 0.0.1-60

package/src/client-role/sequence-mapper.ts

@@ -0,0 +1,201 @@
+/**
+ * @syncular/relay - Sequence Mapper
+ *
+ * Tracks the mapping between relay's local commit_seq
+ * and the main server's global commit_seq.
+ */
+
+import { type Kysely, sql } from 'kysely';
+import type { RelayDatabase, RelaySequenceMapStatus } from '../schema';
+
+/**
+ * Sequence mapping entry.
+ */
+export interface SequenceMapping {
+  localCommitSeq: number;
+  mainCommitSeq: number | null;
+  status: RelaySequenceMapStatus;
+}
+
+/**
+ * Sequence mapper for tracking local to main commit sequence mappings.
+ */
+export class SequenceMapper<DB extends RelayDatabase = RelayDatabase> {
+  private readonly db: Kysely<DB>;
+
+  constructor(options: { db: Kysely<DB> }) {
+    this.db = options.db;
+  }
+
+  /**
+   * Create a pending mapping for a local commit that will be forwarded.
+   */
+  async createPendingMapping(localCommitSeq: number): Promise<void> {
+    const now = Date.now();
+    await sql`
+      insert into ${sql.table('relay_sequence_map')} (
+        local_commit_seq,
+        main_commit_seq,
+        status,
+        created_at,
+        updated_at
+      )
+      values (${localCommitSeq}, ${null}, 'pending', ${now}, ${now})
+      on conflict (local_commit_seq) do nothing
+    `.execute(this.db);
+  }
+
+  /**
+   * Mark a mapping as forwarded with the main server's commit_seq.
+   */
+  async markForwarded(
+    localCommitSeq: number,
+    mainCommitSeq: number
+  ): Promise<void> {
+    const now = Date.now();
+    await sql`
+      update ${sql.table('relay_sequence_map')}
+      set
+        main_commit_seq = ${mainCommitSeq},
+        status = 'forwarded',
+        updated_at = ${now}
+      where local_commit_seq = ${localCommitSeq}
+    `.execute(this.db);
+  }
+
+  /**
+   * Mark a mapping as confirmed (main server acknowledged).
+   */
+  async markConfirmed(localCommitSeq: number): Promise<void> {
+    const now = Date.now();
+    await sql`
+      update ${sql.table('relay_sequence_map')}
+      set status = 'confirmed', updated_at = ${now}
+      where local_commit_seq = ${localCommitSeq}
+    `.execute(this.db);
+  }
+
+  /**
+   * Get the mapping for a local commit sequence.
+   */
+  async getMapping(localCommitSeq: number): Promise<SequenceMapping | null> {
+    const rowResult = await sql<{
+      local_commit_seq: number;
+      main_commit_seq: number | null;
+      status: RelaySequenceMapStatus;
+    }>`
+      select local_commit_seq, main_commit_seq, status
+      from ${sql.table('relay_sequence_map')}
+      where local_commit_seq = ${localCommitSeq}
+      limit 1
+    `.execute(this.db);
+    const row = rowResult.rows[0];
+
+    if (!row) return null;
+
+    return {
+      localCommitSeq: row.local_commit_seq,
+      mainCommitSeq: row.main_commit_seq,
+      status: row.status,
+    };
+  }
+
+  /**
+   * Get the local commit sequence for a main server commit sequence.
+   */
+  async getLocalCommitSeq(mainCommitSeq: number): Promise<number | null> {
+    const rowResult = await sql<{ local_commit_seq: number }>`
+      select local_commit_seq
+      from ${sql.table('relay_sequence_map')}
+      where main_commit_seq = ${mainCommitSeq}
+      limit 1
+    `.execute(this.db);
+
+    return rowResult.rows[0]?.local_commit_seq ?? null;
+  }
+
+  /**
+   * Get all pending mappings (commits not yet forwarded).
+   */
+  async getPendingMappings(): Promise<SequenceMapping[]> {
+    const rowsResult = await sql<{
+      local_commit_seq: number;
+      main_commit_seq: number | null;
+      status: RelaySequenceMapStatus;
+    }>`
+      select local_commit_seq, main_commit_seq, status
+      from ${sql.table('relay_sequence_map')}
+      where status = 'pending'
+      order by local_commit_seq asc
+    `.execute(this.db);
+    const rows = rowsResult.rows;
+
+    return rows.map((row) => ({
+      localCommitSeq: row.local_commit_seq,
+      mainCommitSeq: row.main_commit_seq,
+      status: row.status,
+    }));
+  }
+
+  /**
+   * Create a mapping for commits pulled from main (assigned new local commit_seq).
+   *
+   * These mappings go directly to 'confirmed' status since they came from main.
+   */
+  async createConfirmedMapping(
+    localCommitSeq: number,
+    mainCommitSeq: number
+  ): Promise<void> {
+    const now = Date.now();
+    await sql`
+      insert into ${sql.table('relay_sequence_map')} (
+        local_commit_seq,
+        main_commit_seq,
+        status,
+        created_at,
+        updated_at
+      )
+      values (
+        ${localCommitSeq},
+        ${mainCommitSeq},
+        'confirmed',
+        ${now},
+        ${now}
+      )
+      on conflict (local_commit_seq)
+      do update set
+        main_commit_seq = ${mainCommitSeq},
+        status = 'confirmed',
+        updated_at = ${now}
+    `.execute(this.db);
+  }
+
+  /**
+   * Delete confirmed/forwarded sequence mappings older than the given age.
+   * Keeps pending mappings (they haven't been forwarded yet).
+   */
+  async pruneOldMappings(maxAgeMs: number): Promise<number> {
+    const threshold = Date.now() - maxAgeMs;
+    const result = await sql`
+      delete from ${sql.table('relay_sequence_map')}
+      where status in ('confirmed', 'forwarded')
+      and updated_at < ${threshold}
+    `.execute(this.db);
+
+    return Number(result.numAffectedRows ?? 0);
+  }
+
+  /**
+   * Get the highest main_commit_seq we've seen (for tracking pull cursor).
+   */
+  async getHighestMainCommitSeq(): Promise<number> {
+    const rowResult = await sql<{ max_seq: number | null }>`
+      select max(main_commit_seq) as max_seq
+      from ${sql.table('relay_sequence_map')}
+      where main_commit_seq is not null
+      limit 1
+    `.execute(this.db);
+
+    return rowResult.rows[0]?.max_seq ?? 0;
+  }
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * @syncular/relay - Edge Relay Server
+ *
+ * An edge relay server that acts as a local server to nearby clients
+ * while simultaneously acting as a client to the main server.
+ *
+ * @example
+ * ```typescript
+ * import { createRelayServer } from '@syncular/relay';
+ * import { createSqliteServerDialect } from '@syncular/server-dialect-sqlite';
+ *
+ * const relay = createRelayServer({
+ *   db: sqliteDb,
+ *   dialect: createSqliteServerDialect(),
+ *   mainServerTransport: createHttpTransport({ baseUrl: 'https://main.example.com/sync' }),
+ *   mainServerClientId: 'relay-branch-001',
+ *   mainServerActorId: 'relay-service',
+ *   scopeKeys: ['client:acme'],
+ *   shapes: shapeRegistry,
+ *   subscriptions: subscriptionRegistry,
+ * });
+ *
+ * // Mount routes for local clients
+ * app.route('/sync', relay.getRoutes());
+ *
+ * // Start background sync with main
+ * await relay.start();
+ * ```
+ */
+
+// Client role (syncing with main server)
+export * from './client-role';
+
+// Migration
+export * from './migrate';
+
+// Mode manager
+export * from './mode-manager';
+
+// Realtime WebSocket manager
+export * from './realtime';
+
+// Main exports
+export * from './relay';
+
+// Schema types
+export * from './schema';
+
+// Server role (serving local clients)
+export * from './server-role';

package/src/migrate.ts

@@ -0,0 +1,113 @@
+/**
+ * @syncular/relay - Schema setup
+ *
+ * Creates relay-specific tables for edge relay functionality.
+ * Uses Kysely for dialect-agnostic schema creation.
+ */
+
+import type { ServerSyncDialect } from '@syncular/server';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type { RelayDatabase } from './schema';
+
+/**
+ * Ensures the relay schema exists in the database.
+ * Safe to call multiple times (idempotent).
+ *
+ * This creates relay-specific tables on top of the base sync schema.
+ * Call `ensureSyncSchema()` from @syncular/server first to create base tables.
+ */
+export async function ensureRelaySchema<
+  DB extends RelayDatabase = RelayDatabase,
+>(db: Kysely<DB>, dialect: ServerSyncDialect): Promise<void> {
+  // Ensure base sync schema exists first
+  await dialect.ensureSyncSchema(db);
+
+  // Create relay-specific tables
+  const isSqlite = dialect.name === 'sqlite';
+
+  // Forward outbox table
+  await sql
+    .raw(`
+    CREATE TABLE IF NOT EXISTS relay_forward_outbox (
+      id TEXT PRIMARY KEY,
+      local_commit_seq INTEGER NOT NULL,
+      client_id TEXT NOT NULL,
+      client_commit_id TEXT NOT NULL,
+      operations_json TEXT NOT NULL,
+      schema_version INTEGER NOT NULL DEFAULT 1,
+      status TEXT NOT NULL DEFAULT 'pending',
+      main_commit_seq INTEGER,
+      error TEXT,
+      last_response_json TEXT,
+      created_at INTEGER NOT NULL DEFAULT (${isSqlite ? "strftime('%s','now') * 1000" : 'EXTRACT(EPOCH FROM NOW()) * 1000'}),
+      updated_at INTEGER NOT NULL DEFAULT (${isSqlite ? "strftime('%s','now') * 1000" : 'EXTRACT(EPOCH FROM NOW()) * 1000'}),
+      attempt_count INTEGER NOT NULL DEFAULT 0
+    )
+  `)
+    .execute(db);
+
+  // Index for finding next sendable outbox entry
+  await sql
+    .raw(`
+    CREATE INDEX IF NOT EXISTS idx_relay_forward_outbox_status
+    ON relay_forward_outbox (status, created_at)
+  `)
+    .execute(db);
+
+  // Sequence map table
+  await sql
+    .raw(`
+    CREATE TABLE IF NOT EXISTS relay_sequence_map (
+      local_commit_seq INTEGER PRIMARY KEY,
+      main_commit_seq INTEGER,
+      status TEXT NOT NULL DEFAULT 'pending',
+      created_at INTEGER NOT NULL DEFAULT (${isSqlite ? "strftime('%s','now') * 1000" : 'EXTRACT(EPOCH FROM NOW()) * 1000'}),
+      updated_at INTEGER NOT NULL DEFAULT (${isSqlite ? "strftime('%s','now') * 1000" : 'EXTRACT(EPOCH FROM NOW()) * 1000'})
+    )
+  `)
+    .execute(db);
+
+  // Index for looking up main_commit_seq
+  await sql
+    .raw(`
+    CREATE INDEX IF NOT EXISTS idx_relay_sequence_map_main
+    ON relay_sequence_map (main_commit_seq)
+    WHERE main_commit_seq IS NOT NULL
+  `)
+    .execute(db);
+
+  // Forward conflicts table
+  await sql
+    .raw(`
+    CREATE TABLE IF NOT EXISTS relay_forward_conflicts (
+      id TEXT PRIMARY KEY,
+      local_commit_seq INTEGER NOT NULL,
+      client_id TEXT NOT NULL,
+      client_commit_id TEXT NOT NULL,
+      response_json TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      resolved_at INTEGER
+    )
+  `)
+    .execute(db);
+
+  // Index for finding unresolved conflicts
+  await sql
+    .raw(`
+    CREATE INDEX IF NOT EXISTS idx_relay_forward_conflicts_unresolved
+    ON relay_forward_conflicts (resolved_at)
+    WHERE resolved_at IS NULL
+  `)
+    .execute(db);
+
+  // Config table
+  await sql
+    .raw(`
+    CREATE TABLE IF NOT EXISTS relay_config (
+      key TEXT PRIMARY KEY,
+      value_json TEXT NOT NULL
+    )
+  `)
+    .execute(db);
+}

package/src/mode-manager.ts

@@ -0,0 +1,142 @@
+/**
+ * @syncular/relay - Mode Manager
+ *
+ * State machine for tracking relay online/offline status.
+ */
+
+/**
+ * Relay operating modes.
+ */
+export type RelayMode = 'online' | 'offline' | 'reconnecting';
+
+/**
+ * Mode manager options.
+ */
+export interface ModeManagerOptions {
+  healthCheckIntervalMs?: number;
+  reconnectBackoffMs?: number;
+  maxReconnectBackoffMs?: number;
+  onModeChange?: (mode: RelayMode) => void;
+}
+
+/**
+ * Mode manager for tracking relay online/offline state.
+ *
+ * Uses health checks to detect connectivity to the main server
+ * and manages reconnection with exponential backoff.
+ */
+export class ModeManager {
+  private mode: RelayMode = 'offline';
+  private healthCheckIntervalMs: number;
+  private reconnectBackoffMs: number;
+  private maxReconnectBackoffMs: number;
+  private currentBackoffMs: number;
+  private onModeChange?: (mode: RelayMode) => void;
+
+  private running = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private healthCheckFn: (() => Promise<boolean>) | null = null;
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: assigned and incremented in healthCheck
+  private consecutiveFailures = 0;
+
+  constructor(options: ModeManagerOptions = {}) {
+    this.healthCheckIntervalMs = options.healthCheckIntervalMs ?? 30000;
+    this.reconnectBackoffMs = options.reconnectBackoffMs ?? 1000;
+    this.maxReconnectBackoffMs = options.maxReconnectBackoffMs ?? 60000;
+    this.currentBackoffMs = this.reconnectBackoffMs;
+    this.onModeChange = options.onModeChange;
+  }
+
+  /**
+   * Get the current mode.
+   */
+  getMode(): RelayMode {
+    return this.mode;
+  }
+
+  /**
+   * Start the mode manager with a health check function.
+   */
+  start(healthCheckFn: () => Promise<boolean>): void {
+    if (this.running) return;
+    this.running = true;
+    this.healthCheckFn = healthCheckFn;
+
+    // Start with immediate health check
+    this.scheduleHealthCheck(0);
+  }
+
+  /**
+   * Stop the mode manager.
+   */
+  stop(): void {
+    this.running = false;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Manually report a successful operation (resets backoff).
+   */
+  reportSuccess(): void {
+    if (this.mode !== 'online') {
+      this.setMode('online');
+    }
+    this.consecutiveFailures = 0;
+    this.currentBackoffMs = this.reconnectBackoffMs;
+  }
+
+  /**
+   * Manually report a failed operation.
+   */
+  reportFailure(): void {
+    this.consecutiveFailures++;
+
+    if (this.mode === 'online') {
+      this.setMode('reconnecting');
+    }
+
+    // Increase backoff for next attempt
+    this.currentBackoffMs = Math.min(
+      this.currentBackoffMs * 2,
+      this.maxReconnectBackoffMs
+    );
+  }
+
+  private setMode(newMode: RelayMode): void {
+    if (this.mode === newMode) return;
+    this.mode = newMode;
+    this.onModeChange?.(newMode);
+  }
+
+  private scheduleHealthCheck(delayMs: number): void {
+    if (!this.running) return;
+    if (this.timer) return;
+
+    this.timer = setTimeout(async () => {
+      this.timer = null;
+
+      if (!this.healthCheckFn) {
+        this.scheduleHealthCheck(this.healthCheckIntervalMs);
+        return;
+      }
+
+      try {
+        const healthy = await this.healthCheckFn();
+
+        if (healthy) {
+          this.reportSuccess();
+          this.scheduleHealthCheck(this.healthCheckIntervalMs);
+        } else {
+          this.reportFailure();
+          this.scheduleHealthCheck(this.currentBackoffMs);
+        }
+      } catch {
+        this.reportFailure();
+        this.scheduleHealthCheck(this.currentBackoffMs);
+      }
+    }, delayMs);
+  }
+}