microprofile-health-35 Provide different types of health check

api/src/main/java/org/eclipse/microprofile/health/Liveness.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2019 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICES file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ */
+package org.eclipse.microprofile.health;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.inject.Qualifier;
+
+/**
+ *
+ * This qualifier is used to define a liveness Health Check procedure
+ *
+ * @author Antoine Sabot-Durand
+ * @since 2.0
+ */
+@Qualifier
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Liveness {
+}

api/src/main/java/org/eclipse/microprofile/health/Readiness.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2019 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICES file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ */
+package org.eclipse.microprofile.health;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import javax.inject.Qualifier;
+
+/**
+ *
+ * This qualifier is used to define a readiness Health Check procedure
+ *
+ * @author Antoine Sabot-Durand
+ * @since 2.0
+ */
+@Qualifier
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Readiness {
+}

spec/src/main/asciidoc/java-api.adoc

@@ -17,7 +17,12 @@
 
 = Java API Usage
 
-The main API to provide health check procedures on the application level is the `HealthCheck` interface:
+This specification provides the following API to define health check procedures.
+
+
+== Common API check
+
+The main API to provide health check procedures (readiness or liveness) on the application level is the `HealthCheck` interface:
 
 ```
 @FunctionalInterface
@@ -29,7 +34,42 @@ public interface HealthCheck {
 
 Applications provide health check procedures (implementation of a `HealthCheck`), which will be used by the runtime hosting the application to verify the healthiness of the computing node.
 
-There can be one or several `HealthCheck` exposed, they will all be invoked when an inbound protocol request is received (i.e. HTTP).
+== Different kinds of Health Checks
+
+This specification provides different kinds of health check procedures.
+Difference between them is only semantic.
+The nature of the procedure is defined by annotating the `HealthCheck` procedure with a specific annotation.
+
+* Readiness checks defined with `@Readiness` annotation
+* Liveness checks defined with `@Liveness` annotation
+* Backward compatible checks defined with `@Health` annotation
+
+
+A `HealthCheck` procedure with none of the above annotations is not an active procedure and should be ignored.
+
+=== Readiness check
+
+A Health Check for readiness allows third party services to know if the application is ready to process requests or not.
+
+The `@Readiness` annotation must be applied on a `HealthCheck` implementation to define a readiness check procedure, otherwise, this annotation is ignored.
+
+=== Liveness check
+
+A Health Check for liveness allows third party services to determine if the application is running.
+This means that if this procedure fails the application can be discarded (terminated, shutdown).
+
+The `@Liveness` annotation must be applied on a `HealthCheck` implementation to define a Liveness check procedure, otherwise, this annotation is ignored.
+
+
+=== Backward compatible check
+
+To provide backward compatibility with previous specification version, a `HealthCheck` implementation with `@Health` annotation is still supported.
+
+`@Health` annotation is deprecated, new procedures shouldn't use it.
+
+== Multiple HealthChecks procedures for a given kind
+
+There can be one or several `HealthCheck` exposed for a given kind, they will all be invoked when an inbound protocol request is received (i.e. HTTP).
 
 If more than one `HealthCheck` are invoked, they will be called in an unpredictable order.
 
@@ -50,7 +90,28 @@ public abstract class HealthCheckResponse {
 }
 ```
 
-The status of all `HealthCheck` 's determines the overall status.
+The status of all `HealthCheck` 's determines the overall status for the given Health check kind.
+
+
+== Combining multiple kinds of checks
+
+A `HealthCheck` implementation may be annotated with multiple kinds of checks.
+The procedure will be used to resolve every kind of health check for which it is annotated.
+
+For instance this procedure will be used to resolve liveness and readiness health check.
+
+----
+@Liveness
+@Readiness
+public class MyCheck implements HealthCheck {
+
+  public HealthCheckResponse call() {
+    ...
+  }
+}
+----
+
+
 
 == Constructing `HealthCheckResponse` 's
 
@@ -85,9 +146,8 @@ public class CheckDiskspace implements HealthCheck {
 
 = Integration with CDI
 
-Any enabled bean with a bean of type `org.eclipse.microprofile.health.HealthCheck` and default qualifier that can be used as health check procedure.
+Any enabled bean with a bean of type `org.eclipse.microprofile.health.HealthCheck` and `@Liveness`, `@Readiness` or `@Health` qualifier can be used as health check procedure.
 
-In addition, for backward compatibility with version 1.0 of the current specification, any enabled bean with a bean of type `org.eclipse.microprofile.health.HealthCheck` and `@Health` qualifier.
 
 Contextual references of health check procedures are invoked by runtime when the outermost protocol entry point (i.e. `http://HOST:PORT/health`) receives an inbound request
 
@@ -102,7 +162,7 @@ public class MyCheck implements HealthCheck {
 }
 ```
 
-As health check procedures are CDI bean they can also be defined with CDI producers:
+Health check procedures are CDI beans, therefore, they can also be defined with CDI producers:
 
 
 ```
@@ -111,12 +171,14 @@ class MyChecks {
 
   @Produces
   @ApplicationScoped
+  @Liveness
   HealthCheck check1() {
     return () -> HealthStatus.state(getMemUsage() < 0.9);
   }
 
   @Produces
   @ApplicationScoped
+  @Readiness
   HealthCheck check2() {
     return () -> HealthStatus.state(getCpuUsage() < 0.9);
   }

spec/src/main/asciidoc/overview.adoc

@@ -19,27 +19,30 @@
 
 == Rationale
 
-The Eclipse MicroProfile Health Check (MP-HC) specification defines a single container runtime mechanism for validating
+The Eclipse MicroProfile Health Check specification defines a single container runtime mechanism for validating
 the availability and status of a MicroProfile implementation. This is primarily intended as a machine to machine (M2M)
 mechanism for use in containerized environments like cloud providers. Example of
 existing specifications from those environments include https://docs.cloudfoundry.org/devguide/deploy-apps/healthchecks.html[Cloud Foundry Health Checks] and
 https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes[Kubernetes Liveness and Readiness Probes].
 
 In this scenario health checks are used to determine if a computing node needs to be discarded (terminated, shutdown) and eventually replaced by another (healthy) instance.
 
-The MP-HC architecture consists of a single `/health` endpoint in a MicroProfile runtime that represents the status of
-the entire runtime. This `/health` endpoint is expected to be associated with a configurable context, such as a web
-application deployment, that can be configured with settings such as port, virtual-host, security, etc.
-Further, the MP-HC defines the notion of a procedure that represents the health of a particular
-subcomponent of an application. There can be zero or more procedures in an application, and the
-overall health of the application as reflected via the `/health` endpoint is the logical AND of
-all of the procedure health status.
+The MicroProfile Health Check architecture consists of two `/health/ready` and `/health/live` endpoints in a MicroProfile runtime that respectively represent the readiness and the liveness of the entire runtime.
+These endpoints are linked to Health Check procedures defined with specifications API and annotated respectively with `@Liveness` and `@Readiness` annotations.
 
-The 1.0 version of the MP-HC specification does not define how the `/health` endpoint may be partitioned in the event
+For backward compatibility, a 3rd endpoint `/health` may also be used to provide a combination of previous endpoints and Health Check procedures annotated with the deprecated `@Health` annotation.
+
+These endpoints are expected to be associated with a configurable context, such as a web application deployment, that can be configured with settings such as port, virtual-host, security, etc.
+Further, the MicroProfile Health Check defines the notion of a procedure that represents the health of a particular subcomponent of an application.
+
+In an application, there can be zero or more procedures bound to a given health endpoint.
+The overall application health for a given endpoint is the logical AND of all of the procedures bound to it.
+
+The current version of the MicroProfile Health Check specification does not define how the defined endpoints may be partitioned in the event
 that the MicroProfile runtime supports deployment of multiple applications. If an implementation wishes to
-support multiple applications within a MicroProfile runtime, the semantics of the `/health` endpoint are
+support multiple applications within a MicroProfile runtime, the semantics of individual endpoints are
 expected to be the logical AND of all the application in the runtime. The exact details of this are deferred to
-a future version of the MP-HC specification.
+a future version of the MicroProfile Health Check specification.
 
 == Proposed solution
 

spec/src/main/asciidoc/protocol-wireformat.adoc

@@ -18,7 +18,7 @@
 =  Protocol and Wireformat
 
 == Abstract
-This document defines the protocol to be used by components that need to ensure a compatible wireformat, agreed upon semantics and possible forms of interactions between system components that need to determine the “liveliness” of computing nodes in a bigger system.
+This document defines the protocol to be used by components that need to ensure a compatible wireformat, agreed upon semantics and possible forms of interactions between system components that need to determine the “liveliness” or "readiness" of computing nodes in a bigger system.
 
 === Guidelines
 
@@ -59,7 +59,7 @@ Note that the force of these words is modified by the requirement level of the d
 | The service/application that is checked
 
 | Consumer
-| The probing end, usually a machine, that needs to verify the liveness of a Producer
+| The probing end, usually a machine, that needs to verify the liveness or readiness of a Producer
 
 | Health Check Procedure
 | The code executed to determine the liveliness of a Producer
@@ -156,13 +156,27 @@ Aspects regarding the secure access of health check information.
 * A producer MAY support security on all health check invocations (i.e. authentication)
 * A producer MUST NOT enforce security by default, it SHOULD be an opt-in feature (i.e. configuration change)
 
-== Appendix A: REST interface specifications
+== Appendix A: REST interfaces specifications
+
 
 |===
-| Context       | Verb          | Status Code  | Response
+| Context       | Verb          | Status Code  | Kind of procedure called |Response
+| /health/live
+| GET
+| 200, 500, 503
+| Liveness
+| See Appendix B
+
+| /health/ready
+| GET
+| 200, 500, 503
+| Readiness
+| See Appendix B
+
 | /health
 | GET
 | 200, 500, 503
+| Backward compatible + Liveness + Readiness
 | See Appendix B
 |===
 
@@ -177,35 +191,45 @@ Aspects regarding the secure access of health check information.
 
 === Response Codes and status mappings
 
-The following table give valid health check responses:
+The following table gives valid health check responses for all kinds of health checks:
 
 |===
 | Request | HTTP Status       | JSON Payload         | State  | Comment
-| /health
+| /health/live
+  /health/ready
+  /health
 | 200
 | Yes
 | UP
 | Check with payload. See <<With procedures installed into the runtime>>.
 
-| /health
+| /health/live
+  /health/ready
+  /health
 | 200
 | Yes
 | UP
 | Check with no procedures expected or installed. See <<With no procedures expected or installed into the runtime>>
 
-| /health
+| /health/live
+  /health/ready
+  /health
 | 503
 | Yes
 | Down
 | Check failed
 
-| /health
+| /health/live
+  /health/ready
+  /health
 | 503
 | Yes
 | Down
 | Check with procedures expected but not yet installed. See <<With procedures expected but not yet installed into the runtime>>
 
-| /health
+| /health/live
+  /health/ready
+  /health
 | 500
 | No
 | Undetermined