README
¶
connect-grpchealth-go
connect-grpchealth-go adds support for gRPC-style health checks to any
net/http server — including those built with Connect. By
polling this API, load balancers, container orchestrators, and other
infrastructure systems can respond to changes in your HTTP server's health.
The exposed health checking API is wire compatible with Google's gRPC implementations, so it works with grpcurl, grpc-health-probe, and Kubernetes gRPC liveness probes.
For more on Connect, see the announcement blog post, the documentation
on connect.build (especially the Getting Started guide for Go), the
connect-go repo, or the demo service.
Example
package main
import (
"net/http"
"golang.org/x/net/http2"
"golang.org/x/net/http2/h2c"
grpchealth "github.com/bufbuild/connect-grpchealth-go"
)
func main() {
mux := http.NewServeMux()
checker := grpchealth.NewStaticChecker(
"acme.user.v1.UserService",
"acme.group.v1.GroupService",
// protoc-gen-connect-go generates package-level constants
// for these fully-qualified protobuf service names, so you'd more likely
// reference userv1.UserServiceName and groupv1.GroupServiceName.
)
mux.Handle(grpchealth.NewHandler(checker))
// If you don't need to support HTTP/2 without TLS (h2c), you can drop
// x/net/http2 and use http.ListenAndServeTLS instead.
http.ListenAndServe(
":8080",
h2c.NewHandler(mux, &http2.Server{}),
)
}
Status: Stable
This module is stable. It supports:
- The two most recent major releases of Go.
- APIv2 of Protocol Buffers in Go (
google.golang.org/protobuf).
Within those parameters, connect-grpchealth-go follows semantic versioning.
We will not make breaking changes in the 1.x series of releases.
Legal
Offered under the Apache 2 license.
Documentation
¶
Overview ¶
Package grpchealth enables any net/http server, including those built with Connect, to respond to gRPC-style health checks. This lets load balancers, container orchestrators, and other infrastructure systems respond to changes in your HTTP server's health.
The exposed health-checking API is wire compatible with Google's gRPC implementations, so it works with grpcurl, grpc-health-probe, and Kubernetes gRPC liveness probes.
The core Connect package is github.com/bufbuild/connect-go. Documentation is available at https://connect.build.
Index ¶
Constants ¶
const HealthV1ServiceName = "grpc.health.v1.Health"
HealthV1ServiceName is the fully-qualified name of the v1 version of the health service.
Variables ¶
This section is empty.
Functions ¶
func NewHandler ¶
NewHandler wraps the supplied Checker to build an HTTP handler for gRPC's health-checking API. It returns the path on which to mount the handler and the HTTP handler itself.
Note that the returned handler only supports the unary Check method, not the streaming Watch. As suggested in gRPC's health schema, it returns connect.CodeUnimplemented for the Watch method.
For more details on gRPC's health checking protocol, see https://github.com/grpc/grpc/blob/master/doc/health-checking.md and https://github.com/grpc/grpc/blob/master/src/proto/grpc/health/v1/health.proto.
Types ¶
type CheckRequest ¶
type CheckRequest struct {
Service string
}
CheckRequest is a request for the health of a service. When using protobuf, Service will be a fully-qualified service name (for example, "acme.ping.v1.PingService"). If the Service is an empty string, the caller is asking for the health status of whole process.
type CheckResponse ¶
type CheckResponse struct {
Status Status
}
CheckResponse reports the health of a service (or of the whole process). The only valid Status values are StatusUnknown, StatusServing, and StatusNotServing. When asked to report on the status of an unknown service, Checkers should return a connect.CodeNotFound error.
Often, systems monitoring health respond to errors by restarting the process. They often respond to StatusNotServing by removing the process from a load balancer pool.
type Checker ¶
type Checker interface {
Check(context.Context, *CheckRequest) (*CheckResponse, error)
}
A Checker reports the health of a service. It must be safe to call concurrently.
type StaticChecker ¶
type StaticChecker struct {
// contains filtered or unexported fields
}
StaticChecker is a simple Checker implementation. It always returns StatusServing for the process, and it returns a static value for each service.
If you have a dynamic list of services, want to ping a database as part of your health check, or otherwise need something more specialized, you should write a custom Checker implementation.
func NewStaticChecker ¶
func NewStaticChecker(services ...string) *StaticChecker
NewStaticChecker constructs a StaticChecker. By default, each of the supplied services has StatusServing.
The supplied strings should be fully-qualified protobuf service names (for example, "acme.user.v1.UserService"). Generated Connect service files have this declared as a constant.
func (*StaticChecker) Check ¶
func (c *StaticChecker) Check(_ context.Context, req *CheckRequest) (*CheckResponse, error)
Check implements Checker. It's safe to call concurrently with SetStatus.
func (*StaticChecker) SetStatus ¶ added in v1.0.0
func (c *StaticChecker) SetStatus(service string, status Status)
SetStatus sets the health status of a service, registering a new service if necessary. It's safe to call SetStatus and Check concurrently.
type Status ¶
type Status uint8
Status describes the health of a service.
const ( // StatusUnknown indicates that the service's health state is indeterminate. StatusUnknown Status = 0 // StatusServing indicates that the service is ready to accept requests. StatusServing Status = 1 // StatusNotServing indicates that the process is healthy but the service is // not accepting requests. For example, StatusNotServing is often appropriate // when your primary database is down or unreachable. StatusNotServing Status = 2 )
Source Files
Directories