From 45479ed5ef597b11b6ec422e09d299d55a23b228 Mon Sep 17 00:00:00 2001 From: xstefank Date: Wed, 20 Feb 2019 10:59:00 +0100 Subject: [PATCH] [issue #110] Wireformat `checks` property as object, not array, keyed by check name Signed-off-by: xstefank --- spec/src/main/asciidoc/java-api.adoc | 4 +- .../main/asciidoc/protocol-wireformat.adoc | 116 +++++++++--------- 2 files changed, 59 insertions(+), 61 deletions(-) diff --git a/spec/src/main/asciidoc/java-api.adoc b/spec/src/main/asciidoc/java-api.adoc index 80fd169..f95f2f8 100644 --- a/spec/src/main/asciidoc/java-api.adoc +++ b/spec/src/main/asciidoc/java-api.adoc @@ -68,6 +68,8 @@ public class SuccessfulCheck implements HealthCheck { The `name` is used to tell the different checks apart when a human operator looks at the responses. It may be that one check of several fails and it's useful to know which one. +The names are required to be unique within the context of application deployment. + `HealthCheckResponse` 's also support a free-form information holder, that can be used to supply arbitrary data to the consuming end: ``` @@ -121,4 +123,4 @@ class MyChecks { return () -> HealthStatus.state(getCpuUsage() < 0.9); } }} -``` \ No newline at end of file +``` diff --git a/spec/src/main/asciidoc/protocol-wireformat.adoc b/spec/src/main/asciidoc/protocol-wireformat.adoc index 23eb839..fd2a788 100644 --- a/spec/src/main/asciidoc/protocol-wireformat.adoc +++ b/spec/src/main/asciidoc/protocol-wireformat.adoc @@ -123,7 +123,7 @@ Each provider MUST provide the REST/HTTP interaction, but MAY provide other prot * Producer MUST support JSON encoded payload with simple UP/DOWN states * 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 `name` entry specifying the name of the check, to support protocols that support external identifier (i.e. URI). This name MUST be unique within the context of the application. * 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 @@ -143,7 +143,7 @@ When multiple procedures are installed all procedures MUST be executed and the o ==== Executing procedures -When executing health check procedures a producer MUST handle any unchecked exceptions and synthesize a substitute respone. +When executing health check procedures a producer MUST handle any unchecked exceptions and synthesize a substitute response. * The synthesized response MUST contain a `status` entry with a value of "DOWN". * The synthesized response MUST contain a `name` entry with a value set to the runtime class name of the failing check. @@ -216,46 +216,47 @@ The following table give valid health check responses: ``` { - "$schema": "http://json-schema.org/draft-04/schema#", - "type": "object", - "properties": { - "status": { - "type": "string" - }, - "checks": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "status": { - "type": "string" - }, - "data": { - "type": "object", - "properties": { - "key": { - "type": "string" - }, - "value": { - "type": "string|boolean|int" - } - } - } - }, - "required": [ - "name", - "status" - ] - } - } - }, - "required": [ - "status", - "checks" - ] + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "checks": { + "type": "object", + "patternProperties": { + "^.*$": { + "properties": { + "name": { + "type": "string" + }, + "status": { + "type": "string" + }, + "data": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "value": { + "type": [ + "string", + "boolean", + "integer" + ] + } + } + } + } + } + } + } + }, + "required": [ + "status", + "checks" + ] } ``` (See http://jsonschema.net/#/) @@ -268,16 +269,15 @@ Status `200` and the following payload: ``` { "status": "UP", - "checks": [ - { - "name": "myCheck", + "checks": { + "myCheck": { "status": "UP", "data": { "key": "value", "foo": "bar" } } - ] + } } ``` @@ -286,20 +286,18 @@ Status `503` and the following payload: ``` { "status": "DOWN", - "checks": [ - { - "name": "firstCheck", + "checks": { + "firstCheck": { "status": "DOWN", "data": { "key": "value", "foo": "bar" } }, - { - "name": "secondCheck", + "secondCheck": { "status": "UP" } - ] + } } ``` @@ -307,19 +305,17 @@ Status 500 ``` { "status": "DOWN", - "checks": [ - { - "name": "example.health.FirstCheck", + "checks": { + "example.health.FirstCheck": { "status": "DOWN", "data": { "rootCause": "timed out waiting for available connection" } }, - { - "name": "secondCheck", + "secondCheck": { "status": "UP" } - ] + } } ``` @@ -330,7 +326,7 @@ Status `200` and the following payload: ``` { "status": "UP", - "checks": [] + "checks": {} } ``` @@ -341,6 +337,6 @@ Status `503` and the following payload: ``` { "status": "DOWN", - "checks": [] + "checks": {} } ```