DragonTCP/README.md

DragonTCP Proxy v6 - Server Debug Build

This build adds server-side diagnostic logging for the adaptive/chunk transport. The wire protocol and v6 client remain compatible.

New server flags

--debug Session/connect/error logging plus periodic aggregate statistics.

--debug-chunks Logs every COPEN, CPUSH, ACK, CPULL, DATA, WAIT, EOF, and CCLOSE event. This is extremely verbose with 32-byte chunks and can reduce throughput. Enabling --debug-chunks also enables normal debug logging.

--debug-stats-interval DURATION Aggregate statistics frequency. Default: 5s. Set to 0 to disable periodic statistics.

Recommended diagnostic command for fixed 32-byte chunks

sudo ./dragontcp-server-linux-amd64 --token 'YOUR_SECRET' --chunk-max 32 --chunk-buffered 2048 --chunk-poll-wait 50ms --chunk-session-timeout 5m --max-connections 20000 --tcp-buffer 0 --debug --debug-chunks --debug-stats-interval 5s

Normal production command with useful low-overhead debug

sudo ./dragontcp-server-linux-amd64 --token 'YOUR_SECRET' --chunk-max 32 --chunk-buffered 2048 --chunk-poll-wait 50ms --chunk-session-timeout 5m --max-connections 20000 --tcp-buffer 0 --debug --debug-stats-interval 10s

Disable all debug logging

Simply omit --debug and --debug-chunks.

Example debug output

[DEBUG] SESSION OPEN id=... target=example.com:443 max_chunk=32 active_sessions=1 [CHUNK] CPUSH id=... seq=0 bytes=32 -> ACK accepted=32 [CHUNK] CPULL id=... ack=-1 want=0 offset=0 limit=32 [CHUNK] DATA id=... seq=0 offset=0 bytes=32 total=32 [CHUNK] CPULL id=... want=8 -> WAIT [DEBUG] SESSION CLOSE id=... active_sessions=0 [DEBUG] STATS uptime=10s active_connections=8 active_sessions=2 sessions_opened=5 sessions_closed=3 bytes_up=... bytes_down=... push_records=... pull_requests=... data_records=... waits=... errors=0

Counters

active_connections - currently open DragonTCP TCP connections active_sessions - currently open chunk proxy sessions sessions_opened - total chunk sessions opened sessions_closed - total chunk sessions closed bytes_up - bytes accepted from client and written toward target bytes_down - bytes read from target into chunk buffering push_records - accepted upload CPUSH records pull_requests - CPULL requests received data_records - DATA responses generated waits - WAIT responses because downstream data was not ready yet errors - debug-counted server/protocol errors

Important performance note

At 32 bytes, --debug-chunks can generate thousands or millions of log lines for large transfers. Use it while diagnosing a failure, then switch to --debug only for normal use.

Large-chunk update

This is the v6 debug/adaptive-chunk branch with FIXED poller concurrency. It intentionally does NOT include the later adaptive-poller controller.

Chunk limits

Previous hard limit:

8192 bytes

New hard limit:

1048576 bytes (1 MiB)

The framed protocol ceiling was increased to 2 MiB so a 1 MiB CPUSH/DATA record plus protocol metadata fits safely.

New defaults:

client --chunk-max 65536
server --chunk-max 65536

The adaptive client still begins at:

--chunk-start 256

and can grow toward the configured maximum after successful records.

Use up to 1 MiB adaptive chunks

Server:

sudo ./dragontcp-server-linux-amd64 --token 'YOUR_SECRET' --chunk-max 1048576 --debug --debug-stats-interval 10s

Android ARM64 client with fixed poller count of 8:

./dragontcp-client-android-arm64 --server-host YOUR_SERVER_IP --token 'YOUR_SECRET' --chunk-start 256 --chunk-min 32 --chunk-max 1048576 --chunk-pollers 8 --chunk-timeout 2s --chunk-adapt-log

The number of pollers stays exactly at the value passed with --chunk-pollers. Only the chunk size adapts.

Examples of useful ceilings

--chunk-max 16384       # 16 KiB
--chunk-max 32768       # 32 KiB
--chunk-max 65536       # 64 KiB (new default maximum)
--chunk-max 131072      # 128 KiB
--chunk-max 262144      # 256 KiB
--chunk-max 524288      # 512 KiB
--chunk-max 1048576     # 1 MiB hard maximum

Fixed-size mode also supports the same range:

--chunk-size 262144

Memory note

Larger server chunk maxima require larger per-session target-read buffers and can increase buffered memory substantially when many sessions are active. For thousands of simultaneous users, do not automatically use 1 MiB unless measurements show that it is useful. Values such as 16-64 KiB are a more reasonable starting point, while the adaptive client can still be configured to probe higher when your network supports it.

Validation

The updated source and binaries were rebuilt from this v6 debug branch. Validation included:

• Go builds for Linux amd64, Linux ARM64, Linux ARMv7 client, and Android ARM64.
• A protocol round-trip test with a full 1 MiB request and response frame.
• An 8 MiB HTTP download through the proxy using fixed 262144-byte (256 KiB) chunk configuration; the downloaded SHA-256 matched the source exactly.

DragonTCP branding update

This package was renamed from HOX to DragonTCP.

Binary names are now:

dragontcp-server-linux-amd64
dragontcp-server-arm64
dragontcp-client-linux-amd64
dragontcp-client-android-arm64
dragontcp-client-arm64
dragontcp-client-armv7

The Go module and command directories were also renamed to DragonTCP. The existing UP/OK wire framing and chunk protocol were intentionally kept unchanged, so this branding change does not break compatibility with the previous protocol implementation.