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

apps_script/vps_exit_node.py

@@ -34,6 +34,7 @@
 import logging
 import os
 import re
+import socket
 import socketserver
 import sys
 import urllib.error
@@ -209,6 +210,23 @@ def _relay_request(
         }
 
 
+
+
+def _relay_udp_packet(host: str, port: int, payload: bytes) -> dict:
+    """Send one UDP packet and return one response packet (best effort)."""
+    if not host or port <= 0 or port > 65535:
+        return {"e": "bad_udp_target"}
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.settimeout(2.0)
+        sock.sendto(payload, (host, port))
+        data, _ = sock.recvfrom(65535)
+        return {"ok": True, "payload": base64.b64encode(data).decode()}
+    except Exception as exc:
+        return {"e": str(exc) or type(exc).__name__}
+    finally:
+        sock.close()
+
 # ---------------------------------------------------------------------------
 # HTTP request handler
 # ---------------------------------------------------------------------------
@@ -265,6 +283,7 @@ def do_POST(self):  # noqa: N802
         m = str(body.get("m") or "GET").upper()
         h = _sanitize_headers(body.get("h"))
         b64 = body.get("b")
+        udp_mode = bool(body.get("udp"))
 
         if not _PSK:
             self._send_json(500, {"e": "server_psk_missing"})
@@ -275,6 +294,25 @@ def do_POST(self):  # noqa: N802
             self._send_json(401, {"e": "unauthorized"})
             return
 
+
+        if udp_mode:
+            host = str(body.get("host") or "")
+            try:
+                port = int(body.get("port") or 0)
+            except Exception:
+                port = 0
+            payload = b""
+            pb64 = body.get("payload")
+            if isinstance(pb64, str) and pb64:
+                try:
+                    payload = base64.b64decode(pb64)
+                except Exception:
+                    self._send_json(400, {"e": "bad_udp_payload"})
+                    return
+            result = _relay_udp_packet(host, port, payload)
+            self._send_json(200, result)
+            return
+
         if not _safe_url(u):
             self._send_json(400, {"e": "bad_url"})
             return

docs/GETTING_STARTED.md

@@ -1,156 +1,218 @@
-# Getting Started
+# Getting Started (Complete Guide)
 
-This guide keeps only the setup path most users need. Follow it once, then come back to the root README only when you need another topic.
+This is the **full, practical setup guide** for first-time users.
+If you follow this page in order, you can go from zero to a working proxy.
 
-## What You Need
+---
 
-- Python 3.10 or newer
-- A free Google account
-- Git, or the ZIP download from GitHub
-- A browser where you can set an HTTP proxy
+## Quick Outcome
 
-## 1. Get The Project
+When done correctly:
+- Local HTTP proxy works at `127.0.0.1:8085`
+- Local SOCKS5 proxy works at `127.0.0.1:1080`
+- HTTPS websites open without certificate warnings
+- You can run route checks with `--scan` and stability-first checks with `--adaptive-scan`
 
-Choose whichever option works on your network.
+---
 
-**Option A: ZIP**
+## Prerequisites
 
-[Click to Download](https://github.com/masterking32/MasterHttpRelayVPN/archive/refs/heads/python_testing.zip)
+- Python `3.10+`
+- A Google account (for Apps Script relay)
+- Git (optional, ZIP download also works)
+- A browser where you can set manual proxy
 
+---
 
-**Option B: Git**
+## 1) Download The Project
+
+### Option A — ZIP
+
+Download and extract:
+
+- <https://github.com/masterking32/MasterHttpRelayVPN/archive/refs/heads/python_testing.zip>
+
+Then open terminal in extracted folder.
+
+### Option B — Git
 
 ```bash
 git clone https://github.com/masterking32/MasterHttpRelayVPN.git
 cd MasterHttpRelayVPN
 ```
 
-## 2. Deploy The Google Relay
+---
 
-The relay is the small Apps Script program that fetches websites for you.
+## 2) Deploy The Google Apps Script Relay
 
-1. Open [Google Apps Script](https://script.google.com/) and sign in.
+1. Open <https://script.google.com/> and sign in.
 2. Click **New project**.
-3. Delete the default editor content.
-4. Open [apps_script/Code.gs](../apps_script/Code.gs), copy everything, and paste it into Apps Script.
-5. Change this line to a long secret:
+3. Delete default code.
+4. Open local file [`apps_script/Code.gs`](../apps_script/Code.gs), copy all code, paste into Apps Script.
+5. Change:
 
    ```javascript
    const AUTH_KEY = "your-secret-password-here";
    ```
 
-6. Click **Deploy** -> **New deployment**.
+   to your own long random secret.
+
+6. Click **Deploy** → **New deployment**.
 7. Select **Web app**.
-8. Set **Execute as** to **Me**.
-9. Set **Who has access** to **Anyone**.
-10. Click **Deploy**, authorize the app, and copy the **Deployment ID**.
+8. Set **Execute as** = **Me**.
+9. Set **Who has access** = **Anyone**.
+10. Deploy, authorize, copy **Deployment ID**.
 
-Keep the `AUTH_KEY` and Deployment ID nearby. You need both locally.
+You now need **both** values locally:
+- `Deployment ID`
+- `AUTH_KEY`
 
-## 3. Run The One-Click Launcher
+---
 
-**Windows**
+## 3) Start The App (Recommended)
+
+### Windows
 
 ```cmd
 start.bat
 ```
 
-**Linux / macOS**
+### Linux / macOS
 
 ```bash
 chmod +x start.sh
 ./start.sh
 ```
 
-The launcher creates `.venv`, installs dependencies, runs `setup.py` if `config.json` is missing, and starts the proxy.
-
-If dependency installation fails through PyPI, the launcher retries through the runflare mirror automatically.
+What launcher does:
+- creates `.venv`
+- installs dependencies
+- runs setup wizard if `config.json` is missing
+- starts proxy
 
-## 4. Answer The Setup Wizard
+---
 
-When the wizard opens:
+## 4) Fill Setup Wizard Correctly
 
-1. Enter the same `auth_key` you placed inside [apps_script/Code.gs](../apps_script/Code.gs).
-2. Paste the Apps Script Deployment ID.
-3. Keep the default HTTP proxy port `8085` unless you already use that port.
-4. Keep LAN sharing off unless other devices must use this proxy.
+When prompted:
+1. `auth_key` = exactly same as `AUTH_KEY` in Apps Script
+2. `script_id` = your Deployment ID
+3. Keep HTTP port `8085` unless busy
+4. Keep LAN sharing disabled unless you need other devices
 
-The wizard writes `config.json` for you.
+The wizard creates `config.json`.
 
-## 5. Configure Your Browser
+---
 
-Use the HTTP proxy for normal browsing:
+## 5) Configure Browser Proxy
 
 | Field | Value |
-|-------|-------|
+|---|---|
 | Proxy type | HTTP |
 | Address | `127.0.0.1` |
 | Port | `8085` |
 
-Firefox path: **Settings** -> **General** -> **Network Settings** -> **Manual proxy**. Enter `127.0.0.1` and `8085`, then enable the option to also use it for HTTPS.
+For Firefox: Settings → General → Network Settings → Manual proxy.
+Enable proxy for HTTPS too.
 
-Chrome and Edge use the system proxy on Windows. You can also use extensions such as FoxyProxy or SwitchyOmega for easier switching.
+---
 
-## 6. Install The CA Certificate
+## 6) Install Local CA (HTTPS Required)
 
-HTTPS browsing needs the local CA certificate generated by the proxy. The file is created at `ca/ca.crt` after first run.
+The proxy generates `ca/ca.crt`.
+If auto-install fails, install manually.
 
-**The app tries to install it automatically. If it cannot, install it manually:**
+### Windows
+1. Open `ca/ca.crt`
+2. Install Certificate
+3. Current User
+4. Place in **Trusted Root Certification Authorities**
+5. Restart browser fully
 
-**Windows**
+### macOS
+1. Open `ca/ca.crt` in Keychain Access
+2. Open certificate → Trust
+3. Set **Always Trust**
+4. Restart browser
 
-1. Double-click `ca/ca.crt`.
-2. Choose **Install Certificate**.
-3. Choose **Current User**.
-4. Choose **Place all certificates in the following store**.
-5. Select **Trusted Root Certification Authorities**.
-6. Finish, then fully restart your browser.
-
-**macOS**
-
-1. Open `ca/ca.crt` in Keychain Access.
-2. Find the certificate and open it.
-3. Expand **Trust**.
-4. Set **When using this certificate** to **Always Trust**.
-5. Close the dialog, enter your password, and restart your browser.
-
-**Linux Ubuntu / Debian**
+### Ubuntu / Debian
 
 ```bash
 sudo cp ca/ca.crt /usr/local/share/ca-certificates/masterhttp-relay.crt
 sudo update-ca-certificates
 ```
 
-Restart your browser after installing.
+Restart browser.
+
+### Firefox (if needed)
+Firefox can use a separate trust store:
+- Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import `ca/ca.crt`
+- Enable trust for website identification
+
+---
+
+## 7) Verify It Works
+
+- Open normal websites through browser proxy.
+- If `unauthorized` appears: `AUTH_KEY` mismatch between Apps Script and `config.json`.
+- If HTTPS certificate errors appear: CA not trusted correctly.
 
-**Firefox**
+---
 
-Firefox may use a separate certificate store:
+## 8) Route Quality Commands
 
-1. Open **Settings** -> **Privacy & Security** -> **Certificates** -> **View Certificates**.
-2. Go to **Authorities**.
-3. Click **Import** and select `ca/ca.crt`.
-4. Enable **Trust this CA to identify websites**.
+### Fast reachability scan
 
-## Manual Run Commands
+```bash
+python main.py --scan
+```
 
-Use these only if you are not using the launcher:
+Use suggested `google_ip` in `config.json`.
+
+### Stability-first adaptive scan (recommended for unstable networks)
 
 ```bash
+python main.py --adaptive-scan
+```
+
+This ranking is based on route stability metrics (not only minimum ping).
+
+---
+
+## 9) Manual Start (Without launcher)
+
+### Windows
+
+```cmd
 python -m venv .venv
 .venv\Scripts\python -m pip install -r requirements.txt
 .venv\Scripts\python setup.py
 .venv\Scripts\python main.py
 ```
 
-On Linux / macOS, replace `.venv\Scripts\python` with `.venv/bin/python`.
+### Linux / macOS
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements.txt
+.venv/bin/python setup.py
+.venv/bin/python main.py
+```
+
+---
+
+## 10) Common Problems (Short)
 
-## Done
+- `unauthorized`: auth key mismatch
+- proxy connects but sites fail: wrong Deployment ID or script deployment not public
+- HTTPS warnings: CA not installed/trusted
+- some services block Google egress: use Exit Node guide
 
-When everything is working, the terminal shows the HTTP proxy on `127.0.0.1:8085` and SOCKS5 on `127.0.0.1:1080`.
+---
 
-Next useful pages:
+## Next Docs
 
 - [Troubleshooting](TROUBLESHOOTING.md)
-- [Configuration Reference](CONFIGURATION.md)
-- [Exit Node Guide](exit-node/EXIT_NODE_DEPLOYMENT.md)
+- [Configuration](CONFIGURATION.md)
+- [Exit Node](exit-node/EXIT_NODE_DEPLOYMENT.md)
+- [Architecture](ARCHITECTURE.md)