pkg/store: Update documentation with latest changes

Signed-off-by: Alexandre Beslic <abronan@docker.com>

pkg/store/README.md

@@ -1,6 +1,10 @@
 # Storage
 
-This package is used by the discovery service to register machines inside the cluster. It is also used to store cluster's metadata.
+The goal of `pkg/store` is to abstract common store operations for multiple Key/Value backends.
+
+For example, you can use it to store your metadata or for service discovery to register machines and endpoints inside your cluster.
+
+As of now, `pkg/store` offers support for `Consul`, `Etcd` and `Zookeeper`.
 
 ## Example of usage
 
@@ -19,15 +23,16 @@ import (
 
 func main() {
 	var (
+		// Consul local address
 		client = "localhost:8500"
 	)
 
 	// Initialize a new store with consul
-	kv, err := store.CreateStore(
-		store.Consul,
+	kv, err = store.NewStore(
+		store.CONSUL, // or "consul"
 		[]string{client},
-		store.Config{
-		    Timeout: 10*time.Second
+		&store.Config{
+			Timeout: 10*time.Second,
 		},
 	)
 	if err != nil {
@@ -35,17 +40,17 @@ func main() {
 	}
 
 	key := "foo"
-	err = kv.Put(key, []byte("bar"))
+	err = kv.Put(key, []byte("bar"), nil)
 	if err != nil {
 		log.Error("Error trying to put value at key `", key, "`")
 	}
 
-	value, _, err := kv.Get(key)
+	pair, err := kv.Get(key)
 	if err != nil {
 		log.Error("Error trying accessing value at key `", key, "`")
 	}
 
-	log.Info("value: ", string(value))
+	log.Info("value: ", string(pair.Value))
 }
 ```
 
@@ -57,23 +62,22 @@ A new **storage backend** should include those calls:
 
 ```go
 type Store interface {
-	Put(key string, value []byte) error
-	Get(key string) (value []byte, lastIndex uint64, err error)
+	Put(key string, value []byte, options *WriteOptions) error
+	Get(key string) (*KVPair, error)
 	Delete(key string) error
 	Exists(key string) (bool, error)
-	Watch(key string, ttl uint64, callback WatchCallback) error
-	CancelWatch(key string) error
-	Acquire(key string, value []byte) (string, error)
-	Release(session string) error
-	GetRange(prefix string) (value [][]byte, err error)
-	DeleteRange(prefix string) error
-	WatchRange(prefix string, filter string, heartbeat uint64, callback WatchCallback) error
-	CancelWatchRange(prefix string) error
-	AtomicPut(key string, oldValue []byte, newValue []byte, index uint64) (bool, error)
-	AtomicDelete(key string, oldValue []byte, index uint64) (bool, error)
+	Watch(key string, stopCh <-chan struct{}) (<-chan *KVPair, error)
+	WatchTree(prefix string, stopCh <-chan struct{}) (<-chan []*KVPair, error)
+	NewLock(key string, options *LockOptions) (Locker, error)
+	List(prefix string) ([]*KVPair, error)
+	DeleteTree(prefix string) error
+	AtomicPut(key string, value []byte, previous *KVPair, options *WriteOptions) (bool, *KVPair, error)
+	AtomicDelete(key string, previous *KVPair) (bool, error)
 }
 ```
 
-To be elligible as a **discovery backend** only, a K/V store implementation should at least offer `Get`, `Put`, `WatchRange`, `GetRange`.
+In the case of Swarm and to be eligible as a **discovery backend** only, a K/V store implementation should at least offer `Get`, `Put`, `WatchTree` and `List`.
+
+`Put` should support usage of `ttl` to be able to remove entries in case of a node failure.
 
 You can get inspiration from existing backends to create a new one. This interface could be subject to changes to improve the experience of using the library and contributing to a new backend.