chassis

README

chassis

TODO: Write a project description

Testing

Be sure to run tests as:

go test -gcflags=-l -test.v ./...

# on ARM-based machines (e.g. Apple Silicon)
GOARCH=amd64 go test -gcflags=-l -test.v ./...

Mocks

Generate mocks using mockery:

mockery --all --inpackage --case underscore

Documentation

Index

• type CacheConfig
• type CheckConfig
• type ConsumerConfig
• type DaoLayerConfig
• type DatabaseConfig
• type EventConfig
• type GatewayLayerConfig
• type GrpcHandlers
• type HandlerLayerConfig
• type InitializeConfig
• type MainBuilder
  • func NewMainBuilder(mbc *MainBuilderConfig) MainBuilder
• type MainBuilderConfig
• type MessageBusConfig
• type SecretsConfig
• type ServiceLayerConfig

Types

type CacheConfig

type CacheConfig struct {
	// CacheAddress host of the cache instance
	CacheAddress string
	// CacheSecret the secret/password for the cache instance
	CacheSecret string
}

CacheConfig defines the configuration for the cache layer (only Redis is currently supported)

type CheckConfig

type CheckConfig struct {
	// Check is the check to perform.
	Check func(ctx *gin.Context)
}

CheckConfig specifies a configuration for use in readiness and wellness checks.

type ConsumerConfig

type ConsumerConfig struct {
	// Event is the event type to subscribe to
	Event protoreflect.ProtoMessage
	// Consumer is the callback function to execute when a message is received
	Consumer messagebus.Consumer
	// Duplicate indicates whether or not to duplicate messages to all replicas of the service. By default, this is false and messages are
	// load-balanced to a single replica of the service. If Duplicate is set to true, messages will instead be duplicated to each replica
	// of the service. This is useful in special cases where you need to ensure that all replicas of a service receive a message.
	Duplicate bool
	// IgnoreType states whether the subscribing consumer should ignore the event type when receiving messages. If true, the consumer
	// will receive all events that match Event.Source. If false, the consumer will only receive events that match both Event.Source and Event.Type.
	// Essentially this is a way to subscribe to all events of a certain aggregate type instead of a specific event type.
	IgnoreType bool
}

ConsumerConfig defines the configuration for a consumer handler (processing messages off of the messagebus)

type DaoLayerConfig

type DaoLayerConfig struct {
	// CreateDaoLayer creates the dao layer
	CreateDaoLayer func(b MainBuilder)
}

DaoLayerConfig defines the function for initializing the DAO layer if any custom setup is required

type DatabaseConfig

type DatabaseConfig struct {
	Databases []database.Client
}

DatabaseConfig defines the connection configuration to all databases

type EventConfig

type EventConfig struct{}

EventConfig defines the configuration for events

type GatewayLayerConfig

type GatewayLayerConfig struct {
	// CreateInternalClients creates the gateway layer using the client factory.
	CreateInternalClients func(b MainBuilder, clientFactory cf.ClientFactory) []*grpc.ClientConn
}

GatewayLayerConfig specifies how the gateway layer will be configured.

type GrpcHandlers

type GrpcHandlers struct {
	Desc    grpc.ServiceDesc
	Handler interface{}
}

type HandlerLayerConfig

type HandlerLayerConfig struct {
	// HttpPortConfigKey will only be used if DoNotRegisterService is true. It specifies the config key to read the port from.
	// ONLY USE THIS FOR THE REGISTRY SERVICE ITSELF OR IF YOU REALLY KNOW WHAT YOU'RE DOING.
	HttpPortConfigKey string
	// CreateRestHandlers creates the http restful interface using the gin-engine router. This needs to
	// be a function called from main.go so that it has both the service interfaces (
	// and access to mainbuilder attributes (e.g. the logger).
	CreateRestHandlers func(b MainBuilder)
	// GrpcPortConfigKey will only be used if DoNotRegisterService is true. It specifies the config key to read the port from.
	// ONLY USE THIS FOR THE REGISTRY SERVICE ITSELF OR IF YOU REALLY KNOW WHAT YOU'RE DOING.
	GrpcPortConfigKey string
	// CreateRpcHandlers creates the rpc interface using the grpc server. This needs to
	// be a function called from main.go so that it has both the service interfaces
	// and access to mainbuilder attributes (e.g. the logger).
	CreateRpcHandlers func(b MainBuilder) []GrpcHandlers
	// RpcOptions is a slice of optional grpc.ServerOption structs to set on the gRPC server.
	RpcOptions []grpc.ServerOption
	// CreateConsumers defines a function that creates the consumer interfaces on the messagebus.
	// This needs to be a function called from main.go so that it has both the service interfaces
	// and access to mainbuilder attributes (e.g. the logger).
	CreateConsumers func(b MainBuilder) []ConsumerConfig
}

HandlerLayerConfig specifies how the handler layer will be configured.

type InitializeConfig

type InitializeConfig struct {
	// BaseDirectory specifies the base directory from which to run the application.
	// This should only be used in local debugging.
	BaseDirectory string
	// LogFile specifies the file to print logs into.
	// This should only be used in local debugging.
	LogFile string
	// OnInitialize is called after the config and secrets have been initialized but prior to dao, service, and handler layers.
	OnInitialize func(b MainBuilder)
}

InitializeConfig defines the beginning configuration of the application such as the root directory, logfile, etc.

type MainBuilder

type MainBuilder interface {

	// Run starts the execution of the application.
	Run()
	// Close releases all assets. Call via defer.
	Close()

	// IsDevMode specifies if this application is running in development mode (true) or production mode (false)
	IsDevMode() bool
	// GetCacheClient gets the cache implementation client.
	GetCacheClient() *redis.Client
	// GetConfig exposes the viper configuration for the application.
	GetConfig() *viper.Viper
	// GetLogger exposes the logger the application is using.
	GetLogger() l.Logger
	// GetHttpRouter exposes the gin http router.
	GetHttpRouter() *gin.Engine
	// GetRegistryClient exposes the registry client.
	GetRegistryClient() rgpb.RegistryClient
	// GetRpcServer exposes the grpc server.
	GetRpcServer() *grpc.Server
	// GetSecretsClient exposes the secret vault client.
	GetSecretsClient() secrets.Client
	// GetEventManager... TODO
	GetEventManager() events.EventManager
	GetTelemetry() ct.Telemetry
	// contains filtered or unexported methods
}

MainBuilder is an interface that exposes the functionality for using the chassis module

func NewMainBuilder

func NewMainBuilder(mbc *MainBuilderConfig) MainBuilder

NewMainBuilder initializes the whole microservice application. Pass in the configuration for each layer and then call Run() to start the application.

type MainBuilderConfig

type MainBuilderConfig struct {
	// ApplicationName is the name of the application.
	ApplicationName string
	// Bool config variable that specifies whether the application is running in dev mode.
	// Defaults to "isDevMode" if not specified.
	IsDevModeVariable string
	// DoNotRegisterService specifies the service to register with the service registry.
	// Defaults to false if not specified. If you set this you must also set the server ports for both HTTP and RPC in the HandlerLayerConfig.
	//
	// ONLY SET THIS TO TRUE FOR THE REGISTRY SERVICE ITSELF OR IF YOU REALLY KNOW WHAT YOU'RE DOING.
	DoNotRegisterService bool
	// EventConfig is the event configuration.
	EventConfig *EventConfig
	// DaoLayerConfig is the dao layer configuration.
	DaoLayerConfig *DaoLayerConfig
	// DatabaseConfig is the `SQL` db configuatrion
	DatabaseConfig *DatabaseConfig
	// CacheConfig is the `Cache` configuatrion
	CacheConfig *CacheConfig
	// GatewayLayerConfig is the gateway layer configuration.
	GatewayLayerConfig *GatewayLayerConfig
	// ServiceLayerConfig is the service layer configuration.
	ServiceLayerConfig *ServiceLayerConfig
	// HandlerLayerConfig is the handler layer configuration.
	HandlerLayerConfig *HandlerLayerConfig
	// ReadinessCheckConfig is the readiness check configuration.
	ReadinessCheckConfig *CheckConfig
	// WellnessCheckConfig is the wellness check configuration.
	WellnessCheckConfig *CheckConfig
	// SecretsConfig is the secrets vault configuration.
	SecretsConfig *SecretsConfig
	// InitializeConfig is the configuration for initialize.
	InitializeConfig *InitializeConfig
	// MessageBusConfig is the configuration for connecting to the message bus.
	MessageBusConfig *MessageBusConfig
	// OnRun is called when MainBuilder.Run is called. DO NOT consume the calling thread.
	// It will be called after the configuration and logger have been initialized but before anything
	// else has been initialized.
	OnRun func(b MainBuilder)
	// OnStop is called when the application is closing.
	OnStop func(b MainBuilder)
}

MainBuilderConfig specifies each configuration for MainBuilder.

type MessageBusConfig

type MessageBusConfig struct {
	Buses []messagebus.Client
}

MessageBusConfig defines the service options for the messagebus module

type SecretsConfig

type SecretsConfig struct {
	Client secrets.Client
	// Required should return true if the secrets client must be initialized successfully and false otherwise.
	// A common usecase for this is to only require the secrets client if the application is running in production mode.
	// For that usecase, you can use the following:
	//
	//  func(b chassis.MainBuilder) bool { return !b.IsDevMode() }
	Required func(b MainBuilder) bool
}

SecretsConfig defines connection configuration for the secrets vault to be used by the application.

type ServiceLayerConfig

type ServiceLayerConfig struct {
	// CreateServiceLayer creates the service layer using the client factory.
	CreateServiceLayer func(b MainBuilder)
}

ServiceLayerConfig specifies how the service layer will be configured.