dgrpc

README

dfuse GRPC Library

This is a helper library for instanciating GRPC clients and servers. It is used as part of dfuse.

Usage

See example usage in bstream.

Contributing

Issues and PR in this repo related strictly to the dgrpc library.

Report any protocol-specific issues in their respective repositories

Please first refer to the general dfuse contribution guide, if you wish to contribute to this code base.

License

Apache 2.0

Documentation

Index

• Variables
• func ListenAndServe(srv *http.Server) error
• func NewExternalClient(remoteAddr string, extraOpts ...grpc.DialOption) (*grpc.ClientConn, error)
• func NewGRPCServer(opts ...ServerOption) *grpc.Server
• func NewInternalClient(remoteAddr string) (*grpc.ClientConn, error)
• func NewServer(opts ...ServerOption) *grpc.Server
• func SimpleHTTPServer(srv *grpc.Server, listenAddr string, healthHandler http.HandlerFunc) *http.Server
• func SimpleHealthCheck(isDown func() bool) http.HandlerFunc
• type AuthCheckerFunc
• type HealthCheck
• type HealthCheckOver
• type Resolver
  • func (r *Resolver) Build(target resolver.Target, cc resolver.ClientConn, opts resolver.BuildOptions) (resolver.Resolver, error)
  • func (r *Resolver) Close()
  • func (r *Resolver) ResolveNow(resolver.ResolveNowOptions)
  • func (r *Resolver) Scheme() string
• type SecureTLSConfig
  • func SecuredByBuiltInSelfSignedCertificate() SecureTLSConfig
  • func SecuredByX509KeyPair(publicCertFile, privateKeyFile string) (SecureTLSConfig, error)
• type Server
  • func NewServer2(opts ...ServerOption) *Server
  • func (s *Server) Launch(listenAddr string)
  • func (s *Server) OnTerminated(f func(err error))
  • func (s *Server) RegisterService(f func(gs *grpc.Server))
  • func (s *Server) Shutdown(timeout time.Duration)
• type ServerOption
  • func InsecureServer() ServerOption
  • func OverrideTraceID() ServerOption
  • func PlainTextServer() ServerOption
  • func SecureServer(config SecureTLSConfig) ServerOption
  • func WithAuthChecker(authChecker AuthCheckerFunc, enforced bool) ServerOption
  • func WithHealthCheck(over HealthCheckOver, check HealthCheck) ServerOption
  • func WithLogger(logger *zap.Logger) ServerOption
  • func WithPostStreamInterceptor(interceptor grpc.StreamServerInterceptor) ServerOption
  • func WithPostUnaryInterceptor(interceptor grpc.UnaryServerInterceptor) ServerOption

Variables

var Verbosity = 3

Verbosity is configuration that can be used to globally reduce logging chattiness of various aspect of the dgrpc middleware.

Accepted value is a scale from 0 to 5 (inclusively). A verbosity of 0 means really not verbose, while 5 means really realy verbose. It can be mostly seen as: `Fatal` (0), `Error` (1), `Warn` (2), `Info` (3), `Debug` (4) and `Trace` (5).

For now, this controls server logging of gRCP code to zap level which reduce some of the case into `INFO` level and some more like `OK` on `DEBUG` level.

Functions

func ListenAndServe

func ListenAndServe(srv *http.Server) error

ListenAndServe open a TCP listener and serve gRPC through it the received HTTP server.

Deprecated: Uses `server := dgrpc.NewServer2(options...)` then `go server.Launch()` instead. If you

require HTTP health handler, uses option `dgrpc.WithHealthCheck(dgrpc.HealthCheckOverHTTP, ...)`
when configuring your server.

func NewExternalClient

func NewExternalClient(remoteAddr string, extraOpts ...grpc.DialOption) (*grpc.ClientConn, error)

NewExternalClient creates a grpc ClientConn with keepalive, tracing and secure TLS

func NewGRPCServer

func NewGRPCServer(opts ...ServerOption) *grpc.Server

NewGRPCServer creates a new standard fully configured with tracing, logging and more.

**Note** Debugging a gRPC server can be done by using `export GODEBUG=http2debug=2`

func NewInternalClient

func NewInternalClient(remoteAddr string) (*grpc.ClientConn, error)

NewInternalClient creates a grpc ClientConn with keepalive, tracing and *insecure TLS* debug me using `export GODEBUG=http2debug=2`

func NewServer

func NewServer(opts ...ServerOption) *grpc.Server

NewServer creates a new standard fully configured with tracing, logging and more.

Deprecated: Use NewGRPCServer version instead, the `NewServer` will return

a `dgrpc.Server` instance in an upcoming version.

func SimpleHTTPServer

func SimpleHTTPServer(srv *grpc.Server, listenAddr string, healthHandler http.HandlerFunc) *http.Server

SimpleHTTPServer creates an HTTP server that is able to serve gRPC traffic and has an HTTP handler over HTTP if `healthHandler` is specified.

Deprecated: Uses `server := dgrpc.NewServer2(options...)` with the `dgrpc.WithHealthCheck(dgrpc.HealthCheckOverHTTP, ...)`

then `go server.Launch()` instead. By default opens a plain-text server, if you require an insecure server
like before, use `InsecureServer` option.

func SimpleHealthCheck

func SimpleHealthCheck(isDown func() bool) http.HandlerFunc

SimpleHealthCheck creates an HTTP handler that server health check response based on `isDown`.

Deprecated: Uses `server := dgrpc.NewServer2(options...)` with the `dgrpc.WithHealthCheck(dgrpc.HealthCheckOverHTTP, ...)`

then `go server.Launch()` instead.

Types

type AuthCheckerFunc

type AuthCheckerFunc func(ctx context.Context, token, ipAddress string) (context.Context, error)

type HealthCheck

type HealthCheck func(ctx context.Context) (isReady bool, out interface{}, err error)

type HealthCheckOver

type HealthCheckOver uint8

HealthCheckOver is a bit field used by the `Server` to decide on what to serve the health check when it's defined.

const (
	// HealthCheckOverHTTP tells the `Server` to serve the health check over an HTTP endpoint (`/healthz` by default)
	HealthCheckOverHTTP HealthCheckOver = 1 << 0

	// HealthCheckOverGRPC tells the `Server` to serve the health check over the `grpc.health.v1.HealthServer` GRPC service.
	HealthCheckOverGRPC HealthCheckOver = 1 << 1
)

type Resolver

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

Resolver works by launching a ConnStateManager function when Build() is called.

func (*Resolver) Build

func (r *Resolver) Build(target resolver.Target, cc resolver.ClientConn, opts resolver.BuildOptions) (resolver.Resolver, error)

func (*Resolver) Close

func (r *Resolver) Close()

Close will close the context

func (*Resolver) ResolveNow

func (r *Resolver) ResolveNow(resolver.ResolveNowOptions)

ResolveNow is a noop for Resolver.

func (*Resolver) Scheme

func (r *Resolver) Scheme() string

type SecureTLSConfig

type SecureTLSConfig interface {
	// contains filtered or unexported methods
}

func SecuredByBuiltInSelfSignedCertificate

func SecuredByBuiltInSelfSignedCertificate() SecureTLSConfig

SecuredByBuiltInSelfSignedCertificate creates a SecureTLSConfig that uses the built-in hard-coded certificate found in package `insecure` (path `github.com/dfuse-io/dgrpc/insecure`).

This certificate is self-signed and distributed publicly over the internet, so it's not a safe certificate, can be seen as compromised.

**Never** uses that in a production environment.

func SecuredByX509KeyPair

func SecuredByX509KeyPair(publicCertFile, privateKeyFile string) (SecureTLSConfig, error)

SecuredByX509KeyPair creates a SecureTLSConfig by loading the provided public/private X509 pair (`.pem` files format).

type Server

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

Server is actually a thin wrapper struct around an `*http.Server` and a `*grpc.Server` to more easily managed how we deploy our gRPC service.

You first create a NewServer2(...) with the various option we provide for how stuff should be wired together. You then `Launch` it and the wrapper takes care of doing the hard code of correctly managing the lifecyle of everything.

Here how various options affects the behavior of the `Launch` method. - WithSecure(SecuredByX509KeyPair(..., ...)) => Starts a TLS HTTP2 endpoint to serve the gRPC over an encrypted connection - WithHealthCheck(check, HealthCheckOverHTTP) => Offers an HTTP endpoint `/healthz` to query the health check over HTTP

func NewServer2

func NewServer2(opts ...ServerOption) *Server

NewServer2 creates a new thin-wrapper `dgrpc.Server` instance to make it easy to configure and launch a gRPC server that has a well-defined lifecycle tied to `shutter.Shutter` pattern.

The server is easily configurable by providing various `dgrpc.ServerOption` options to change the behaviour of the server.

This new server is opinionated towards dfuse needs (for example supporting the health check over HTTP) but is generic and configurable enough to used by any organization.

Some elements are "hard-coded" but we are willing to open more the configuration if requested by the community.

**Important** We use `NewServer2` name temporarly while we test the concept, when

we are statisfied with the interface and feature set, the actual
`NewServer` will be replaced by this implementation.

func (*Server) Launch

func (s *Server) Launch(listenAddr string)

Launch starts all the necessary elements (gRPC Server, HTTP Server if required, etc.) and controls their lifecycle via the internal shutter.

This should be called in a Goroutine `go server.Launch("localhost:9000")` and `server.Shutdown()` should be called later on to stop gracefully the server.

func (*Server) OnTerminated

func (s *Server) OnTerminated(f func(err error))

func (*Server) RegisterService

func (s *Server) RegisterService(f func(gs *grpc.Server))

RegisterService can be used to register your own gRPC service handler.

server := dgrpc.NewServer2(...)
server.RegisterService(func (gs *grpc.Server) {
  pbapi.RegisterStateService(gs, implementation)
})

**Note**

func (*Server) Shutdown

func (s *Server) Shutdown(timeout time.Duration)

type ServerOption

type ServerOption func(*serverOptions)

ServerOption represents option that can be used when constructing a gRPC server to customize its behavior.

func InsecureServer

func InsecureServer() ServerOption

InsecureServer option can be used to flag to use a TSL config using a built-in self-signed certificate when starting the server which making it exchange in encrypted format but cannot be considered a secure setup.

This is a useful tool for development, **never** use it in a production environment. This is equivalent of using the `Secure(SecuredByBuiltInSelfSignedCertificate)` option.

Important: providing this option erases the settings of the counter-part **SecureServer** option and **PlainTextServer** option, it's mutually exclusive with them.

func OverrideTraceID

func OverrideTraceID() ServerOption

OverrideTraceID option can be used to force the generation of a new fresh trace ID for every gRPC request entering the middleware

func PlainTextServer

func PlainTextServer() ServerOption

PlainText option can be used to flag to not use a TSL config when starting the server which making it exchanges it's data in **plain-text** format (plain binary is more accurate here).

Important: providing this option erases the settings of the counter-part **InsecureServer** option and **SecureServer** option, it's mutually exclusive with them.

func SecureServer

func SecureServer(config SecureTLSConfig) ServerOption

SecureServer option can be used to flag to use a secured TSL config when starting the server.

The config object can be created by one of the various `SecuredBy...` method on this package like `SecuredByX509KeyPair(certFile, keyFile)`.

Important: providing this option erases the settings of the counter-part **InsecureServer** option and **PlainTextServer** option, it's mutually exclusive with them.

func WithAuthChecker

func WithAuthChecker(authChecker AuthCheckerFunc, enforced bool) ServerOption

WithAuthChecker option can be used to pass a function that will be called on connection, validating authentication with 'Authorization: bearer' header

If `enforced` is set to `true`, the token is required and an error is thrown when it's not present. If sets to `false`, it's still extracted from the request metadata and pass to the auth checker function.

func WithHealthCheck

func WithHealthCheck(over HealthCheckOver, check HealthCheck) ServerOption

WithHealthCheck option can be used to automatically register an health check function that will be used to determine the health of the server.

If HealthCheckOverHTTP is used, the `Launch` method starts an HTTP endpoint '/healthz' to query the `HealthCheck` method provided information. The endpoint returns an `OK 200` if `HealthCheck` returned `isReady == true`, an `Service Unavailable 503` if `isReady == false`.

The HTTP response body returned depends on the combination of `out` and and `err` from `HealthCheck` call:

- Returns `out` as JSON if `out != nil && err == nil` - Returns `{"error": err.Error()}` JSON if `out == nil && err != nil` - Returns `{"ok": true}` JSON if `out == nil && err == nil`

If HealthCheckOverGRPC is used, the `Launch` method registers within the gRPC server a `grpc.health.v1.HealthServer` that uses the `HealthCheck` `isReady` field to returning either `HealthCheckResponse_SERVING` or `HealthCheckResponse_NOT_SERVING`.

Both option can be provided at a time with `HealthCheckOverHTTP | HealthCheckOverGRPC`

func WithLogger

func WithLogger(logger *zap.Logger) ServerOption

WithLogger option can be used to pass the logger that should be used to log stuff within the various middlewares

func WithPostStreamInterceptor

func WithPostStreamInterceptor(interceptor grpc.StreamServerInterceptor) ServerOption

WithPostStreamInterceptor option can be used to add your own `grpc.StreamServerInterceptor` after all others defined automatically by the package.

func WithPostUnaryInterceptor

func WithPostUnaryInterceptor(interceptor grpc.UnaryServerInterceptor) ServerOption

WithPostUnaryInterceptor option can be used to add your own `grpc.UnaryServerInterceptor` after all others defined automatically by the package.