Launch

docs/XHTTP_PROTOCOL.md

@@ -0,0 +1,58 @@
+# XHTTP-SSH request contract
+
+## Public configuration names
+
+The app exposes these names:
+
+- **Server** — the XHTTP proxy address that receives the TCP connection.
+- **Port** — the XHTTP listener port.
+- **SNI** — the hostname sent in the TLS handshake for CDN/fronting routing.
+- **XHTTP Host** — the HTTP `Host` value used for CDN or reverse-proxy routing.
+- **XHTTP Path** — the base request path.
+- **User name / Password** — SSH authentication inside the XHTTP stream.
+
+The **Server is the XHTTP proxy**. There is no separate client-side SSH destination because the XHTTP session itself carries the raw SSH byte stream.
+
+XHTTP TLS uses a trust-all certificate manager and disables hostname verification, matching SocksRevive VOID. The configured SNI is still sent, but certificates are not validated.
+
+
+## Session creation and downlink
+
+For each SSH transport connection, the client generates a random hexadecimal session ID and opens one long-lived request:
+
+```text
+GET {basePath}/{sessionId}
+Host: {xhttpHost}
+Accept: */*
+```
+
+With TLS enabled, the URL host is the configured SNI. A custom DNS implementation pins that URL host to the configured Server, so the socket still connects to the XHTTP proxy address. The response body is consumed continuously as the server-to-client SSH stream.
+
+## Uplink
+
+Client-to-server SSH bytes use monotonically increasing POST sequence numbers:
+
+```text
+POST {basePath}/{sessionId}/0
+POST {basePath}/{sessionId}/1
+POST {basePath}/{sessionId}/2
+...
+Content-Type: application/octet-stream
+```
+
+Only one POST is in flight at a time. The client waits for a successful response before sending the next sequence, preserving order and preventing an unbounded reorder queue. Pending writes are coalesced up to 900 KiB per POST and use an 8 MiB bounded backpressure buffer.
+
+## Failure and reconnect
+
+A failed GET stream, failed or timed-out POST, SSH ping failure, or VPN-service loss closes the current XHTTP/SSH transport. For transient transport failures, the local SOCKS relay and Android TUN remain alive while the client creates a new XHTTP session and SSH connection.
+
+## Server expectations
+
+A compatible server must:
+
+1. map GET and POST requests by session ID;
+2. stream server-to-client bytes immediately in the GET response body;
+3. accept sequence-numbered POST bodies and append them in numeric order;
+4. return success only after a POST body has been accepted for delivery;
+5. close the session when either direction is unusable;
+6. avoid website-style request rate limits on this path, because the POST requests are VPN tunnel packets rather than API traffic.