ispectify_ws 7.0.0-dev3

Provider-agnostic WebSocket diagnostics for ISpect — connection lifecycle, sent and received frame logging, session grouping, and redaction for any WebSocket client.

ispectify_ws is the provider-agnostic WebSocket diagnostics layer for the ISpect toolkit. It captures sent and received frames, connection-state transitions, and errors — for any WebSocket client — and redacts sensitive data before logging. The published package depends only on ispectify; you keep your own WebSocket client dependency.

• Frame-level capture for sent and received messages (ws-sent / ws-received).
• Connection lifecycle logging via ws-state (connecting / open / closing / closed / reconnecting).
• Error logging with stack traces (ws-error); one correlation id per connection session.
• Same redaction engine as the HTTP interceptors.

Install

dependencies:
  ispectify: ^7.0.0-dev3
  ispectify_ws: ^7.0.0-dev3
  # plus your WebSocket client, e.g.
  # ws: ^1.0.0  |  web_socket_channel: ^3.0.0  |  socket_io_client: ^3.0.0

Quick start

Bind any client to the WsDiagnosticsSink port. Metrics and state are optional — push whatever your client can report:

import 'package:ispect/ispect.dart';
import 'package:ispectify_ws/ispectify_ws.dart';

final diagnostics = WsDiagnostics(logger: ISpect.logger);

diagnostics
  ..newConnection() // starts a fresh correlation session
  ..onStateChanged(WsConnectionState.open, url: url);

channel.stream.listen(
  (message) => diagnostics.onReceived(message, url: url),
  onError: (Object e, StackTrace st) => diagnostics.onError(e, st, url: url),
  onDone: () => diagnostics.onStateChanged(WsConnectionState.closed, url: url),
);
// Outbound: call diagnostics.onSent(data, url: url) before sending a frame.

Ready-to-copy adapters

The package example ships thin adapters that wire a concrete client to WsDiagnostics — copy the one you need into your app (and add that client to your own pubspec.yaml):

Client	Adapter
ws (plugfox)	example/lib/interceptors/ws_interceptor.dart
web_socket_channel	example/lib/interceptors/web_socket_channel_interceptor.dart
socket_io_client	example/lib/interceptors/socket_io_interceptor.dart

Migrating from 5.x? ISpectWSInterceptor moved out of the published package into example/lib/interceptors/ws_interceptor.dart. Copy it in and add ws to your app — ISpectWSInterceptorSettings and the ws-sent / ws-received / ws-error keys are unchanged. See docs/DEPRECATIONS.md.

Settings

const settings = ISpectWSInterceptorSettings(
  enabled: true,
  logRequests: true,  // sent frames
  logResponses: true, // received frames
  printSentData: true,
  printReceivedData: true,
  printStateData: true,
  printReceivedMessage: true,
  printErrorData: true,
  printErrorMessage: true,
  enableRedaction: true,
);

final diagnostics = WsDiagnostics(logger: ISpect.logger, settings: settings);

Frame bodies, raw connection-state details, and errors are captured and redacted by default. Use ISpectWSInterceptorSettingsBuilder.metadataOnly() to retain frame lifecycle metadata without payloads, or the production preset to disable sent/received frame retention and keep redacted error diagnostics. print* fields shape retained records but do not re-enable a suppressed frame. Use the concrete settings copyWith or builder for retention controls; the shared base configure helper retains its legacy-compatible field set.

Data redaction

Sensitive data is masked before it reaches logs or observers. Redaction is on by default. The built-in rules cover auth headers, tokens, passwords, API keys, cookies, common PII (SSN, passport, driver's license), financial data (credit cards, IBAN), and phone numbers.

The default policy is a single source of truth. Configure it once and core logs, traces, persistence, network and database adapters, BLoC and Riverpod observers, supported exports, clipboard helpers, and cURL generation resolve it when each diagnostic operation runs.

Redaction works best paired with deliberate capture. Use the integration's metadataOnly() or compact preset when payload values are unnecessary, and register project-specific keys for the business identifiers only your application understands.

Global configuration

import 'package:ispectify/ispectify.dart';

ISpectRedaction.configure(
  service: RedactionService(
    additionalSensitiveKeys: {
      'x-custom-secret',
      'internal_token',
    },
    additionalSensitiveKeyPatterns: [
      RegExp(r'my_app_secret_\w+', caseSensitive: false),
    ],
    fullyMaskedKeys: {'filename'},
    placeholder: '***',
    visibleEdgeLength: 3,
  ),
);

additionalSensitiveKeys and additionalSensitiveKeyPatterns extend the built-in policy. Use sensitiveKeys or sensitiveKeyPatterns only when you intentionally want to replace the corresponding defaults:

final replacementPolicy = RedactionService(
  sensitiveKeys: {
    'x-custom-secret',
    'internal_token',
  },
  sensitiveKeyPatterns: [
    RegExp(r'my_app_secret_\w+', caseSensitive: false),
  ],
);

Flutter apps can pass the same policy as ISpect.run(redactionService: ...); ISpect.dispose() restores the policy that was active before that run. An explicit RedactionService supplied to one integration stays local and takes precedence over the global policy. Existing integrations without an explicit service pick up later global reconfiguration. The policy is scoped to the current Dart isolate.

Local exceptions

final redactor = RedactionService(
  ignoredKeys: {'mobile', 'platform_token'},
  ignoredValues: {'<test-token>', 'public-api-key'},
);

Disabling

ISpectRedaction.configure(enabled: false) is the global content-masking opt-out. Each interceptor also accepts enableRedaction: false on its settings object for a local opt-out. Size limits, non-executing snapshots, private-storage checks, and the compile-time ISPECT_ENABLED gate remain enforced.

Only disable redaction in isolated local or deterministic test environments. Exported sessions and observer events should be handled according to the data they contain.

The ISpect toolkit

ISpect is a modular monorepo. Pick the packages your project needs. Each one works on its own.

Package	What it does
ispect	Flutter UI: debug panel, log viewer, navigation observer, inspector integration.
ispect_layout	Visual layout inspector with sizes, constraints, decorations, compare mode, and a color picker.
ispectify	Pure-Dart logging core: typed log entries, filtering, tracing, observers.
ispectify_dio	Dio HTTP interceptor with automatic redaction.
ispectify_http	http package interceptor with automatic redaction.
ispectify_ws	Provider-agnostic WebSocket capture (any client) with automatic redaction.
ispectify_db	Database operation tracing for SQL, ORMs, and KV stores.
ispectify_bloc	BLoC event, state, transition, and error observer.
ispectify_riverpod	Riverpod provider add, update, dispose, and failure observer.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines, and open issues or pull requests at the ISpect repository.

License

MIT. See LICENSE.

---