The Artifact Registry GraphQL resolvers each carry their own `Gitlab::Graphql::Limit::FieldCallCount` extension to bound how many outbound Artifact Registry (AR) HTTP requests a single GraphQL operation can trigger. In practice this does not work as intended: `FieldCallCount` keys per field, not per operation, so it does not bound the operation's total AR fan-out. This issue captures the architectural decision, surfaced during review of gitlab-org/gitlab!251068, of whether to move that budget to a single shared key at the `AcquiresClient` choke point. ## Background The single-artifact resolvers (`PackageResolver`, `ImageResolver`) use `FieldCallCount` with `limit: 1`, and the connection resolvers (`PackagesResolver`, `ImagesResolver`, and the upcoming `VersionsResolver` and `ManifestsResolver`) use `limit: 20`. The intent is to cap the number of AR reads one GraphQL operation can drive. The problem is that `FieldCallCount` maintains an independent counter per field. Each field gets its own budget, so the sum of per-field budgets is what actually bounds an operation, not any single operation-wide limit. There is no shared counter across the AR resolver family, so the extension cannot express "this operation may issue at most N AR requests total." ## Observations 1. Per-field keying means one operation can still drive many AR reads. Each field has its own independent budget, so a single query selecting `package`, `image`, `packages`, and `images` triggers four AR reads plus one repository read (five round trips), all within budget because each counter is separate. 2. It counts selections, not requests. The counter increments before the resolver's `resolve` body runs, so a format-mismatched selection that makes no AR call (for example, selecting the `image` field on a maven repository, which returns null without calling AR) still consumes its budget. So `limit: 1` means "one selection of this field," not "one AR request." 3. Reading N artifacts costs 2N AR round trips instead of 1+N. Because `limit: 1` forbids a second selection of the same field in one operation, a client reading N artifacts must send N separate GraphQL requests. The repository read is deduplicated only within a single request (via `Gitlab::SafeRequestStore.fetch` in `RepositoryResolver`), and `SafeRequestStore` does not span requests, so each of the N requests re-reads the repository. That is N repository reads plus N artifact reads = 2N round trips, versus 1 repository read plus N artifact reads = 1+N if the operation could batch them. Multiplexing does not help either, because `FieldCallCount` keys on `operation_fingerprint`, which hashes the query document and ignores variables. ## Proposed direction One option to evaluate: move the fan-out budget off the per-field `FieldCallCount` extensions and onto a single shared budget keyed at the `AcquiresClient` choke point, the concern every AR resolver goes through to obtain the client and issue a read. A single shared key would bound the whole operation's AR fan-out regardless of which fields are selected, and could count actual requests rather than selections. This is an architectural decision because it changes fan-out semantics for the entire AR resolver family, including the connection resolvers landing in later S14 steps (`versions`, `manifests`). Tradeoffs to consider: - Correctness of the bound: does a shared key at `AcquiresClient` actually cap the operation's total AR fan-out in all selection shapes, and how is the limit chosen across single-artifact and connection resolvers? - Requests vs selections: whether to count actual AR requests (incrementing when a read is issued) instead of selections, so no-op selections do not consume budget. - Impact on the later connection resolvers: how the shared budget interacts with `versions` and `manifests` resolvers before they land. - Interaction with repo-read dedup: whether a shared budget changes the `SafeRequestStore` repository-read deduplication story, which currently only spans a single request, and whether batching N artifacts into one operation would let a single repository read cover them. ## Out of scope for !251068 The immediate action in !251068 is only to correct the misleading code comment on the `FieldCallCount` extension so it describes what the extension actually does (bounds aliased re-selection of one field) rather than claiming it bounds the operation's AR cost. This issue tracks the larger decision. ## Acceptance criterion: bound fan-out per HTTP request, not per operation The GraphQL `_json` multiplex batch is capped only by total text size (`MAX_QUERY_SIZE`, about 10,000 chars), with no operation-count cap. Because `FieldCallCount` keys on `operation_fingerprint`, each near-duplicate operation in a batch gets a fresh 20-call budget. About 64 minimal distinct operations fit in one batch, each re-arming the budget, so a single authenticated HTTP request can drive on the order of 1,400 outbound AR reads. A shared budget keyed per operation (even at `AcquiresClient`) does not close this, since the multiplex gives each operation its own query and context. The bound must be per HTTP request: either a request-scoped counter shared across all `_json` entries (for example stored on the controller request rather than the query context), or a multiplex operation-count cap in `GraphqlController`. Acceptance criterion: the chosen mechanism must bound the total AR fan-out of a single HTTP request (including a multiplex `_json` batch), not just a single operation. ## Fan-out wall-clock duration The manifests connection issues up to 20 sequential per-row AR reads in one operation. The AR client `read_timeout` is 20 seconds (`Gitlab::HTTP` `DEFAULT_TIMEOUT_OPTIONS`), so a slow AR turns a full page into a multi-minute stall. This can exceed the 30 second GraphQL execution timeout and abort every row at once instead of degrading per row. Options to evaluate: a tighter dedicated read timeout for sub-collection reads, or bounding the fan-out wall-clock another way. Both points were surfaced in review of gitlab-org/gitlab!251073 by mkhalifa3. ## References - Follow-up from gitlab-org/gitlab!251068 review by @radbatnag