app

README

Introduction

Minimal Go framework for microservice applications running in AWS supporting:

• Multiple HTTP endpoints on different ports
• AWS SQS message processing
• Prometheus metrics endpoint
• Semantic logging using zerolog

Build & Test

Build:

go build ./...

Test:

go test

Coverage:

go test -coverprofile=coverage.out; go tool cover -func=coverage.out

Getting Started

See cmd/demo/main.go for an example app.

Documentation

Index

• Variables
• func BuildEnvConfigName(name ...string) string
• func ReadEnvConfig(c interface{}, path ...string) error
• type App
  • func NewApp(config AppConfig) *App
  • func (a *App) AddHttp(handler http.Handler, port int)
  • func (a *App) AddPrometheus(path string, port int)
  • func (a *App) AddSQS(prefix string, handler MsgHandler)
  • func (a *App) AddSQSWithConfig(config *SQSWorkerConfig, handler MsgHandler)
  • func (a *App) AddTask(t Task)
  • func (a *App) AddTaskFunc(t TaskFunc)
  • func (a App) ReadConfig(c interface{}, name ...string) error
  • func (a *App) Start()
  • func (a App) Stop()
• type AppConfig
  • func NewAppConfig(name string) *AppConfig
  • func (c AppConfig) Build() AppConfig
  • func (c AppConfig) WithMetrics(prefix string) AppConfig
• type Deleter
• type Metrics
  • func NewMetrics(config PrometheusConfig) *Metrics
  • func (m Metrics) NewCounterVec(name string, help string, labelNames []string) *prometheus.CounterVec
  • func (m Metrics) NewHistogramVec(name string, help string, labelNames []string) *prometheus.HistogramVec
• type MsgContext
• type MsgHandler
• type MsgHandlerFunc
  • func (f MsgHandlerFunc) Process(msg *MsgContext) error
• type MsgRouter
  • func NewMsgRouter() *MsgRouter
  • func (r *MsgRouter) Handle(msgType string, handler MsgHandler)
  • func (r *MsgRouter) HandleFunc(msgType string, handler MsgHandlerFunc)
  • func (r MsgRouter) Process(msg *MsgContext) error
• type PrometheusConfig
• type Queue
  • func NewQueue(config *QueueConfig, svc sqsiface.SQSAPI) *Queue
  • func (q Queue) Delete(ctx context.Context, msg *sqs.Message, queue string) error
  • func (q Queue) Receive(ctx context.Context, queue string, max int) ([]*sqs.Message, error)
  • func (q Queue) Send(ctx context.Context, body string, queue string) error
• type QueueConfig
  • func NewQueueConfig(msgTypeKey string) *QueueConfig
• type Receiver
• type SQSWorkerConfig
  • func NewSQSWorkerConfig() *SQSWorkerConfig
• type Sender
• type Task
• type TaskFunc
  • func (t TaskFunc) Run(ctx context.Context, logger zerolog.Logger)

Variables

var (
	NoMsgTypeErr = errors.New("no msgType attribute found on message")
)

Functions

func BuildEnvConfigName

func BuildEnvConfigName(name ...string) string

BuildEnvConfigName will format an environment variable name string from the supplied parts.

func ReadEnvConfig

func ReadEnvConfig(c interface{}, path ...string) error

ReadEnvConfig will read values from environment variables into the matching fields in c. The path argument specifies the names that will become underscore delimited to build the full environment variable name.

Types

type App

type App struct {
	Metrics *Metrics
	// contains filtered or unexported fields
}

App holds config and state comprising the app.

func NewApp

func NewApp(config AppConfig) *App

NewApp creates a new App. name is expected to be in upper camelcase format.

func (*App) AddHttp

func (a *App) AddHttp(handler http.Handler, port int)

func (*App) AddPrometheus

func (a *App) AddPrometheus(path string, port int)

AddPrometheus adds an HTTP server and metrics endpoint to allow collection of Prometheus metrics.

func (*App) AddSQS

func (a *App) AddSQS(prefix string, handler MsgHandler)

func (*App) AddSQSWithConfig

func (a *App) AddSQSWithConfig(config *SQSWorkerConfig, handler MsgHandler)

func (*App) AddTask

func (a *App) AddTask(t Task)

func (*App) AddTaskFunc

func (a *App) AddTaskFunc(t TaskFunc)

func (App) ReadConfig

func (a App) ReadConfig(c interface{}, name ...string) error

ReadConfig will read configuration environment variables into c. The supplied name elements are appended to the app name to form a full environment variable name.

func (*App) Start

func (a *App) Start()

Start will start serving or running any added handlers, tasks, etc. The function will block until a call to Stop is made, or an os.Interrupt signal is received.

func (App) Stop

func (a App) Stop()

Stop will shutdown any running handlers, tasks, etc and exit the app.

type AppConfig

type AppConfig struct {
	Name       string
	Env        string `default:"dev"`
	Prometheus PrometheusConfig
}

AppConfig holds configuration data for the app.

func NewAppConfig

func NewAppConfig(name string) *AppConfig

NewAppConfig returns a pointer to a new AppConfig.

func (AppConfig) Build

func (c AppConfig) Build() AppConfig

Build returns a finalised copy of the working AppConfig instance.

func (AppConfig) WithMetrics

func (c AppConfig) WithMetrics(prefix string) AppConfig

WithMetrics adds Prometheus metrics configuration with prefix being the metric name prefix for any subsequently created metrics.

type Deleter

type Deleter interface {
	Delete(ctx context.Context, msg *sqs.Message, queue string) error
}

Deleter is an interface for deleting a message from a queue.

type Metrics

type Metrics struct {
	// contains filtered or unexported fields
}

func NewMetrics

func NewMetrics(config PrometheusConfig) *Metrics

func (Metrics) NewCounterVec

func (m Metrics) NewCounterVec(name string, help string, labelNames []string) *prometheus.CounterVec

func (Metrics) NewHistogramVec

func (m Metrics) NewHistogramVec(name string, help string, labelNames []string) *prometheus.HistogramVec

type MsgContext

type MsgContext struct {
	Msg     *sqs.Message
	MsgType *string
	Logger  zerolog.Logger
}

type MsgHandler

type MsgHandler interface {
	Process(msg *MsgContext) error
}

type MsgHandlerFunc

type MsgHandlerFunc func(msg *MsgContext) error

func (MsgHandlerFunc) Process

func (f MsgHandlerFunc) Process(msg *MsgContext) error

type MsgRouter

type MsgRouter struct {
	// contains filtered or unexported fields
}

MsgRouter handles routing messages to handlers based on the message's msgType.

func NewMsgRouter

func NewMsgRouter() *MsgRouter

func (*MsgRouter) Handle

func (r *MsgRouter) Handle(msgType string, handler MsgHandler)

Handle registers handler to receive messages of msgType.

func (*MsgRouter) HandleFunc

func (r *MsgRouter) HandleFunc(msgType string, handler MsgHandlerFunc)

Handle registers handler to receive messages of msgType.

func (MsgRouter) Process

func (r MsgRouter) Process(msg *MsgContext) error

Process will pass msg to the registered handler for the message's message type.

type PrometheusConfig

type PrometheusConfig struct {
	Enabled bool
	Path    string `default:"/metrics"`
	Port    int    `default:"9090"`
	Prefix  string
}

type Queue

type Queue struct {
	// contains filtered or unexported fields
}

func NewQueue

func NewQueue(config *QueueConfig, svc sqsiface.SQSAPI) *Queue

func (Queue) Delete

func (q Queue) Delete(ctx context.Context, msg *sqs.Message, queue string) error

func (Queue) Receive

func (q Queue) Receive(ctx context.Context, queue string, max int) ([]*sqs.Message, error)

func (Queue) Send

func (q Queue) Send(ctx context.Context, body string, queue string) error

type QueueConfig

type QueueConfig struct {
	WaitTime   int
	MsgTypeKey string
}

func NewQueueConfig

func NewQueueConfig(msgTypeKey string) *QueueConfig

type Receiver

type Receiver interface {
	Receive(ctx context.Context, queue string, max int) ([]*sqs.Message, error)
}

Receiver is an interface for receiving messages from a queue.

type SQSWorkerConfig

type SQSWorkerConfig struct {
	Endpoint     string
	ReceiveQueue string
	MsgTypeKey   string
}

func NewSQSWorkerConfig

func NewSQSWorkerConfig() *SQSWorkerConfig

type Sender

type Sender interface {
	Send(ctx context.Context, body string, queue string) error
}

type Task

type Task interface {
	Run(ctx context.Context, logger zerolog.Logger)
}

type TaskFunc

type TaskFunc func(ctx context.Context, logger zerolog.Logger)

func (TaskFunc) Run

func (t TaskFunc) Run(ctx context.Context, logger zerolog.Logger)