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 WithChannelz(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 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
  • func WithoutLoggingMiddleware() HTTPOption
  • func WithoutMetricsMiddleware() HTTPOption
• type Option
  • func WithContext(ctx context.Context) Option
  • func WithGRPC(grpcOptions ...GRPCOption) Option
  • func WithHTTP(serverName string, myHttpOptions ...HTTPOption) Option
  • func WithLogger(logger zerolog.Logger) Option
  • func WithMetricsListeningAddress(serverListeningAddress string) Option
  • func WithMetricsRegistry(metrics *metrics.Registry) Option
  • func WithPrometheusRegistry(registry *prometheus.Registry) Option
  • func WithStatus(status *status.Status) Option
  • func WithStatusListeningAddress(serverListeningAddress string) 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 WithChannelz

func WithChannelz(listenAddr string) GRPCOption

WithChannelz enables gRPC's channelz http server and configures its listening address if the listening address is left empty, it will use the default value (:8123)

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 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

func WithoutLoggingMiddleware

func WithoutLoggingMiddleware() HTTPOption

func WithoutMetricsMiddleware

func WithoutMetricsMiddleware() HTTPOption

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(serverName string, myHttpOptions ...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 WithMetricsListeningAddress

func WithMetricsListeningAddress(serverListeningAddress string) Option

WithPrometheusListeningAddress is meant to configure cadre to use a separate http server for prometheus - useful for putting it behind firewall Default is to use the first HTTP server's listening address merging them together. This may cause problems when a conflicting route is configured

func WithMetricsRegistry

func WithMetricsRegistry(metrics *metrics.Registry) Option

WithMetricsRegistry 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 WithPrometheusRegistry

func WithPrometheusRegistry

func WithPrometheusRegistry(registry *prometheus.Registry) Option

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

func WithStatus

func WithStatus(status *status.Status) Option

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

func WithStatusListeningAddress

func WithStatusListeningAddress(serverListeningAddress string) Option

WithStatusListeningAddress is meant to configure cadre to use a separate http server for status endpoint - useful for putting it behind firewall Default is to use the first HTTP server's listening address merging them together. This may cause problems when a conflicting route is configured

type Service

type Service interface {
	Name() string
}

type ServiceRegistrator

type ServiceRegistrator func(*grpc.Server)