Initial Commit

docs/old-network-planning/DESCRIPTION.md

@@ -0,0 +1,263 @@
+# Network Library Architecture
+
+This document describes the architecture and functionality of the network library, which provides a modular, extensible system for handling network connections across different transport protocols with fallback mechanisms.
+
+## Overview
+
+The network library is designed to provide a robust networking layer for real-time applications, particularly focusing on peer-to-peer connections with fallback mechanisms. It supports WebRTC as the primary connection method, with WebSocket and relay server fallbacks when direct connections can't be established.
+
+Key features include:
+
+- Multiple transport protocols (WebRTC, WebSocket, Relay)
+- Connection state management
+- Priority-based message queuing
+- Message batching and optimization
+- Network statistics tracking
+- Automatic reconnection handling
+- Fallback mechanism when preferred connection methods fail
+
+## Core Components
+
+### 1. Connection Types
+
+Defines fundamental types, enums, and interfaces used throughout the system including:
+
+- `ConnectionType` enum: Defines supported connection types (WEBSOCKET, WEBRTC, RELAY)
+- `ConnectionState` enum: Represents connection states (CONNECTING, CONNECTED, DISCONNECTED, FAILED, RECONNECTING)
+- `MessagePriority` enum: Represents message priority levels (CRITICAL, HIGH, MEDIUM, LOW)
+- `Connection` interface: Represents a network connection with properties like id, type, state, stats
+- `ConnectionStats` interface: Tracks performance metrics like latency, jitter, packet loss, reliability score
+
+### 2. Messages
+
+Defines the structure and types for all network messages, including:
+
+- `MessageType` enum: Defines all supported message types (CONNECT, DISCONNECT, PING, PONG, OFFER, ANSWER, ICE_CANDIDATE, etc.)
+- `NetworkMessage` interface: Core message structure with type, sender, timestamp, payload, priority
+- `MessagePayloads` type: Type mapping for payloads of different message types
+- `MessageFactory`: Utility class for creating properly formatted messages
+
+### 3. Base Connection
+
+Provides the foundation for all network connections:
+
+- Abstract `BaseConnection` class implementing core functionality:
+  - Connection state management
+  - Message priority queuing
+  - Network statistics tracking (latency, jitter, packet loss)
+  - Automatic reconnection handling
+  - Adaptive batch processing
+  - Ping/Pong heartbeat system
+
+### 4. Base Message Handler
+
+Provides foundational message handling functionality:
+
+- Abstract `BaseMessageHandler` class:
+  - Message validation and type checking
+  - Message queue management
+  - Priority-based message processing
+  - Error handling and recovery
+  - Event emission for message lifecycle
+  - Batch processing capabilities
+
+### 5. Relay Message
+
+Specialized handling for relay-based messaging:
+
+- `RelayMessage` class:
+  - Relay message encapsulation
+  - Message routing between peers
+  - Relay chain tracking
+  - Loop prevention
+  - Priority handling for relayed messages
+  - Relay statistics tracking
+
+### 6. Relay Connection
+
+Handles relay server-based connections:
+
+- `RelayConnectionManager` class:
+  - Fallback connectivity for failed WebRTC connections
+  - Message relaying between peers
+  - Connection state management
+  - Automatic relay server selection
+  - Message priority handling
+  - Connection statistics tracking
+
+### 7. WebRTC Connection
+
+Implements WebRTC-specific connection handling:
+
+- WebRTC signaling
+- ICE candidate handling
+- Direct peer connections
+- Data channel management
+- Media stream handling (if needed)
+
+### 8. WebSocket Connection
+
+Implements WebSocket-specific connection handling:
+
+- Direct server connections
+- Message serialization/deserialization
+- Connection monitoring
+- Automatic reconnection
+
+## Architecture Relationships
+
+```text
+┌─────────────────┐     ┌─────────────────┐
+│  ConnectionTypes│◄────┤  Messages       │
+└────────┬────────┘     └────────┬────────┘
+         │                       │
+         ▼                       ▼
+┌─────────────────┐     ┌─────────────────┐
+│  BaseConnection │◄────┤ BaseMessageHandler
+└────────┬────────┘     └────────┬────────┘
+         │                       │
+         ▼                       ▼
+┌─────────────────┐     ┌─────────────────┐
+│WebRTCConnection │     │  RelayMessage   │
+└────────┬────────┘     └────────┬────────┘
+         │                       │
+         │                       ▼
+         │              ┌─────────────────┐
+         └─────────────►│RelayConnection  │
+                        └─────────────────┘
+```
+
+## Implementation Details
+
+### Connection Management
+
+1. When establishing connections:
+   - First attempt direct WebRTC connection
+   - If WebRTC fails, fall back to WebSocket connection
+   - If WebSocket is unavailable, use relay server connection
+
+2. Connection State Machine:
+   - CONNECTING → Attempting to establish connection
+   - CONNECTED → Successfully connected
+   - DISCONNECTED → Connection lost
+   - RECONNECTING → Attempting to reestablish lost connection
+   - FAILED → All connection attempts failed
+
+### Message Handling
+
+1. Messages are processed according to priority:
+   - CRITICAL messages processed immediately
+   - HIGH, MEDIUM, LOW messages are queued for batch processing
+
+2. Message Flow:
+   - Messages created through MessageFactory
+   - Messages added to priority queue
+   - Messages processed by BaseMessageHandler
+   - Connection-specific handlers implement sending logic
+
+3. Message Batching:
+   - Related messages combined to reduce network overhead
+   - Batch processing interval adaptively adjusted based on network conditions
+   - Critical messages bypass batching
+
+### Reliability Mechanisms
+
+1. Automatic Reconnection:
+   - Connection failures trigger reconnection attempts
+   - Exponential backoff strategy for retry attempts
+   - Connection monitoring through ping/pong messages
+
+2. Fallback Strategy:
+   - Preferred connection method attempted first
+   - On failure, fall back to next available method
+   - Multiple relay servers used for redundancy
+
+3. Statistics Tracking:
+   - Latency, jitter, packet loss measured
+   - Adaptive timing based on network performance
+   - Connection reliability scoring
+
+## Usage Patterns
+
+### Basic Connection
+
+```typescript
+// Create connection manager
+const connectionManager = new ConnectionManager();
+
+// Connect to a peer
+await connectionManager.connect(peerId);
+
+// Send a message
+connectionManager.sendMessage(peerId, {
+  type: MessageType.STATE_UPDATE,
+  payload: { position: { x: 100, y: 200 } }
+});
+
+// Listen for messages
+connectionManager.on('message', (message) => {
+  console.log('Received message:', message);
+});
+
+// Disconnect
+connectionManager.disconnect(peerId);
+```
+
+### Advanced Usage
+
+```typescript
+// Configure connection manager with options
+const connectionManager = new ConnectionManager({
+  preferredConnectionType: ConnectionType.WEBRTC,
+  maxRetries: 5,
+  retryDelay: 2000,
+  relayServers: ['wss://relay1.example.com', 'wss://relay2.example.com']
+});
+
+// Connect with options
+await connectionManager.connect(peerId, {
+  timeout: 10000,
+  metadata: { username: 'Player1' }
+});
+
+// Send prioritized message
+connectionManager.sendMessage(peerId, {
+  type: MessageType.STATE_UPDATE,
+  payload: { position: { x: 100, y: 200 } },
+  priority: MessagePriority.HIGH
+});
+
+// Register type-specific handlers
+connectionManager.on(MessageType.STATE_UPDATE, (message) => {
+  updateGameState(message.payload);
+});
+
+// Monitor connection quality
+connectionManager.on('statistics', (stats, peerId) => {
+  updateNetworkIndicator(stats.latency, stats.packetLoss);
+});
+```
+
+## Key Design Patterns
+
+1. **Abstract Factory Pattern** - MessageFactory creates different types of messages
+2. **Strategy Pattern** - Different connection implementations can be swapped
+3. **Observer Pattern** - Event handling for connection state changes and messages
+4. **Command Pattern** - Messages encapsulate operations to be performed
+5. **Chain of Responsibility** - Messages processed through handlers
+6. **Adapter Pattern** - Consistent interface across different connection technologies
+
+## Testing Requirements
+
+The library should be tested with:
+
+- Jest tests (.test.ts) for unit testing
+- Playwright tests (.spec.ts) for integration testing
+
+Test coverage should include:
+
+- Connection establishment and teardown
+- Message sending and receiving
+- Error handling and recovery
+- Fallback mechanisms
+- Performance under various network conditions