## :dart: Why Part of epic **[AR Ruby client (monolith/S02)](https://gitlab.com/groups/gitlab-org/-/work_items/22451)**. S02 is the platform foundation every AR-fronting GraphQL resolver (`monolith/S03`+) calls; it ships no GraphQL or UI of its own. This step stands up the shared client foundation so the two sibling endpoint steps can consume it, and proves that foundation end-to-end through the smallest endpoint. > **Re-scoped back to `ee/lib`.** The interim gem packaging (`ee/gems/gitlab-artifact_registry-client/`) was dropped after legal review concluded the client must ship under the EE license ([decision thread on gitlab-org/gitlab!246861](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/246861#note_3629413100)). The client ships as EE monolith code at `ee/lib/artifact_registry/` (namespace `ArtifactRegistry::`). The gem MRs ([gitlab-org/gitlab!246861](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/246861), [gitlab-org/gitlab!247309](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/247309), [gitlab-org/gitlab!247315](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/247315)) are closed, and the gem packaging spec/plan amendment ([artifact-registry!1043](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1043)) no longer applies. Extracting the client into an EE-licensed gem later is tracked in [#607692](https://gitlab.com/gitlab-org/gitlab/-/work_items/607692). ## :compass: What Stand up the foundation of `ArtifactRegistry::Client` at `ee/lib/artifact_registry/` (the HTTP client mapping one-to-one to the S17 hosted-repository CRUD surface), plus `repository`, the smallest endpoint, as its first consumer. - **Faraday connection** (memoized, credential-free): `:json` request + JSON response parser, `RETRY_OPTIONS` (`max: 1, interval: 0`, transport exceptions only, idempotent verbs, no status retry), `:net_http`, client-owned timeout options, `GitLab/<version>` user agent, `X-Request-Id` carrying the Labkit correlation ID when one is present. - **Credential seam**: `ArtifactRegistry::TokenExchange`, a stub collaborator whose `token_for(current_user, slug)` returns `nil` until the real token exchange lands, so the client raises `AuthorizationError` before issuing any request (fail closed). The real exchange later swaps in behind this seam without touching method contracts. - **Private `request` primitive**: acquires the credential per call through the token exchange and attaches it as `Authorization: Bearer`, parses the JSON body, maps status/transport outcome to a typed exception, parses the error envelope (`code`/`message`/`request_id`), and bounds error-body reporting (a `String` body truncated to 200 characters; bearer credentials redacted from exception messages). - **Typed exception hierarchy** (nested under `Client`): `Error` base carrying `status` and `request_id`, plus `AuthorizationError`, `UnavailableError`, and `ApiError` (adding `code`). - **Error tracking**: transport-level failures are reported through `Gitlab::ErrorTracking.log_exception` via the Faraday error callback (the client lives in the monolith, so it uses monolith facilities directly; no injected callback). - **Path-segment encoder**: private helper percent-encoding `slug`/`name` before interpolation (defense-in-depth against path traversal); blank arguments and bare `.`/`..` segments are rejected before any request. - **`ArtifactRegistry::Repository`** value object: Hash-backed PODO, unknown-field tolerant. - **`repository` detail method**: `GET` one repository, `200` -> `Repository`, `404` -> `nil`. - **Config stanza**: `Gitlab.config.artifact_registry.api_url` (`config/gitlab.yml.example` + `config/initializers/1_settings.rb`), defaulting to `http://localhost:8080` in development/test; `base_url:` remains overridable at construction. ### Files - `ee/lib/artifact_registry/client.rb`, `ee/lib/artifact_registry/repository.rb`, `ee/lib/artifact_registry/token_exchange.rb` (new) - `ee/spec/lib/artifact_registry/client_spec.rb`, `ee/spec/lib/artifact_registry/repository_spec.rb`, `ee/spec/lib/artifact_registry/token_exchange_spec.rb` (new) - `config/gitlab.yml.example`, `config/initializers/1_settings.rb`, `config/bounded_contexts.yml` (modify) ## :white_check_mark: Acceptance In the EE RSpec suite (`ee/spec/lib/artifact_registry/`), `repository` shows: `AuthorizationError` on `401`/`403`; `UnavailableError` on transport failure / `5xx` / `429`; `ApiError` (with envelope) on a non-`404` mapped error; `Repository` on `200`; `nil` on `404`. With the stub `TokenExchange` returning `nil`, the client raises `AuthorizationError` with **no HTTP request issued** (fail closed). Credential attached as `Authorization: Bearer`, never in returned objects, and redacted from exception messages. `X-Request-Id` present exactly when a correlation ID is available; envelope `request_id` preserved on every exception that carries one. `UnavailableError` paths are reported through `Gitlab::ErrorTracking.log_exception`. Idempotent `GET` retries once on transport failure; `5xx` does not retry. Path segments percent-encoded, with blank and bare-`.`/`..` segments rejected before any request. `Repository` exposes every documented field and ignores extra keys. Covers S02 acceptance criteria **2, 6, 8** (idempotent-`GET` retry), **9, 10** (fail-closed seam), **12, 13** (error tracking), and the status dispatch of **7**. ## :triangular_flag_on_post: Feature flag None. The client carries no flag; the code has no caller, so it is dark by absence of a consumer. Merges green on the default branch (unreferenced code). ## :link: Dependencies - **Blocks** Step 2 and Step 3 (both consume this foundation). - Implementation MR: [gitlab-org/gitlab!244245](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/244245) (reinstated after the gem MR [gitlab-org/gitlab!246861](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/246861) was closed). - Spec: https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/monolith/S02-ar-ruby-client.md - Plan (Step 1): https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/plans/monolith/2026-07-02-ar-ruby-client.md#step-1-client-foundation-and-repository-fetch - Future gem extraction: [#607692](https://gitlab.com/gitlab-org/gitlab/-/work_items/607692)