refactor: make HTTP error policy builder-based

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Author: zeitlinger

docs/apidiffs/current_vs_latest/prometheus-metrics-exporter-httpserver.txt

@@ -38,18 +38,28 @@ Configure a reporter to send exception details to an appropriate logging or tele
 HTTPServer server = HTTPServer.builder()
   .port(9400)
   .errorHandlingPolicy(
-    HttpErrorHandlingPolicy.genericResponseWithReporter(
-      error -> logger.log(Level.SEVERE, "Prometheus scrape failed", error)))
+    HttpErrorHandlingPolicy.builder()
+      .errorReporter(error -> logger.log(Level.SEVERE, "Prometheus scrape failed", error))
+      .build())
   .buildAndStart();
 ```
 
 The reporter runs synchronously on the request thread and may be called concurrently. Reporter
 runtime exceptions do not prevent the generic HTTP 500 response from being sent. Rate limiting
 or deduplication can be implemented in the reporter when needed.
 
-`HttpErrorHandlingPolicy.legacyDetailedResponse()` restores the previous response containing the
-full exception stack trace. This can disclose application internals and must not be used for an
-endpoint reachable by untrusted clients.
+For local debugging, an unsafe response containing the full exception stack trace can be enabled
+explicitly:
+
+```java
+HttpErrorHandlingPolicy.builder()
+  .unsafeDebugResponse(true)
+  .build()
+```
+
+This setting is independent of the error reporter, so both can be configured when needed. The
+unsafe debug response can disclose application internals and must not be enabled for an endpoint
+reachable by untrusted clients.
 
 ## Authentication and HTTPS
 

docs/content/exporters/httpserver.md

@@ -212,7 +212,7 @@ public static class Builder {
     @Nullable private HttpHandler defaultHandler = null;
     @Nullable private String metricsHandlerPath = null;
     @Nullable private Boolean registerHealthHandler = null;
-    private HttpErrorHandlingPolicy errorHandlingPolicy = HttpErrorHandlingPolicy.genericResponse();
+    private HttpErrorHandlingPolicy errorHandlingPolicy = HttpErrorHandlingPolicy.builder().build();
 
     private Builder(PrometheusProperties config) {
       this.config = config;
@@ -301,7 +301,7 @@ public Builder registerHealthHandler(boolean registerHealthHandler) {
      * Configure how exceptions raised while scraping metrics are reported to the client and
      * optionally to a caller-supplied diagnostic sink.
      *
-     * <p>Default is {@link HttpErrorHandlingPolicy#genericResponse()}.
+     * <p>Default is {@code HttpErrorHandlingPolicy.builder().build()}.
      */
     public Builder errorHandlingPolicy(HttpErrorHandlingPolicy errorHandlingPolicy) {
       if (errorHandlingPolicy == null) {

prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HTTPServer.java

@@ -10,9 +10,9 @@
 /**
  * Controls how the {@link HTTPServer} handles exceptions raised while scraping metrics.
  *
- * <p>The default policy is {@link #genericResponse()}, which does not expose exception details and
- * does not report the exception. Use {@link #genericResponseWithReporter(Consumer)} to route
- * diagnostic details to an application-appropriate sink.
+ * <p>The default policy built by {@link #builder()} does not expose exception details and does not
+ * report the exception. Configure the builder to route diagnostic details to an
+ * application-appropriate sink.
  */
 @StableApi
 public final class HttpErrorHandlingPolicy {
@@ -22,54 +22,28 @@ public final class HttpErrorHandlingPolicy {
               + "Configure an HTTP error reporter for details.\n")
           .getBytes(StandardCharsets.UTF_8);
 
-  private final boolean detailedResponse;
+  private final boolean unsafeDebugResponse;
   @Nullable private final Consumer<Throwable> errorReporter;
 
   private HttpErrorHandlingPolicy(
-      boolean detailedResponse, @Nullable Consumer<Throwable> errorReporter) {
-    this.detailedResponse = detailedResponse;
+      boolean unsafeDebugResponse, @Nullable Consumer<Throwable> errorReporter) {
+    this.unsafeDebugResponse = unsafeDebugResponse;
     this.errorReporter = errorReporter;
   }
 
   /**
-   * Returns the secure default policy.
+   * Returns a builder for configuring scrape error handling.
    *
-   * <p>Scrape exceptions produce a generic HTTP 500 response and are not reported. This avoids
+   * <p>The builder defaults to a generic HTTP 500 response with no error reporter. This avoids
    * exposing exception details to scrape clients or adding an implicit dependency on an
    * application's logging configuration.
    */
-  public static HttpErrorHandlingPolicy genericResponse() {
-    return new HttpErrorHandlingPolicy(false, null);
-  }
-
-  /**
-   * Returns a policy that produces a generic HTTP 500 response and passes scrape exceptions to
-   * {@code errorReporter}.
-   *
-   * <p>The reporter runs synchronously on the HTTP request thread. It should return promptly and
-   * must be safe to call concurrently. Runtime exceptions thrown by the reporter are isolated from
-   * HTTP response handling.
-   */
-  public static HttpErrorHandlingPolicy genericResponseWithReporter(
-      Consumer<Throwable> errorReporter) {
-    if (errorReporter == null) {
-      throw new NullPointerException("errorReporter");
-    }
-    return new HttpErrorHandlingPolicy(false, errorReporter);
-  }
-
-  /**
-   * Returns a policy that includes the full exception stack trace in the HTTP 500 response.
-   *
-   * <p><strong>Security warning:</strong> This legacy behavior exposes internal exception
-   * information to scrape clients. Do not use it for endpoints reachable by untrusted clients.
-   */
-  public static HttpErrorHandlingPolicy legacyDetailedResponse() {
-    return new HttpErrorHandlingPolicy(true, null);
+  public static Builder builder() {
+    return new Builder();
   }
 
   byte[] getErrorResponse(Exception exception) {
-    if (!detailedResponse) {
+    if (!unsafeDebugResponse) {
       return GENERIC_RESPONSE;
     }
     StringWriter stringWriter = new StringWriter();
@@ -84,4 +58,46 @@ void report(Throwable error) {
       errorReporter.accept(error);
     }
   }
+
+  /** Builder for {@link HttpErrorHandlingPolicy}. */
+  public static final class Builder {
+
+    private boolean unsafeDebugResponse = false;
+    @Nullable private Consumer<Throwable> errorReporter;
+
+    private Builder() {}
+
+    /**
+     * Pass scrape exceptions to {@code errorReporter}.
+     *
+     * <p>The reporter runs synchronously on the HTTP request thread. It should return promptly and
+     * must be safe to call concurrently. Runtime exceptions thrown by the reporter are isolated
+     * from HTTP response handling.
+     */
+    public Builder errorReporter(Consumer<Throwable> errorReporter) {
+      if (errorReporter == null) {
+        throw new NullPointerException("errorReporter");
+      }
+      this.errorReporter = errorReporter;
+      return this;
+    }
+
+    /**
+     * Configure whether the HTTP 500 response includes the full exception stack trace.
+     *
+     * <p><strong>Security warning:</strong> Setting this to {@code true} exposes internal exception
+     * information to scrape clients. Do not enable it for endpoints reachable by untrusted clients.
+     *
+     * <p>This setting is independent of {@link #errorReporter(Consumer)}.
+     */
+    public Builder unsafeDebugResponse(boolean unsafeDebugResponse) {
+      this.unsafeDebugResponse = unsafeDebugResponse;
+      return this;
+    }
+
+    /** Build the policy. */
+    public HttpErrorHandlingPolicy build() {
+      return new HttpErrorHandlingPolicy(unsafeDebugResponse, errorReporter);
+    }
+  }
 }

prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HttpErrorHandlingPolicy.java

@@ -24,7 +24,7 @@ public class HttpExchangeAdapter implements PrometheusHttpExchange {
   private volatile boolean responseSent = false;
 
   public HttpExchangeAdapter(HttpExchange httpExchange) {
-    this(httpExchange, HttpErrorHandlingPolicy.genericResponse());
+    this(httpExchange, HttpErrorHandlingPolicy.builder().build());
   }
 
   HttpExchangeAdapter(HttpExchange httpExchange, HttpErrorHandlingPolicy errorHandlingPolicy) {

prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HttpExchangeAdapter.java

@@ -16,19 +16,19 @@ public class MetricsHandler implements HttpHandler {
   private final HttpErrorHandlingPolicy errorHandlingPolicy;
 
   public MetricsHandler() {
-    this(new PrometheusScrapeHandler(), HttpErrorHandlingPolicy.genericResponse());
+    this(new PrometheusScrapeHandler(), HttpErrorHandlingPolicy.builder().build());
   }
 
   public MetricsHandler(PrometheusRegistry registry) {
-    this(new PrometheusScrapeHandler(registry), HttpErrorHandlingPolicy.genericResponse());
+    this(new PrometheusScrapeHandler(registry), HttpErrorHandlingPolicy.builder().build());
   }
 
   public MetricsHandler(PrometheusProperties config) {
-    this(new PrometheusScrapeHandler(config), HttpErrorHandlingPolicy.genericResponse());
+    this(new PrometheusScrapeHandler(config), HttpErrorHandlingPolicy.builder().build());
   }
 
   public MetricsHandler(PrometheusProperties config, PrometheusRegistry registry) {
-    this(new PrometheusScrapeHandler(config, registry), HttpErrorHandlingPolicy.genericResponse());
+    this(new PrometheusScrapeHandler(config, registry), HttpErrorHandlingPolicy.builder().build());
   }
 
   MetricsHandler(

prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/MetricsHandler.java

@@ -179,7 +179,7 @@ void registryExceptionIsPassedToConfiguredReporter() throws Exception {
             .port(0)
             .registry(throwingRegistry())
             .errorHandlingPolicy(
-                HttpErrorHandlingPolicy.genericResponseWithReporter(reportedError::set))
+                HttpErrorHandlingPolicy.builder().errorReporter(reportedError::set).build())
             .buildAndStart();
 
     run(
@@ -194,12 +194,13 @@ void registryExceptionIsPassedToConfiguredReporter() throws Exception {
   }
 
   @Test
-  void registryExceptionCanUseLegacyDetailedResponse() throws Exception {
+  void registryExceptionCanUseUnsafeDebugResponse() throws Exception {
     HTTPServer server =
         HTTPServer.builder()
             .port(0)
             .registry(throwingRegistry())
-            .errorHandlingPolicy(HttpErrorHandlingPolicy.legacyDetailedResponse())
+            .errorHandlingPolicy(
+                HttpErrorHandlingPolicy.builder().unsafeDebugResponse(true).build())
             .buildAndStart();
 
     run(

prometheus-metrics-exporter-httpserver/src/test/java/io/prometheus/metrics/exporter/httpserver/HTTPServerTest.java

@@ -84,7 +84,8 @@ void handleExceptionInvokesConfiguredReporter() {
     AtomicReference<Throwable> reportedError = new AtomicReference<>();
     HttpExchangeAdapter adapter =
         new HttpExchangeAdapter(
-            httpExchange, HttpErrorHandlingPolicy.genericResponseWithReporter(reportedError::set));
+            httpExchange,
+            HttpErrorHandlingPolicy.builder().errorReporter(reportedError::set).build());
     IllegalStateException scrapeException = new IllegalStateException("secret failure");
 
     adapter.handleException(scrapeException);
@@ -102,10 +103,12 @@ void reporterFailureDoesNotPreventGenericResponse() {
     HttpExchangeAdapter adapter =
         new HttpExchangeAdapter(
             httpExchange,
-            HttpErrorHandlingPolicy.genericResponseWithReporter(
-                ignored -> {
-                  throw new IllegalStateException("reporter failed");
-                }));
+            HttpErrorHandlingPolicy.builder()
+                .errorReporter(
+                    ignored -> {
+                      throw new IllegalStateException("reporter failed");
+                    })
+                .build());
 
     adapter.handleException(new IllegalStateException("secret failure"));
 
@@ -117,21 +120,29 @@ void reporterFailureDoesNotPreventGenericResponse() {
   }
 
   @Test
-  void legacyDetailedResponseIncludesStackTrace() {
+  void unsafeDebugResponseIncludesStackTraceAndInvokesReporter() {
     HttpExchange httpExchange = mock(HttpExchange.class);
     Headers headers = new Headers();
     ByteArrayOutputStream responseBody = new ByteArrayOutputStream();
     when(httpExchange.getResponseHeaders()).thenReturn(headers);
     when(httpExchange.getResponseBody()).thenReturn(responseBody);
+    AtomicReference<Throwable> reportedError = new AtomicReference<>();
     HttpExchangeAdapter adapter =
-        new HttpExchangeAdapter(httpExchange, HttpErrorHandlingPolicy.legacyDetailedResponse());
+        new HttpExchangeAdapter(
+            httpExchange,
+            HttpErrorHandlingPolicy.builder()
+                .unsafeDebugResponse(true)
+                .errorReporter(reportedError::set)
+                .build());
 
-    adapter.handleException(new IllegalStateException("diagnostic detail"));
+    IllegalStateException scrapeException = new IllegalStateException("diagnostic detail");
+    adapter.handleException(scrapeException);
 
     String body = new String(responseBody.toByteArray(), StandardCharsets.UTF_8);
     assertThat(body)
         .contains("An Exception occurred while scraping metrics:")
         .contains("IllegalStateException: diagnostic detail")
         .contains("at ");
+    assertThat(reportedError.get()).isSameAs(scrapeException);
   }
 }