## :mag: Context `internal/iam/caching.go`'s `CachingResolver` fronts every `ReadRelationships` call with a per-pod, in-process TTL cache (default 30s, capped at 60s by [ADR-021](https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/021_authorization.md)). It is a Go map behind an `RWMutex`, with expiry evaluated lazily on read, a `maxCacheEntries = 10_000` bound, a purge-then-clear-everything overflow fallback, and a `singleflight` group collapsing concurrent misses for one key. The cache exists to absorb the bursty traffic artifact clients produce — a Maven or sbt resolution fires many requests carrying the *same* principal, the same token, and the same operation, differing only in the file requested. Those should collapse onto one `iam-data-access` lookup. ## :warning: Why per-pod is the wrong shape for that goal 1. **The collapse rate is divided by the pod count.** A burst spread across `n` pods by the load balancer produces `n` misses, `n` RPCs to `iam-data-access`, and `n` copies of the same entry. The busier the burst, the more pods it touches, so the mechanism weakens exactly where it was meant to help. 1. **The staleness window is per pod, so enforcement is non-deterministic during it.** Each pod fills its own entry at its own instant, so within one window the same caller can be allowed on one pod and denied on the next request routed elsewhere. A single shared entry expires once for the whole fleet. This is the same window [handbook!21025](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/21025) re-specified and that [#1025](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1025) is measuring. 1. **We hand-rolled expiry and eviction that Redis gives us as one flag.** Lazy expiry on read, the capacity bound, the purge pass, the full-clear fallback and its WARN log, and the injectable clock in tests are all scaffolding around a missing `EX`. The full-clear path is itself an open scalability issue ([#527](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/527)), reachable by an authenticated caller sending enough distinct object ids in one window. ## :thought_balloon: On the "no network hop" objection The reason recorded for keeping this in memory is [ADR-021](https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/021_authorization.md)'s constraint, read as "no network hop during authorization". The ADR's actual constraint is narrower: **no callbacks to the GitLab instance during request processing**, and it says in the same bullet that it does not target the Artifact Registry's own dependencies. The authorization path already makes network calls today. `iam-data-access` is a separate service reached over gRPC through a headless service — unlike GLAZ, it is not a co-located sidecar. Adding a Redis `GET` on the same path is the same class of dependency as the ones already there, and it is one we already run, wire, and instrument. The wording invites the misreading twice over, and both should be fixed rather than argued per review: - ADR-021 exempts "the Artifact Registry's co-located dependencies" but then enumerates exactly two of them, so a reader takes the list as closed and everything else — Redis, PostgreSQL — as forbidden by omission. - [ADR-020](https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/020_authentication_flow.md) states the constraint as "never calls back to the GitLab instance, Rails, or any remote service while processing a request". Read literally, that already forbids the per-request `iam-data-access` call ADR-021 sanctions, so it contradicts shipped behavior. Neither is a decision this issue overturns; both are wordings that describe the rule less precisely than the rule is. A handbook amendment MR restating the constraint as reachability of the *GitLab instance*, with AR's own infrastructure dependencies out of scope, unblocks this and every future question of the same shape. ## :bulb: Proposal Replace the in-process map with a thin typed wrapper over the S05-A `cache`-purpose Redis client, following the `internal/cache/counter` pattern: a focused type that takes a client, owns its key namespace and error contract, and holds no connection lifecycle. The client already exists (`redisclient.NewCacheClient`, wired in `cmd/artifact-registry/wire_cache.go`); this is a new consumer of it, not new infrastructure. - `CachingResolver` keeps its `Resolver` decorator shape, so no caller and no wiring outside the composition root changes. - The existing `cacheKey` encoding becomes the Redis key suffix under an `ar:`-prefixed namespace, per S05-A key naming. - The TTL becomes the key's expiry. Capacity bounding, the purge pass, the full-clear fallback and its WARN log all delete. - `iam.cache_ttl` keeps its meaning, its 30s default, its 60s cap, and its `"0s"` disable. ## :question: Design decisions to settle - **Degradation posture.** Redis being unreachable must never fail an authorization decision: the wrapper surfaces the infrastructure error and the resolver falls through to a direct `iam-data-access` call. This degrades the cache, not the decision — needs to be stated explicitly and tested, and it is a change of failure mode worth naming in the spec. - **Value encoding.** How the relationship tuples are serialized into the value, and how a decode failure is treated (as a miss). - **Security review.** Role-assignment tuples move from process memory into shared Redis. Who else reaches that instance, and whether the value needs anything beyond the transport already configured, is an AppSec question this issue should answer before the MR opens. - **Keep `singleflight`?** It still collapses concurrent same-key misses *within* a pod ahead of the Redis round trip. Cheap to keep; the argument for dropping it is that the shared entry already removes most of the fan-out. - **Metrics.** `cacheEventsTotal` (`hit` / `miss` / `coalesced`, labelled by instance name) carries over; a `degraded` or `error` event is needed for the Redis-unreachable path. - **Redis as an authorization-path dependency.** Sizing, latency budget against the per-RPC `iam.timeout`, and whether the added hop needs its own alerting. ## :white_check_mark: Acceptance criteria 1. A handbook amendment MR has landed against ADR-020 and ADR-021 restating the no-callbacks constraint as scoped to the GitLab instance, with the Artifact Registry's own infrastructure dependencies explicitly out of scope. This lands before the S25 spec MR. 1. The relationship-response cache is instance-wide: two pods serving the same principal, objects, and kinds within one TTL produce one `iam-data-access` lookup, not two. 1. Entry lifetime is a Redis key expiry. No capacity bound, purge pass, or full-clear path remains in `internal/iam`. 1. A Redis outage degrades to direct `iam-data-access` calls with no authorization failures and no boot or readiness impact, covered by a test. 1. `iam.cache_ttl` behavior is unchanged: 30s default, 60s cap enforced at startup, `"0s"` disables. 1. The S25 spec's `Caching` section, the configuration reference, and the `config.example.yaml` comment no longer describe the cache as per-pod. 1. [#527](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/527) closes as resolved by this change rather than being implemented separately. ## :no_entry_sign: Non-goals - Changing the TTL default or the ADR-021 60-second cap. - Changing what is cached, or the key's identity (principal, target objects, kinds filter). - Anything about the verdict cache's own shape beyond it sharing this wrapper. ## :books: Related - [handbook!21025](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/21025) — ADR-021 amendment on the role-change window - [#527](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/527) — observability and partial eviction for the full-clear path, subsumed here - [#1025](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1025) — grant/revoke enforcement latency - [#1057](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1057) — flaky coalesce test in the current implementation - [S25 (iam-relationships-client)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S25-iam-relationships-client.md) `Caching` - [S05-A (cache-abstractions)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-a-cache-abstractions.md) — the `cache` client and wrapper standards