app_debugger_websocket Enterprise

Docs/Bricks/app_debugger_websocket

Tier

Enterpriseversion 1.2.4

Command

archipelago generate app_debugger_websocket

Generates

• features/app_debugger_websocket/app_debugger_websocket
• features/app_debugger_websocket/app_debugger_websocket_api
• features/app_debugger_websocket/app_debugger_websocket_noop

Generates first

app_debuggerwhen needed and missing, so there is nothing to install first

Depends on

shared_identifiers, websocket_sdkgenerate these first

Tutorial

Step-by-step: add app_debugger_websocket to a project

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

Variables

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

Prerequisites

• app_debugger is generated first when the project lacks it. It provides the archipelago:debug_panel_pages sentinel inside app_debugger's own AppDebuggerSDKImpl — the post_gen hook patches it to eagerly resolve WebSocketInspectorSDK). The marker moved between app_debugger versions, so the hook uses the first file that has it: app_debugger's lib/src/di/debug_tools.dart (2.0.0 and later), its lib/src/app_debugger_sdk_impl.dart (1.3.0 to 1.15.x), then the app's lib/bootstrap.dart (older), and adds the imports and path dependencies to that package. A file that already resolves the SDK is left as it is. If no file has the marker, pre_gen prints the lines to add and stops before it writes any file.
• 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/
    │       │   ├── websocket_inspector_config.dart
    │       │   ├── websocket_traffic_direction.dart
    │       │   └── websocket_traffic_entry.dart
    │       └── websocket_inspector_sdk.dart      # WebSocketInspectorSDK contract
    ├── app_debugger_websocket/
    │   └── lib/src/
    │       ├── di/
    │       ├── websocket_debugger_interceptor.dart
    │       ├── websocket_inspector_page.dart
    │       └── websocket_inspector_sdk_impl.dart
    └── 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 production-flavor 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. The debugger home reads DebuggerPanelPageRegistry.instance.pages and lists each page as a tool on its own route — 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 production-flavor builds.

Changelog

Run archipelago brick info app_debugger_websocket to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.