Implement Gitaly proxy in Workhorse
Background
The POC in #1226 (closed) showed that a generic Gitaly proxy in Workhorse is feasible: gRPC tunneled over a WebSocket (HTTP/1.1, since HTTP/2 doesn't reach Workhorse), tested end to end from the Rust tonic client through Workhorse and Praefect to Gitaly.
Proposal
We should implement it for real. The main change from the POC is the auth model: instead of a signed grant held by Orbit, Rails preauthorizes the WebSocket upgrade through Workhorse's existing PreAuthorizeHandler (the same path duo_workflows/ws uses) and returns the Gitaly coordinates plus a read-only policy that Workhorse binds to that one connection. No Gitaly address or token ever reaches the Orbit cluster. The surface is consumer-agnostic (/api/v4/internal/gitaly_proxy/project/:id/ws), Orbit is the first consumer.
The design is captured in ADR 018 (!2384 (merged), merged); the follow-up flag rename is !2401 (merged).
As agreed with Gitaly, the transport-agnostic core (forwarder, read-only policy, target repository resolution, grant contract, director) lives in an exported package in gitlab-org/gitaly, following the shape from #1252 (comment 3802419346). Workhorse imports it and only hosts the WebSocket route, preauth adapter and sessions (Phase 1). Gitway later reuses the same package and the Workhorse proxy layer is removed (Phase 2, tracked separately).
MRs, in dependency order. Everything stays Draft until the package shape is agreed in G1. W1/W2/W3 pin a Gitaly pseudo-version until the next release tag.
| Leg | Repo | Scope | MR |
|---|---|---|---|
| ADR | knowledge-graph | ADR 018: design, read-only policy, session lifetime, alternatives | ADR 018 + Quick follow-up |
| G1 | gitlab-org/gitaly |
exported proxy package: forwarder (reusing internal/grpc/proxy), read-only policy, target repo resolution, grant contract, director |
gitlab-org/gitaly!9243 (merged) |
| W1 | gitlab-org/gitlab (Workhorse) |
Workhorse-only pieces importing G1: WS net.Conn, config, metrics |
gitlab-org/gitlab!253414 |
| W2 | gitlab-org/gitlab (Workhorse) |
per-connection sessions and drain state machine, director, h2 tracking, config | gitlab-org/gitlab!253431 (chained on W1) |
| W3 | gitlab-org/gitlab (Workhorse) |
WebSocket route, preauth handler, graceful shutdown wiring | gitlab-org/gitlab!256922 (chained on W2) |
| R1 | gitlab-org/gitlab (Rails) |
API::Internal::GitalyProxy preauth endpoint, authorizer seam, Orbit authorizer |
gitlab-org/gitlab!253417 |
| K1 | knowledge-graph | WS-tunneled tonic transport in gitlab-client |
!2381 |
| K2 | knowledge-graph | indexer GetArchive over the proxy with Rails HTTP fallback |
!2382 (chained on K1) |
| K3 | knowledge-graph | webserver ListBlobs over the proxy, channel cache, admission control |
!2467 (chained on K2) |
Original MR table (before the Gitaly package split)
| Leg | Repo | Scope | MR |
|---|---|---|---|
| ADR | knowledge-graph | ADR 018: design, read-only policy, session lifetime, alternatives | ADR 018 + Quick follow-up |
| W1 | gitlab-org/gitlab (Workhorse) |
internal/gitalyproxy core: proxy port, WS net.Conn, target repo resolution, read-only invariants |
gitlab-org/gitlab!253414 |
| W2 | gitlab-org/gitlab (Workhorse) |
route, preauth type, director, per-connection sessions and drain state machine | gitlab-org/gitlab!253431 (chained on W1) |
| R1 | gitlab-org/gitlab (Rails) |
API::Internal::GitalyProxy preauth endpoint, authorizer seam, Orbit authorizer |
gitlab-org/gitlab!253417 |
| K1 | knowledge-graph | WS-tunneled tonic transport in gitlab-client |
!2381 |
| K2 | knowledge-graph | indexer GetArchive over the proxy with Rails HTTP fallback |
!2382 (chained on K1) |
| K3 | knowledge-graph | webserver ListBlobs over the proxy, channel cache, admission control |
Everything ships behind feature flags: workhorse_gitaly_proxy as the kill switch (rollout: gitlab-org/gitlab#627577 (closed)) and orbit_gitaly_proxy for the per-namespace rollout (gitlab-org/gitlab#627576). On the Orbit side the transport stays rails_http by default until K2 is rolled out.