Add RFC 9457 Problem Details for Maven registry
What does this MR do and why?
Related to #595487
Feature flag rollout issue: #597477
Implements RFC 9457 — Problem Details for HTTP APIs for Maven package registry error responses.
Currently, all Maven endpoint errors return Content-Type: application/json with a body like {"message": "403 Forbidden - Package protected."}. Maven clients discard this body entirely — they only read the HTTP status code and reason phrase. On HTTP/2 connections, reason phrases don't exist, so users see only the numeric status code with no explanation of what went wrong.
When the maven_problem_details_errors feature flag is enabled, all 4xx/5xx responses from Maven endpoints return:
Content-Type: application/problem+json(exact value, no parameters — required by Maven Resolver's exact string comparison)- A JSON body with
type,status,title, anddetailfields per RFC 9457
Maven 3.9.11+ clients then display the structured error details:
[ERROR] Could not transfer artifact com.example:foo:pom:1.0 from/to gitlab (...):
RFC9457Payload {type=about:blank, status=403, title='Forbidden', detail='Package protected.'}
Backward compatibility
This change is fully backward-compatible. Older Maven clients (pre-3.9.11), Gradle 8.x, and sbt/Coursier all ignore the response body on errors — changing the body format and Content-Type has zero impact.
How does it work?
A new helper module API::Helpers::Packages::Maven::ProblemDetails overrides render_structured_api_error! — the single method all error helpers (forbidden!, not_found!, bad_request!, etc.) flow through.
The override:
- Checks the
maven_problem_details_errorsfeature flag - Only transforms 4xx/5xx responses (not 2xx like
no_content!) - Extracts a clean
detailfrom the legacy message string by stripping the"NNN StatusPhrase - "prefix - Sets
Content-Type: application/problem+jsonand constructs the RFC 9457 body - When the flag is disabled, calls
super— zero behavioral change
The module is included in all three Maven API classes: MavenPackages, DependencyProxy::Packages::Maven, and VirtualRegistries::Packages::Maven::Endpoints.
Feature flag
Name: maven_problem_details_errors (default disabled)
MR acceptance checklist
- Tests added for new functionality
- Feature flag created