Improve the quality of the health check

The valve will check if its associated container and all its children
are available. Will return down if any is not available.

Author: rmaucher

java/org/apache/catalina/valves/HealthCheckValve.java

@@ -19,11 +19,14 @@
 import java.io.IOException;
 
 import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletResponse;
 
+import org.apache.catalina.Container;
 import org.apache.catalina.Context;
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.connector.Request;
 import org.apache.catalina.connector.Response;
+import org.apache.catalina.util.LifecycleBase;
 import org.apache.tomcat.util.buf.MessageBytes;
 
 
@@ -38,13 +41,24 @@ public class HealthCheckValve extends ValveBase {
             "  \"checks\": []\n" +
             "}";
 
+    private static final String DOWN =
+            "{\n" +
+            "  \"status\": \"DOWN\",\n" +
+            "  \"checks\": []\n" +
+            "}";
+
     private String path = "/health";
 
     /**
      * Will be set to true if the valve is associated with a context.
      */
     protected boolean context = false;
 
+    /**
+     * Check if all child containers are available.
+     */
+    protected boolean checkContainersAvailable = true;
+
     public HealthCheckValve() {
         super(true);
     }
@@ -57,6 +71,14 @@ public final void setPath(String path) {
         this.path = path;
     }
 
+    public boolean getCheckContainersAvailable() {
+        return this.checkContainersAvailable;
+    }
+
+    public void setCheckContainersAvailable(boolean checkContainersAvailable) {
+        this.checkContainersAvailable = checkContainersAvailable;
+    }
+
     @Override
     protected synchronized void startInternal() throws LifecycleException {
         super.startInternal();
@@ -74,9 +96,28 @@ public void invoke(Request request, Response response)
                 context ? request.getRequestPathMB() : request.getDecodedRequestURIMB();
         if (urlMB.equals(path)) {
             response.setContentType("application/json");
-            response.getOutputStream().print(UP);
+            if (isAvailable(getContainer())) {
+                response.getOutputStream().print(UP);
+            } else {
+                response.setStatus(HttpServletResponse.SC_SERVICE_UNAVAILABLE);
+                response.getOutputStream().print(DOWN);
+            }
         } else {
             getNext().invoke(request, response);
         }
     }
+
+    protected boolean isAvailable(Container container) {
+        for (Container child : container.findChildren()) {
+            if (!isAvailable(child)) {
+                return false;
+            }
+        }
+        if (container instanceof LifecycleBase) {
+            return ((LifecycleBase) container).getState().isAvailable();
+        } else {
+            return true;
+        }
+    }
+
 }

webapps/docs/changelog.xml

@@ -45,6 +45,14 @@
   issues do not "pop up" wrt. others).
 -->
 <section name="Tomcat 10.0.0-M9 (markt)" rtext="in development">
+  <subsection name="Catalina">
+    <changelog>
+      <update>
+        The health check valve will now check the state of its associated
+        containers to report availability. (remm)
+      </update>
+    </changelog>
+  </subsection>
 </section>
 <section name="Tomcat 10.0.0-M8 (markt)" rtext="release in progress">
   <subsection name="Catalina">

webapps/docs/config/valve.xml

@@ -2236,10 +2236,7 @@
   <subsection name="Introduction">
 
     <p>The <strong>Health Check Valve</strong> responds to
-    cloud orchestrators health checks. Note that it checks
-    that a context is mapped (so that an application is deployed),
-    for example if you don't have a ROOT context but demo-1.0
-    you have to check for <code>/demo-1.0/health</code></p>
+    cloud orchestrators health checks.</p>
   </subsection>
 
   <subsection name="Attributes">
@@ -2255,10 +2252,18 @@
       </attribute>
 
       <attribute name="path" required="false">
-        <p>Path by the cloud orchestrators health check logic.
+        <p>Path by the cloud orchestrators health check logic. If the valve
+        is associated with a context, then this will be relative to the context
+        path. Otherwise, the valve will match the full URI.
         The default value is <strong>/health</strong>.</p>
       </attribute>
 
+      <attribute name="checkContainersAvailable" required="false">
+        <p>If <code>true</code> the valve will check if its associated
+        container and all its children are available.
+        The default value is <strong>true</strong>.</p>
+      </attribute>
+
     </attributes>
 
   </subsection>