Add connection failure listener

api/src/main/java/jakarta/servlet/ConnectionFailureDetails.java

@@ -0,0 +1,28 @@
+package jakarta.servlet;
+
+import java.io.IOException;
+import java.util.Optional;
+
+/**
+ * An interface that carries information about why a connection has failed.
+ *
+ * @since Servlet 6.0
+ */
+public interface ConnectionFailureDetails {
+
+    /**
+     * Returns an optional cause of the underlying failure. If the failure was caused by a protocol level mechanism rather
+     * than a failure then this may be missing.
+     *
+     * @return The cause of the failure
+     */
+    Optional<IOException> cause();
+
+    /**
+     * If this is {@code true} the stream was explicitly reset by the remote endpoint, if this is false then there has been
+     * a connection level failure rather than the client simply closing this stream.
+     *
+     * @return {@code true} if the stream was explicitly reset by the remote endpoint
+     */
+    boolean isStreamReset();
+}

api/src/main/java/jakarta/servlet/ConnectionFailureListener.java

@@ -0,0 +1,22 @@
+package jakarta.servlet;
+
+import java.util.EventListener;
+
+/**
+ * A listener that allows an application to be notified of a problem with the underlying connection.
+ *
+ * @since Servlet 6.0
+ */
+public interface ConnectionFailureListener extends EventListener {
+
+    /**
+     * This method is invoked on a best effort basis if the underlying connection has gone away.
+     *
+     * This method will generally be invoked from a different thread to any other threads currently running in the
+     * application, so any attempt to stop application processing as a result of this notification should be done in a
+     * thread safe manner.
+     *
+     * @param details Information about the failure
+     */
+    void onConnectionFailure(ConnectionFailureDetails details);
+}

api/src/main/java/jakarta/servlet/ServletRequest.java

@@ -609,4 +609,18 @@ public AsyncContext startAsync(ServletRequest servletRequest, ServletResponse se
      * @since Servlet 6.0
      */
     ServletConnection getServletConnection();
+
+    /**
+     * Adds a listener to be eagerly notified of any underlying connection failure. Delivery to this listener is on a best
+     * effort basis, depending on the implementation and the underlying protocol in use some containers may never be able to
+     * warn of underlying connection failure.
+     *
+     * This listener is intended to allow long running tasks to potentially be cancelled if the underlying connection has
+     * gone away. Failures will still be reported at the IO level if an attempt is made to read or write to the request or
+     * response, and if async IO is in use failures may also be delivered to these listeners.
+     *
+     * @since Servlet 6.0
+     * @param listener The listener to be notified.
+     */
+    void addConnectionFailureListener(ConnectionFailureListener listener);
 }

api/src/main/java/jakarta/servlet/ServletRequestWrapper.java

@@ -515,4 +515,20 @@ public String getProtocolRequestId() {
     public ServletConnection getServletConnection() {
         return request.getServletConnection();
     }
+
+    /**
+     * Adds a listener to be eagerly notified of any underlying connection failure. Delivery to this listener is on a best
+     * effort basis, depending on the implementation and the underlying protocol in use some containers may never be able to
+     * warn of underlying connection failure.
+     *
+     * This listener is intended to allow long running tasks to potentially be cancelled if the underlying connection has
+     * gone away. Failures will still be reported at the IO level if an attempt is made to read or write to the request or
+     * response, and if async IO is in use failures may also be delivered to these listeners.
+     *
+     * @param listener The listener to be notified.
+     */
+    @Override
+    public void addConnectionFailureListener(ConnectionFailureListener listener) {
+        request.addConnectionFailureListener(listener);
+    }
 }

api/src/test/java/jakarta/servlet/MockServletRequest.java

@@ -226,4 +226,9 @@ public String getProtocolRequestId() {
     public ServletConnection getServletConnection() {
         return null;
     }
+
+    @Override
+    public void addConnectionFailureListener(ConnectionFailureListener listener) {
+
+    }
 }