grpc

Documentation

Overview

Package grpc implements a smart wrapper over the grpc ecosystem.

It provides bootstrapping for launching a production ready grpc server alongside a grpc gateway server.

It also wraps the most common grpc parameters used in the company in the options.

Index

• Variables
• func HandleError(targetErr error, errorHandler ErrorHandler) error
• type ErrorHandler
• type MonitorOperationer
• type PanicHandler
• type Server
  • func NewServer(opt ...ServerOption) (*Server, error)
  • func (s *Server) Close() error
  • func (s *Server) ListenAndServe() error
• type ServerOption
  • func WithAddress(a string) ServerOption
  • func WithDebug(logger *zap.Logger, logRequest bool, ignoredMethods ...string) ServerOption
  • func WithDebugStandardLibraryEndpoints() ServerOption
  • func WithErrorHandler(errorHandler ErrorHandler) ServerOption
  • func WithGRPCListener(lis net.Listener) ServerOption
  • func WithGRPCServerOptions(opts []grpc.ServerOption) ServerOption
  • func WithGatewayCorsOptions(opts cors.Options) ServerOption
  • func WithHTTPMiddlewares(mw chi.Middlewares) ServerOption
  • func WithHTTPRoute(method, path string, handler http.HandlerFunc) ServerOption
  • func WithMonitorOperationer(monitorOperationer MonitorOperationer) ServerOption
  • func WithMuxOptions(opts []runtime.ServeMuxOption) ServerOption
  • func WithNoGateway() ServerOption
  • func WithOTEL(handlerOptions ...otelgrpc.Option) ServerOption
  • func WithPanicHandler(panicHandler PanicHandler) ServerOption
  • func WithRegisterGatewayFunc(f registerGatewayFunc) ServerOption
  • func WithRegisterServerFunc(f registerServerFunc) ServerOption
  • func WithTracing() ServerOption
  • func WithUnaryServerInterceptor(unaryInterceptor grpc.UnaryServerInterceptor) ServerOption
  • func WithUnaryServerInterceptorAuthFunc(authFunc grpcauth.AuthFunc) ServerOption
  • func WithUnaryServerInterceptorCodeGen() ServerOption
  • func WithUnaryServerInterceptorContextPropagation() ServerOption
  • func WithUnaryServerInterceptorLogger(logger *zap.Logger) ServerOption
  • func WithUnaryServerInterceptorRecovery(recoveryHandler grpcrecovery.RecoveryHandlerFunc) ServerOption

Variables

var ErrServerClosed = errors.New("go-commons.grpc: server closed")

ErrServerClosed indicates that the operation is now illegal because of the server has been closed.

Functions

func HandleError

func HandleError(
	targetErr error,
	errorHandler ErrorHandler,
) error

HandleError proposes a way of handling GRPC errors. It logs and reports the error to an external service, everything under a one-second timeout to avoid increasing the response time. nolint: gocognit // high cognitive complexity, fix later.

Types

type ErrorHandler

type ErrorHandler interface {
	LogError(error)
	IsApplicationError(error) bool
	ReportError(context.Context, error) error
	ErrorToGRPCStatus(error) (*status.Status, error)
}

ErrorHandler defines methods for handling an error.

type MonitorOperationer

type MonitorOperationer interface {
	MonitorOperation(
		ctx context.Context,
		name string,
		traceID [16]byte,
		operationFunc func(context.Context),
	)
}

MonitorOperationer defines.

type PanicHandler

type PanicHandler interface {
	ReportPanic(context.Context, any) error
	LogPanic(any)
	LogError(error)
}

PanicHandler defines methods for handling a panic.

type Server

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

Server holds the grpc and gateway underlying servers. It starts and stops both of them together. In case one of the server fails the other one is closed.

func NewServer

func NewServer(opt ...ServerOption) (*Server, error)

NewServer creates Server with both the grpc server and, if it's the case, the gateway server.

The servers have not started to accept requests yet.

func (*Server) Close

func (s *Server) Close() error

Close closes both underlying servers. Safe to use concurrently and can be called multiple times.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts accepting incoming connections on both servers. If one of the servers encounters an error, both are stopped.

type ServerOption

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

A ServerOption sets options such as credentials, codec and keepalive parameters, etc.

The main purpose of Options in this package is to wrap the most common grpc parameter used in the company in order to provide the developers with a single point of entry for configuring different projects grpc servers.

func WithAddress

func WithAddress(a string) ServerOption

WithAddress configures the Server to listen to the given address in case of the Gateway server. And in case of the grpc server it uses the same address but port-1.

func WithDebug

func WithDebug(logger *zap.Logger, logRequest bool, ignoredMethods ...string) ServerOption

WithDebug enables logging for the servers.

func WithDebugStandardLibraryEndpoints

func WithDebugStandardLibraryEndpoints() ServerOption

WithDebugStandardLibraryEndpoints registers the debug routes from the standard library to the gateway.

func WithErrorHandler

func WithErrorHandler(errorHandler ErrorHandler) ServerOption

WithErrorHandler adds an interceptor to the GRPC server that intercepts and handles the error returned by the handler.

func WithGRPCListener

func WithGRPCListener(lis net.Listener) ServerOption

WithGRPCListener configures the GRPC server to use the given net.Listener instead of configuring an address. ! Prefer to use this only in testing.

func WithGRPCServerOptions

func WithGRPCServerOptions(opts []grpc.ServerOption) ServerOption

WithGRPCServerOptions configures the grpc server to use the given grpc server options.

func WithGatewayCorsOptions

func WithGatewayCorsOptions(opts cors.Options) ServerOption

WithGatewayCorsOptions sets the options to be used with CORS for the gateway server.

func WithHTTPMiddlewares

func WithHTTPMiddlewares(mw chi.Middlewares) ServerOption

WithHTTPMiddlewares configures the Gateway Server http handler to use the provided middlewares.

func WithHTTPRoute

func WithHTTPRoute(method, path string, handler http.HandlerFunc) ServerOption

WithHTTPRoute registers a new http route to the gateway server.

func WithMonitorOperationer

func WithMonitorOperationer(
	monitorOperationer MonitorOperationer,
) ServerOption

WithMonitorOperationer adds an interceptor to the GRPC server that instruments the grpc handler.

func WithMuxOptions

func WithMuxOptions(opts []runtime.ServeMuxOption) ServerOption

WithMuxOptions configures the underlying runtime.ServeMux of the Gateway Server. The ServeMux as a handler for the http server.

func WithNoGateway

func WithNoGateway() ServerOption

WithNoGateway disables the gateway server. ! Prefer to use this only in testing.

func WithOTEL

func WithOTEL(handlerOptions ...otelgrpc.Option) ServerOption

WithOTEL adds the OpenTelemetry instrumentation to the GRPC server.

func WithPanicHandler

func WithPanicHandler(panicHandler PanicHandler) ServerOption

WithPanicHandler adds an interceptor to the GRPC server that intercepts and handles panics.

func WithRegisterGatewayFunc

func WithRegisterGatewayFunc(f registerGatewayFunc) ServerOption

WithRegisterGatewayFunc registers a GRPC service to the Gateway server.

func WithRegisterServerFunc

func WithRegisterServerFunc(f registerServerFunc) ServerOption

WithRegisterServerFunc registers a GRPC service to the GRPC server.

func WithTracing

func WithTracing() ServerOption

WithTracing enables tracing for both servers.

func WithUnaryServerInterceptor

func WithUnaryServerInterceptor(
	unaryInterceptor grpc.UnaryServerInterceptor,
) ServerOption

WithUnaryServerInterceptor adds an interceptor to the GRPC server.

func WithUnaryServerInterceptorAuthFunc

func WithUnaryServerInterceptorAuthFunc(
	authFunc grpcauth.AuthFunc,
) ServerOption

WithUnaryServerInterceptorAuthFunc adds an interceptor to the GRPC server that executes a per-request auth.

func WithUnaryServerInterceptorCodeGen

func WithUnaryServerInterceptorCodeGen() ServerOption

WithUnaryServerInterceptorCodeGen adds an interceptor to the GRPC server that exports log fields from requests.

func WithUnaryServerInterceptorContextPropagation

func WithUnaryServerInterceptorContextPropagation() ServerOption

WithUnaryServerInterceptorContextPropagation adds an interceptor to the GRPC server that binds the received metadata on the incoming context to the outgoing context.

func WithUnaryServerInterceptorLogger

func WithUnaryServerInterceptorLogger(logger *zap.Logger) ServerOption

WithUnaryServerInterceptorLogger adds an interceptor to the GRPC server that adds the given zap.Logger to the context.

func WithUnaryServerInterceptorRecovery

func WithUnaryServerInterceptorRecovery(
	recoveryHandler grpcrecovery.RecoveryHandlerFunc,
) ServerOption

WithUnaryServerInterceptorRecovery adds an interceptor to the GRPC server that recovers from panics.