## :mag: Context [S05-A](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-a-cache-abstractions.md) defines one key grammar for every cache abstraction in the service: ```plaintext ar:<abstraction>:<name>:<id> ``` Four segments, none of which names a tenant. `<id>` is the per-entity identifier the consumer supplies, so a namespace only ever appears inside it, if at all, and never as something an operation can match on. This surfaced while amending S25 to back the IAM relationship cache with the provisioned key-value store (!2679, [#1279](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1279)). That cache's `<id>` is a SHA-256 digest of the request, so the principal, the namespace, and the object set are all folded into one opaque segment. Review raised it as a grammar question rather than a spec-local one, which is correct: the grammar binds every abstraction under it, so one consumer should not settle it. ## :thought_balloon: What an opaque keyspace costs 1. **No tenant boundary.** [ADR-001](https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/001_organizations_as_anchor_point.md) makes organizations "the isolation and sharding boundary", and "the intended sharding boundary for Cells". A keyspace where no key names its namespace offers nothing to shard on. 1. **No targetable invalidation.** Deleting the entries for one principal or one resource needs an index plus a multi-key `DEL`, which S05-A's own cross-slot rules put behind a `{…}` hash tag. For the relationship cache specifically, an external signal cannot reconstruct a key at all without the exact object set the original request passed — so the IAM-driven invalidation on grant or revoke that [#1279](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1279) records as GA scope has no key to delete. 1. **No namespace-scoped flush.** The only lever during a mass revocation today is disabling a cache fleet-wide. For the relationship cache that is `iam.cache_ttl: "0s"`, which takes every namespace's cache down to deal with one, and costs a config write plus a deploy because configuration is read once at startup. Of the three, the flush is the weakest driver on its own: the relationship cache TTL is capped at 60 seconds 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), so it bounds the exposure already, and per-entry invalidation supersedes a manual flush anyway. The first two are the reasons to settle the grammar. ## :bulb: Proposal to discuss Carry the namespace UUID in the key format. The namespace UUID is the correct partition key because it is already the DB and storage partition boundary — the organization is just a loose FK for the namespace. The shape, the segment's position, and its hash-tag treatment are the substance of this discussion rather than settled inputs — two starting points: ```plaintext ar:<namespace-uuid>:<abstraction>:<name>:<id> ar:<abstraction>:<name>:{<namespace-uuid>}:<id> ``` The second co-locates one namespace's keys on a single slot, which is what a multi-key namespace-scoped operation needs on a Redis Cluster; the first reads more naturally and leaves slot behavior to a later decision. S05-A's existing rule — do not hash-tag a single-key abstraction, because it adds no safety and concentrates unrelated keys on one slot — bears on the choice. ### :question: Open questions - **Enumeration.** A prefix `SCAN` has no cost until it runs but is O(keyspace) when it does, on a deployment shared with the job queues. A maintained per-namespace index set is cheap to flush but adds a second write to every fill, which for the relationship cache is every authorization decision. Preference is `SCAN`: the hot path should not pay for a capability used during incidents. - **Per-abstraction migration mode.** A key rename is not uniformly benign. For a cache it is a miss then a refill. For `internal/cache/counter` it is not: S13's failure streak and storage accounting's buffered deltas are durable state, so a flag-day rename zeroes them. Accounting has reconciliation's recompute as a backstop and S13 tolerates a reset, but a rename is effectively a mass crash for both, so the amendment should state dual-read or flag-day per abstraction rather than leave it to each implementer. - **Does every abstraction want the segment?** A counter keyed on a remote repository ID is as un-attributable as the relationship cache, but nothing has asked to scope it by namespace yet. A grammar that makes the segment mandatory and a grammar that permits it are different decisions. ## :arrows_counterclockwise: Change plan 1. Amend S05-A's key grammar (spec MR), including the enumeration and migration-mode answers above. 1. Update each AR-authored Redis abstraction onto the amended grammar. ### :straight_ruler: Scope boundary The grammar governs **AR-authored wrapper keys only**. asynq and River manage their own keyspaces on the `jobs` purpose, and those are library-owned — out of scope, and not something an AR grammar can reach. In scope today: | Abstraction | Current key | Note | | --- | --- | --- | | `internal/cache/counter` | `ar:counter:<name>:<id>` | Durable state; see the migration-mode question | | Storage accounting's cache-purpose keys | via the `cache` purpose client | Buffered deltas, reconciliation backstop | | S06 URL cache | on the `jobs` purpose today | Its move to the `cache` purpose is S06-owned and separate | | IAM relationship cache | `ar:iam_relationships:<decision\|verdict>_v1:<digest>` | Not yet implemented; ships under [#1279](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1279) | ## :footprints: Sequencing for the IAM relationship cache S25 keeps its current format, and the change to it lands as part of this grammar update rather than ahead of it. [#1279](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1279)'s non-goals already exclude changing the key's identity, and S25's key carries a version segment (`decision_v1`, `verdict_v1`), so adopting an amended grammar there is a version bump: old pods keep reading old keys through a rolling deploy and never see the new ones. ## :books: Related - [S05-A (cache-abstractions)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-a-cache-abstractions.md) — the grammar, its atomicity and cross-slot standards, and the degradation standard - [S05 (distributed-state)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-distributed-state.md) — per-purpose composition - [#1279](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1279) — the relationship cache move that surfaced this; its GA invalidation note depends on the outcome - [#223](https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/223) — S05-A delivery