Documentation ¶
Overview ¶
Package etcetera is etcd client that uses a tagged struct to save and load values
Behavior ¶
We took some decisions when creating this library taking into account that less is more. The decisions are all listed bellow.
Always retrieving the last index: For the use case that we thought, there's no reason (for now) to retrieve an intermediate state of a field. We are always looking for the current value in etcd. But we store the index of all attributes retrieved from etcd so that the user wants to know it (in the library we use "version" instead of "index" because it appears to have a better context).
Setting unlimited TTL: The type of data that we store in etcd (configuration values) don't need a TTL. Or at least we did not imagine any case when it does need a TTL.
Ignoring errors occurred in watch: When something goes wrong while retrieving or parsing the data from etcd, we prefer to silent drop the update instead of setting a strange value to the configuration field. Another problem is to create a good API to notify about errors occurred in watch, the first idea is to use a channel for errors, but it doesn't appears to be a elegant approach, and more than that, what the user can do with this error? Well, we are still thinking about it.
Ignoring "directory already exist" errors: If the directory already exists, great! We go on and create the structure under this directory. There's no reason to stop everything because of this error.
Not allowing URI in structure's field tag: This was a change made on 2014-12-17. I thought that leaving the decision to the user to create an URI in a structure's field tag could cause strange behaviors when structuring the configuration in etcd. So all the slashes in the field's tag will be replaced by hyphens, except if the slash is the first or last character
Improve ¶
There are some issues that we still need to improve in the project. First, the code readability is terrible with all the reflection used, and with a good re-factory the repeated code could be reused. The full test coverage will ensure that the re-factory does not break anything.
Second, when watching a field, you will receive a channel to notify when you want to stop watching. Now if you send a boolean false into the channel instead of closing it, we could have a strange behavior since there are two go routines listening on this channel (go-etcd and etcetera watch functions).
And finally, we could have concurrency issues while updating configuration fields caused by the watch service. We still need to test the possible cases, but adding a read/write lock don't appears to be an elegant solution.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidConfig alert whenever you try to use something that is not a structure in the Save // function, or something that is not a pointer to a structure in the Load funciton ErrInvalidConfig = errors.New("etcetera: configuration must be a structure or a pointer to a structure") // ErrNotInitialized alert when you pass a structure to the Load function that has a map attribute // that is not initialized ErrNotInitialized = errors.New("etcetera: configuration has fields that are not initialized (map)") // ErrFieldNotMapped alert whenever you try to access a field that wasn't loaded in the client // structure. If we don't load the field before we cannot determinate the path or version ErrFieldNotMapped = errors.New("etcetera: trying to retrieve information of a field that wasn't previously loaded") // ErrFieldNotAddr is throw when a field that cannot be addressable is used in a place that we // need the pointer to identify the path related to the field ErrFieldNotAddr = errors.New("etcetera: field must be a pointer or an addressable value") )
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client stores the etcd connection, the configuration instance that we are managing and some extra informations that are useful for controlling path versions and making the API simpler
func NewClient ¶
NewClient internally build a etcd client object (go-etcd library). The machines attribute defines the etcd cluster that this client will be connect to. Now the namespace defines a special root directory to build the configuration URIs, and is recommended when you want to use more than one configuration structure in the same etcd. And finally the config attribute is the configuration struct that you want to send or retrieve of etcd
func NewTLSClient ¶
func NewTLSClient(machines []string, cert, key, caCert, namespace string, config interface{}) (*Client, error)
NewTLSClient internally build a etcd client object with TLS (go-etcd library). The machines attribute defines the etcd cluster that this client will be connect to. The cert, key, caCert attributes are the same from the go-etcd library to ensure the TLS connection. Now the namespace defines a special root directory to build the configuration URIs, and is recommended when you want to use more than one configuration structure in the same etcd. And finally the config attribute is the configuration struct that you want to send or retrieve of etcd
func (*Client) Load ¶
Load retrieves the data from the etcd into the given structure. Only attributes with the tag 'etcd' will be filled. Supported types are 'struct', 'slice', 'map', 'string', 'int', 'int64' and 'bool'
func (*Client) Save ¶
Save stores a structure in etcd. Only attributes with the tag 'etcd' are going to be saved. Supported types are 'struct', 'slice', 'map', 'string', 'int', 'int64' and 'bool'
func (*Client) SaveField ¶
SaveField saves a specific field from the configuration structure. Works in the same way of Save, but it can be used to save specific parts of the configuration, avoiding excessive requests to etcd cluster
func (*Client) Version ¶
Version returns the current version of a field retrieved from etcd. It does not query etcd for the latest version. When the field was not retrieved from etcd yet, the version 0 is returned
func (*Client) Watch ¶
Watch keeps track of a specific field in etcd using a long polling strategy. When a change is detected the callback function will run. When you want to stop watching the field, just close the returning channel
BUG(rafaeljusto): If the user sends a boolean false instead of closing the returning channel, we could have a strange behavior since there are two go routines listening on it (go-etcd and etcetera watch functions)
Notes ¶
Bugs ¶
If the user sends a boolean false instead of closing the returning channel, we could have a strange behavior since there are two go routines listening on it (go-etcd and etcetera watch functions)