AI: Setup Claude Code cli.

Author: ossrs-ai

.gitignore

@@ -1,4 +1,6 @@
 .idea
 srs-proxy
 .env
-.go-formarted
+.go-formarted
+.claude
+.vscode

CLAUDE.md

@@ -0,0 +1,87 @@
+# proxy-go Project Guidelines
+
+## Project Summary
+
+proxy-go is a stateless media streaming proxy with built-in load balancing for building scalable origin clusters. It supports RTMP, SRT, WebRTC (WHIP/WHEP), HLS, and HTTP-FLV protocols.
+
+Key characteristics:
+- Stateless design enables horizontal scaling
+- Built-in load balancer (memory or Redis-based)
+- Protocol handlers for RTMP, WebRTC, SRT, HTTP streaming
+- Backend origin servers register via System API
+- Official solution for SRS Origin Cluster
+
+## Design Overview
+
+See the "Design" section in @README.md for the complete architecture overview, including:
+- Stateless proxy architecture with built-in load balancing
+- Single Proxy Mode (memory-based)
+- Multi-Proxy Mode (Redis sync, AWS NLB)
+- Complete Cluster (Edge + Proxy + Origins)
+
+## Configuration
+
+All configuration via environment variables (`.env` file supported):
+
+### Server Listen Ports (client-facing)
+- `PROXY_RTMP_SERVER=11935` - RTMP media server
+- `PROXY_HTTP_SERVER=18080` - HTTP streaming (HLS, HTTP-FLV)
+- `PROXY_WEBRTC_SERVER=18000` - WebRTC server (UDP)
+- `PROXY_SRT_SERVER=20080` - SRT server (UDP)
+- `PROXY_HTTP_API=11985` - HTTP API (WHIP/WHEP)
+- `PROXY_SYSTEM_API=12025` - System API (origin registration)
+
+### Load Balancer Configuration
+- `PROXY_LOAD_BALANCER_TYPE=memory` - Use "memory" (single proxy) or "redis" (multi-proxy)
+- `PROXY_REDIS_HOST=127.0.0.1`
+- `PROXY_REDIS_PORT=6379`
+- `PROXY_REDIS_PASSWORD=` (empty for no password)
+- `PROXY_REDIS_DB=0`
+
+### Other Settings
+- `PROXY_STATIC_FILES=../srs/trunk/research` - Static web files directory
+- `PROXY_FORCE_QUIT_TIMEOUT=30s` - Force shutdown timeout
+- `PROXY_GRACE_QUIT_TIMEOUT=20s` - Graceful shutdown timeout
+
+## How to Run
+
+When running the project for testing or development, you should:
+1. Build and start the proxy server
+2. Publish a test stream using FFmpeg
+3. Verify the stream is working using ffprobe
+
+### Step 1: Build and Start Proxy Server
+
+```bash
+make && env PROXY_RTMP_SERVER=1935 PROXY_HTTP_SERVER=8080 \
+    PROXY_HTTP_API=1985 PROXY_WEBRTC_SERVER=8000 PROXY_SRT_SERVER=10080 \
+    PROXY_SYSTEM_API=12025 PROXY_LOAD_BALANCER_TYPE=memory ./srs-proxy
+```
+
+The proxy server should start and listen on the configured ports.
+
+### Step 2: Publish a Test Stream
+
+In a new terminal, publish a test stream using FFmpeg:
+
+```bash
+ffmpeg -stream_loop -1 -re -i ~/git/srs/trunk/doc/source.flv -c copy -f flv rtmp://localhost/live/livestream
+```
+
+> Note: `-stream_loop -1` makes FFmpeg loop the input file infinitely, ensuring the stream doesn't quit after the file ends.
+
+### Step 3: Verify Stream with ffprobe
+
+In another terminal, use ffprobe to verify the stream is working:
+
+**Test RTMP stream:**
+```bash
+ffprobe rtmp://localhost/live/livestream
+```
+
+**Test HTTP-FLV stream:**
+```bash
+ffprobe http://localhost:8080/live/livestream.flv
+```
+
+Both commands should successfully detect the stream and display video/audio codec information. If ffprobe shows stream details without errors, the proxy is working correctly.

README.md

@@ -13,5 +13,63 @@ can discover more details from SRS. And this proxy is the official solution to b
 an origin cluster for SRS. Please see [SRS Origin Cluster](https://ossrs.io/lts/en-us/docs/v7/doc/origin-cluster) 
 for details.
 
+## Design
+
+**proxy-go** is a stateless media streaming proxy with built-in load balancing that enables building scalable origin clusters. The proxy itself acts as the load balancer, routing streams from clients to backend origin servers.
+
+```
+Client → Proxy (with Load Balancer) → Backend Origin Servers
+```
+
+Since the proxy is stateless, you can deploy multiple proxies behind a load balancer (like AWS NLB) for horizontal scaling:
+
+```
+Client → AWS NLB → Proxy Servers → Backend Origin Servers
+```
+
+**Single Proxy Mode**
+
+Use case: Moderate amount of streams requiring multiple origin servers (each stream has few viewers). The total stream count is manageable by a single proxy server. Uses memory-based load balancing (no Redis needed).
+
+```
+                                       +--------------------+
+                               +-------+ Origin Server A    +
+                               +       +--------------------+
+                               +
++-----------------------+      +       +--------------------+
++   Proxy Server        +------+-------+ Origin Server B    +
++ (Memory LB)           +      +       +--------------------+
++-----------------------+      +
+                               +       +--------------------+
+                               +-------+ Origin Server C    +
+                                       +--------------------+
+```
+
+**Multi-Proxy Mode (Scalable)**
+
+Use case: When a single proxy becomes a bottleneck. Supports a large number of streams across many origin servers, with limited viewers per stream. Redis is required for state synchronization between proxies.
+
+```
+                         +-----------------------+
+                     +---+ Proxy Server A        +------+
++-----------------+  |   +-----------+-----------+      +
+|    AWS NLB      +--+               |                  +
++-----------------+  |          (Redis Sync)            + Origin Servers
+                     |   +-----------+-----------+      +
+                     +---+ Proxy Server B        +------+
+                         +-----------------------+
+```
+
+**Complete Cluster (Edge + Proxy + Origins)**
+
+Use case: Very large deployments with both numerous streams AND numerous viewers. Edge servers aggregate upstream connections - fetching one stream from upstream to serve multiple viewers, dramatically reducing load on proxy and origin servers.
+
+```
+Edge Servers → Proxy Servers → Origin Servers
+(Proxy + Cache)   (Proxy)      (SRS/Media)
+```
+
+> **Note**: Future edge servers will be implemented as proxy servers with caching enabled, creating a unified architecture where the same codebase serves both proxy and edge roles. The edge cache aggregates viewer connections, so thousands of viewers can watch the same stream while only requesting it once from upstream.
+
 William Yang<br/>
 June 23, 2025

rtmp.go

@@ -84,8 +84,8 @@ func (v *srsRTMPServer) Run(ctx context.Context) error {
 				defer conn.Close()
 
 				handleErr := func(err error) {
-					if isPeerClosedError(err) {
-						logger.Df(ctx, "RTMP peer is closed")
+					if isPeerClosedError(err) || isClosedNetworkError(err) {
+						logger.Df(ctx, "RTMP connection closed")
 					} else {
 						logger.Wf(ctx, "RTMP serve err %+v", err)
 					}
@@ -384,9 +384,19 @@ func (v *RTMPConnection) serve(ctx context.Context, conn *net.TCPConn) error {
 
 	// Reset the error if caused by another goroutine.
 	if r0 != nil {
+		// If backend connection closed normally, treat as normal disconnection
+		if isClosedNetworkError(r0) || isPeerClosedError(r0) {
+			logger.Df(ctx, "RTMP backend disconnected")
+			return nil
+		}
 		return errors.Wrapf(r0, "proxy backend->client")
 	}
 	if r1 != nil {
+		// If client connection closed normally, treat as normal disconnection
+		if isClosedNetworkError(r1) || isPeerClosedError(r1) {
+			logger.Df(ctx, "RTMP client disconnected")
+			return nil
+		}
 		return errors.Wrapf(r1, "proxy client->backend")
 	}
 

utils.go

@@ -148,12 +148,16 @@ func isClosedNetworkError(err error) bool {
 		return false
 	}
 
+	// Unwrap to get the underlying error
+	causeErr := errors.Cause(err)
+
 	// Check for "use of closed network connection" error
-	if netErr, ok := err.(*net.OpError); ok {
+	if netErr, ok := causeErr.(*net.OpError); ok {
 		return netErr.Err.Error() == "use of closed network connection"
 	}
 
-	return false
+	// Also check if the error message contains the text
+	return strings.Contains(causeErr.Error(), "use of closed network connection")
 }
 
 // convertURLToStreamURL convert the URL in HTTP request to special URLs. The unifiedURL is the URL