Documentation
¶
Overview ¶
Package settings holds runtime settings that admins edit: typed definitions, a database store, and an atomically swapped snapshot that changes are hot-applied from.
Index ¶
- Constants
- func Decode[T any](s *Snapshot, key string) T
- func Location(s *Snapshot) *time.Location
- func ParseEd25519PublicKey(spec string) (ed25519.PublicKey, error)
- func PickLocalized(m map[string]string, locale string) string
- func SameJSON(a, b json.RawMessage) bool
- type Def
- type Range
- type Registry
- type RegistrySource
- type Service
- func (s *Service) Current() *Snapshot
- func (s *Service) Load(ctx context.Context) error
- func (s *Service) Registry() *Registry
- func (s *Service) Set(ctx context.Context, actor *int64, changes map[string]json.RawMessage, ...) (*Snapshot, error)
- func (s *Service) SetOnReload(fn func())
- func (s *Service) Touch(ctx context.Context) (int64, error)
- func (s *Service) Watch(ctx context.Context, interval time.Duration)
- type Snapshot
- type Type
- type ValidationError
Constants ¶
const ( MaxCustomCSS = 64 * 1024 MaxCustomJS = 64 * 1024 )
Largest theme.custom_css and theme.custom_js, in bytes.
const ConfigVersionKey = "config_version"
ConfigVersionKey is the system_state row every node polls. It is bumped by any change that should reach browsers and other nodes: settings, theme, plugins.
const (
MaxTextOverrides = 3000
)
Limits of i18n.overrides.
const Redacted = "********"
Redacted stands in for a saved secret inside a value shown to the admin panel (Def.Redact); sent back unchanged, it keeps the saved secret (Def.Restore).
Variables ¶
This section is empty.
Functions ¶
func ParseEd25519PublicKey ¶ added in v1.1.0
ParseEd25519PublicKey decodes a PEM SPKI, base64 SPKI/raw, or 64-hex Ed25519 public key.
func PickLocalized ¶
PickLocalized chooses exact locale, then same language, then en, then zh-CN, then any.
func SameJSON ¶
func SameJSON(a, b json.RawMessage) bool
SameJSON reports whether a and b decode to the same value.
Types ¶
type Def ¶
type Def struct {
Key string
Type Type
Default any
// Public settings are sent to every visitor in the site bootstrap.
Public bool
// Secret settings (passwords, secret keys) are never shown again once saved: the
// admin panel only learns whether one is set.
Secret bool
// SentTo names the settings that say where a Secret is sent (the SMTP server of the
// SMTP password). The admin panel must give the secret again to change one of them:
// a kept secret would otherwise go to a server of the editor's choosing.
SentTo []string
// Superadmin settings put code into every page (custom CSS): only a super
// administrator, the admin token or the CLI may change them (BS S16).
Superadmin bool
Doc string
// Enum lists the allowed values; the admin panel offers them as a choice.
Enum []any
// DynamicEnum optionally appends runtime-registered options (e.g. plugin providers).
DynamicEnum func() []any
// Range bounds a TypeInt setting, both ends included.
Range *Range
// Validate runs after the type, Enum and Range checks; nil means none.
Validate func(v any) error
// Redact hides the secret parts of a value (an object with secret fields) from the
// admin panel, and Restore puts the stored ones back into an edited value where the
// panel left them redacted. Both or neither.
Redact func(v any) any
Restore func(stored, edited any) any
}
Def defines one setting.
func (Def) AllowedEnum ¶ added in v1.1.0
AllowedEnum returns the union of built-in Enum values and any DynamicEnum entries.
func (Def) Canonical ¶
func (d Def) Canonical(raw json.RawMessage) (json.RawMessage, error)
Canonical checks raw against the definition, as saving it would, and returns the value as it is stored. The BS importer writes settings with it.
type Range ¶
type Range struct{ Min, Max int64 }
Range is an inclusive integer range.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is the set of known settings. Modules register theirs at startup.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry returns a registry pre-filled with the core settings.
func (*Registry) Register ¶
Register adds definitions; duplicate keys and defaults that fail their own definition are errors.
func (*Registry) SetDynamicEnum ¶ added in v1.1.0
SetDynamicEnum attaches a runtime option provider to a setting's allowed enum list.
type RegistrySource ¶ added in v1.1.0
type RegistrySource struct {
ID string `json:"id"`
Name string `json:"name,omitempty"`
URLs []string `json:"urls"`
PublicKey string `json:"publicKey,omitempty"`
Official bool `json:"official,omitempty"`
Enabled bool `json:"enabled"`
}
RegistrySource configures one plugin/theme market registry in plugin.registries.
func DefaultPluginRegistries ¶ added in v1.1.0
func DefaultPluginRegistries() []RegistrySource
DefaultPluginRegistries returns the default official market registry configuration with the domestic CDN primary mirror and GitHub failover mirror.
func ParsePluginRegistries ¶ added in v1.1.0
func ParsePluginRegistries(v any) ([]RegistrySource, error)
ParsePluginRegistries validates and normalizes a plugin.registries setting value.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service loads, stores and broadcasts settings.
func NewService ¶
func NewService(reg *Registry, client *ent.Client, broker *pubsub.Broker, bus *hook.Bus, log *slog.Logger) *Service
NewService builds the service; call Load before use.
func (*Service) Current ¶
Current returns the live snapshot. Hold on to it for the duration of one request.
func (*Service) Set ¶
func (s *Service) Set(ctx context.Context, actor *int64, changes map[string]json.RawMessage, rec *audit.Entry) (*Snapshot, error)
Set validates and stores changes in one transaction, bumps the config version and publishes the new snapshot. A JSON null resets a key to its default. A setting with secret parts (Def.Restore) gets the stored ones back where the edited value left them redacted. rec, if not nil, is written to the audit log in the same transaction, with the keys changed.
func (*Service) SetOnReload ¶ added in v1.1.0
func (s *Service) SetOnReload(fn func())
SetOnReload registers a callback run when Watch detects a config version bump from another process (such as `skinloom theme reload`).
type Snapshot ¶
type Snapshot struct {
Version int64
// contains filtered or unexported fields
}
Snapshot is an immutable view of all settings at one config version.
func NewSnapshot ¶
NewSnapshot builds a snapshot from raw JSON values (tests and tooling; the service builds its own from the database).
func (*Snapshot) Localized ¶
Localized picks the best translation of a localized setting for locale.
type ValidationError ¶
ValidationError lists per-key problems of a rejected update.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string