dogmatiq / dodeca

🚫 Utilities for 12-Factor applications written in Go.

Dodeca

Go utilities for developers of 12-Factor applications.

This project is deprecated.

• All Dogmatiq projects that use the Dodeca logging package are transitioning to use slog instead, in anticipation of its inclusion in Go's standard library.

• The Dodeca config package has been superceded by dogmatiq/ferrite. Please see the migration guide for more information.

This repository will be archived once it is no longer used by other Dogmatiq projects.

Logging

The logging package provides a very simple logging interface.

The 12 Factor methodology states that all application logs should be written to STDOUT, and as such this is the default behavior of the logging package.

Additionally, the logger discriminates between application messages and debug messages, as per Dave Cheney's post about logging.

Configuration

The config package provides features to abstract the specification of a configuration value, from the consumption of a configuration value, using environment variables.

The 12 Factor methodology states that all application configuration should be read from environment variables. However, it is not uncommon to have configuration requirements with complexity that exceeds the capability of simple key/value pairs. In such situations, the obvious solution is to use a configuration file.

The approach we've taken is to allow configuration to be specified as a regular environment variable, or as an environment variable that describes the path to a configuration file.

The developer can then chose to consume this configuration as a string, []byte, io.ReadCloser, or as a path to a real file on disk, regardless of how the configuration as specified.

Usage

Specifying configuration

For any given environment variable K, the environment variable K__DATASOURCE indicates how the content of K should be interpreted.

If K__DATASOURCE is:

• empty, undefined or the value string:plain, then K is a regular variable
• the value string:hex, then K contains a binary value with hexadecimal encoding
• the value string:base64, then K contains a binary value with base-64 encoding
• the value file, then K contains a path to a file containing the value

Consuming configuration

There are three primary approaches to consuming configuration. The preferred way is to use once of the "typed" functions, such as AsBool(), AsInt(), etc.

These accept a config.Bucket type. The second approach is to use the bucket directly, which gives access to config.Value which in turn has methods for representing that value as a string, []byte, io.ReadCloser, or as a path to a real file on disk.

Finally, the config.GetEnv() function can be used as a drop-in replacement for os.Getenv(). However, it should be noted that when there is a problem loading a configuration value, such as when a non-existent file is specified this function simply returns an empty string.

dodeca's Issues

Standardise the test suite.

Just some simple things to bring inline with current practices:

• Use When() instead of Context("when ...")
• Use Describe("func Foo()") for functions / methods, including closing parens

Rename the fmt parameter to avoid aliasing the fmt package.

Add functions for reading environment variables with strict typing.

For example, it would be great to be able to read integers, floats, bools, durations, etc from a bucket and have the values parsed and validated.

• bool
• int
• int8
• int16
• int32
• int64
• uint
• uint8
• uint16
• uint32
• uint64
• float32
• float64
• time.Duration
• complex64 - I'm not going add functions for complex types unless someone comes up with a use case
• complex128

Update all godoc.org URLs to pkg.go.dev.

See dogmatiq/dogma#112 and dogmatiq/dogma@b3c4407 for an example.

Add prefix logger.

func WithPrefix(logger, format string, v ...interface{}) Logger { ... }

logger = WithPrefix(logger, "message prefix: ")

For reference, see https://github.com/dogmatiq/infix/blob/e97558df12f5f2b938e582a46a8eafd5ac27707f/internal/x/loggingx/prefix.go

Upload coverage reports under CI whenever CODECOV_TOKEN is available.

As per the changes to the CI configuration template in dogmatiq/template-go@eb5bb57.

Writer implementation should strip trailing new-lines.

It should probably trim, then split on newlines... perhaps even buffering any non-newline-terminated strings.

Add adaptors for "promoting" and "demoting" message levels.

For example, promote would convert debug messages into regular log messages:

func Promote(l Logger) Logger { ... }

promoted := logging.Promote(logger)
promoted.Debug("foo") // equivalent to logger.Log("foo")
promoted.Log("foo")   // also equivalent to logger.Log("foo")

And demote, the opposite:

// capture would be similar to the CaptureDebug flag on StandardLogger
func Demote(l Logger, capture bool) Logger { ... }

demoted := logging.Demote(logger, true)
demoted.Debug("foo") // equivalent to logger.Debug("foo") if capture is true, or blackholed if false
demoted.Log("foo")   // also equivalent to logger.Debug("foo")

Convert from Travis CI to GitHub actions.

Provide a mechanism to obtain an io.Writer from a logger.

There will need to be two variants, one for regular log messages, and another for debug.

Use Go v1.15 in CI configuration.

See the template repo CI configuration.

Use Makefiles from makefiles.dev.