@cendarsoss/pusher-js 8.4.11

package/LIBRARY_STRUCTURE_ANALYSIS.md

@@ -0,0 +1,940 @@
+# Pusher-JS Library Structure Analysis
+
+## Overview
+This document provides a comprehensive analysis of the pusher-js library architecture, focusing on areas relevant for implementing delta compression and rate cache sync features.
+
+**Library**: pusher-js v8.4.0  
+**Type**: Real-time messaging client for browsers, React Native, Node.js  
+**Architecture**: Event-driven, multi-transport with WebSocket and HTTP fallback
+
+---
+
+## 1. Main Library Structure and Entry Points
+
+### Root Entry Point: `/src/core/pusher.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\pusher.ts`
+
+**Key Responsibilities**:
+- Main Pusher class that serves as the public API entry point
+- Creates and manages connection, channels, and events dispatcher
+- Manages channel subscriptions and event forwarding
+- Handles session ID generation and timeline tracking
+
+**Key Properties**:
+```typescript
+export default class Pusher {
+  key: string;                           // Application key
+  config: Config;                        // Connection configuration
+  channels: Channels;                    // Channel management
+  global_emitter: EventsDispatcher;      // Global event dispatcher
+  sessionID: number;                     // Unique session identifier
+  timeline: Timeline;                    // Event timeline for debugging
+  timelineSender: TimelineSender;        // Stats transmission
+  connection: ConnectionManager;         // Connection lifecycle manager
+  user: UserFacade;                      // User authentication
+}
+```
+
+**Key Methods**:
+- `subscribe(channel_name)` - Subscribe to a channel
+- `unsubscribe(channel_name)` - Unsubscribe from a channel
+- `send_event(event_name, data, channel)` - Send client event
+- `bind(event_name, callback)` - Bind to global events
+- `channel(name)` - Get channel instance
+
+**Message Flow in Constructor**:
+```typescript
+this.connection.bind('message', (event) => {
+  var eventName = event.event;
+  var internal = eventName.indexOf('pusher_internal:') === 0;
+  if (event.channel) {
+    var channel = this.channel(event.channel);
+    if (channel) {
+      channel.handleEvent(event);  // Delegate to channel
+    }
+  }
+  // Emit globally [deprecated]
+  if (!internal) {
+    this.global_emitter.emit(event.event, event.data);
+  }
+});
+```
+
+---
+
+## 2. Protocol Messages Handling
+
+### Message Type Definitions: `/src/core/connection/protocol/message-types.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\connection\protocol\message-types.ts`
+
+**Core Message Structure**:
+```typescript
+interface PusherEvent {
+  event: string;        // Event name
+  channel?: string;     // Channel name (optional)
+  data?: any;          // Event payload
+  user_id?: string;    // User ID for presence channels (optional)
+}
+```
+
+### Protocol Handler: `/src/core/connection/protocol/protocol.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\connection\protocol\protocol.ts`
+
+**Responsibilities**:
+- Encode/decode messages in Pusher format
+- Process handshake messages
+- Handle close event actions and error classification
+
+**Key Functions**:
+
+1. **decodeMessage(messageEvent: MessageEvent): PusherEvent**
+   - Parses incoming WebSocket message
+   - Handles nested JSON data in pusher event data field
+   - Throws `MessageParseError` on invalid JSON
+   - **Integration Point**: Messages arrive as JSON strings, need decompression BEFORE this step
+
+2. **encodeMessage(event: PusherEvent): string**
+   - Serializes Pusher events to JSON
+   - **Integration Point**: Delta compression could be applied AFTER this step
+
+3. **processHandshake(messageEvent): Action**
+   - Processes connection_established or error messages
+   - Returns action with socket_id and activityTimeout
+   - **Relevant for**: Cache sync initialization
+
+4. **getCloseAction(closeEvent): string**
+   - Maps close codes to actions: 'connected', 'refused', 'backoff', 'retry', 'tls_only'
+
+**Example Message Flow**:
+```
+Raw WebSocket data: '{"event":"pusher:subscribe","data":{"auth":"xyz"}}'
+                    ↓
+            Protocol.decodeMessage()
+                    ↓
+Decoded PusherEvent: {event: "pusher:subscribe", data: {auth: "xyz"}}
+                    ↓
+            Channel.handleEvent()
+```
+
+---
+
+## 3. Channel Subscriptions and Event Processing
+
+### Channel Management: `/src/core/channels/channels.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\channels\channels.ts`
+
+**Responsibilities**:
+- Maintains channel registry/map
+- Creates appropriate channel type (public/private/presence/encrypted)
+- Proxies disconnect signals to all channels
+
+**Key Methods**:
+```typescript
+class Channels {
+  channels: ChannelTable;  // Dictionary of channels
+  
+  add(name: string, pusher: Pusher): Channel      // Create/retrieve
+  find(name: string): Channel                     // Lookup
+  remove(name: string): Channel                   // Delete
+  all(): Channel[]                                // Get all
+  disconnect(): void                             // Disconnect all
+}
+```
+
+**Channel Type Factory** (in `createChannel()`):
+- `private-encrypted-*` → EncryptedChannel (with nacl)
+- `private-*` → PrivateChannel
+- `presence-*` → PresenceChannel
+- others → Channel (public)
+
+### Base Channel Class: `/src/core/channels/channel.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\channels\channel.ts`
+
+**Extends**: EventsDispatcher (inherits emit/bind/unbind)
+
+**State Management**:
+```typescript
+class Channel extends EventsDispatcher {
+  name: string;
+  pusher: Pusher;
+  subscribed: boolean;              // Currently subscribed
+  subscriptionPending: boolean;     // Subscription in progress
+  subscriptionCancelled: boolean;   // Pending cancellation
+  subscriptionCount: null;          // For subscription_count events
+}
+```
+
+**Key Methods - Event Handling**:
+
+1. **handleEvent(event: PusherEvent)**
+   - Routes internal vs. user events
+   - Handles special internal events: subscription_succeeded, subscription_count
+   - Emits user events with metadata
+   - **Integration Point**: Delta decompression should happen BEFORE this
+
+2. **handleSubscriptionSucceededEvent(event)**
+   - Updates subscribed state
+   - Emits 'pusher:subscription_succeeded'
+   - Handles subscription cancellation race condition
+
+3. **subscribe()**
+   - Authorizes via channel.authorize() callback
+   - Sends 'pusher:subscribe' message with auth data
+   - Handles authorization errors
+
+4. **trigger(event, data)**
+   - Client-side event publishing
+   - Validates event name starts with 'client-'
+   - Calls pusher.send_event()
+
+**Event Emission Flow**:
+```
+Connection → Pusher.message → Channel.handleEvent()
+                              ↓
+                    Is internal event?
+                    ↙              ↘
+                  NO               YES
+                  ↓                ↓
+         Emit user event    Handle internal
+         with metadata      (subscription_succeeded,
+                            subscription_count)
+```
+
+### Presence Channels: `/src/core/channels/presence_channel.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\channels\presence_channel.ts`
+
+**Extends**: PrivateChannel
+
+**Additional Responsibilities**:
+- Members state management
+- Presence event handling: member_added, member_removed
+- User ID association with presence data
+
+**Key Difference**:
+```typescript
+handleEvent(event: PusherEvent) {
+  // Includes metadata.user_id for presence events
+  var metadata: Metadata = {};
+  if (event.user_id) {
+    metadata.user_id = event.user_id;
+  }
+  this.emit(eventName, data, metadata);
+}
+```
+
+---
+
+## 4. Event Handling and Dispatch System
+
+### Event Dispatcher: `/src/core/events/dispatcher.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\events\dispatcher.ts`
+
+**Core Responsibility**: Manage callback bindings and event emission
+
+**Architecture**:
+```typescript
+class Dispatcher {
+  callbacks: CallbackRegistry;        // Event → [callbacks]
+  global_callbacks: Function[];       // Callbacks for all events
+  failThrough?: Function;             // Called if no callbacks bound
+}
+```
+
+**Key Methods**:
+
+1. **bind(eventName, callback, context?)**
+   - Register callback for specific event
+   - Maintains context binding
+   - Returns this (chainable)
+
+2. **bind_global(callback)**
+   - Register callback for ALL events
+   - Callback receives (eventName, data) arguments
+
+3. **emit(eventName, data?, metadata?)**
+   - Call all global callbacks: `global_callback(eventName, data)`
+   - Call event-specific callbacks: `callback(data, metadata?)`
+   - Falls back to failThrough if no callbacks
+   - **Integration Point**: Event data passes through here; compression/decompression happens before
+
+4. **unbind/unbind_global/unbind_all**
+   - Deregister callbacks
+
+**Emission Flow**:
+```typescript
+emit(eventName: string, data?: any, metadata?: Metadata): Dispatcher {
+  // 1. Call global callbacks
+  for (var i = 0; i < this.global_callbacks.length; i++) {
+    this.global_callbacks[i](eventName, data);
+  }
+  
+  // 2. Get event-specific callbacks
+  var callbacks = this.callbacks.get(eventName);
+  
+  // 3. Build arguments (data + metadata)
+  var args = [];
+  if (metadata) {
+    args.push(data, metadata);
+  } else if (data) {
+    args.push(data);
+  }
+  
+  // 4. Call all callbacks
+  if (callbacks && callbacks.length > 0) {
+    for (var i = 0; i < callbacks.length; i++) {
+      callbacks[i].fn.apply(callbacks[i].context || global, args);
+    }
+  } else if (this.failThrough) {
+    this.failThrough(eventName, data);
+  }
+  
+  return this;
+}
+```
+
+### Callback Registry: `/src/core/events/callback_registry.ts`
+**Manages**: Event name → [Callback objects]
+
+```typescript
+interface Callback {
+  fn: Function;
+  context?: any;
+}
+```
+
+---
+
+## 5. Connection Management and Message Flow
+
+### Connection Manager: `/src/core/connection/connection_manager.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\connection\connection_manager.ts`
+
+**Responsibilities**:
+- Lifecycle management (connecting, connected, disconnected, failed, unavailable)
+- Activity checks (ping/pong)
+- Strategy selection and execution
+- Network reachability monitoring
+- Error handling and retry logic
+
+**State Machine**:
+```
+initialized → connecting → connected → disconnected
+                  ↓ (error)
+            unavailable → connecting (retry)
+                  ↓ (strategy not supported)
+                failed
+```
+
+**Key Properties**:
+```typescript
+class ConnectionManager extends EventsDispatcher {
+  key: string;
+  state: string;                       // Current connection state
+  connection: Connection;              // Active connection
+  socket_id: string;                   // Socket ID from server
+  strategy: Strategy;                  // Transport selection strategy
+  runner: StrategyRunner;              // Active strategy runner
+  activityTimeout: number;             // Activity check interval
+  usingTLS: boolean;
+}
+```
+
+**Key Methods**:
+
+1. **connect()**
+   - Initiates connection attempt
+   - Updates state to 'connecting'
+   - Sets unavailableTimer
+
+2. **send(data)**
+   - Raw data transmission via active connection
+   - Returns false if no connection
+
+3. **send_event(name, data, channel?)**
+   - Event-level transmission
+   - Delegates to connection.send_event()
+
+4. **disconnect()**
+   - Graceful disconnection
+   - Updates state to 'disconnected'
+
+**Connection Callback Handlers**:
+```typescript
+private buildConnectionCallbacks(errorCallbacks): ConnectionCallbacks {
+  return {
+    message: (message) => {
+      // MAIN MESSAGE HANDLER
+      this.resetActivityCheck();
+      this.emit('message', message);  // Emitted to Pusher instance
+    },
+    ping: () => {
+      this.send_event('pusher:pong', {});  // Reply to server ping
+    },
+    activity: () => {
+      this.resetActivityCheck();  // Reset activity timer
+    },
+    error: (error) => {
+      this.emit('error', error);
+    },
+    closed: () => {
+      this.abandonConnection();
+      if (this.shouldRetry()) {
+        this.retryIn(1000);
+      }
+    },
+  };
+}
+```
+
+**Message Reception Flow**:
+```
+Transport receives data
+        ↓
+Connection.bindListeners (message handler)
+        ↓
+Protocol.decodeMessage(messageEvent)
+        ↓
+Connection emits 'message' with decoded PusherEvent
+        ↓
+ConnectionManager message callback
+        ↓
+ConnectionManager.emit('message', message)
+        ↓
+Pusher instance listens to connection 'message'
+        ↓
+Pusher delegates to Channel.handleEvent()
+```
+
+### Connection: `/src/core/connection/connection.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\connection\connection.ts`
+
+**Responsibilities**:
+- Protocol-level message handling
+- Transport abstraction
+- Ping/pong management
+- Error routing
+
+**Key Methods**:
+
+1. **send(data: any): boolean**
+   - Raw string/data transmission
+
+2. **send_event(name, data, channel?): boolean**
+   - Creates PusherEvent, encodes via Protocol.encodeMessage()
+   - Sends via transport
+
+3. **ping()**
+   - If transport supports native ping: use it
+   - Otherwise: send 'pusher:ping' event
+
+**Transport Listener Binding**:
+```typescript
+private bindListeners() {
+  var listeners = {
+    message: (messageEvent: MessageEvent) => {
+      var pusherEvent;
+      try {
+        pusherEvent = Protocol.decodeMessage(messageEvent);  // JSON parsing
+      } catch (e) {
+        this.emit('error', {
+          type: 'MessageParseError',
+          error: e,
+          data: messageEvent.data,
+        });
+      }
+
+      if (pusherEvent !== undefined) {
+        Logger.debug('Event recd', pusherEvent);
+
+        switch (pusherEvent.event) {
+          case 'pusher:error':
+            this.emit('error', {
+              type: 'PusherError',
+              data: pusherEvent.data,
+            });
+            break;
+          case 'pusher:ping':
+            this.emit('ping');
+            break;
+          case 'pusher:pong':
+            this.emit('pong');
+            break;
+        }
+        this.emit('message', pusherEvent);  // Main emission
+      }
+    },
+    // ... other listeners
+  };
+}
+```
+
+**Integration Point for Delta Compression**:
+After `Protocol.decodeMessage()` successfully parses JSON, the data needs decompression if it was compressed.
+
+---
+
+## 6. Existing Compression/Optimization Features
+
+### Transport Caching Strategy: `/src/core/strategies/websocket_prioritized_cached_strategy.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\strategies\websocket_prioritized_cached_strategy.ts`
+
+**Current Optimization**: Transport selection caching (not message compression)
+
+**What it Does**:
+- Caches the last successful transport (WebSocket vs HTTP fallback)
+- Stores in localStorage with TTL (default 30 minutes)
+- Skips cache after 3 failures to force re-evaluation
+- Measures latency for quick retry on subsequent connections
+
+**Cached Data Structure**:
+```typescript
+{
+  timestamp: number,          // When cached
+  transport: string,          // 'ws', 'wss', 'xhr_streaming', etc.
+  latency: number,           // Round-trip time in ms
+  cacheSkipCount: number,    // Failures before re-trying cache
+}
+```
+
+**Storage Key**: `'pusherTransport' + (usingTLS ? 'TLS' : 'NonTLS')`
+
+**Relevant Code**:
+```typescript
+function fetchTransportCache(usingTLS: boolean): any {
+  var storage = Runtime.getLocalStorage();
+  if (storage) {
+    try {
+      var serializedCache = storage[getTransportCacheKey(usingTLS)];
+      if (serializedCache) {
+        return JSON.parse(serializedCache);
+      }
+    } catch (e) {
+      flushTransportCache(usingTLS);
+    }
+  }
+  return null;
+}
+
+function storeTransportCache(
+  usingTLS: boolean,
+  transport: TransportStrategy,
+  latency: number,
+  cacheSkipCount: number,
+) {
+  var storage = Runtime.getLocalStorage();
+  if (storage) {
+    try {
+      storage[getTransportCacheKey(usingTLS)] = Collections.safeJSONStringify({
+        timestamp: Util.now(),
+        transport: transport,
+        latency: latency,
+        cacheSkipCount: cacheSkipCount,
+      });
+    } catch (e) {
+      // catch over quota exceptions
+    }
+  }
+}
+```
+
+### JSON Encoding/Decoding
+All messages use standard JSON serialization:
+
+**Protocol.encodeMessage()**:
+```typescript
+encodeMessage: function (event: PusherEvent): string {
+  return JSON.stringify(event);
+},
+```
+
+**Protocol.decodeMessage()**:
+```typescript
+decodeMessage: function (messageEvent: MessageEvent): PusherEvent {
+  try {
+    var messageData = JSON.parse(messageEvent.data);
+    var pusherEventData = messageData.data;
+    if (typeof pusherEventData === 'string') {
+      try {
+        pusherEventData = JSON.parse(messageData.data);  // Nested JSON
+      } catch (e) {}
+    }
+    // ... return PusherEvent
+  } catch (e) {
+    throw { type: 'MessageParseError', error: e, data: messageEvent.data };
+  }
+},
+```
+
+### Safe JSON Serialization: `/src/core/utils/collections.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\utils\collections.ts`
+
+**Function**: `safeJSONStringify(source: any): string`
+
+**Purpose**: Handle circular references (important for React Native)
+
+**Implementation**:
+```typescript
+export function safeJSONStringify(source: any): string {
+  try {
+    return JSON.stringify(source);
+  } catch (e) {
+    return JSON.stringify(decycleObject(source));
+  }
+}
+```
+
+Uses Douglas Crockford's cycle.js technique to break circular references before stringification.
+
+**Relevant for**: Compression should use safeJSONStringify to avoid issues with circular structures.
+
+---
+
+## 7. Data Structure and Message Metadata
+
+### Event Metadata: `/src/core/channels/metadata.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\channels/metadata.ts`
+
+```typescript
+interface Metadata {
+  user_id?: string;  // Present in presence channel events
+}
+```
+
+Used to pass additional context to event callbacks (especially for presence events).
+
+### Action Response: `/src/core/connection/protocol/action.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core\connection/protocol/action.ts`
+
+```typescript
+interface Action {
+  action: string;                  // 'connected', 'refused', 'backoff', etc.
+  id?: string;                     // socket_id
+  activityTimeout?: number;        // Server-specified activity timeout
+  error?: any;                     // Error details
+}
+```
+
+---
+
+## 8. Timeline/Diagnostics System
+
+### Timeline: `/src/core/timeline/timeline.ts`
+
+The library includes a diagnostics timeline system that tracks:
+- Connection events
+- Transport selection
+- Errors
+- Performance metrics
+- State transitions
+
+**Initialized in Pusher constructor**:
+```typescript
+this.timeline = new Timeline(this.key, this.sessionID, {
+  cluster: this.config.cluster,
+  features: Pusher.getClientFeatures(),
+  params: this.config.timelineParams || {},
+  limit: 50,
+  level: TimelineLevel.INFO,
+  version: Defaults.VERSION,
+});
+```
+
+Sent periodically (every 60 seconds) if `enableStats: true`.
+
+**Integration Point**: Could be used to track compression statistics and cache sync metrics.
+
+---
+
+## 9. Configuration and Defaults
+
+### Default Configuration: `/src/core/defaults.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core/defaults.ts`
+
+```typescript
+{
+  VERSION: string,
+  PROTOCOL: 7,
+  
+  // Timeouts
+  activityTimeout: 120000,      // 2 minutes
+  pongTimeout: 30000,           // 30 seconds
+  unavailableTimeout: 10000,    // 10 seconds
+  
+  // Transport ports
+  wsPort: 80,
+  wssPort: 443,
+  
+  // Endpoints
+  authEndpoint: '/pusher/auth',
+  stats_host: 'stats.pusher.com',
+}
+```
+
+### Config Builder: `/src/core/config.ts`
+**Path**: `C:\Users\radu0\Desktop\Code\Javascript\sockudo-js\src\core/config.ts`
+
+- Merges user options with defaults
+- Validates configuration
+- Builds authentication handlers
+
+---
+
+## 10. Integration Points for New Features
+
+### Delta Compression Integration Points
+
+**1. Outgoing Message Compression** (Client → Server):
+```
+Pusher.send_event() 
+  → Connection.send_event()
+    → Protocol.encodeMessage()  [returns JSON string]
+    → [COMPRESSION POINT] Apply delta compression
+    → Connection.send() [transmit compressed data]
+```
+
+**2. Incoming Message Decompression** (Server → Client):
+```
+Transport receives raw data
+  → Connection.bindListeners.message()
+    → [DECOMPRESSION POINT] Detect and decompress if needed
+    → Protocol.decodeMessage()  [parse JSON]
+    → Connection.emit('message', pusherEvent)
+    → ConnectionManager.message callback
+    → Pusher instance receives
+    → Channel.handleEvent()
+    → Dispatcher.emit() [call user callbacks]
+```
+
+**Implementation Locations**:
+1. **Compression/Decompression Module**: New utility in `/src/core/compression/` or `/src/core/utils/compression.ts`
+2. **Connection.send_event()**: Add compression before `this.send()`
+3. **Connection.bindListeners()**: Add decompression in message handler before `Protocol.decodeMessage()`
+4. **Protocol**: Optional - add compression support flags to protocol
+
+### Rate Cache Sync Integration Points
+
+**1. Cache Storage**:
+- Use existing localStorage pattern from `WebSocketPrioritizedCachedStrategy`
+- Store channel state snapshots with version/timestamp
+- Location: `/src/core/cache/` or `/src/core/strategies/cache_sync_strategy.ts`
+
+**2. Subscription Sync**:
+```
+Channel.subscribe()
+  → Authorize()
+  → Check cache for existing state
+  → If valid: restore from cache
+  → Send 'pusher:subscribe'
+```
+
+**3. Event Rate Limiting**:
+- Add to `Dispatcher.emit()` or `Channel.handleEvent()`
+- Implement token bucket or sliding window
+- Track per-event or per-channel
+
+**4. Cache Update Hooks**:
+- On `pusher:subscription_succeeded` - capture state
+- On new events - update cache incrementally
+- On connection loss - persist for recovery
+
+**Suggested Locations**:
+1. **Cache Manager**: `/src/core/cache/cache_manager.ts`
+2. **Rate Limiter**: `/src/core/utils/rate_limiter.ts`
+3. **Extensions**: Modify `Channel.handleEvent()` and `Channel.subscribe()`
+
+---
+
+## 11. File Structure Reference
+
+```
+src/core/
+├── pusher.ts                          [Main entry point]
+├── connection/
+│   ├── connection_manager.ts          [Connection lifecycle]
+│   ├── connection.ts                  [Protocol adapter]
+│   ├── callbacks.ts                   [Type definitions]
+│   └── protocol/
+│       ├── protocol.ts                [Message encode/decode]
+│       ├── message-types.ts           [PusherEvent interface]
+│       └── action.ts                  [Server response types]
+├── channels/
+│   ├── channels.ts                    [Channel registry]
+│   ├── channel.ts                     [Base channel]
+│   ├── presence_channel.ts            [Presence-aware channel]
+│   ├── private_channel.ts             [Auth channel]
+│   ├── encrypted_channel.ts           [End-to-end encrypted]
+│   ├── members.ts                     [Presence members]
+│   └── metadata.ts                    [Event metadata]
+├── events/
+│   ├── dispatcher.ts                  [Event emitter]
+│   ├── callback.ts                    [Callback wrapper]
+│   ├── callback_registry.ts           [Callback storage]
+│   └── callback_table.ts              [Type definitions]
+├── transports/
+│   ├── transport.ts                   [Transport interface]
+│   ├── transport_connection.ts        [Transport adapter]
+│   ├── transport_manager.ts           [Multi-transport handler]
+│   └── transports_table.ts            [Available transports]
+├── strategies/
+│   ├── strategy.ts                    [Strategy interface]
+│   ├── websocket_prioritized_cached_strategy.ts  [Caching]
+│   └── transport_strategy.ts          [Transport selection]
+├── timeline/
+│   ├── timeline.ts                    [Diagnostics]
+│   ├── timeline_sender.ts             [Send metrics]
+│   └── level.ts                       [Log levels]
+├── utils/
+│   ├── collections.ts                 [Utility functions]
+│   ├── factory.ts                     [Object creation]
+│   ├── flat_promise.ts                [Promise wrapper]
+│   ├── url_store.ts                   [URL utilities]
+│   └── timers/
+│       ├── abstract_timer.ts
+│       ├── timed_callback.ts
+│       └── scheduling.ts
+├── http/                              [HTTP fallback transport]
+├── auth/                              [Authentication]
+├── config.ts                          [Configuration]
+├── defaults.ts                        [Default values]
+├── options.ts                         [Options validation]
+├── util.ts                            [Utility helpers]
+└── socket.ts                          [Socket interface]
+```
+
+---
+
+## 12. Key Message Flows
+
+### Subscription Flow
+```
+1. Pusher.subscribe("channel-name")
+   ↓
+2. Channels.add() creates Channel instance
+   ↓
+3. If not subscribed and connected:
+   Channel.subscribe()
+   ↓
+4. Channel.authorize() [callback for auth]
+   ↓
+5. Connection.send_event('pusher:subscribe', {auth, channel_data})
+   ↓
+6. Server receives and broadcasts subscription_succeeded
+   ↓
+7. Connection receives 'pusher_internal:subscription_succeeded'
+   ↓
+8. Channel.handleSubscriptionSucceededEvent()
+   ↓
+9. Channel emits 'pusher:subscription_succeeded'
+```
+
+### Event Publication Flow
+```
+1. User calls channel.bind('my-event', callback)
+   ↓
+2. Dispatcher.bind(eventName, callback) stores callback
+   ↓
+3. Server publishes event to channel
+   ↓
+4. Transport receives JSON: {"event":"my-event","channel":"...", "data":{...}}
+   ↓
+5. Connection.message handler:
+   - Protocol.decodeMessage() parses JSON
+   - Emits 'message' event
+   ↓
+6. ConnectionManager.message callback:
+   - Resets activity timer
+   - Emits 'message' to Pusher
+   ↓
+7. Pusher.connection binds to 'message':
+   - Finds channel
+   - Calls channel.handleEvent()
+   ↓
+8. Channel.handleEvent():
+   - If user event: Dispatcher.emit(eventName, data, metadata)
+   ↓
+9. Dispatcher.emit():
+   - Calls all callbacks with (data, metadata)
+```
+
+### Connection Establishment Flow
+```
+1. Pusher.connect()
+   → ConnectionManager.connect()
+   ↓
+2. Strategy selects transport (ws, wss, xhr_streaming, etc.)
+   ↓
+3. Transport connects and sends initial handshake
+   ↓
+4. Protocol.processHandshake():
+   - Expects 'pusher:connection_established'
+   - Returns Action with socket_id and activityTimeout
+   ↓
+5. HandshakeCallback.connected():
+   - Set socket_id
+   - Update state to 'connected'
+   - Emit 'connected' event
+   ↓
+6. Pusher.connection binds to 'connected':
+   - Calls subscribeAll()
+   ↓
+7. For each channel:
+   - If subscriptionPending: Channel.reinstateSubscription()
+   - Else if connected: Channel.subscribe()
+   ↓
+8. Channel authorization and subscription occurs
+```
+
+---
+
+## 13. Recommendations for Feature Implementation
+
+### Delta Compression
+**Considerations**:
+1. Bidirectional: Need compression for both incoming and outgoing
+2. Optional: Must not break compatibility; use protocol version or feature flags
+3. Performance: Only compress messages above a minimum size threshold
+4. Caching: Maintain compression context/dictionary per connection
+5. Error handling: Graceful fallback to uncompressed if decompression fails
+
+**Integration Points** (Priority Order):
+1. Create `/src/core/compression/delta_compressor.ts`
+2. Modify `Connection.bindListeners()` - decompress incoming
+3. Modify `Connection.send_event()` - compress outgoing
+4. Add compression flag to handshake `ConnectionCallbacks`
+5. Update `Protocol` to support compression metadata
+
+### Rate Cache Sync
+**Considerations**:
+1. State Recovery: Cache channel subscriptions across page reloads
+2. Incremental Sync: Only sync changed state, not full state
+3. TTL: Implement cache expiration with per-channel versioning
+4. Rate Limiting: Separate from caching; implement token bucket
+5. Storage: Use localStorage for browser, memory for Node.js
+
+**Integration Points** (Priority Order):
+1. Create `/src/core/cache/cache_manager.ts` for storage abstraction
+2. Create `/src/core/utils/rate_limiter.ts` for rate control
+3. Modify `Channel.subscribe()` - check cache before subscribe
+4. Modify `Channel.handleSubscriptionSucceededEvent()` - update cache
+5. Modify `Dispatcher.emit()` - apply rate limiting
+6. Add lifecycle methods to `ConnectionManager` for cache sync on reconnect
+
+---
+
+## Summary
+
+The pusher-js library is well-structured with clear separation of concerns:
+
+- **Connection Layer**: Manages transport and protocol
+- **Channel Layer**: Manages subscriptions and event routing
+- **Event Layer**: Dispatcher system for callback management
+- **Message Flow**: Unidirectional from transport → connection → channels → user callbacks
+
+For **delta compression**: Insert at Connection message handler (decompress) and send_event (compress)
+For **rate cache sync**: Implement cache layer and integrate with Channel subscribe/handle methods
+
+Both features require careful consideration of:
+- Backward compatibility (feature negotiation)
+- Error handling and fallback
+- Cross-platform support (browser, React Native, Node.js)
+- Existing caching patterns (see WebSocketPrioritizedCachedStrategy)