settings

package
v0.0.0-...-bf59245 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2017 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package settings provides a central registry of runtime editable settings and accompanying helper functions for retreiving their current values.

Settings values are stored in the system.settings table (which is gossiped). A gossip-driven worker updates this package's cached value when the table changes (see the `RefreshSettings“ worker in the `sql` package).

The package's cache is global -- while all the usual drawbacks of mutable global state obviously apply, it is needed to make the package's functionality available to a wide variety of callsites, that may or may not have a *Server or similar available to plumb though.

To add a new setting, call one of the `Register` methods in `registry.go` and save the accessor created by the register function in the package where the setting is to be used. For example, to add an "enterprise" flag, adding into license_check.go:

var enterpriseEnabled = settings.RegisterBoolSetting( 

"enterprise.enabled", "some doc for the setting", false,

)

Then use with `if enterpriseEnabled.Get() ...`

Settings should always be defined with "safe" default values -- until a node receives values via gossip, or even after that, if it cannot read them for some reason, it will use the default values, so define defaults that "fail safe".

In cases where the "safe" default doesn't actually match the desired default, like respecting an opt-*out* setting, we can default to `false` (opted out) and then use a migration to write an explicit `true`: in practice you'd still expect to read `true` unless a preference is expressed, but in the rare cases where you read a default, you don't risk ignoring an expressed opt-out.

Ideally, when passing configuration into some structure or subsystem, e.g. a rate limit into a client or something, passing a `*FooSetting rather than a `Foo` and waiting to call `.Get()` until the value is actually used ensures observing the latest value.

Existing/off-the-shelf systems generally will not be defined in terms of our settings, but if they can either be swapped at runtime or expose some `setFoo` method, that can be used in conjunction with an change callback registered via OnChange.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EncodeBool 

func EncodeBool(b bool) string

EncodeBool encodes a bool in the format parseRaw expects.

func EncodeDuration 

func EncodeDuration(d time.Duration) string

EncodeDuration encodes a duration in the format parseRaw expects.

func EncodeFloat 

func EncodeFloat(f float64) string

EncodeFloat encodes a bool in the format parseRaw expects.

func EncodeInt 

func EncodeInt(i int64) string

EncodeInt encodes an int in the format parseRaw expects.

func Freeze 

func Freeze()

Freeze ensures that no new settings can be defined after the gossip worker has started. See settingsworker.go.

func Keys 

func Keys() (res []string)

Keys returns a sorted string array with all the known keys.

func TestingSetBool 

func TestingSetBool(s **BoolSetting, v bool) func()

TestingSetBool returns a mock, unregistered bool setting for testing. It takes a pointer to a BoolSetting reference, swapping in the mock setting. It returns a cleanup function that swaps back the original setting. This function should not be used by tests that run in parallel, as it could result in race detector failures, as well as if the cleanup functions are called out of order. The original Setting remains registered for gossip-driven updates which become visible when it is restored.

func TestingSetByteSize 

func TestingSetByteSize(s **ByteSizeSetting, v int64) func()

TestingSetByteSize returns a mock bytesize setting for testing. See TestingSetBool for more details.

func TestingSetDuration 

func TestingSetDuration(s **DurationSetting, v time.Duration) func()

TestingSetDuration returns a mock, unregistered string setting for testing. See TestingSetBool for more details.

func TestingSetEnum 

func TestingSetEnum(s **EnumSetting, i int64) func()

TestingSetEnum returns a mock, unregistered enum setting for testing. See TestingSetBool for more details.

func TestingSetFloat 

func TestingSetFloat(s **FloatSetting, v float64) func()

TestingSetFloat returns a mock, unregistered float setting for testing. See TestingSetBool for more details.

func TestingSetInt 

func TestingSetInt(s **IntSetting, v int64) func()

TestingSetInt returns a mock, unregistered int setting for testing. See TestingSetBool for more details.

func TestingSetString 

func TestingSetString(s **StringSetting, v string) func()

TestingSetString returns a mock, unregistered string setting for testing. See TestingSetBool for more details.

Types

type BoolSetting 

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

BoolSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "bool" is updated.

func RegisterBoolSetting 

func RegisterBoolSetting(key, desc string, defaultValue bool) *BoolSetting

RegisterBoolSetting defines a new setting with type bool.

func (BoolSetting) Description 

func (i BoolSetting) Description() string

func (*BoolSetting) Get 

func (b *BoolSetting) Get() bool

Get retrieves the bool value in the setting.

func (BoolSetting) Hidden 

func (i BoolSetting) Hidden() bool

func (*BoolSetting) Hide 

func (i *BoolSetting) Hide()

Hide prevents a setting from showing up in SHOW ALL CLUSTER SETTINGS. It can still be used with SET and SHOW if the exact setting name is known. Use Hide for in-development features and other settings that should not be user-visible.

func (*BoolSetting) OnChange 

func (b *BoolSetting) OnChange(fn func()) *BoolSetting

OnChange registers a callback to be called when the setting changes.

func (*BoolSetting) String 

func (b *BoolSetting) String() string

func (*BoolSetting) Typ 

func (*BoolSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

type ByteSizeSetting 

type ByteSizeSetting struct {
	IntSetting
}

ByteSizeSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "bytesize" is updated.

func RegisterByteSizeSetting 

func RegisterByteSizeSetting(key, desc string, defaultValue int64) *ByteSizeSetting

RegisterByteSizeSetting defines a new setting with type bytesize.

func RegisterValidatedByteSizeSetting 

func RegisterValidatedByteSizeSetting(
	key, desc string, defaultValue int64, validateFn func(int64) error,
) *ByteSizeSetting

RegisterValidatedByteSizeSetting defines a new setting with type bytesize with a validation function.

func (ByteSizeSetting) Description 

func (i ByteSizeSetting) Description() string

func (ByteSizeSetting) Hidden 

func (i ByteSizeSetting) Hidden() bool

func (*ByteSizeSetting) Hide 

func (i *ByteSizeSetting) Hide()

Hide prevents a setting from showing up in SHOW ALL CLUSTER SETTINGS. It can still be used with SET and SHOW if the exact setting name is known. Use Hide for in-development features and other settings that should not be user-visible.

func (*ByteSizeSetting) OnChange 

func (b *ByteSizeSetting) OnChange(fn func()) *ByteSizeSetting

OnChange registers a callback to be called when the setting changes.

func (*ByteSizeSetting) String 

func (b *ByteSizeSetting) String() string

func (*ByteSizeSetting) Typ 

func (*ByteSizeSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

type DurationSetting 

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

DurationSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "duration" is updated.

func RegisterDurationSetting 

func RegisterDurationSetting(key, desc string, defaultValue time.Duration) *DurationSetting

RegisterDurationSetting defines a new setting with type duration.

func RegisterNonNegativeDurationSetting 

func RegisterNonNegativeDurationSetting(
	key, desc string, defaultValue time.Duration,
) *DurationSetting

RegisterNonNegativeDurationSetting defines a new setting with type duration.

func RegisterValidatedDurationSetting 

func RegisterValidatedDurationSetting(
	key, desc string, defaultValue time.Duration, validateFn func(time.Duration) error,
) *DurationSetting

RegisterValidatedDurationSetting defines a new setting with type duration.

func TestingDuration 

func TestingDuration(v time.Duration) *DurationSetting

TestingDuration returns a one off, unregistered duration setting for test use only.

func (DurationSetting) Description 

func (i DurationSetting) Description() string

func (*DurationSetting) Get 

func (d *DurationSetting) Get() time.Duration

Get retrieves the duration value in the setting.

func (DurationSetting) Hidden 

func (i DurationSetting) Hidden() bool

func (*DurationSetting) Hide 

func (i *DurationSetting) Hide()

Hide prevents a setting from showing up in SHOW ALL CLUSTER SETTINGS. It can still be used with SET and SHOW if the exact setting name is known. Use Hide for in-development features and other settings that should not be user-visible.

func (*DurationSetting) OnChange 

func (d *DurationSetting) OnChange(fn func()) *DurationSetting

OnChange registers a callback to be called when the setting changes.

func (*DurationSetting) String 

func (d *DurationSetting) String() string

func (*DurationSetting) Typ 

func (*DurationSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*DurationSetting) Validate 

func (d *DurationSetting) Validate(v time.Duration) error

Validate that a value conforms with the validation function.

type EnumSetting 

type EnumSetting struct {
	IntSetting
	// contains filtered or unexported fields
}

EnumSetting is a StringSetting that restricts the values to be one of the `enumValues`

func RegisterEnumSetting 

func RegisterEnumSetting(
	key, desc string, defaultValue string, enumValues map[int64]string,
) *EnumSetting

RegisterEnumSetting defines a new setting with type int.

func (EnumSetting) Description 

func (i EnumSetting) Description() string

func (EnumSetting) Hidden 

func (i EnumSetting) Hidden() bool

func (*EnumSetting) Hide 

func (i *EnumSetting) Hide()

Hide prevents a setting from showing up in SHOW ALL CLUSTER SETTINGS. It can still be used with SET and SHOW if the exact setting name is known. Use Hide for in-development features and other settings that should not be user-visible.

func (*EnumSetting) OnChange 

func (e *EnumSetting) OnChange(fn func()) *EnumSetting

OnChange registers a callback to be called when the setting changes.

func (*EnumSetting) ParseEnum 

func (e *EnumSetting) ParseEnum(raw string) (int64, bool)

ParseEnum returns the enum value, and a boolean that indicates if it was parseable.

func (*EnumSetting) Typ 

func (e *EnumSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

type FloatSetting 

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

FloatSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "float" is updated.

func RegisterFloatSetting 

func RegisterFloatSetting(key, desc string, defaultValue float64) *FloatSetting

RegisterFloatSetting defines a new setting with type float.

func RegisterNonNegativeFloatSetting 

func RegisterNonNegativeFloatSetting(key, desc string, defaultValue float64) *FloatSetting

RegisterNonNegativeFloatSetting defines a new setting with type float.

func RegisterValidatedFloatSetting 

func RegisterValidatedFloatSetting(
	key, desc string, defaultValue float64, validateFn func(float64) error,
) *FloatSetting

RegisterValidatedFloatSetting defines a new setting with type float.

func (FloatSetting) Description 

func (i FloatSetting) Description() string

func (*FloatSetting) Get 

func (f *FloatSetting) Get() float64

Get retrieves the float value in the setting.

func (FloatSetting) Hidden 

func (i FloatSetting) Hidden() bool

func (*FloatSetting) Hide 

func (i *FloatSetting) Hide()

Hide prevents a setting from showing up in SHOW ALL CLUSTER SETTINGS. It can still be used with SET and SHOW if the exact setting name is known. Use Hide for in-development features and other settings that should not be user-visible.

func (*FloatSetting) OnChange 

func (f *FloatSetting) OnChange(fn func()) *FloatSetting

OnChange registers a callback to be called when the setting changes.

func (*FloatSetting) String 

func (f *FloatSetting) String() string

func (*FloatSetting) Typ 

func (*FloatSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*FloatSetting) Validate 

func (f *FloatSetting) Validate(v float64) error

Validate that a value conforms with the validation function.

type IntSetting 

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

IntSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "int" is updated.

func RegisterIntSetting 

func RegisterIntSetting(key, desc string, defaultValue int64) *IntSetting

RegisterIntSetting defines a new setting with type int.

func RegisterValidatedIntSetting 

func RegisterValidatedIntSetting(
	key, desc string, defaultValue int64, validateFn func(int64) error,
) *IntSetting

RegisterValidatedIntSetting defines a new setting with type int with a validation function.

func (IntSetting) Description 

func (i IntSetting) Description() string

func (*IntSetting) Get 

func (i *IntSetting) Get() int64

Get retrieves the int value in the setting.

func (IntSetting) Hidden 

func (i IntSetting) Hidden() bool

func (*IntSetting) Hide 

func (i *IntSetting) Hide()

Hide prevents a setting from showing up in SHOW ALL CLUSTER SETTINGS. It can still be used with SET and SHOW if the exact setting name is known. Use Hide for in-development features and other settings that should not be user-visible.

func (*IntSetting) OnChange 

func (i *IntSetting) OnChange(fn func()) *IntSetting

OnChange registers a callback to be called when the setting changes.

func (*IntSetting) String 

func (i *IntSetting) String() string

func (*IntSetting) Typ 

func (*IntSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*IntSetting) Validate 

func (i *IntSetting) Validate(v int64) error

Validate that a value conforms with the validation function.

type Setting 

type Setting interface {

	// Typ returns the short (1 char) string denoting the type of setting.
	Typ() string
	String() string

	Description() string

	Hidden() bool
	// contains filtered or unexported methods
}

Setting implementions wrap a val with atomic access.

func Lookup 

func Lookup(name string) (Setting, bool)

Lookup returns a Setting by name along with its description.

type StringSetting 

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

StringSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "string" is updated.

func RegisterStringSetting 

func RegisterStringSetting(key, desc string, defaultValue string) *StringSetting

RegisterStringSetting defines a new setting with type string.

func RegisterValidatedStringSetting 

func RegisterValidatedStringSetting(
	key, desc string, defaultValue string, validateFn func(string) error,
) *StringSetting

RegisterValidatedStringSetting defines a new setting with type string with a validation function.

func (StringSetting) Description 

func (i StringSetting) Description() string

func (*StringSetting) Get 

func (s *StringSetting) Get() string

Get retrieves the string value in the setting.

func (StringSetting) Hidden 

func (i StringSetting) Hidden() bool

func (*StringSetting) Hide 

func (i *StringSetting) Hide()

Hide prevents a setting from showing up in SHOW ALL CLUSTER SETTINGS. It can still be used with SET and SHOW if the exact setting name is known. Use Hide for in-development features and other settings that should not be user-visible.

func (*StringSetting) OnChange 

func (s *StringSetting) OnChange(fn func()) *StringSetting

OnChange registers a callback to be called when the setting changes. This overrides the `common“ impl to return the concrete impl type.

func (*StringSetting) String 

func (s *StringSetting) String() string

func (*StringSetting) Typ 

func (*StringSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*StringSetting) Validate 

func (s *StringSetting) Validate(v string) error

Validate that a value conforms with the validation function.

type Updater 

type Updater map[string]struct{}

Updater is a helper for updating the in-memory settings.

RefreshSettings passes the serialized representations of all individual settings -- e.g. the rows read from the system.settings table. We update the wrapped atomic settings values as we go and note which settings were updated, then set the rest to default in Done().

func MakeUpdater 

func MakeUpdater() Updater

MakeUpdater returns a new Updater, pre-alloced to the registry size.

func (Updater) Done 

func (u Updater) Done()

Done sets all settings not updated by the updater to their default values.

func (Updater) Set 

func (u Updater) Set(key, rawValue, vt string) error

Set attempts to parse and update a setting and notes that it was updated.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.