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.
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
Supersedes !9242 (closed) (closed).
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 grant call metadata plus one optional validated correlation ID.
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. WithCorrelationIDProvider re-injects one per-stream correlation ID after enforcing the shared 128-character ASCII contract and replacing any grant value. The host enforces ExpiresIn and MaxConcurrentStreams because those limits apply to session state outside one stream.
Dial and peek causes remain unwrap-compatible for host logs, while their wire statuses use fixed proxy: gitaly_unavailable and proxy: peek_failed messages so internal transport details cannot reach the consumer.
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. This exposes Praefect's secondary destinations, finalizer, and error-handler surface. That compatibility trade-off keeps one unchanged forwarding implementation and a minimal Praefect diff; 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, correlation ID replacement and validation, transport-error redaction, no-dial-before-authorization for descriptor and request denials, and a listener-to-proxy-to-in-process-Gitaly round trip. Gitaly's testhelper.Run provides the package goleak checks.