diplomat 2.0.5 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c67b8ac370c8b73bd37fea1bcdcca6f88cf75e789f58a2ebb7abe0b1a1da83c1
-  data.tar.gz: ec8ff0e996067dab3580d874961d30588b8015f6efdb0d133f0699a2501fd4ab
+  metadata.gz: 2638dd7e205e74662fe2dd9124a268447b21173a7fa383f124cea572a7fbf0c0
+  data.tar.gz: d2630310fb56f3b8fe9ae2a4cf4b71b1773481078d6349c8bd2fd5bd189cbe3f
 SHA512:
-  metadata.gz: fa2eca5776b8652c1032e5d67348086e48a8f3f05adf1b18a1457754a460f8bcbfda561108124962e7da059155c60df19860dfae1baf24b559ecfd258bcdcd41
-  data.tar.gz: b429f5262c799f09f735d6821a772429c2a66e829b08facd55b9fbb1938f768545fae8b2eda2a222dedcf9f560e3c3b4be5e7c46afb1e35ccc8e0412e933902e
+  metadata.gz: cb12a73c20d249c32f87c3a36b59e90e691a71192f534c29ec127f82042e92d4f697b314924d33b4a8d6104892a5e68063ec2d450e4fc3153d3ab8be74110bac
+  data.tar.gz: 742b7f771257d00c95c037869e9e23458d3c81dbaecefa1dfc848722566082ac90c0770ed87a4563bd19f638291bbe24e5cd69e6b676bce3d2be248e62d5d5dc

data/README.md

@@ -2,7 +2,7 @@
 [![Gem Version](https://badge.fury.io/rb/diplomat.svg)](https://rubygems.org/gems/diplomat) [![Gem](https://img.shields.io/gem/dt/diplomat.svg)](https://rubygems.org/gems/diplomat/versions/2.0.0) [![Build Status](https://travis-ci.org/WeAreFarmGeek/diplomat.svg?branch=master)](https://travis-ci.org/WeAreFarmGeek/diplomat) [![Code Climate](https://codeclimate.com/github/johnhamelink/diplomat.svg)](https://codeclimate.com/github/WeAreFarmGeek/diplomat) [![Inline docs](http://inch-ci.org/github/wearefarmgeek/diplomat.svg?branch=master)](http://inch-ci.org/github/wearefarmgeek/diplomat)
 ### A HTTP Ruby API for [Consul](http://www.consul.io/)
 
-![Diplomacy Boad Game](http://i.imgur.com/Nkuy4b7.jpg)
+![Diplomacy Board Game](http://i.imgur.com/Nkuy4b7.jpg)
 
 
 ## FAQ
@@ -72,12 +72,14 @@ foo = Diplomat::Kv.get('foo')
 ```
 
 Or retrieve a value from another datacenter:
+
 ```ruby
 foo = Diplomat::Kv.get('foo', :dc => 'dc-west')
 # => "baz"
 ```
 
 You can also retrieve values recursively:
+
 ```ruby
 Diplomat::Kv.put('foo/a', 'lorem')
 Diplomat::Kv.put('foo/b', 'ipsum')
@@ -94,6 +96,7 @@ Or list all available keys:
 Diplomat::Kv.get('/', :keys => true) # => ['foo/a', 'foo/b']
 ```
 You can convert the consul data to a ruby hash
+
 ```ruby
 Diplomat::Kv.put('foo/a', 'lorem')
 Diplomat::Kv.put('foo/b', 'ipsum')
@@ -317,6 +320,20 @@ end
 
 This is traditionally kept inside the `config/initializers` directory if you're using rails. The middleware allows you to customise what happens when faraday sends and receives data. This can be useful if you want to instrument your use of diplomat, for example. You can read more about Faraday's custom middleware [here](http://stackoverflow.com/a/20973008).
 
+Alternatively, configuration settings can be overriden at each method call allowing for instance to address different consul agents, with some other token.
+
+```ruby
+Diplomat::Service.get('foo', { http_addr: 'http://consu01:8500' })
+Diplomat::Service.get('foo', { http_addr: 'http://consu02:8500' })
+Diplomat::Kv.put('key/path', 'value', { http_addr: 'http://localhost:8500', dc: 'dc1', token: '111-222-333-444-555' })
+```
+
+Most common options are:
+* dc: target datacenter
+* token: identity used to perform the corresponding action
+* http_addr: to target a remote consul node
+* stale: use consistency mode that allows any server to service the read regardless of whether it is the leader
+
 ### Todo
 
 -  [ ] Updating Docs with latest changes

data/lib/diplomat/acl.rb

@@ -6,16 +6,17 @@ module Diplomat
 
     # Get Acl info by ID
     # @param id [String] ID of the Acl to get
+    # @param options [Hash] options parameter hash
     # @return [Hash]
-    # rubocop:disable PerceivedComplexity, MethodLength, CyclomaticComplexity, AbcSize
-    def info(id, options = nil, not_found = :reject, found = :return)
+    # rubocop:disable PerceivedComplexity
+    def info(id, options = {}, not_found = :reject, found = :return)
       @id = id
       @options = options
-      url = ["/v1/acl/info/#{id}"]
-      url << check_acl_token
-      url << use_consistency(options)
+      custom_params = []
+      custom_params << use_consistency(options)
+
+      raw = send_get_request(@conn_no_err, ["/v1/acl/info/#{id}"], options, custom_params)
 
-      raw = @conn_no_err.get concat_url url
       if raw.status == 200 && raw.body.chomp != 'null'
         case found
         when :reject
@@ -35,55 +36,45 @@ module Diplomat
         raise Diplomat::UnknownStatus, "status #{raw.status}: #{raw.body}"
       end
     end
-    # rubocop:enable PerceivedComplexity, MethodLength, CyclomaticComplexity, AbcSize
+    # rubocop:enable PerceivedComplexity
 
     # List all Acls
+    # @param options [Hash] options parameter hash
     # @return [List] list of [Hash] of Acls
-    def list
-      url = ['/v1/acl/list']
-      url += check_acl_token
-      @raw = @conn_no_err.get concat_url url
+    def list(options = {})
+      @raw = send_get_request(@conn_no_err, ['/v1/acl/list'], options)
       parse_body
     end
 
     # Update an Acl definition, create if not present
     # @param value [Hash] Acl definition, ID field is mandatory
+    # @param options [Hash] options parameter hash
     # @return [Hash] The result Acl
-    def update(value)
-      raise Diplomat::IdParameterRequired unless value['ID']
+    def update(value, options = {})
+      raise Diplomat::IdParameterRequired unless value['ID'] || value[:ID]
 
-      @raw = @conn.put do |req|
-        url = ['/v1/acl/update']
-        url += check_acl_token
-        url += use_cas(@options)
-        req.url concat_url url
-        req.body = value.to_json
-      end
+      custom_params = use_cas(@options)
+      @raw = send_put_request(@conn, ['/v1/acl/update'], options, value, custom_params)
       parse_body
     end
 
     # Create an Acl definition
     # @param value [Hash] Acl definition, ID field is mandatory
+    # @param options [Hash] options parameter hash
     # @return [Hash] The result Acl
-    def create(value)
-      @raw = @conn.put do |req|
-        url = ['/v1/acl/create']
-        url += check_acl_token
-        url += use_cas(@options)
-        req.url concat_url url
-        req.body = value.to_json
-      end
+    def create(value, options = {})
+      custom_params = use_cas(@options)
+      @raw = send_put_request(@conn, ['/v1/acl/create'], options, value, custom_params)
       parse_body
     end
 
     # Destroy an ACl token by its id
     # @param ID [String] the Acl ID
+    # @param options [Hash] options parameter hash
     # @return [Bool]
-    def destroy(id)
+    def destroy(id, options = {})
       @id = id
-      url = ["/v1/acl/destroy/#{@id}"]
-      url << check_acl_token
-      @raw = @conn.put concat_url url
+      @raw = send_put_request(@conn, ["/v1/acl/destroy/#{@id}"], options, nil)
       @raw.body.chomp == 'true'
     end
   end

data/lib/diplomat/agent.rb

@@ -8,62 +8,34 @@ module Diplomat
     @access_methods = %i[self checks services members]
 
     # Get agent configuration
+    # @param options [Hash] options parameter hash
     # @return [OpenStruct] all data associated with the node
-    def self
-      url = ['/v1/agent/self']
-
-      # If the request fails, it's probably due to a bad path
-      # so return a PathNotFound error.
-      begin
-        ret = @conn.get concat_url url
-      rescue Faraday::ClientError
-        raise Diplomat::PathNotFound
-      end
+    def self(options = {})
+      ret = send_get_request(@conn, ['/v1/agent/self'], options)
       JSON.parse(ret.body).tap { |node| OpenStruct.new node }
     end
 
     # Get local agent checks
+    # @param options [Hash] options parameter hash
     # @return [OpenStruct] all agent checks
-    def checks
-      url = ['/v1/agent/checks']
-
-      # If the request fails, it's probably due to a bad path
-      # so return a PathNotFound error.
-      begin
-        ret = @conn.get concat_url url
-      rescue Faraday::ClientError
-        raise Diplomat::PathNotFound
-      end
+    def checks(options = {})
+      ret = send_get_request(@conn, ['/v1/agent/checks'], options)
       JSON.parse(ret.body).tap { |node| OpenStruct.new node }
     end
 
     # Get local agent services
+    # @param options [Hash] options parameter hash
     # @return [OpenStruct] all agent services
-    def services
-      url = ['/v1/agent/services']
-
-      # If the request fails, it's probably due to a bad path
-      # so return a PathNotFound error.
-      begin
-        ret = @conn.get concat_url url
-      rescue Faraday::ClientError
-        raise Diplomat::PathNotFound
-      end
+    def services(options = {})
+      ret = send_get_request(@conn, ['/v1/agent/services'], options)
       JSON.parse(ret.body).tap { |node| OpenStruct.new node }
     end
 
     # Get cluster members (as seen by the agent)
+    # @param options [Hash] options parameter hash
     # @return [OpenStruct] all members
-    def members
-      url = ['/v1/agent/members']
-
-      # If the request fails, it's probably due to a bad path
-      # so return a PathNotFound error.
-      begin
-        ret = @conn.get concat_url url
-      rescue Faraday::ClientError
-        raise Diplomat::PathNotFound
-      end
+    def members(options = {})
+      ret = send_get_request(@conn, ['/v1/agent/members'], options)
       JSON.parse(ret.body).map { |node| OpenStruct.new node }
     end
   end

data/lib/diplomat/check.rb

@@ -6,8 +6,8 @@ module Diplomat
 
     # Get registered checks
     # @return [OpenStruct] all data associated with the service
-    def checks
-      ret = @conn.get '/v1/agent/checks'
+    def checks(options = {})
+      ret = send_get_request(@conn, ['/v1/agent/checks'], options)
       JSON.parse(ret.body)
     end
 
@@ -15,42 +15,52 @@ module Diplomat
     # @param check_id [String] the unique id of the check
     # @param name [String] the name
     # @param notes [String] notes about the check
-    # @param script [String] command to be run for check
+    # @param args [String[]] command to be run for check
     # @param interval [String] frequency (with units) of the check execution
-    # @param ttl [String] time (with units) to mark a check down
+    # @param options [Hash] options parameter hash
     # @return [Integer] Status code
-    #
-    def register_script(check_id, name, notes, script, interval)
-      ret = @conn.put do |req|
-        req.url '/v1/agent/check/register'
-        req.body = JSON.generate(
-          'ID' => check_id, 'Name' => name, 'Notes' => notes, 'Script' => script, 'Interval' => interval
-        )
+    # rubocop:disable ParameterLists
+    def register_script(check_id, name, notes, args, interval, options = {})
+      unless args.is_a?(Array)
+        raise(Diplomat::DeprecatedArgument, 'Script usage is deprecated, replace by an array of args')
       end
+
+      definition = {
+        'ID' => check_id,
+        'Name' => name,
+        'Notes' => notes,
+        'Args' => args,
+        'Interval' => interval
+      }
+      ret = send_put_request(@conn, ['/v1/agent/check/register'], options, definition)
       ret.status == 200
     end
+    # rubocop:enable ParameterLists
 
     # Register a TTL check
     # @param check_id [String] the unique id of the check
     # @param name [String] the name
     # @param notes [String] notes about the check
     # @param ttl [String] time (with units) to mark a check down
+    # @param options [Hash] options parameter hash
     # @return [Boolean] Success
-    def register_ttl(check_id, name, notes, ttl)
-      ret = @conn.put do |req|
-        req.url '/v1/agent/check/register'
-        req.body = JSON.generate(
-          'ID' => check_id, 'Name' => name, 'Notes' => notes, 'TTL' => ttl
-        )
-      end
+    def register_ttl(check_id, name, notes, ttl, options = {})
+      definition = {
+        'ID' => check_id,
+        'Name' => name,
+        'Notes' => notes,
+        'TTL' => ttl
+      }
+      ret = send_put_request(@conn, ['/v1/agent/check/register'], options, definition)
       ret.status == 200
     end
 
     # Deregister a check
     # @param check_id [String] the unique id of the check
+    # @param options [Hash] options parameter hash
     # @return [Integer] Status code
-    def deregister(check_id)
-      ret = @conn.put "/v1/agent/check/deregister/#{check_id}"
+    def deregister(check_id, options = {})
+      ret = send_put_request(@conn, ["/v1/agent/check/deregister/#{check_id}"], options, nil)
       ret.status == 200
     end
 
@@ -58,37 +68,42 @@ module Diplomat
     # @param check_id [String] the unique id of the check
     # @param status [String] status of the check. Valid values are "passing", "warning", and "critical"
     # @param output [String] human-readable message will be passed through to the check's Output field
+    # @param options [Hash] options parameter hash
     # @return [Integer] Status code
-    def update_ttl(check_id, status, output = nil)
-      ret = @conn.put do |req|
-        req.url "/v1/agent/check/update/#{check_id}"
-        req.body = JSON.generate('Status' => status, 'Output' => output)
-      end
+    def update_ttl(check_id, status, output = nil, options = {})
+      definition = {
+        'Status' => status,
+        'Output' => output
+      }
+      ret = send_put_request(@conn, ["/v1/agent/check/update/#{check_id}"], options, definition)
       ret.status == 200
     end
 
     # Pass a check
     # @param check_id [String] the unique id of the check
     # @param output [String] human-readable message will be passed through to the check's Output field
+    # @param options [Hash] options parameter hash
     # @return [Integer] Status code
-    def pass(check_id, output = nil)
-      update_ttl(check_id, 'passing', output)
+    def pass(check_id, output = nil, options = {})
+      update_ttl(check_id, 'passing', output, options)
     end
 
     # Warn a check
     # @param check_id [String] the unique id of the check
     # @param output [String] human-readable message will be passed through to the check's Output field
+    # @param options [Hash] options parameter hash
     # @return [Integer] Status code
-    def warn(check_id, output = nil)
-      update_ttl(check_id, 'warning', output)
+    def warn(check_id, output = nil, options = {})
+      update_ttl(check_id, 'warning', output, options)
     end
 
     # Fail a check
     # @param check_id [String] the unique id of the check
     # @param output [String] human-readable message will be passed through to the check's Output field
+    # @param options [Hash] options parameter hash
     # @return [Integer] Status code
-    def fail(check_id, output = nil)
-      update_ttl(check_id, 'critical', output)
+    def fail(check_id, output = nil, options = {})
+      update_ttl(check_id, 'critical', output, options)
     end
   end
 end

data/lib/diplomat/datacenter.rb

@@ -5,16 +5,15 @@ module Diplomat
 
     # Get an array of all avaliable datacenters accessible by the local consul agent
     # @param meta [Hash] output structure containing header information about the request (index)
+    # @param options [Hash] options parameter hash
     # @return [OpenStruct] all datacenters avaliable to this consul agent
-    def get(meta = nil)
-      url = ['/v1/catalog/datacenters']
-
-      ret = @conn.get concat_url url
+    def get(meta = nil, options = {})
+      ret = send_get_request(@conn, ['/v1/catalog/datacenters'], options)
 
       if meta && ret.headers
-        meta[:index] = ret.headers['x-consul-index']
-        meta[:knownleader] = ret.headers['x-consul-knownleader']
-        meta[:lastcontact] = ret.headers['x-consul-lastcontact']
+        meta[:index] = ret.headers['x-consul-index'] if ret.headers['x-consul-index']
+        meta[:knownleader] = ret.headers['x-consul-knownleader'] if ret.headers['x-consul-knownleader']
+        meta[:lastcontact] = ret.headers['x-consul-lastcontact'] if ret.headers['x-consul-lastcontact']
       end
       JSON.parse(ret.body)
     end

data/lib/diplomat/error.rb

@@ -11,4 +11,5 @@ module Diplomat
   class UnknownStatus < StandardError; end
   class IdParameterRequired < StandardError; end
   class InvalidTransaction < StandardError; end
+  class DeprecatedArgument < StandardError; end
 end

data/lib/diplomat/event.rb

@@ -10,17 +10,17 @@ module Diplomat
     # @param node [String] the target node name
     # @param tag [String] the target tag name, must only be used with service
     # @param dc [String] the dc to target
+    # @param options [Hash] options parameter hash
     # @return [nil]
     # rubocop:disable Metrics/ParameterLists
-    def fire(name, value = nil, service = nil, node = nil, tag = nil, dc = nil)
-      url = ["/v1/event/fire/#{name}"]
-      url += check_acl_token
-      url += use_named_parameter('service', service) if service
-      url += use_named_parameter('node', node) if node
-      url += use_named_parameter('tag', tag) if tag
-      url += use_named_parameter('dc', dc) if dc
+    def fire(name, value = nil, service = nil, node = nil, tag = nil, dc = nil, options = {})
+      custom_params = []
+      custom_params << use_named_parameter('service', service) if service
+      custom_params << use_named_parameter('node', node) if node
+      custom_params << use_named_parameter('tag', tag) if tag
+      custom_params << use_named_parameter('dc', dc) if dc
 
-      @conn.put concat_url(url), value
+      send_put_request(@conn, ["/v1/event/fire/#{name}"], options, value, custom_params)
       nil
     end
     # rubocop:enable Metrics/ParameterLists
@@ -32,6 +32,7 @@ module Diplomat
     # @param found [Symbol] behaviour if there are already events matching name;
     #   :reject with exception, :return its current value, or :wait for its next value
     # @return [Array[hash]] The list of { :name, :payload } hashes
+    # @param options [Hash] options parameter hash
     # @note
     #   Events are sent via the gossip protocol; there is no guarantee of delivery
     #   success or order, but the local agent will store up to 256 events that do
@@ -55,15 +56,9 @@ module Diplomat
     #   - W R - get the first or current value; always return something, but
     #           block only when necessary
     #   - W W - get the first or next value; wait until there is an update
-    # rubocop:disable MethodLength, AbcSize
-    def get_all(name = nil, not_found = :reject, found = :return)
-      url = ['/v1/event/list']
-      url += check_acl_token
-      url += use_named_parameter('name', name)
-      url = concat_url url
-
+    def get_all(name = nil, not_found = :reject, found = :return, options = {})
       # Event list never returns 404 or blocks, but may return an empty list
-      @raw = @conn.get url
+      @raw = send_get_request(@conn, ['/v1/event/list'], options, use_named_parameter('name', name))
       if JSON.parse(@raw.body).count.zero?
         case not_found
         when :reject
@@ -76,19 +71,15 @@ module Diplomat
         when :reject
           raise Diplomat::EventAlreadyExists, name
         when :return
-          # Always set the response to 200 so we always return
-          # the response body.
-          @raw.status = 200
           @raw = parse_body
           return return_payload
         end
       end
 
-      @raw = wait_for_next_event(url)
+      @raw = wait_for_next_event(['/v1/event/list'], options, use_named_parameter('name', name))
       @raw = parse_body
       return_payload
     end
-    # rubocop:enable MethodLength, AbcSize
 
     # Get a specific event in the sequence matching name
     # @param name [String] the name of the event (regex)
@@ -102,6 +93,7 @@ module Diplomat
     # @return [hash] A hash with keys :value and :token;
     #   :value is a further hash of the :name and :payload of the event,
     #   :token is the event's ordinate in the sequence and can be passed to future calls to get the subsequent event
+    # @param options [Hash] options parameter hash
     # @note
     #   Whereas the consul API for events returns all past events that match
     #   name, this method allows retrieval of individual events from that
@@ -110,12 +102,9 @@ module Diplomat
     #   middle, though these can only be identified relative to the preceding
     #   event. However, this is ideal for iterating through the sequence of
     #   events (while being sure that none are missed).
-    # rubocop:disable MethodLength, CyclomaticComplexity, AbcSize
-    def get(name = nil, token = :last, not_found = :wait, found = :return)
-      url = ['/v1/event/list']
-      url += check_acl_token
-      url += use_named_parameter('name', name)
-      @raw = @conn.get concat_url url
+    # rubocop:disable PerceivedComplexity
+    def get(name = nil, token = :last, not_found = :wait, found = :return, options = {})
+      @raw = send_get_request(@conn, ['/v1/event/list'], options, use_named_parameter('name', name))
       body = JSON.parse(@raw.body)
       # TODO: deal with unknown symbols, invalid indices (find_index will return nil)
       idx = case token
@@ -124,7 +113,7 @@ module Diplomat
             when :next then body.length
             else body.find_index { |e| e['ID'] == token } + 1
             end
-      if idx == body.length
+      if JSON.parse(@raw.body).count.zero? || idx == body.length
         case not_found
         when :reject
           raise Diplomat::EventNotFound, name
@@ -133,7 +122,7 @@ module Diplomat
           event_payload = ''
           event_token = :last
         when :wait
-          @raw = wait_for_next_event(url)
+          @raw = wait_for_next_event(['/v1/event/list'], options, use_named_parameter('name', name))
           @raw = parse_body
           # If it's possible for two events to arrive at once,
           # this needs to #find again:
@@ -149,7 +138,7 @@ module Diplomat
         when :return
           event = body[idx]
           event_name = event['Name']
-          event_payload = Base64.decode64(event['Payload'])
+          event_payload = event['Payload'].nil? ? nil : Base64.decode64(event['Payload'])
           event_token = event['ID']
         end
       end
@@ -159,17 +148,19 @@ module Diplomat
         token: event_token
       }
     end
-    # rubocop:enable MethodLength, CyclomaticComplexity, AbcSize
+    # rubocop:enable PerceivedComplexity
 
     private
 
-    def wait_for_next_event(url)
-      index = @raw.headers['x-consul-index']
-      url = [url, use_named_parameter('index', index)].join('&')
-      @conn.get do |req|
-        req.url concat_url url
-        req.options.timeout = 86_400
+    def wait_for_next_event(url, options = {}, param = nil)
+      if options.nil?
+        options = { timeout: 86_400 }
+      else
+        options[:timeout] = 86_400
       end
+      index = @raw.headers['x-consul-index']
+      param += use_named_parameter('index', index)
+      send_get_request(@conn, url, options, param)
     end
   end
 end