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 GroupOf(key string) string
- type Definition
- type Group
- 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) 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 ¶
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 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.
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) 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.
Source Files