Draft: feat(gitlab-client): add WebSocket-tunneled Gitaly proxy transport
What does this MR do and why?
Orbit can read a repository only by downloading a full archive over HTTP today. This MR adds the client half of the Workhorse Gitaly proxy to gitlab-client: a gRPC channel tunneled through one WebSocket per project session, rotated before the session expires and retried once when the proxy rejects a stale stream. Nothing calls it yet, so runtime behaviour is unchanged; the indexer caller is !2382.
Related Issues
Related to #1252
Server side: gitlab-org/gitlab!253414 (Workhorse core package), gitlab-org/gitlab!253431 (Workhorse route, sessions, director), gitlab-org/gitlab!253417 (Rails preauthorization).
Testing
cargo test -p gitlab-client: 42 passed (22 new), run against an in-process fake Workhorse with a real WebSocket upgrade and a real tonic server per connection, including a TLS path with a self-signed CA. Clippy, fmt, shear and deny are clean; CI: https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/pipelines/2817501391
Performance Analysis
No hot path is touched and nothing dials the channel yet. One WebSocket plus one HTTP/2 connection per project session; channel eviction and admission control belong to the webserver follow-up.
- This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context - layout, deviations from the design notes, dependencies
The wire contract is ADR 018, currently proposed in !2384 (merged).
Header names, proxy: status reason codes, handshake HTTP statuses and WebSocket close codes were checked against the Workhorse side in gitlab-org/gitlab!253431; the two ends agree on every point.
Layout (crates/gitlab-client/src/gitaly_proxy/)
websocket_io.rs:AsyncRead/AsyncWriteadapter over the WebSocket; one write is one binary message. Close 1000/1001 is EOF; any other close, a code-less close, or a socket ending without a close handshake is anio::Error, so a truncated gRPC stream surfaces asUnavailableinstead of a short but successful body. Shutdown sends an explicit close 1000 because tungstenite alone sends a code-less close, which the server logs as abnormal.dial.rs: builds the session URI (/api/v4/internal/gitaly_proxy/project/{id}/ws), signs a fresh JWT intoGitlab-Orbit-Api-Requestper dial, honoursresolve_hostlike the HTTP client, caps messages at 1 MiB, and validates the three 101 headers (profile equal toreadonly_repository, expiry in seconds, repository as base64url JSON). A refused 101 is closed with 1000 and reasonunsupported_profileormalformed_session. 401/403/404/429/503/502 map to typed errors. A TLS config seam exists for tests; production uses the platform verifier.channel.rs: tonic channel over a custom connector. The first handshake runs outside tonic so its typed error and the session are known before a channel exists. h2 keepalive 20 s / 10 s, while idle. Rotation atconnected_at + expires_in - max(expires_in / 10, 5 s). One slot per project with a single-flight dial; the RPC wrapper retries exactly once onUnauthenticated/Unavailablecarrying aproxy:prefix. Only the initial RPC result is classified; mid-stream classification is the caller's job (!2382).error.rs: typed error and prefix-then-code status classifier.client.rs: per-project channel accessor and retrying RPC wrapper; JWT signing is shared with the HTTP path.tests.rs: fake Workhorse (TCP listener, header-checking upgrade, one tonic server per accepted connection with a stubgitaly.BlobServicescripted per connection index). Covers framing, every handshake outcome, rotation while an older stream is still running, retry-once, and TLS (SNI/Host stays the configured domain whileresolve_hostredirects the TCP connect; a wrong-name certificate is rejected).
Not covered: the h2 keepalive timers.
Deviations from the design notes
- TLS roots come from
rustls-platform-verifier, built once per dialer, so the tunnel trusts what the reqwest client trusts. tokio-tungstenite'srustls-tls-native-rootsfeature stays enabled because the crate exposes no public rustls feature without roots;rustls-native-certsis already in the lockfile viaclickhouse. tokio-tungsteniteis pinned to 0.28 (crates.io latest is 0.30) to share thetungstenitealready in the lockfile viakube-client.- No
X-Request-Idon the handshake. The existing HTTP path does not send one either and the server derives a correlation id from the connection. Could I ask you to say whether propagating the labkit correlation id on both paths should land here or in a follow-up? - An expiry below the 5 s floor makes a channel single-use. The server clamps to at least 30 s, so this is only reachable in tests, and the rotation test relies on it.
Dependencies
Workspace: hyper-util (tokio), tokio-tungstenite 0.28 (rustls-tls-native-roots), rustls-platform-verifier 0.7. Crate dev-deps: tokio-stream, tonic-prost, rcgen, tokio-rustls.