fix: hide HTTP scrape error details

[zeitlinger]

Summary

• return a generic HTTP 500 body instead of exposing exception details
• include a safe hint explaining how to enable better diagnostics
• avoid adding server-side logging by default
• let users explicitly opt into either detailed HTTP responses or server-side error reporting
• verify the secure default does not expose the exception type or message

This is the focused replacement for the #2283 portion of #2297.

Fixes #2283

Implementation plan

1. Make HttpErrorHandlingPolicy builder-based and pass the built policy through the HTTPServer builder to the exchange adapter. Response verbosity and error reporting remain orthogonal choices.
2. Make the default policy return a generic HTTP 500 response with a short hint to configure server-side error reporting for diagnostic details. The default must not add a new log entry for the scrape exception.
3. Let callers configure either axis independently:
   • attach a caller-supplied error reporter while keeping the generic response, so applications and Java agents can route diagnostics to an appropriate sink; and
   • enable an explicitly unsafe debug response mode that includes exception details in the HTTP body. Avoid “legacy” naming; the API and docs must make the disclosure risk clear.
4. Preserve the existing logging behavior for failures where the error response itself cannot be sent or response headers were already committed, because no useful client response remains possible in those paths.
5. Add focused tests for the secure default, diagnostic hint, independent verbosity/reporter configuration, reporter invocation and isolation, reporter failure handling, and the explicitly unsafe debug-response mode. Add user documentation for the available policies and their security tradeoffs, plus the repository’s release-please changelog entry linking to that documentation.

Alternatives considered

• Unconditional server-side logging: rejected because it replaces the response disclosure with a new operational regression: one stack trace per failed scrape, with possible log-ingestion cost and application-logging side effects for unshaded integrations.
• Keep the detailed response as the default: rejected because it does not remediate Security Report: Full Stack Trace Disclosure in HTTP Error Responses #2283 unless every user discovers and enables the secure mode.
• Generic response with no diagnostic guidance: rejected because it leaves operators with a silent, unexplained HTTP 500 and no discoverable path to better diagnostics.
• Hard-code rate limiting or deduplication in the adapter: deferred in favor of a reporter abstraction. Correct suppression requires bounded state, concurrency handling, distinct-failure classification, and suppressed-count reporting; callers or a later reusable reporter can implement that policy without coupling it to HTTP response handling.
• Ambient debug/verbosity configuration: rejected in favor of an explicit builder option on HttpErrorHandlingPolicy, so re-enabling unsafe debug responses is deliberate and carries a clear security warning.
• Network controls or authentication documentation alone: rejected as the primary fix. They remain useful defense in depth but should not substitute for a safe default response.

Validation

• mise run lint:fix
• mise run build
• ./mvnw test -pl prometheus-metrics-exporter-httpserver -Dcoverage.skip=true -Dcheckstyle.skip=true

Release note

Release Please will use this override for the generated changelog and GitHub release notes after a squash merge:

BEGIN_COMMIT_OVERRIDE
fix(httpserver): make scrape error responses secure and configurable

Scrape failures now return a generic HTTP 500 response by default. Applications can configure a server-side error reporter or explicitly enable an unsafe debug response containing exception details. See the HTTPServer scrape error handling documentation.
END_COMMIT_OVERRIDE

[github-actions]

⚠️ API changes detected — maintainer review required

This PR modifies the published API diff for the following module(s):

• prometheus-metrics-exporter-httpserver

Please review the changes in docs/apidiffs/current_vs_latest/ carefully before approving.

[zeitlinger]

Addressed all outstanding review feedback:

• Made the policy-taking MetricsHandler and HttpExchangeAdapter constructors public without changing existing defaults.
• Changed reporters to Consumer<? super Exception> and added explicit synchronous HttpErrorHandlingPolicy.julReporter() at JUL SEVERE.
• Run configured reporters after the response is written; configured reporters also receive post-response failures without unconditional JUL logging.
• Preserved transport-failure logging and documented the behavior and opt-in JUL reporter.
• Added constructor, ordering, post-response, JUL-level, and policy behavior tests; regenerated the HTTPServer API diff.

Validated with mise run lint:fix, mise run build, mise run api-diff, and the HTTPServer module test suite (26 tests).