diplomat-scalp42 0.224

data/lib/diplomat/members.rb

@@ -0,0 +1,14 @@
+module Diplomat
+  # Methods for interacting with the Consul members API endpoint
+  class Members < Diplomat::RestClient
+    @access_methods = [:get]
+
+    # Get all members
+    # @param options [Hash] options parameter hash
+    # @return [OpenStruct] all data associated with the service
+    def get(options = {})
+      ret = send_get_request(@conn, ['/v1/agent/members'], options)
+      JSON.parse(ret.body)
+    end
+  end
+end

data/lib/diplomat/node.rb

@@ -0,0 +1,43 @@
+module Diplomat
+  # Methods for interacting with the Consul node API endpoint
+  class Node < Diplomat::RestClient
+    @access_methods = %i[get get_all register deregister]
+
+    # Get a node by it's key
+    # @param key [String] the key
+    # @param options [Hash] :dc string for dc specific query
+    # @return [OpenStruct] all data associated with the node
+    def get(key, options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_get_request(@conn, ["/v1/catalog/node/#{key}"], options, custom_params)
+      OpenStruct.new JSON.parse(ret.body)
+    end
+
+    # Get all the nodes
+    # @param options [Hash] :dc string for dc specific query
+    # @return [OpenStruct] the list of all nodes
+    def get_all(options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_get_request(@conn, ['/v1/catalog/nodes'], options, custom_params)
+      JSON.parse(ret.body).map { |service| OpenStruct.new service }
+    end
+
+    # Register a node
+    # @param definition [Hash] Hash containing definition of a node to register
+    # @param options [Hash] options parameter hash
+    # @return [Boolean]
+    def register(definition, options = {})
+      register = send_put_request(@conn, ['/v1/catalog/register'], options, definition)
+      register.status == 200
+    end
+
+    # De-register a node (and all associated services and checks)
+    # @param definition [Hash] Hash containing definition of a node to de-register
+    # @param options [Hash] options parameter hash
+    # @return [Boolean]
+    def deregister(definition, options = {})
+      deregister = send_put_request(@conn, ['/v1/catalog/deregister'], options, definition)
+      deregister.status == 200
+    end
+  end
+end

data/lib/diplomat/nodes.rb

@@ -0,0 +1,22 @@
+module Diplomat
+  # @depreciated
+  # Methods for interacting with the Consul nodes API endpoint
+  class Nodes < Diplomat::RestClient
+    @access_methods = %i[get get_all]
+
+    # Get all nodes
+    # @deprecated Please use Diplomat::Node instead.
+    # @param options [Hash] options parameter hash
+    # @return [OpenStruct] all data associated with the nodes in catalog
+    def get(options = {})
+      ret = send_get_request(@conn, ['/v1/catalog/nodes'], options)
+      JSON.parse(ret.body)
+    end
+
+    def get_all(options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_get_request(@conn, ['/v1/catalog/nodes'], options, custom_params)
+      JSON.parse(ret.body).map { |service| OpenStruct.new service }
+    end
+  end
+end

data/lib/diplomat/policy.rb

@@ -0,0 +1,112 @@
+module Diplomat
+  # Methods for interacting with the Consul ACL Policy API endpoint
+  class Policy < Diplomat::RestClient
+    @access_methods = %i[list read create delete update]
+    attr_reader :id, :type, :acl
+
+    # Read ACL policy with the given UUID
+    # @param id [String] UUID of the ACL policy to read
+    # @param options [Hash] options parameter hash
+    # @return [Hash] existing ACL policy
+    # rubocop:disable PerceivedComplexity
+    def read(id, options = {}, not_found = :reject, found = :return)
+      @options = options
+      custom_params = []
+      custom_params << use_consistency(options)
+
+      @raw = send_get_request(@conn_no_err, ["/v1/acl/policy/#{id}"], options, custom_params)
+
+      if @raw.status == 200 && @raw.body.chomp != 'null'
+        case found
+        when :reject
+          raise Diplomat::PolicyNotFound, id
+        when :return
+          return parse_body
+        end
+      elsif @raw.status == 404
+        case not_found
+        when :reject
+          raise Diplomat::PolicyNotFound, id
+        when :return
+          return nil
+        end
+      elsif @raw.status == 403
+        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
+
+    # List all the ACL policies
+    # @param options [Hash] options parameter hash
+    # @return [List] list of [Hash] of ACL policies
+    def list(options = {})
+      @raw = send_get_request(@conn_no_err, ['/v1/acl/policies'], options)
+      raise Diplomat::AclNotFound if @raw.status == 403
+
+      parse_body
+    end
+
+    # Update an existing ACL policy
+    # @param value [Hash] ACL policy definition, ID and Name fields are mandatory
+    # @param options [Hash] options parameter hash
+    # @return [Hash] result ACL policy
+    def update(value, options = {})
+      id = value[:ID] || value['ID']
+      raise Diplomat::IdParameterRequired if id.nil?
+
+      policy_name = value[:Name] || value['Name']
+      raise Diplomat::NameParameterRequired if policy_name.nil?
+
+      custom_params = use_cas(@options)
+      @raw = send_put_request(@conn, ["/v1/acl/policy/#{id}"], options, value, custom_params)
+      if @raw.status == 200
+        parse_body
+      elsif @raw.status == 400
+        raise Diplomat::PolicyMalformed, @raw.body
+      else
+        raise Diplomat::UnknownStatus, "status #{@raw.status}: #{@raw.body}"
+      end
+    end
+
+    # Create a new ACL policy
+    # @param value [Hash] ACL policy definition, Name field is mandatory
+    # @param options [Hash] options parameter hash
+    # @return [Hash] new ACL policy
+    def create(value, options = {})
+      blacklist = ['ID', 'iD', 'Id', :ID, :iD, :Id] & value.keys
+      raise Diplomat::PolicyMalformed, 'ID should not be specified' unless blacklist.empty?
+
+      id = value[:Name] || value['Name']
+      raise Diplomat::NameParameterRequired if id.nil?
+
+      custom_params = use_cas(@options)
+      @raw = send_put_request(@conn, ['/v1/acl/policy'], options, value, custom_params)
+
+      # rubocop:disable GuardClause
+      if @raw.status == 200
+        return parse_body
+      elsif @raw.status == 500 && @raw.body.chomp.include?('already exists')
+        raise Diplomat::PolicyAlreadyExists, @raw.body
+      else
+        raise Diplomat::UnknownStatus, "status #{@raw.status}: #{@raw.body}"
+      end
+    end
+    # rubocop:enable GuardClause
+
+    # Delete an ACL policy by its UUID
+    # @param id [String] UUID of the ACL policy to delete
+    # @param options [Hash] options parameter hash
+    # @return [Bool]
+    def delete(id, options = {})
+      @raw = send_delete_request(@conn, ["/v1/acl/policy/#{id}"], options, nil)
+      @raw.body.chomp == 'true'
+    end
+  end
+end

data/lib/diplomat/query.rb

@@ -0,0 +1,87 @@
+module Diplomat
+  # Methods for interacting with the Consul query API endpoint
+  class Query < Diplomat::RestClient
+    @access_methods = %i[get get_all create delete update execute explain]
+
+    # Get a prepared query by it's key
+    # @param key [String] the prepared query ID
+    # @param options [Hash] :dc string for dc specific query
+    # @return [OpenStruct] all data associated with the prepared query
+    def get(key, options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_get_request(@conn, ["/v1/query/#{key}"], options, custom_params)
+      JSON.parse(ret.body).map { |query| OpenStruct.new query }
+    end
+
+    # Get all prepared queries
+    # @param options [Hash] :dc Consul datacenter to query
+    # @return [OpenStruct] the list of all prepared queries
+    def get_all(options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_get_request(@conn, ['/v1/query'], options, custom_params)
+      JSON.parse(ret.body).map { |query| OpenStruct.new query }
+    end
+
+    # Create a prepared query or prepared query template
+    # @param definition [Hash] Hash containing definition of prepared query
+    # @param options [Hash] :dc Consul datacenter to query
+    # @return [String] the ID of the prepared query created
+    def create(definition, options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      @raw = send_post_request(@conn, ['/v1/query'], options, definition, custom_params)
+      parse_body
+    rescue Faraday::ClientError
+      raise Diplomat::QueryAlreadyExists
+    end
+
+    # Delete a prepared query or prepared query template
+    # @param key [String] the prepared query ID
+    # @param options [Hash] :dc Consul datacenter to query
+    # @return [Boolean]
+    def delete(key, options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_delete_request(@conn, ["/v1/query/#{key}"], options, custom_params)
+      ret.status == 200
+    end
+
+    # Update a prepared query or prepared query template
+    # @param key [String] the prepared query ID
+    # @param definition [Hash] Hash containing updated definition of prepared query
+    # @param options [Hash] :dc Consul datacenter to query
+    # @return [Boolean]
+    def update(key, definition, options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_put_request(@conn, ["/v1/query/#{key}"], options, definition, custom_params)
+      ret.status == 200
+    end
+
+    # Execute a prepared query or prepared query template
+    # @param key [String] the prepared query ID or name
+    # @param options [Hash] prepared query execution options
+    # @option dc [String] :dc Consul datacenter to query
+    # @option near [String] node name to sort the resulting list in ascending order based on the
+    #   estimated round trip time from that node
+    # @option limit [Integer] to limit the size of the return list to the given number of results
+    # @return [OpenStruct] the list of results from the prepared query or prepared query template
+    # rubocop:disable PerceivedComplexity
+    def execute(key, options = {})
+      custom_params = []
+      custom_params << use_named_parameter('dc', options[:dc]) if options[:dc]
+      custom_params << use_named_parameter('near', options[:near]) if options[:near]
+      custom_params << use_named_parameter('limit', options[:limit]) if options[:limit]
+      ret = send_get_request(@conn, ["/v1/query/#{key}/execute"], options, custom_params)
+      OpenStruct.new JSON.parse(ret.body)
+    end
+    # rubocop:enable PerceivedComplexity
+
+    # Get the fully rendered query template
+    # @param key [String] the prepared query ID or name
+    # @param options [Hash] :dc Consul datacenter to query
+    # @return [OpenStruct] the list of results from the prepared query or prepared query template
+    def explain(key, options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_get_request(@conn, ["/v1/query/#{key}/explain"], options, custom_params)
+      OpenStruct.new JSON.parse(ret.body)
+    end
+  end
+end

data/lib/diplomat/rest_client.rb

@@ -0,0 +1,278 @@
+require 'deep_merge'
+
+module Diplomat
+  # Base class for interacting with the Consul RESTful API
+  class RestClient
+    @access_methods = []
+    @configuration = nil
+
+    # Initialize the fadaray connection
+    # @param api_connection [Faraday::Connection,nil] supply mock API Connection
+    # @param configuration [Diplomat::Configuration] a dedicated config to use
+    def initialize(api_connection = nil, configuration: nil)
+      @configuration = configuration
+      start_connection api_connection
+    end
+
+    # Get client configuration or global one if not specified via initialize.
+    # @return [Diplomat::Configuration] used by this client
+    def configuration
+      @configuration || ::Diplomat.configuration
+    end
+
+    # Format url parameters into strings correctly
+    # @param name [String] the name of the parameter
+    # @param value [String] the value of the parameter
+    # @return [Array] the resultant parameter string inside an array.
+    def use_named_parameter(name, value)
+      value ? ["#{name}=#{value}"] : []
+    end
+
+    # Assemble a url from an array of parts.
+    # @param parts [Array] the url chunks to be assembled
+    # @return [String] the resultant url string
+    def concat_url(parts)
+      parts.reject!(&:empty?)
+      if parts.length > 1
+        parts.first + '?' + parts.drop(1).join('&')
+      else
+        parts.first
+      end
+    end
+
+    class << self
+      def access_method?(meth_id)
+        @access_methods.include? meth_id
+      end
+
+      # Allow certain methods to be accessed
+      # without defining "new".
+      # @param meth_id [Symbol] symbol defining method requested
+      # @param *args Arguments list
+      # @return [Boolean]
+      def method_missing(meth_id, *args)
+        if access_method?(meth_id)
+          new.send(meth_id, *args)
+        else
+
+          # See https://bugs.ruby-lang.org/issues/10969
+          begin
+            super
+          rescue NameError => e
+            raise NoMethodError, e
+          end
+        end
+      end
+
+      # Make `respond_to?` aware of method short-cuts.
+      #
+      # @param meth_id [Symbol] the tested method
+      # @oaram with_private if private methods should be tested too
+      def respond_to?(meth_id, with_private = false)
+        access_method?(meth_id) || super
+      end
+
+      # Make `respond_to_missing` aware of method short-cuts. This is needed for
+      # {#method} to work on these, which is helpful for testing purposes.
+      #
+      # @param meth_id [Symbol] the tested method
+      # @oaram with_private if private methods should be tested too
+      def respond_to_missing?(meth_id, with_private = false)
+        access_method?(meth_id) || super
+      end
+    end
+
+    private
+
+    # Build the API Client
+    # @param api_connection [Faraday::Connection,nil] supply mock API Connection
+    def start_connection(api_connection = nil)
+      @conn = build_connection(api_connection)
+      @conn_no_err = build_connection(api_connection, true)
+    end
+
+    def build_connection(api_connection, raise_error = false)
+      api_connection || Faraday.new(configuration.url, configuration.options) do |faraday|
+        configuration.middleware.each do |middleware|
+          faraday.use middleware
+        end
+
+        faraday.request  :url_encoded
+        faraday.response :raise_error unless raise_error
+
+        faraday.adapter  Faraday.default_adapter
+      end
+    end
+
+    # Converts k/v data into ruby hash
+    def convert_to_hash(data)
+      data.map do |item|
+        item[:key].split('/').reverse.reduce(item[:value]) { |h, v| { v => h } }
+      end.reduce(:deep_merge)
+    end
+
+    # Parse the body, apply it to the raw attribute
+    def parse_body
+      return JSON.parse(@raw.body) if @raw.status == 200
+
+      raise Diplomat::UnknownStatus, "status #{@raw.status}: #{@raw.body}"
+    end
+
+    # Return @raw with Value fields decoded
+    def decode_values
+      return @raw if @raw.first.is_a? String
+
+      @raw.each_with_object([]) do |acc, el|
+        begin
+          acc['Value'] = Base64.decode64(acc['Value'])
+        rescue StandardError
+          nil
+        end
+        el << acc
+        el
+      end
+    end
+
+    # Get the key/value(s) from the raw output
+    # rubocop:disable PerceivedComplexity
+    def return_value(nil_values = false, transformation = nil, return_hash = false)
+      @value = decode_values
+      return @value if @value.first.is_a? String
+
+      if @value.count == 1 && !return_hash
+        @value = @value.first['Value']
+        @value = transformation.call(@value) if transformation && !@value.nil?
+        return @value
+      else
+        @value = @value.map do |el|
+          el['Value'] = transformation.call(el['Value']) if transformation && !el['Value'].nil?
+          { key: el['Key'], value: el['Value'] } if el['Value'] || nil_values
+        end.compact
+      end
+    end
+    # rubocop:enable PerceivedComplexity
+
+    # Get the name and payload(s) from the raw output
+    def return_payload
+      @value = @raw.map do |e|
+        { name: e['Name'],
+          payload: (Base64.decode64(e['Payload']) unless e['Payload'].nil?) }
+      end
+    end
+
+    def use_cas(options)
+      options ? use_named_parameter('cas', options[:cas]) : []
+    end
+
+    def use_consistency(options)
+      options[:consistency] ? [options[:consistency].to_s] : []
+    end
+
+    # rubocop:disable PerceivedComplexity
+    # TODO: Migrate all custom params in options
+    def parse_options(options)
+      headers = nil
+      query_params = []
+      url_prefix = nil
+      consistency = []
+
+      # Parse options used as header
+      headers = { 'X-Consul-Token' => configuration.acl_token } if configuration.acl_token
+      headers = { 'X-Consul-Token' => options[:token] } if options[:token]
+
+      # Parse consistency options used as query params
+      consistency = 'stale' if options[:stale]
+      consistency = 'leader' if options[:leader]
+      consistency = 'consistent' if options[:consistent]
+      query_params << consistency
+
+      # Parse url host
+      url_prefix = options[:http_addr] if options[:http_addr]
+      { query_params: query_params, headers: headers, url_prefix: url_prefix }
+    end
+    # rubocop:enable PerceivedComplexity
+
+    def send_get_request(connection, url, options, custom_params = nil)
+      rest_options = parse_options(options)
+      url += rest_options[:query_params]
+      url += custom_params unless custom_params.nil?
+      begin
+        connection.get do |req|
+          req.options[:params_encoder] = options[:params_encoder] if options[:params_encoder]
+          req.url rest_options[:url_prefix] ? rest_options[:url_prefix] + concat_url(url) : concat_url(url)
+          rest_options[:headers].map { |k, v| req.headers[k.to_sym] = v } unless rest_options[:headers].nil?
+          req.options.timeout = options[:timeout] if options[:timeout]
+        end
+      rescue Faraday::ClientError => e
+        raise Diplomat::PathNotFound, e
+      end
+    end
+
+    def send_put_request(connection, url, options, data, custom_params = nil, mime = 'application/json')
+      rest_options = parse_options(options)
+      url += rest_options[:query_params]
+      url += custom_params unless custom_params.nil?
+      connection.put do |req|
+        req.url rest_options[:url_prefix] ? rest_options[:url_prefix] + concat_url(url) : concat_url(url)
+        rest_options[:headers].map { |k, v| req.headers[k.to_sym] = v } unless rest_options[:headers].nil?
+        unless data.nil?
+          (req.headers || {})['Content-Type'] = mime
+          req.body = if mime == 'application/json' && !data.is_a?(String)
+                       data.to_json
+                     else
+                       data
+                     end
+        end
+      end
+    end
+
+    def send_post_request(connection, url, options, data, custom_params = nil)
+      rest_options = parse_options(options)
+      url += rest_options[:query_params]
+      url += custom_params unless custom_params.nil?
+      connection.post do |req|
+        req.url rest_options[:url_prefix] ? rest_options[:url_prefix] + concat_url(url) : concat_url(url)
+        rest_options[:headers].map { |k, v| req.headers[k.to_sym] = v } unless rest_options[:headers].nil?
+        req.body = JSON.dump(data) unless data.nil?
+      end
+    end
+
+    def send_delete_request(connection, url, options, custom_params = nil)
+      rest_options = parse_options(options)
+      url += rest_options[:query_params]
+      url += custom_params unless custom_params.nil?
+      connection.delete do |req|
+        req.url rest_options[:url_prefix] ? rest_options[:url_prefix] + concat_url(url) : concat_url(url)
+        rest_options[:headers].map { |k, v| req.headers[k.to_sym] = v } unless rest_options[:headers].nil?
+      end
+    end
+
+    # Mapping for valid key/value store transaction verbs and required parameters
+    #
+    # @return [Hash] valid key/store transaction verbs and required parameters
+    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
+
+    # 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/service.rb

@@ -0,0 +1,111 @@
+module Diplomat
+  # Methods for interacting with the Consul service API endpoint.
+  class Service < Diplomat::RestClient
+    @access_methods = %i[get get_all register deregister register_external deregister_external maintenance]
+
+    # Get a service by it's key
+    # @param key [String] the key
+    # @param scope [Symbol] :first or :all results
+    # @param options [Hash] options parameter hash
+    # @param meta [Hash] output structure containing header information about the request (index)
+    # @return [OpenStruct] all data associated with the service
+    # rubocop:disable PerceivedComplexity
+    def get(key, scope = :first, options = {}, meta = nil)
+      custom_params = []
+      custom_params << use_named_parameter('wait', options[:wait]) if options[:wait]
+      custom_params << use_named_parameter('index', options[:index]) if options[:index]
+      custom_params << use_named_parameter('dc', options[:dc]) if options[:dc]
+      if options[:tag]
+        # tag can be either a String, or an array of strings
+        # by splatting it is guaranteed to be an array of strings
+        [*options[:tag]].each do |value|
+          custom_params << use_named_parameter('tag', value)
+        end
+      end
+
+      # We have to provide a custom params encoder here because Faraday - by default - assumes that
+      # list keys have [] as part of their name. This is however not the case for consul tags, which
+      # just use repeated occurences of the same key.
+      #
+      # So faraday reduces this: http://localhost:8500?a=1&a=2 to http://localhost:8500?a=2 unless you
+      # explicitly tell it not to.
+      options[:params_encoder] = Faraday::FlatParamsEncoder
+
+      ret = send_get_request(@conn, ["/v1/catalog/service/#{key}"], options, custom_params)
+      if meta && ret.headers
+        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
+
+      if scope == :all
+        JSON.parse(ret.body).map { |service| OpenStruct.new service }
+      else
+        OpenStruct.new JSON.parse(ret.body).first
+      end
+    end
+    # rubocop:enable PerceivedComplexity
+
+    # Get all the services
+    # @param options [Hash] :dc Consul datacenter to query
+    # @return [OpenStruct] the list of all services
+    def get_all(options = {})
+      custom_params = options[:dc] ? use_named_parameter('dc', options[:dc]) : nil
+      ret = send_get_request(@conn, ['/v1/catalog/services'], options, custom_params)
+      OpenStruct.new JSON.parse(ret.body)
+    end
+
+    # Register a service
+    # @param definition [Hash] Hash containing definition of service
+    # @param options [Hash] options parameter hash
+    # @return [Boolean]
+    def register(definition, options = {})
+      url = options[:path] || ['/v1/agent/service/register']
+      register = send_put_request(@conn, url, options, definition)
+      register.status == 200
+    end
+
+    # De-register a service
+    # @param service_name [String] Service name to de-register
+    # @param options [Hash] options parameter hash
+    # @return [Boolean]
+    def deregister(service_name, options = {})
+      deregister = send_put_request(@conn, ["/v1/agent/service/deregister/#{service_name}"], options, nil)
+      deregister.status == 200
+    end
+
+    # Register an external service
+    # @param definition [Hash] Hash containing definition of service
+    # @param options [Hash] options parameter hash
+    # @return [Boolean]
+    def register_external(definition, options = {})
+      register = send_put_request(@conn, ['/v1/catalog/register'], options, definition)
+      register.status == 200
+    end
+
+    # Deregister an external service
+    # @param definition [Hash] Hash containing definition of service
+    # @param options [Hash] options parameter hash
+    # @return [Boolean]
+    def deregister_external(definition, options = {})
+      deregister = send_put_request(@conn, ['/v1/catalog/deregister'], options, definition)
+      deregister.status == 200
+    end
+
+    # Enable or disable maintenance for a service
+    # @param service_id [String] id of the service
+    # @param options [Hash] opts the options for enabling or disabling maintenance for a service
+    # @options opts [Boolean] :enable (true) whether to enable or disable maintenance
+    # @options opts [String] :reason reason for the service maintenance
+    # @raise [Diplomat::PathNotFound] if the request fails
+    # @return [Boolean] if the request was successful or not
+    def maintenance(service_id, options = { enable: true })
+      custom_params = []
+      custom_params << ["enable=#{options[:enable]}"]
+      custom_params << ["reason=#{options[:reason].split(' ').join('+')}"] if options[:reason]
+      maintenance = send_put_request(@conn, ["/v1/agent/service/maintenance/#{service_id}"],
+                                     options, nil, custom_params)
+      maintenance.status == 200
+    end
+  end
+end