microprofile-health-35 Provide different types of health check

Introduce qualifiers
Undeprecate @health for custom health checks
Add end points

Signed-off-by: Antoine Sabot-Durand <antoine@sabot-durand.net>

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

@@ -27,8 +27,10 @@
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * Created by hbraun on 24.08.17.
- * @deprecated in version 1.1 of the spec.
+ *
+ * This qualifier is used to define a custom Health Check procedure
+ *
+ * @author hbraun
  */
 @Qualifier
 @Documented

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

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2017 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) 2017 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,12 +17,12 @@
 
 = Java API Usage
 
-The specification provides the following API for Liveness and Readiness
+The specification provides the following API to define health check procedures.
 
 
 == Common API check
 
-The main API to provide health check procedures (liveness or Readiness) on the application level is the `HealthCheck` interface:
+The main API to provide health check procedures (Readiness or liveness) on the application level is the `HealthCheck` interface:
 
 ```
 @FunctionalInterface
@@ -34,7 +34,41 @@ 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 kind of Health Checks
+
+This specification provides different kind of Health check procedures.
+Difference between the 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
+* Custom checks defined with `@Health` annotation
+
+
+An `HealthCheck` procedures with none of the above annotations is not an active procedure and should be ignored.
+
+=== Readiness check
+
+An Health Check for readiness allows third party services to know if the application is ready to process request or not.
+
+The `@Readiness` annotation must be applied on an `HealthCheck` implementation to define a readiness check procedure.
+
+=== Liveness check
+
+An Health Check for liveness allows third party services to know if the application is alive and able to process request or not.
+
+The `@Liveness` annotation must be applied on an `HealthCheck` implementation to define a Liveness check procedure.
+
+
+=== Custom check
+
+To provide backward compatibility with previous specification version, an `HealthCheck` implementation with `@Health` annotation is still supported.
+
+Semantic of such an health check procedure is let to the implementor and therefor is defined as "custom".
+
+== 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.
 
@@ -55,22 +89,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.
 
-== Liveness check
 
-The `@Liveness` qualifier can be applied on an `HealthCheck` implementation to indicate that this bean is dedicated to Liveness check.
+== Combining multiple kind of check
 
-To provide backward compatibility with previous specification version, an `HealthCheck` implementation with `@Health` or no qualifier (i.e. `@Default` qualifier) is also considered as a liveness procedure.
+An `HealthCheck` implementation may be annotated with multiple kind of check.
+The procedure will be used to resolve every kind of health check for which it is annotated.
 
-//TODO: is support for default necessary (is it suppoirted in 1.0) ?
+For instance this procedure will be used to resolve liveness and readiness health check.
 
+----
+@Liveness
+@Readiness
+public class MyCheck implements HealthCheck {
 
-== Readiness check
+  public HealthCheckResponse call() {
+    ...
+  }
+}
+----
 
-The `@Readiness` qualifier must be applied on an `HealthCheck` implementation to indicate that this bean is dedicated to Liveness check.
 
-//TODO: support of both qualifier?
 
 == Constructing `HealthCheckResponse` 's
 
@@ -105,9 +145,8 @@ public class CheckDiskspace implements HealthCheck {
 
 = Integration with CDI
 
-Any enabled bean with a bean of type `org.eclipse.microprofile.health.HealthCheck` and liveness, readiness or 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
 
@@ -122,7 +161,8 @@ public class MyCheck implements HealthCheck {
 }
 ```
 
-As health check procedures are CDI bean they can also be defined with CDI producers:
+As health check procedures are CDI bean.
+Therefore, they can also be defined with CDI producers:
 
 
 ```
@@ -131,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

@@ -27,14 +27,14 @@ https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-read
 
 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 two `/health/ready` and `/health/live` endpoint in a MicroProfile runtime that respectively represents the readiness and the liveness of the entire runtime.
-For backward compatibility, a 3rd endpoint `/health` is also provided and provide the same information than `/health/live`.
-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.
+The MP-HC architecture consists of two `/health/ready` and `/health/live` endpoints in a MicroProfile runtime that respectively represents the readiness and the liveness of the entire runtime.
+For backward compatibility, a 3rd endpoint `/health` can also be used to provide a custom Health Check.
+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 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/live` endpoint is the logical AND of
-all of the procedure health status.
+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 procedure bound to it.
 
 The current version of the MP-HC specification does not define how the `/health/live` endpoint may be partitioned in the event
 that the MicroProfile runtime supports deployment of multiple applications. If an implementation wishes to

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,10 +156,21 @@ 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
+| /health/live
+| GET
+| 200, 500, 503
+| See Appendix B
+
+| /health/ready
+| GET
+| 200, 500, 503
+| See Appendix B
+
 | /health
 | GET
 | 200, 500, 503
@@ -177,35 +188,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 give valid health check responses for all kind 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