feat(health): Add tonic-health server impl

This commit adds a new crate `tonic-health` which implements the
[standard GRPC Health Checking][checking] protocol.

Currently there is only a server implementation, though others have
alluded in the discussion in #135 that client implementations exist
which could also be imported as necessary.

A example server has also been added - once the client work is done a
client for this should be added also.

[checking]: https://github.com/grpc/grpc/blob/master/doc/health-checking.md

Cargo.toml

@@ -2,9 +2,12 @@
 members = [
     "tonic",
     "tonic-build",
+    "tonic-health",
+
     # Non-published crates
     "examples",
     "interop",
+
     # Tests
     "tests/included_service",
     "tests/same_name",

README.md

@@ -29,6 +29,7 @@ contains the tools to build clients and servers from [`protobuf`] definitions.
 - Load balancing
 - Custom metadata
 - Authentication
+- Health Checking
 
 ## Getting Started
 
@@ -67,6 +68,8 @@ question. If that doesn't work, try opening an [issue] with the question.
 - [`tonic`](https://github.com/hyperium/tonic/tree/master/tonic): Generic gRPC and HTTP/2 client/server
 implementation.
 - [`tonic-build`](https://github.com/hyperium/tonic/tree/master/tonic-build): [`prost`] based service codegen.
+- [`tonic-health`](https://github.com/hyperium/tonic/tree/master/tonic-health): Implementation of the standard [gRPC
+health checking service][healthcheck]. Also serves as an example of both unary and response streaming.
 - [`examples`](https://github.com/hyperium/tonic/tree/master/examples): Example gRPC implementations showing off
 tls, load balancing and bi-directional streaming.
 - [`interop`](https://github.com/hyperium/tonic/tree/master/interop): Interop tests implementation.
@@ -105,3 +108,4 @@ terms or conditions.
 [Chat]: https://discord.gg/6yGkFeN
 [routeguide-tutorial]: https://github.com/hyperium/tonic/blob/master/examples/routeguide-tutorial.md
 [helloworld-tutorial]: https://github.com/hyperium/tonic/blob/master/examples/helloworld-tutorial.md
+[healthcheck]: https://github.com/grpc/grpc/blob/master/doc/health-checking.md

examples/Cargo.toml

@@ -102,6 +102,10 @@ path = "src/hyper_warp/client.rs"
 name = "hyper-warp-server"
 path = "src/hyper_warp/server.rs"
 
+[[bin]]
+name = "health-server"
+path = "src/health/server.rs"
+
 [dependencies]
 tonic = { path = "../tonic", features = ["tls", "data-prost"] }
 prost = "0.6"
@@ -126,6 +130,8 @@ warp = { version = "0.2", default-features = false }
 http = "0.2"
 http-body = "0.3"
 pin-project = "0.4"
+# Health example
+tonic-health = { path = "../tonic-health" }
 
 [build-dependencies]
 tonic-build = { path = "../tonic-build", features = ["prost"] }

examples/README.md

@@ -72,6 +72,13 @@ $ cargo run --bin tls-client
 $ cargo run --bin tls-server
 ```
 
+## Health Checking
+
+### Server
+
+```bash
+$ cargo run --bin health-server
+```
 
 ### Notes:
 

examples/src/health/server.rs

@@ -0,0 +1,68 @@
+use tonic::{transport::Server, Request, Response, Status};
+
+use hello_world::greeter_server::{Greeter, GreeterServer};
+use hello_world::{HelloReply, HelloRequest};
+use std::time::Duration;
+use tokio::time::delay_for;
+use tonic_health::server::HealthReporter;
+
+pub mod hello_world {
+    tonic::include_proto!("helloworld");
+}
+
+#[derive(Default)]
+pub struct MyGreeter {}
+
+#[tonic::async_trait]
+impl Greeter for MyGreeter {
+    async fn say_hello(
+        &self,
+        request: Request<HelloRequest>,
+    ) -> Result<Response<HelloReply>, Status> {
+        println!("Got a request from {:?}", request.remote_addr());
+
+        let reply = hello_world::HelloReply {
+            message: format!("Hello {}!", request.into_inner().name),
+        };
+        Ok(Response::new(reply))
+    }
+}
+
+/// This function (somewhat improbably) flips the status of a service every second, in order
+/// that the effect of `tonic_health::HealthReporter::watch` can be easily observed.
+async fn twiddle_service_status(mut reporter: HealthReporter) {
+    let mut iter = 0u64;
+    loop {
+        iter += 1;
+        delay_for(Duration::from_secs(1)).await;
+
+        if iter % 2 == 0 {
+            reporter.set_serving::<GreeterServer<MyGreeter>>().await;
+        } else {
+            reporter.set_not_serving::<GreeterServer<MyGreeter>>().await;
+        };
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let (mut health_reporter, health_service) = tonic_health::server::health_reporter();
+    health_reporter
+        .set_serving::<GreeterServer<MyGreeter>>()
+        .await;
+
+    tokio::spawn(twiddle_service_status(health_reporter.clone()));
+
+    let addr = "[::1]:50051".parse().unwrap();
+    let greeter = MyGreeter::default();
+
+    println!("HealthServer + GreeterServer listening on {}", addr);
+
+    Server::builder()
+        .add_service(health_service)
+        .add_service(GreeterServer::new(greeter))
+        .serve(addr)
+        .await?;
+
+    Ok(())
+}

tonic-health/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "tonic-health"
+version = "0.1.0"
+authors = ["James Nugent <james@jen20.com>"]
+edition = "2018"
+license = "MIT"
+repository = "https://github.com/hyperium/tonic"
+homepage = "https://github.com/hyperium/tonic"
+description = """
+Health Checking module of `tonic` gRPC implementation.
+"""
+readme = "README.md"
+categories = ["network-programming", "asynchronous"]
+keywords = ["rpc", "grpc", "async", "healthcheck"]
+
+
+[dependencies]
+async-stream = "0.2"
+tokio = { version = "0.2", features = ["sync", "stream"] }
+tonic = { path = "../tonic", features = ["codegen", "data-prost", "transport"] }
+bytes = "0.5"
+prost = "0.6"
+
+
+[dev-dependencies]
+tokio = { version = "0.2", features = ["rt-core", "macros"]}
+
+
+[build-dependencies]
+tonic-build = { path = "../tonic-build" }

tonic-health/build.rs

@@ -0,0 +1,9 @@
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tonic_build::prost::configure()
+        .build_server(true)
+        .build_client(false)
+        .format(true)
+        .compile(&["proto/health.proto"], &["proto/"])?;
+
+    Ok(())
+}

tonic-health/proto/health.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package grpc.health.v1;
+
+message HealthCheckRequest {
+    string service = 1;
+}
+
+message HealthCheckResponse {
+    enum ServingStatus {
+        UNKNOWN = 0;
+        SERVING = 1;
+        NOT_SERVING = 2;
+    }
+    ServingStatus status = 1;
+}
+
+service Health {
+    rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
+
+    rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
+}

tonic-health/src/lib.rs

@@ -0,0 +1,35 @@
+use std::fmt::{Display, Formatter};
+
+mod proto {
+    tonic::include_proto!("grpc.health.v1");
+}
+
+pub mod server;
+
+/// An enumeration of values representing gRPC service health.
+#[derive(Copy, Clone, Debug, PartialEq)]
+pub enum ServingStatus {
+    Unknown,
+    Serving,
+    NotServing,
+}
+
+impl Display for ServingStatus {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ServingStatus::Unknown => f.write_str("Unknown"),
+            ServingStatus::Serving => f.write_str("Serving"),
+            ServingStatus::NotServing => f.write_str("NotServing"),
+        }
+    }
+}
+
+impl From<ServingStatus> for proto::health_check_response::ServingStatus {
+    fn from(s: ServingStatus) -> Self {
+        match s {
+            ServingStatus::Unknown => proto::health_check_response::ServingStatus::Unknown,
+            ServingStatus::Serving => proto::health_check_response::ServingStatus::Serving,
+            ServingStatus::NotServing => proto::health_check_response::ServingStatus::NotServing,
+        }
+    }
+}