web_socket_channel_debugger

A helper package to attach network-debugger proxy to package:web_socket_channel for local debugging and WebSocket traffic interception.

Installation

dependencies:
  web_socket_channel: ^3.0.3
  web_socket_channel_debugger: ^0.1.0

Quick Start

import 'package:web_socket_channel_debugger/web_socket_channel_debugger.dart';

void main() async {
  const upstream = 'wss://echo.websocket.events';
  
  final cfg = WebSocketChannelDebugger.attach(
    baseUrl: upstream,
    proxyBaseUrl: 'http://localhost:9091',
    proxyPath: '/wsproxy',
  );

  final channel = WebSocketChannelDebugger.connect(config: cfg);
  await channel.ready;
  
  channel.stream.listen((message) => print('Received: \$message'));
  channel.sink.add('hello');
}

API

`WebSocketChannelDebugger.attach()`

Creates a configuration for connecting through the proxy.

Parameter	Type	Default	Description
`baseUrl`	`String`	required	Target WebSocket URL (`ws://` or `wss://`)
`proxyBaseUrl`	`String`	`http://localhost:9091`	Proxy server address
`proxyPath`	`String`	`/wsproxy`	Proxy WebSocket endpoint path
`enabled`	`bool?`	`true`	Enable/disable proxy
`mode`	`String?`	`reverse`	Mode: `reverse`, `forward`, `none`

`WebSocketChannelDebugger.connect()`

Parameter	Type	Description
`config`	`WscProxyConfig`	Config from `attach()`
`headers`	`Map<String, dynamic>?`	HTTP headers (dart:io only)

Platform Behavior

Feature	dart:io (mobile/desktop)	Web (dart:js_interop)
Reverse mode	yes	yes
Forward mode	yes	no (no HttpOverrides)
Custom headers	yes	no (browser limitation)
Self-signed certs	yes (with flag)	no
Read ENV	yes	no (`--dart-define` only)

Environment Variables

Variable	Description
`SOCKET_PROXY`	Proxy server URL
`SOCKET_PROXY_PATH`	WS endpoint path (usually `/wsproxy`)
`SOCKET_PROXY_MODE`	`reverse` / `forward` / `none`
`SOCKET_PROXY_ENABLED`	`true` / `false`
`SOCKET_PROXY_ALLOW_BAD_CERTS`	Allow self-signed (forward mode)
`SOCKET_UPSTREAM_URL`	Explicit upstream URL
`SOCKET_UPSTREAM_TARGET`	Full `_target` for reverse mode

License

Apache-2.0