grpcutils

README

gprcutils

Provides handy functions that help setting up a new GRPC Server extremely simple.

Example

The example below sets up a GRPC server with the following options enabled:

• mutual TLS or server side TLS
• zerolog GRPC server interceptor
• client and server keepalive setup
• OpenCensus basic metrics (rpc counts)
• OpenCensus zpages handler for viewing metrics
• OpenTelemetry default tracer with export to opentelemetry collector with support for end-to-end remote traces.

import (
  "google.golang.org/grpc/keepalive"
  "github.com/althk/goeasy/grpcutils"
)

func main() {
  var tlsConfig = &grpcutils.TLSConfig{
    CertFilePath:     "path/to/crt",
    KeyFilePath:      "path/to/key",
    ClientCAFilePath: "path/to/clientca.crt",
    RootCAFilePath:   "path/to/rootca.crt",
    SkipTLS:          false, // Setting this to true returns grpc.Server with Insecure creds
    NoClientCert:     false, // Setting this to true turns off mutual TLS auth and does only server auth
  }

  var kaConfig = &grpcutils.KeepAliveConfig{
    KASP:          keepalive.ServerParameters{},  // Skipping this or sending the empty struct will initialize with default values
    KACP:          keepalive.ClientParameters{}, // Skipping this or sending the empty struct will initialize with default values
    KAEP:          keepalive.EnforcementPolicy{}, // Skipping this or sending the empty struct will initialize with default values
    SkipKeepAlive: false,  // Setting this to true skips KeepAlive
  }

  var grpcConfig = &grpcutils.GRPCServerConfig{
    TLSConfig:        tlsConfig,
    SkipReflection:   false,
    SkipHealthServer: false,
    SkipZPages:       false,
    ZPagesAddr:       "localhost:5555",
    KeepAliveConfig: kaConfig,
  }

  grpcServer, err := grpcConfig.NewGRPCServer()
  if err != nil {
    // handle error
  }
  // register your service with grpcServer
  pb.RegisterMyServiceServer(grpcServer, *myServiceServer)

  // start an OpenTelemetry Tracer
  // this will export the traces to an OpenTelemetry Collector server running at
  // otelcollector1:4317
  tp, err := grpcutils.OTelTraceProvider("my-service-name", "otelcollector1:4317")
  if err != nil {
    // handle error
  }
  defer func() {
    if err := tp.Shutdown(context.Background()); err != nil {
     log.Printf("Error shutting down tracer provider: %v", err)
    }
  }()
}

Documentation

Overview

	grpcServer, err := grpcConfig.NewGRPCServer()
	if err != nil {
		// handle error
	}
	// register your service with grpcServer
	pb.RegisterMyServiceServer(grpcServer, *myServiceServer)
	// start an OpenTelemetry Tracer
	tp, err := grpcutils.OTelTraceProvider("my-service-name", "otelcollector1:4317")
	if err != nil {
		// handle error
	}
	defer func() {
		if err := shutdownFn(context.Background()); err != nil {
			log.Printf("Error shutting down tracer provider: %v", err)
		}
	}()
}

Index

• Variables
• func InterceptorLogger(l zerolog.Logger) logging.Logger
• func OTelTraceProvider(svcName, otelCollectorAddr string) (*sdktrace.TracerProvider, error)
• type GRPCServerConfig
  • func (g *GRPCServerConfig) GetGRPCDialOpts() ([]grpc.DialOption, error)
  • func (g *GRPCServerConfig) GetGRPCServerOpts() ([]grpc.ServerOption, error)
  • func (g *GRPCServerConfig) NewGRPCServer() (*grpc.Server, error)
• type KeepAliveConfig
• type TLSConfig
  • func (c *TLSConfig) Creds() (credentials.TransportCredentials, error)

Variables

var DefaultKACP = keepalive.ClientParameters{
	Time:                8 * time.Second,
	Timeout:             2 * time.Second,
	PermitWithoutStream: true,
}

var DefaultKAEP = keepalive.EnforcementPolicy{
	MinTime:             5 * time.Second,
	PermitWithoutStream: true,
}

var DefaultKASP = keepalive.ServerParameters{
	MaxConnectionIdle:     15 * time.Second,
	MaxConnectionAge:      30 * time.Second,
	MaxConnectionAgeGrace: 5 * time.Second,
	Time:                  5 * time.Second,
	Timeout:               2 * time.Second,
}

Functions

func InterceptorLogger

func InterceptorLogger(l zerolog.Logger) logging.Logger

InterceptorLogger adapts zerolog logger to interceptor logger.

func OTelTraceProvider

func OTelTraceProvider(svcName, otelCollectorAddr string) (*sdktrace.TracerProvider, error)

Types

type GRPCServerConfig

type GRPCServerConfig struct {
	*TLSConfig
	SkipReflection   bool
	SkipHealthServer bool
	SkipZPages       bool
	ZPagesAddr       string
	*KeepAliveConfig
}

GRPCServerConfig is used to define the configuration for a new GRPC server.

func (*GRPCServerConfig) GetGRPCDialOpts

func (g *GRPCServerConfig) GetGRPCDialOpts() ([]grpc.DialOption, error)

func (*GRPCServerConfig) GetGRPCServerOpts

func (g *GRPCServerConfig) GetGRPCServerOpts() ([]grpc.ServerOption, error)

func (*GRPCServerConfig) NewGRPCServer

func (g *GRPCServerConfig) NewGRPCServer() (*grpc.Server, error)

type KeepAliveConfig

type KeepAliveConfig struct {
	KASP          keepalive.ServerParameters
	KACP          keepalive.ClientParameters
	KAEP          keepalive.EnforcementPolicy
	SkipKeepAlive bool
}

type TLSConfig

type TLSConfig struct {
	CertFilePath     string
	KeyFilePath      string
	ClientCAFilePath string
	RootCAFilePath   string
	SkipTLS          bool
	NoClientCert     bool
}

func (*TLSConfig) Creds

func (c *TLSConfig) Creds() (credentials.TransportCredentials, error)