Draft: proxy: Add exported gRPC proxy package for Workhorse and Gitway
What does this MR do and why?
Exports Gitaly's transparent gRPC proxy and adds grant, policy, and director packages for Workhorse and Gitway. This keeps the readonly_repository policy with Gitaly and lets Phase 1 reuse the same core that Phase 2 will run in Gitway.
Related to gitlab-org/orbit/knowledge-graph#1252.
Review request
@gl-gitaly could I ask for a Gitaly maintainer review? @jcaigitlab and @vyaklushin are the context holders for the Phase 1 and Phase 2 plan. Thanks!
How was this tested?
TEST_PACKAGES='./proxy/...' make race-gomake lintmake verifyPGHOST=/var/run/postgresql PGPORT=5432 make test(11,085 tests passed, 19 skipped)
Agent context - package extraction and Workhorse follow-up
Package layout
proxy: the exported transparent gRPC forwarder, codec, peeker, destination, and stream director types.proxy/grant: the Rails JSON contract, including Gitaly coordinates, repository, profile, expiry, and limits. The Orbit fixture was moved with it.proxy/policy: profile interface, exact allowlist narrowing, target repository resolution, stable denial errors, and thereadonly_repositoryprofile.proxy/director: composes a host-providedGrantResolverandDialerinto the proxy's stream director. It drops inbound metadata and forwards only grant call metadata.
Reuse and provenance
The existing internal/grpc/proxy package was promoted to proxy instead of copied or wrapped. Praefect only changes its import paths, so its behavior and codec/peeker implementation stay unchanged. This leaves one codec and one peeker in the module. The original Apache-2.0 license and Michal Witkowski headers remain with that implementation; the Workhorse-specific copied attribution was not brought back into Gitaly.
Target repository extraction uses internal/grpc/protoregistry directly. MethodInfo now exposes client-streaming and annotation-count metadata, and maps the existing ambiguous-field result to a sentinel that policy can deny without string matching. Multiple populated target fields are always ambiguous; duplicate occurrences of the same wire field retain protobuf last-value semantics.
Policy invariants and error contract
The profile requires ACCESSOR operation type, REPOSITORY scope, no client streaming, no additional repository annotation, exactly one target repository annotation, the grant's storage and relative path, and empty quarantine directories. Unknown and administrative methods are denied before peeking. The grant allowlist can only narrow the profile. Policy denials retain PermissionDenied with the exact proxy: <reason> messages used by Workhorse and the Rust client.
The director resolves the grant, applies universal and descriptor checks, applies the exact allowlist, peeks and validates the first frame, then dials. No backend stream is created before authorization completes.
Deviation from the proposed sketch
The transparent package is the namespace root proxy, not proxy/proxy. Moving the existing implementation to the shorter public import path avoids a second implementation and avoids a wrapper that external consumers could not use to reach an internal package. The exported package still supports Praefect's existing secondary destinations; the new grant director always selects one destination.
Workhorse follow-up
Workhorse can delete its codec, peeker, proxy, target repository, invariant, profile, director, and grant-contract copies. WebSocket connection handling, the HTTP handler, preauthorization adapter, sessions, HTTP/2 drain tracking, config, and Workhorse metrics remain there.
Test coverage
Tests cover the Orbit allowlist registry walk, exact profile lookup, the Rails JSON fixture, ambiguous.proto, descriptor and populated-request ambiguity, duplicate wire-field behavior, every read-only invariant and denial shape, metadata stripping, no-dial-before-authorization, and a listener-to-proxy-to-in-process-Gitaly round trip. Gitaly's testhelper.Run provides the package goleak checks.