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 typestatustitle, and detail fields 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_errors feature flag
  • Only transforms 4xx/5xx responses (not 2xx like no_content!)
  • Extracts a clean detail from the legacy message string by stripping the "NNN StatusPhrase - " prefix
  • Sets Content-Type: application/problem+json and 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: MavenPackagesDependencyProxy::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
Edited by Tim Rizzi

Merge request reports

Loading