fix: isolate rejected UDP targets from SOCKS associations

[cppla]

Summary

Keep a multi-target SOCKS5 UDP association usable when opening one H3 CONNECT-UDP target is rejected.

Previously, direct H3 PacketConn could keep a healthy target after a signed target failure, but the SOCKS frontend treated that Send error as terminal and closed the whole association. This interrupted unrelated healthy traffic while the physical H3 connection remained available.

• Mark only lazy-target authenticated HTTP 502/503 and known local target/session admission limits with transport.ErrPacketTargetUnavailable.
• Preserve the underlying cause through errors.Is / errors.As; keep signed-response path-health evidence unchanged.
• SOCKS drops only that datagram and continues using the existing association. No automatic retry, admission increase or wire/authentication change.
• Authentication, cancellation, timeout, connection, unknown and existing-session send failures remain terminal.
• Document the per-target boundary and clarify that only fresh authenticated H3 responses can restore path health, never cached UDP enqueue.

Validation

• make check and make race: passed locally.
• Frontend wrapped-error survival plus terminal-error tests: race x20 passed.
• Real SOCKS5 + H3 signed 502 / server-capacity 503 tests: race x10 passed (20 subtests). Same TCP control, physical H3 connection and healthy target are retained; no failed-packet retry or leaked client admission.
• Exact old main 1740df2 production overlay with the same new regression failed both 502 and 503 cases with control TCP EOF. Separate real old-version diagnostics verified the H3 connection itself stayed alive.
• Rejected first/bootstrap target followed by a healthy target at capacity one: race x5 passed, including admission cleanup.
• Existing local/global capacity and web-auto health regressions strengthened; focused race x5 passed.
• Independent scope, classification, resource and secrets review found no remaining blocker.

Evidence is local bounded functionality/error-isolation testing, not a broad weak-network, passive-identification or Internet-performance claim. No historical remote host, full corpus, or release used.

Exact head 729befc20c83477e6012048bf9be8705a52b1fdb passed CI (35807912577, all 10 jobs), CodeQL (35807912416), and Linux netem (35807912489). Container integration, OCI index build and the namespace/netem suite all completed successfully. No unresolved review threads at merge check. Post-merge main f31400434562d4426e38d76009d287a40fd10106 also passed CI (35808176990, all 10 jobs including Docker integration/OCI build), CodeQL (35808176937), and Linux netem (35808177027, actual namespace suite plus diagnostics upload). Main tree d7abfb0d58914b83284c561ea602d40847cb1ba9 equals the tested PR tree; local main is synchronized and clean. Copilot review reported no findings; its initial pending-CI note is superseded by these completed exact-head/main gates. No release created.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Exact-head CI, CodeQL, and Linux netem verification remain pending.

Review effort: Lite
Findings: None

What changed in this PR

This PR isolates rejected UDP targets so shared SOCKS5 associations remain usable.

Changes:

• Classifies recoverable target failures while preserving causes.
• Keeps SOCKS associations alive for rejected datagrams.
• Adds regression tests and documents target and health semantics.

File	Description
internal/​tunnel/​web_udp.go	Classifies recoverable target errors.
internal/​tunnel/​web_udp_test.go	Extends capacity behavior tests.
internal/​tunnel/​web_udp_target_error_test.go	Tests error classification and cause retention.
internal/​tunnel/​web_udp_socks_isolation_test.go	Tests SOCKS/H3 association isolation.
internal/​tunnel/​web_client_udp_health_test.go	Verifies H3 health semantics.
internal/​transport/​transport.go	Defines the target-unavailable error contract.
internal/​proxy/​socks5.go	Drops recoverable target datagrams without closing associations.
internal/​proxy/​socks5_udp_target_error_test.go	Tests recoverable and terminal SOCKS errors.
docs/​WEB_COVER.md	Documents per-target behavior.
docs/​PROTOCOL.md	Documents protocol and health semantics.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.