# 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.