WebSocket Plugin

A robust Flutter WebSocket plugin utilizing the Adapter design pattern for flexible WebSocket communication. This plugin provides a modular, testable, and easy-to-use interface for WebSocket connections with support for automatic reconnection, different message types, comprehensive error handling, and enhanced resilience.

Features

  • Adapter Design Pattern: Easy switching between different WebSocket implementations
  • Automatic Reconnection: Configurable auto-reconnect with exponential backoff
  • Multiple Message Types: Support for text, JSON, and binary messages
  • Comprehensive State Management: Real-time connection state tracking
  • Error Handling: Robust error handling and reporting
  • Testing Support: Built-in mock adapter for unit testing
  • Logging: Optional detailed logging for debugging
  • Type Safety: Full TypeScript-like type safety with Dart
  • Heartbeat Mechanism: Keep connections alive with customizable ping/pong cycles
  • Server Inactivity Detection: Automatically detect when the server stops responding
  • Missed Heartbeat Tracking: Monitor connection health with configurable thresholds
  • Automatic Recovery: Trigger reconnection when heartbeat failures exceed limits
  • Enhanced Reconnection: Intelligent retry delays that increase exponentially
  • Jitter Support: Randomized delays to prevent thundering herd problems
  • Maximum Delay Caps: Configurable upper limits for reconnection delays
  • Connection Resilience: Robust handling of network instability
  • Advanced Monitoring: Comprehensive connection and heartbeat metrics
  • Health Monitoring: Track connection quality and performance
  • Detailed Logging: Enhanced debugging with heartbeat and reconnection logs

Installation

Add this to your package's pubspec.yaml file:

dependencies:
adapter_websocket: 0.0.1

Quick Start

Basic Usage

import 'package:websocket_plugin/websocket_plugin.dart';

// Create configuration
final config = WebSocketConfig(
url: 'wss://echo.websocket.org',
autoReconnect: true,
maxReconnectAttempts: 3,
enableLogging: true,
);

// Create adapter and client
final adapter = WebSocketChannelAdapter(config);
final client = WebSocketClient(adapter);

// Listen to messages
client.messageStream.listen((message) {
print('Received: ${message.data}');
});

// Connect and send messages
await client.connect();
await client.sendText('Hello, WebSocket!');
await client.sendJson({'type': 'greeting', 'message': 'Hello'});

Advanced Configuration

final config = WebSocketConfig(
url: 'wss://your-websocket-server.com',
protocols: ['chat', 'superchat'],
headers: {'Authorization': 'Bearer your-token'},
pingInterval: Duration(seconds: 30),
connectionTimeout: Duration(seconds: 10),
reconnectDelay: Duration(seconds: 5),
maxReconnectAttempts: 5,
autoReconnect: true,
enableLogging: true,

// Enhanced reconnection with exponential backoff
useExponentialBackoff: true,
maxReconnectDelay: Duration(minutes: 5),
backoffMultiplier: 2.0,

// Heartbeat configuration
enableHeartbeat: true,
heartbeatInterval: Duration(seconds: 30),
heartbeatTimeout: Duration(seconds: 10),
heartbeatMessage: 'ping',
expectedPongMessage: 'pong',
maxMissedHeartbeats: 3,
);

Architecture

Adapter Pattern Implementation

The plugin uses the Adapter design pattern to provide flexibility in WebSocket implementations:

// Abstract adapter interface
abstract class WebSocketAdapter {
Stream<WebSocketState> get stateStream;
Stream<WebSocketMessage> get messageStream;
Stream<dynamic> get errorStream;
Stream<Map<String, dynamic>> get statsStream;

Future<void> connect();
Future<void> sendMessage(WebSocketMessage message);
Future<void> disconnect([int? code, String? reason]);
Future<void> forceReconnect();
}

// Concrete implementation using web_socket_channel
class WebSocketChannelAdapter implements WebSocketAdapter {
// Implementation details...
}

// Mock implementation for testing
class MockWebSocketAdapter implements WebSocketAdapter {
// Mock implementation...
}

Key Components

  1. WebSocketClient: High-level client interface with auto-reconnection
  2. WebSocketAdapter: Abstract interface for different implementations
  3. WebSocketConfig: Configuration class for connection parameters
  4. WebSocketMessage: Typed message container with metadata
  5. WebSocketState: Enumeration of connection states
  6. WebSocketStats: Comprehensive statistics for connection and heartbeat health

Message Types

Text Messages

await client.sendText('Hello, World!');

JSON Messages

await client.sendJson({
'type': 'chat',
'message': 'Hello',
'timestamp': DateTime.now().toIso8601String(),
});

Binary Messages

await client.sendBinary([1, 2, 3, 4, 5]);

Custom Messages

final message = WebSocketMessage(
data: 'custom data',
timestamp: DateTime.now(),
type: 'custom',
metadata: {'priority': 'high'},
);
await client.sendMessage(message);

State Management

The plugin provides real-time state tracking:

client.stateStream.listen((state) {
switch (state) {
case WebSocketState.connecting:
print('Connecting...');
break;
case WebSocketState.connected:
print('Connected!');
break;
case WebSocketState.disconnecting:
print('Disconnecting...');
break;
case WebSocketState.disconnected:
print('Disconnected');
break;
case WebSocketState.error:
print('Connection error');
break;
}
});

Error Handling

Comprehensive error handling with detailed error streams:

client.errorStream.listen((error) {
print('WebSocket error: $error');
// Handle error appropriately
});

Testing

The plugin includes enhanced mock capabilities for testing heartbeat and reconnection scenarios:

import 'package:flutter_test/flutter_test.dart';
import 'package:websocket_plugin/websocket_plugin.dart';

void main() {
test('should send and receive messages', () async {
final config = WebSocketConfig(url: 'wss://test.example.com');
final mockAdapter = MockWebSocketAdapter(config);
final client = WebSocketClient(mockAdapter);

    await client.connect();
    await client.sendText('test message');
    
    expect(mockAdapter.sentMessages.length, equals(1));
    expect(mockAdapter.sentMessages.first.data, equals('test message'));
    
    // Simulate receiving a message
    mockAdapter.simulateTextMessage('response');
    
    // Verify message was received
    // ... test assertions
});

test('should handle heartbeat timeouts', () async {
final config = WebSocketConfig(
url: 'wss://test.com',
enableHeartbeat: true,
heartbeatInterval: Duration(milliseconds: 100),
maxMissedHeartbeats: 2,
);

    final mockAdapter = MockWebSocketAdapter(config);
    mockAdapter.setAutoRespondToPing(false); // Simulate unresponsive server
    
    final client = WebSocketClient(mockAdapter);
    
    // Monitor for reconnection attempts
    bool reconnectionTriggered = false;
    client.statsStream.listen((stats) {
      if (stats['reconnection']['isReconnecting'] == true) {
        reconnectionTriggered = true;
      }
    });
    
    await client.connect();
    await Future.delayed(Duration(milliseconds: 500));
    
    expect(reconnectionTriggered, isTrue);
});

test('should simulate network instability', () async {
final mockAdapter = MockWebSocketAdapter(config);
mockAdapter.setSimulateUnstableConnection(true);

    final client = WebSocketClient(mockAdapter);
    await client.connect();
    
    // Connection will randomly disconnect and reconnect
    // Perfect for testing resilience
});
}

Logging

Enable detailed logging for debugging:

final config = WebSocketConfig(
url: 'wss://your-server.com',
enableLogging: true,
);

client.logStream.listen((log) {
print('WebSocket Log: $log');
});

Best Practices

  1. Always dispose clients: Call client.dispose() when done
  2. Handle connection states: Listen to state changes for UI updates
  3. Implement error handling: Always listen to error streams
  4. Use appropriate message types: Choose the right message type for your data
  5. Configure timeouts: Set appropriate connection and reconnection timeouts
  6. Test with mocks: Use the mock adapter for unit testing
  7. Configure appropriate heartbeat intervals based on your network conditions
  8. Use exponential backoff for production environments
  9. Monitor connection statistics to optimize settings
  10. Test with mock adapter to verify resilience
  11. Enable logging during development for debugging

Examples

See the example/ directory for a complete Flutter app demonstrating all features of the WebSocket plugin.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Libraries

websocket_plugin