web_socket_channel_debugger 0.2.1

Helper to attach network-debugger proxy to package:web_socket_channel (reverse/forward).

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.2.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

Links

• web_socket_channel on pub.dev
• network_debugger

License

Apache-2.0