Skip to content

Commit 952e80e

Browse files
777genius777genius
committed
docs: improve README files for all dart packages, add cross-references
1 parent 77bda5d commit 952e80e

File tree

3 files changed

+161
-13
lines changed

3 files changed

+161
-13
lines changed

‎dart_packages/dio_debugger/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# dio_debugger
22

3+
> Part of the [network_debugger](https://pub.dev/packages/network_debugger) ecosystem
4+
35
Lightweight utility that patches the provided `Dio` and attaches a reverse/forward proxy interceptor. Useful for local debugging, traffic interception, and bypassing CORS/certificates via your local proxy.
46

57
## Features
@@ -22,6 +24,22 @@ dependencies:
2224
dio_debugger: ^0.1.2
2325
```
2426
27+
## Starting the Proxy
28+
29+
Before using `dio_debugger`, you need to start the network debugger proxy server. Install and run it with:
30+
31+
```bash
32+
# Install the CLI globally
33+
dart pub global activate network_debugger
34+
35+
# Start the proxy (default port 9091)
36+
network_debugger
37+
```
38+
39+
The proxy will start on `http://localhost:9091` and automatically open the web UI where you can inspect all intercepted traffic.
40+
41+
For more options and programmatic usage, see the [network_debugger package documentation](https://pub.dev/packages/network_debugger).
42+
2543
## Quick start
2644

2745
```dart

‎dart_packages/network_debugger/README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# network_debugger
22

3-
Dart package that automatically downloads, caches, and launches the `network-debugger-web` binary for easy network debugging.
3+
![Запись экрана 2025-10-02 в 13 06 06](https://github.com/user-attachments/assets/43044ece-e6b4-4702-80bc-0584e844c042)
4+
5+
6+
Simple universal tool for debugging HTTP and WebSocket. Suitable for local development and test environments. Has web interface (opens in browser), desktop and CLI.
47

58
## Features
69

@@ -19,7 +22,7 @@ The easiest way to use the network debugger is via the CLI tool:
1922
### Installation
2023

2124
```bash
22-
# Install globally from pub.dev (once published)
25+
# Install globally from pub.dev
2326
dart pub global activate network_debugger
2427

2528
# OR install locally from path

‎dart_packages/socket_io_debugger/README.md‎

Lines changed: 138 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,60 @@
1-
socket_io_debugger
2-
===================
1+
# socket_io_debugger
32

4-
One-call helper to attach a proxy to a Socket.IO client (reverse/forward modes).
3+
> Part of the [network_debugger](https://pub.dev/packages/network_debugger) ecosystem
54
6-
Example:
5+
One-call helper to attach a proxy to a Socket.IO client (reverse/forward modes). Useful for local debugging, traffic interception, and bypassing CORS/certificates via your local proxy.
6+
7+
## Features
8+
9+
- One-liner attach: `SocketIoDebugger.attach()`
10+
- Supports reverse and forward proxy modes
11+
- Config sources (priority):
12+
1) `attach` arguments
13+
2) `--dart-define` (`HTTP_PROXY_MODE`, `HTTP_PROXY`, `SOCKET_PROXY`, `HTTP_PROXY_PATH`, `SOCKET_PROXY_PATH`, `HTTP_PROXY_ALLOW_BAD_CERTS`, `HTTP_PROXY_ENABLED`)
14+
3) OS ENV (via conditional import; web-safe)
15+
- Automatic HTTP client factory for forward proxy mode
16+
- Support for self-signed certificates
17+
- Zero-config for quick setup
18+
19+
## Installation
20+
21+
Add to your `pubspec.yaml`:
22+
23+
```yaml
24+
dependencies:
25+
socket_io_client: ^2.0.3
26+
socket_io_debugger: ^0.1.1
27+
```
28+
29+
## Starting the Proxy
30+
31+
Before using `socket_io_debugger`, you need to start the network debugger proxy server. Install and run it with:
32+
33+
```bash
34+
# Install the CLI globally
35+
dart pub global activate network_debugger
36+
37+
# Start the proxy (default port 9091)
38+
network_debugger
39+
```
40+
41+
The proxy will start on `http://localhost:9091` and automatically open the web UI where you can inspect all intercepted WebSocket traffic.
42+
43+
For more options and programmatic usage, see the [network_debugger package documentation](https://pub.dev/packages/network_debugger).
44+
45+
## Quick start
746

847
```dart
48+
import 'package:socket_io_client/socket_io_client.dart' as io;
49+
import 'package:socket_io_debugger/socket_io_debugger.dart';
50+
51+
// Configure the proxy
952
final cfg = SocketIoDebugger.attach(
1053
baseUrl: 'https://example.com',
1154
socketPath: '/socket.io',
1255
);
56+
57+
// Create socket with proxy configuration
1358
final socket = io.io(
1459
cfg.effectiveBaseUrl,
1560
io.OptionBuilder()
@@ -18,18 +63,100 @@ final socket = io.io(
1863
.setQuery(cfg.query)
1964
.build(),
2065
);
66+
67+
// Connect (with HttpOverrides if forward proxy mode)
2168
if (cfg.useForwardOverrides) {
22-
await HttpOverrides.runZoned(() => socket.connect(), createHttpClient: (_) => cfg.httpClientFactory!());
69+
await HttpOverrides.runZoned(
70+
() => socket.connect(),
71+
createHttpClient: (_) => cfg.httpClientFactory!(),
72+
);
2373
} else {
2474
socket.connect();
2575
}
2676
```
2777

28-
Environment variables:
29-
- HTTP_PROXY_MODE=reverse|forward|none
30-
- HTTP_PROXY, SOCKET_PROXY
31-
- HTTP_PROXY_PATH, SOCKET_PROXY_PATH
32-
- HTTP_PROXY_ALLOW_BAD_CERTS=true|false
33-
- HTTP_PROXY_ENABLED=true|false
78+
## Advanced options
79+
80+
### Reverse proxy mode (default)
81+
82+
Reverse proxy mode routes traffic through the proxy's HTTP endpoint:
83+
84+
```dart
85+
final cfg = SocketIoDebugger.attach(
86+
baseUrl: 'https://example.com',
87+
socketPath: '/socket.io',
88+
proxyBaseUrl: 'http://localhost:9091',
89+
proxyPath: '/wsproxy', // WebSocket proxy endpoint
90+
mode: ProxyMode.reverse,
91+
);
92+
```
93+
94+
### Forward proxy mode
95+
96+
Forward proxy mode uses `HttpOverrides` to route traffic:
97+
98+
```dart
99+
final cfg = SocketIoDebugger.attach(
100+
baseUrl: 'https://example.com',
101+
socketPath: '/socket.io',
102+
proxyBaseUrl: 'http://localhost:9091',
103+
mode: ProxyMode.forward,
104+
allowBadCerts: true, // Allow self-signed certificates
105+
);
106+
```
107+
108+
### Android emulator
109+
110+
When testing on Android emulator, use `10.0.2.2` instead of `localhost`:
111+
112+
```dart
113+
final cfg = SocketIoDebugger.attach(
114+
baseUrl: 'https://example.com',
115+
socketPath: '/socket.io',
116+
proxyBaseUrl: Platform.isAndroid
117+
? 'http://10.0.2.2:9091'
118+
: 'http://localhost:9091',
119+
);
120+
```
121+
122+
## Configuration examples
123+
124+
### Via `--dart-define`
125+
126+
```bash
127+
--dart-define=HTTP_PROXY_MODE=reverse \
128+
--dart-define=SOCKET_PROXY=http://localhost:9091 \
129+
--dart-define=SOCKET_PROXY_PATH=/wsproxy \
130+
--dart-define=HTTP_PROXY_ENABLED=true
131+
```
132+
133+
### Via OS ENV (on platforms with `dart:io`)
134+
135+
```bash
136+
HTTP_PROXY_MODE=reverse
137+
SOCKET_PROXY=http://localhost:9091
138+
SOCKET_PROXY_PATH=/wsproxy
139+
HTTP_PROXY_ENABLED=true
140+
HTTP_PROXY_ALLOW_BAD_CERTS=true
141+
```
142+
143+
## Environment variables
144+
145+
- `HTTP_PROXY_MODE` — Proxy mode: `reverse`, `forward`, or `none`
146+
- `HTTP_PROXY` — HTTP proxy URL (fallback for `SOCKET_PROXY`)
147+
- `SOCKET_PROXY` — Socket.IO proxy URL
148+
- `HTTP_PROXY_PATH` — HTTP proxy path (fallback for `SOCKET_PROXY_PATH`)
149+
- `SOCKET_PROXY_PATH` — Socket.IO proxy path
150+
- `HTTP_PROXY_ALLOW_BAD_CERTS` — Allow self-signed certificates: `true`, `1`, `yes`, `on`
151+
- `HTTP_PROXY_ENABLED` — Enable/disable proxy: `true`, `1`, `yes`, `on`
152+
153+
## Notes
154+
155+
- The proxy must expose a WebSocket proxy endpoint (e.g., `/wsproxy`) that accepts `_target` query and forwards the WebSocket connection
156+
- If `proxyBaseUrl` is empty or `HTTP_PROXY_ENABLED=false`, the package is a no-op (safe for prod)
157+
- Forward proxy mode requires `dart:io` and won't work on web platform
158+
- If the proxy is provided without scheme and with port `:443`, `https` will be used automatically
34159

160+
## License
35161

162+
MIT

0 commit comments

Comments
 (0)