From b7cd4b51cbe359de25aeaef6b3e39a1541ac23c0 Mon Sep 17 00:00:00 2001
From: yusing <yusing.wys@gmail.com>
Date: Thu, 8 Jan 2026 20:53:38 +0800
Subject: [PATCH] docs(stream): enhance documentation

---
 agent/pkg/agent/stream/README.md | 100 +++++++++++++++++++++++++++++--
 1 file changed, 96 insertions(+), 4 deletions(-)

diff --git a/agent/pkg/agent/stream/README.md b/agent/pkg/agent/stream/README.md
index 98b1bdcb..b49ff7b7 100644
--- a/agent/pkg/agent/stream/README.md
+++ b/agent/pkg/agent/stream/README.md
@@ -1,6 +1,30 @@
 # Stream proxy protocol
 
-This package implements a small header-based handshake that allows an authenticated client to request forwarding to a `(host, port)` destination.
+This package implements a small header-based handshake that allows an authenticated client to request forwarding to a `(host, port)` destination. It supports both TCP-over-TLS and UDP-over-DTLS transports.
+
+## Overview
+
+```mermaid
+graph TD
+    subgraph Client
+        TC[TCPClient] -->|TLS| TSS[TCPServer]
+        UC[UDPClient] -->|DTLS| USS[UDPServer]
+    end
+
+    subgraph Stream Protocol
+        H[StreamRequestHeader]
+    end
+
+    TSS -->|Redirect| DST1[Destination TCP]
+    USS -->|Forward UDP| DST2[Destination UDP]
+
+    subgraph Connection Management
+        CM[ConnectionManager]
+    end
+
+    TSS -.-> CM
+    USS -.-> CM
+```
 
 ## Header
 
@@ -17,7 +41,29 @@ Total: `headerSize = 8 + 1 + 255 + 1 + 5 + 4 = 273` bytes.
 
 Checksum is `crc32.ChecksumIEEE(header[0:headerSize-4])`.
 
-See [`StreamRequestHeader`](header.go:10).
+See [`StreamRequestHeader`](header.go:25).
+
+## File Structure
+
+| File                                | Purpose                                                      |
+| ----------------------------------- | ------------------------------------------------------------ |
+| [`header.go`](header.go)            | Stream request header structure and validation.              |
+| [`tcp_client.go`](tcp_client.go:26) | TCP client implementation with TLS transport.                |
+| [`tcp_server.go`](tcp_server.go:45) | TCP server implementation for handling stream requests.      |
+| [`udp_client.go`](udp_client.go:27) | UDP client implementation with DTLS transport.               |
+| [`udp_server.go`](udp_server.go:26) | UDP server implementation for handling DTLS stream requests. |
+| [`common.go`](common.go:31)         | Connection manager and shared constants.                     |
+
+## Constants
+
+| Constant       | Value                     | Purpose                                           |
+| -------------- | ------------------------- | ------------------------------------------------- |
+| `StreamALPN`   | `"godoxy-agent-stream/1"` | TLS ALPN protocol for stream multiplexing.        |
+| `headerSize`   | `273` bytes               | Total size of the stream request header.          |
+| `dialTimeout`  | `10s`                     | Timeout for establishing destination connections. |
+| `readDeadline` | `10s`                     | Read timeout for UDP destination sockets.         |
+
+See [`common.go`](common.go:11).
 
 ## TCP behavior
 
@@ -27,7 +73,13 @@ See [`StreamRequestHeader`](header.go:10).
 
 Server reads the header using `io.ReadFull` to avoid dropping bytes.
 
-See [`NewTCPClient()`](tcp_client.go:15) and [`(*TCPServer).redirect()`](tcp_server.go:77).
+See [`NewTCPClient()`](tcp_client.go:26) and [`(*TCPServer).redirect()`](tcp_server.go:116).
+
+### TCP Server variants
+
+- [`NewTCPServer()`](tcp_server.go:45) - Creates a fully-configured TCP server with TLS listener.
+- [`NewTCPServerFromListener()`](tcp_server.go:36) - Wraps an existing TLS listener.
+- [`NewTCPServerHandler()`](tcp_server.go:24) - Handler for ALPN-multiplexed connections.
 
 ## UDP-over-DTLS behavior
 
@@ -39,4 +91,44 @@ See [`NewTCPClient()`](tcp_client.go:15) and [`(*TCPServer).redirect()`](tcp_ser
 
 Responses do **not** include a header.
 
-See [`NewUDPClient()`](udp_client.go:17) and [`(*UDPServer).handleDTLSConnection()`](udp_server.go:67).
+See [`NewUDPClient()`](udp_client.go:27) and [`(*UDPServer).handleDTLSConnection()`](udp_server.go:89).
+
+## Connection Management
+
+The [`ConnectionManager`](common.go:26) handles destination connection pooling:
+
+- Each client connection gets a unique destination connection.
+- Connections are created on-demand and cached by client remote address.
+- Connections are closed when the client disconnects.
+
+```go
+// Get or create a destination connection for the given host:port
+conn, err := connMgr.GetOrCreateDestConnection(clientConn, host, port)
+
+// Clean up when client disconnects
+connMgr.DeleteDestConnection(clientConn)
+```
+
+## Error Handling
+
+| Error              | Description                                     |
+| ------------------ | ----------------------------------------------- |
+| `ErrInvalidHeader` | Header validation failed (version or checksum). |
+
+See [`header.go`](header.go:23).
+
+## Integration
+
+This package is used by the agent to provide stream tunneling capabilities. See the parent [`agent`](../README.md) package for integration details with the GoDoxy server.
+
+### Certificate Requirements
+
+Both TCP and UDP servers require:
+
+- CA certificate for client verification
+- Server certificate for TLS/DTLS termination
+
+Both clients require:
+
+- CA certificate for server verification
+- Client certificate for mTLS authentication