commons

Documentation

Overview

Package commons handles common non-domain features

Some of these could be in `cmd/app` main package, but I suspect these will be reusable across apps, and so I would prefer to make these easily copy-pasteable, or be easy to create an actually public `commons` library.

Index

• func LivenessController(ginEngine *gin.Engine, indicators ...HealthIndicator)
• func NewGinEngine(serviceName string, logger *slog.Logger) *gin.Engine
• func NewLogger(format LogFormat, writer io.Writer) *slog.Logger
• func NewMockDb(t *testing.T, migrationsDirectory string, logger *slog.Logger) (*sqlx.DB, func())
• func ReadinessController(ginEngine *gin.Engine, indicators ...HealthIndicator)
• func RunMigrations(database *sql.DB, migrationDirectory string, logger *slog.Logger) error
• type DbHealthIndicator
  • func NewDbHealthIndicator(name string, db PingableDB, logger *slog.Logger) *DbHealthIndicator
  • func (dbHealthIndicator *DbHealthIndicator) IndicateHealth() (string, bool)
• type HealthIndicator
• type LogFormat
• type PingableDB
• type Status

Functions

func LivenessController

func LivenessController(ginEngine *gin.Engine, indicators ...HealthIndicator)

LivenessController creates an endpoint to report whether the service is HEALTHY (HTTP 200) or FAILING (HTTP 503) in regard to "liveness": https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/#liveness-probe.

To report this, it uses a default healthReport, plus any HealthIndicator structs provided to it. If you build something that you want to include in the LivenessController, first ensure it can be a HealthIndicator, then simply pass it in when doing dependency injection.

func NewGinEngine

func NewGinEngine(serviceName string, logger *slog.Logger) *gin.Engine

NewGinEngine is a factory method for creating a production-ready gin.Engine instance.

func NewLogger

func NewLogger(format LogFormat, writer io.Writer) *slog.Logger

NewLogger makes a new sensibly preconfigured slog.Logger for use in an application. The log format will be LogFormatJSON or plain text depending on the value of the `LOG_FORMAT` environment variable.

func NewMockDb

func NewMockDb(t *testing.T, migrationsDirectory string, logger *slog.Logger) (*sqlx.DB, func())

NewMockDb is a factory method for creating a mock database instance, using Testcontainers.

NOTE: Only to be used for testing (or local development).

func ReadinessController

func ReadinessController(ginEngine *gin.Engine, indicators ...HealthIndicator)

ReadinessController creates an endpoint to report whether the service is HEALTHY (HTTP 200) or FAILING (HTTP 503) in regard to "readiness": https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/#readiness-probe.

To report this, it uses a default healthReport, plus any HealthIndicator structs provided to it. If you build something that you want to include in the LivenessController, first ensure it can be a HealthIndicator, then simply pass it in when doing dependency injection.

func RunMigrations

func RunMigrations(database *sql.DB, migrationDirectory string, logger *slog.Logger) error

RunMigrations runs the DB migrations found in the given migration directory on the given sql.DB.

Types

type DbHealthIndicator

type DbHealthIndicator struct {
	Name   string
	Db     PingableDB
	Logger *slog.Logger
}

DbHealthIndicator is a HealthIndicator for a given PingableDB.

func NewDbHealthIndicator

func NewDbHealthIndicator(name string, db PingableDB, logger *slog.Logger) *DbHealthIndicator

NewDbHealthIndicator is a factory method for producing a DbHealthIndicator.

func (*DbHealthIndicator) IndicateHealth

func (dbHealthIndicator *DbHealthIndicator) IndicateHealth() (string, bool)

IndicateHealth is the HealthIndicator.IndicateHealth implementation for DbHealthIndicator.

type HealthIndicator

type HealthIndicator interface {
	IndicateHealth() (name string, isHealthy bool)
}

HealthIndicator describes how a health indicator should function. A component can be a HealthIndicator if it has a name (for visibility) and can report if it is healthy or not.

type LogFormat

type LogFormat string

LogFormat is an enumeration for choosing the format to use for logging.

const LogFormatJSON LogFormat = "JSON"

LogFormatJSON is a LogFormat that can be used to configure JSON logging.

const LogFormatTEXT LogFormat = "TEXT"

LogFormatTEXT is a LogFormat that can be used to configure TEXT logging.

type PingableDB

type PingableDB interface {
	Ping() error
}

PingableDB is a DB that can be pinged.

type Status

type Status string

Status is an enumeration for conveying the health status.

const (
	// HEALTHY conveys a Status that is up.
	HEALTHY Status = "HEALTHY"
	// FAILING conveys a Status that is down.
	FAILING Status = "FAILING"
)