gconf

Documentation

Overview

Package gconf provides a toolset for managing an extension configuration.

Extension that defines a configuration object can use gconf package to load initial state from genesis, update configuration state via messages and to retrieve configuration object from the store.

Each extension can declare and store only one configuration object.

To use gconf you must follow a few simple principles.

1. Define your configuration as a protobuf message.

2. Define your configuration update message as a protobuf message. It must have a `patch` field that holds the new configuration state. Add created message to the Tx declaration. Register handler in your extension routing.

3. Zero field values are ignored during the update message processing,

4. use `InitConfig` inside of your extension initializer to copy configuration from the genesis into the database,

5. Use `Load` function to load your configuration state from the database,

See existing extensions for an example of how to use this package.

Index

• func InitConfig(db Store, opts weave.Options, pkg string, conf Configuration) error
• func Load(db ReadStore, pkg string, dst Unmarshaler) error
• func RegisterQuery(qr weave.QueryRouter)
• func Save(db Store, pkg string, src ValidMarshaler) error
• type Configuration
• type OwnedConfig
• type ReadStore
• type Store
• type Unmarshaler
• type UpdateConfigurationHandler
  • func NewUpdateConfigurationHandler(pkg string, config OwnedConfig, auth x.Authenticator, ...) UpdateConfigurationHandler
  • func (h UpdateConfigurationHandler) Check(ctx weave.Context, store weave.KVStore, tx weave.Tx) (*weave.CheckResult, error)
  • func (h UpdateConfigurationHandler) Deliver(ctx weave.Context, store weave.KVStore, tx weave.Tx) (*weave.DeliverResult, error)
• type ValidMarshaler

Functions

func InitConfig

func InitConfig(db Store, opts weave.Options, pkg string, conf Configuration) error

InitConfig will take opts["conf"][pkg], parse it into the given Configuration object validate it, and store under the proper key in the database Returns an error if anything goes wrong

func Load

func Load(db ReadStore, pkg string, dst Unmarshaler) error

func RegisterQuery

func RegisterQuery(qr weave.QueryRouter)

RegisterQuery expose all configurations to queries.

func Save

func Save(db Store, pkg string, src ValidMarshaler) error

Save will Validate the object, before writing it to a special "configuration" singleton for that package name.

Types

type Configuration

type Configuration interface {
	ValidMarshaler
	Unmarshaler
}

type OwnedConfig

type OwnedConfig interface {
	Unmarshaler
	ValidMarshaler
	GetOwner() weave.Address
}

OwnedConfig must have an Owner field in protobuf. A configuration update message must be signed by an owner in order to be authorized to apply the change.

type ReadStore

type ReadStore interface {
	Get([]byte) ([]byte, error)
}

ReadStore is a subset of weave.ReadOnlyKVStore.

type Store

type Store interface {
	ReadStore
	Set([]byte, []byte) error
}

Store is a subset of weave.KVStore.

type Unmarshaler

type Unmarshaler interface {
	Unmarshal([]byte) error
}

Unmarshaler is implemented by object that can load their state from given binary representation. This interface is implemented by all protobuf messages.

type UpdateConfigurationHandler

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

func NewUpdateConfigurationHandler

func NewUpdateConfigurationHandler(
	pkg string,
	config OwnedConfig,
	auth x.Authenticator,
	initConfAdmin func(weave.ReadOnlyKVStore) (weave.Address, error),
) UpdateConfigurationHandler

NewUpdateConfigurationHandler returns a message handler that process configuration patch message.

To pass authentication step, each message must be signed by the current configuration owner.

A special chicken-egg problem appears when the configuration does not exist (it was not created via genesis). This is an issue, because without configuration we cannot configure configuration owner that can update the configuration. This means that the configuration cannot be created as well. A configuration is needed to create a configuration. To address the above issue, an optional `initConfAdmin` argument can be given to provide a creation only admin address. A good deafult is to use `migration.CurrentAdmin` function. `initConfAdmin` is used to authenticate the tranaction only when no configuration exist. Once a configuration is created, `initConfAdmin` is not used anymore and the autentication relies only on configuration's owner declaration.

func (UpdateConfigurationHandler) Check

func (h UpdateConfigurationHandler) Check(ctx weave.Context, store weave.KVStore, tx weave.Tx) (*weave.CheckResult, error)

func (UpdateConfigurationHandler) Deliver

func (h UpdateConfigurationHandler) Deliver(ctx weave.Context, store weave.KVStore, tx weave.Tx) (*weave.DeliverResult, error)

type ValidMarshaler

type ValidMarshaler interface {
	Marshal() ([]byte, error)
	Validate() error
}

ValidMarshaler is implemented by object that can serialize itself to a binary representation. Marshal is implemented by all protobuf messages. You must add your own Validate method

Note duplicate of code in x/persistent.go