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 GetUncached(c context.Context, key string, value interface{}) error
- 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 Bundle
- type EventualConsistentStorage
- type MemoryStorage
- type 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
Constants ¶
This section is empty.
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 ¶
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 GetUncached ¶
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 Set ¶
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 ¶
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.
Types ¶
type Bundle ¶
type Bundle struct {
Values map[string]*json.RawMessage // immutable
// contains filtered or unexported fields
}
Bundle contains all latest settings.
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 ¶
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 ¶
GetSettings grabs Settings from the context if it's there.
func (*Settings) Get ¶
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 ¶
GetStorage returns underlying Storage instance.
func (*Settings) GetUncached ¶
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 ¶
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.
//
// Returns the settings and the duration they should be cached for by default.
FetchAllSettings(c context.Context) (*Bundle, time.Duration, 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.
Source Files