Merge pull request #73 from NodePassProject/main

Connection pooling enhancement, UDP control support, Timeout management upgrade

Author: yosebyte

docs/en/api.md

@@ -1578,7 +1578,8 @@ Examples:
 | `min` | Minimum pool capacity | Integer > 0 | `64` | Client dual-end handshake mode only |
 | `max` | Maximum pool capacity | Integer > 0 | `1024` | Dual-end handshake mode |
 | `mode` | Runtime mode control | `0`(auto), `1`(force mode 1), `2`(force mode 2) | `0` | Both |
-| `read` | Read timeout duration | Time duration (e.g., `10m`, `30s`, `1h`) | `10m` | Both |
+| `read` | Read timeout duration | Time duration (e.g., `10m`, `30s`, `1h`) | `0` | Both |
 | `rate` | Bandwidth rate limit | Integer (Mbps), 0=unlimited | `0` | Both |
 | `slot` | Connection slot count | Integer (1-65536) | `65536` | Both |
-| `proxy` | PROXY protocol support | `0`(disabled), `1`(enabled) | `0` | Both |
+| `proxy` | PROXY protocol support | `0`(disabled), `1`(enabled) | `0` | Both |
+| `noudp` | UDP support control | `0`(enabled), `1`(disabled) | `0` | Both |

docs/en/configuration.md

@@ -125,39 +125,37 @@ Example:
 nodepass "client://server.example.com:10101/127.0.0.1:8080?min=32"
 ```
 
-## Data Read Timeout and Connection Reuse
+## Data Read Timeout
 
-The `read` parameter controls both data read timeout and connection pool reuse behavior:
+The `read` parameter controls data read timeout behavior:
 
-- `read`: Data read timeout and connection reuse (default: 0, meaning no timeout and no connection recycling)
-  - Value 0 or omitted: No data read timeout, connections are not recycled to the pool after data transfer completes
-  - Positive integer with time unit: Sets read timeout and enables connection reuse
+- `read`: Data read timeout (default: 0, meaning no timeout)
+  - Value 0 or omitted: No data read timeout
+  - Positive integer with time unit: Sets read timeout
     - Value format: integer followed by unit (`s` for seconds, `m` for minutes, `h` for hours)
     - Examples: `30s` (30 seconds), `5m` (5 minutes), `1h` (1 hour)
     - If no data is received within the timeout period, the connection is closed
-    - After data transfer completes, the connection is recycled to the pool for reuse
   - Applies to both client and server modes
 
 Example:
 ```bash
-# Set data read timeout to 5 minutes, enable connection reuse
+# Set data read timeout to 5 minutes
 nodepass "client://server.example.com:10101/127.0.0.1:8080?read=5m"
 
-# Set data read timeout to 30 seconds for fast-response applications, enable connection reuse
+# Set data read timeout to 30 seconds for fast-response applications
 nodepass "client://server.example.com:10101/127.0.0.1:8080?read=30s"
 
-# Set data read timeout to 1 hour for long-running transfers, enable connection reuse
+# Set data read timeout to 1 hour for long-running transfers
 nodepass "client://server.example.com:10101/127.0.0.1:8080?read=1h"
 
-# Default behavior: no timeout and no connection recycling (omit read parameter or set to 0)
+# Default behavior: no timeout (omit read parameter or set to 0)
 nodepass "client://server.example.com:10101/127.0.0.1:8080"
 ```
 
-**Connection Reuse Use Cases:**
-- **HTTP Short Connections**: Set reasonable read timeout and enable connection reuse for frequent short connections to improve pool utilization
-- **Long Connection Optimization**: Set larger timeout values for long-lived connections while avoiding resource waste
-- **Resource Control**: Enable connection recycling by setting timeout in scenarios requiring strict connection lifecycle control
-- **Default Mode**: Use the default no-timeout no-recycling mode for scenarios requiring maximum flexibility
+**Data Read Timeout Use Cases:**
+- **Connection Management**: Prevent idle connections from consuming resources indefinitely
+- **Resource Control**: Set appropriate timeouts based on expected data transfer patterns
+- **Network Reliability**: Handle network interruptions gracefully with automatic cleanup
 
 ## Rate Limiting
 NodePass supports bandwidth rate limiting for traffic control through the `rate` parameter. This feature helps prevent network congestion and ensures fair resource allocation across multiple connections.
@@ -264,6 +262,43 @@ nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&proxy=1&rate=100"
 - The header format follows the HAProxy PROXY protocol v1 specification
 - If the target service doesn't support PROXY protocol, connections may fail or behave unexpectedly
 
+## UDP Support Control
+
+NodePass supports UDP traffic tunneling in addition to TCP. The `noudp` parameter allows you to disable UDP support when only TCP traffic needs to be handled, which can reduce resource usage and simplify configuration.
+
+- `noudp`: UDP support control (default: 0)
+  - Value 0: UDP support enabled - both TCP and UDP traffic will be tunneled
+  - Value 1: UDP support disabled - only TCP traffic will be tunneled, UDP packets are ignored
+  - Applies to both client and server modes
+  - When disabled, UDP-related resources (buffers, connections, sessions) are not allocated
+
+Example:
+```bash
+# Enable UDP support (default behavior)
+nodepass "server://0.0.0.0:10101/0.0.0.0:8080?noudp=0"
+
+# Disable UDP support for TCP-only scenarios
+nodepass "server://0.0.0.0:10101/0.0.0.0:8080?noudp=1"
+
+# Client with UDP disabled
+nodepass "client://server.example.com:10101/127.0.0.1:8080?noudp=1"
+
+# Combined with other parameters
+nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&noudp=1"
+```
+
+**UDP Support Control Use Cases:**
+- **TCP-Only Services**: Disable UDP when tunneling only TCP-based applications
+- **Resource Optimization**: Reduce memory and CPU usage by avoiding UDP processing overhead
+- **Security**: Prevent UDP-based attacks or unwanted traffic in restricted environments
+- **Simplified Configuration**: Easier setup when UDP tunneling is not required
+- **Network Isolation**: Isolate TCP and UDP traffic handling for better control
+
+**Important Notes:**
+- When UDP is disabled, any UDP packets sent to the tunnel will be silently dropped
+- Existing UDP sessions will be terminated when switching to noudp=1
+- UDP buffer pools and session management are disabled when noudp=1
+
 ## Target Address Groups and Load Balancing
 
 NodePass supports configuring multiple target addresses to achieve high availability and load balancing. Target address groups are only applicable to the egress side (the final destination of traffic) and should not be used on the ingress side.
@@ -334,10 +369,11 @@ NodePass allows flexible configuration via URL query parameters. The following t
 | `min`     | Minimum pool capacity | `64`    |   X    |   O    |   X    |
 | `max`     | Maximum pool capacity | `1024`  |   O    |   X    |   X    |
 | `mode`    | Run mode control      | `0`     |   O    |   O    |   X    |
-| `read`    | Data read timeout and connection reuse | `0` |   O    |   O    |   X    |
+| `read`    | Data read timeout      | `0` |   O    |   O    |   X    |
 | `rate`    | Bandwidth rate limit  | `0`     |   O    |   O    |   X    |
 | `slot`    | Maximum connection limit | `65536` |   O    |   O    |   X    |
 | `proxy`   | PROXY protocol support| `0`     |   O    |   O    |   X    |
+| `noudp`   | UDP support control    | `0`     |   O    |   O    |   X    |
 
 - O: Parameter is valid and recommended for configuration
 - X: Parameter is not applicable and should be ignored
@@ -347,6 +383,7 @@ NodePass allows flexible configuration via URL query parameters. The following t
 - For client/server dual-end handshake modes, adjust connection pool capacity (`min`, `max`) based on traffic and resource constraints for optimal performance.
 - Use run mode control (`mode`) when automatic detection doesn't match your deployment requirements or for consistent behavior across environments.
 - Configure rate limiting (`rate`) to control bandwidth usage and prevent network congestion in shared environments.
+- Set `noudp=1` when only TCP traffic needs to be tunneled to reduce resource usage and simplify configuration.
 - Log level (`log`) can be set in all modes for easier operations and troubleshooting.
 
 ## Environment Variables

docs/en/how-it-works.md

@@ -148,6 +148,7 @@ The data flow mode is automatically determined based on tunnel address and targe
    - For UDP: Direct datagram forwarding to target address with minimal latency
    - Simplified data path ensuring reliable and efficient forwarding
 
+### Specific protocol characteristics
 - **TCP Exchange**: 
   - Persistent connections for full-duplex communication
   - Continuous data streaming until connection termination
@@ -156,7 +157,7 @@ The data flow mode is automatically determined based on tunnel address and targe
 
 - **UDP Exchange**:
   - One-shot datagram forwarding with configurable buffer sizes (`UDP_DATA_BUF_SIZE`)
-  - Read timeout control for response waiting (`read` parameter or default 10m)
+  - Read timeout control for response waiting (`read` parameter or default 0)
   - Optimized for low-latency, stateless communication
   - **Client Single-End Forwarding Optimization**: Direct forwarding mechanism with minimal latency
 
@@ -266,10 +267,10 @@ The connection pool design follows the principle of "warm-up over cold start," e
    - Intelligent session timeout management, balancing resource usage and responsiveness
    - Session reuse mechanisms, reducing connection establishment overhead
 
-2. **TCP Connection Reuse**:
-   - Long connection keep-alive technology, reducing connection establishment/closure overhead
-   - Intelligent connection reuse strategies, maximizing connection utilization
-   - Connection health checks, ensuring reliability of reused connections
+2. **TCP Connection Management**:
+   - Connection pool management for efficient resource utilization
+   - One-time use model for connection pool entries to ensure state cleanliness
+   - Connection health monitoring and automatic cleanup
 
 3. **Cross-Protocol Unified Management**:
    - Unified connection lifecycle management, simplifying system complexity

docs/en/installation.md

@@ -4,7 +4,7 @@ This guide provides detailed instructions for installing NodePass using differen
 
 ## System Requirements
 
-- Go 1.24 or higher (for building from source)
+- Go 1.25 or higher (for building from source)
 - Network connectivity between server and client endpoints
 - Admin privileges may be required for binding to ports below 1024
 

docs/en/troubleshooting.md

@@ -70,7 +70,7 @@ This guide helps you diagnose and resolve common issues you might encounter when
 
 3. **Timeout Configuration**
    - Adjust `NP_UDP_DIAL_TIMEOUT` if using UDP with slow response times
-   - Increase `read` parameter in URL for long-running transfers (default: 10m)
+   - Increase `read` parameter in URL for long-running transfers (default: 0)
    - Consider adjusting `NP_TCP_DIAL_TIMEOUT` for unstable network conditions
 
 4. **Overloaded Server**

docs/en/usage.md

@@ -22,7 +22,7 @@ Common query parameters:
 - `min=<min_pool>`: Minimum connection pool capacity (default: 64, set by client)
 - `max=<max_pool>`: Maximum connection pool capacity (default: 1024, set by server and delivered to client)
 - `mode=<run_mode>`: Run mode control (`0`, `1`, or `2`) - controls operational behavior
-- `read=<timeout>`: Data read timeout duration (default: 10m, supports time units like 30s, 5m, 30m, etc.)
+- `read=<timeout>`: Data read timeout duration (default: 0, supports time units like 30s, 5m, 1h, etc.)
 - `rate=<mbps>`: Bandwidth rate limit in Mbps (default: 0 for unlimited)
 - `proxy=<mode>`: PROXY protocol support (default: `0`, `1` enables PROXY protocol v1 header transmission)
 
@@ -59,7 +59,7 @@ nodepass "server://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_
   - `0`: Automatic detection (default) - attempts local binding first, falls back if unavailable
   - `1`: Force reverse mode - server binds to target address locally and receives traffic
   - `2`: Force forward mode - server connects to remote target address
-- `read`: Data read timeout duration (default: 10m, supports time units like 30s, 5m, 30m, etc.)
+- `read`: Data read timeout duration (default: 0, supports time units like 30s, 5m, 1h, etc.)
 - `rate`: Bandwidth rate limit (default: 0 means no limit)
 - `proxy`: PROXY protocol support (default: `0`, `1` enables PROXY protocol v1 header before data transfer)
 
@@ -114,7 +114,7 @@ nodepass "client://<tunnel_addr>/<target_addr>?log=<level>&min=<min_pool>&mode=<
   - `0`: Automatic detection (default) - attempts local binding first, falls back to handshake mode
   - `1`: Force single-end forwarding mode - local proxy with connection pooling
   - `2`: Force dual-end handshake mode - requires server coordination
-- `read`: Data read timeout duration (default: 10m, supports time units like 30s, 5m, 30m, etc.)
+- `read`: Data read timeout duration (default: 0, supports time units like 30s, 5m, 1h, etc.)
 - `rate`: Bandwidth rate limit (default: 0 means no limit)
 - `proxy`: PROXY protocol support (default: `0`, `1` enables PROXY protocol v1 header before data transfer)
 

docs/zh/api.md

@@ -1578,7 +1578,8 @@ client://<server_host>:<server_port>/<local_host>:<local_port>?<parameters>
 | `min` | 最小连接池容量 | 整数 > 0 | `64` | 仅客户端双端握手模式 |
 | `max` | 最大连接池容量 | 整数 > 0 | `1024` | 双端握手模式 |
 | `mode` | 运行模式控制 | `0`(自动), `1`(强制模式1), `2`(强制模式2) | `0` | 两者 |
-| `read` | 读取超时时间 | 时间长度 (如 `10m`, `30s`, `1h`) | `10m` | 两者 |
+| `read` | 读取超时时间 | 时间长度 (如 `10m`, `30s`, `1h`) | `0` | 两者 |
 | `rate` | 带宽速率限制 | 整数 (Mbps), 0=无限制 | `0` | 两者 |
 | `slot` | 连接槽位数 | 整数 (1-65536) | `65536` | 两者 |
-| `proxy` | PROXY协议支持 | `0`(禁用), `1`(启用) | `0` | 两者 |
+| `proxy` | PROXY协议支持 | `0`(禁用), `1`(启用) | `0` | 两者 |
+| `noudp` | UDP支持控制 | `0`(启用), `1`(禁用) | `0` | 两者 |

docs/zh/configuration.md

@@ -125,39 +125,37 @@ nodepass "server://0.0.0.0:10101/remote.example.com:8080?mode=2"
 nodepass "client://server.example.com:10101/127.0.0.1:8080?min=32"
 ```
 
-## 数据读取超时与连接重用
+## 数据读取超时
 
-`read`参数用于控制数据读取超时时间和连接池连接的重用行为：
+`read`参数用于控制数据读取超时行为：
 
-- `read`: 数据读取超时时间（默认: 0，表示无超时且不回收连接）
-  - 值为0或省略：无数据读取超时，连接在数据传输完成后不回收到连接池
-  - 正整数加时间单位：设置读取超时时间，并启用连接重用
+- `read`: 数据读取超时时间（默认: 0，表示无超时）
+  - 值为0或省略：无数据读取超时
+  - 正整数加时间单位：设置读取超时时间
     - 值格式：整数后跟单位（`s`表示秒，`m`表示分钟，`h`表示小时）
     - 示例：`30s`（30秒），`5m`（5分钟），`1h`（1小时）
     - 如果在超时时间内未接收到数据，连接将被关闭
-    - 数据传输完成后，连接将被回收到连接池供重用
   - 适用于客户端和服务端模式
 
 示例：
 ```bash
-# 设置数据读取超时为5分钟，启用连接重用
+# 设置数据读取超时为5分钟
 nodepass "client://server.example.com:10101/127.0.0.1:8080?read=5m"
 
-# 设置数据读取超时为30秒，适用于快速响应应用，启用连接重用
+# 设置数据读取超时为30秒，适用于快速响应应用
 nodepass "client://server.example.com:10101/127.0.0.1:8080?read=30s"
 
-# 设置数据读取超时为1小时，适用于长时间传输，启用连接重用
+# 设置数据读取超时为1小时，适用于长时间传输
 nodepass "client://server.example.com:10101/127.0.0.1:8080?read=1h"
 
-# 默认行为：无超时且不回收连接（省略read参数或设置为0）
+# 默认行为：无超时（省略read参数或设置为0）
 nodepass "client://server.example.com:10101/127.0.0.1:8080"
 ```
 
-**连接重用使用场景：**
-- **HTTP短连接**：为频繁的短连接设置合理的读取超时并启用连接重用，提高连接池利用率
-- **长连接优化**：为长时间保持的连接设置较大的超时值，同时避免资源浪费
-- **资源控制**：在需要严格控制连接生命周期的场景下，通过设置超时启用连接回收
-- **默认模式**：对于需要最大灵活性的场景，使用默认的无超时不回收模式
+**数据读取超时使用场景：**
+- **连接管理**：防止空闲连接无限期消耗资源
+- **资源控制**：根据预期的数据传输模式设置适当的超时时间
+- **网络可靠性**：优雅处理网络中断，通过自动清理
 
 ## 速率限制
 NodePass支持通过`rate`参数进行带宽速率限制，用于流量控制。此功能有助于防止网络拥塞，确保多个连接间的公平资源分配。
@@ -264,6 +262,43 @@ nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&proxy=1&rate=100"
 - 头部格式遵循HAProxy PROXY协议v1规范
 - 如果目标服务不支持PROXY协议，将导致连接失败
 
+## UDP支持控制
+
+除了TCP之外，NodePass还支持UDP流量隧道。`noudp`参数允许您在只需要处理TCP流量时禁用UDP支持，这样可以减少资源使用并简化配置。
+
+- `noudp`: UDP支持控制（默认: 0）
+  - 值为0：启用UDP支持 - TCP和UDP流量都将被隧道传输
+  - 值为1：禁用UDP支持 - 仅TCP流量将被隧道传输，UDP数据包将被忽略
+  - 适用于客户端和服务端模式
+  - 禁用时，不会分配UDP相关的资源（缓冲区、连接、会话）
+
+示例：
+```bash
+# 启用UDP支持（默认行为）
+nodepass "server://0.0.0.0:10101/0.0.0.0:8080?noudp=0"
+
+# 为仅TCP场景禁用UDP支持
+nodepass "server://0.0.0.0:10101/0.0.0.0:8080?noudp=1"
+
+# 禁用UDP的客户端
+nodepass "client://server.example.com:10101/127.0.0.1:8080?noudp=1"
+
+# 与其他参数组合使用
+nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&noudp=1"
+```
+
+**UDP支持控制使用场景：**
+- **仅TCP服务**：仅隧道传输TCP应用时禁用UDP
+- **资源优化**：通过避免UDP处理开销减少内存和CPU使用
+- **安全性**：在受限环境中防止基于UDP的攻击或不需要的流量
+- **简化配置**：不需要UDP隧道时更容易设置
+- **网络隔离**：更好地控制TCP和UDP流量处理
+
+**重要说明：**
+- 禁用UDP时，发送到隧道的任何UDP数据包都将被静默丢弃
+- 切换到noudp=1时，现有的UDP会话将被终止
+- 当noudp=1时，UDP缓冲池和会话管理被禁用
+
 ## 目标地址组与负载均衡
 
 NodePass支持配置多个目标地址以实现高可用性和负载均衡。目标地址组功能仅适用于出口端（流量最终到达的目的地），不应在入口端使用。
@@ -334,10 +369,11 @@ NodePass支持通过URL查询参数进行灵活配置，不同参数在 server
 | `min`     | 最小连接池容量       | `64`      |   X    |   O    |   X    |
 | `max`     | 最大连接池容量       | `1024`    |   O    |   X    |   X    |
 | `mode`    | 运行模式控制         | `0`       |   O    |   O    |   X    |
-| `read`    | 数据读取超时与连接重用 | `0`     |   O    |   O    |   X    |
+| `read`    | 数据读取超时          | `0`       |   O    |   O    |   X    |
 | `rate`    | 带宽速率限制         | `0`       |   O    |   O    |   X    |
 | `slot`    | 最大连接数限制       | `65536`   |   O    |   O    |   X    |
 | `proxy`   | PROXY协议支持        | `0`       |   O    |   O    |   X    |
+| `noudp`   | UDP支持控制          | `0`       |   O    |   O    |   X    |
 
 - O：参数有效，推荐根据实际场景配置
 - X：参数无效，忽略设置
@@ -347,6 +383,7 @@ NodePass支持通过URL查询参数进行灵活配置，不同参数在 server
 - client/server 双端握手模式建议根据流量和资源情况调整连接池容量（min/max），优化性能。
 - 当自动检测不符合部署需求时或需要跨环境一致行为时，使用运行模式控制（mode）。
 - 配置速率限制（rate）以控制带宽使用，防止共享环境中的网络拥塞。
+- 仅需要隧道传输TCP流量时设置`noudp=1`，以减少资源使用并简化配置。
 - 日志级别（log）可在所有模式下灵活调整，便于运维和排查。
 
 ## 环境变量