EtcdClient

EtcdClient v0.2.0-alpha.2 EtcdClient View Source

This module provides basic ETCD watch, lease, and kv functionality, it is incomplete and still in development.

Opens a grpc connection channel to etcd with hostname and port provided in 'opts' keyword list. Registers the channel with name provided in 'opts' keyword list.

To start from a supervisor: add to config.exs:

config :myapp,
  etcd: [
    hostname: "localhost",
    port: "2379"
  ]

Add to supervisor child list:

  {EtcdClient, [Keyword.put(Application.get_env(:myapp, :etcd), :name, ETCD)]}

To use above connection pass the name you provided as the 'conn' argument to EtcdClient functions:

  {:ok, response} = EtcdClient.put_kv_pair(ETCD, key, value)

To establish an etcd lease and associate a kv pair:

  {:ok, response} = EtcdClient.start_lease(ETCD, lease_id, time_to_live)
  {:ok, pid} = EtcdClient.keep_lease_alive(ETCD, lease_id, keep_alive_interval)
  {:ok, response} = EtcdClient.put_kv_pair(ETCD, key, value, lease_id)

To establish an etcd watch over a range of keys:

  {:ok, pid} = EtcdClient.start_watcher(ETCD, watcher_id, from)
  EtcdClient.add_watch(start_range, end_range, watcher_id, watch_id)

Events recieved by the watcher will be sent to the pid provided in the from argument, to retrieve them if using a GenServer add:

  def handle_info({:watch_event, event} , state) do
    watch_response = elem(event, 1)
    Enum.each(watch_response.events, fn(e) -> process_watch_event(e) end)
    {:noreply, 1}
  end

If using the latest master branch of etcd (3.3+git) you can add multiple watches to the same watcher. Older versions will ignore the watch_id and you will need to start a separate watcher(with unique ids) for each individual watch.

For more information on etcd request and response types see the generated proto files in /lib/priv on github.

Link to this section Summary

Functions

add_lock(conn, name, lease_id)
add_watch(watcher_id, watch_create_request)

Adds a watch to EtcdClient.Watcher with given 'watcher_id' using provided 'watch_create_request'

add_watch(start_key, end_key, watcher_id, watch_id)

Adds an etcd watch on key range to the EtcdClient.Watcher with given 'watcher_id'. Function to start a basic watch with default etcd options

cancel_watch(watcher_id, watch_id)

Sends a watch cancel request to etcd on the stream for provided 'watcher_id' to cancel the watch with provided 'watch_id'

child_spec(opts)
close_connection(conn)

Closes and unregisters the grpc connection registered under 'conn'

delete_kv_pair(conn, key)

Sends a delete range request to etcd on grpc channel registered under 'conn' deleting the kv pair associated with 'key'. Returns {:ok, number_off_keys_deleted}

delete_kv_range(conn, delete_range_request)

Sends a delete range request to etcd using provided 'delete_range_request' and returns the full delete range response. Use this function if you need the full response

delete_kv_range(conn, key, range)

Sends a delete range request to etcd on grpc channel registered under 'conn' deleting the kv range between 'key' and 'range'. Returns {:ok, number_of_keys_deleted}

get_kv_pair(conn, key)

Sends a range request to etcd on grpc channel registered under 'conn'. Returns the kv pair associated with 'key' if it exists in the form of a list of key/value/lease maps

get_kv_range(conn, range_request)

Sends a range request to etcd using provided 'range_request' and returns the full etcd range response. Use this function if you need the full range response

get_kv_range(conn, key, range)

Sends a range request to etcd on grpc channel registered under 'conn'. Returns the kv range between 'key' and 'range' if any exist in the form of a list of key/value/lease maps

get_leases(conn)

Returns all active leases on the given etcd 'conn' as a list of lease_ids

keep_lease_alive(conn, id, keep_alive_interval)

Starts an EtcdClient.Lease. EtcdClient.Lease opens an etcd lease keep alive stream and sends keep alive requests for given 'id' every 'keep_alive_interval' in miliseconds

kill_watcher(watcher_id)
put_kv_pair(conn, put_request)

Sends a PUT request to etcd with provided 'put_request' and returns full put response. Use this function if you need prev_kv data or the full put response

put_kv_pair(conn, key, value)

Sends a put request to etcd on grpc channel registered under 'conn' with 'key' and 'value' as the key value pair to be put. Returns {:ok, %{key, value}}

put_kv_pair(conn, key, value, lease_id)

Sends a PUT request to etcd on grpc channel registered under 'conn' with 'key' and 'value' as the key value pair to be put and assigined to the lease provided in 'lease_id' Returns {:ok, %{key, value, lease}}

revoke_lease(conn, id)

Revokes an etcd lease with the given 'id' and kills it's keep alive process if it exists

start_lease(conn, ttl)

Sends a lease grant request to etcd on grpc channel registered under 'conn' with time to live 'ttl' Returns {:ok, %{lease_id, lease_ttl, error}}

start_lease(conn, id, ttl)

Sends a lease grant request to etcd on grpc channel registered under 'conn' with 'id' and time to live 'ttl' Returns {:ok, %{lease_id, lease_ttl, error}}

start_link(opts)
start_watcher(conn, id, from)

Starts an EtcdClient.Watcher with the given 'id'. Opens an etcd watch stream that etcd watches can be added to. EtcdClient.Watcher supports multiple etcd watches on a single stream. If more than one stream is needed start another EtcdClient.Watcher with a different id. Watch events will be sent to the pid provided in the from argument.

Link to this section Functions

Link to this function

add_lock(conn, name, lease_id)

View Source 
add_lock(term(), binary(), integer()) :: {:ok, V3lockpb.LockResponse.t()}
Link to this function

add_watch(watcher_id, watch_create_request)

View Source 
add_watch(term(), Etcdserverpb.WatchCreateRequest.t()) :: :ok

Adds a watch to EtcdClient.Watcher with given 'watcher_id' using provided 'watch_create_request'

Link to this function

add_watch(start_key, end_key, watcher_id, watch_id)

View Source 
add_watch(binary(), binary(), term(), integer()) :: :ok

Adds an etcd watch on key range to the EtcdClient.Watcher with given 'watcher_id'. Function to start a basic watch with default etcd options

Link to this function

cancel_watch(watcher_id, watch_id)

View Source 
cancel_watch(term(), integer()) :: :ok

Sends a watch cancel request to etcd on the stream for provided 'watcher_id' to cancel the watch with provided 'watch_id'

Link to this function

child_spec(opts)

View Source
Link to this function

close_connection(conn)

View Source 
close_connection(term()) :: :ok

Closes and unregisters the grpc connection registered under 'conn'

Link to this function

delete_kv_pair(conn, key)

View Source 
delete_kv_pair(term(), binary()) ::
  {:ok, integer()} | {:error, GRPC.RPCError.t()}

Sends a delete range request to etcd on grpc channel registered under 'conn' deleting the kv pair associated with 'key'. Returns {:ok, number_off_keys_deleted}

Link to this function

delete_kv_range(conn, delete_range_request)

View Source 
delete_kv_range(term(), Etcdserverpb.DeleteRangeRequest.t()) ::
  {:ok, Etcdserverpb.DeleteRangeResponse.t()} | {:error, GRPC.RPCError.t()}

Sends a delete range request to etcd using provided 'delete_range_request' and returns the full delete range response. Use this function if you need the full response

Link to this function

delete_kv_range(conn, key, range)

View Source 
delete_kv_range(term(), binary(), binary()) ::
  {:ok, integer()} | {:error, GRPC.RPCError.t()}

Sends a delete range request to etcd on grpc channel registered under 'conn' deleting the kv range between 'key' and 'range'. Returns {:ok, number_of_keys_deleted}

Link to this function

get_kv_pair(conn, key)

View Source 
get_kv_pair(term(), binary()) :: {:ok, list()} | {:error, GRPC.RPCError.t()}

Sends a range request to etcd on grpc channel registered under 'conn'. Returns the kv pair associated with 'key' if it exists in the form of a list of key/value/lease maps

Link to this function

get_kv_range(conn, range_request)

View Source 
get_kv_range(term(), Etcdserverpb.RangeRequest.t()) ::
  {:ok, Etcdserverpb.RangeResponse.t()} | {:error, GRPC.RPCError.t()}

Sends a range request to etcd using provided 'range_request' and returns the full etcd range response. Use this function if you need the full range response

Link to this function

get_kv_range(conn, key, range)

View Source 
get_kv_range(term(), binary(), binary()) ::
  {:ok, list()} | {:error, GRPC.RPCError.t()}

Sends a range request to etcd on grpc channel registered under 'conn'. Returns the kv range between 'key' and 'range' if any exist in the form of a list of key/value/lease maps

Link to this function

get_leases(conn)

View Source 
get_leases(term()) :: {:ok, list()} | {:error, GRPC.RPCError.t()}

Returns all active leases on the given etcd 'conn' as a list of lease_ids

Link to this function

keep_lease_alive(conn, id, keep_alive_interval)

View Source 
keep_lease_alive(term(), integer(), integer()) :: {:ok, pid()}

Starts an EtcdClient.Lease. EtcdClient.Lease opens an etcd lease keep alive stream and sends keep alive requests for given 'id' every 'keep_alive_interval' in miliseconds

Link to this function

kill_watcher(watcher_id)

View Source 
kill_watcher(term()) :: :ok | {:error, String.t()}
Link to this function

put_kv_pair(conn, put_request)

View Source 
put_kv_pair(term(), Etcdserverpb.PutRequest.t()) ::
  {:ok, Etcdserverpb.PutResponse.t()} | {:error, GRPC.RPCError.t()}

Sends a PUT request to etcd with provided 'put_request' and returns full put response. Use this function if you need prev_kv data or the full put response

Link to this function

put_kv_pair(conn, key, value)

View Source 
put_kv_pair(conn :: term(), key :: binary(), value :: binary()) ::
  {:ok, map()} | {:error, GRPC.RPCError.t()}

Sends a put request to etcd on grpc channel registered under 'conn' with 'key' and 'value' as the key value pair to be put. Returns {:ok, %{key, value}}

Link to this function

put_kv_pair(conn, key, value, lease_id)

View Source 
put_kv_pair(term(), binary(), binary(), integer()) ::
  {:ok, map()} | {:error, GRPC.RPCError.t()}

Sends a PUT request to etcd on grpc channel registered under 'conn' with 'key' and 'value' as the key value pair to be put and assigined to the lease provided in 'lease_id' Returns {:ok, %{key, value, lease}}

Link to this function

revoke_lease(conn, id)

View Source 
revoke_lease(term(), integer()) :: {:ok, :revoked} | {:error, GRPC.RPCError.t()}

Revokes an etcd lease with the given 'id' and kills it's keep alive process if it exists

Link to this function

start_lease(conn, ttl)

View Source 
start_lease(term(), integer()) :: {:ok, map()} | {:error, GRPC.RPCError.t()}

Sends a lease grant request to etcd on grpc channel registered under 'conn' with time to live 'ttl' Returns {:ok, %{lease_id, lease_ttl, error}}

Link to this function

start_lease(conn, id, ttl)

View Source 
start_lease(term(), integer(), integer()) ::
  {:ok, map()} | {:error, GRPC.RPCError.t()}

Sends a lease grant request to etcd on grpc channel registered under 'conn' with 'id' and time to live 'ttl' Returns {:ok, %{lease_id, lease_ttl, error}}

Link to this function

start_link(opts)

View Source 
start_link(keyword()) :: {:ok, pid()} | {:error, String.t()}
Link to this function

start_watcher(conn, id, from)

View Source 
start_watcher(term(), term(), pid()) :: {:ok, GRPC.Server.Stream.t()}

Starts an EtcdClient.Watcher with the given 'id'. Opens an etcd watch stream that etcd watches can be added to. EtcdClient.Watcher supports multiple etcd watches on a single stream. If more than one stream is needed start another EtcdClient.Watcher with a different id. Watch events will be sent to the pid provided in the from argument.