settings

Documentation

Overview

Package settings implements storage for infrequently changing global settings.

Settings are represented as (key, value) pairs, where value is JSON serializable struct. Settings are cached internally in the process memory to avoid hitting the storage all the time.

Index

• Variables
• func Get(c context.Context, key string, value interface{}) error
• func GetUIPages() map[string]UIPage
• func GetUncached(c context.Context, key string, value interface{}) error
• func RegisterUIPage(settingsKey string, p UIPage)
• func Set(c context.Context, key string, value interface{}, who, why string) error
• func SetIfChanged(c context.Context, key string, value interface{}, who, why string) error
• func Use(c context.Context, s *Settings) context.Context
• type BaseUIPage
  • func (BaseUIPage) Fields(c context.Context) ([]UIField, error)
  • func (BaseUIPage) Overview(c context.Context) (template.HTML, error)
  • func (BaseUIPage) ReadSettings(c context.Context) (map[string]string, error)
  • func (BaseUIPage) Title(c context.Context) (string, error)
  • func (BaseUIPage) WriteSettings(c context.Context, values map[string]string, who, why string) error
• type Bundle
• type EventualConsistentStorage
• type MemoryStorage
  • func (m *MemoryStorage) FetchAllSettings(c context.Context) (*Bundle, error)
  • func (m *MemoryStorage) UpdateSetting(c context.Context, key string, value json.RawMessage, who, why string) error
• type Settings
  • func GetSettings(c context.Context) *Settings
  • func New(storage Storage) *Settings
  • func (s *Settings) Get(c context.Context, key string, value interface{}) error
  • func (s *Settings) GetStorage() Storage
  • func (s *Settings) GetUncached(c context.Context, key string, value interface{}) error
  • func (s *Settings) Set(c context.Context, key string, value interface{}, who, why string) error
  • func (s *Settings) SetIfChanged(c context.Context, key string, value interface{}, who, why string) error
• type Storage
• type UIField
  • func YesOrNoField(f UIField) UIField
• type UIFieldType
  • func (f UIFieldType) IsEditable() bool
• type UIPage
• type YesOrNo
  • func (yn *YesOrNo) Set(v string) error
  • func (yn YesOrNo) String() string

Variables

var (
	// ErrNoSettings can be returned by Get and Set on fatal errors.
	ErrNoSettings = errors.New("settings: settings are not available")

	// ErrBadType is returned if Get(...) receives unexpected type.
	ErrBadType = errors.New("settings: bad type")
)

Functions

func Get

func Get(c context.Context, key string, value interface{}) error

Get returns setting value (possibly cached) for the given key.

It will be deserialized into the supplied value. Caller is responsible to pass correct type here. If the setting is not set or the context doesn't have settings implementation in it, returns ErrNoSettings.

func GetUIPages

func GetUIPages() map[string]UIPage

GetUIPages returns a map with all registered pages.

func GetUncached

func GetUncached(c context.Context, key string, value interface{}) error

GetUncached is like Get, by always fetches settings from the storage.

Do not use GetUncached in performance critical parts, it is much heavier than Get.

func RegisterUIPage

func RegisterUIPage(settingsKey string, p UIPage)

RegisterUIPage makes exposes UI for a block of settings (identified by given unique key).

Should be called once when application starts (e.g. from init() of a package that defines the settings). Panics if such key is already registered.

func Set

func Set(c context.Context, key string, value interface{}, who, why string) error

Set overwrites a setting value for the given key.

New settings will apply only when existing in-memory cache expires. In particular, Get() right after Set() may still return old value.

Returns ErrNoSettings if context doesn't have Settings implementation.

func SetIfChanged

func SetIfChanged(c context.Context, key string, value interface{}, who, why string) error

SetIfChanged is like Set, but fetches an existing value and compares it to a new one before changing it.

Avoids generating new revisions of settings if no changes are actually made. Also logs who is making the change.

Returns ErrNoSettings if context doesn't have Settings implementation.

func Use

func Use(c context.Context, s *Settings) context.Context

Use injects Settings into the context to be used by Get and Set.

Types

type BaseUIPage

type BaseUIPage struct{}

BaseUIPage can be embedded into UIPage implementers to provide default behavior.

func (BaseUIPage) Fields

func (BaseUIPage) Fields(c context.Context) ([]UIField, error)

Fields describes the schema of the config page.

func (BaseUIPage) Overview

func (BaseUIPage) Overview(c context.Context) (template.HTML, error)

Overview is optional HTML paragraph describing this settings block.

func (BaseUIPage) ReadSettings

func (BaseUIPage) ReadSettings(c context.Context) (map[string]string, error)

ReadSettings returns a map "field ID => field value to display".

func (BaseUIPage) Title

func (BaseUIPage) Title(c context.Context) (string, error)

Title is used in UI to name this settings block.

func (BaseUIPage) WriteSettings

func (BaseUIPage) WriteSettings(c context.Context, values map[string]string, who, why string) error

WriteSettings saves settings described as a map "field ID => field value".

type Bundle

type Bundle struct {
	Values map[string]*json.RawMessage // immutable
	Exp    time.Time
	// contains filtered or unexported fields
}

Bundle contains all latest settings along with the timestamp when they need to be refetched. Stored in lazyslot.Slot.

type EventualConsistentStorage

type EventualConsistentStorage interface {
	Storage

	// GetConsistencyTime returns "last modification time" + "expiration period".
	//
	// It indicates moment in time when last setting change is fully propagated to
	// all instances.
	//
	// Returns zero time if there are no settings stored.
	GetConsistencyTime(c context.Context) (time.Time, error)
}

EventualConsistentStorage is Storage where settings changes take effect not immediately but by some predefined moment in the future.

type MemoryStorage

type MemoryStorage struct {
	Expiration time.Duration // default expiration time of in-memory cache
	// contains filtered or unexported fields
}

MemoryStorage implements Storage interface, using memory as a backend. Useful in unit tests.

func (*MemoryStorage) FetchAllSettings

func (m *MemoryStorage) FetchAllSettings(c context.Context) (*Bundle, error)

FetchAllSettings fetches all latest settings at once.

func (*MemoryStorage) UpdateSetting

func (m *MemoryStorage) UpdateSetting(c context.Context, key string, value json.RawMessage, who, why string) error

UpdateSetting updates a setting at the given key.

type Settings

type Settings struct {
	// contains filtered or unexported fields
}

Settings represent process global cache of all settings. Exact same instance of Settings should be injected into the context used by request handlers.

func GetSettings

func GetSettings(c context.Context) *Settings

GetSettings grabs Settings from the context if it's there.

func New

func New(storage Storage) *Settings

New creates new Settings object that uses given Storage to fetch and save settings.

func (*Settings) Get

func (s *Settings) Get(c context.Context, key string, value interface{}) error

Get returns setting value (possibly cached) for the given key.

It will be deserialized into the supplied value. Caller is responsible to pass correct type and pass same type to all calls. If the setting is not set returns ErrNoSettings.

func (*Settings) GetStorage

func (s *Settings) GetStorage() Storage

GetStorage returns underlying Storage instance.

func (*Settings) GetUncached

func (s *Settings) GetUncached(c context.Context, key string, value interface{}) error

GetUncached is like Get, by always fetches settings from the storage.

Do not use GetUncached in performance critical parts, it is much heavier than Get.

func (*Settings) Set

func (s *Settings) Set(c context.Context, key string, value interface{}, who, why string) error

Set changes a setting value for the given key.

New settings will apply only when existing in-memory cache expires. In particular, Get() right after Set() may still return old value.

func (*Settings) SetIfChanged

func (s *Settings) SetIfChanged(c context.Context, key string, value interface{}, who, why string) error

SetIfChanged is like Set, but fetches an existing value and compares it to a new one before changing it.

Avoids generating new revisions of settings if no changes are actually made. Also logs who is making the change.

type Storage

type Storage interface {
	// FetchAllSettings fetches all latest settings at once.
	FetchAllSettings(c context.Context) (*Bundle, error)

	// UpdateSetting updates a setting at the given key.
	UpdateSetting(c context.Context, key string, value json.RawMessage, who, why string) error
}

Storage knows how to fetch settings from permanent storage and mutate them there. Methods of Storage can be called concurrently.

type UIField

type UIField struct {
	ID             string             // page unique ID
	Title          string             // human friendly name
	Type           UIFieldType        // how the field is displayed and behaves
	Placeholder    string             // optional placeholder value
	Validator      func(string) error // optional value validation
	Help           template.HTML      // optional help text
	ChoiceVariants []string           // valid only for UIFieldChoice
}

UIField is description of a single UI element of the settings page.

Its ID acts as a key in map used by ReadSettings\WriteSettings.

func YesOrNoField

func YesOrNoField(f UIField) UIField

YesOrNoField modifies the field so that it corresponds to YesOrNo value.

It sets 'Type', 'ChoiceVariants' and 'Validator' properties.

type UIFieldType

type UIFieldType string

UIFieldType describes look and feel of UI field, see the enum below.

const (
	UIFieldText   UIFieldType = "text"   // one line of text, editable
	UIFieldChoice UIFieldType = "choice" // pick one of predefined choices
	UIFieldStatic UIFieldType = "static" // one line of text, read only
)

Note: exact values here are important. They are referenced in the HTML template that renders the settings page. See server/settings/admin/*.

func (UIFieldType) IsEditable

func (f UIFieldType) IsEditable() bool

IsEditable returns true for fields that can be edited.

type UIPage

type UIPage interface {
	// Title is used in UI to name this settings page.
	Title(c context.Context) (string, error)

	// Overview is optional HTML paragraph describing this settings page.
	Overview(c context.Context) (template.HTML, error)

	// Fields describes the schema of this settings page.
	Fields(c context.Context) ([]UIField, error)

	// ReadSettings returns a map "field ID => field value to display".
	//
	// It is called when rendering the settings page.
	ReadSettings(c context.Context) (map[string]string, error)

	// WriteSettings saves settings described as a map "field ID => field value".
	//
	// All values are validated using field validators first.
	WriteSettings(c context.Context, values map[string]string, who, why string) error
}

UIPage controls how some settings section (usually corresponding to a key in global settings JSON blob) is displayed and edited in UI.

Packages that wishes to expose UI for managing their settings register a page via RegisterUIPage(...) call during init() time.

type YesOrNo

type YesOrNo bool

YesOrNo is a bool that serializes to 'yes' or 'no'.

Useful in UIFields that define boolean values.

func (*YesOrNo) Set

func (yn *YesOrNo) Set(v string) error

Set changes the value of YesOrNo.

func (YesOrNo) String

func (yn YesOrNo) String() string

String returns "yes" or "no".