From a8f219fad5722d708b77f39778622790500fd2ef Mon Sep 17 00:00:00 2001 From: Teju Nareddy Date: Wed, 11 Sep 2019 12:15:49 -0700 Subject: [PATCH 1/2] Add documentation for `grpc-health-check` Signed-off-by: Teju Nareddy --- packages/grpc-health-check/README.md | 91 +++++++++++++++++++++++++ packages/grpc-health-check/package.json | 5 +- 2 files changed, 94 insertions(+), 2 deletions(-) create mode 100644 packages/grpc-health-check/README.md diff --git a/packages/grpc-health-check/README.md b/packages/grpc-health-check/README.md new file mode 100644 index 00000000..6484ac0a --- /dev/null +++ b/packages/grpc-health-check/README.md @@ -0,0 +1,91 @@ +# grpc-health-check + +Health check client and service for use with gRPC-node. + +## Background + +This package exports both a client and server that adhere to the [gRPC Health Checking Protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). + +By using this package, clients and servers can rely on common proto and service definitions. This means: +- Clients can use the generated stubs to health check _any_ server that adheres to the protocol. +- Servers do not reimplement common logic for publishing health statuses. + +## Installation + +Use the package manager [npm](https://www.npmjs.com/get-npm) to install `grpc-health-check`. + +```bash +npm install grpc-health-check +``` + +## Usage + +### Server + +Any gRPC-node server can use `grpc-health-check` to adhere to the gRPC Health Checking Protocol. +The following shows how this package can be added to a pre-existing gRPC server. + +```javascript 1.8 +// Import package +let health = require('grpc-health-check'); + +// Define service status map. Key is the service name, value is the corresponding status. +// By convention, the empty string "" key represents that status of the entire server. +const statusMap = { + "ServiceFoo": proto.grpc.health.v1.HealthCheckResponse.ServingStatus.SERVING, + "ServiceBar": proto.grpc.health.v1.HealthCheckResponse.ServingStatus.NOT_SERVING, + "": proto.grpc.health.v1.HealthCheckResponse.ServingStatus.NOT_SERVING, +}; + +// Construct the service implementation +let healthImpl = new health.Implementation(statusMap); + +// Add the service and implementation to your pre-existing gRPC-node server +server.addService(health.service, healthImpl); +``` + +Congrats! Your server now allows any client to run a health check against it. + +### Client + +Any gRPC-node client can use `grpc-health-check` to run health checks against other servers that follow the protocol. +The following shows how this package can be used by a pre-existing gRPC client. + +```javascript 1.8 +// Import package +let grpc = require('grpc'); +let health = require('grpc-health-check'); + +// Create the client +let healthClient = new health.Client('localhost:8082', grpc.credentials.createInsecure()); + +// Define the request, which contains the service to health check +// By convention, the empty string "" key represents that status of the entire server. +let request = { + service: "", +}; + +// Define the callback +function callback (error, status) { + if (error) { + console.error(error); + return; + } + + console.log(status); +} + +// Make the request +healthClient.check(request, callback); +``` + +This should print out "NOT_SERVING" if used with the server above. + +## Contributing + +Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. + +Please make sure to update tests as appropriate. + +## License +[Apache License 2.0](https://choosealicense.com/licenses/apache-2.0/) diff --git a/packages/grpc-health-check/package.json b/packages/grpc-health-check/package.json index e10de7c1..388eb7d8 100644 --- a/packages/grpc-health-check/package.json +++ b/packages/grpc-health-check/package.json @@ -1,8 +1,8 @@ { "name": "grpc-health-check", - "version": "1.7.0", + "version": "1.7.1", "author": "Google Inc.", - "description": "Health check service for use with gRPC", + "description": "Health check client and service for use with gRPC-node", "repository": { "type": "git", "url": "https://github.com/grpc/grpc-node.git" @@ -22,6 +22,7 @@ }, "files": [ "LICENSE", + "README.md", "health.js", "v1" ], From 0e37241a512a88864b9c90e717c8c78f861815e3 Mon Sep 17 00:00:00 2001 From: Teju Nareddy Date: Wed, 11 Sep 2019 13:21:05 -0700 Subject: [PATCH 2/2] Omit client code due to bug in package. Will re-add once package is updated. Signed-off-by: Teju Nareddy --- packages/grpc-health-check/README.md | 31 ---------------------------- 1 file changed, 31 deletions(-) diff --git a/packages/grpc-health-check/README.md b/packages/grpc-health-check/README.md index 6484ac0a..62a88347 100644 --- a/packages/grpc-health-check/README.md +++ b/packages/grpc-health-check/README.md @@ -49,37 +49,6 @@ Congrats! Your server now allows any client to run a health check against it. ### Client Any gRPC-node client can use `grpc-health-check` to run health checks against other servers that follow the protocol. -The following shows how this package can be used by a pre-existing gRPC client. - -```javascript 1.8 -// Import package -let grpc = require('grpc'); -let health = require('grpc-health-check'); - -// Create the client -let healthClient = new health.Client('localhost:8082', grpc.credentials.createInsecure()); - -// Define the request, which contains the service to health check -// By convention, the empty string "" key represents that status of the entire server. -let request = { - service: "", -}; - -// Define the callback -function callback (error, status) { - if (error) { - console.error(error); - return; - } - - console.log(status); -} - -// Make the request -healthClient.check(request, callback); -``` - -This should print out "NOT_SERVING" if used with the server above. ## Contributing