config

Package config provides configuration helpers for the composition root of an apistock app: a Secret type that never leaks into logs or output, and environment lookup with *_FILE support for mounted secrets.

Library modules never read the environment; only the application's internal/app package uses this package (ADR-0020).

Stability: pre-1.0 (ADR-0015).

Variables#

var ErrBothSet#

var ErrBothSet = errors.New("config: both variable and _FILE variant are set")

ErrBothSet reports that both KEY and KEY_FILE are set.

var OS#

var OS = Source{Getenv: os.Getenv, ReadFile: os.ReadFile}

OS reads the process environment and the filesystem.

Types#

type Secret#

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

Secret holds a sensitive value such as an API key or password. Formatting, logging and JSON/text marshaling all print "[redacted]". Use Secret.Reveal to read the value.

The zero value is an empty secret.

func NewSecret#

func NewSecret(value string) Secret

NewSecret wraps value.

func (Secret) Format#

func (s Secret) Format(f fmt.State, _ rune)

Format prints "[redacted]" for every verb.

func (Secret) GoString#

func (s Secret) GoString() string

GoString returns "[redacted]".

func (Secret) IsZero#

func (s Secret) IsZero() bool

IsZero reports whether the secret is empty.

func (Secret) LogValue#

func (s Secret) LogValue() slog.Value

LogValue makes slog print "[redacted]".

func (Secret) MarshalText#

func (s Secret) MarshalText() ([]byte, error)

MarshalText returns "[redacted]", so JSON and other encoders never expose the value.

func (Secret) Reveal#

func (s Secret) Reveal() string

Reveal returns the secret value.

func (Secret) String#

func (s Secret) String() string

String returns "[redacted]".

func (*Secret) UnmarshalText#

func (s *Secret) UnmarshalText(text []byte) error

UnmarshalText stores text as the secret value. Environment loaders that support encoding.TextUnmarshaler use it.

type Source#

type Source struct {
	Getenv   func(key string) string
	ReadFile func(name string) ([]byte, error)
}

Source reads configuration values. The zero value is not usable; use OS or construct one with test doubles.

func (Source) Get#

func (s Source) Get(key string) (string, error)

Get returns the value of key. If key is empty and key+"_FILE" names a file, Get returns the file's contents with surrounding whitespace removed; this supports Docker and Kubernetes secrets mounted as files. Setting both returns ErrBothSet. A missing key returns "".

func (Source) Secret#

func (s Source) Secret(key string) (Secret, error)

Secret is like Source.Get but wraps the value in a Secret.

type Value#

type Value[T any] interface {
	Get(ctx context.Context) T
}

A Value is a setting read each time it's used, so it can change while the app runs. Library modules accept a Value for options documented as live; apps pass a runtime setting (ADR-0031) or Static.

Get must be fast and safe for concurrent use: it's called on hot paths such as every login attempt.

func Static#

func Static[T any](v T) Value[T]

Static returns a Value that always returns v.