proxy/.scratch/protocol-probe/spec.md

Protocol Probe

Decisions

1. Probe semantics. The Protocol Probe is a user-initiated handshake check against the Single proxy URL endpoint. It reports which proxy protocols the endpoint speaks (HTTP, SOCKS5, or both). It never forwards traffic through the proxy and never contacts anything beyond the endpoint itself.

2. Trigger. Ctrl+D starts a probe only when:

   • the Profile form is in Single mode, and
   • the active field is the Single proxy URL field. It does not run on the Name or Bypass fields, and it does not run when saving with Ctrl+S.

3. Bare host:port default. A typed endpoint without a scheme is treated as http:// for parsing and dialing, matching the curl convention used elsewhere in the app.

4. Mapping table. After detection, the Profile is updated as follows:

   • HTTP only: the Single proxy URL becomes http://<host:port>.
   • HTTP and SOCKS5: the form switches to advanced mode; HTTP and HTTPS become http://<host:port>, while ALL/SOCKS becomes socks5://<host:port>. This preserves both detected capabilities and creates a Profile representable by GNOME as well as HTTP-only Targets.
   • SOCKS5 only: the Single proxy URL becomes socks5h://<host:port>.
   • Unrecognized protocol: status message only; the field is left untouched.
   • Dial failure: status message only; the field is left untouched.

5. Userinfo preservation. The exact bytes of any typed user:pass@ userinfo are preserved, including special characters such as @ and spaces. Only the scheme is replaced.

6. Stale-result safety. A probe started on the form is tagged with a generation ID. If the user leaves the form (Esc or a successful Ctrl+S) before the probe completes, the result is ignored and cannot mutate the abandoned form or the profiles page status.

7. Failure UX. A failed or unrecognized probe shows a status message and leaves the typed field unchanged so the user can correct the input and still save the Profile.

8. Documentation. README and CONTEXT already describe the Protocol Probe, its privacy boundary, and the socks5h GNOME caveat.