verschlimmbesserung.core — verschlimmbesserung 0.1.3

Core Raft API operations over HTTP. Clients are currently stateless, but you may maintain connection pools going forward. In general, one creates a client using (connect) and uses that client as the first argument to all API functions.

Every operation may take a map of options as an optional final argument. These options are remapped from :clojure-style keys to their Raft equivalents and passed as the query parameters of the request; with the exception of a few keys like :timeout; see http-opts for details.

Functions with a bang, like reset!, mutate state. All other functions are pure.

Some functions come in pairs, like get and get*.

The get* variant returns the full etcd response body as a map, as specified by http://coreos.com/docs/distributed-configuration/etcd-api/. Note that values are strings; verschlimmbesserung does not provide value serialization/deserialization yet.

The get variant returns a more streamlined representation: just the node value itself.

api-version clj

base-url clj

(base-url client)

Constructs the base URL for all etcd requests. Example:

(base-url client) ; => "http://127.0.0.1:4001/v2"

cas! clj

(cas! client key value value')

(cas! client key value value' opts)

Compare and set based on the current value. Updates key to be value' iff the current value of key is value. Optionally, you may also constrain the previous index and/or the existence of the key. Returns false for CAS failure. Options:

:timeout :ttl :prev-value :prev-index :prev-exist?

cas-index! clj

(cas-index! client key index value')

(cas-index! client key index value' opts)

Compare and set based on the current value. Updates key to be value' iff the current index key matches. Optionally, you may also constrain the previous value and/or the existence of the key. Returns truthy if CAS succeeded; false otherwise. Options:

:timeout :ttl :prev-value :prev-index :prev-exist?

connect clj

(connect server-uri)

(connect server-uri opts)

Creates a new etcd client for the given server URI. Example:

(def etcd (connect "http://127.0.0.1:4001"))

Options:

:timeout How long, in milliseconds, to wait for requests. :swap-retry-delay Roughly how long to wait between CAS retries in swap!

create! clj

(create! client path value)

(create! client path value opts)

Creates a new, automatically named object under the given path with the given value, and returns the full key of the created object. Options:

:timeout :ttl

create!* clj

(create!* client path value)

(create!* client path value opts)

decompose-string clj

(decompose-string s)

Splits a string on slashes, ignoring any leading slash.

default-swap-retry-delay clj

How long to wait (approximately) between retrying swap! operations which failed. In milliseconds.

default-timeout clj

milliseconds

delete! clj

(delete! client key)

(delete! client key opts)

Deletes the given key. Options:

:timeout :dir? :recursive?

delete-all! clj

(delete-all! client key)

(delete-all! client key opts)

Deletes all nodes, recursively if necessary, under the given directory. Options:

:timeout

encode-key clj

(encode-key k)

Return a url-encoded key string for a key.

encode-key-seq clj

(encode-key-seq key-seq)

Return a url-encoded key string for a key sequence.

get clj

(get client key)

(get client key opts)

Gets the current value of a key. If the key does not exist, returns nil. Single-node queries return the value of the node itself: a string for leaf nodes; a sequence of keys for a directory.

(get client [:cats :mittens]) => "the cat"

Directories have nil values unless :recursive? is specified.

(get client :cats) => {"mittens" "the cat" "more cats" nil}

Recursive queries return a nested map of string keys to nested maps or, at the leaves, values.

(get client :cats {:wait-index 4 :recursive? true}) => {"mittens" "black and white" "snowflake" "white" "favorites" {"thomas o'malley" "the alley cat" "percival" "the professor"}}

Options:

:recursive? :consistent? :quorum? :sorted? :wait? :wait-index :timeout

get* clj

(get* client key)

(get* client key opts)

http-opts clj

(http-opts client opts)

Given a map of options for a request, constructs a clj-http options map. :timeout is used for the socket and connection timeout. Remaining options are passed as query params.

key-url clj

(key-url client key)

The URL for a particular key.

(key-url client "foo") ; => "http://127.0.0.1:4001/v2/keys/foo

node->pair clj

(node->pair prefix-len node)

Transforms an etcd node representation of a directory into a [key value] pair, recursively. Prefix is the length of the key prefix to drop; etcd represents keys as full paths at all levels.

node->value clj

(node->value node)

(node->value prefix node)

Transforms an etcd node representation into a value, recursively. Prefix is the length of the key prefix to drop; etcd represents keys as full paths at all levels.

normalise-key clj

(normalise-key key)

Return the key as a sequence of key elements. A key can be specified as a string, symbol, keyword or sequence thereof. A nil key maps to [""], the root.

normalise-key-element clj

(normalise-key-element key)

String, symbol, and keyword keys map to their names; e.g. "foo", :foo, and 'foo are equivalent.

Numbers map to (str num).

parse clj macro

(parse expr)

Parses regular responses using parse-resp, but also rewrites slingshot exceptions to have a little more useful structure; bringing the json error response up to the top level and merging in the http :status.

parse-json clj

(parse-json str-or-stream)

Parse an inputstream or string as JSON

parse-resp clj

(parse-resp response)

Takes a clj-http response, extracts the body, and assoc's status and Raft X-headers as metadata (:etcd-index, :raft-index, :raft-term) on the response's body.

prefix-key clj

(prefix-key prefix key)

For a given key, return a key sequence, prefixed with the given key element.

remap-keys clj

(remap-keys f m)

Given a map, transforms its keys using the (f key). If (f key) is nil, preserves the key unchanged.

(remap-keys inc {1 :a 2 :b}) ; => {2 :a 3 :b}

(remap-keys {:a :a'} {:a 1 :b 2}) ; => {:a' 1 :b 2}

reset! clj

(reset! client key value)

(reset! client key value opts)

Resets the current value of a given key to value. Options:

:ttl :timeout

swap! clj

(swap! client key f & args)

Atomically updates the value at the given key to be (f old-value & args). Randomized backoff based on the client's swap retry delay. Returns the successfully set value.

url clj

(url client key-seq)

The URL for a key under a specified root-key.

(url client ["keys" "foo"]) ; => "http://127.0.0.1:4001/v2/keys/foo