Documentation
¶
Overview ¶
Package metakv2 provides a KV API to ns_server's metakv2 store, which keeps its values in chronicle rather than in ns_config.
Leaf operations are covered here, along with the removal of a whole directory and the quorum wait a fresh read needs. The store also has directory creation and listing, bulk mutations and snapshot reads, none of which have a caller in Go yet.
Two things differ from the metakv package:
A key lives in a directory, and a leaf directly under the root is not allowed. So the shallowest usable path is of the form /dir/key. The enclosing directories are created on demand.
A leaf may be marked sensitive, which keeps its value out of the store's own logs.
Sensitivity is fixed when the leaf is created: an update carries it forward, and the store refuses a write that explicitly states the opposite of what is stored. Recreating the leaf is the only way to change it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrKeyExists = errors.New("Key exists")
ErrKeyExists is returned from Add and AddSensitive when the key is already there.
var ErrNotFound = errors.New("Not found")
ErrNotFound is returned from Get when the key does not exist.
var ErrRevMismatch = errors.New("Rev mismatch")
ErrRevMismatch is returned from Set when the revision passed in does not match the one currently stored. Re-read the key and try again.
var ErrSensitiveUnsupported = errors.New(
"Sensitive keys are not supported until the cluster is fully upgraded")
ErrSensitiveUnsupported is returned from AddSensitive while the cluster is not yet fully upgraded. A caller should wait and retry.
var ErrTimeout = errors.New("Timeout")
ErrTimeout is returned from SyncQuorum when a quorum was not reached in time.
Functions ¶
func RecursiveDelete ¶
RecursiveDelete removes the given directory and everything underneath it, keys and directories alike, in one transaction. Deleting a directory that does not exist is not an error.
The path names the directory the same way a key is named, with no trailing "/". Note that a directory may sit directly under the root, so passing a one segment path such as "/dir" discards everything the package ever put under it.
func SyncQuorum ¶
SyncQuorum waits until this node's copy of the store has caught up with everything a quorum of nodes has committed. A Get reads this node's copy, which can lag behind what another node has written, so a caller that must not act on a stale value calls this first. ErrTimeout is returned if no quorum was reached in time.
The timeout must be between one second and six minutes, which is the range the store accepts. Zero leaves the wait to the store's own default.
Types ¶
type Entry ¶
Entry is what Get returns about a leaf.
func Get ¶
Get returns the given key, or ErrNotFound if it does not exist.
It does not report whether the leaf is sensitive, and Entry has no field for it. A caller that names a key already knows what it put there, and a flag checked at runtime would be the weaker guard, since it holds only as long as the leaf was tagged correctly to begin with. The store does report it when listing a directory, where the caller receives keys it did not name, and this package has no listing call yet.
type Rev ¶
type Rev string
Rev is a revision of a leaf, used as a CAS value to detect races with concurrent mutators.
func Add ¶
Add creates the given key, which must not exist yet, and returns the revision it was created at. ErrKeyExists is returned if the key is already there. Any missing directories along the path are created.
func AddSensitive ¶
AddSensitive is Add for a value that must not be recorded in the logs.
The cluster has to be fully upgraded to accept a sensitive key, and ErrSensitiveUnsupported is returned until it is. Nothing is written in that case, and the same call succeeds once the upgrade completes.
func Set ¶
Set updates the given key, creating it if it does not exist, and returns the revision the key now has. That revision can be passed to a later Set to make it conditional, with no Get in between.
A non-empty rev makes this update conditional on the stored revision still matching, and ErrRevMismatch is returned if it does not. Writing the value that is already stored is not an error, and reports the revision the key already had, since nothing was committed.
A key that Set creates is not sensitive. The flag can only be set when a key is created and AddSensitive is the only way to create one that is.
A key created by AddSensitive stays sensitive across a Set. There is no SetSensitive, since sensitivity cannot be changed after creation. Set never states the flag on the wire either: stating it would commit the caller to whatever is stored, and the store refuses a mismatch, so a Set that sent even sensitive=false would fail against every key created sensitive. That is what lets a caller use Set without knowing how the key was created.
Source Files