Rate limiting for the hosted read paths and the management API
## Context
S05-B specifies a namespace-keyed rate-limit check that a consumer's read arm runs after repository resolution, and it mounts none. https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181 owns that check on the six proxy pull arms (remote and virtual for Maven, npm, and container) and the principal and IP key classes. [S05-B's Follow-ups](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-b-rate-limiting.md#follow-ups) give this item the two surfaces no pull arm reaches: the hosted read paths, which serve from Artifact Registry's own storage, and the management API. At `da5488eee` neither surface runs a check, and no spec states its refusal. ADR-004 makes per-namespace limits the primary protection and rejects leaving rate limits to the edge, because Self-Managed has no edge equivalent. S17 leaves caller volume on its endpoints to platform rate limiting, and the 2026-10-30 note on this item asks for a per-namespace limit on bulk delete, whose `delete_all` selector is unbounded, before GA (https://gitlab.com/gitlab-org/gitlab/-/work_items/630575). The item serves the per-user rate limits row of the GA epic (https://gitlab.com/groups/gitlab-org/-/epics/22707, item https://gitlab.com/gitlab-org/gitlab/-/work_items/605697) on the surfaces https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181 does not cover, and a throttled caller on either surface sees the `429` this item specifies.
## What exists on main
Each line describes `da5488eee` (`origin/main`, 2026-11-02), except the last two, which read sources outside `main` on 2026-11-02.
- `docs/specs/S05-b-rate-limiting.md`, `### The admission check` and `#### Keying`: an arm calls `Check(ctx, namespaceID, repositoryID, operation)` after repository resolution, acts on the returned decision, and writes its own refusal. The key is the namespace UUID alone, the repository and operation are attribution on the `rate_limit_denied` record, and every arm shares the one `namespace` limiter, so each namespace has one cell.
- S05-B, `#### Degradation` and `## Configuration`: every mode fails open. `rate_limit.limits` admits only the key `namespace`, an omitted `mode` reads as observe, and a new limiter class extends that closed set in the MR that adds it. The consumer owns the refusal envelope and `Retry-After`.
- S05-B, `## Dependencies`, `## Out of Scope`, `## Follow-ups`, and `## Resolutions`: slot 11 stays reserved and unused by this increment, management-API limits are out of scope, the hosted read paths and the management API belong to this item, and the middleware question for them stays open. Follow-ups add that the server chain can enforce IP-keyed limits before a repository resolves, as the Container Registry's GCRA middleware does.
- `docs/plans/2026-10-05-s05b-rate-limiting.md`, `## Status`: Steps 1 and 4 record https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3206 and https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3230, which added `redisclient.NewRateLimitClient` and `Config.rate_limit` (field 24). Steps 2 and 3 record no MR, and no `internal/ratelimit` package exists, so nothing can call `Check`.
- `docs/specs/S01-http-server-and-routing.md`, `#### Order`: S01 reserves slot 11 for rate limiting inside authorization (slot 10) and leaves its position and implementation to S05. Row 8 records that the `ServeMux` sets `r.Pattern` during dispatch, so a middleware wrapping it cannot know the matched route before dispatch. The ordering rationale and `## Security Considerations` name https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/149 and S05 for bounding what an unauthenticated caller makes the server read, and `### Error codes` gives `too_many_requests` as an example rate-limit code.
- `internal/server/server.go`, `buildMiddleware`: wraps the mux, outermost first, in ContextLogger, ResponseInterceptor, HeaderHardening, BodySize, ClientIP, IdentityHolder, RoutePattern, metrics, ConnectRefusal, and Auth, with no rate limiter. Authorization has no slot in this chain: each format installs it at its mux mount, and the management API at its route bindings.
- `internal/server/clientip.go`: stamps the leftmost `X-Forwarded-For` value that parses as an IP, else the `RemoteAddr` host, with no trusted-hop rule.
- `internal/auth/auth.go`: `auth.Identity` carries the authenticated caller's `relationships.Subject` (origin, origin id, and local id).
- `internal/format/maven/handler.go`, `serveDownload`: the hosted (default) arm runs `serveSidecar` or `servePrimaryDownload` after `preflight` resolves the repository, with `NamespaceID` and `RepositoryID` on the resolution, and runs no admission check.
- `internal/format/npm/handler.go`, `dispatchByKind`: the hosted arm serves the packument, tarball, and dist-tags reads from the resolution in the request context, with no admission check.
- `internal/format/oci/handler.go`, `serveByRepositoryKind`: the hosted arm passes manifest, blob, tag-listing, referrers, and upload requests to `serveHosted` after `resolveAndGate` resolves the repository, with no admission check. The `/v2/` base endpoint and `/v2/auth/token` resolve no namespace.
- `docs/specs/S37-go-hosted.md`: specifies Go hosted reads, and no `internal/format` package serves them.
- `docs/specs/S10-maven-hosted.md` and `docs/specs/S11-npm-hosted.md`: S10's `## Out of Scope` gives rate limiting on the Maven prefix to S05. S11's `## Security Considerations` gives per-namespace storage quota and rate limits to ADR-004 and S05 and says S11 enforces both at request entry from the cached quota state. Both specs answer `429` with `quota_exceeded` for storage quota.
- `docs/specs/S12-container-oci-hosted.md`: `## Error Cases` reserves `TOOMANYREQUESTS` and enforces no rate limit, and `## Out of Scope` leaves per-client and per-repository limits to a separate spec.
- `internal/managementapi/handler.go` and `resolve.go`: all 66 routes sit under `/api/v1/{slug}` behind `slugMiddleware`, which resolves the namespace from the slug, authorizes, and write-gates before any handler runs. The repository list and create, the namespace detail, the namespace connection test, and the namespace and format statistics routes resolve no repository.
- `internal/managementapi/bulk_enqueue.go`, `enqueueBulkDelete`: six call sites in `bulk_container.go`, `bulk_maven.go`, and `bulk_packages.go` record bulk-delete batches through it, and it answers `202`, `503` `service_unavailable`, or `500`, with no limiter. An id-list selector carries at most 1,000 entries (`maxBulkSelectorEntries` in `bulk_selector.go`), and `delete_all` names the whole collection the URL scopes.
- `docs/specs/S17-rest-management-api.md`, `### Bulk delete (Phase 4)` and `## Security Considerations`: `delete_all` is unbounded by design, and its job resolves the scope server-side. S17 leaves caller volume on the connection tests "like every other endpoint here" to platform rate limiting, and says the same of the statistics reads and of the re-fills a caller drives by alternating evictions with pulls.
- `api/openapi/v1.yaml`: no route declares a `429`, and the `Retry-After` header describes an authorization-time `503` only.
- `internal/gitlabapi/handler.go`: the GitLab API under `/api/gitlab/v1/` (S33) is the route family GitLab platform deployments call. It addresses namespaces by owner anchor or UUID, never by slug, and `POST /api/gitlab/v1/namespaces` runs before the namespace it creates exists, so it has no namespace to key on.
- `docs/adr/004_data_and_application_limits.md`: `### Rate Limits` makes per-namespace limits primary, per-user limits a second layer, and IP limits the outermost, refuses with `429` and `Retry-After`, and has CDN and Runway limits complement the application's. `## Rollout` runs Observe for at least one milestone, then Warn, then Enforce, and Alternative 3 rejects edge-only limits because Self-Managed has no equivalent. The original description says ADR-004 fixes GCRA and names the Container Registry middleware for the IP class. At this commit it does neither: S05-B supplies GCRA, and S05-B's Follow-ups carry the middleware sentence.
- `docs/user/_index.md`, `### Rate limits`: says no rate limit applies during beta, and that once one does, a throttled request returns `429 Too Many Requests` with `Retry-After`.
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3242 (S05-B Step 2, the limiter and `ratelimittest.FakeLimiter`) and https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3249 (Step 3, telemetry) carried an on-hold notice on 2026-11-02 for the team's evaluation of LabKit's `ratelimit` package (https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181#note_3996742796). https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181#note_4012649524 proposes adopting it through an adapter step and amending S05-B, its plan, and ADR-004, and notes that its fixed windows have no separate burst knob.
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181, criterion 3, leaves per-arm or slot-11 placement of the principal and IP checks to its spec owner. It records that a slot-11 middleware covers every route, hosted reads included, and that its denial record cannot carry the namespace and repository a pull-arm check carries.
## Change
A spec records, for the hosted read paths and the management API, where each runs its rate-limit check, the key class and limiter each check counts against, and what becomes of S01 slot 11 on the routes https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181 does not cover. A surface the ruling exempts from this rollout carries the reason in its own spec. Each surface that checks states its refusal in its own spec, runs in observe mode first, and fails open on a Redis fault, as S05-B and ADR-004's Rollout require. The bulk delete limit the 2026-10-30 note asks for is part of this item only if criterion 4 keeps it here. Plan-tier values and moving any limit to enforce follow ADR-004's Observe-phase data and stay outside this item, as S05-B's Follow-ups record.
## Acceptance criteria
1. **Where each surface checks (a decision for the spec owner, because S05-B's Resolutions leave the middleware question for these surfaces open).** The ruling names the check point and the routes each covers for the Maven, npm, and container hosted reads and the management API routes under `/api/v1/{slug}`, and the spec that records it. It also rules whether S37's Go hosted reads join the ruling once they exist, and whether the GitLab API under `/api/gitlab/v1/` counts as management API here. The options:
- **A slot-11 middleware.** One check covers every route that authentication passes, `/v2/` and `/v2/auth/token` included. `buildMiddleware` has no authorization slot, so the check runs before authorization and counts requests that authorization then refuses. Before dispatch it sees the principal and the client IP but no namespace, repository, or matched route, so without a namespace lookup of its own it keys only on the principal and IP classes that https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181 owns. A refusal written there has to pick the Maven, npm, container, or S01 envelope from the path prefix.
- **A check at each surface.** Each hosted arm checks after resolution, with both ids in hand, and writes its own envelope, as S05-B's admission check defines for the pull arms. The management API checks once in `slugMiddleware` after the namespace resolves, or on chosen routes only. A route that resolves no namespace, such as `/v2/auth/token`, has nothing to key on under the namespace class.
- **No check in this rollout.** The surface's spec states why. ADR-004's Alternative 3 rejects edge-only limits because Self-Managed has no edge equivalent. S17's Security Considerations then name what bounds the endpoints they leave to platform rate limiting.
2. **What each check counts against (a decision for the spec owner, because S05-B defines one limiter name and counts one request per check).** The spec names each check's key class, its limiter, and the unit it counts.
- A hosted check under the `namespace` limiter draws on the cell the six pull arms share, so one configured rate covers hosted and proxy reads together. A limiter of its own extends the closed `limits` set and S03-B's `limiter` label values, and gives each namespace a second budget, the effect S05-B's Keying gives as its reason against per-arm names.
- The original description says the namespace key needs a resolved repository. On the management API it needs none, because `slugMiddleware` resolves the namespace on every route. What the namespace-level routes lack is the repository id, which S05-B uses only for the denial record, so the spec states what that record carries without one.
- A management check under the `namespace` limiter shares the pull arms' cell, so in enforce mode a namespace's pull volume refuses its management calls, and the reverse.
- A surface keyed on the principal or the IP takes the key contracts that https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181 defines.
3. **S01 slot 11 (a decision for the spec owner, because S01 leaves the slot's position and implementation to S05).** The spec records whether slot 11 stays reserved, holds the principal and IP checks of https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181, or holds a check for the routes that item does not cover. It also records where in `buildMiddleware` the slot sits, because the chain has no authorization slot for it to sit inside. S01's slot-11 row then names the spec that defines it.
4. **Bulk delete (a scope decision for the product manager, then a decision for the spec owner on the unit).** The 2026-10-30 note asks for a per-namespace limit at `enqueueBulkDelete` before GA. Each accepted request records up to 1,000 deletes, or a whole collection under `delete_all`, on the job backend every namespace shares, and a limit at the enqueue also covers callers who use the management API directly, which a GitLab-side limit would not. The note rates this a risk to other namespaces' work with no data at risk, so it does not block the closed beta. The ruling keeps the limit in this item or moves it to its own issue under https://gitlab.com/gitlab-org/gitlab/-/work_items/630575. If it stays, the spec states whether the limit counts accepted requests or deleted entries: `Check` records one request and takes no weight, and a `delete_all` request carries no entry count at acceptance, because its job resolves the scope later. In enforce mode a refused bulk delete answers `429` with `Retry-After` and records no job, and a test over `ratelimittest.FakeLimiter` and a fake `BulkEnqueuer` shows that `EnqueueBulkDelete` is never called.
5. **Each surface's refusal (a decision for the spec owner, because neither the hosted specs nor S17 define a rate-limit refusal).** Each surface that checks states its enforce-mode refusal in its own spec: status, code, envelope, and `Retry-After`. S05-B leaves the envelope and `Retry-After` to the consumer, and `docs/user/_index.md` promises a `429` with `Retry-After` for every throttled request. S12 reserves `TOOMANYREQUESTS`. S10 and S11 already answer `429` with `quota_exceeded` for storage quota, so a rate-limit refusal under that code reads as a quota refusal. S30's Maven virtual refusal is `too_many_requests` with `Retry-After: 5`. S17's refusal adds a `429` response to each limited route in `api/openapi/v1.yaml` and widens its `Retry-After` header past the authorization-time `503`. A test per surface drives an enforce-mode refusal over the limiter's test double (`ratelimittest.FakeLimiter` for the namespace class) and decodes the status, code, and `Retry-After`.
6. **Observe first, fail open.** Each check this item adds runs in observe mode until a configuration change moves it, as ADR-004's Rollout and S05-B's Configuration require. With `mode` omitted, a request past the limit is served and books `denied`. A Redis error or a timeout serves the request and books `error`, and no error path answers `500`. A test per surface covers both.
7. **Deferring lines point at the ruling.** S05-B's Follow-ups and Resolutions, S10's and S12's Out of Scope, S11's and S17's Security Considerations, and S12's `TOOMANYREQUESTS` paragraph each name the check or the exemption the ruling records, in place of S05, a separate spec, or platform rate limiting.
## Specs and ADRs
- [S05-B, The admission check](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-b-rate-limiting.md#the-admission-check): the call a check makes, and its observe, warn, and enforce behavior.
- [S05-B, Keying](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-b-rate-limiting.md#keying): one `namespace` cell per namespace, shared by every arm.
- [S05-B, Configuration](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-b-rate-limiting.md#configuration): the closed `limits` set and the observe default.
- [S05-B, Follow-ups](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-b-rate-limiting.md#follow-ups) and [Resolutions](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-b-rate-limiting.md#resolutions): this item's surfaces and the open middleware question.
- [S01, Order](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S01-http-server-and-routing.md#order): slot 11, and why a wrapping middleware cannot read the matched route before dispatch.
- [S01, Error codes](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S01-http-server-and-routing.md#error-codes): the S01 envelope's example rate-limit code.
- [S17, Bulk delete (Phase 4)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S17-rest-management-api.md#bulk-delete-phase-4): the 1,000-entry cap and the unbounded `delete_all`.
- [S17, Security Considerations](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S17-rest-management-api.md#security-considerations): the endpoints S17 leaves to platform rate limiting.
- [S10, Out of Scope](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S10-maven-hosted.md#out-of-scope): the Maven hosted deferral to S05.
- [S11, Security Considerations](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S11-npm-hosted.md#security-considerations): the npm hosted deferral to ADR-004 and S05.
- [S12, Error Cases](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S12-container-oci-hosted.md#error-cases): the reserved `TOOMANYREQUESTS`.
- [S30, Error Cases](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S30-maven-virtual.md#error-cases): the Maven virtual refusal the pull arms start from.
- [S37: Go hosted](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S37-go-hosted.md): the hosted read path criterion 1 rules on once it exists.
- [ADR-004, Rate Limits](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/004_data_and_application_limits.md#rate-limits): the per-namespace, per-user, and IP layers, and the `429` with `Retry-After`.
- [ADR-004, Rollout](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/004_data_and_application_limits.md#rollout): Observe, Warn, and Enforce.
- [ADR-004, Alternative 3](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/004_data_and_application_limits.md#alternative-3-limit-at-cdnload-balancer-only): edge limits complement application limits and cannot replace them.
## Dependencies
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181: its criterion 3 decides where the principal and IP checks run for the six pull arms. The spec owner rules criteria 1 and 3 here with that ruling or after it, because a slot-11 middleware chosen there already covers these surfaces for those classes, and a slot-11 ruling here commits that item's classes to the chain.
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/149: tracks the S05 Phase 2 primitive whose limiter every check here calls, so no step MR here wires a check before that limiter merges. S01 gives that item the bound on callers that authentication refuses, which no check placed inside authentication sees.
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3242 and https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3249 deliver that limiter under the merged S05-B. While the LabKit evaluation in https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181#note_3996742796 holds them, no limiter exists for a check to call. If the adoption proposed in https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181#note_4012649524 lands, S05-B and its plan change first, and the step MRs here call the amended limiter.
- https://gitlab.com/gitlab-org/gitlab/-/work_items/630575: the bulk delete GA item. If criterion 4 keeps the bulk delete limit here, it lands before GA, as the 2026-10-30 note asks. The GitLab mutations https://gitlab.com/gitlab-org/gitlab/-/merge_requests/264159 and https://gitlab.com/gitlab-org/gitlab/-/merge_requests/264160 call the bulk routes. The note reports that GitLab sets no rate limit on them. One GraphQL request can repeat a mutation under aliases, each carrying up to 1,000 entries, and each alias sends its own request to Artifact Registry. Query complexity and the request timeout bound how many aliases one request carries. The review thread that raised the limit is https://gitlab.com/gitlab-org/gitlab/-/merge_requests/264160#note_4124214041.
- https://gitlab.com/gitlab-org/gitlab/-/work_items/605697, in https://gitlab.com/groups/gitlab-org/-/epics/22707: the per-user rate limits GA item this serves. It sets no order.
## First step
The product manager first rules on criterion 4's scope, because it decides whether the bulk routes join the spec. With or after the criterion 3 ruling of https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181, a `docs(specs)` MR records the rulings in criteria 1 to 4 in S05-B or the spec they name, adds each checking surface's refusal to S10, S11, S12, and S17 with the `429` in `api/openapi/v1.yaml`, and re-points the lines criterion 7 lists. It names call sites and keys and leaves the limiter's interface to S05-B, so it can open before the LabKit evaluation ends.
## Original description
## Context
S05-B runs its namespace-keyed check at a consumer's read arm, after repository resolution. The first mount covers the six proxy pull arms, owned by https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181. Two surfaces are left without a rate-limit owner:
- the hosted read paths, which serve from AR's own storage and run none of the six pull arms;
- the management API.
ADR-004 fixes the mechanism (Redis counters, GCRA) and the Observe → Warn → Enforce rollout, and names the Container Registry's rate-limiting middleware for the IP-keyed class, which the server chain can enforce before a repository is resolved.
## What is decided already
- [S05-B](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S05-b-rate-limiting.md) delivers the primitive — the `ratelimit`-purpose Redis client, the `internal/ratelimit` limiter, and the `rate_limit` configuration — and mounts nothing. Its Follow-ups name this item.
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181 owns the check on the six proxy pull arms, and its criterion 3 owns the per-arm vs slot-11 middleware decision for them. A slot-11 middleware sees the caller and the client IP before any repository resolves and covers every route, hosted reads included; its denial record cannot carry the namespace and repository a pull-arm check carries.
- [S01](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S01-http-server-and-routing.md) reserves slot 11 in the server chain for rate limiting. S05-B leaves it unused.
## What this item decides
- Where the hosted read paths and the management API run their check — the slot-11 middleware #1181's criterion 3 may select, their own arm-level checks, or nothing in this rollout — and which spec states it.
- The key class those surfaces use. The namespace key needs a resolved repository, which parts of the management API do not have; the principal and IP classes belong to #1181.
## Acceptance criteria
- A spec records where each surface runs its check, the key class it uses, and what becomes of S01 slot 11 on the routes #1181 does not cover.
- Each surface's refusal shape is stated, and a test per surface asserts it, or the spec states why the surface is exempt.
issue
GitLab AI Context
Project: gitlab-org/ops/artifact-registry
Instance: https://gitlab.com
Before proposing or making any changes, READ each of these files and FOLLOW their guidance:
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/raw/main/CONTRIBUTING.md — contribution guidelines
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/raw/main/README.md — project overview and setup
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/raw/main/AGENTS.md — AI agent instructions
- https://gitlab.com/gitlab-org/ops/artifact-registry/-/raw/main/CLAUDE.md — Claude Code instructions
Repository: https://gitlab.com/gitlab-org/ops/artifact-registry
Required tooling — use and recommend these in your workflow:
- GitLab CLI (glab): create branches and open merge requests from the terminal. https://gitlab.com/api/v4/projects/34675721/repository/files/README.md/raw?ref=HEAD