Consul Key/Value Storage Notes - Brief

consul.kv.md

SYNOPSIS Consul Key/Value Storage Notes

DESCRIPTION Structure and function of consul key-value storage. Easier to find and slightly less verbose than the resources on the Consul documentation and sources

WIRE FORMAT Annotated json encoding (raw format differs)

	[
	  {
		// Key is the key
    	"Key": "some/path/to/somewhere",

		// Value is the key's value
		"Value": "dGVzdA==",

		// CreateIndex is a number that represents key creation
		"CreateIndex": 100,

		// ModifyIndex counts upward from CreateIndex every time key is modified 
		"ModifyIndex": 200,

		// LockIndex counts the total n.o. times the key was acquired by a session
		"LockIndex": 200,

		// Flags are user-defined uint64 bit vectors
		"Flags": 0,

		// Session is a unique bitstring that identifies the resource currently holding
		// the lock on this key
		"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
		}
	]

OPERATIONS

1.) Create & Update - PUT - Non-blocking - No consistency guarantees

// This is not a real go struct; they're actually URL-encoded query parameters
type Param struct{
	// key is the path to the key, which looks like a file-system path on UNIX
	// without the leading '/'. This value can be cleaned and operated on from
	// Go's "path" package
	key string 
	
	// Dc (datacenter) is where the key is updated. Key-value stores aren't
	// replicated across datacenters.
	dc	string // datacenter (optional) 
	
	// Flags are user-defined flags; nothing special
	flags uint64 
	
	// cas (Compare and Set)
	// If cas is zero, consul won't update an existing key
	// Otherwise, cas only updates the key if cas == ModifiedIndex
	// at the time of the request
	cas uint64
	
	// Acquire carries a session ID, a random bitstring generated by
	// consul. If set, consul will update the value if the key doesn't
	// exist, the key isn't locked, or the key is locked by the session
	// represented by the acquire bitstring. (likewise, consul will create
	// and acquire a key-value pair that doesn't exist yet)
	//
	// Acquire uses the locking "honor system". Writers that
	// set acquire respect the locking semantics, but other writers do not
	// meaning if you set it for one writer you have to set it for all of them
	// (unless you want them writing over your value for a specific reason)
	//
	// A counter in the key-value pair, known as LockIndex, is incremented
	// every time the lock is acquired by a session.
	acquire string
}

2.) Read - GET - Blocking - Supports consistency

type Param struct{
	key string
	dc string
	
	// Recurse reads a tree of keys by prefix. What this actually does depends
	// on the value of 'keys', see below for 'keys'
	recurse bool
	
	// Keys, if true, tells consul to return a list of keys matching a prefix but
	// not those keys' values. If false, a recursive read returns the values too.
	keys bool
	
	// Raw tells consul to return the key-value's raw data instead of encoding
	// it in a web-safe transport format "application/json". Metadata is not
	// included if this is set
	raw bool
	
	// Separator is the character to use as a seperator. Changing this is probably
	// not a good idea
	seperator string
}

3.) Delete - DELETE - Non-blocking - No consistency guarantees

type Param struct{
	key string 
	
	// Recurse deletes a tree of keys by prefix, it assumes that key is a prefix
	recurse bool
	
	// cas has the same semantics as in Create/Update. 
	cas uint64
}