# ADS relay protocol v1 All requests use `Authorization: Bearer `. Agent and client roles have separate shared tokens. Tickets are opaque random 192-bit values and must not be logged. Public deployments use HTTPS/WSS with normal certificate verification; TLS ends at the relay. ## Endpoints | Endpoint | Role | Purpose | |---|---|---| | `GET /healthz` | Public | Liveness only | | `GET /v1/devices` | Client | JSON array of gateway IDs and busy flags | | `GET /v1/agent?device=ID` | Agent | Persistent gateway control WebSocket | | `GET /v1/lease?device=ID` | Client | Persistent exclusive ownership WebSocket | | `GET /v1/connect?device=ID&lease=TICKET` | Client | One binary data WebSocket per local TCP connection | | `GET /v1/data?device=ID&session=TICKET` | Agent | One binary WebSocket paired to a pending client stream | IDs contain 1–128 ASCII letters, digits, `.`, `_`, `-`. Device IDs cannot be replaced by another agent until the original connection ends. Duplicate agents / occupied leases return HTTP 409, missing devices return 404, bad roles return 401. Stream limit is 32 per device. ## Connection flow 1. Agent connects and receives `{"type":"registered","device":"home-phone"}`. 2. Client daemon acquires a lease and receives `{"type":"leased","lease":"..."}`. 3. Client daemon accepts a local TCP socket, opens `/v1/connect` with its lease. 4. Relay sends the agent `{"type":"open","session":"..."}`. 5. Agent connects to the phone's raw TCP adbd (directly, or through an existing ADB smart socket), then opens `/v1/data` with that session ticket. 6. Relay pairs the streams. Each session ticket can only be claimed once, by the current registered agent for the requested device. 7. Binary WebSocket messages carry consecutive raw TCP bytes. Message boundaries have no ADB meaning. Chunks are at most 64 KiB from Rust; all peers limit received messages to 128 KiB. Agent and lease control channels use server-initiated ping every 20 seconds with a 10-second timeout. Device data must attach within 15 seconds. Payload writes time out after 30 seconds; awaited bounded writes propagate backpressure. Disconnecting agent or lease cancels attached streams. A new agent registration or lease never inherits old sessions. The client connects the resulting local TCP endpoint with the local ADB Server. The phone therefore authenticates the local computer's ADB key, not just the gateway key. This is the distinction between a real local ADB transport and pointing an adb CLI at a remote ADB Server. ## Scope One relay process, one trusted administration domain. There is no database, per-user ACL, distributed broker or end-to-end encryption in v1. An agent-role token authorizes registering device aliases within that domain; provision it only to trusted gateway hosts. Gateways currently require a raw TCP adbd endpoint. Existing smart socket mode uses `host:transport:` then `tcp:` on the selected device. It does not transparently virtualize a USB-only device. TCP half-close is not carried across a WebSocket close. Reconnection creates fresh transports, not resumable application streams.