Module: Consulkit::Client::KV

Included in:
Consulkit::Client
Defined in:
lib/consulkit/client/kv.rb

Overview

Methods for accessing Consul’s KV store.

Instance Method Summary collapse

Instance Method Details

#kv_acquire_lock(key, session_id, value = nil, query_params = {}) ⇒ Object

Atomically creates or updates the specified key by acquiring a lock with the session ID.

return [Boolean]

Parameters:

  • key (String) —

    the key to create or update.

  • query_params (Hash) (defaults to: {}) —

    optional query parameters.



174
175
176
 
# File 'lib/consulkit/client/kv.rb', line 174

def kv_acquire_lock(key, session_id, value = nil, query_params = {})
  kv_write(key, value, **query_params, acquire: session_id)
end

#kv_decode_response_body(body) ⇒ Object, Array<Hash>

Automatically base64 decodes the ‘Value’ of each KV entry in the body, if the body looks like a Consul KV entry list response.

as-is.

Parameters:

  • body (Object) —

    the response body to decode.

Returns:

  • (Object, Array<Hash>) —

    the body parameter, but with ‘Value’ base64 decoded, or the body parameter



205
206
207
208
209
210
211
212
213
214
 
# File 'lib/consulkit/client/kv.rb', line 205

def kv_decode_response_body(body)
  return body unless body.is_a?(Array)
  return body unless body.first.is_a?(Hash) && (body.first.key? 'Value')

  body.each do |kv_entry|
    next if kv_entry['Value'].nil?

    kv_entry['Value'] = Base64.decode64(kv_entry['Value'])
  end
end

#kv_delete(key, query_params = {}) ⇒ Object

Deletes the specified key.

return [Boolean]

Parameters:

  • key (String) —

    the key to delete.

  • query_params (Hash) (defaults to: {}) —

    optional query parameters.



194
195
196
 
# File 'lib/consulkit/client/kv.rb', line 194

def kv_delete(key, query_params = {})
  delete("/v1/kv/#{key}", query_params).body == true
end

#kv_read(key, query_params = {}) {|Faraday::Response| ... } ⇒ Array<Hash>

Reads the specified key. The value of the keys in the response are automatically base64 decoded, if applicable.

Parameters:

  • key (String) —

    the key to read.

  • query_params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query_params):

  • optional (Hash) —

    query parameters.

  • :recurse (Boolean)
  • :raw (Boolean)
  • :keys (Boolean)
  • :separator (String)

Yields:

  • (Faraday::Response) —

    The response from the underlying Faraday library.

Returns:

  • (Array<Hash>)

See Also:



51
52
53
54
55
 
# File 'lib/consulkit/client/kv.rb', line 51

def kv_read(key, query_params = {}, &block)
  kv_read!(key, query_params, &block)
rescue Consulkit::Error::NotFound
  []
end

#kv_read!(key, query_params = {}) {|Faraday::Response| ... } ⇒ Array<Hash>

Reads the specified key, raising an exception if not found. The value of the keys in the response are automatically base64 decoded, if applicable.

Parameters:

  • key (String) —

    the key to read.

  • query_params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query_params):

  • optional (Hash) —

    query parameters.

  • :recurse (Boolean)
  • :raw (Boolean)
  • :keys (Boolean)
  • :separator (String)

Yields:

  • (Faraday::Response) —

    The response from the underlying Faraday library.

Returns:

  • (Array<Hash>)

Raises:

See Also:



27
28
29
30
31
32
33
34
35
 
# File 'lib/consulkit/client/kv.rb', line 27

def kv_read!(key, query_params = {})
  response = get("/v1/kv/#{key}", query_params)

  if block_given?
    yield response
  else
    kv_decode_response_body(response.body)
  end
end

#kv_read_blocking(key, wait = nil, query_params = {}) {|changed, result| ... } ⇒ Object

Reads the specified key, then yields the result of a blocking query for that key. The value of the keys in the response are automatically base64 decoded, if applicable. Return false from the block to end the loop.

Parameters:

  • key (String) —

    the key to read.

  • query_params (Hash) (defaults to: {}) —

    optional query parameters.

Yields:

  • (changed, result)

Yield Parameters:

  • changed (Boolean) —

    true if the consul index has changed since the last query.

  • result (Array<Hash>) —

    the current result of the consul query.

See Also:



96
97
98
99
100
101
102
103
104
 
# File 'lib/consulkit/client/kv.rb', line 96

def kv_read_blocking(key, wait = nil, query_params = {})
  last_index, = kv_read_with_index(key, query_params)

  loop do
    new_index, result = kv_read_with_index(key, **query_params, wait: wait, index: last_index)

    return unless yield(new_index != last_index, result)
  end
end

#kv_read_recursive(key, query_params = {}) ⇒ <Hash>

Reads the specified key recursively. The value of the keys in the response are automatically base64 decoded, if applicable.

Parameters:

  • key (String) —

    the key to read.

  • query_params (Hash) (defaults to: {}) —

    optional query parameters.

Returns:

  • (<Hash>)

See Also:



115
116
117
 
# File 'lib/consulkit/client/kv.rb', line 115

def kv_read_recursive(key, query_params = {})
  kv_read(key, **query_params, recurse: true)
end

#kv_read_recursive_as_hash(key) ⇒ Hash<String, Hash>

Reads the specified key recursively, returning a hash where each key is indexed by its key name. The value of the keys in the response are automatically base64 decoded, if applicable.

Parameters:

  • key (String) —

    the key to read.

Returns:

  • (Hash<String, Hash>) 


125
126
127
128
129
 
# File 'lib/consulkit/client/kv.rb', line 125

def kv_read_recursive_as_hash(key)
  kv_read_recursive(key).to_h do |entry|
    [entry['Key'], entry]
  end
end

#kv_read_single(key) ⇒ Hash?

Reads the specified key, expecting a single KV entry. The value of the key is automatically base64 decoded.

Parameters:

  • key (String) —

    the key to read.

Returns:

  • (Hash, nil) 


62
63
64
65
66
 
# File 'lib/consulkit/client/kv.rb', line 62

def kv_read_single(key)
  kv_read!(key).first
rescue Consulkit::Error::NotFound
  nil
end

#kv_read_with_index(key, query_params = {}) ⇒ Array<(Integer, Array<Hash>)>

Reads the specified key, and returns the X-Consul-Index value. The value of the keys in the response are automatically base64 decoded, if applicable.

Parameters:

  • key (String) —

    the key to read.

  • query_params (Hash) (defaults to: {}) —

    optional query parameters.

Returns:

  • (Array<(Integer, Array<Hash>)>)

See Also:



77
78
79
80
81
82
83
 
# File 'lib/consulkit/client/kv.rb', line 77

def kv_read_with_index(key, query_params = {})
  kv_read!(key, **query_params) do |response|
    [response.headers['X-Consul-Index'], kv_decode_response_body(response.body)]
  end
rescue Consulkit::Error::NotFound => e
  [e.response_headers['X-Consul-Index'], []]
end

#kv_release_lock(key, session_id, value = nil, query_params = {}) ⇒ Object

Atomically updates the specified key while releasing the associated lock.

return [Boolean]

Parameters:

  • key (String) —

    the key to update.

  • query_params (Hash) (defaults to: {}) —

    optional query parameters.



184
185
186
 
# File 'lib/consulkit/client/kv.rb', line 184

def kv_release_lock(key, session_id, value = nil, query_params = {})
  kv_write(key, value, **query_params, release: session_id)
end

#kv_write(key, value, query_params = {}) {|Faraday::Response| ... } ⇒ Boolean

Creates or updates the specified key.

Parameters:

  • key (String) —

    the key to create or update.

  • query_params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query_params):

  • optional (Hash) —

    query parameters.

  • :flags (Integer)
  • :cas (Integer)
  • :acquire (String)
  • :release (String)

Yields:

  • (Faraday::Response) —

    The response from the underlying Faraday library.

Returns:

  • (Boolean)

See Also:



148
149
150
151
152
153
154
155
156
 
# File 'lib/consulkit/client/kv.rb', line 148

def kv_write(key, value, query_params = {})
  response = put("/v1/kv/#{key}", value, query_params)

  if block_given?
    yield response
  else
    response.body == true
  end
end

#kv_write_cas(key, value, modify_index, query_params = {}) ⇒ Object

Atomically creates or updates the specified key, if and only if the modify index matches.

return [Boolean]

Parameters:

  • key (String) —

    the key to create or update.

  • query_params (Hash) (defaults to: {}) —

    optional query parameters.



164
165
166
 
# File 'lib/consulkit/client/kv.rb', line 164

def kv_write_cas(key, value, modify_index, query_params = {})
  kv_write(key, value, **query_params, cas: modify_index)
end