@affectively/dash 5.3.1 → 5.4.1

package/dist/src/sync/hybrid-provider.d.ts

@@ -0,0 +1,307 @@
+import * as Y from 'yjs';
+import { Observable } from 'lib0/observable';
+import * as awarenessProtocol from 'y-protocols/awareness';
+import { type AeonConfig } from './aeon/config.js';
+import { DashDeltaAdapter } from './aeon/delta-adapter.js';
+import { DashPresenceAdapter } from './aeon/presence-adapter.js';
+import { DashOfflineAdapter } from './aeon/offline-adapter.js';
+export declare class HybridProvider extends Observable<string> {
+    private doc;
+    private ws;
+    private wt;
+    private connected;
+    private url;
+    private activeRelayUrl;
+    private roomName;
+    awareness: awarenessProtocol.Awareness;
+    private writer;
+    private highFrequencyMode;
+    private connectionState;
+    private reconnectAttempts;
+    private readonly maxReconnectDelay;
+    private readonly baseReconnectDelay;
+    private reconnectTimeout;
+    private relayDiscovery;
+    private discoveredRelayUrls;
+    private relayDiscoveryCursor;
+    private lastRelayDiscoveryAt;
+    private relayHealth;
+    private relayPerformance;
+    private compressionEngine;
+    private adaptiveCompression;
+    private batchTiming;
+    private outboundQueue;
+    private outboundQueueBytes;
+    private batchFlushTimeout;
+    private flushingBatch;
+    private lastCompressionRatio;
+    private relayPrivacy;
+    private roomCryptoKey;
+    private roomCryptoKeyReady;
+    private localCapabilitiesBitmask;
+    private peerCapabilities;
+    private protocolVersion;
+    private lastCapabilityAdvertisedAt;
+    private aeonConfig;
+    private deltaAdapter;
+    private presenceAdapter;
+    private offlineAdapter;
+    constructor(url: string, roomName: string, doc: Y.Doc, { awareness, aeonConfig, relayDiscovery, relayPerformance, relayPrivacy, }?: {
+        awareness?: awarenessProtocol.Awareness;
+        aeonConfig?: AeonConfig;
+        relayDiscovery?: RelayDiscoveryConfig;
+        relayPerformance?: RelayPerformanceConfig;
+        relayPrivacy?: RelayPrivacyConfig;
+    });
+    private connect;
+    private connectWebSocket;
+    /**
+     * Schedule reconnection with exponential backoff + jitter
+     * Prevents thundering herd on network flapping
+     */
+    private scheduleReconnect;
+    private seedAdaptiveNetworkProfile;
+    private initializeRoomCryptoKey;
+    private getRoomCryptoKey;
+    private computeLocalCapabilities;
+    private getKnownRemoteClientIds;
+    private isCapabilityEnabled;
+    private capabilityListFromBitmask;
+    private sendCapabilitiesAdvertisement;
+    private reconcilePeerCapabilities;
+    private getAuthToken;
+    private resolveRelayUrl;
+    private discoverRelayUrls;
+    private fetchRelayCandidates;
+    private rankRelayUrls;
+    private scoreRelay;
+    private recordRelaySuccess;
+    private recordRelayFailure;
+    enterHighFrequencyMode(): Promise<void>;
+    private sendSyncStep1;
+    /**
+     * Read loop for WebTransport with dynamic buffer sizing
+     * Handles payloads larger than initial buffer
+     */
+    private readLoop;
+    /**
+     * Handle incoming message with protocol validation
+     * Never silently ignores malformed messages
+     */
+    private handleMessage;
+    /**
+     * Send message with error handling and offline queue fallback
+     * Never fails silently - either sends, queues, or throws
+     */
+    private send;
+    private enqueueOutbound;
+    private scheduleBatchFlush;
+    private flushOutboundQueue;
+    private encodeBatchFrame;
+    private applyOutboundPipeline;
+    private maybeCompressPayload;
+    private decompressPayload;
+    private maybeEncryptPayload;
+    private decryptPayload;
+    private sendSingleFrame;
+    /**
+     * Queue message for offline sync
+     */
+    private queueForOffline;
+    private onDocUpdate;
+    private onAwarenessUpdate;
+    destroy(): void;
+    /**
+     * Get the delta adapter for compression stats
+     */
+    getDeltaAdapter(): DashDeltaAdapter | null;
+    /**
+     * Get the presence adapter for rich presence features
+     */
+    getPresenceAdapter(): DashPresenceAdapter | null;
+    /**
+     * Get the offline adapter for queue management
+     */
+    getOfflineAdapter(): DashOfflineAdapter | null;
+    /**
+     * Get Aeon configuration
+     */
+    getAeonConfig(): AeonConfig;
+    /**
+     * Process offline queue when back online
+     */
+    processOfflineQueue(): Promise<{
+        synced: number;
+        failed: number;
+    }>;
+    /**
+     * Get comprehensive connection status
+     */
+    getConnectionStatus(): ConnectionStatus;
+    /**
+     * Force immediate reconnection (resets backoff)
+     * Use when user explicitly requests reconnect
+     */
+    forceReconnect(): void;
+    /**
+     * Get all awareness states from connected peers
+     */
+    getAwarenessStates(): AwarenessState[];
+    /**
+     * Get the local client ID
+     */
+    getLocalClientId(): number;
+    /**
+     * Get connected peer count (excluding local)
+     */
+    getPeerCount(): number;
+    /**
+     * Get document state information
+     */
+    getDocumentState(): DocumentState;
+    /**
+     * Get a snapshot of the Yjs document for inspection
+     */
+    getDocumentSnapshot(): DocumentSnapshot;
+    /**
+     * Set local awareness state for introspection (admin view)
+     */
+    setLocalAwareness(state: Record<string, unknown>): void;
+    /**
+     * Get full provider status for debugging
+     */
+    getProviderStatus(): ProviderStatus;
+    /**
+     * Get Aeon-specific status
+     */
+    getAeonStatus(): AeonStatus;
+}
+export interface ConnectionStatus {
+    connected: boolean;
+    connectionState: 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+    roomName: string;
+    url: string;
+    reconnectAttempts: number;
+    websocket: {
+        state: 'connecting' | 'open' | 'closing' | 'closed';
+        connected: boolean;
+        bufferedAmount: number;
+    };
+    webTransport: {
+        connected: boolean;
+        highFrequencyMode: boolean;
+    };
+    discovery: {
+        enabled: boolean;
+        knownRelays: number;
+        lastDiscoveryAt: number | null;
+        targetPeerId: string;
+    };
+    performance: {
+        batching: boolean;
+        adaptiveCompression: boolean;
+        activeBatching: boolean;
+        activeCompression: boolean;
+        queuedFrames: number;
+        lastCompressionRatio: number | null;
+    };
+    privacy: {
+        enabled: boolean;
+        keyLoaded: boolean;
+        activeEncryption: boolean;
+    };
+    protocol: {
+        version: number;
+        localCapabilities: string[];
+        knownPeers: number;
+    };
+    transport: 'WebSocket' | 'WebTransport';
+}
+export interface RelayDiscoveryConfig {
+    enabled?: boolean;
+    bootstrapUrls?: string[];
+    discoveryPath?: string;
+    refreshIntervalMs?: number;
+    requestTimeoutMs?: number;
+    maxCandidates?: number;
+    dhtQueryEnabled?: boolean;
+    targetPeerId?: string;
+}
+export interface RelayPerformanceConfig {
+    enableAdaptiveCompression?: boolean;
+    enableBatching?: boolean;
+    compressionThresholdBytes?: number;
+    maxBatchDelayMs?: number;
+    maxBatchSizeBytes?: number;
+}
+export interface RelayPrivacyConfig {
+    enabled?: boolean;
+    roomKey?: string | Uint8Array;
+}
+export interface AwarenessState {
+    clientId: number;
+    state: Record<string, unknown>;
+    isLocal: boolean;
+}
+export interface SharedTypeInfo {
+    name: string;
+    type: 'YMap' | 'YArray' | 'YText' | 'YXmlFragment' | 'unknown';
+    size: number;
+}
+export interface DocumentState {
+    clientId: number;
+    guid: string;
+    stateVectorSize: number;
+    updateSize: number;
+    sharedTypes: SharedTypeInfo[];
+    transactionCount: number;
+    gcEnabled: boolean;
+}
+export interface DocumentSnapshot {
+    timestamp: string;
+    roomName: string;
+    content: Record<string, unknown>;
+}
+export interface ProviderStatus {
+    connection: ConnectionStatus;
+    awareness: {
+        localClientId: number;
+        peerCount: number;
+        states: AwarenessState[];
+    };
+    document: DocumentState;
+    aeon: AeonStatus;
+}
+export interface AeonStatus {
+    enabled: {
+        deltaSync: boolean;
+        richPresence: boolean;
+        offlineQueue: boolean;
+    };
+    delta: {
+        totalOperations: number;
+        totalFull: number;
+        totalDelta: number;
+        totalOriginalSize: number;
+        totalDeltaSize: number;
+        averageReductionPercent: number;
+    } | null;
+    offline: {
+        pending: number;
+        syncing: number;
+        failed: number;
+        synced: number;
+        totalOperations: number;
+    } | null;
+    presence: {
+        total: number;
+        online: number;
+        away: number;
+        offline: number;
+    } | null;
+    compression: {
+        averageCompressionMs: number;
+        averageRatio: number;
+        networkCondition: 'fast' | 'normal' | 'slow' | 'offline';
+    } | null;
+}