grpchealth

README

grpchealth

connectrpc.com/grpchealth 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 connectrpc.com (especially the Getting Started guide for Go), the Connect repo, or the demo service.

Example

package main

import (
  "net/http"

  "connectrpc.com/grpchealth"
)

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 use
  // http.ListenAndServeTLS instead.
  protocols := new(http.Protocols)
  protocols.SetHTTP1(true)
  protocols.SetUnencryptedHTTP2(true)
  server := &http.Server{
    Addr:      ":8080",
    Handler:   mux,
    Protocols: protocols,
  }
  server.ListenAndServe()
}

Status: Stable

This module is stable. It supports:

• The two most recent major releases of Go (the same version of Go that continue to eceive security patches).
• APIv2 of Protocol Buffers in Go (google.golang.org/protobuf).

Within those parameters, grpchealth 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 connectrpc.com/connect. Documentation is available at https://connectrpc.com.

Index

• Constants
• func NewHandler(checker Checker, options ...connect.HandlerOption) (string, http.Handler)
• type CheckRequest
• type CheckResponse
• type Checker
• type Client
  • func NewClient(httpClient connect.HTTPClient, baseURL string, opts ...connect.ClientOption) *Client
  • func (c *Client) Check(ctx context.Context, req *CheckRequest) (*CheckResponse, error)
  • func (c *Client) Watch(ctx context.Context, req *CheckRequest) <-chan WatchEvent
• type StaticChecker
  • func NewStaticChecker(services ...string) *StaticChecker
  • func (c *StaticChecker) Check(_ context.Context, req *CheckRequest) (*CheckResponse, error)
  • func (c *StaticChecker) SetStatus(service string, status Status)
  • func (c *StaticChecker) Watch(_ context.Context, req *CheckRequest, onChange func()) (func(), error)
• type Status
  • func (s Status) String() string
• type WatchEvent
• type Watcher

Constants

const (
	// HealthV1ServiceName is the fully-qualified name of the v1 version of the health service.
	HealthV1ServiceName = "grpc.health.v1.Health"
)

Functions

func NewHandler

func NewHandler(checker Checker, options ...connect.HandlerOption) (string, http.Handler)

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.

If the Checker also implements Watcher, the returned handler supports the streaming Watch RPC. Otherwise, the Watch method returns connect.CodeUnimplemented.

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 Client

type Client struct {
	// contains filtered or unexported fields
}

Client calls the gRPC health-checking API. It implements Checker, so it can be used anywhere a Checker is expected. It is safe to use concurrently.

func NewClient

func NewClient(httpClient connect.HTTPClient, baseURL string, opts ...connect.ClientOption) *Client

NewClient constructs a new Client for the gRPC health-checking API.

The URL supplied should be the base URL of the Connect or gRPC server (for example, https://api.example.com). By default the client uses the Connect protocol with the binary Protobuf codec. To use the gRPC protocol, supply connect.WithGRPC as an option.

func (*Client) Check

func (c *Client) Check(ctx context.Context, req *CheckRequest) (*CheckResponse, error)

Check reports the health of the named service. An empty service name requests the health of the whole server process. If the service is unknown, the returned error will have connect.CodeNotFound.

func (*Client) Watch

func (c *Client) Watch(ctx context.Context, req *CheckRequest) <-chan WatchEvent

Watch streams health status changes for the requested service. Status updates are delivered on the returned channel. The channel closes when the stream ends, either because ctx is canceled, the server terminates the stream, or an error occurs. If the stream terminates with an error and ctx has not been canceled, the final value on the channel has its Err field set.

Callers cancel ctx to stop the stream and release resources:

ctx, cancel := context.WithCancel(ctx)
defer cancel()
for event := range client.Watch(ctx, &CheckRequest{Service: svc}) {
    if event.Err != nil {
        // Handle error; this is the final event.
        break
    }
    fmt.Println(event.Response.Status)
}

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. It also implements Watcher, so the handler returned by NewHandler supports the streaming Watch RPC.

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

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.

If the given service name is empty, it sets a server-wide status that is returned to check requests that do not request a particular service. If no such status is ever set, checks that do not request a particular service will get a response of StatusServing.

func (*StaticChecker) Watch

func (c *StaticChecker) Watch(_ context.Context, req *CheckRequest, onChange func()) (func(), error)

Watch implements Watcher. It's safe to call concurrently with SetStatus.

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
)

func (Status) String

func (s Status) String() string

String representation of the status.

type WatchEvent

type WatchEvent struct {
	Response *CheckResponse
	Err      error
}

WatchEvent is a single update delivered by Client.Watch. Exactly one of Response or Err is set. An Err event, when delivered, is the final event on the channel.

type Watcher

type Watcher interface {
	Checker

	// Watch monitors the health of the requested service and calls onChange
	// whenever the status may have changed. Implementations should return
	// quickly rather than blocking. They may return an error if the request
	// cannot be satisfied (for example, if the service is unknown). The
	// context is only used for the duration of the Watch call itself; it
	// does not govern the lifetime of the watch.
	//
	// The returned stop function tells the implementation to stop calling
	// onChange. However, if two goroutines are racing, one calling stop and
	// the other calling onChange, this is fine. In other words, it is not
	// an error if onChange gets called after stop; but stop should arrange
	// for calls to onChange to cease.
	Watch(ctx context.Context, req *CheckRequest, onChange func()) (stop func(), err error)
}

A Watcher extends Checker with the ability to notify the caller when the health status of a service changes. When a Checker also implements Watcher, the handler returned by NewHandler supports the streaming Watch RPC.