ispectify_ws 4.3.1-dev02

ispectify_ws: ^4.3.1-dev02 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
• 🔒 Sensitive Data Redaction: Centralized redaction for sent/received payloads (enabled by default, configurable)
• ⚡ Performance Metrics: Connection timing and message count tracking
• 🎛️ Lightweight: Minimal overhead using ws package interceptors

🔧 Configuration Options #

Basic Setup #

final logger = ISpectify();

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

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

interceptor.setClient(client);

Sensitive Data Redaction #

Redaction is enabled by default. Disable globally via settings or provide a custom redactor.

// Disable redaction
final interceptor = ISpectWSInterceptor(
  logger: logger,
  settings: const ISpectWSInterceptorSettings(enableRedaction: false),
);

// Provide a custom redactor
final redactor = RedactionService();
redactor.ignoreKeys(['x-debug']);
redactor.ignoreValues(['sample-token']);
final interceptor2 = ISpectWSInterceptor(
  logger: logger,
  redactor: redactor,
);

Advanced Configuration with Filters #

final interceptor = ISpectWSInterceptor(
  logger: logger,
  settings: ISpectWSInterceptorSettings(
    enabled: true,
    sentFilter: (request) {
      return request.body?['data']?.toString().contains('important') ?? false;
    },
    receivedFilter: (response) {
      return !response.body?['data']?.toString().contains('error') ?? true;
    },
    errorFilter: (error) {
      return true;
    },
    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.3.1-dev02

🚀 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