app

Documentation

Overview

Package app provides support for creating and running fx based apps.

It provides the following:

• app ID
• app ReleaseID
• app InstanceID
• eventlog.Logger using a zerolog.Logger with the above app IDs

Index

• Constants
• func Go(opts Opts, options ...fx.Option) (shutdowner fx.Shutdowner, done chan error, err error)
• func Module(opts Opts) fx.Option
• func New(opts Opts, options ...fx.Option) *fx.App
• type ID
• type InstanceID
• type Logger
• type Opts
• type ReleaseID

Constants

const (
	// 	type Data struct {
	//		DependencyGraph string `json:"dot_graph"` // DOT language visualization of the app dependency graph
	//	}
	InitializedEvent = "01DE4STZ0S24RG7R08PAY1RQX3"
	// 	type Data struct {
	//		Err string `json:"e"`
	//	}
	InitFailedEvent = "01DE4SWMZXD1ZB40QRT7RGQVPN"

	StartingEvent = "01DE4SXMG8W3KSPZ9FNZ8Z17F8"
	// 	type Data struct {
	//		Err string `json:"e"`
	//	}
	StartFailedEvent = "01DE4SY6RYCD0356KYJV7G7THW"

	// 	type Data struct {
	//		Duration uint
	//      DependencyGraph string `json:"dot_graph"` // DOT language visualization of the app dependency graph
	//	}
	StartedEvent = "01DE4X10QCV1M8TKRNXDK6AK7C"

	StoppingEvent = "01DE4SZ1KY60JQTF7XP4DQ8WGC"
	// 	type Data struct {
	//		Err string `json:"e"`
	//	}
	StopFailedEvent = "01DE4T0W35RPD6QMDS42WQXR48"

	// 	type Data struct {
	//		Duration uint
	//	}
	StoppedEvent = "01DE4T1V9N50BB67V424S6MG5C"
)

app lifecycle event IDs

const (
	IDLabel         = "a"
	ReleaseIDLabel  = "r"
	InstanceIDLabel = "i"
)

application ID labels

- used to add app IDs to log events, e.g.,

{"a":"01DG138TTVDX5JH5F4GMNC3V67","r":"01DG138TTVK4MVW3B5TJGDSKHR","x":"01DG138TTVYGSN7QWBFT9660SS","n":"foo","z":"01DG138TTVBHCXQW29QTQAWPNM","t":1563405085,"m":"bar"}

const (
	// EnvPrefix is the standard env var name prefix.
	// "APP12X" was chosen to represent 12-factor apps.
	EnvPrefix = "APP12X"
)

envconfig related constants

Functions

func Go

func Go(opts Opts, options ...fx.Option) (shutdowner fx.Shutdowner, done chan error, err error)

Go runs the app async, i.e., on a background goroutine. It returns an fx.Shutdowner, which can be used to trigger application shutdown. Once shutdown is triggered, the done channel can be used to wait until the app shutdown is complete. The done channel will return an error if any error occurs during app initialization, startup, or shutdown. An error is returned if the app initialization failed.

App lifecycle error events:

• InitFailedEvent
• StartFailedEvent
• StopFailedEvent

func Module

func Module(opts Opts) fx.Option

Module returns the module's fx options

func New

func New(opts Opts, options ...fx.Option) *fx.App

New initializes a new fx App with the following augmentations:

• app life cycle events are logged:
• InitializedEvent
• StartingEvent
• StartedEvent
• StoppingEvent
• StoppedEvent

Types

type ID

type ID func() ulid.ULID

ID returns the application ID, i.e., it corresponds to an application

type InstanceID

type InstanceID func() ulid.ULID

InstanceID returns the application instance ID, i.e., it corresponds to an application instance

type Logger

type Logger func(event string, level zerolog.Level) eventlog.Logger

Logger returns a new application event logger

• see `ZeroLogger` which provides the underlying app zerolog.Logger

type Opts

type Opts struct {
	// EnvPrefix is used to load the app ID and ReleaseID from env vars, using the following naming:
	//
	//	${EnvPrefix}_ID
	//  ${EnvPrefix}_RELEASE_ID
	//
	// If blank, then the default value of "APP12X" will be used - defined by the `EnvPrefix` const
	EnvPrefix string

	ID        ulid.ULID // if set, then it will not be loaded from the env
	ReleaseID ulid.ULID // if set, then it will not be loaded from the env

	LogWriter io.Writer // defaults to os.stderr
	// GlobalLogLevel is used to get the global log level.
	//
	// If not explicitly set, then it will first try to lookup the log level from an env var ${EnvPrefix}_LOG_LEVEL.
	// If the env var is not set, then `zerolog.InfoLevel` is returned.
	GlobalLogLevel *zerolog.Level // defaults to zerolog.Info
	// contains filtered or unexported fields
}

Opts is used to configure the fx module

type ReleaseID

type ReleaseID func() ulid.ULID

ReleaseID returns the application release ID, i.e., it corresponds to an applicaiton release mapped to a specific version