apistockdocs
v0.4 GitHub apistock.dev
Technical/Module packages

modules/settings

import "apistock.dev/modules/settings"Source on GitHub

Package settings provides runtime settings: non-secret tunables declared in Go with a default and bounds, stored in PostgreSQL only when changed, and applied on every instance without a restart (ADR-0031).

Secrets and infrastructure (database URL, API keys, listen addresses) stay in the environment (ADR-0020); they can't be declared here. 

reg := settings.NewRegistry()
codeTTL := settings.Duration(reg, "auth.verification_code_ttl", 15*time.Minute,
	settings.Describe("How long email verification codes stay valid."),
	settings.Range(5*time.Minute, time.Hour),
	settings.ReasonRequired(),
)
store, err := settings.NewStore(ctx, pool, reg, recorder)
// Run store with the app's runners; pass codeTTL, a config.Value, to modules.

A Store loads every stored value at startup, applies changes made through Store.Set and Store.Reset immediately, and learns about changes made by other instances through PostgreSQL LISTEN/NOTIFY, with a periodic full reload as a fallback.

Stability: pre-1.0 (ADR-0015).

Constants#

const DefaultResyncInterval#

go
const DefaultResyncInterval = 5 * time.Minute

DefaultResyncInterval is how often a running Store reloads every value, covering notifications lost while disconnected.

Variables#

var ErrUnknownSetting, …#

go
var (
	// ErrUnknownSetting reports a key that isn't declared in the registry.
	ErrUnknownSetting = errors.New("settings: unknown setting")

	// ErrVersionConflict reports that the setting changed after the caller
	// read it. Read it again and retry.
	ErrVersionConflict = errors.New("settings: setting changed since it was read")

	// ErrReasonRequired reports a change without a reason to a setting
	// declared with [ReasonRequired].
	ErrReasonRequired = errors.New("settings: a reason is required to change this setting")

	// ErrActorRequired reports a change without an authenticated actor in
	// the context.
	ErrActorRequired = errors.New("settings: changes require an authenticated actor")

	// ErrInvalidValue reports a value that fails decoding or validation.
	// The error is an [*InvalidValueError].
	ErrInvalidValue = errors.New("settings: invalid value")
)

Errors returned by Store methods. Check them with errors.Is.

var Migrations#

go
var Migrations fs.FS = mustSub(migrationFiles, "migrations")

Migrations holds the module's goose migrations: the settings_values and settings_history tables. Apps copy them into db/migrations (the settings recipe does this); tests can apply them directly with pgtest.

Types#

type Change#

go
type Change struct {
	// Version is the View.Version the caller last read.
	Version int64
	// Reason explains the change; required for ReasonRequired settings.
	Reason string
}

Change carries what a caller supplies with a change. The actor comes from the context.

type HistoryEntry#

go
type HistoryEntry struct {
	ID        int64
	Key       string
	OldValue  json.RawMessage
	NewValue  json.RawMessage
	Version   int64
	Reason    string
	ActorKind actor.Kind
	ActorID   string
	RequestID string
	ChangedAt time.Time
}

HistoryEntry is one change to a setting. A nil value means the default.

type InvalidValueError#

go
type InvalidValueError struct {
	Key    string
	Reason string
}

InvalidValueError describes why a value was rejected. Reason never contains the rejected value.

func (*InvalidValueError) Error#

go
func (e *InvalidValueError) Error() string

func (*InvalidValueError) Unwrap#

go
func (e *InvalidValueError) Unwrap() error

Unwrap returns ErrInvalidValue.

type Kind#

go
type Kind string

Kind is a setting's value type.

const KindBool, …#

go
const (
	KindBool       Kind = "bool"
	KindInt        Kind = "int"
	KindFloat      Kind = "float"
	KindString     Kind = "string"
	KindEnum       Kind = "enum"
	KindDuration   Kind = "duration"
	KindStringList Kind = "string_list"
)

Setting kinds.

type Option#

go
type Option interface {
	// contains filtered or unexported methods
}

An Option configures a setting declaration. An option that doesn't fit the setting's kind makes the declaration panic at startup.

func Describe#

go
func Describe(text string) Option

Describe sets the help text shown to operators.

func Email#

go
func Email() Option

Email requires a String setting, or each item of a StringList, to be a bare email address such as no-reply@example.com.

func Group#

go
func Group(name string) Option

Group sets the group used to organise settings in listings. Default: the key's first segment.

func MaxItems#

go
func MaxItems(n int) Option

MaxItems limits a StringList setting to n items.

func MaxLen#

go
func MaxLen(n int) Option

MaxLen limits a String setting, or each item of a StringList, to n characters.

func OneOf#

go
func OneOf(values ...string) Option

OneOf limits a String setting, or each item of a StringList, to values.

func Range#

go
func Range[T int | float64 | time.Duration](lo, hi T) Option

Range limits an Int, Float or Duration setting to [lo, hi]. The bounds' type must match the setting: Range(0.0, 2.0) for a Float.

func ReasonRequired#

go
func ReasonRequired() Option

ReasonRequired makes every change to the setting require a reason, recorded in its history. Use it for security-relevant settings.

func RestartRequired#

go
func RestartRequired() Option

RestartRequired makes Setting.Get return the value loaded at startup. Changes are stored immediately and take effect when instances restart.

func URL#

go
func URL() Option

URL requires a String setting, or each item of a StringList, to be an absolute http or https URL.

func Validate#

go
func Validate[T any](fn func(T) error) Option

Validate adds a custom check. fn's parameter type must match the setting: func(time.Duration) error for a Duration. Error messages are shown to operators and must not include the value.

type Registry#

go
type Registry struct {
	// contains filtered or unexported fields
}

A Registry holds declared settings and their current values. Declare every setting before calling NewStore. A Registry is safe for concurrent use.

func NewRegistry#

go
func NewRegistry() *Registry

NewRegistry returns an empty registry.

type Setting#

go
type Setting[T any] struct {
	// contains filtered or unexported fields
}

A Setting is a typed handle to one declared setting. It implements config.Value, so library modules can accept it for live options.

func Bool#

go
func Bool(r *Registry, key string, def bool, opts ...Option) *Setting[bool]

Bool declares a true/false setting.

func Duration#

go
func Duration(r *Registry, key string, def time.Duration, opts ...Option) *Setting[time.Duration]

Duration declares a duration setting, stored and edited as a Go duration string such as "15m" or "1h30m". Combine with Range.

func Enum#

go
func Enum(r *Registry, key string, def string, allowed []string, opts ...Option) *Setting[string]

Enum declares a text setting limited to allowed values.

func Float#

go
func Float(r *Registry, key string, def float64, opts ...Option) *Setting[float64]

Float declares a decimal setting. Combine with Range, passing float bounds such as Range(0.0, 2.0).

func Int#

go
func Int(r *Registry, key string, def int, opts ...Option) *Setting[int]

Int declares a whole-number setting. Combine with Range.

func String#

go
func String(r *Registry, key string, def string, opts ...Option) *Setting[string]

String declares a text setting. Combine with MaxLen, URL or Email.

func StringList#

go
func StringList(r *Registry, key string, def []string, opts ...Option) *Setting[[]string]

StringList declares a list-of-text setting, such as allowed origins. Get returns a copy the caller may modify.

func (*Setting[T]) Get#

go
func (s *Setting[T]) Get(context.Context) T

Get returns the setting's current value. It returns the default while the setting is unchanged, when its stored value fails validation, and before a store has loaded. Settings declared with RestartRequired keep the value loaded at startup. Get never touches the database.

func (*Setting[T]) Key#

go
func (s *Setting[T]) Key() string

Key returns the setting's key.

type Store#

go
type Store struct {
	// contains filtered or unexported fields
}

Store persists settings in PostgreSQL and keeps a Registry current. It is an app.Runner: run it so changes from other instances arrive. It is safe for concurrent use.

func NewStore#

go
func NewStore(ctx context.Context, pool *pgxpool.Pool, reg *Registry, recorder audit.Recorder, opts ...StoreOption) (*Store, error)

NewStore loads every stored value into reg and returns the store. After NewStore, reg accepts no new declarations. Changes are recorded as "settings.value.changed" audit events through recorder.

The settings tables come from Migrations; apply them first.

func (*Store) DeleteHistoryBefore#

go
func (s *Store) DeleteHistoryBefore(ctx context.Context, before time.Time, limit int) (int64, error)

DeleteHistoryBefore deletes up to limit setting changes made before before, oldest first, and returns how many it deleted. Retention calls it until it deletes fewer than limit (ADR-0051).

func (*Store) Get#

go
func (s *Store) Get(key string) (View, error)

Get returns one setting, or ErrUnknownSetting.

func (*Store) History#

go
func (s *Store) History(ctx context.Context, key string, before int64, limit int) ([]HistoryEntry, error)

History returns changes to key, newest first. For the next page, pass the last entry's ID as before (0 starts from the newest). limit is clamped to 1–100.

func (*Store) List#

go
func (s *Store) List() []View

List returns every declared setting in declaration order. It reads memory only.

func (*Store) OldestHistory#

go
func (s *Store) OldestHistory(ctx context.Context) (oldest time.Time, ok bool, err error)

OldestHistory returns when the oldest recorded change was made; ok is false when there are none.

func (*Store) Reload#

go
func (s *Store) Reload(ctx context.Context) error

Reload reads every stored value from the database.

func (*Store) Reset#

go
func (s *Store) Reset(ctx context.Context, key string, change Change) (View, error)

Reset returns key to its default. It returns the same errors as Store.Set, except for invalid values.

func (*Store) Run#

go
func (s *Store) Run(ctx context.Context) error

Run keeps the registry current until ctx is done, then returns nil. It listens on a dedicated connection for changes committed by any instance, reloads everything after connecting (changes made while disconnected send no notification), and reloads everything every resync interval as a fallback. Connection failures are logged and retried with backoff.

func (*Store) Set#

go
func (s *Store) Set(ctx context.Context, key string, value json.RawMessage, change Change) (View, error)

Set validates value (JSON, such as `"30m"` or `42`) and stores it for key. The change applies to this instance immediately and to others within moments. It returns ErrUnknownSetting, an *InvalidValueError, ErrReasonRequired, ErrActorRequired or ErrVersionConflict. Setting the current value again changes nothing.

func (*Store) UnknownKeys#

go
func (s *Store) UnknownKeys() []string

UnknownKeys returns stored keys that no declaration matches, for example settings removed from the code. Their rows are kept and ignored.

type StoreOption#

go
type StoreOption interface {
	// contains filtered or unexported methods
}

A StoreOption configures NewStore.

func WithLogger#

go
func WithLogger(logger *slog.Logger) StoreOption

WithLogger sets the logger for listener and invalid-value warnings. Default: discard.

func WithResyncInterval#

go
func WithResyncInterval(d time.Duration) StoreOption

WithResyncInterval sets how often Store.Run reloads every value. Default: DefaultResyncInterval.

type View#

go
type View struct {
	Key         string
	Kind        Kind
	Group       string
	Description string

	// Value is the effective value as JSON; Default is the declared default.
	Value   json.RawMessage
	Default json.RawMessage
	// Modified reports whether a valid stored value overrides the default.
	Modified bool
	// InvalidStoredValue reports a stored value that fails validation, so
	// the default is in effect.
	InvalidStoredValue bool

	// Version increases with every change; pass it back to change the
	// setting. It is 0 for a setting that has never been changed.
	Version   int64
	UpdatedAt time.Time
	UpdatedBy string

	ReasonRequired  bool
	RestartRequired bool
	// RestartPending reports a restart-required setting changed since this
	// instance started.
	RestartPending bool

	// Constraints summarises validation, such as min, max, one_of, max_len,
	// max_items and format. Treat it as read-only.
	Constraints map[string]any
}

View is a setting's declaration and current state, for operator APIs.

v0.4
esc
↑↓ move↵ openesc close