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

Fixes #135.

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(())
+}