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 ¶
- func Equal(def Definition, a, b string) bool
- func GroupOf(key string) string
- func Normalize(def Definition, raw string) (string, error)
- type Definition
- type Group
- type ImportRejection
- type ImportReport
- type Kind
- type MemoryRepo
- type Repo
- type Schema
- type Store
- func (s *Store) Bool(key string) bool
- func (s *Store) Cron(key string) string
- func (s *Store) Duration(key string) time.Duration
- func (s *Store) Float(key string) float64
- func (s *Store) Import(ctx context.Context, values map[string]string, actor string) (ImportReport, error)
- func (s *Store) Int(key string) int
- func (s *Store) Int64(key string) int64
- func (s *Store) Overrides() int
- func (s *Store) Raw(key string) string
- func (s *Store) Reload(ctx context.Context) error
- func (s *Store) Reset(ctx context.Context, key, actor string) error
- func (s *Store) Schema() Schema
- func (s *Store) Set(ctx context.Context, key, raw, actor string) error
- func (s *Store) String(key string) string
- func (s *Store) Values() []Value
- func (s *Store) Watch(fn func(changed []string))
- type Value
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 ¶
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
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.
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) Save ¶
func (r *MemoryRepo) Save(_ context.Context, key, value, _ string) error
Save stores an override.
func (*MemoryRepo) SaveIfAbsent ¶ added in v0.9.0
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.
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 ¶
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 ¶
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 ¶
NewTestStore builds a store on a memory repository with the overrides already loaded.
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) Raw ¶
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 ¶
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 ¶
Reset drops the override so the setting follows the default from the schema again.
func (*Store) Set ¶
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.
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.