Crate connectrpc_health 

gRPC health-checking service for connectrpc.

Wire-compatible with grpc.health.v1.Health, so grpc_health_probe, grpcurl, Kubernetes’ gRPC liveness probes, and any other client of the standard gRPC health protocol just work.

Non-empty unregistered services return Err(ConnectError::not_found(_)) from both Check and Watch; the empty service auto-subscribes on Watch and returns Serving on Check by default — see HealthService’s # Unknown services section for how this relates to the gRPC Health spec.

Cargo features

• client (on by default) — re-exports the generated HealthClient for in-process probes, integration tests, and sidecar tooling. Pulls in connectrpc’s client feature (the HTTP/2 transport stack). Server-only deployments drop it with connectrpc-health = { version = "0.7", default-features = false }; use connectrpc_health::HealthClient then becomes an unresolved import (the type is gone), but the dependency graph loses connectrpc/client.

Writing a custom Checker

StaticChecker covers most servers. If you implement Checker yourself (e.g. report NotServing while a database connection is down), note that the default watch implementation returns Unimplemented — fine for kubelet / grpc_health_probe (they only call Check), but service meshes (Linkerd, Istio) and gRPC clients with health-based load balancing call Watch too. Override the method if your probes need it. See Checker::watch for details.

Quick start

use connectrpc::Router;
use connectrpc_health::{install_static, Status};

// In real code, pass the generated `*_SERVICE_NAME` constant —
// the literal below is a stand-in.
let (router, health) = install_static(Router::new(), [
    "acme.user.v1.UserService",
]);

// Later, when something goes wrong. `set_status` errors on unknown
// names; here the name was just registered above, so `.expect`
// documents the invariant.
health
    .set_status("acme.user.v1.UserService", Status::NotServing)
    .expect("registered above");

// ...and at shutdown. `shutdown()` flips every registered service,
// including the empty whole-process entry seeded on construction.
health.shutdown();

For custom logic (probing a database, propagating dependency state), implement Checker directly and wrap it in HealthService::new / HealthService::from_arc; see the next section for the one extra call that path needs.

Request limits

A HealthCheckRequest is one service name, so the health routes do not need the multi-megabyte request ceiling a connectrpc service allows by default. This crate sizes Check and Watch to MAX_REQUEST_BYTES (16 KiB) per request through per-route Limits — see request_limits for the exact profile — and a larger request is refused with resource_exhausted before it reaches the Checker. The profile replaces the service-wide limits on these two routes, whether those are looser or tighter.

• install_static applies request_limits for you.
• Registering a HealthService any other way — the generated HealthExt::register or Router::add_service — does not, so follow it with apply_request_limits(router, request_limits()).
• To tune the health routes specifically, call apply_request_limits with your own Limits after either path; the later call wins.

use connectrpc::{Limits, Router};
use connectrpc_health::{apply_request_limits, install_static};

let (router, health) = install_static(Router::new(), ["acme.user.v1.UserService"]);
// Optional: hold the health routes to 1 KiB instead of the bundled 16 KiB.
let router = apply_request_limits(
    router,
    Limits::default()
        .with_max_request_body_size(1024)
        .with_max_message_size(1024),
);

Modules

wire

Re-exports of the generated grpc.health.v1 wire types — request and response messages, ServingStatus, the *_SPEC constants. Downstream crates can build probe loops without regenerating the proto.

Structs

HealthClientclient

Generated client for calling a grpc.health.v1.Health server.

HealthService

gRPC-compatible health service backed by a user-supplied Checker.

StaticChecker

In-memory checker backed by a HashMap<String, Status>.

StatusStream

A stream of Status updates produced by Checker::watch.

UnknownServiceError

Returned by StaticChecker::set_status when called with a name that hasn’t been registered. Register first via StaticChecker::register (or up front via StaticChecker::with_services) to avoid this.

Enums

Status

Health status of a single service or of the whole server.

Constants

HEALTH_SERVICE_NAME

Fully-qualified protobuf service name: "grpc.health.v1.Health". Full service name for this service.

MAX_REQUEST_BYTES

The largest request message, in bytes on the wire and after decompression, the health routes accept under request_limits: 16 KiB.

Traits

Checker

Reports the health of services on this server.

HealthExt

Generated extension trait that adds .register(router) to any Arc<S> where S: Health. Import it to register a HealthService. Extension trait for registering a service implementation with a Router.

Functions

apply_request_limits

Set the Check and Watch routes on router to limits, replacing the service-wide limits for them (whether looser or tighter).

install_static

One-line installation for the static-checker happy path.

request_limits

The per-route Limits this crate sets on its Check and Watch routes: message size capped at MAX_REQUEST_BYTES (the request body at that plus the 5-byte envelope framed protocols add), decode budget left at the connectrpc default.