@syncular/server 0.0.6-95 → 0.1.0

package/src/relay/mode-manager.ts

@@ -0,0 +1,142 @@
+/**
+ * @syncular/server/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 !== 'reconnecting') {
+      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);
+  }
+}

package/src/relay/realtime.ts

@@ -0,0 +1,207 @@
+/**
+ * @syncular/server/relay - Realtime WebSocket Manager
+ *
+ * Manages WebSocket connections for local clients to receive
+ * instant notifications when data changes.
+ *
+ * Adapted from @syncular/server/hono/ws.ts for relay use.
+ */
+
+import { RealtimeConnectionRegistry } from '@syncular/core';
+
+/**
+ * WebSocket event data for sync notifications.
+ */
+export interface RelayWebSocketEvent {
+  event: 'sync' | 'heartbeat' | 'error';
+  data: {
+    cursor?: number;
+    error?: string;
+    timestamp: number;
+  };
+}
+
+/**
+ * WebSocket connection interface for the relay.
+ */
+export interface RelayWebSocketConnection {
+  sendSync(cursor: number): void;
+  sendHeartbeat(): void;
+  sendError(message: string): void;
+  close(code?: number, reason?: string): void;
+  isOpen: boolean;
+  actorId: string;
+  clientId: string;
+  ownerKey: string;
+}
+
+function createRelayConnectionOwnerKey(args: {
+  actorId: string;
+  clientId: string;
+}): string {
+  return JSON.stringify([args.actorId, args.clientId]);
+}
+
+/**
+ * Realtime manager for relay WebSocket connections.
+ *
+ * Tracks active connections by client ID and scope key for
+ * efficient notification routing.
+ */
+export class RelayRealtime {
+  private readonly registry: RealtimeConnectionRegistry<RelayWebSocketConnection>;
+
+  constructor(options?: { heartbeatIntervalMs?: number }) {
+    this.registry = new RealtimeConnectionRegistry({
+      heartbeatIntervalMs: options?.heartbeatIntervalMs,
+    });
+  }
+
+  /**
+   * Register a connection for a client.
+   * Returns a cleanup function to unregister.
+   */
+  register(
+    connection: RelayWebSocketConnection,
+    initialScopeKeys: string[] = []
+  ): () => void {
+    return this.registry.register(connection, initialScopeKeys);
+  }
+
+  /**
+   * Update the effective scopes for an already-connected client.
+   */
+  updateClientScopeKeys(clientId: string, scopeKeys: string[]): void {
+    const connections = this.registry.getConnectionsForClient(clientId);
+    if (!connections || connections.size === 0) return;
+
+    const ownerKeys = new Set<string>();
+    for (const connection of connections) {
+      ownerKeys.add(connection.ownerKey);
+    }
+
+    for (const ownerKey of ownerKeys) {
+      this.registry.updateOwnerScopeKeys(ownerKey, scopeKeys);
+    }
+  }
+
+  /**
+   * Notify clients that new data is available for the given scopes.
+   */
+  notifyScopeKeys(
+    scopeKeys: string[],
+    cursor: number,
+    opts?: { excludeClientIds?: string[] }
+  ): void {
+    this.registry.forEachConnectionInScopeKeys(
+      scopeKeys,
+      (conn) => {
+        conn.sendSync(cursor);
+      },
+      { excludeClientIds: opts?.excludeClientIds }
+    );
+  }
+
+  /**
+   * Get the number of active connections for a client.
+   */
+  getConnectionCount(clientId: string): number {
+    return this.registry.getConnectionCount(clientId);
+  }
+
+  /**
+   * Get total number of active connections.
+   */
+  getTotalConnections(): number {
+    return this.registry.getTotalConnections();
+  }
+
+  /**
+   * Close all connections for a client.
+   */
+  closeClientConnections(clientId: string): void {
+    this.registry.closeClientConnections(clientId, 1000, 'client closed');
+  }
+
+  /**
+   * Close all connections.
+   */
+  closeAll(): void {
+    this.registry.closeAll(1000, 'server shutdown');
+  }
+}
+
+/**
+ * Create a WebSocket connection wrapper.
+ *
+ * Use this with your WebSocket library to create connections
+ * compatible with RelayRealtime.
+ */
+export function createRelayWebSocketConnection(
+  ws: {
+    send(message: string): void;
+    close(code?: number, reason?: string): void;
+    readyState: number;
+  },
+  args: { actorId: string; clientId: string }
+): RelayWebSocketConnection {
+  let closed = false;
+
+  function safeSend(message: string): boolean {
+    try {
+      ws.send(message);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  const connection: RelayWebSocketConnection = {
+    get isOpen() {
+      if (closed) return false;
+      return ws.readyState === 1;
+    },
+    actorId: args.actorId,
+    clientId: args.clientId,
+    ownerKey: createRelayConnectionOwnerKey(args),
+    sendSync(cursor: number) {
+      if (!connection.isOpen) return;
+      const ok = safeSend(
+        JSON.stringify({
+          event: 'sync',
+          data: { cursor, timestamp: Date.now() },
+        })
+      );
+      if (!ok) closed = true;
+    },
+    sendHeartbeat() {
+      if (!connection.isOpen) return;
+      const ok = safeSend(
+        JSON.stringify({ event: 'heartbeat', data: { timestamp: Date.now() } })
+      );
+      if (!ok) closed = true;
+    },
+    sendError(message: string) {
+      if (connection.isOpen) {
+        safeSend(
+          JSON.stringify({
+            event: 'error',
+            data: { error: message, timestamp: Date.now() },
+          })
+        );
+      }
+      connection.close(1011, 'server error');
+    },
+    close(code?: number, reason?: string) {
+      if (closed) return;
+      closed = true;
+      try {
+        ws.close(code, reason);
+      } catch {
+        // ignore
+      }
+    },
+  };
+
+  return connection;
+}