gogrpcservice

README

go-grpc-service

Optionated base service for gRPC (and HTTP) server implementations in golang using google.golang.org/grpc.

The main additional benefits of this base service include:

• Centralized and extensible hook system for configuring services
• Support for gRPC method reflection, e.g. custom proto method options are injected to the method context via interceptors (see the sample service)
• Unified logging and setup
• Boilerplate code for dialing other gRPC services provided
• Abstraction layer around health checking for gRPC and HTTP

Usage as a library

import "github.com/romnnn/go-grpc-service"

For a full example, check out the sample service in examples/:

# check out the sample GRPC service
go run github.com/romnnn/go-grpc-service/examples/sample-grpc-service --port 8080
# check out the sample HTTP service
go run github.com/romnnn/go-grpc-service/examples/sample-http-service --port 8080
# check out the sample JWT authentication GRPC service
go run github.com/romnnn/go-grpc-service/examples/sample-auth-service --port 8080 --generate

References

• Set the logging format for HTTP services:

  s.Service.SetLogFormat(&log.JSONFormatter{
  	TimestampFormat: time.RFC3339,
  })
  

Development

Prerequisites

Before you get started, make sure you have installed the following tools::

$ python3 -m pip install -U cookiecutter>=1.4.0
$ python3 -m pip install pre-commit bump2version invoke ruamel.yaml halo
$ go get -u golang.org/x/tools/cmd/goimports
$ go get -u golang.org/x/lint/golint
$ go get -u github.com/fzipp/gocyclo
$ go get -u github.com/mitchellh/gox  # if you want to test building on different architectures

Remember: To be able to excecute the tools downloaded with go get, make sure to include $GOPATH/bin in your $PATH. If echo $GOPATH does not give you a path make sure to run (export GOPATH="$HOME/go" to set it). In order for your changes to persist, do not forget to add these to your shells .bashrc.

With the tools in place, it is strongly advised to install the git commit hooks to make sure checks are passing in CI:

invoke install-hooks

You can check if all checks pass at any time:

invoke pre-commit

Note for Maintainers: After merging changes, tag your commits with a new version and push to GitHub to create a release:

bump2version (major | minor | patch)
git push --follow-tags

If you want to (re-)generate the sample grpc service, make sure to install protoc, protoc-gen-go and protoc-gen-go-grpc. You can then use the provided script:

apt install -y protobuf-compiler
go install google.golang.org/protobuf/cmd/protoc-gen-go
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc
invoke compile-proto

Note

This project is still in the alpha stage and should not be considered production ready.

Documentation

Index

• Constants
• Variables
• type BootstrapGrpcOptions
• type DialOptions
• type GrpcMethodName
• type Service
  • func (bs *Service) Bootstrap(cliCtx *cli.Context) error
  • func (bs *Service) BootstrapGrpc(ctx context.Context, cliCtx *cli.Context, opts *BootstrapGrpcOptions) error
  • func (bs *Service) BootstrapHTTP(ctx context.Context, cliCtx *cli.Context, handler *echo.Echo, ...) error
  • func (bs *Service) ConfigureLogging(cliCtx *cli.Context)
  • func (bs *Service) ConfigureTracing(cliCtx *cli.Context) (io.Closer, error)
  • func (bs *Service) Connect(cliCtx *cli.Context) error
  • func (bs *Service) Dial(ctx context.Context, host string, port uint, opts *DialOptions) (*grpc.ClientConn, error)
  • func (bs *Service) GracefulStop()
  • func (bs *Service) ServeGrpc(listener net.Listener) error
  • func (bs *Service) SetHealthy(healthy bool)
  • func (bs *Service) SetLogFormat(format logrus.Formatter)
  • func (bs *Service) SetLogLevel(level logrus.Level)
  • func (bs *Service) SetupGrpcHealthCheck(ctx context.Context)
  • func (bs *Service) SetupHTTPHealthCheck(ctx context.Context, handler *echo.Echo, url string)
• type WrappedServerStream
  • func WrapServerStream(stream grpc.ServerStream) *WrappedServerStream
  • func (w *WrappedServerStream) Context() context.Context

Constants

const Version = "0.0.9"

Version is incremented using bump2version

Variables

var (
	// GrpcMethodDescriptor ...
	GrpcMethodDescriptor = grpcMethodDescriptor("methodDesc")

	// NotReady ...
	NotReady = status.Error(codes.Unavailable, "the service is currently unavailable")
)

Types

type BootstrapGrpcOptions

type BootstrapGrpcOptions struct {
	USI grpc.UnaryServerInterceptor
	SSI grpc.StreamServerInterceptor
}

BootstrapGrpcOptions ...

type DialOptions

type DialOptions struct {
	TimeoutSec int
}

DialOptions ...

type GrpcMethodName

type GrpcMethodName string

GrpcMethodName ...

type Service

type Service struct {
	Name         string
	Version      string
	BuildTime    string
	Echo         *echo.Echo
	HTTPServer   *http.Server
	GrpcServer   *grpc.Server
	Health       *health.Server
	TracerCloser io.Closer
	Ready        bool
	Healthy      bool

	// Hooks
	PostBootstrapHook func(bs *Service) error
	ConnectHook       func(bs *Service) error

	// Configuration
	HTTPHealthCheckURL string
	// contains filtered or unexported fields
}

Service ...

func (*Service) Bootstrap

func (bs *Service) Bootstrap(cliCtx *cli.Context) error

Bootstrap ...

func (*Service) BootstrapGrpc

func (bs *Service) BootstrapGrpc(ctx context.Context, cliCtx *cli.Context, opts *BootstrapGrpcOptions) error

BootstrapGrpc prepares a grpc service

func (*Service) BootstrapHTTP

func (bs *Service) BootstrapHTTP(ctx context.Context, cliCtx *cli.Context, handler *echo.Echo, mws []echo.MiddlewareFunc) error

BootstrapHTTP prepares an http service

func (*Service) ConfigureLogging

func (bs *Service) ConfigureLogging(cliCtx *cli.Context)

ConfigureLogging ...

func (*Service) ConfigureTracing

func (bs *Service) ConfigureTracing(cliCtx *cli.Context) (io.Closer, error)

ConfigureTracing ...

func (*Service) Connect

func (bs *Service) Connect(cliCtx *cli.Context) error

Connect connects to databases and other services

func (*Service) Dial

func (bs *Service) Dial(ctx context.Context, host string, port uint, opts *DialOptions) (*grpc.ClientConn, error)

Dial connects to an external GRPC service

func (*Service) GracefulStop

func (bs *Service) GracefulStop()

GracefulStop ...

func (*Service) ServeGrpc

func (bs *Service) ServeGrpc(listener net.Listener) error

ServeGrpc prepares an http service

func (*Service) SetHealthy

func (bs *Service) SetHealthy(healthy bool)

SetHealthy ...

func (*Service) SetLogFormat

func (bs *Service) SetLogFormat(format logrus.Formatter)

SetLogFormat ...

func (*Service) SetLogLevel

func (bs *Service) SetLogLevel(level logrus.Level)

SetLogLevel ...

func (*Service) SetupGrpcHealthCheck

func (bs *Service) SetupGrpcHealthCheck(ctx context.Context)

SetupGrpcHealthCheck ...

func (*Service) SetupHTTPHealthCheck

func (bs *Service) SetupHTTPHealthCheck(ctx context.Context, handler *echo.Echo, url string)

SetupHTTPHealthCheck ...

type WrappedServerStream

type WrappedServerStream struct {
	grpc.ServerStream
	// WrappedContext is the wrapper's own Context. You can assign it.
	WrappedContext context.Context
}

WrappedServerStream is a thin wrapper around grpc.ServerStream that allows modifying context.

func WrapServerStream

func WrapServerStream(stream grpc.ServerStream) *WrappedServerStream

WrapServerStream returns a ServerStream that has the ability to overwrite context.

func (*WrappedServerStream) Context

func (w *WrappedServerStream) Context() context.Context

Context returns the wrapper's WrappedContext, overwriting the nested grpc.ServerStream.Context()