config

Documentation

Overview

Package config provides configuration helpers for the composition root of a gorbital 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: stable (ADR-0015, ADR-0054).

Index

• Variables
• type Secret
  • func NewSecret(value string) Secret
  • func (s Secret) Format(f fmt.State, _ rune)
  • func (s Secret) GoString() string
  • func (s Secret) IsZero() bool
  • func (s Secret) LogValue() slog.Value
  • func (s Secret) MarshalText() ([]byte, error)
  • func (s Secret) Reveal() string
  • func (s Secret) String() string
  • func (s *Secret) UnmarshalText(text []byte) error
• type Source
  • func (s Source) Get(key string) (string, error)
  • func (s Source) Secret(key string) (Secret, error)
• type Value
  • func Static[T any](v T) Value[T]

Variables

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

ErrBothSet reports that both KEY and KEY_FILE are set.

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.