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 Finisher
• 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 WithGinOptions(options ...gin.OptionFunc) HTTPOption
  • func WithGlobalMiddleware(middleware ...gin.HandlerFunc) HTTPOption
  • func WithHTTPListeningAddress(addr string) HTTPOption
  • func WithMetricsAggregation() 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 WithFinisher(cb Finisher, handledSigs ...os.Signal) 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 Finisher

type Finisher func(sig os.Signal)

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 WithGinOptions

func WithGinOptions(options ...gin.OptionFunc) HTTPOption

WithGinOptions sets Gin router options.

func WithGlobalMiddleware

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

WithGlobalMiddleware adds new global middleware to the HTTP server default - metrics, logging and recovery (in this order).

func WithHTTPListeningAddress

func WithHTTPListeningAddress(addr string) HTTPOption

WithHTTPListeningAddress configures the HTTP server's listening address.

func WithMetricsAggregation

func WithMetricsAggregation() HTTPOption

WithMetricsAggregation enables path aggregation of endpoint. For example when using asterisk (*) in path and endpoint unpacks all possible values it will aggregate it back to asterisk (*).

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 error at runtime. Use with care.

func WithoutLoggingMiddleware

func WithoutLoggingMiddleware() HTTPOption

WithoutLoggingMiddleware disables logging middleware for the HTTP handler.

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 WithFinisher

func WithFinisher(cb Finisher, handledSigs ...os.Signal) Option

WithFinisher adds a callback to be called for various signals (SIGINT, SIGTERM by default) which can be optionally set.

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)