59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 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.
|