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 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/AsyncWrite adapter 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 an io::Error, so a truncated gRPC stream surfaces as Unavailable instead 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 into Gitlab-Orbit-Api-Request per dial, honours resolve_host like the HTTP client, caps messages at 1 MiB, and validates the three 101 headers (profile equal to readonly_repository, expiry in seconds, repository as base64url JSON). A refused 101 is closed with 1000 and reason unsupported_profile or malformed_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 at connected_at + expires_in - max(expires_in / 10, 5 s). One slot per project with a single-flight dial; the RPC wrapper retries exactly once on Unauthenticated/Unavailable carrying a proxy: 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 stub gitaly.BlobService scripted 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 while resolve_host redirects 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's rustls-tls-native-roots feature stays enabled because the crate exposes no public rustls feature without roots; rustls-native-certs is already in the lockfile via clickhouse.
  • tokio-tungstenite is pinned to 0.28 (crates.io latest is 0.30) to share the tungstenite already in the lockfile via kube-client.
  • No X-Request-Id on 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.

Edited by Dmitry Gruzd

Merge request reports

Loading
Loading