excetera v0.0.2 Excetera

Simpler interface on top of Excetera.API.

In all the functions here that take path, it should be a string beginning with a slash (/).

Summary

Functions

Delete the value at path

Delete the value at path

Get the value at path and return {:ok, <value>} or {:error, <reason>}

Get the value at path and raise in case of failure

Get the value at path

Synonym for get(path, default, [type: :term] ++ options)

List directory contents at path

List directory contents at path

Create a new directory at path

Create a new directory at path

Create a new in-order key in directory at path

Create a new in-order key in directory at path

Remove an empty directory at path

Remove an empty directory at path

Set the value at path

Set the value at path and raise in case of failure

Synonym for set(path, value, [type: :term] ++ options)

Functions

delete(path, options \\ [])

Delete the value at path.

Returns :ok in case of success.

If path was not found, returns {:error, "Key not found"}.

If path points to a directory, removes it if recursive: true option is passed, otherwise returns {:error, "Not a file"}.

Options

  • condition: [...] - a list of predicates, effectively performs atomic compare-and-delete in etcd terms
  • timeout: <int> - request timeout in milliseconds

etcd options

  • recursive: <bool> - if true, and path points to a directory, delete the directory with its children

Reference: https://coreos.com/docs/distributed-configuration/etcd-api/#toc_7,

       https://coreos.com/docs/distributed-configuration/etcd-api/#toc_16

Examples

Excetera.delete("/test/dir", recursive: true)

Excetera.delete("/test/key", condition: [prevValue: "<secret>"])
delete!(path, options \\ [])

Delete the value at path.

Returns :ok in case of success, raises Excetera.KeyError otherwise.

See delete/2 for details.

fetch(path, options \\ [])

Get the value at path and return {:ok, <value>} or {:error, <reason>}.

If type: <type> option is passed, it will try to parse the value and will raise in case of failure. By default, the argument is interpreted as a string and returned as is.

If path points to a directory, {:error, "Not a file"} will be returned unless dir: true option is passed.

Options

  • type: <type> - specifies how to parse the obtained value
  • dir: <bool> - if true, return the contents of the directory as a map
  • timeout: <int> - request timeout in milliseconds

Types

  • :str (default) - do not transform the value in any way
  • :json - the value is decoded as JSON
  • :term - the value is decoded with :erlang.binary_to_term
  • <function> - the value is passed through the provided function of one argument

etcd options

  • wait: <bool> - if true, waits for the value at path to change; the timeout is reset to :infinity unless overriden explicitly

  • waitIndex: <int> - specify the point in etcd’s timeline to start waiting from
fetch!(path, options \\ [])

Get the value at path and raise in case of failure.

See fetch/2 for details.

get(path, default, options \\ [])

Get the value at path.

If the value is not available, or a timeout was triggered, or it failed to parse, default will be returned.

If path points to a directory, it will return its contents if dir: true option is passed; will raise Excetera.KeyError otherwise.

See fetch/2 for details.

Reference: https://coreos.com/docs/distributed-configuration/etcd-api/#toc_5

Examples

Excetera.get("/non/existent/key", 123)
#=> 123

Excetera.get("/timeout/too/small", 'abc', timeout: 1)
#=> 'abc'
get_term(path, default, options \\ [])

Synonym for get(path, default, [type: :term] ++ options).

Examples

Excetera.set_term("/test/term", {'hello', :world})
Excetera.get_term("/test/term", :novalue)
#=> {'hello', :world})
lsdir(path, options \\ [])

List directory contents at path.

Returns {:ok, <contents>} or {:error, <reason>}. In particular, if path does not point to a directory, returns {:error, "Not a directory"}.

Depending on the value of the :sorted option, returns the contents of a directory as a map (default) or as a list.

Options

  • timeout: <int> - request timeout in milliseconds

etcd options

  • sorted: <bool> - when true, returns the contents as a list; useful when fetching the contents of a directory with in-order keys
  • recursive: <bool> - whether to fetch the contents of child directories

Reference: https://coreos.com/docs/distributed-configuration/etcd-api/#toc_15

Examples

Excetera.set!("/test/dir/a", 1)
Excetera.set!("/test/dir/b/c", 2)

Excetera.lsdir("/test/dir")
#=> {:ok, %{"a" => "1", "b" => %{}}}

Excetera.lsdir("/test/dir", recursive: true)
#=> {:ok, %{"a" => "1", "b" => %{"c" => "2"}}}
lsdir!(path, options \\ [])

List directory contents at path.

Returns just the contents or raises in case of failure.

See lsdir/2 for details.

mkdir(path, options \\ [])

Create a new directory at path.

Accepts the same set of options as set/3 except for the :type one.

Returns :ok or {:error, <reason>}.

Reference: https://coreos.com/docs/distributed-configuration/etcd-api/#toc_14

mkdir!(path, options \\ [])

Create a new directory at path.

Returns :ok or raises Excetera.KeyError.

See mkdir/2 for details.

put(path, value, options \\ [])

Create a new in-order key in directory at path.

Returns {:ok, <key>} with the new key in case of success or {:error, <reason>} in case of failure.

Options

  • type: <type> - same as in set/3
  • timeout: <int> - request timeout in milliseconds

etcd options

  • ttl: <int> - set the time-to-live for the value in seconds

Reference: https://coreos.com/docs/distributed-configuration/etcd-api/#toc_10

Examples

{:ok, key1} = Excetera.put("/put_test/dir", "hello")
key2 = Excetera.put!("/put_test/dir", "world")
"world" = Excetera.fetch!("/put_test/dir/" <> key2)
put!(path, value, options \\ [])

Create a new in-order key in directory at path.

Returns just the new key or raises.

See put/3 for details.

rmdir(path, options \\ [])

Remove an empty directory at path.

Returns :ok or {:error, <reason>}.

Accepts the same set of options as delete/2.

rmdir!(path, options \\ [])

Remove an empty directory at path.

Returns :ok or raises Excetera.KeyError.

See rmdir/2 for details.

set(path, value, options \\ [])

Set the value at path.

If type: <type> option is passed, it will try to encode the value and will raise in case of failure. By default, the argument is passed through to_string().

If path points to a directory, {:error, "Not a file"} will be returned.

Options

  • type: <type> - specifies how to encode the value before sending
  • condition: [...] - a list of predicates, effectively performs atomic compare-and-swap in etcd terms
  • timeout: <int> - request timeout in milliseconds

Types

  • :str (default) - pass the value through to_string()
  • :json - the value is encoded as JSON
  • :term - the value is encoded with :erlang.binary_to_term
  • <function> - the value is passed through the provided function of one argument that should return a string

etcd options

  • ttl: <int> - set the time-to-live for the value in seconds

Reference: https://coreos.com/docs/distributed-configuration/etcd-api/#toc_3,

       https://coreos.com/docs/distributed-configuration/etcd-api/#toc_12

Examples

Excetera.set("/test/key", 123, condition: [prevValue: "122"])

Excetera.set("/test/key", 123, ttl: 13, condition: [prevExist: false])
set!(path, value, options \\ [])

Set the value at path and raise in case of failure.

See set/3 for details.

set_term(path, value, options \\ [])

Synonym for set(path, value, [type: :term] ++ options).

Examples

Excetera.set_term("/test/term", {'hello', :world})
Excetera.get_term("/test/term", :novalue)
#=> {'hello', :world})