cadre

README

Cadre

Cadre is a strongly opinionated library intended to removed boilerplate code from a modern Go application supporting gRPC and HTTP. It has been build for internal projects needs at ModernTV.

Cadre makes it easy to create and application with gRPC and/or HTTP interface. It provides prometheus metrics and application status endpoints, debugging tools, logging and various gRPC utils.

Cadre tries to be flexible but enforces several libraries:

• logging - zerolog
• http server - gin

See _examples folder for usage details.

Disclaimer

Cadre is not production ready. It is under heavy development and its API can be changed at any time.

Why Cadre?

Cadre

Documentation

Index

• type Builder
  • func NewBuilder(name string, options ...Option) (b *Builder, err error)
  • func (b *Builder) Build() (c *cadre, err error)
• type Cadre
• type GRPCOption
  • func WithChannelzListeningAddress(listenAddr string) GRPCOption
  • func WithGRPCListeningAddress(addr string) GRPCOption
  • func WithGRPCMultiplex() GRPCOption
  • func WithLoggingOptions(opts []grpc_zerolog.Option) GRPCOption
  • func WithRecoveryOptions(opts []grpc_recovery.Option) GRPCOption
  • func WithService(name string, registrator ServiceRegistrator) GRPCOption
  • func WithStreamInterceptors(streamInterceptors ...grpc.StreamServerInterceptor) GRPCOption
  • func WithUnaryInterceptors(unaryInterceptors ...grpc.UnaryServerInterceptor) GRPCOption
  • func WithoutChannelz() GRPCOption
  • func WithoutLogging() GRPCOption
  • func WithoutRecovery() GRPCOption
  • func WithoutReflection() GRPCOption
• type HTTPOption
  • func WithGlobalMiddleware(middlware ...gin.HandlerFunc) HTTPOption
  • func WithHTTPListeningAddress(addr string) HTTPOption
  • func WithRoute(method, path string, handlers ...gin.HandlerFunc) HTTPOption
  • func WithRoutingGroup(group http.RoutingGroup) HTTPOption
• type Option
  • func WithContext(ctx context.Context) Option
  • func WithGRPC(grpcOptions ...GRPCOption) Option
  • func WithHTTP(httpOptions ...HTTPOption) Option
  • func WithLogger(logger *zerolog.Logger) Option
  • func WithMetrics(metrics *metrics.Registry) Option
  • func WithPrometheus(registry *prometheus.Registry) Option
  • func WithPrometheusListeningAddress(serverListeningAddress string) Option
  • func WithStatus(status *status.Status) Option
• type Service
• type ServiceRegistrator

Types

type Builder

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

func NewBuilder

func NewBuilder(name string, options ...Option) (b *Builder, err error)

NewBuilder creates a new Builder instance and allows the user to configure the Cadre server by various options

func (*Builder) Build

func (b *Builder) Build() (c *cadre, err error)

Build validates the Builder's configuration and creates a new Cadre server

type Cadre

type Cadre interface {
	Start() error
	Shutdown() error
}

type GRPCOption

type GRPCOption func(*grpcOptions) error

func WithChannelzListeningAddress

func WithChannelzListeningAddress(listenAddr string) GRPCOption

WithChannelzListeningAddress configures the channelz's listening address

func WithGRPCListeningAddress

func WithGRPCListeningAddress(addr string) GRPCOption

WithGRPCListeningAddress configures gRPC's standalone server's listening address

func WithGRPCMultiplex

func WithGRPCMultiplex() GRPCOption

WithGRPCMultiplex configures Cadre to multiplex grpc and http on the same port

func WithLoggingOptions

func WithLoggingOptions(opts []grpc_zerolog.Option) GRPCOption

func WithRecoveryOptions

func WithRecoveryOptions(opts []grpc_recovery.Option) GRPCOption

WithRecoveryOptions configures gRPC's recovery middleware with custom options

func WithService

func WithService(name string, registrator ServiceRegistrator) GRPCOption

WithService registers a new gRPC service to the Cadre's gRPC server

func WithStreamInterceptors

func WithStreamInterceptors(streamInterceptors ...grpc.StreamServerInterceptor) GRPCOption

WithStreamInterceptors adds custom grpc stream interceptor(s) to the end of the interceptor chain default order (if not disabled) - ctxtags, logging, recovery, metrics

func WithUnaryInterceptors

func WithUnaryInterceptors(unaryInterceptors ...grpc.UnaryServerInterceptor) GRPCOption

WithUnaryInterceptors adds custom grpc unary interceptor(s) to the end of the interceptor chain default order (if not disabled) - ctxtags, logging, recovery, metrics

func WithoutChannelz

func WithoutChannelz() GRPCOption

WithoutChannelz disables gRPC's channelz http server

func WithoutLogging

func WithoutLogging() GRPCOption

WithoutLogging disables logging middleware - default on

func WithoutRecovery

func WithoutRecovery() GRPCOption

WithoutRecovery disables gRPC's recovery middleware

func WithoutReflection

func WithoutReflection() GRPCOption

WithoutReflection disables gRPC's reflection service - default on

type HTTPOption

type HTTPOption func(*httpOptions) error

func WithGlobalMiddleware

func WithGlobalMiddleware(middlware ...gin.HandlerFunc) HTTPOption

WithGlobalMiddleware adds new global middleware to the HTTP server default - metrics, recovery and logging

func WithHTTPListeningAddress

func WithHTTPListeningAddress(addr string) HTTPOption

WithHTTPListeningAddress configures the HTTP server's listening address

func WithRoute

func WithRoute(method, path string, handlers ...gin.HandlerFunc) HTTPOption

WithRoute adds new route to the HTTP server returns an error if the path-method combo is already registered

func WithRoutingGroup

func WithRoutingGroup(group http.RoutingGroup) HTTPOption

WithRoutingGroup adds a new routing group to the HTTP server may cause gin configuration eror at runtime. use with care

type Option

type Option func(*Builder) error

func WithContext

func WithContext(ctx context.Context) Option

WithContext supplies custom context for the cadre server. This is useful for graceful shutdown

func WithGRPC

func WithGRPC(grpcOptions ...GRPCOption) Option

WithGRPC configures cadre with a GRPC server

func WithHTTP

func WithHTTP(httpOptions ...HTTPOption) Option

WithHTTP enables HTTP server

func WithLogger

func WithLogger(logger *zerolog.Logger) Option

WithLogger allows configuring cadre with custom zerolog logger. If not used Cadre will be configured with zerolog.Nop()

func WithMetrics

func WithMetrics(metrics *metrics.Registry) Option

WithMetrics allows replacing the default metrics registry with a custom pre-configured one. If used, the prometheus registry from metrics Registry will replace the default prometheus registry. Do not use with WithPrometheus

func WithPrometheus

func WithPrometheus(registry *prometheus.Registry) Option

WithPrometheus configures cadre to use a specific prometheus registry. This prometheus registry will be used to create metrics registry.

func WithPrometheusListeningAddress

func WithPrometheusListeningAddress(serverListeningAddress string) Option

WithPrometheusListeningAddress is meant to configure cadre to use a separate http server for prometheus - useful for putting it behind firewall

func WithStatus

func WithStatus(status *status.Status) Option

WithStatus allows replacing the default status with a custom pre-configured one

type Service

type Service interface {
	Name() string
}

type ServiceRegistrator

type ServiceRegistrator func(*grpc.Server)