settingsx

package
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package settingsx holds the business settings of a project: the schema, the current values and typed access to them.

Business settings are what an administrator changes without a developer and without a deploy: schedules, limits, timeouts, flags. Technical parameters of modules live in platformgo.yaml and environment variables instead.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Equal added in v0.9.0

func Equal(def Definition, a, b string) bool

Equal reports whether two values of the setting mean the same thing. Values that do not parse are compared as text, so a broken value equals only itself.

func GroupOf

func GroupOf(key string) string

GroupOf returns the group name of a key: "orders.create.timeout" gives "orders.create".

func Normalize added in v0.9.0

func Normalize(def Definition, raw string) (string, error)

Normalize returns the canonical text of a value of the setting, so that two spellings of the same value compare equal: "1m" and "60s" give "1m0s", "t" and "TRUE" give "true", "05" gives "5", "1.50" gives "1.5". A string keeps its text as is; a schedule loses repeated spaces and the case of a shorthand.

Normalize checks only that the text parses as the kind; bounds and options are the business of Validate. The result is meant for comparison, not for storage: an administrator who wrote "1m" expects to see "1m".

Types

type Definition

type Definition struct {
	Key     string   // full key, "orders.create.max_attempts"
	Group   string   // group, "orders.create"
	Name    string   // name inside the group, "max_attempts"
	Kind    Kind     //
	Default string   // value used until the database says otherwise
	Min     string   // lower bound for int and duration; empty means unbounded
	Max     string   // upper bound for int and duration
	Options []string // allowed values for string
	Title   string   // human readable name for the admin UI

	Description      string // what the setting does, shown in the admin UI
	GroupDescription string // what the group is about; the same for every setting of a group
	RequiresRestart  bool   // the value is read once at start, so a change needs a restart
}

Definition describes one setting. Values are kept as text: that is what the database stores and what the admin UI edits, while typed access parses on read.

type Group

type Group struct {
	Name        string
	Description string
	Definitions []Definition
}

Group is a set of settings shown together in the admin UI.

type ImportRejection added in v0.9.0

type ImportRejection struct {
	Key   string
	Value string
	Err   error
}

ImportRejection is a value the schema refused.

type ImportReport added in v0.9.0

type ImportReport struct {
	Imported  []string          // stored as overrides
	Unchanged []string          // an equal override is already stored: a repeated import
	Defaults  []string          // equal to the default of the schema, so nothing is stored
	Kept      []string          // a different override is already stored and wins
	Rejected  []ImportRejection // the schema refuses the value; nothing is stored
	Unknown   []string          // the schema does not describe the key
}

ImportReport says what Import did with every key it was given. Each list is ordered by key, and a key appears in exactly one of them.

func (ImportReport) String added in v0.9.0

func (r ImportReport) String() string

String is the report for a log or the output of a migration command.

func (ImportReport) Total added in v0.9.0

func (r ImportReport) Total() int

Total returns how many keys the report covers.

type Kind

type Kind string

Kind is the type of a setting. It decides how the raw value is parsed, which constraints apply and which control the admin UI shows.

const (
	KindBool     Kind = "bool"
	KindInt      Kind = "int"
	KindInt64    Kind = "int64"
	KindFloat    Kind = "float"
	KindDuration Kind = "duration"
	KindString   Kind = "string"
	KindCron     Kind = "cron"
)

The kinds are the types of taply's configuration schema.

func Kinds

func Kinds() []Kind

Kinds returns every supported kind.

type MemoryRepo

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

MemoryRepo keeps overrides in memory. Tests of project code use it so that reading a setting needs no database.

func NewMemoryRepo

func NewMemoryRepo(values map[string]string) *MemoryRepo

NewMemoryRepo creates a repository with the given overrides.

func (*MemoryRepo) Delete

func (r *MemoryRepo) Delete(_ context.Context, key string) error

Delete removes an override.

func (*MemoryRepo) Load

func (r *MemoryRepo) Load(context.Context) (map[string]string, error)

Load returns the stored overrides.

func (*MemoryRepo) Save

func (r *MemoryRepo) Save(_ context.Context, key, value, _ string) error

Save stores an override.

func (*MemoryRepo) SaveIfAbsent added in v0.9.0

func (r *MemoryRepo) SaveIfAbsent(_ context.Context, key, value, _ string) (bool, error)

SaveIfAbsent stores an override unless the key has one, and reports whether it did.

type Repo

type Repo interface {
	Load(ctx context.Context) (map[string]string, error)
	Save(ctx context.Context, key, value, actor string) error
	Delete(ctx context.Context, key string) error
}

Repo stores the values that differ from the defaults. Only overrides are kept, so a setting left alone keeps following the default from the schema across releases.

type Schema

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

Schema is the settings of a project. It is generated from settings.yaml, so code never refers to a key the schema does not describe.

func MustSchema

func MustSchema(defs ...Definition) Schema

MustSchema is NewSchema for generated code: a broken schema is a generation bug and must surface on the first run, not in production.

func NewSchema

func NewSchema(defs ...Definition) (Schema, error)

NewSchema validates the definitions and builds the schema.

func (Schema) Definition

func (s Schema) Definition(key string) (Definition, bool)

Definition returns one setting by key.

func (Schema) Definitions

func (s Schema) Definitions() []Definition

Definitions returns every setting ordered by key.

func (Schema) Groups

func (s Schema) Groups() []Group

Groups returns the settings grouped, in group name order.

func (Schema) Validate

func (s Schema) Validate(key, raw string) error

Validate checks a raw value against the setting, the way the admin UI and Set do.

type Store

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

Store keeps the current values in memory and reads them from the repository.

Reads happen on every request and must not touch the database, so values are cached; the module refreshes the cache and Set updates it right away.

func From

func From(app *platform.App) *Store

From returns the store from the container. It panics when the settings module is not enabled, the same way every other platform dependency does.

func NewStore

func NewStore(schema Schema, repo Repo, log *slog.Logger) *Store

NewStore creates a store. The values are not loaded yet: call Reload, which the module does during Init. The logger may be nil.

func NewTestStore

func NewTestStore(schema Schema, overrides map[string]string) *Store

NewTestStore builds a store on a memory repository with the overrides already loaded.

func (*Store) Bool

func (s *Store) Bool(key string) bool

Bool returns a bool setting.

func (*Store) Cron

func (s *Store) Cron(key string) string

Cron returns a schedule setting as text: the scheduler parses it itself.

func (*Store) Duration

func (s *Store) Duration(key string) time.Duration

Duration returns a duration setting.

func (*Store) Float added in v0.2.0

func (s *Store) Float(key string) float64

Float returns a float setting.

func (*Store) Import added in v0.9.0

func (s *Store) Import(ctx context.Context, values map[string]string, actor string) (ImportReport, error)

Import moves values kept elsewhere — another table, a file, an older configuration service — into the store. Only overrides are stored: a value equal to the default of the schema, in any spelling (Equal), is skipped, so the setting keeps following the default across releases. A source that wrote a row for every key, defaults included, therefore leaves only its real overrides behind.

Import never overwrites a stored override: a value an administrator set after the first import wins, and the key is reported as kept. A repository that can insert a value only when the key is absent (the one of the settings module, MemoryRepo) makes that check atomic, so a concurrent Set or a second instance importing at the same time is not overwritten either. Values are stored one by one; after a failure the keys already stored are in the report, and a repeated call carries on from there.

Import is meant to run once. Repeating it stores nothing twice and keeps every value set since, but a setting an administrator reset to its default has no override any more and would be imported again.

A rejected value is logged as a warning: the source may have used it, while the store keeps the default, so the effective value changes until someone sets it.

The actor is recorded as the author of every stored value, as with Set.

func (*Store) Int

func (s *Store) Int(key string) int

Int returns an int setting.

func (*Store) Int64 added in v0.2.0

func (s *Store) Int64(key string) int64

Int64 returns an int64 setting.

func (*Store) Overrides

func (s *Store) Overrides() int

Overrides returns how many settings differ from their defaults.

func (*Store) Raw

func (s *Store) Raw(key string) string

Raw returns the current value as text. An unknown key is a programming error: the generated accessors only pass keys from the schema.

func (*Store) Reload

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

Reload reads the overrides from the repository and replaces the cache. Values the schema does not know are ignored: a removed setting must not break the application.

func (*Store) Reset

func (s *Store) Reset(ctx context.Context, key, actor string) error

Reset drops the override so the setting follows the default from the schema again.

func (*Store) Schema

func (s *Store) Schema() Schema

Schema returns the schema of the settings.

func (*Store) Set

func (s *Store) Set(ctx context.Context, key, raw, actor string) error

Set validates the value, stores it and updates the cache. The actor is recorded for the audit log: settings change behaviour in production, so who changed what matters.

func (*Store) String

func (s *Store) String(key string) string

String returns a string setting.

func (*Store) Values

func (s *Store) Values() []Value

Values returns every setting with its current value, ordered by key.

func (*Store) Watch

func (s *Store) Watch(fn func(changed []string))

Watch registers a callback for value changes: it is how a schedule or a limit takes effect without a restart. The callback runs in the goroutine that made the change, so it must be quick and must not call back into the store.

type Value

type Value struct {
	Definition
	Value      string // current value
	Overridden bool   // true when it differs from the default and is stored in the repository
}

Value is a setting together with its current value: what the admin UI shows.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL