@topgunbuild/client 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LWWRecord, ORMapRecord, PredicateNode, LWWMap, ORMap, Timestamp, HLC } from '@topgunbuild/core';
+import { LWWRecord, ORMapRecord, PredicateNode, LWWMap, ORMap, Timestamp, HLC, NodeHealth, ConnectionPoolConfig, PartitionRouterConfig, PartitionMap, ClusterClientConfig } from '@topgunbuild/core';
 export { LWWMap, LWWRecord, PredicateNode, Predicates } from '@topgunbuild/core';
 import pino from 'pino';
 
@@ -304,6 +304,104 @@ interface OperationDroppedEvent {
     key: string;
 }
 
+/**
+ * Connection Provider Types
+ *
+ * IConnectionProvider abstracts WebSocket connection handling to support
+ * both single-server and cluster modes.
+ */
+/**
+ * Events emitted by IConnectionProvider.
+ */
+type ConnectionProviderEvent = 'connected' | 'disconnected' | 'reconnected' | 'message' | 'partitionMapUpdated' | 'error';
+/**
+ * Connection event handler type.
+ */
+type ConnectionEventHandler = (...args: any[]) => void;
+/**
+ * Abstract interface for WebSocket connection providers.
+ *
+ * Implementations:
+ * - SingleServerProvider: Direct connection to a single server
+ * - ClusterClient: Multi-node connection pool with partition routing
+ */
+interface IConnectionProvider {
+    /**
+     * Connect to the server(s).
+     * In cluster mode, connects to all seed nodes.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key.
+     * In cluster mode: routes to partition owner based on key hash.
+     * In single-server mode: returns the only connection.
+     *
+     * @param key - The key to route (used for partition-aware routing)
+     * @throws Error if not connected
+     */
+    getConnection(key: string): WebSocket;
+    /**
+     * Get any available connection.
+     * Used for subscriptions, metadata requests, and non-key-specific operations.
+     *
+     * @throws Error if not connected
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Check if at least one connection is active and ready.
+     */
+    isConnected(): boolean;
+    /**
+     * Get all connected node IDs.
+     * Single-server mode returns ['default'].
+     * Cluster mode returns actual node IDs.
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Subscribe to connection events.
+     *
+     * Events:
+     * - 'connected': A connection was established (nodeId?: string)
+     * - 'disconnected': A connection was lost (nodeId?: string)
+     * - 'reconnected': A connection was re-established after disconnect (nodeId?: string)
+     * - 'message': A message was received (nodeId: string, data: any)
+     * - 'partitionMapUpdated': Partition map was updated (cluster mode only)
+     * - 'error': An error occurred (error: Error)
+     */
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Unsubscribe from connection events.
+     */
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Send a message via the appropriate connection.
+     * In cluster mode, routes based on key if provided.
+     *
+     * @param data - Serialized message data
+     * @param key - Optional key for routing (cluster mode)
+     */
+    send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Close all connections gracefully.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Configuration for SingleServerProvider.
+ */
+interface SingleServerProviderConfig {
+    /** WebSocket URL to connect to */
+    url: string;
+    /** Maximum reconnection attempts (default: 10) */
+    maxReconnectAttempts?: number;
+    /** Initial reconnect delay in ms (default: 1000) */
+    reconnectDelayMs?: number;
+    /** Backoff multiplier for reconnect delay (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum reconnect delay in ms (default: 30000) */
+    maxReconnectDelayMs?: number;
+}
+
 interface HeartbeatConfig {
     intervalMs: number;
     timeoutMs: number;
@@ -323,7 +421,10 @@ interface BackoffConfig {
 }
 interface SyncEngineConfig {
     nodeId: string;
-    serverUrl: string;
+    /** @deprecated Use connectionProvider instead */
+    serverUrl?: string;
+    /** Connection provider (preferred over serverUrl) */
+    connectionProvider?: IConnectionProvider;
     storageAdapter: IStorageAdapter;
     reconnectInterval?: number;
     heartbeat?: Partial<HeartbeatConfig>;
@@ -337,6 +438,8 @@ declare class SyncEngine {
     private readonly hlc;
     private readonly stateMachine;
     private readonly backoffConfig;
+    private readonly connectionProvider;
+    private readonly useConnectionProvider;
     private websocket;
     private opLog;
     private maps;
@@ -357,6 +460,7 @@ declare class SyncEngine {
     private waitingForCapacity;
     private highWaterMarkEmitted;
     private backpressureListeners;
+    private pendingWriteConcernPromises;
     constructor(config: SyncEngineConfig);
     /**
      * Get the current connection state
@@ -383,6 +487,14 @@ declare class SyncEngine {
      * Check if fully connected and synced
      */
     private isConnected;
+    /**
+     * Initialize connection using IConnectionProvider (Phase 4.5 cluster mode).
+     * Sets up event handlers for the connection provider.
+     */
+    private initConnectionProvider;
+    /**
+     * Initialize connection using direct WebSocket (legacy single-server mode).
+     */
     private initConnection;
     private scheduleReconnect;
     private calculateBackoffDelay;
@@ -390,6 +502,18 @@ declare class SyncEngine {
      * Reset backoff counter (called on successful connection)
      */
     private resetBackoff;
+    /**
+     * Send a message through the current connection.
+     * Uses connectionProvider if in cluster mode, otherwise uses direct websocket.
+     * @param message Message object to serialize and send
+     * @param key Optional key for routing (cluster mode only)
+     * @returns true if message was sent, false otherwise
+     */
+    private sendMessage;
+    /**
+     * Check if we can send messages (connection is ready).
+     */
+    private canSend;
     private loadOpLog;
     private saveOpLog;
     registerMap(mapName: string, map: LWWMap<any, any> | ORMap<any, any>): void;
@@ -424,6 +548,11 @@ declare class SyncEngine {
     releaseLock(name: string, requestId: string, fencingToken: number): Promise<boolean>;
     private handleServerMessage;
     getHLC(): HLC;
+    /**
+     * Helper method to apply a single server event to the local map.
+     * Used by both SERVER_EVENT and SERVER_BATCH_EVENT handlers.
+     */
+    private applyServerEvent;
     /**
      * Closes the WebSocket connection and cleans up resources.
      */
@@ -433,6 +562,43 @@ declare class SyncEngine {
      * Use after fatal errors to start fresh.
      */
     resetConnection(): void;
+    /**
+     * Wait for a partition map update from the connection provider.
+     * Used when an operation fails with NOT_OWNER error and needs
+     * to wait for an updated partition map before retrying.
+     *
+     * @param timeoutMs - Maximum time to wait (default: 5000ms)
+     * @returns Promise that resolves when partition map is updated or times out
+     */
+    waitForPartitionMapUpdate(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for the connection to be available.
+     * Used when an operation fails due to connection issues and needs
+     * to wait for reconnection before retrying.
+     *
+     * @param timeoutMs - Maximum time to wait (default: 10000ms)
+     * @returns Promise that resolves when connected or rejects on timeout
+     */
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for a specific sync state.
+     * Useful for waiting until fully connected and synced.
+     *
+     * @param targetState - The state to wait for
+     * @param timeoutMs - Maximum time to wait (default: 30000ms)
+     * @returns Promise that resolves when state is reached or rejects on timeout
+     */
+    waitForState(targetState: SyncState, timeoutMs?: number): Promise<void>;
+    /**
+     * Check if the connection provider is connected.
+     * Convenience method for failover logic.
+     */
+    isProviderConnected(): boolean;
+    /**
+     * Get the connection provider for direct access.
+     * Use with caution - prefer using SyncEngine methods.
+     */
+    getConnectionProvider(): IConnectionProvider;
     private resetMap;
     /**
      * Starts the heartbeat mechanism after successful connection.
@@ -514,6 +680,26 @@ declare class SyncEngine {
      * Drop the oldest pending operation (used by 'drop-oldest' strategy).
      */
     private dropOldestOp;
+    /**
+     * Register a pending Write Concern promise for an operation.
+     * The promise will be resolved when the server sends an ACK with the operation result.
+     *
+     * @param opId - Operation ID
+     * @param timeout - Timeout in ms (default: 5000)
+     * @returns Promise that resolves with the Write Concern result
+     */
+    registerWriteConcernPromise(opId: string, timeout?: number): Promise<any>;
+    /**
+     * Resolve a pending Write Concern promise with the server result.
+     *
+     * @param opId - Operation ID
+     * @param result - Result from server ACK
+     */
+    private resolveWriteConcernPromise;
+    /**
+     * Cancel all pending Write Concern promises (e.g., on disconnect).
+     */
+    private cancelAllWriteConcernPromises;
 }
 
 interface ILock {
@@ -532,19 +718,55 @@ declare class DistributedLock implements ILock {
     isLocked(): boolean;
 }
 
+/**
+ * Cluster mode configuration for TopGunClient.
+ * When provided, the client connects to multiple nodes with partition-aware routing.
+ */
+interface TopGunClusterConfig {
+    /** Initial seed nodes (at least one required) */
+    seeds: string[];
+    /** Connection pool size per node (default: 1) */
+    connectionsPerNode?: number;
+    /** Enable smart routing to partition owner (default: true) */
+    smartRouting?: boolean;
+    /** Partition map refresh interval in ms (default: 30000) */
+    partitionMapRefreshMs?: number;
+    /** Connection timeout per node in ms (default: 5000) */
+    connectionTimeoutMs?: number;
+    /** Retry attempts for failed operations (default: 3) */
+    retryAttempts?: number;
+}
+/**
+ * Default values for cluster configuration
+ */
+declare const DEFAULT_CLUSTER_CONFIG: Required<Omit<TopGunClusterConfig, 'seeds'>>;
+/**
+ * TopGunClient configuration options
+ */
+interface TopGunClientConfig {
+    /** Unique node identifier (auto-generated if not provided) */
+    nodeId?: string;
+    /** Single-server mode: WebSocket URL to connect to */
+    serverUrl?: string;
+    /** Cluster mode: Configuration for multi-node routing */
+    cluster?: TopGunClusterConfig;
+    /** Storage adapter for local persistence */
+    storage: IStorageAdapter;
+    /** Backoff configuration for reconnection */
+    backoff?: Partial<BackoffConfig>;
+    /** Backpressure configuration */
+    backpressure?: Partial<BackpressureConfig>;
+}
 declare class TopGunClient {
     private readonly nodeId;
     private readonly syncEngine;
     private readonly maps;
     private readonly storageAdapter;
     private readonly topicHandles;
-    constructor(config: {
-        nodeId?: string;
-        serverUrl: string;
-        storage: IStorageAdapter;
-        backoff?: Partial<BackoffConfig>;
-        backpressure?: Partial<BackpressureConfig>;
-    });
+    private readonly clusterClient?;
+    private readonly isClusterMode;
+    private readonly clusterConfig?;
+    constructor(config: TopGunClientConfig);
     start(): Promise<void>;
     setAuthToken(token: string): void;
     setAuthTokenProvider(provider: () => Promise<string | null>): void;
@@ -581,6 +803,46 @@ declare class TopGunClient {
      * Closes the client, disconnecting from the server and cleaning up resources.
      */
     close(): void;
+    /**
+     * Check if running in cluster mode
+     */
+    isCluster(): boolean;
+    /**
+     * Get list of connected cluster nodes (cluster mode only)
+     * @returns Array of connected node IDs, or empty array in single-server mode
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Get the current partition map version (cluster mode only)
+     * @returns Partition map version, or 0 in single-server mode
+     */
+    getPartitionMapVersion(): number;
+    /**
+     * Check if direct routing is active (cluster mode only)
+     * Direct routing sends operations directly to partition owners.
+     * @returns true if routing is active, false otherwise
+     */
+    isRoutingActive(): boolean;
+    /**
+     * Get health status for all cluster nodes (cluster mode only)
+     * @returns Map of node IDs to their health status
+     */
+    getClusterHealth(): Map<string, NodeHealth>;
+    /**
+     * Force refresh of partition map (cluster mode only)
+     * Use this after detecting routing errors.
+     */
+    refreshPartitionMap(): Promise<void>;
+    /**
+     * Get cluster router statistics (cluster mode only)
+     */
+    getClusterStats(): {
+        mapVersion: number;
+        partitionCount: number;
+        nodeCount: number;
+        lastRefresh: number;
+        isStale: boolean;
+    } | null;
     /**
      * Get the current connection state
      */
@@ -771,6 +1033,574 @@ declare class BackpressureError extends Error {
     constructor(pendingCount: number, maxPending: number);
 }
 
+/**
+ * ConnectionPool - Manages WebSocket connections to multiple cluster nodes
+ *
+ * Phase 4: Partition-Aware Client Routing
+ *
+ * Features:
+ * - Maintains connections to all known cluster nodes
+ * - Automatic reconnection with exponential backoff
+ * - Health monitoring and status tracking
+ * - Connection lifecycle management
+ */
+
+interface ConnectionPoolEvents {
+    'node:connected': (nodeId: string) => void;
+    'node:disconnected': (nodeId: string, reason: string) => void;
+    'node:healthy': (nodeId: string) => void;
+    'node:unhealthy': (nodeId: string, reason: string) => void;
+    'message': (nodeId: string, message: any) => void;
+    'error': (nodeId: string, error: Error) => void;
+}
+declare class ConnectionPool {
+    private readonly listeners;
+    private readonly config;
+    private readonly connections;
+    private primaryNodeId;
+    private healthCheckTimer;
+    private authToken;
+    constructor(config?: Partial<ConnectionPoolConfig>);
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeAllListeners(event?: string): this;
+    /**
+     * Set authentication token for all connections
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Add a node to the connection pool
+     */
+    addNode(nodeId: string, endpoint: string): Promise<void>;
+    /**
+     * Remove a node from the connection pool
+     */
+    removeNode(nodeId: string): Promise<void>;
+    /**
+     * Get connection for a specific node
+     */
+    getConnection(nodeId: string): WebSocket | null;
+    /**
+     * Get primary connection (first/seed node)
+     */
+    getPrimaryConnection(): WebSocket | null;
+    /**
+     * Get any healthy connection
+     */
+    getAnyHealthyConnection(): {
+        nodeId: string;
+        socket: WebSocket;
+    } | null;
+    /**
+     * Send message to a specific node
+     */
+    send(nodeId: string, message: any): boolean;
+    /**
+     * Send message to primary node
+     */
+    sendToPrimary(message: any): boolean;
+    /**
+     * Get health status for all nodes
+     */
+    getHealthStatus(): Map<string, NodeHealth>;
+    /**
+     * Get list of connected node IDs
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Get all node IDs
+     */
+    getAllNodes(): string[];
+    /**
+     * Check if node is connected and authenticated
+     */
+    isNodeConnected(nodeId: string): boolean;
+    /**
+     * Check if connected to a specific node.
+     * Alias for isNodeConnected() for IConnectionProvider compatibility.
+     */
+    isConnected(nodeId: string): boolean;
+    /**
+     * Start health monitoring
+     */
+    startHealthCheck(): void;
+    /**
+     * Stop health monitoring
+     */
+    stopHealthCheck(): void;
+    /**
+     * Close all connections and cleanup
+     */
+    close(): void;
+    private connect;
+    private sendAuth;
+    private handleMessage;
+    private flushPendingMessages;
+    private scheduleReconnect;
+    private performHealthCheck;
+}
+
+/**
+ * PartitionRouter - Routes operations to the correct cluster node
+ *
+ * Phase 4: Partition-Aware Client Routing
+ *
+ * Features:
+ * - Maintains local copy of partition map
+ * - Routes keys to owner nodes using consistent hashing
+ * - Handles stale routing with automatic refresh
+ * - Supports fallback to server-side forwarding
+ */
+
+interface RoutingResult {
+    nodeId: string;
+    partitionId: number;
+    isOwner: boolean;
+    isBackup: boolean;
+}
+interface PartitionRouterEvents {
+    'partitionMap:updated': (version: number, changesCount: number) => void;
+    'partitionMap:stale': (currentVersion: number, lastRefresh: number) => void;
+    'routing:miss': (key: string, expectedOwner: string, actualOwner: string) => void;
+}
+declare class PartitionRouter {
+    private readonly listeners;
+    private readonly config;
+    private readonly connectionPool;
+    private partitionMap;
+    private lastRefreshTime;
+    private refreshTimer;
+    private pendingRefresh;
+    constructor(connectionPool: ConnectionPool, config?: Partial<PartitionRouterConfig>);
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    once(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeListener(event: string, listener: (...args: any[]) => void): this;
+    removeAllListeners(event?: string): this;
+    /**
+     * Get the partition ID for a given key
+     */
+    getPartitionId(key: string): number;
+    /**
+     * Route a key to the owner node
+     */
+    route(key: string): RoutingResult | null;
+    /**
+     * Route a key and get the WebSocket connection to use
+     */
+    routeToConnection(key: string): {
+        nodeId: string;
+        socket: WebSocket;
+    } | null;
+    /**
+     * Get routing info for multiple keys (batch routing)
+     */
+    routeBatch(keys: string[]): Map<string, RoutingResult[]>;
+    /**
+     * Get all partitions owned by a specific node
+     */
+    getPartitionsForNode(nodeId: string): number[];
+    /**
+     * Get current partition map version
+     */
+    getMapVersion(): number;
+    /**
+     * Check if partition map is available
+     */
+    hasPartitionMap(): boolean;
+    /**
+     * Get owner node for a key.
+     * Returns null if partition map is not available.
+     */
+    getOwner(key: string): string | null;
+    /**
+     * Get backup nodes for a key.
+     * Returns empty array if partition map is not available.
+     */
+    getBackups(key: string): string[];
+    /**
+     * Get the full partition map.
+     * Returns null if not available.
+     */
+    getMap(): PartitionMap | null;
+    /**
+     * Update entire partition map.
+     * Only accepts newer versions.
+     */
+    updateMap(map: PartitionMap): boolean;
+    /**
+     * Update a single partition (for delta updates).
+     */
+    updatePartition(partitionId: number, owner: string, backups: string[]): void;
+    /**
+     * Check if partition map is stale
+     */
+    isMapStale(): boolean;
+    /**
+     * Request fresh partition map from server
+     */
+    refreshPartitionMap(): Promise<void>;
+    /**
+     * Start periodic partition map refresh
+     */
+    startPeriodicRefresh(): void;
+    /**
+     * Stop periodic refresh
+     */
+    stopPeriodicRefresh(): void;
+    /**
+     * Handle NOT_OWNER error from server
+     */
+    handleNotOwnerError(key: string, actualOwner: string, newMapVersion: number): void;
+    /**
+     * Get statistics about routing
+     */
+    getStats(): {
+        mapVersion: number;
+        partitionCount: number;
+        nodeCount: number;
+        lastRefresh: number;
+        isStale: boolean;
+    };
+    /**
+     * Cleanup resources
+     */
+    close(): void;
+    private handlePartitionMap;
+    private handlePartitionMapDelta;
+    private applyPartitionChange;
+    private updateConnectionPool;
+    private doRefreshPartitionMap;
+}
+
+/**
+ * ClusterClient - Cluster-aware client wrapper
+ *
+ * Phase 4: Partition-Aware Client Routing
+ * Phase 4.5: Implements IConnectionProvider for SyncEngine abstraction
+ *
+ * Wraps the standard TopGunClient with cluster-aware routing capabilities.
+ * Coordinates between ConnectionPool and PartitionRouter for optimal
+ * request routing in a clustered environment.
+ */
+
+interface ClusterClientEvents {
+    'connected': () => void;
+    'disconnected': (reason: string) => void;
+    'partitionMap:ready': (version: number) => void;
+    'routing:active': () => void;
+    'error': (error: Error) => void;
+    'circuit:open': (nodeId: string) => void;
+    'circuit:closed': (nodeId: string) => void;
+    'circuit:half-open': (nodeId: string) => void;
+}
+/**
+ * Circuit breaker state for a node.
+ */
+interface CircuitState {
+    /** Number of consecutive failures */
+    failures: number;
+    /** Timestamp of last failure */
+    lastFailure: number;
+    /** Current circuit state */
+    state: 'closed' | 'open' | 'half-open';
+}
+/**
+ * Routing metrics for monitoring smart routing effectiveness.
+ */
+interface RoutingMetrics {
+    /** Operations routed directly to partition owner */
+    directRoutes: number;
+    /** Operations falling back to any node (owner unavailable) */
+    fallbackRoutes: number;
+    /** Operations when partition map is missing/stale */
+    partitionMisses: number;
+    /** Total routing decisions made */
+    totalRoutes: number;
+}
+type ClusterRoutingMode = 'direct' | 'forward';
+/**
+ * ClusterClient implements IConnectionProvider for multi-node cluster mode.
+ * It provides partition-aware routing and connection management.
+ */
+declare class ClusterClient implements IConnectionProvider {
+    private readonly listeners;
+    private readonly connectionPool;
+    private readonly partitionRouter;
+    private readonly config;
+    private initialized;
+    private routingActive;
+    private readonly routingMetrics;
+    private readonly circuits;
+    private readonly circuitBreakerConfig;
+    constructor(config: ClusterClientConfig);
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeAllListeners(event?: string): this;
+    /**
+     * Connect to cluster nodes (IConnectionProvider interface).
+     * Alias for start() method.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key (IConnectionProvider interface).
+     * Routes to partition owner based on key hash when smart routing is enabled.
+     * @throws Error if not connected
+     */
+    getConnection(key: string): WebSocket;
+    /**
+     * Get fallback connection when owner is unavailable.
+     * @throws Error if no connection available
+     */
+    private getFallbackConnection;
+    /**
+     * Request a partition map refresh in the background.
+     * Called when routing to an unknown/disconnected owner.
+     */
+    private requestPartitionMapRefresh;
+    /**
+     * Request partition map from a specific node.
+     * Called on first node connection.
+     */
+    private requestPartitionMapFromNode;
+    /**
+     * Check if at least one connection is active (IConnectionProvider interface).
+     */
+    isConnected(): boolean;
+    /**
+     * Send data via the appropriate connection (IConnectionProvider interface).
+     * Routes based on key if provided.
+     */
+    send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Send data with automatic retry and rerouting on failure.
+     * @param data - Data to send
+     * @param key - Optional key for routing
+     * @param options - Retry options
+     * @throws Error after max retries exceeded
+     */
+    sendWithRetry(data: ArrayBuffer | Uint8Array, key?: string, options?: {
+        maxRetries?: number;
+        retryDelayMs?: number;
+        retryOnNotOwner?: boolean;
+    }): Promise<void>;
+    /**
+     * Check if an error is retryable.
+     */
+    private isRetryableError;
+    /**
+     * Wait for partition map update.
+     */
+    private waitForPartitionMapUpdateInternal;
+    /**
+     * Wait for at least one connection to be available.
+     */
+    private waitForConnectionInternal;
+    /**
+     * Helper delay function.
+     */
+    private delay;
+    /**
+     * Initialize cluster connections
+     */
+    start(): Promise<void>;
+    /**
+     * Set authentication token
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Send operation with automatic routing (legacy API for cluster operations).
+     * @deprecated Use send(data, key) for IConnectionProvider interface
+     */
+    sendMessage(key: string, message: any): boolean;
+    /**
+     * Send directly to partition owner
+     */
+    sendDirect(key: string, message: any): boolean;
+    /**
+     * Send to primary node for server-side forwarding
+     */
+    sendForward(message: any): boolean;
+    /**
+     * Send batch of operations with routing
+     */
+    sendBatch(operations: Array<{
+        key: string;
+        message: any;
+    }>): Map<string, boolean>;
+    /**
+     * Get connection pool health status
+     */
+    getHealthStatus(): Map<string, NodeHealth>;
+    /**
+     * Get partition router stats
+     */
+    getRouterStats(): ReturnType<PartitionRouter['getStats']>;
+    /**
+     * Get routing metrics for monitoring smart routing effectiveness.
+     */
+    getRoutingMetrics(): RoutingMetrics;
+    /**
+     * Reset routing metrics counters.
+     * Useful for monitoring intervals.
+     */
+    resetRoutingMetrics(): void;
+    /**
+     * Check if cluster routing is active
+     */
+    isRoutingActive(): boolean;
+    /**
+     * Get list of connected nodes
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Check if cluster client is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Force refresh of partition map
+     */
+    refreshPartitionMap(): Promise<void>;
+    /**
+     * Shutdown cluster client (IConnectionProvider interface).
+     */
+    close(): Promise<void>;
+    /**
+     * Get the connection pool (for internal use)
+     */
+    getConnectionPool(): ConnectionPool;
+    /**
+     * Get the partition router (for internal use)
+     */
+    getPartitionRouter(): PartitionRouter;
+    /**
+     * Get any healthy WebSocket connection (IConnectionProvider interface).
+     * @throws Error if not connected
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Get any healthy WebSocket connection, or null if none available.
+     * Use this for optional connection checks.
+     */
+    getAnyConnectionOrNull(): WebSocket | null;
+    /**
+     * Get circuit breaker state for a node.
+     */
+    getCircuit(nodeId: string): CircuitState;
+    /**
+     * Check if a node can be used (circuit not open).
+     */
+    canUseNode(nodeId: string): boolean;
+    /**
+     * Record a successful operation to a node.
+     * Resets circuit breaker on success.
+     */
+    recordSuccess(nodeId: string): void;
+    /**
+     * Record a failed operation to a node.
+     * Opens circuit breaker after threshold failures.
+     */
+    recordFailure(nodeId: string): void;
+    /**
+     * Get all circuit breaker states.
+     */
+    getCircuitStates(): Map<string, CircuitState>;
+    /**
+     * Reset circuit breaker for a specific node.
+     */
+    resetCircuit(nodeId: string): void;
+    /**
+     * Reset all circuit breakers.
+     */
+    resetAllCircuits(): void;
+    private setupEventHandlers;
+    private waitForPartitionMap;
+}
+
+/**
+ * SingleServerProvider implements IConnectionProvider for single-server mode.
+ *
+ * This is an adapter that wraps direct WebSocket connection handling,
+ * providing the same interface used by ClusterClient for multi-node mode.
+ */
+declare class SingleServerProvider implements IConnectionProvider {
+    private readonly url;
+    private readonly config;
+    private ws;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private isClosing;
+    private listeners;
+    constructor(config: SingleServerProviderConfig);
+    /**
+     * Connect to the WebSocket server.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key.
+     * In single-server mode, key is ignored.
+     */
+    getConnection(_key: string): WebSocket;
+    /**
+     * Get any available connection.
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Check if connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Get connected node IDs.
+     * Single-server mode returns ['default'] when connected.
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Subscribe to connection events.
+     */
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Unsubscribe from connection events.
+     */
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Send data via the WebSocket connection.
+     * In single-server mode, key parameter is ignored.
+     */
+    send(data: ArrayBuffer | Uint8Array, _key?: string): void;
+    /**
+     * Close the WebSocket connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Emit an event to all listeners.
+     */
+    private emit;
+    /**
+     * Schedule a reconnection attempt with exponential backoff.
+     */
+    private scheduleReconnect;
+    /**
+     * Calculate backoff delay with exponential increase.
+     */
+    private calculateBackoffDelay;
+    /**
+     * Get the WebSocket URL this provider connects to.
+     */
+    getUrl(): string;
+    /**
+     * Get current reconnection attempt count.
+     */
+    getReconnectAttempts(): number;
+    /**
+     * Reset reconnection counter.
+     * Called externally after successful authentication.
+     */
+    resetReconnectAttempts(): void;
+}
+
 declare const logger: pino.Logger<never, boolean>;
 
-export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, DEFAULT_BACKPRESSURE_CONFIG, EncryptedStorageAdapter, type HeartbeatConfig, IDBAdapter, type IStorageAdapter, type OpLogEntry, type OperationDroppedEvent, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };
+export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, type HeartbeatConfig, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type OpLogEntry, type OperationDroppedEvent, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RoutingMetrics, type RoutingResult, SingleServerProvider, type SingleServerProviderConfig, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopGunClientConfig, type TopGunClusterConfig, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };