diplomat-blsk 2.0.2

data/lib/diplomat/acl.rb

@@ -0,0 +1,92 @@
+module Diplomat
+  # Methods for interacting with the Consul ACL API endpoint
+  class Acl < Diplomat::RestClient
+    include ApiOptions
+
+    @access_methods = %i[list info create destroy update]
+    attr_reader :id, :type, :acl
+
+    # Get Acl info by ID
+    # @param id [String] ID of the Acl to get
+    # @return [Hash]
+    # rubocop:disable PerceivedComplexity, MethodLength, CyclomaticComplexity, AbcSize
+    def info(id, options = nil, not_found = :reject, found = :return)
+      @id = id
+      @options = options
+      url = ["/v1/acl/info/#{id}"]
+      url << check_acl_token
+      url << use_consistency(options)
+
+      raw = @conn_no_err.get concat_url url
+      if raw.status == 200 && raw.body.chomp != 'null'
+        case found
+        when :reject
+          raise Diplomat::AclAlreadyExists, id
+        when :return
+          @raw = raw
+          return parse_body
+        end
+      elsif raw.status == 200 && raw.body.chomp == 'null'
+        case not_found
+        when :reject
+          raise Diplomat::AclNotFound, id
+        when :return
+          return nil
+        end
+      else
+        raise Diplomat::UnknownStatus, "status #{raw.status}: #{raw.body}"
+      end
+    end
+    # rubocop:enable PerceivedComplexity, MethodLength, CyclomaticComplexity, AbcSize
+
+    # List all Acls
+    # @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
+      parse_body
+    end
+
+    # Update an Acl definition, create if not present
+    # @param value [Hash] Acl definition, ID field is mandatory
+    # @return [Hash] The result Acl
+    def update(value)
+      raise Diplomat::IdParameterRequired unless 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
+      parse_body
+    end
+
+    # Create an Acl definition
+    # @param value [Hash] Acl definition, ID field is mandatory
+    # @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
+      parse_body
+    end
+
+    # Destroy an ACl token by its id
+    # @param ID [String] the Acl ID
+    # @return [Bool]
+    def destroy(id)
+      @id = id
+      url = ["/v1/acl/destroy/#{@id}"]
+      url << check_acl_token
+      @raw = @conn.put concat_url url
+      @raw.body.chomp == 'true'
+    end
+  end
+end

data/lib/diplomat/agent.rb

@@ -0,0 +1,70 @@
+require 'base64'
+require 'faraday'
+
+module Diplomat
+  # Agent API endpoint methods
+  # @see https://www.consul.io/docs/agent/http/agent.html
+  class Agent < Diplomat::RestClient
+    @access_methods = %i[self checks services members]
+
+    # Get agent configuration
+    # @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
+      JSON.parse(ret.body).tap { |node| OpenStruct.new node }
+    end
+
+    # Get local agent checks
+    # @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
+      JSON.parse(ret.body).tap { |node| OpenStruct.new node }
+    end
+
+    # Get local agent services
+    # @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
+      JSON.parse(ret.body).tap { |node| OpenStruct.new node }
+    end
+
+    # Get cluster members (as seen by the agent)
+    # @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
+      JSON.parse(ret.body).map { |node| OpenStruct.new node }
+    end
+  end
+end

data/lib/diplomat/api_options.rb

@@ -0,0 +1,46 @@
+module Diplomat
+  # Helper methods for interacting with the Consul RESTful API
+  module ApiOptions
+    def check_acl_token
+      use_named_parameter('token', Diplomat.configuration.acl_token)
+    end
+
+    def use_cas(options)
+      options ? use_named_parameter('cas', options[:cas]) : []
+    end
+
+    def use_consistency(options)
+      options && options[:consistency] ? [options[:consistency].to_s] : []
+    end
+
+    # Mapping for valid key/value store transaction verbs and required parameters
+    #
+    # @return [Hash] valid key/store transaction verbs and required parameters
+    # rubocop:disable MethodLength
+    def valid_transaction_verbs
+      {
+        'set' => %w[Key Value],
+        'cas' => %w[Key Value Index],
+        'lock' => %w[Key Value Session],
+        'unlock' => %w[Key Value Session],
+        'get' => %w[Key],
+        'get-tree' => %w[Key],
+        'check-index' => %w[Key Index],
+        'check-session' => %w[Key Session],
+        'delete' => %w[Key],
+        'delete-tree' => %w[Key],
+        'delete-cas' => %w[Key Index]
+      }
+    end
+    # rubocop:enable MethodLength
+
+    # Key/value store transactions that require that a value be set
+    #
+    # @return [Array<String>] verbs that require a value be set
+    def valid_value_transactions
+      @valid_value_transactions ||= valid_transaction_verbs.select do |verb, requires|
+        verb if requires.include? 'Value'
+      end
+    end
+  end
+end

data/lib/diplomat/check.rb

@@ -0,0 +1,81 @@
+module Diplomat
+  # Methods for interacting with the Consul check API endpoint
+  class Check < Diplomat::RestClient
+    @access_methods = %i[checks register_script register_ttl
+                         deregister pass warn fail]
+
+    # Get registered checks
+    # @return [OpenStruct] all data associated with the service
+    def checks
+      ret = @conn.get '/v1/agent/checks'
+      JSON.parse(ret.body)
+    end
+
+    # Register a check
+    # @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 interval [String] frequency (with units) of the check execution
+    # @param ttl [String] time (with units) to mark a check down
+    # @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
+        )
+      end
+      ret.status == 200
+    end
+
+    # 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
+    # @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
+      ret.status == 200
+    end
+
+    # Deregister a check
+    # @param check_id [String] the unique id of the check
+    # @return [Integer] Status code
+    def deregister(check_id)
+      ret = @conn.get "/v1/agent/check/deregister/#{check_id}"
+      ret.status == 200
+    end
+
+    # Pass a check
+    # @param check_id [String] the unique id of the check
+    # @return [Integer] Status code
+    def pass(check_id)
+      ret = @conn.get "/v1/agent/check/pass/#{check_id}"
+      ret.status == 200
+    end
+
+    # Warn a check
+    # @param check_id [String] the unique id of the check
+    # @return [Integer] Status code
+    def warn(check_id)
+      ret = @conn.get "/v1/agent/check/warn/#{check_id}"
+      ret.status == 200
+    end
+
+    # Warn a check
+    # @param check_id [String] the unique id of the check
+    # @return [Integer] Status code
+    def fail(check_id)
+      ret = @conn.get "/v1/agent/check/fail/#{check_id}"
+      ret.status == 200
+    end
+  end
+end

data/lib/diplomat/configuration.rb

@@ -0,0 +1,28 @@
+module Diplomat
+  # Methods for configuring Diplomat
+  class Configuration
+    attr_reader :middleware
+    attr_accessor :url, :acl_token, :options
+
+    # Override defaults for configuration
+    # @param url [String] consul's connection URL
+    # @param acl_token [String] a connection token used when making requests to consul
+    # @param options [Hash] extra options to configure Faraday::Connection
+    def initialize(url = 'http://localhost:8500', acl_token = nil, options = {})
+      @middleware = []
+      @url = url
+      @acl_token = acl_token
+      @options = options
+    end
+
+    # Define a middleware for Faraday
+    # @param middleware [Class] Faraday Middleware class
+    def middleware=(middleware)
+      if middleware.is_a? Array
+        @middleware = middleware
+        return
+      end
+      @middleware = [middleware]
+    end
+  end
+end

data/lib/diplomat/datacenter.rb

@@ -0,0 +1,22 @@
+module Diplomat
+  # Methods for interacting with the Consul dataceneter API endpoint
+  class Datacenter < Diplomat::RestClient
+    @access_methods = [:get]
+
+    # 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)
+    # @return [OpenStruct] all datacenters avaliable to this consul agent
+    def get(meta = nil)
+      url = ['/v1/catalog/datacenters']
+
+      ret = @conn.get concat_url url
+
+      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']
+      end
+      JSON.parse(ret.body)
+    end
+  end
+end

data/lib/diplomat/error.rb

@@ -0,0 +1,14 @@
+module Diplomat
+  class KeyNotFound < StandardError; end
+  class PathNotFound < StandardError; end
+  class KeyAlreadyExists < StandardError; end
+  class AclNotFound < StandardError; end
+  class AclAlreadyExists < StandardError; end
+  class EventNotFound < StandardError; end
+  class EventAlreadyExists < StandardError; end
+  class QueryNotFound < StandardError; end
+  class QueryAlreadyExists < StandardError; end
+  class UnknownStatus < StandardError; end
+  class IdParameterRequired < StandardError; end
+  class InvalidTransaction < StandardError; end
+end

data/lib/diplomat/event.rb

@@ -0,0 +1,177 @@
+module Diplomat
+  # Methods for interacting with the Consul event API endpoint
+  class Event < Diplomat::RestClient
+    include ApiOptions
+
+    @access_methods = %i[fire get_all get]
+
+    # Send an event
+    # @param name [String] the event name
+    # @param value [String] the payload of the event
+    # @param service [String] the target service name
+    # @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
+    # @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
+
+      @conn.put concat_url(url), value
+      nil
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Get the list of events matching name
+    # @param name [String] the name of the event (regex)
+    # @param not_found [Symbol] behaviour if there are no events matching name;
+    #   :reject with exception, :return degenerate value, or :wait for a non-empty list
+    # @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
+    # @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
+    #   arrive. This method lists those events.
+    #   It has the same semantics as Kv::get, except the value returned is a list
+    #   i.e. the current value is all events up until now, the next value is the
+    #   current list plus the next event to arrive.
+    #   To get a specific event in the sequence, @see #get
+    #   When trying to get a list of events matching a name, there are two possibilities:
+    #   - The list doesn't (yet) exist / is empty
+    #   - The list exists / is non-empty
+    #   The combination of not_found and found behaviour gives maximum possible
+    #   flexibility. For X: reject, R: return, W: wait
+    #   - X X - meaningless; never return a value
+    #   - X R - "normal" non-blocking get operation. Default
+    #   - X W - get the next value only (must have a current value)
+    #   - R X - meaningless; never return a meaningful value
+    #   - R R - "safe" non-blocking, non-throwing get-or-default operation
+    #   - R W - get the next value or a default
+    #   - W X - get the first value only (must not have a current value)
+    #   - 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
+
+      # Event list never returns 404 or blocks, but may return an empty list
+      @raw = @conn.get url
+      if JSON.parse(@raw.body).count.zero?
+        case not_found
+        when :reject
+          raise Diplomat::EventNotFound, name
+        when :return
+          return []
+        end
+      else
+        case found
+        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 = 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)
+    # @param token [String|Symbol] the ordinate of the event in the sequence;
+    #   String are tokens returned by previous calls to this function
+    #   Symbols are the special tokens :first, :last, and :next
+    # @param not_found [Symbol] behaviour if there is no matching event;
+    #   :reject with exception, :return degenerate value, or :wait for event
+    # @param found [Symbol] behaviour if there is a matching event;
+    #   :reject with exception, or :return its current value
+    # @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
+    # @note
+    #   Whereas the consul API for events returns all past events that match
+    #   name, this method allows retrieval of individual events from that
+    #   sequence. However, because consul's API isn't conducive to this, we can
+    #   offer first, last, next (last + 1) events, or arbitrary events in the
+    #   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
+      body = JSON.parse(@raw.body)
+      # TODO: deal with unknown symbols, invalid indices (find_index will return nil)
+      idx = case token
+            when :first then 0
+            when :last then body.length - 1
+            when :next then body.length
+            else body.find_index { |e| e['ID'] == token } + 1
+            end
+      if idx == body.length
+        case not_found
+        when :reject
+          raise Diplomat::EventNotFound, name
+        when :return
+          event_name = ''
+          event_payload = ''
+          event_token = :last
+        when :wait
+          @raw = wait_for_next_event(url)
+          @raw = parse_body
+          # If it's possible for two events to arrive at once,
+          # this needs to #find again:
+          event = @raw.last
+          event_name = event['Name']
+          event_payload = Base64.decode64(event['Payload'])
+          event_token = event['ID']
+        end
+      else
+        case found
+        when :reject
+          raise Diplomat::EventAlreadyExits, name
+        when :return
+          event = body[idx]
+          event_name = event['Name']
+          event_payload = Base64.decode64(event['Payload'])
+          event_token = event['ID']
+        end
+      end
+
+      {
+        value: { name: event_name, payload: event_payload },
+        token: event_token
+      }
+    end
+    # rubocop:enable MethodLength, CyclomaticComplexity, AbcSize
+
+    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
+      end
+    end
+  end
+end