Discussion: Improving error messages from gem when using HTTP/2

[luisgcoding]

Background

I've opened PR #9270 to address a problem with error messaging when gem fetching fails, particularly when using HTTP/2. Before moving forward, I'd like to get community feedback on the best approach.

The Problem

When gem fetching fails (after executing a gem install <packageName> command) with HTTP errors, RubyGems currently displays the reasonPhrase field (e.g., "Forbidden", "Bad Request") from HTTP/1.1 responses. This works for HTTP/1.1, but there's a significant limitation: HTTP/2 removed the reasonPhrase field entirely (RFC 7540), meaning users only see numeric status codes like "403" without any descriptive text when using HTTP/2.

This is particularly problematic for external/private gem registries that want to provide helpful error messages to users (e.g., "This component was blocked due to security policy X" ).

Proposed Solutions

I'm presenting two approaches and would appreciate the community's input on which direction to pursue:

Option 1: Custom Header Approach (Currently in PR #9270)

Add support for a custom HTTP header X-Error-Message. When present, its value is displayed along with the status code.

Pros:

• Simple to implement for both client and server.
• Low overhead.
• Backwards compatible (falls back to current behavior if header is absent).
• Already used by other package managers Hugging Face CLI

Cons:

• Uses a custom header (not a standard).
• Limited structure for error information.

Option 2: RFC 9457 Problem Details

Implement support for RFC 9457 (Problem Details for HTTP APIs).

RubyGems would check if Content-Type: application/problem+json is present, parse the structured error response, and display it in a human-readable format.

Pros:

• Standards-based approach.
• Rich structured error information (type, title, detail, instance).
• Can include additional context.
• Already implemented by Maven

Cons:

• More complex implementation for both client and server.
• Requires parsing JSON error responses.
• Heavier for simple error cases.

Questions for the Community:

1. Which approach do you prefer? Simple header vs. standard RFC?
2. Are there other considerations I'm missing for gem server compatibility?

I'm happy to update the PR based on community feedback. Looking forward to hearing your thoughts!