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.

Edited by Dmitry Gruzd