Draft: feat(orbit-server): proxy web blob reads through Gitaly
What does this MR do and why?
Webserver content resolution currently sends every blob batch through a Rails internal endpoint. This MR adds an opt-in Workhorse Gitaly proxy path with bounded project-channel reuse, client-side admission control, and Rails fallback, while keeping rails_http as the default.
Related Issues
Related to #1252
Chained on !2382 and targeting its branch. Server-side dependencies are gitlab-org/gitlab!253414, gitlab-org/gitlab!253431, and gitlab-org/gitlab!253417.
Testing
cargo test -p orbit-server -p gitlab-client (328 passed), cargo test -p indexer --lib (506 passed), and support-crate tests (113 passed, 1 ignored). Workspace clippy with all targets/features, fmt, schema generation, metrics catalog, and cargo shear pass. Markdownlint and Vale pass; offline lychee is blocked by nine pre-existing missing local files outside this diff.
Performance Analysis
The default Rails path does not create a proxy cache. The opt-in path caps retained project channels at 32, active sessions at 64, global streams at 64, streams per channel at 16, and negative entries at 1024; saturated calls fail immediately or use Rails fallback instead of waiting.
- This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context: cache policy, admission semantics, fallback, and review decisions
- The cache is keyed only by project ID because Rails preauthorization and K1 sessions bind one repository per project. Refs remain
ListBlobsrequest payload and do not change session authorization. - A Moka cache retains 32 project channels by default and evicts on capacity, 60 seconds idle, rotation, or RPC/stream error. A lightweight service-owned maintenance task runs at half the idle interval so burst-then-idle traffic releases sockets and session permits without another request.
- The session ceiling remains 64 while retained entries cap at 32. It bounds retained entries plus capacity-evicted channels still held by active streams and transient concurrent cache admission; lowering it to 32 would prevent a new entry from being created before capacity eviction releases the old permit.
- A separate 30-second negative cache records a 404 preauthorization response and now has its own capacity of 1024. This covers flag-off, project-not-found, and policy-not-covered responses, which Workhorse intentionally collapses.
- Admission uses non-blocking permits: 64 active sessions, 64 global streams, and 16 streams per project channel by default. Global stream admission starts only after the project channel is ready, so cold handshakes do not consume stream capacity.
- The per-channel default is below Workhorse's default grant cap of 32. The K1 101 contract does not expose a Rails-narrowed stream cap, so K3 cannot dynamically mirror a narrower grant without a wire-contract change.
- Both Rails and proxy transports keep blobs completed before a stream/decode error, populate those cache entries, and mark the resolution outcome as an error. This restores the previous default-path behavior and gives proxy reads parity.
- A post-open proxy failure has a distinct error variant that is never fallback-eligible. It carries completed blobs to the resolver and evicts the channel. Pre-stream local admission, negative cache, 403/404/429/503 handshake, and policy failures remain eligible only in
workhorse_ws_with_fallback. - The transport metric records one outcome per logical call. Fallback uses
fallback_okorfallback_erroron the proxy attempt, which exposes a failed Rails fallback without adding a second logicalrails_httpcount and preserves K2's counting convention. - Gitaly passes the full revision vector to one
git rev-list --objectstraversal. An unresolvable revision fails the RPC rather than skipping one input; a tree revision expands to multiple blobs. Tests cover both. Orbit sends path-scoped<revision>:<file_path>entries and relies on graph file paths resolving to blobs. Positional pairing is unchanged from Rails; a directory path would violate that invariant and can misalign later results. ListBlobsrequests setbytes_limit = -1; zero requests metadata without content. Both transports retain the existing 1 MiB local blob guard, and proxy requests do not ask Gitaly for paths that the resolver does not consume.- K1 needed one minimal extension: conditional channel invalidation. Its test replaces C1 with C2, proves invalidating C1 leaves C2 current, then proves invalidating C2 forces C3.
- The fake Workhorse uses a real WebSocket upgrade and tonic server. Tests cover concurrent cold single-flight, rotation, timer-driven idle/capacity/error eviction, in-flight eviction, caller cancellation permit release, global/per-channel/session saturation, fallback, mid-stream partials, request content, and 404 cooldown/expiry.
- This MR does not add
FindChangedPathsproxying, Docker/GDK end-to-end coverage, h2 keepalive coverage, dynamic narrowed-grant admission, or mid-stream replay.