Documentation
¶
Overview ¶
Package settings provides engine-scoped configuration that is declared in code, stored per deployment, and optionally overridden per tenant.
Declaration is the contract: an engine states which settings it owns, their types, defaults, and validation. Nothing outside the owning engine may declare or write them, which keeps one engine's configuration out of another engine's migrations.
Index ¶
- Variables
- type Choice
- type Definition
- type Kind
- type Registry
- func (registry *Registry) Declare(owner string, definitions ...Definition) error
- func (registry *Registry) Freeze()
- func (registry *Registry) Frozen() bool
- func (registry *Registry) Lookup(owner, key string) (Definition, bool)
- func (registry *Registry) Owned(owner string) []Definition
- func (registry *Registry) Owners() []string
- type Scope
- func (scope *Scope) Bool(ctx context.Context, key string, tenant uuid.UUID) (bool, error)
- func (scope *Scope) Clear(ctx context.Context, key string, tenant uuid.UUID) error
- func (scope *Scope) Definitions() []Definition
- func (scope *Scope) Duration(ctx context.Context, key string, tenant uuid.UUID) (time.Duration, error)
- func (scope *Scope) Get(ctx context.Context, key string, tenant uuid.UUID) (any, error)
- func (scope *Scope) Int(ctx context.Context, key string, tenant uuid.UUID) (int64, error)
- func (scope *Scope) Owner() string
- func (scope *Scope) Set(ctx context.Context, key string, tenant uuid.UUID, value any) error
- func (scope *Scope) String(ctx context.Context, key string, tenant uuid.UUID) (string, error)
- func (scope *Scope) Values(ctx context.Context, tenant uuid.UUID) (map[string]any, error)
- type Store
- func (store *Store) Clear(ctx context.Context, owner, key string, tenant uuid.UUID) error
- func (store *Store) Load(ctx context.Context) error
- func (store *Store) Registry() *Registry
- func (store *Store) Resolve(ctx context.Context, owner, key string, tenant uuid.UUID) (any, error)
- func (store *Store) Scoped(owner string) *Scope
- func (store *Store) Set(ctx context.Context, owner, key string, tenant uuid.UUID, raw any) error
- func (store *Store) Values(ctx context.Context, owner string, tenant uuid.UUID) (map[string]any, error)
Constants ¶
This section is empty.
Variables ¶
var ErrFrozen = fmt.Errorf("settings registry is frozen")
Functions ¶
This section is empty.
Types ¶
type Definition ¶
type Definition struct {
// Key is the engine-local name. It is namespaced by the owning engine, so
// two engines may both declare "timeout" without colliding.
Key string
Kind Kind
Default any
Label string
Description string
// Choices enumerates permitted values and is required for Enum.
Choices []Choice
// Overridable allows a tenant to replace the deployment-wide value. A
// setting that governs platform behavior rather than tenant behavior
// should leave this false so tenants cannot change it.
Overridable bool
// Secret redacts the value wherever settings are serialized or logged.
Secret bool
// Check applies engine rules beyond the kind, such as a permitted range.
// It runs after the value is coerced to its declared type.
Check func(any) error
}
Definition declares one setting owned by one engine.
func (Definition) Coerce ¶
func (definition Definition) Coerce(raw any) (any, error)
Coerce converts a raw value to the declared kind and applies validation. Values arrive from JSON storage and from application code, so integers may legitimately present as float64.
func (Definition) Validate ¶
func (definition Definition) Validate() error
Validate reports whether the declaration itself is well formed. It does not consider stored values.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds every engine's declarations. It is frozen once mounting finishes so no engine can introduce or redefine a setting at runtime.
func NewRegistry ¶
func NewRegistry() *Registry
func (*Registry) Declare ¶
func (registry *Registry) Declare(owner string, definitions ...Definition) error
Declare records definitions owned by one engine. Redeclaring a key is an error rather than an overwrite, so a mistaken duplicate cannot silently change another declaration's type or default.
func (*Registry) Lookup ¶
func (registry *Registry) Lookup(owner, key string) (Definition, bool)
Lookup returns the declaration for one owned setting.
func (*Registry) Owned ¶
func (registry *Registry) Owned(owner string) []Definition
Owned returns one engine's declarations ordered by key, for rendering a settings surface without the host knowing what the engine declared.
type Scope ¶
type Scope struct {
// contains filtered or unexported fields
}
Scope binds a store to one owning engine so reads and writes cannot address another engine's keys.
func (*Scope) Definitions ¶
func (scope *Scope) Definitions() []Definition
Definitions returns this engine's declarations ordered by key.
func (*Scope) Duration ¶
func (scope *Scope) Duration(ctx context.Context, key string, tenant uuid.UUID) (time.Duration, error)
Duration resolves a Duration setting.
func (*Scope) Get ¶
Get resolves one of this engine's settings for a tenant. Pass uuid.Nil to read the deployment-wide value.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists declared setting values. It reads and writes only keys the registry knows, so a stale row for a removed setting can never be resolved.
func (*Store) Clear ¶
Clear removes a stored value so resolution falls back to the deployment-wide value or the declared default.
func (*Store) Load ¶
Load reads every stored value into the cache. Settings are read on nearly every request while changing rarely, so the read path must not add a query per access — especially since a request transaction holds a pooled connection for its whole lifetime.
func (*Store) Resolve ¶
Resolve returns the effective value for one setting: the tenant override if one exists and the setting permits overrides, otherwise the deployment-wide value, otherwise the declared default.
Source Files