ispectify_ws 4.2.1-dev13

ispectify_ws: ^4.2.1-dev13 copied to clipboard

WebSocket interceptor integration for ISpectify logging system using ws package

🔍 Overview #

ISpectify WebSocket provides seamless integration between the ws package and the ISpectify logging system for comprehensive WebSocket monitoring.

Enhance your WebSocket debugging workflow by automatically capturing and logging all WebSocket client interactions using the ws package. Provides seamless integration with Dart's WebSocket client through interceptors for comprehensive connection and message monitoring.

🎯 Key Features #

• 🔗 WebSocket Connection Logging: Automatic logging of all WebSocket connections
• 📨 Message Tracking: Detailed logging of sent and received messages
• ❌ Error Handling: Comprehensive error logging with stack traces
• 🔍 Connection Inspection: URL, connection state, and metrics logging
• ⚡ Performance Metrics: Connection timing and message count tracking
• 🎛️ Lightweight: Minimal overhead using ws package interceptors

🔧 Configuration Options #

Basic Setup #

final logger = ISpectify();

// Create interceptor with custom settings
final interceptor = ISpectWSInterceptor(
  logger: logger,
  settings: const ISpectWSInterceptorSettings(
    enabled: true,
    printSentData: true,
    printReceivedData: true,
    printReceivedMessage: true,
    printErrorData: true,
    printErrorMessage: true,
    printReceivedHeaders: false,
  ),
);

// Create WebSocket client
final client = WebSocketClient(
  WebSocketOptions.common(
    interceptors: [interceptor],
  ),
);

// Set client for interceptor
interceptor.setClient(client);

Advanced Configuration with Filters #

final interceptor = ISpectWSInterceptor(
  logger: logger,
  settings: ISpectWSInterceptorSettings(
    enabled: true,
    // Custom filters for selective logging
    sentFilter: (request) {
      // Only log requests containing specific data
      return request.body?['data']?.toString().contains('important') ?? false;
    },
    receivedFilter: (response) {
      // Only log successful responses
      return !response.body?['data']?.toString().contains('error') ?? true;
    },
    errorFilter: (error) {
      // Log all errors
      return true;
    },
    // Custom console colors
    sentPen: AnsiPen()..blue(),
    receivedPen: AnsiPen()..green(),
    errorPen: AnsiPen()..red(),
  ),
);

Connection Event Handling #

final interceptor = ISpectWSInterceptor(
  logger: logger,
  onClientReady: (client) {
    print('WebSocket client is ready');
    print('Client metrics: ${client.metrics}');
  },
);

📦 Installation #

Add ispectify_ws to your pubspec.yaml:

dependencies:
  ispectify_ws: ^4.2.1-dev10

🚀 Quick Start #

import 'dart:async';
import 'dart:io' as io show exit;
import 'package:ispectify/ispectify.dart';
import 'package:ispectify_ws/ispectify_ws.dart';
import 'package:ws/ws.dart';

void main() {
  const url = 'wss://echo.websocket.org';
  final logger = ISpectify();

  // Create WebSocket interceptor
  final interceptor = ISpectWSInterceptor(
    logger: logger,
    settings: const ISpectWSInterceptorSettings(
      enabled: true,
      printSentData: true,
      printReceivedData: true,
      printErrorData: true,
    ),
  );

  // Create WebSocket client with interceptor
  final client = WebSocketClient(
    WebSocketOptions.common(
      connectionRetryInterval: (
        min: const Duration(milliseconds: 500),
        max: const Duration(seconds: 15),
      ),
      interceptors: [interceptor],
    ),
  );

  // Set client for interceptor
  interceptor.setClient(client);

  // Connect and send messages - all will be automatically logged
  client
    ..connect(url)
    ..add('Hello WebSocket!')
    ..add('{"type": "message", "data": "JSON data"}');

  // Listen to messages
  client.stream.listen(
    (message) {
      print('Received: $message');
    },
    onError: (error) {
      print('Error: $error');
    },
  );

  // Close connection after some time
  Timer(const Duration(seconds: 5), () async {
    await client.close();
    print('Connection closed');
    print('Metrics: ${client.metrics}');
  });
}

📚 Examples #

See the example/ directory for complete integration examples with different WebSocket client configurations.

🏗️ Architecture #

ISpectifyWS integrates with the WebSocket client through interceptors:

🤝 Contributing #

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main branch.

📄 License #

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

🔗 Related Packages #

• ispectify - Foundation logging system
• ispectify_dio - Dio HTTP client integration
• ispectify_http - HTTP client integration
• ispect - Main debugging interface
• ws - WebSocket client package for Dart

Built with ❤️ for the Flutter community