grpchealth

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 12, 2023 License: Apache-2.0 Imports: 7 Imported by: 26

README

connect-grpchealth-go

Build Report Card GoDoc

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:

Within those parameters, connect-grpchealth-go follows semantic versioning. We will not make breaking changes in the 1.x series of releases.

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

View Source
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

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

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
)

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL