Allow an exception handler to be bound to handle unexpected for the HTTP worker

Author: robotdan

build.savant

@@ -18,7 +18,7 @@ restifyVersion = "4.2.1"
 slf4jVersion = "2.0.17"
 testngVersion = "7.11.0"
 
-project(group: "io.fusionauth", name: "java-http", version: "1.1.1", licenses: ["ApacheV2_0"]) {
+project(group: "io.fusionauth", name: "java-http", version: "1.2.0", licenses: ["ApacheV2_0"]) {
   workflow {
     fetch {
       // Dependency resolution order:

pom.xml

@@ -2,7 +2,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>io.fusionauth</groupId>
   <artifactId>java-http</artifactId>
-  <version>1.1.1</version>
+  <version>1.2.0</version>
   <packaging>jar</packaging>
 
   <name>Java HTTP library (client and server)</name>
@@ -200,4 +200,4 @@
       </build>
     </profile>
   </profiles>
-</project>
+</project>

src/main/java/io/fusionauth/http/server/Configurable.java

@@ -331,6 +331,19 @@ default T withShutdownDuration(Duration duration) {
     return (T) this;
   }
 
+  /**
+   *
+   * Sets the unexpected exception handler that may occur while processing an HTTP request. This can be set to null which means the HTTP
+   * worker will use the default behavior.
+   *
+   * @param unexpectedExceptionHandler The unexpected exception handler.
+   * @return This.
+   */
+  default T withUnexpectedExceptionHandler(HTTPUnexpectedExceptionHandler unexpectedExceptionHandler) {
+    configuration().withUnexpectedExceptionHandler(unexpectedExceptionHandler);
+    return (T) this;
+  }
+
   /**
    * This configures the duration of the initial delay before calculating and enforcing the minimum write throughput. Defaults to 5
    * seconds.

src/main/java/io/fusionauth/http/server/HTTPServerConfiguration.java

@@ -79,6 +79,8 @@ public class HTTPServerConfiguration implements Configurable<HTTPServerConfigura
 
   private Duration shutdownDuration = Duration.ofSeconds(10);
 
+  private HTTPUnexpectedExceptionHandler unexpectedExceptionHandler;
+
   private Duration writeThroughputCalculationDelayDuration = Duration.ofSeconds(5);
 
   /**
@@ -110,6 +112,14 @@ public String getContextPath() {
     return contextPath;
   }
 
+  /**
+   * @return The HTTP unexpected exception handler for this server or null if a default was not set.
+   */
+  public HTTPUnexpectedExceptionHandler getDefaultExceptionHandler() {
+    return unexpectedExceptionHandler;
+  }
+
+
   /**
    * @return The expect validator. Cannot be null and is required.
    */
@@ -573,6 +583,15 @@ public HTTPServerConfiguration withShutdownDuration(Duration duration) {
     return this;
   }
 
+  /**
+   * {@inheritDoc}
+   */
+  @Override
+  public HTTPServerConfiguration withUnexpectedExceptionHandler(HTTPUnexpectedExceptionHandler unexpectedExceptionHandler) {
+    this.unexpectedExceptionHandler = unexpectedExceptionHandler;
+    return this;
+  }
+
   /**
    * {@inheritDoc}
    */

src/main/java/io/fusionauth/http/server/HTTPUnexpectedExceptionHandler.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025, FusionAuth, All Rights Reserved
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific
+ * language governing permissions and limitations under the License.
+ */
+package io.fusionauth.http.server;
+
+public interface HTTPUnexpectedExceptionHandler {
+  /**
+   *
+   * @param response the HTTP response, may be null.
+   * @param t        the unexpected exception to handle.
+   */
+  void handle(HTTPResponse response, Throwable t);
+}

src/main/java/io/fusionauth/http/server/internal/HTTPWorker.java

@@ -36,6 +36,7 @@
 import io.fusionauth.http.server.HTTPRequest;
 import io.fusionauth.http.server.HTTPResponse;
 import io.fusionauth.http.server.HTTPServerConfiguration;
+import io.fusionauth.http.server.HTTPUnexpectedExceptionHandler;
 import io.fusionauth.http.server.Instrumenter;
 import io.fusionauth.http.server.io.ConnectionClosedException;
 import io.fusionauth.http.server.io.HTTPInputStream;
@@ -267,9 +268,27 @@ public void run() {
       logger.debug(String.format("[%s] Closing socket with status [%d]. An IO exception was thrown during processing. These are pretty common.", Thread.currentThread().threadId(), Status.InternalServerError), e);
       closeSocketOnError(response, Status.InternalServerError);
     } catch (Throwable e) {
-      // Log the error and signal a failure
+      HTTPUnexpectedExceptionHandler unexpectedExceptionHandler = configuration.getDefaultExceptionHandler();
       var status = Status.InternalServerError;
-      logger.error(String.format("[%s] Closing socket with status [%d]. An HTTP worker threw an exception while processing a request.", Thread.currentThread().threadId(), status), e);
+      if (unexpectedExceptionHandler != null) {
+        if (response != null) {
+          // Set the initial status, allowing the handler to attempt to modify the status code.
+          response.setHeader(Headers.Connection, Connections.Close);
+          response.setStatus(status);
+        }
+
+        try {
+          unexpectedExceptionHandler.handle(response, e);
+        } catch (Throwable ignore) {
+        }
+
+        status = response != null ? response.getStatus() : status;
+      } else {
+        // Log the error
+        logger.error(String.format("[%s] Closing socket with status [%d]. An HTTP worker threw an exception while processing a request.", Thread.currentThread().threadId(), status), e);
+      }
+
+      // Signal an error
       closeSocketOnError(response, status);
     } finally {
       if (instrumenter != null) {