ispectify_ws 4.4.0-dev09

ispectify_ws: ^4.4.0-dev09 copied to clipboard

WebSocket interceptor integration for ISpectify logging system using ws package

TL;DR #

Track WebSocket connects, messages, errors, metrics with optional redaction.

🏗️ Architecture #

ISpectifyWS integrates with the WebSocket client through interceptors:

Overview #

ISpectify WebSocket integrates the ws package with the ISpectify logging system for WebSocket monitoring.

ISpectifyWS integrates the ws package with the ISpectify logging system for WebSocket 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 only with synthetic / non-sensitive data.

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

final redactor = RedactionService();
redactor.ignoreKeys(['x-debug']);
redactor.ignoreValues(['<placeholder-token>']);
final interceptor2 = ISpectWSInterceptor(
  logger: logger,
  redactor: redactor,
);

Filtering with Optional Predicates #

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

Security & Production Guidelines #

IMPORTANT: ISpect is development‑only. Keep it out of production builds.

🚀 Quick Start #

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

// Use dart define to control ISpectify WebSocket integration
const bool kEnableISpectWS = bool.fromEnvironment('ENABLE_ISPECT', defaultValue: false);

void main() {
  // Replace with your test endpoint or local dev server; avoid deprecated public echo services
  const url = 'wss://example.com/socket';
  if (kEnableISpectWS) {
    _initializeWithISpect(url);
  } else {
    _initializeWithoutISpect(url);
  }
}

void _initializeWithISpect(String url) {
  final logger = ISpectify();
  final interceptor = ISpectWSInterceptor(
    logger: logger,
    settings: const ISpectWSInterceptorSettings(
      enabled: true,
      printSentData: true,
      printReceivedData: true,
      printErrorData: true,
      enableRedaction: true, // Keep redaction enabled for any non-local traffic
    ),
  );
  final client = WebSocketClient(
    WebSocketOptions.common(
      connectionRetryInterval: (
        min: const Duration(milliseconds: 500),
        max: const Duration(seconds: 15),
      ),
      interceptors: [interceptor],
    ),
  );
  interceptor.setClient(client);
  _runWebSocketExample(client, url);
}

void _initializeWithoutISpect(String url) {
  final client = WebSocketClient(
    WebSocketOptions.common(
      connectionRetryInterval: (
        min: const Duration(milliseconds: 500),
        max: const Duration(seconds: 15),
      ),
    ),
  );
  _runWebSocketExample(client, url);
}

void _runWebSocketExample(WebSocketClient client, String url) {
  client
    ..connect(url)
    ..add('Hello WebSocket!');
  client.stream.listen(
    (message) {
      print('Received: $message');
    },
    onError: (error) {
      print('Error: $error');
    },
  );
  Timer(const Duration(seconds: 5), () async {
    await client.close();
    print('Connection closed');
    if (kEnableISpectWS) {
      print('Metrics: ${client.metrics}');
    }
  });
}

Minimal Setup #

Examples #

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

🤝 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