grpc

Documentation

Index

• Variables
• func CloseServer(listener net.Listener, server *grpc.Server)
• func NewHealthServer(depsCheck *DepsCheck, watchInterval time.Duration) healthpb.HealthServer
• func StartServer(port int) (net.Listener, *grpc.Server, error)
• func TimestampOptional(src *time.Time) *timestamppb.Timestamp
• type ConnPool
  • func NewConnPool() ConnPool
• type DepCheckCallbacks
• type DepCheckServices
• type DepsCheck
• type ErrorHandler
  • func HandleError(defaultCode codes.Code) ErrorHandler
• type ExecService
  • func ServiceWithMetrics[In any, Out any](name string, service ExecService[In, Out], logger adapters.GRPC) ExecService[In, Out]
• type ProtoConverter
  • func NewProtoConverter[Proto comparable, Entity comparable](mapper ProtoMapper[Proto, Entity], protoDefault Proto, entityDefault Entity) ProtoConverter[Proto, Entity]
• type ProtoMapper
• type Protocol
  • func (p *Protocol) WithAddr(host string) string

Variables

var ErrConnectionPoolClosed = errors.New("connection pool is closed")

var ErrPortRequired = errors.New("port is required")

var NewTokenSource = idtoken.NewTokenSource

NewTokenSource helps to mock token source, otherwise tests would need to rely on actual Google Cloud credentials.

var SortDirectionConverter = NewProtoConverter[commonv1.SortDirection, database.SortDirection](
	ProtoMapper[commonv1.SortDirection, database.SortDirection]{
		commonv1.SortDirection_SORT_DIRECTION_ASC:  database.SortDirectionAsc,
		commonv1.SortDirection_SORT_DIRECTION_DESC: database.SortDirectionDesc,
	},
	commonv1.SortDirection_SORT_DIRECTION_UNSPECIFIED,
	database.SortDirectionNone,
)

var SystemCertPool = x509.SystemCertPool

SystemCertPool helps to mock the default behavior to retrieve system certificates. We do this because Go's implementation is OS specific.

Functions

func CloseServer

func CloseServer(listener net.Listener, server *grpc.Server)

CloseServer closes an existing GRPC server.

func NewHealthServer

func NewHealthServer(depsCheck *DepsCheck, watchInterval time.Duration) healthpb.HealthServer

func StartServer

func StartServer(port int) (net.Listener, *grpc.Server, error)

StartServer starts a new GRPC server on the specified port.

You must ensure to properly close the server when you are done, using the CloseGRPCServer method.

listener, server := deploy.StartGRPCServer(50051)
// Graceful shutdown.
defer deploy.CloseGRPCServer(listener, server)

func TimestampOptional

func TimestampOptional(src *time.Time) *timestamppb.Timestamp

Types

type ConnPool

type ConnPool interface {
	// Close terminates all connections in the pool. Use this method for graceful shutdowns.
	Close()
	// Open opens a new connection to an existing GRPC service.
	// This method automatically handles authentication under GCP environments.
	Open(host string, port int, protocol Protocol) (*grpc.ClientConn, error)
}

ConnPool manages client connections to GRPC services. It is thread-safe, and should be shared for opening connections to different services.

func NewConnPool

func NewConnPool() ConnPool

NewConnPool creates a new connection pool for GRPC services.

type DepCheckCallbacks

type DepCheckCallbacks map[string]func() error

DepCheckCallbacks is a function that checks the health of a list of dependencies, and return an error for any failed dependency.

This map must contain every dependency. Healthy dependencies must be associated to a nil error value.

type DepCheckServices

type DepCheckServices map[string][]string

DepCheckServices lists dependencies for each GRPC service. When healthcheck is triggered, a GRPC service will be marked as healthy only if every single one of its dependencies is also healthy.

You should only list RPC services here. The generic health (empty key) is automatically handled by the system.

type DepsCheck

type DepsCheck struct {
	Dependencies DepCheckCallbacks
	Services     DepCheckServices
}

DepsCheck configures a health checker for a GRPC service. This healthcheck is run periodically, and will prevent faulty calls to unhealthy services.

type ErrorHandler

type ErrorHandler interface {
	Is(target error, code codes.Code) ErrorHandler
	IsW(target error, code codes.Code, wrap error) ErrorHandler
	IsWF(target error, code codes.Code, format string, args ...interface{}) ErrorHandler

	As(target interface{}, code codes.Code) ErrorHandler
	AsW(target interface{}, code codes.Code, wrap error) ErrorHandler
	AsWF(target interface{}, code codes.Code, format string, args ...interface{}) ErrorHandler

	Test(caseFn func(initialErr error) (err error, ok bool)) ErrorHandler

	Handle(err error) error
}

func HandleError

func HandleError(defaultCode codes.Code) ErrorHandler

HandleError creates a new error handler. You can define different case depending on the error you want to handle. This handler is thread safe, and a single handler can be shared between multiple goroutines.

type ExecService

type ExecService[In any, Out any] interface {
	Exec(ctx context.Context, data In) (Out, error)
}

func ServiceWithMetrics

func ServiceWithMetrics[In any, Out any](
	name string, service ExecService[In, Out], logger adapters.GRPC,
) ExecService[In, Out]

type ProtoConverter

type ProtoConverter[Proto comparable, Entity comparable] interface {
	ToProto(src Entity) Proto
	FromProto(src Proto) Entity
}

func NewProtoConverter

func NewProtoConverter[Proto comparable, Entity comparable](
	mapper ProtoMapper[Proto, Entity],
	protoDefault Proto,
	entityDefault Entity,
) ProtoConverter[Proto, Entity]

type ProtoMapper

type ProtoMapper[Proto comparable, Entity comparable] map[Proto]Entity

type Protocol

type Protocol string

const (
	ProtocolHTTP  Protocol = "http"
	ProtocolHTTPS Protocol = "https"
)

func (*Protocol) WithAddr

func (p *Protocol) WithAddr(host string) string