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.

    DEPRECATED. Available only on GAEv1. Use command line flags instead.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    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")
    
    	// ErrReadOnly is returned by Set(...) if the storage is read only.
    	ErrReadOnly = errors.New("settings: the storage is read only")
    )

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

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

              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 {
                	MutableStorage
                
                	// 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 MutableStorage where settings changes take effect not immediately but by some predefined moment in the future.

                  type ExternalStorage

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

                    ExternalStorage implements Storage interface using an externally supplied io.Reader with JSON.

                    This is read-only storage (it doesn't implement MutableStorage interface), meaning settings it stores can't be change via UpdateSetting (or admin UI).

                    They still can be dynamically reloaded via Load() though.

                    func (*ExternalStorage) FetchAllSettings

                    func (s *ExternalStorage) FetchAllSettings(context.Context) (*Bundle, time.Duration, error)

                      FetchAllSettings is part of Storage interface, it returns a bundle with all latest settings and its expiration time.

                      The bundle has expiration time of 10 sec, so that Settings{...} implementation doesn't go through slower cache-miss code path all the time a setting is read (which happens multiple times per request). In practice it means changes loaded via Load() apply at most 10 sec later.

                      func (*ExternalStorage) Load

                      func (s *ExternalStorage) Load(c context.Context, r io.Reader) error

                        Load loads (or reloads) settings from a given reader.

                        The reader should supply a JSON document with a dict. Keys are strings matching various settings pages, and values are corresponding settings (usually also dicts). After settings are loaded (and the context is properly configured), calling settings.Get(c, <key>, &output) deserializes the value supplied for the corresponding key into 'output'.

                        On success logs what has changed (if anything) and eventually starts serving new settings (see comments for FetchAllSettings regarding the caching).

                        On failure returns an error without any logging or without changing what is currently being served.

                        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, time.Duration, 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 MutableStorage

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

                                MutableStorage knows how to fetch settings from permanent storage and mutate them there.

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

                                            func (s *Settings) IsMutable() bool

                                              IsMutable returns true if the storage supports MutableStorage interface.

                                              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.
                                                  	//
                                                  	// Returns the settings and the duration they should be cached for by default.
                                                  	FetchAllSettings(c context.Context) (*Bundle, time.Duration, error)
                                                  }

                                                    Storage knows how to fetch settings.

                                                    May also optionally implement MutableStorage if it supports mutating settings. Otherwise the settings are assumed to be updated via some external mechanism.

                                                    Methods of Storage can be called concurrently.