diff --git a/README.adoc b/README.adoc index cb28d7b..627132e 100644 --- a/README.adoc +++ b/README.adoc @@ -17,9 +17,9 @@ // limitations under the License. // -# MicroProfile Health += MicroProfile Health -## Motivation +== Motivation Health checks are used to probe the state of a computing node from another machine (i.e. kubernetes service controller) with the primary target being cloud infrastructure environments where automated processes maintain the state of computing nodes. @@ -27,21 +27,21 @@ In this scenario, _health checks are used to determine if a computing node needs It’s not intended (although could be used) as a monitoring solution for human operators. -## Proposed solution +== Proposed solution The proposed solution breaks down into two parts: - A health check protocol and wireformat - A Java API to implement health check procedures -## Detailed design +== Detailed design -### Protocol +=== Protocol This project defines a protocol (wireformat, semantics and possible forms of interactions) between system components that need to determine the “liveliness” of computing nodes in a bigger architecture. A detailed description of the health check protocol can be found in the link:https://github.com/eclipse/microprofile-health/tree/master/spec/src/main/asciidoc/protocol-wireformat.adoc[companion document]. -### API Usage +=== API Usage The main API to provide health check procedures on the application level is the `HealthCheck` interface: @@ -71,7 +71,8 @@ public abstract class HealthCheckResponse { [...] } ``` -### Constructing `HealthCheckResponse`s + +=== Constructing `HealthCheckResponse`s Application level code is expected to use one of static methods on `HealthCheckResponse` to retrieve a `HealthCheckResponseBuilder` used to construct a response, i.e. : @@ -84,7 +85,7 @@ public class SuccessfulCheck implements HealthCheck { } ``` -### Integration with CDI +=== Integration with CDI Within CDI contexts, beans that implement `HealthCheck` and annotated with `@Health` are discovered automatically and are invoked by the framework or runtime when the outermost protocol entry point (i.e. `http://HOST:PORT/health`) receives an inbound request. @@ -99,18 +100,18 @@ public class CheckDiskSpace implements HealthCheck { } ``` -### On the wire +=== On the wire It's the responsibility of the runtime to gather all `HealthCheckResponse` s for `HealthCheck` s known to the runtime. This means an inbound HTTP request will lead to a series of invocations - on health check procedures and the runtime will provide a composite response, with a single overall outcome, i.e.: + on health check procedures and the runtime will provide a composite response, with a single overall status, i.e.: ``` { - "outcome": "UP", + "status": "UP", "checks": [ { "name": "first-check", - "state": "UP", + "status": "UP", "data": { "key": "foo", "foo": "bar" @@ -118,7 +119,7 @@ It's the responsibility of the runtime to gather all `HealthCheckResponse` s for }, { "name": "second-check", - "state": "UP" + "status": "UP" } ] } @@ -126,7 +127,7 @@ It's the responsibility of the runtime to gather all `HealthCheckResponse` s for The link:https://github.com/eclipse/microprofile-health/tree/master/spec/src/main/asciidoc/protocol-wireformat.adoc[companion document] contains further information on forms of interaction and the wireformat. -# SPI Usage += SPI Usage Implementors of the API are expected to supply implementations of `HealthCheckResponse` and `HealthCheckResponseBuilder` by providing a `HealthCheckResponseProvider` to their implementation. The `HealthCheckResponseProvider` is discovered using the default JDK service loader. diff --git a/sample-implementation/README.adoc b/sample-implementation/README.adoc index 1f9a515..ee9c28f 100644 --- a/sample-implementation/README.adoc +++ b/sample-implementation/README.adoc @@ -1,5 +1,5 @@ -# Health API Reference Implementation Notes += Health API Reference Implementation Notes The RI TCK coverage currently depends on custom Wildfly Swarm branch: @@ -12,7 +12,7 @@ Since this is not published to maven central, test execution is disabled by defa mvn -Dmaven.test.skip=false test ``` -## Building the Sample Implementation +== Building the Sample Implementation ``` @@ -21,7 +21,7 @@ cd health-sample mvn clean install ``` -## Running the TCK against the sample implementation +== Running the TCK against the sample implementation - Update the propoerty `wildfly-swarm.version` in `sample-implementation/pom.xml` to the version used in `health-sample/pom.xml` (i.e. 2017.9.0-SNAPSHOT) - Run the tests with `mvn -Dmaven.test.skip=false test` diff --git a/spec/src/main/asciidoc/java-api.adoc b/spec/src/main/asciidoc/java-api.adoc index 89ce194..95a7337 100644 --- a/spec/src/main/asciidoc/java-api.adoc +++ b/spec/src/main/asciidoc/java-api.adoc @@ -49,7 +49,7 @@ public abstract class HealthCheckResponse { } ``` -The status of all `HealthCheck` 's determines the overall outcome. +The status of all `HealthCheck` 's determines the overall status. == Constructing `HealthCheckResponse`s diff --git a/spec/src/main/asciidoc/protocol-wireformat.adoc b/spec/src/main/asciidoc/protocol-wireformat.adoc index d77e2d1..0086e8e 100644 --- a/spec/src/main/asciidoc/protocol-wireformat.adoc +++ b/spec/src/main/asciidoc/protocol-wireformat.adoc @@ -64,8 +64,8 @@ Note that the force of these words is modified by the requirement level of the d | Health Check Procedure | The code executed to determine the liveliness of a Producer -| Producer Outcome -| The overall outcome, determined by considering all health check procedure results +| Producer status +| The overall status, determined by considering all health check procedure results | Health check procedure result | The result of single check @@ -76,11 +76,11 @@ Note that the force of these words is modified by the requirement level of the d 1. Consumer invokes the health check of a Producer through any of the supported protocols 2. Producer enforces security constraints on the invocation (i.e authentication) 3. Producer executes a set of Health check procedures (could be a set with one element) -4. Producer determines the overall outcome (Producer outcome) -5. The outcome is mapped to outermost protocol (i.e. HTTP status codes) +4. Producer determines the overall status +5. The status is mapped to outermost protocol (i.e. HTTP status codes) 6. The payload is written to the response stream 7. The consumer reads the response -8. The consumer determines the overall outcome +8. The consumer determines the overall status === Protocol Specifics This section describes the specifics of the HTTP protocol usage. @@ -95,9 +95,10 @@ Health checks (innermost) can and should be mapped to the actual invocation prot * Producers MAY support a variety of protocols but the information items in the response payload MUST remain the same. * Producers SHOULD define a well known default context to perform checks -* Each response SHOULD integrate with the outermost protocol whenever it makes sense (i.e. using HTTP status codes to signal the overall state) +* Each response SHOULD integrate with the outermost protocol whenever it makes sense (i.e. using HTTP status codes to +signal the overall status) * Inner protocol information items MUST NOT be replaced by outer protocol information items, rather kept redundantly. -* The inner protocol response MUST be self-contained, that is carrying all information needed to reason about the producer outcome +* The inner protocol response MUST be self-contained, that is carrying all information needed to reason about the producer status === Mandatory and optional protocol types @@ -114,7 +115,7 @@ Each provider MUST provide the REST/HTTP interaction, but MAY provide other prot * The primary information MUST be boolean, it needs to be consumed by other machines. Anything between available/unavailable doesn’t make sense or would increase the complexity on the side of the consumer processing that information. * The response information MAY contain an additional information holder * Consumers MAY process the additional information holder or simply decide to ignore it -* The response information MUST contain the boolean state of each check +* The response information MUST contain the boolean `status` of each check * The response information MUST contain the name of each check === Wireformats @@ -123,21 +124,21 @@ Each provider MUST provide the REST/HTTP interaction, but MAY provide other prot * Producers MAY support an additional information holder with key/value pairs to provide further context (i.e. disk.free.space=120mb). * The JSON response payload MUST be compatible with the one described in Appendix B * The JSON response MUST contain the `name` entry specifying the name of the check, to support protocols that support external identifier (i.e. URI) -* The JSON response MUST contain the `state` entry specifying the state as String: “UP” or “DOWN” +* The JSON response MUST contain the `status` entry specifying the state as String: “UP” or “DOWN” * The JSON MAY support an additional information holder to carry key value pairs that provide additional context == Health Check Procedures * A producer MUST support custom, application level health check procedures * A producer SHOULD support reasonable out-of-the-box procedures -* A producer without health check procedures installed MUST returns positive overall outcome (i.e. HTTP 200) +* A producer without health check procedures installed MUST returns positive overall status (i.e. HTTP 200) -=== Policies to determine the overall outcome +=== Policies to determine the overall status -When multiple procedures are installed all procedures MUST be executed and the overall outcome needs to be determined. +When multiple procedures are installed all procedures MUST be executed and the overall status needs to be determined. -* Consumers MUST support a logical conjunction policy to determine the outcome -* Consumers MUST use the logical conjunction policy by default to determine the outcome -* Consumers MAY support custom policies to determine the outcome +* Consumers MUST support a logical conjunction policy to determine the status +* Consumers MUST use the logical conjunction policy by default to determine the status +* Consumers MAY support custom policies to determine the status == Security @@ -158,8 +159,8 @@ Aspects regarding the secure access of health check information. === Status Codes: -* 200 for a health check with a positive outcome -* 503 in case the overall outcome is negative +* 200 for a health check with a positive status (`UP`) +* 503 in case the overall status is negative (`DOWN`) * 500 in case the producer wasn’t able to process the health check request (i.e. error in procedure) @@ -203,7 +204,7 @@ The following table give valid health check responses: "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { - "outcome": { + "status": { "type": "string" }, "checks": { @@ -214,7 +215,7 @@ The following table give valid health check responses: "name": { "type": "string" }, - "state": { + "status": { "type": "string" }, "data": { @@ -231,13 +232,13 @@ The following table give valid health check responses: }, "required": [ "name", - "state" + "status" ] } } }, "required": [ - "outcome", + "status", "checks" ] } @@ -250,11 +251,11 @@ The following table give valid health check responses: Status 200 ``` { - "outcome": "UP", + "status": "UP", "checks": [ { "name": "myCheck", - "state": "UP", + "status": "UP", "data": { "key": "value", "foo": "bar" @@ -267,11 +268,11 @@ Status 200 Status 503 ``` { - "outcome": "DOWN", + "status": "DOWN", "checks": [ { "name": "firstCheck", - "state": "DOWN", + "status": "DOWN", "data": { "key": "value", "foo": "bar" @@ -279,7 +280,7 @@ Status 503 }, { "name": "secondCheck", - "state": "UP" + "status": "UP" } ] } @@ -291,7 +292,7 @@ Status `200` and the following payload: ``` { - "outcome": "UP", + "status": "UP", "checks": [] } ``` diff --git a/tck/pom.xml b/tck/pom.xml index 2fa961d..587a7de 100644 --- a/tck/pom.xml +++ b/tck/pom.xml @@ -23,7 +23,6 @@ ../ - org.eclipse.microprofile.health microprofile-health-tck MicroProfile Health TCK diff --git a/tck/src/main/java/org/eclipse/microprofile/health/tck/DelegateProcedureSuccessfulTest.java b/tck/src/main/java/org/eclipse/microprofile/health/tck/DelegateProcedureSuccessfulTest.java index ffa9ab9..0ce0897 100644 --- a/tck/src/main/java/org/eclipse/microprofile/health/tck/DelegateProcedureSuccessfulTest.java +++ b/tck/src/main/java/org/eclipse/microprofile/health/tck/DelegateProcedureSuccessfulTest.java @@ -76,16 +76,16 @@ public void testSuccessfulDelegateInvocation() throws Exception { ); Assert.assertEquals( - asJsonObject(checks.get(0)).getString("state"), + asJsonObject(checks.get(0)).getString("status"), "UP", "Expected a successful check result" ); // overall outcome Assert.assertEquals( - json.getString("outcome"), + json.getString("status"), "UP", - "Expected overall outcome to be successful" + "Expected overall status to be successful" ); } } diff --git a/tck/src/main/java/org/eclipse/microprofile/health/tck/HealthCheckResponseAttributesTest.java b/tck/src/main/java/org/eclipse/microprofile/health/tck/HealthCheckResponseAttributesTest.java index 7a09802..268897f 100644 --- a/tck/src/main/java/org/eclipse/microprofile/health/tck/HealthCheckResponseAttributesTest.java +++ b/tck/src/main/java/org/eclipse/microprofile/health/tck/HealthCheckResponseAttributesTest.java @@ -78,7 +78,7 @@ public void testSuccessResponsePayload() throws Exception { ); Assert.assertEquals( - asJsonObject(check).getString("state"), + asJsonObject(check).getString("status"), "UP", "Expected a successful check result" ); @@ -97,7 +97,7 @@ public void testSuccessResponsePayload() throws Exception { // overall outcome Assert.assertEquals( - json.getString("outcome"), + json.getString("status"), "UP", "Expected overall outcome to be successful" ); diff --git a/tck/src/main/java/org/eclipse/microprofile/health/tck/MultipleProceduresFailedTest.java b/tck/src/main/java/org/eclipse/microprofile/health/tck/MultipleProceduresFailedTest.java index 0a1f08a..23f00d5 100644 --- a/tck/src/main/java/org/eclipse/microprofile/health/tck/MultipleProceduresFailedTest.java +++ b/tck/src/main/java/org/eclipse/microprofile/health/tck/MultipleProceduresFailedTest.java @@ -86,9 +86,9 @@ public void testFailureResponsePayload() throws Exception { // overall outcome Assert.assertEquals( - json.getString("outcome"), + json.getString("status"), "DOWN", - "Expected overall outcome to be unsuccessful" + "Expected overall status to be unsuccessful" ); } @@ -101,7 +101,7 @@ private void verifyFailurePayload(JsonValue check) { ); Assert.assertEquals( - asJsonObject(check).getString("state"), + asJsonObject(check).getString("status"), "DOWN", "Expected a successful check result" ); @@ -116,7 +116,7 @@ private void verifySuccessPayload(JsonValue check) { ); Assert.assertEquals( - asJsonObject(check).getString("state"), + asJsonObject(check).getString("status"), "UP", "Expected a successful check result" ); diff --git a/tck/src/main/java/org/eclipse/microprofile/health/tck/NoProcedureSuccessfulTest.java b/tck/src/main/java/org/eclipse/microprofile/health/tck/NoProcedureSuccessfulTest.java index 1bcf7d8..966983d 100644 --- a/tck/src/main/java/org/eclipse/microprofile/health/tck/NoProcedureSuccessfulTest.java +++ b/tck/src/main/java/org/eclipse/microprofile/health/tck/NoProcedureSuccessfulTest.java @@ -58,9 +58,8 @@ public void testSuccessResponsePayload() throws Exception { JsonReader jsonReader = Json.createReader(new StringReader(response.getBody().get())); JsonObject json = jsonReader.readObject(); - System.out.println(json); - Assert.assertEquals(json.getString("outcome"), "UP","Expected outcome UP"); + Assert.assertEquals(json.getString("status"), "UP","Expected status UP"); Assert.assertTrue(json.getJsonArray("checks").isEmpty(), "Expected empty checks array"); } diff --git a/tck/src/main/java/org/eclipse/microprofile/health/tck/SingleProcedureFailedTest.java b/tck/src/main/java/org/eclipse/microprofile/health/tck/SingleProcedureFailedTest.java index d982f1b..71abc00 100644 --- a/tck/src/main/java/org/eclipse/microprofile/health/tck/SingleProcedureFailedTest.java +++ b/tck/src/main/java/org/eclipse/microprofile/health/tck/SingleProcedureFailedTest.java @@ -75,16 +75,16 @@ public void testFailureResponsePayload() throws Exception { ); Assert.assertEquals( - asJsonObject(checks.get(0)).getString("state"), + asJsonObject(checks.get(0)).getString("status"), "DOWN", "Expected a successful check result" ); // overall outcome Assert.assertEquals( - json.getString("outcome"), + json.getString("status"), "DOWN", - "Expected overall outcome to be unsuccessful" + "Expected overall status to be unsuccessful" ); } } diff --git a/tck/src/main/java/org/eclipse/microprofile/health/tck/SingleProcedureSuccessfulTest.java b/tck/src/main/java/org/eclipse/microprofile/health/tck/SingleProcedureSuccessfulTest.java index 7d2530e..7a3ce79 100644 --- a/tck/src/main/java/org/eclipse/microprofile/health/tck/SingleProcedureSuccessfulTest.java +++ b/tck/src/main/java/org/eclipse/microprofile/health/tck/SingleProcedureSuccessfulTest.java @@ -75,16 +75,16 @@ public void testSuccessResponsePayload() throws Exception { ); Assert.assertEquals( - asJsonObject(checks.get(0)).getString("state"), + asJsonObject(checks.get(0)).getString("status"), "UP", "Expected a successful check result" ); // overall outcome Assert.assertEquals( - json.getString("outcome"), + json.getString("status"), "UP", - "Expected overall outcome to be successful" + "Expected overall status to be successful" ); } }