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"

  "golang.org/x/net/http2"
  "golang.org/x/net/http2/h2c"
  "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 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 three most recent major releases of Go. Keep in mind that only the last two releases receive 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 StaticChecker
  • func NewStaticChecker(services ...string) *StaticChecker
  • func (c *StaticChecker) Check(_ context.Context, req *CheckRequest) (*CheckResponse, error)
  • func (c *StaticChecker) SetStatus(service string, status Status)
• type Status
  • func (s Status) String() string

Constants

const HealthV1ServiceName = "grpc.health.v1.Health"

HealthV1ServiceName is the fully-qualified name of the v1 version of the health service.

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.

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

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
)

func (Status) String

func (s Status) String() string

String representation of the status.