## Summary Implement the Maven local (hosted) repository format end-to-end based on S10 - the full vertical slice: upload (release + SNAPSHOT), download, checksum sidecars, `maven-metadata.xml` generation + reconciliation, the RFC 9457 error envelope, and the conformance CI gate. ## Spec and plan - Spec: [`docs/specs/S10-maven-hosted.md`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/b02578f4077e064ca66cbf32239a4d86f406ddff/docs/specs/S10-maven-hosted.md) - Plan: [`docs/plans/2026-05-12-maven-hosted.md`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/ac8e56fb8636fb8785d1389b75212e0c1069f1e6/docs/plans/2026-05-12-maven-hosted.md) ## Scope Maven protocol surface: upload (release + SNAPSHOT), download, `maven-metadata.xml`, checksum sidecars, and file CRUD. Delivered as **12 implementation steps** (Steps 1-11, with Step 8 split into 8a/8b). Execution follows the dependency DAG below - **not numeric order**; each step's blockers are its direct predecessors. Step numbers are stable references for MR titles and review. **Out of scope:** virtual/remote Maven (S14), management REST CRUD, audit emission, retention/lifecycle (S19/S20), download analytics (S18), storage accounting (S22). Counter bumps (`downloads_count`, `artifacts_count`, `size_bytes`, `last_downloaded_at`) ship as TODO-marked no-op stubs pending S18/S20/S22. ## Dependency DAG ```mermaid graph TD S1["Step 1: MavenConfig"] S2["Step 2: Schema migration + jet codegen"] S3["Step 3: Path parsing + coordinate validation"] S4["Step 4: Datastore methods"] S5["Step 5: Handler skeleton + RFC 9457 + routing + pre-flight"] S6["Step 6: Download flow (GET primary + sidecar + HEAD)"] S7["Step 7: Upload flow - sidecars"] S8a["Step 8a: Upload primary pre-stream slice"] S8b["Step 8b: Upload primary stream + commit"] S9["Step 9: Metadata reconciler service"] S10["Step 10: Reconciler bg-job wrapping (gated on S27)"] S10b["Step 10b: Composition-root mount of slug-anchored formats"] S11["Step 11: Conformance CI job (gated on registry-conformance)"] S2 --> S4 S1 --> S5 S3 --> S5 S4 --> S5 S4 --> S6 S5 --> S6 S4 --> S8a S5 --> S8a S8a --> S8b S4 --> S9 S5 --> S9 S6 --> S7 S9 --> S10 S5 --> S10b S10b --> S11 S6 --> S11 S7 --> S11 S8b --> S11 ``` ## Status | Step | Description | MR | Status | Done | Assignee | Dependencies | |------|-------------|----|--------|------|----------|--------------| | 1 | MavenConfig (proto + Go validation): `MavenConfig` proto message + typed `Config` struct, defaults, startup validation (≤5 GB artifact, ≤10 MB metadata) | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/409 | ~"workflow::complete" | [x] | @mkhalifa3 | — | | 2 | Schema migration + jet codegen: four goose migrations (`maven_repositories`, `maven_packages`, `maven_versions`, `maven_files` with `sha512`), partial unique indexes, byte-column CHECKs, `blob_storage_blobs` FK omitted (OCI Step 1 pattern) | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/446 | ~"workflow::complete" | [x] | @mkhalifa3 | external: S06 Step 6 (FK target, soft) | | 3 | Path parsing + coordinate validation: pure-lexical `ParsePath`, segment rejection rules, coordinate regexes, classifier validation, fuzz target | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/457 | ~"workflow::complete" | [x] | @mkhalifa3 | — | | 4 | Datastore methods: Postgres `*store` on jet satisfying `DownloadStore` / `DigestStore` / `UploadStore` / `ReconcilerStore`; find-or-create, joined file lookups, version-cap count, TODO-marked counter stubs; `invariants_test.go` diagnostic #1 | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/564 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 2 | | 5 | Handler skeleton + RFC 9457 envelope + route registration + pre-flight slice: dispatcher, `namespace.Resolver` extension (`MavenRepositoryFinder`), `wire_maven.go`, path-traversal matrix (18 cases), 405-on-non-local; `invariants_test.go` diagnostic #2 (`http.Error` ban) | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/638 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 1, 3, 4; external: S06 Steps 1-2 | | 6 | Download flow (GET primary + sidecar synth + HEAD): `OpenBlob` stream/redirect, handler-owned Range/206/416, HEAD-bypasses-`OpenBlob`, `.md5` FIPS short-circuit, delivery-mode threading, counter-bump rules | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/706 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 4, 5; external: S06 Step 2 | | 7 | Upload flow - sidecars (Upload Step 4a + 4b): PUT `.sha1`/`.sha256`/`.sha512` validate vs parent digest; PUT `.md5` accept-and-discard 204; 256-byte cap; `Expect: 100-continue` drain | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/752 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 6 | | 8a | Upload primary pre-stream slice: PUT dispatch + read-deadline extend + `MaxBytesReader` install + find-or-create package/version + version-cap check; stream branch returns 501 | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/707 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 4, 5 | | 8b | Upload primary stream + commit (Upload Step 4c + 5): hash tee (SHA-1/512/MD5), `Session.Commit`, split-transaction `maven_files` + attachment insert, duplicate handling, concurrent harness, fixture generator | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/765 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 8a; external: S06 Steps 2-4, S06 Step 6 (soft) | | 9 | Metadata reconciler service: `MetadataReconciler.Reconcile` rewrites package-level `maven-metadata.xml`, `WithForceStream` read, DOCTYPE/billion-laughs defense, `FOR SHARE` repo invariant, sentinels (`ErrNoMetadata` / `ErrEmptyVersionSet` / `ErrInvalidMetadata`) | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/802 | ~"workflow::complete" | [x] | @sylviashen | Steps 4, 5; external: S06 Step 2, S06 Step 6 (soft) | | 10 | Reconciler background-job wrapping: `ReconcileArgs` + `jobsriver` worker, `EnqueueReconcile` for S20, `WithUnique(UniqueByArgs())` dedup, panic-recovery + drain | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/959 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 9; external: **S27 Phase 1** (Steps 4 + 7) | | 10b | Composition-root mount of slug-anchored formats: shared root dispatcher mounts npm + maven slug-anchored routes alongside OCI's `/v2/`, preserving reserved-prefix precedence over the slug wildcard | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/916 | ~"workflow::complete" | [x] | @sylviashen | Step 5; cross-format: npm mount seam, S01 composition root | | 11 | Maven conformance CI job: `conformance:maven` in `.gitlab-ci.yml`, mise task, setup script; runs `registry-conformance` Maven runner end-to-end | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/986 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 6, 7, 8b, 10b; external: **registry-conformance Maven runner**, S06 Steps 7-9 + 16/17 (real backend) | ## Cross-workstream dependencies (critical path) - **S06 (storage layer)** - `BlobStore` / `Session` interfaces + stub gate Steps 5, 6, 8b, 9. S06 Step 6 (`blob_storage_blobs` FK) gates the _enabled_ state of one `maven_files` FK (Step 2 ships it omitted, OCI Step 1 pattern). S06 Steps 7-9 + 16/17 (real backend) gate Step 11. - **S08 (auth)** - stub middleware fronts the handler; full auth deferred to S08/ADR-020. - **S27 (background jobs - `jobsriver` Phase 1)** - gates Step 10 (Phase 1 Steps 4 + 7). - **registry-conformance Maven runner** - gates Step 11. ## Related - Pre-launch DB review: [#106](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/106) - Threat-model follow-up (reconciler cooldown): [#84](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/84) - Buffered-counter centralization: [#91](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/91)