settings

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 29 Imported by: 0

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

View Source
const (
	MaxCustomCSS = 64 * 1024
	MaxCustomJS  = 64 * 1024
)

Largest theme.custom_css and theme.custom_js, in bytes.

View Source
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.

View Source
const (
	MaxTextOverrides = 3000
)

Limits of i18n.overrides.

View Source
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 Decode

func Decode[T any](s *Snapshot, key string) T

Decode unmarshals the value of key into T.

func Location

func Location(s *Snapshot) *time.Location

Location is the site's time zone (site.timezone), or UTC if it cannot be loaded.

func ParseEd25519PublicKey added in v1.1.0

func ParseEd25519PublicKey(spec string) (ed25519.PublicKey, error)

ParseEd25519PublicKey decodes a PEM SPKI, base64 SPKI/raw, or 64-hex Ed25519 public key.

func PickLocalized

func PickLocalized(m map[string]string, locale string) string

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

func (d Def) AllowedEnum() []any

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.

func (Def) Shown

func (d Def) Shown(v any) any

Shown is value v as the admin panel may see it: nil for a secret setting, the redacted value for one with secret parts.

type Range

type Range struct{ Min, Max int64 }

Range is an inclusive integer range.

func AtLeast

func AtLeast(lo int64) *Range

AtLeast is the range from lo up, without an upper bound.

func Between

func Between(lo, hi int64) *Range

Between is the range lo to hi.

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) All

func (r *Registry) All() []Def

All returns every definition sorted by key.

func (*Registry) Def

func (r *Registry) Def(key string) (Def, bool)

Def returns the definition of key.

func (*Registry) Register

func (r *Registry) Register(defs ...Def) error

Register adds definitions; duplicate keys and defaults that fail their own definition are errors.

func (*Registry) SetDynamicEnum added in v1.1.0

func (r *Registry) SetDynamicEnum(key string, fn func() []any)

SetDynamicEnum attaches a runtime option provider to a setting's allowed enum list.

func (*Registry) SetValidator

func (r *Registry) SetValidator(key string, fn func(v any) error)

SetValidator attaches a validator to an existing setting (used when the validator needs a dependency that is built after the registry, e.g. the theme registry).

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

func (s *Service) Current() *Snapshot

Current returns the live snapshot. Hold on to it for the duration of one request.

func (*Service) Load

func (s *Service) Load(ctx context.Context) error

Load reads every setting and the config version and makes them current.

func (*Service) Registry

func (s *Service) Registry() *Registry

Registry returns the definitions.

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`).

func (*Service) Touch

func (s *Service) Touch(ctx context.Context) (int64, error)

Touch bumps the config version without changing settings (themes and plugins use it when their own state changes) and broadcasts it.

func (*Service) Watch

func (s *Service) Watch(ctx context.Context, interval time.Duration)

Watch polls the config version so changes made by other nodes or by the CLI become live here too. With Redis configured (later milestone) this becomes a subscription.

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

func NewSnapshot(reg *Registry, version int64, values map[string]json.RawMessage) *Snapshot

NewSnapshot builds a snapshot from raw JSON values (tests and tooling; the service builds its own from the database).

func (*Snapshot) IsSet

func (s *Snapshot) IsSet(key string) bool

IsSet reports whether key has a stored (non-default) value.

func (*Snapshot) Localized

func (s *Snapshot) Localized(key, locale string) string

Localized picks the best translation of a localized setting for locale.

func (*Snapshot) Raw

func (s *Snapshot) Raw(key string) json.RawMessage

Raw returns the stored value of key, or its default.

func (*Snapshot) String

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

String returns a string setting.

type Type

type Type string

Type is the value type of a setting.

const (
	TypeString    Type = "string"
	TypeText      Type = "text"
	TypeBool      Type = "bool"
	TypeInt       Type = "int"
	TypeLocalized Type = "localized" // {"zh-CN": "…", "en": "…"}
	TypeJSON      Type = "json"      // any JSON value
)

type ValidationError

type ValidationError struct {
	Fields map[string]string
}

ValidationError lists per-key problems of a rejected update.

func (*ValidationError) Error

func (e *ValidationError) Error() string

Jump to

Keyboard shortcuts

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