brick

README

🧱 brick

Brick is a minimalistic opinionated web service unit suitable for microservice development.

Create a new app from brick-starter-kit.

WORK IN PROGRESS

Documentation

Overview

Package brick contains facades and configurations that are useful for a variety of apps.

Index

• func MakeCacheOf[V any](l interface{ ... }, name string, ttl time.Duration, ...) *cache.FailoverOf[V]
• func MountDevPortal(r chi.Router, l *BaseLocator)
• func NewBaseWebService(l *BaseLocator) *web.Service
• func Start(cfg WithBaseConfig, init func(docsMode bool) (*BaseLocator, http.Handler), ...)
• type BaseConfig
  • func (c *BaseConfig) Base() BaseConfig
• type BaseLocator
  • func NewBaseLocator(cfg BaseConfig) (*BaseLocator, error)
  • func NoOpLocator() *BaseLocator
  • func (l *BaseLocator) CacheInvalidationIndex() *cache.InvalidationIndex
  • func (l *BaseLocator) CacheTransfer() *cache.HTTPTransfer
  • func (l *BaseLocator) SetupDebugRouter()
  • func (l *BaseLocator) StartHTTPServer(handler http.Handler) (string, error)
  • func (l *BaseLocator) TransferCache(ctx context.Context) error
• type StartOptions
• type WithBaseConfig

Functions

func MakeCacheOf

func MakeCacheOf[V any](l interface {
	StatsTracker() stats.Tracker
	CtxdLogger() ctxd.Logger
}, name string, ttl time.Duration, options ...func(cfg *cache.FailoverConfigOf[V]),
) *cache.FailoverOf[V]

MakeCacheOf creates an instance of failover cache and adds it to cache transfer.

func MountDevPortal

func MountDevPortal(r chi.Router, l *BaseLocator)

MountDevPortal mounts debug handlers to router.

func NewBaseWebService

func NewBaseWebService(l *BaseLocator) *web.Service

NewBaseWebService initializes default http router.

func Start

func Start(cfg WithBaseConfig, init func(docsMode bool) (*BaseLocator, http.Handler), options ...func(o *StartOptions))

Start loads config and runs application with provided service locator and http router.

Types

type BaseConfig

type BaseConfig struct {
	// Initialized indicates zero/uninitialized value of the configuration.
	Initialized bool `default:"true"`

	Log zapctxd.Config `split_words:"true"`

	// Environment is the name of environment where application runs.
	Environment string `default:"dev"`

	// ServiceName is the name of the service to use in documentation and tracing.
	ServiceName string `split_words:"true"`

	// HTTPListenAddr is the address of HTTP server listener.
	HTTPListenAddr string `split_words:"true" default:":80"`

	// ShutdownTimeout limits time for graceful shutdown of an application.
	ShutdownTimeout time.Duration `split_words:"true" default:"10s"`

	// Debug controls dev tools.
	Debug debug.Config `split_words:"true"`

	// CacheTransferURL is URL to fetch cache from on application start.
	CacheTransferURL string `split_words:"true"`
}

BaseConfig is a basic application agnostic service configuration that manages common infrastructure.

func (*BaseConfig) Base

func (c *BaseConfig) Base() BaseConfig

Base exposes base config.

type BaseLocator

type BaseLocator struct {
	BaseConfig BaseConfig

	ctxd.LoggerProvider
	stats.TrackerProvider
	*graceful.Switch
	DebugRouter *debug.Mux

	UseCaseMiddlewares []usecase.Middleware

	// HTTPServiceOptions can be used to configure low-level middlewares like middleware.StripSlashes on an
	// initialized web.Service.
	HTTPServiceOptions     []func(s *web.Service)
	HTTPRecoveryMiddleware func(h http.Handler) http.Handler
	HTTPServerMiddlewares  []func(h http.Handler) http.Handler
	OpenAPI                *openapi.Collector
	SwaggerUIOptions       []func(cfg *swgui.Config)

	Storage *sqluct.Storage
	// contains filtered or unexported fields
}

BaseLocator is a basic application agnostic service locator that manages common infrastructure.

func NewBaseLocator

func NewBaseLocator(cfg BaseConfig) (*BaseLocator, error)

NewBaseLocator initializes basic service locator.

func NoOpLocator

func NoOpLocator() *BaseLocator

NoOpLocator creates a dummy service locator, suitable to docs rendering.

func (*BaseLocator) CacheInvalidationIndex

func (l *BaseLocator) CacheInvalidationIndex() *cache.InvalidationIndex

CacheInvalidationIndex returns cache invalidation index.

func (*BaseLocator) CacheTransfer

func (l *BaseLocator) CacheTransfer() *cache.HTTPTransfer

CacheTransfer provides a shared instance of cache transfer over HTTP.

func (*BaseLocator) SetupDebugRouter

func (l *BaseLocator) SetupDebugRouter()

SetupDebugRouter initializes a router with debug tools.

func (*BaseLocator) StartHTTPServer

func (l *BaseLocator) StartHTTPServer(handler http.Handler) (string, error)

StartHTTPServer starts HTTP server with provided handler in a goroutine and returns listening addr or error.

Server will listen at BaseConfig.HTTPListenAddr, if the value is empty free random port will be used.

Server will be gracefully stopped on service locator shutdown.

func (*BaseLocator) TransferCache

func (l *BaseLocator) TransferCache(ctx context.Context) error

TransferCache performs cache transfer.

type StartOptions

type StartOptions struct {
	// EnvPrefix is the prefix for environment variables.
	EnvPrefix string

	// EnvPrepare is called after all config loaders and before envconfig.Process,
	// it can be used to override defaults via env vars.
	EnvPrepare func() error

	// NoHTTP instructs application to exit instead of starting HTTP server.
	NoHTTP bool

	// OnHTTPStart is called after the HTTP server is started.
	OnHTTPStart func(addr string)
}

StartOptions allows more control on application startup.

type WithBaseConfig

type WithBaseConfig interface {
	Base() BaseConfig
}

WithBaseConfig is an embedded config accessor.