feat: SOCKS5 UDP ASSOCIATE relay, adaptive route engine, transport scanner & docs; fix YouTube comments

[Aria00pp]

Summary of Changes

1. Add SOCKS5 UDP ASSOCIATE and UDP relay support through exit node.
2. Add async adaptive route engine with SQLite route intelligence and stability-first scoring.
3. Add adaptive transport scan, engine and storage; complete Getting Started docs.
4. Harden adaptive transport routing correctness and lifecycle enforcement.
5. Harden adaptive transport route controller determinism and safety.
6. Fixed Youtube comments not loading (No VPS).

Motivation

• Enable low-latency UDP applications (games, VoIP, etc.) to use the proxy via SOCKS5 UDP ASSOCIATE by relaying UDP packets over the existing Apps Script exit-node chain.
• Reuse the current HTTPS-based relay/exit-node infrastructure so UDP can be proxied without adding a separate UDP transport path on the VPS.
• Provide a production-ready adaptive routing subsystem to improve session survivability and jitter consistency under hostile DPI/throttling (Iran 2026 use-cases) rather than chasing raw minimum latency.
• Replace ICMP probing with multi-signal probes (TCP connect, TLS handshake/ALPN, HTTP/2 preface, optional QUIC signal) to measure handshake consistency, jitter, and loss while avoiding obvious DPI triggers.
• Persist rolling route intelligence to prioritize historically stable routes, support warmup/retirement, and enable sticky-session behavior during active gameplay.
• Deliver a single coherent, merge-ready implementation path (no TODOs/future stubs) that is fully async, cancellable, and safe for scale and long-running use.
• Provide an adaptive route-scoring subsystem to rank Google-facing exit IPs by stability/jitter/loss for more reliable route selection.
• Expose the adaptive scanner from the CLI so users can run stability-first checks with --adaptive-scan.
• Improve first-run UX by expanding and clarifying the GETTING_STARTED.md pages (English and Farsi) into a full step-by-step guide.
• Ensure a single active route is strictly enforced and never bypassed by implicit fallbacks during active sessions.
• Introduce a strict session lifecycle so route switches are only permitted after explicit failure-triggered transitions.
• Persist real runtime metrics and apply time-decay + volatility penalties to make scoring reflect recent, stable performance.
• Remove synthetic probe successes and add safer concurrency/shutdown semantics to avoid orphan tasks and socket exhaustion.
• Eliminate nondeterminism, unsafe fallbacks, and orphan async work in the adaptive routing subsystem to ensure a single authoritative route is enforced and session lifecycle rules are never bypassed.
• Remove false-positive probe logic and strengthen persistence and scoring so route decisions reflect real, recent, and stable network behavior.

Description

• Added UDP handling to the exit-node by introducing _relay_udp_packet and supporting an udp JSON mode in apps_script/vps_exit_node.py to send a single UDP packet and return a response packet encoded in base64.
• Extended SOCKS5 negotiation in src/proxy/socks5.py to accept UDP ASSOCIATE (cmd 0x03) and return the command name together with the destination tuple as (, host, port).
• Updated src/proxy/proxy_server.py to dispatch udp_associate requests, added ProxyServer._handle_socks5_udp_associate to bind a datagram socket and reply with the bind address, and implemented _Socks5UdpRelayProtocol to forward UDP packets either directly or via the fronter's relay_udp_packet call and to wrap/unwrap SOCKS5 UDP headers.
• Implemented DomainFronter.relay_udp_packet in src/relay/domain_fronter.py to encapsulate a single UDP packet into the existing HTTPS relay payloads (k, udp, host, port, payload) and decode the base64 response for return.
• New async adaptive transport package src/core/adaptive_transport implementing probabilistic sampling, adaptive concurrency, cancellation support, rolling scoring and sticky-session selection, and a simple circuit breaker; primary engine at engine.py.
• Probing stack probe.py implements TCP connect timing, TLS handshake timing with ALPN, HTTP/2 preface checks, and an optional QUIC UDP signal; summarization computes median RTT, jitter, loss, handshake success, and stability metrics used in scoring.
• Persistence layer storage.py provides SQLite-backed route intelligence with decayed averages, cooldown and retire fields to favor historically stable routes and avoid full-range in-memory materialization.
• Hygiene hygiene.py rejects non-public/bogon/multicast/loopback/reserved addresses explicitly instead of silently clamping invalid input.
• Transport profile scaffolding transport_profiles.py provides protocol/fallback/fingerprint metadata for integration with VLESS+REALITY, HTTP/2, HTTP/3, UDP-over-TCP and QUIC wiring.
• CLI integration: main.py gains --adaptive-scan which runs an adaptive ranking flow over candidate fronting IPs and prints a stability-first ranking output.
• Tests: added tests/test_adaptive_transport.py covering IP hygiene, circuit-breaker failure counting, and sticky-session selection semantics.
• Files added/modified: main.py, and new package files src/core/adaptive_transport/init.py, models.py, hygiene.py, probe.py, storage.py, transport_profiles.py, engine.py, plus tests/test_adaptive_transport.py.
• Add a new adaptive transport package under src/core/adaptive_transport/ including engine.py, probe.py, models.py, hygiene.py, storage.py, transport_profiles.py, and init.py to perform concurrent probes, score routes, and persist intelligence to SQLite.
• Wire the adaptive engine into main.py by importing AdaptiveRouteEngine/ProbeTarget, adding the --adaptive-scan CLI flag, and printing a ranked list of candidate routes when invoked.
• Update the command-line behavior so --adaptive-scan runs the engine against CANDIDATE_IPS and exits with a human-readable ranking (score, median/jitter/loss/handshake metrics).
• Revise docs/GETTING_STARTED.md and docs/fa/GETTING_STARTED.md to a complete, practical walkthrough with clearer steps, commands, CA installation instructions, and examples for launcher/manual start.
• Add unit tests at tests/test_adaptive_transport.py covering IP hygiene, the engine circuit-breaker, and sticky route selection.
• Enforce session lifecycle and single active-route gating in AdaptiveRouteEngine with SessionState, session-locked route rejection, circuit-breaker hard-failure checks, and the bound_transport_route accessor (src/core/adaptive_transport/engine.py).
• Add controlled probe task bookkeeping and cancellation (_scan_tasks) and an awaited shutdown to ensure no orphan async tasks remain on re-scan/shutdown (src/core/adaptive_transport/engine.py).
• Add append-only runtime metrics model (RuntimeMetrics) and route_runtime_metrics time-series table, plus record_runtime_metrics API, to persist disconnects/retransmissions/latency-spikes/packet-delay-variance (src/core/adaptive_transport/models.py, src/core/adaptive_transport/storage.py).
• Replace prior simplistic scoring aggregation with a recency-decay weighting and volatility/metrics penalties in top_routes SQL to bias recent stable performance and penalize unstable routes (src/core/adaptive_transport/storage.py).
• Harden probe correctness by requiring negotiated HTTP/2 ALPN and reading a full HTTP/2 frame header before declaring H2 success, and remove synthetic QUIC success signaling so probes reflect real transport behavior (src/core/adaptive_transport/probe.py).
• Add structured decision logs for route selection and rejection reasons to support replayable routing decisions (src/core/adaptive_transport/engine.py).
• Enforce deterministic evaluation order by removing random sampling and sorting candidates by stable route key, and reduce concurrency limits for safer probe fan-out (src/core/adaptive_transport/engine.py).
• Strictly enforce a single active route and session lifecycle by rejecting candidate switches when a session is session_active, when switch_guard applies, or when the active route has not hard-failed, and expose session transition logs (src/core/adaptive_transport/engine.py).
• Centralize async probe task tracking, add a _stopped guard, and ensure shutdown cancels and awaits all scan tasks to prevent orphaned background tasks (src/core/adaptive_transport/engine.py).
• Tighten probe correctness: TLS now requires a negotiated ssl_object/version, HTTP/2 still requires ALPN h2 plus a valid frame header, and QUIC probe now sends an initial-like UDP packet and requires a real UDP response to mark success (src/core/adaptive_transport/probe.py).
• Make SQLite writes safer and append-only-friendly by enabling WAL and connection timeouts for write paths, and replace the top-route decay math with an exponential recency-weight and increased volatility penalty to prefer recent, stable routes (src/core/adaptive_transport/storage.py).
• Add structured logs for route_score_breakdown, route_rejected reasons, route_selected, and session_transition to allow deterministic replay of routing decisions (src/core/adaptive_transport/engine.py).

Testing

• Ran the automated unit test suite with pytest -q, and the tests completed successfully.
• Performed a basic smoke check of SOCKS5 negotiation to ensure CONNECT and UDP ASSOCIATE handshakes complete and that UDP packets are forwarded by the new datagram protocol (success).
• Ran unit test suite: pytest -q (output: 21 passed).
• Performed bytecode verification: python -m py_compile main.py src/core/adaptive_transport/*.py (succeeded with no syntax errors).
• Checked for unresolved merge markers: rg -n '<<<<<<<|=======|>>>>>>>' . (no conflict markers in modified code paths).
• Commands run exactly as executed: pytest -q; python -m py_compile main.py src/core/adaptive_transport/*.py; rg -n '<<<<<<<|=======|>>>>>>>' ..
• Ran the new unit tests in tests/test_adaptive_transport.py using python -m unittest, and they passed.
• Exercised the CLI --adaptive-scan code path locally to verify the engine instantiation and printed ranking output (smoke test succeeded).
• Ran pytest -q and all tests passed: 21 passed.
• Executed a runtime smoke script exercising sticky-route behavior, failure-triggered transition, binding accessor, and shutdown, which completed successfully (smoke_ok).
• Scanned sources and tests for unresolved markers using rg and found no TODO or merge-conflict markers.
• Ran pytest -q and all tests passed (21 passed).
• Ran a runtime smoke test that exercised select_route sticky behavior, failure-triggered switch, and clean shutdown, which completed successfully and printed smoke ok.
• Verified repository hygiene with python -m compileall -q src, and searches found no merge conflict markers or TODO/FIXME tokens.
• Confirmed that shutdown cancels/awaits scan tasks in the smoke test and automated runs (no async task leaks observed).

Known Issues

• Higher script.google.com relay gas (quota consumption)
  The new UDP relay and adaptive transport probing increase traffic through the Apps Script exit node, which can lead to accelerated consumption of the scripts.google.com relay gas (Google Apps Script daily quotas). This is especially noticeable during active UDP sessions and when running the adaptive scanner.
  We are tracking this for future optimization.

• UDP gaming and real‑time workload validation pending
  The SOCKS5 UDP ASSOCIATE relay has passed unit, protocol handshake, and basic smoke tests, but has not yet been validated under real‑world gaming or high‑frequency real‑time communication workloads (e.g., competitive FPS, VoIP, low‑latency streaming). Performance characteristics such as relay‑induced jitter, packet reordering, throughput ceilings, and long‑session stability under actual game traffic remain unverified.
  We recommend treating the UDP path as experimental for gaming purposes and conducting targeted latency/jitter tests under your own network conditions before relying on it for latency‑sensitive titles. Feedback and measurement data are very welcome and will help harden the relay for production gaming use.