app_debugger_websocket Pro

WebSocket traffic inspector sub-brick for app_debugger. Adds a WebSocket tab to the debugger panel showing a live tree of sent/received frames grouped by endpoint > topic > event. Automatically swapped to a no-op stub in release builds.

Version: 1.0.0

Variables

This brick has no generation-time variables. The inspector works with any WebSocket SDK implementation at runtime.

Prerequisites

• app_debugger brick must be installed first.
• A WebSocket SDK must be configured (e.g. websocket_sdk_dart or websocket_sdk_phoenix).

Usage

Interactive

archipelago generate app_debugger_websocket

Non-interactive (CI)

archipelago generate app_debugger_websocket --config my_config.json

Generated Structure

features/
└── app_debugger_websocket/
    ├── app_debugger_websocket_api/
    │   └── lib/src/
    │       └── models/
    ├── app_debugger_websocket/
    │   └── lib/src/
    │       └── di/
    └── app_debugger_websocket_noop/
        └── lib/src/
            └── di/

Required Setup

Register the interceptor with your WebSocket client after initializeInjector():

import 'package:app_debugger_websocket_api/app_debugger_websocket_api.dart';

final wsInspector = getIt<WebSocketInspectorSDK>();
if (wsInspector.interceptor != null) {
  getIt<WebSocketClient>().addInterceptor(wsInspector.interceptor!);
}

The null guard makes this safe in release builds where the noop stub returns null for interceptor.

Ring Buffer Configuration

Override WebSocketInspectorConfig in a custom @module class:

Field	Default	Description
maxEntries	500	Maximum entries kept in the ring buffer
capturePayloads	true	Whether to capture message payloads
payloadTruncateLength	2048	Truncate payloads longer than this length

How It Works

1. WebSocketInspectorSDKImpl constructs a WebSocketDebuggerInterceptor and registers a WebSocketInspectorPage with DebuggerPanelPageRegistry.
2. DebuggerPanel reads DebuggerPanelPageRegistry.instance.pages and appends extra tabs — no import of app_debugger_websocket required.
3. The interceptor captures every onSend, onReceive, onError, and onStateChange call into a ring buffer.
4. The panel UI groups entries by endpoint > topic > event using ExpansionTile widgets and refreshes reactively via trafficStream.
5. build_prepare.yaml swaps app_debugger_websocket → app_debugger_websocket_noop for release builds.