Class: Imperium::KV

Inherits:
Client show all
Defined in:
lib/imperium/kv.rb

Overview

A client for the KV API.

Constant Summary

Constants inherited from Client

Client::UNIVERSAL_API_OPTIONS

Instance Attribute Summary

Attributes inherited from Client

#config

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Client

default_client, inherited, #initialize, #path_prefix, reset_default_client, reset_default_clients

Constructor Details

This class inherits a constructor from Imperium::Client

Class Method Details

.delete(key, *options) ⇒ Object

DELETE a key using the Client.default_client

See Also:



20
21
22
 
# File 'lib/imperium/kv.rb', line 20

def self.delete(key, *options)
  default_client.delete(key, *options)
end

.get(key, *options) ⇒ Object

GET a key using the Client.default_client

See Also:



8
9
10
 
# File 'lib/imperium/kv.rb', line 8

def self.get(key, *options)
  default_client.get(key, *options)
end

.put(key, value, *options) ⇒ Object

Create or update a key using the Client.default_client

See Also:



14
15
16
 
# File 'lib/imperium/kv.rb', line 14

def self.put(key, value, *options)
  default_client.put(key, value, *options)
end

Instance Method Details

#delete(key, *options) ⇒ KVDELETEResponse

TODO:

Decide whether to support recursive deletion by accepting the :recurse parameter

Delete the specified key

Parameters:

  • key (String) —

    The key to be created or updated.

  • options (Array<Symbol,String,Hash>) —

    The options for constructing the request

Options Hash (*options):

  • :dc (String) —

    Specify the datacenter to use for the request

  • :cas (Integer) —

    Specifies to use a Check-And-Set operation. This is very useful as a building block for more complex synchronization primitives. Unlike PUT, the index must be greater than 0 for Consul to take any action: a 0 index will not delete the key. If the index is non-zero, the key is only deleted if the index matches the ModifyIndex of that key.

Returns:



123
124
125
126
127
128
 
# File 'lib/imperium/kv.rb', line 123

def delete(key, *options)
  expanded_options = hashify_options(options)
  query_params = extract_query_params(expanded_options, allowed_params: DELETE_ALLOWED_OPTIONS)
  response = @http_client.delete(prefix_path(key), query: query_params)
  KVDELETEResponse.new(response, options: expanded_options)
end

#get(key, *options) ⇒ KVGETResponse

TODO:

Support blocking queries by accepting an :index parameter

Get the specified key/prefix using the supplied options.

Examples:

Fetching a key that is allowed to be stale.

response = Imperium::KV.get('foo/bar', :stale) # => KVGETResponse...

Fetching a prefix recursively allowing values to be stale.

response = Imperium::KV.get('foo/bar', :stale, :recurse) # => KVGETResponse...

Parameters:

  • key (String) —

    The key/prefix to be fetched from Consul.

  • options (Array<Symbol,String,Hash>) —

    The options for constructing the request

Options Hash (*options):

  • :dc (String) —

    Specify the datacenter to use for the request

  • :consistent (Symbol) —

    Specify the consistent option to the API resulting in the most up to date value possible at the expense of a bit of latency and the requirement of a validly elected leader. See Consistency Modes documentation.

  • :stale (Symbol) —

    Specify the stale option to the API resulting in a potentially stale value with the benefit of a faster, more scaleable read. See Consistency Modes documentation.

  • :recurse (Symbol) —

    Supply the recurse option to the API to fetch any keys with the specified prefix.

  • :keys (Symbol) —

    Fetch only the keys with the specified prefix.

  • :separator (String) —

    See Consul’s Documentation

Returns:



61
62
63
64
65
66
 
# File 'lib/imperium/kv.rb', line 61

def get(key, *options)
  expanded_options = hashify_options(options)
  query_params = extract_query_params(expanded_options, allowed_params: GET_ALLOWED_OPTIONS)
  response = @http_client.get(prefix_path(key), query: query_params)
  KVGETResponse.new(response, prefix: key, options: expanded_options)
end

#put(key, value, *options) ⇒ KVPUTResponse

Update or create the specified key

Parameters:

  • key (String) —

    The key to be created or updated.

  • value (String) —

    The value to be set on the key.

  • options (Array<Symbol,String,Hash>) —

    The options for constructing the request

Options Hash (*options):

  • :dc (String) —

    Specify the datacenter to use for the request

  • :flags (Integer) —

    Specifies an unsigned value between 0 and (2^64)-1. Clients can choose to use this however makes sense for their application.

  • :cas (Integer) —

    Specifies to use a Check-And-Set operation. This is very useful as a building block for more complex synchronization primitives. If the index is 0, Consul will only put the key if it does not already exist. If the index is non-zero, the key is only set if the index matches the ModifyIndex of that key.

  • :acquire (String) —

    Supply a session key for use in acquiring lock on the key. From the Consul docs: Specifies to use a lock acquisition operation. This is useful as it allows leader election to be built on top of Consul. If the lock is not held and the session is valid, this increments the LockIndex and sets the Session value of the key in addition to updating the key contents. A key does not need to exist to be acquired. If the lock is already held by the given session, then the LockIndex is not incremented but the key contents are updated. This lets the current lock holder update the key contents without having to give up the lock and reacquire it.

  • :release (String) —

    Supply a session key for releasing a lock. From the Consul docs: Specifies to use a lock release operation. This is useful when paired with ?acquire= as it allows clients to yield a lock. This will leave the LockIndex unmodified but will clear the associated Session of the key. The key must be held by this session to be unlocked.

Returns:



100
101
102
103
104
105
 
# File 'lib/imperium/kv.rb', line 100

def put(key, value, *options)
  expanded_options = hashify_options(options)
  query_params = extract_query_params(expanded_options, allowed_params: PUT_ALLOWED_OPTIONS)
  response = @http_client.put(prefix_path(key), value, query: query_params)
  KVPUTResponse.new(response, options: expanded_options)
end

#transaction(*options) {|a| ... } ⇒ TransactionResponse

Perform operation in the transaction

This is useful when having a number of statements that must be executed
together or not at all.

Parameters:

  • options (Array<Symbol,String,Hash>) —

    The options for constructing the request

Options Hash (*options):

  • :dc (String) —

    Specify the datacenter to use for the request

Yield Parameters:

  • a (Transaction) —

    Transaction instance that can be used to perform operations in the transaction

Returns:



141
142
143
144
145
146
147
148
 
# File 'lib/imperium/kv.rb', line 141

def transaction(*options)
  expanded_options = hashify_options(options)
  query_params = extract_query_params(expanded_options)
  tx = Imperium::Transaction.new
  yield tx
  response = @http_client.put('v1/txn', tx.body, query: query_params)
  Imperium::TransactionResponse.new(response)
end