@topgunbuild/client 0.10.1 → 0.11.0

package/dist/index.d.mts

@@ -2692,6 +2692,207 @@ declare class SingleServerProvider implements IConnectionProvider {
     resetReconnectAttempts(): void;
 }
 
+/**
+ * Configuration for HttpSyncProvider.
+ */
+interface HttpSyncProviderConfig {
+    /** HTTP URL of the TopGun server (e.g., 'http://localhost:8080') */
+    url: string;
+    /** Client identifier for the server to track HLC state */
+    clientId: string;
+    /** Hybrid Logical Clock instance for causality tracking */
+    hlc: HLC;
+    /** JWT auth token for Authorization header */
+    authToken?: string;
+    /** Polling interval in milliseconds (default: 5000) */
+    pollIntervalMs?: number;
+    /** HTTP request timeout in milliseconds (default: 30000) */
+    requestTimeoutMs?: number;
+    /** Map names to sync deltas for on each poll */
+    syncMaps?: string[];
+    /** Custom fetch implementation for testing or platform compatibility */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * HTTP-based connection provider for serverless environments.
+ *
+ * Implements IConnectionProvider by translating WebSocket-style send() calls
+ * into queued operations that are flushed via HTTP POST /sync at regular
+ * polling intervals. Responses are translated back into synthetic message
+ * events that SyncEngine understands.
+ *
+ * This provider is completely stateless on the server side -- each request
+ * carries the client's HLC state and the server computes deltas without
+ * maintaining per-client state.
+ */
+declare class HttpSyncProvider implements IConnectionProvider {
+    private readonly url;
+    private readonly clientId;
+    private readonly hlc;
+    private readonly pollIntervalMs;
+    private readonly requestTimeoutMs;
+    private readonly syncMaps;
+    private readonly fetchImpl;
+    private authToken;
+    private listeners;
+    private pollTimer;
+    /** Queued operations to send on next poll */
+    private pendingOperations;
+    /** Queued one-shot queries to send on next poll */
+    private pendingQueries;
+    /** Per-map last sync timestamps for delta tracking */
+    private lastSyncTimestamps;
+    /** Whether the last HTTP request succeeded */
+    private connected;
+    /** Whether we were previously connected (for reconnected event) */
+    private wasConnected;
+    constructor(config: HttpSyncProviderConfig);
+    /**
+     * Connect by sending an initial sync request to verify auth and get state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key.
+     * HTTP mode does not expose raw WebSocket connections.
+     */
+    getConnection(_key: string): WebSocket;
+    /**
+     * Get any available connection.
+     * HTTP mode does not expose raw WebSocket connections.
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Check if connected (last HTTP request succeeded).
+     */
+    isConnected(): boolean;
+    /**
+     * Get connected node IDs.
+     * Returns ['http'] when connected, [] when not.
+     */
+    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 HTTP sync provider.
+     *
+     * Deserializes the msgpackr binary to extract the message type and routes:
+     * - OP_BATCH / CLIENT_OP: queued as operations for next poll
+     * - AUTH: silently ignored (auth via HTTP header)
+     * - SYNC_INIT: silently ignored (HTTP uses timestamp-based deltas)
+     * - QUERY_SUB: queued as one-shot query for next poll
+     * - All other types: silently dropped with debug log
+     */
+    send(data: ArrayBuffer | Uint8Array, _key?: string): void;
+    /**
+     * Close the HTTP sync provider.
+     * Stops the polling loop, clears queued operations, and sets disconnected state.
+     */
+    close(): Promise<void>;
+    /**
+     * Update the auth token (e.g., after token refresh).
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Send an HTTP sync request with queued operations and receive deltas.
+     */
+    private doSyncRequest;
+    /**
+     * Start the polling loop.
+     */
+    private startPolling;
+    /**
+     * Stop the polling loop.
+     */
+    private stopPolling;
+    /**
+     * Emit an event to all listeners.
+     */
+    private emit;
+}
+
+/**
+ * Configuration for AutoConnectionProvider.
+ */
+interface AutoConnectionProviderConfig {
+    /** Server URL (ws:// or http://) */
+    url: string;
+    /** Client identifier */
+    clientId: string;
+    /** Hybrid Logical Clock instance */
+    hlc: HLC;
+    /** Max WebSocket connection attempts before falling back to HTTP (default: 3) */
+    maxWsAttempts?: number;
+    /** JWT auth token */
+    authToken?: string;
+    /** Skip WebSocket and go HTTP-only */
+    httpOnly?: boolean;
+    /** HTTP polling interval in ms (default: 5000) */
+    httpPollIntervalMs?: number;
+    /** Map names to sync via HTTP */
+    syncMaps?: string[];
+    /** Custom fetch implementation for HTTP mode */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * AutoConnectionProvider implements protocol negotiation by trying WebSocket
+ * first and falling back to HTTP sync when WebSocket connection fails.
+ *
+ * This enables seamless deployment in both traditional server environments
+ * (using WebSockets) and serverless environments (using HTTP polling).
+ */
+declare class AutoConnectionProvider implements IConnectionProvider {
+    private readonly config;
+    private readonly maxWsAttempts;
+    /** The active underlying provider */
+    private activeProvider;
+    /** Whether we're using HTTP mode */
+    private isHttpMode;
+    private listeners;
+    constructor(config: AutoConnectionProviderConfig);
+    /**
+     * Connect using WebSocket first, falling back to HTTP after maxWsAttempts failures.
+     * If httpOnly is true, skips WebSocket entirely.
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect using HTTP sync provider.
+     */
+    private connectHttp;
+    getConnection(key: string): WebSocket;
+    getAnyConnection(): WebSocket;
+    isConnected(): boolean;
+    getConnectedNodes(): string[];
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Close the active underlying provider.
+     */
+    close(): Promise<void>;
+    /**
+     * Whether currently using HTTP mode.
+     */
+    isUsingHttp(): boolean;
+    /**
+     * Proxy events from the underlying provider to our listeners.
+     */
+    private proxyEvents;
+    /**
+     * Convert a URL to WebSocket URL format.
+     */
+    private toWsUrl;
+    /**
+     * Convert a URL to HTTP URL format.
+     */
+    private toHttpUrl;
+}
+
 declare const logger: pino.Logger<never, boolean>;
 
-export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, 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 };
+export { AutoConnectionProvider, type AutoConnectionProviderConfig, type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, HttpSyncProvider, type HttpSyncProviderConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, 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 };

package/dist/index.d.ts

@@ -2692,6 +2692,207 @@ declare class SingleServerProvider implements IConnectionProvider {
     resetReconnectAttempts(): void;
 }
 
+/**
+ * Configuration for HttpSyncProvider.
+ */
+interface HttpSyncProviderConfig {
+    /** HTTP URL of the TopGun server (e.g., 'http://localhost:8080') */
+    url: string;
+    /** Client identifier for the server to track HLC state */
+    clientId: string;
+    /** Hybrid Logical Clock instance for causality tracking */
+    hlc: HLC;
+    /** JWT auth token for Authorization header */
+    authToken?: string;
+    /** Polling interval in milliseconds (default: 5000) */
+    pollIntervalMs?: number;
+    /** HTTP request timeout in milliseconds (default: 30000) */
+    requestTimeoutMs?: number;
+    /** Map names to sync deltas for on each poll */
+    syncMaps?: string[];
+    /** Custom fetch implementation for testing or platform compatibility */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * HTTP-based connection provider for serverless environments.
+ *
+ * Implements IConnectionProvider by translating WebSocket-style send() calls
+ * into queued operations that are flushed via HTTP POST /sync at regular
+ * polling intervals. Responses are translated back into synthetic message
+ * events that SyncEngine understands.
+ *
+ * This provider is completely stateless on the server side -- each request
+ * carries the client's HLC state and the server computes deltas without
+ * maintaining per-client state.
+ */
+declare class HttpSyncProvider implements IConnectionProvider {
+    private readonly url;
+    private readonly clientId;
+    private readonly hlc;
+    private readonly pollIntervalMs;
+    private readonly requestTimeoutMs;
+    private readonly syncMaps;
+    private readonly fetchImpl;
+    private authToken;
+    private listeners;
+    private pollTimer;
+    /** Queued operations to send on next poll */
+    private pendingOperations;
+    /** Queued one-shot queries to send on next poll */
+    private pendingQueries;
+    /** Per-map last sync timestamps for delta tracking */
+    private lastSyncTimestamps;
+    /** Whether the last HTTP request succeeded */
+    private connected;
+    /** Whether we were previously connected (for reconnected event) */
+    private wasConnected;
+    constructor(config: HttpSyncProviderConfig);
+    /**
+     * Connect by sending an initial sync request to verify auth and get state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key.
+     * HTTP mode does not expose raw WebSocket connections.
+     */
+    getConnection(_key: string): WebSocket;
+    /**
+     * Get any available connection.
+     * HTTP mode does not expose raw WebSocket connections.
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Check if connected (last HTTP request succeeded).
+     */
+    isConnected(): boolean;
+    /**
+     * Get connected node IDs.
+     * Returns ['http'] when connected, [] when not.
+     */
+    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 HTTP sync provider.
+     *
+     * Deserializes the msgpackr binary to extract the message type and routes:
+     * - OP_BATCH / CLIENT_OP: queued as operations for next poll
+     * - AUTH: silently ignored (auth via HTTP header)
+     * - SYNC_INIT: silently ignored (HTTP uses timestamp-based deltas)
+     * - QUERY_SUB: queued as one-shot query for next poll
+     * - All other types: silently dropped with debug log
+     */
+    send(data: ArrayBuffer | Uint8Array, _key?: string): void;
+    /**
+     * Close the HTTP sync provider.
+     * Stops the polling loop, clears queued operations, and sets disconnected state.
+     */
+    close(): Promise<void>;
+    /**
+     * Update the auth token (e.g., after token refresh).
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Send an HTTP sync request with queued operations and receive deltas.
+     */
+    private doSyncRequest;
+    /**
+     * Start the polling loop.
+     */
+    private startPolling;
+    /**
+     * Stop the polling loop.
+     */
+    private stopPolling;
+    /**
+     * Emit an event to all listeners.
+     */
+    private emit;
+}
+
+/**
+ * Configuration for AutoConnectionProvider.
+ */
+interface AutoConnectionProviderConfig {
+    /** Server URL (ws:// or http://) */
+    url: string;
+    /** Client identifier */
+    clientId: string;
+    /** Hybrid Logical Clock instance */
+    hlc: HLC;
+    /** Max WebSocket connection attempts before falling back to HTTP (default: 3) */
+    maxWsAttempts?: number;
+    /** JWT auth token */
+    authToken?: string;
+    /** Skip WebSocket and go HTTP-only */
+    httpOnly?: boolean;
+    /** HTTP polling interval in ms (default: 5000) */
+    httpPollIntervalMs?: number;
+    /** Map names to sync via HTTP */
+    syncMaps?: string[];
+    /** Custom fetch implementation for HTTP mode */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * AutoConnectionProvider implements protocol negotiation by trying WebSocket
+ * first and falling back to HTTP sync when WebSocket connection fails.
+ *
+ * This enables seamless deployment in both traditional server environments
+ * (using WebSockets) and serverless environments (using HTTP polling).
+ */
+declare class AutoConnectionProvider implements IConnectionProvider {
+    private readonly config;
+    private readonly maxWsAttempts;
+    /** The active underlying provider */
+    private activeProvider;
+    /** Whether we're using HTTP mode */
+    private isHttpMode;
+    private listeners;
+    constructor(config: AutoConnectionProviderConfig);
+    /**
+     * Connect using WebSocket first, falling back to HTTP after maxWsAttempts failures.
+     * If httpOnly is true, skips WebSocket entirely.
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect using HTTP sync provider.
+     */
+    private connectHttp;
+    getConnection(key: string): WebSocket;
+    getAnyConnection(): WebSocket;
+    isConnected(): boolean;
+    getConnectedNodes(): string[];
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Close the active underlying provider.
+     */
+    close(): Promise<void>;
+    /**
+     * Whether currently using HTTP mode.
+     */
+    isUsingHttp(): boolean;
+    /**
+     * Proxy events from the underlying provider to our listeners.
+     */
+    private proxyEvents;
+    /**
+     * Convert a URL to WebSocket URL format.
+     */
+    private toWsUrl;
+    /**
+     * Convert a URL to HTTP URL format.
+     */
+    private toHttpUrl;
+}
+
 declare const logger: pino.Logger<never, boolean>;
 
-export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, 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 };
+export { AutoConnectionProvider, type AutoConnectionProviderConfig, type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, HttpSyncProvider, type HttpSyncProviderConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, 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 };