elastomer-client 2.3.0 → 3.0.0

data/lib/elastomer/client/scroller.rb

@@ -23,10 +23,8 @@ module Elastomer
       Scroller.new(self, query, opts)
     end
 
-    # DEPRECATED in ES 2.1.0 - use a Scroll query sorted by _doc: https://www.elastic.co/guide/en/elasticsearch/reference/2.3/search-request-search-type.html#scan
-    #
     # Create a new Scroller instance for scrolling all results from a `query`
-    # via "scan" semantics.
+    # via "scan" semantics by sorting by _doc.
     #
     # query  - The query to scan as a Hash or a JSON encoded String
     # opts   - Options Hash
@@ -45,8 +43,7 @@ module Elastomer
     #
     # Returns a new Scroller instance
     def scan( query, opts = {} )
-      opts = opts.merge(:search_type => "scan")
-      Scroller.new(self, query, opts)
+      Scroller.new(self, add_sort_by_doc(query), opts)
     end
 
     # Begin scrolling a query.
@@ -99,7 +96,7 @@ module Elastomer
     #
     # Returns the response body as a Hash.
     def continue_scroll( scroll_id, scroll = "5m" )
-      response = get "/_search/scroll", :body => scroll_id, :scroll => scroll, :action => "search.scroll"
+      response = get "/_search/scroll", :body => {:scroll_id => scroll_id}, :scroll => scroll, :action => "search.scroll"
       response.body
     rescue RequestError => err
       if err.error && err.error["caused_by"]["type"] == "search_context_missing_exception"
@@ -120,7 +117,25 @@ module Elastomer
       response.body
     end
 
-    DEFAULT_OPTS = {
+    # Internal: Add sort by doc to query.
+    #
+    # Raises an exception if the query contains a sort already.
+    # Returns the query as a hash
+    def add_sort_by_doc(query)
+      if query.nil?
+        query = {}
+      elsif query.is_a? String
+        query = MultiJson.load(query)
+      end
+
+      if query.has_key? :sort
+         raise ArgumentError, "Query cannot contain a sort (found sort '#{query[:sort]}' in query: #{query})"
+      end
+
+      query.merge(:sort => [:_doc])
+    end
+
+  DEFAULT_OPTS = {
       :index => nil,
       :type => nil,
       :scroll => "5m",

data/lib/elastomer/client/tasks.rb

@@ -0,0 +1,188 @@
+module Elastomer
+  class Client
+
+    # Returns a Tasks instance for querying the cluster bound to this client for
+    # metadata about internal tasks in flight, and to submit administrative
+    # requests (like cancellation) concerning those tasks.
+    #
+    # Returns a new Tasks object associated with this client
+    def tasks
+      Tasks.new(self)
+    end
+
+    class Tasks
+
+      # TODO - validate params from this whitelist
+      PARAMETERS = %i[
+        nodes
+        actions
+        parent_task_id
+        wait_for_completion
+        pretty
+        detailed
+        timeout
+        group_by
+      ].to_set.freeze
+
+      # Create a new Tasks for introspecting on internal cluster activity.
+      # More context: https://www.elastic.co/guide/en/elasticsearch/reference/5.6/tasks.html
+      #
+      # client     - Elastomer::Client used for HTTP requests to the server
+      #
+      # Raises IncompatibleVersionException if caller attempts to access Tasks API on ES version < 5.0.0
+      def initialize(client)
+        @client = client
+      end
+
+      attr_reader :client
+
+      # Fetch results from the generic _tasks endpoint.
+      #
+      # params       - Hash of request parameters, including:
+      #
+      # Examples
+      #
+      #   tasks.get
+      #   tasks.get :nodes => "DmteLdw1QmSgW3GZmjmoKA,DmteLdw1QmSgW3GZmjmoKB", :actions => "cluster:*", :detailed => true
+      #
+      # Examples (ES 5+ only)
+      #
+      #   tasks.get :group_by => "parents"
+      #   tasks.get :group_by => "parents", :actions => "*reindex", ...
+      #
+      # Returns the response body as a Hash
+      def get(params = {})
+        response = client.get "/_tasks", params
+        response.body
+      end
+
+      # Fetch results from the _tasks endpoint for a particular cluster node and task ID.
+      # NOTE: the API docs note the behavior wrong for this call; "task_id:<task_id>" is really "<node_id>:<task_id>"
+      # where "node_id" is a value from the "nodes" hash returned from the /_tasks endpoint, and "task_id" is
+      # from the "tasks" child hash of any of the "nodes" entries of the /_tasks endpoint
+      #
+      # node_id         - the name of the ES cluster node hosting the target task
+      # task_id         - the numerical ID of the task to return data about in the response
+      # params          - Hash of request parameters to include
+      #
+      # Examples
+      #
+      #  tasks.get_by_id "DmteLdw1QmSgW3GZmjmoKA", 123
+      #  tasks.get_by_id "DmteLdw1QmSgW3GZmjmoKA", 456, :pretty => true
+      #
+      # Returns the response body as a Hash
+      def get_by_id(node_id, task_id, params = {})
+        raise ArgumentError, "invalid node ID provided: #{node_id.inspect}" if node_id.to_s.empty?
+        raise ArgumentError, "invalid task ID provided: #{task_id.inspect}" unless task_id.is_a?(Integer)
+
+        # in this API, the task ID is included in the path, not as a request parameter.
+        response = client.get "/_tasks/#{node_id}:#{task_id}", params
+        response.body
+      end
+
+      # Fetch task details for all child tasks of the specified parent task.
+      # NOTE: the API docs note the behavior wrong for this call: "parentTaskId:<task_id>"
+      # is not the correct syntax for the parent_task_id param value. The correct
+      # value syntax is "<parent_node_id>:<parent_task_id>"
+      #
+      # parent_node_id  - ID of the node the parent task is hosted by
+      # parent_task_id  - ID of a parent task who's child tasks' data will be returned in the response
+      # params          - Hash of request parameters to include
+      #
+      # Examples
+      #
+      #   tasks.get_by_parent_id "DmteLdw1QmSgW3GZmjmoKA", 123
+      #   tasks.get_by_parent_id "DmteLdw1QmSgW3GZmjmoKB", 456, :detailed => true
+      #
+      # Returns the response body as a Hash
+      def get_by_parent_id(parent_node_id, parent_task_id, params = {})
+        raise ArgumentError, "invalid parent node ID provided: #{parent_node_id.inspect}" if node_id.to_s.empty?
+        raise ArgumentError, "invalid parent task ID provided: #{parent_task_id.inspect}" unless parent_task_id.is_a?(Integer)
+
+        # in this API, we pass the parent task ID as a formatted parameter in a request to the _tasks endpoint
+        formatted_parent = { :parent_task_id => "#{parent_node_id}:#{parent_task_id}" }
+        response = client.get "/_tasks", params.merge(formatted_parent)
+        response.body
+      end
+
+      # Wait for the specified amount of time (10 seconds by default) for some task(s) to complete.
+      # Filters for task(s) to wait upon using same filter params as Tasks#get(params)
+      #
+      # timeout         - maximum time to wait for target task to complete before returning, example: "5s"
+      # params          - Hash of request params to include (mostly task filters in this context)
+      #
+      # Examples
+      #
+      # tasks.wait_for "5s", :actions => "*health"
+      # tasks.wait_for("30s", :actions => "*reindex", :nodes => "DmteLdw1QmSgW3GZmjmoKA,DmteLdw1QmSgW3GZmjmoKB")
+      #
+      # Returns the response body as a Hash when timeout expires or target tasks complete
+      # COMPATIBILITY WARNING: the response body differs between ES versions for this API
+      def wait_for(timeout = "10s", params = {}) 
+        params_with_wait = params.merge({ :wait_for_completion => true, :timeout => timeout })
+        self.get(params_with_wait)
+      end
+
+      # Wait for the specified amount of time (10 seconds by default) for some task(s) to complete.
+      # Filters for task(s) to wait upon using same IDs and filter params as Tasks#get_by_id(params)
+      #
+      # node_id                 - the ID of the node on which the target task is hosted
+      # task_id                 - the ID of the task to wait on
+      # timeout                 - time for call to await target tasks completion before returning
+      # params                  - Hash of request params to include (mostly task filters in this context)
+      #
+      # Examples
+      #
+      # tasks.wait_by_id "DmteLdw1QmSgW3GZmjmoKA", 123, "15s"
+      # tasks.wait_by_id "DmteLdw1QmSgW3GZmjmoKA", 456, "30s", :actions => "*search"
+      #
+      # Returns the response body as a Hash when timeout expires or target tasks complete
+      def wait_by_id(node_id, task_id, timeout = "10s", params = {})
+        raise ArgumentError, "invalid node ID provided: #{node_id.inspect}" if node_id.to_s.empty?
+        raise ArgumentError, "invalid task ID provided: #{task_id.inspect}" unless task_id.is_a?(Integer)
+
+        params_with_wait = params.merge({ :wait_for_completion => true, :timeout => timeout })
+        self.get_by_id(node_id, task_id, params_with_wait)
+      end
+
+      # Cancels a task running on a particular node.
+      # NOTE: the API docs note the behavior wrong for this call; "task_id:<task_id>" is really "<node_id>:<task_id>"
+      # where "node_id" is a value from the "nodes" hash returned from the /_tasks endpoint, and "task_id" is
+      # from the "tasks" child hash of any of the "nodes" entries of the /_tasks endpoint
+      #
+      # node_id         - the ES node hosting the task to be cancelled
+      # task_id         - ID of the task to be cancelled
+      # params          - Hash of request parameters to include
+      #
+      # Examples
+      #
+      #   tasks.cancel_by_id "DmteLdw1QmSgW3GZmjmoKA", 123
+      #   tasks.cancel_by_id "DmteLdw1QmSgW3GZmjmoKA", 456, :pretty => true
+      #
+      # Returns the response body as a Hash
+      def cancel_by_id(node_id, task_id, params = {})
+        raise ArgumentError, "invalid node ID provided: #{node_id.inspect}" if node_id.to_s.empty?
+        raise ArgumentError, "invalid task ID provided: #{task_id.inspect}" unless task_id.is_a?(Integer)
+
+        response = client.post "/_tasks/#{node_id}:#{task_id}/_cancel", params
+        response.body
+      end
+
+      # Cancels a task or group of tasks using various filtering parameters.
+      #
+      # params          - Hash of request parameters to include
+      #
+      # Examples
+      #
+      #   tasks.cancel :actions => "*reindex"
+      #   tasks.cancel :actions => "*search", :nodes => "DmteLdw1QmSgW3GZmjmoKA,DmteLdw1QmSgW3GZmjmoKB,DmteLdw1QmSgW3GZmjmoKC"
+      #
+      # Returns the response body as a Hash
+      def cancel(params = {})
+        response = client.post "/_tasks/_cancel", params
+        response.body
+      end
+
+    end # end class Tasks
+  end # end class Client
+end # end module Elastomer

data/lib/elastomer/client/warmer.rb

@@ -1,6 +1,8 @@
 module Elastomer
   class Client
 
+    # DEPRECATED: Warmers have been removed from Elasticsearch as of 5.0.
+    # See https://www.elastic.co/guide/en/elasticsearch/reference/5.0/indices-warmers.html
     class Warmer
 
       # Create a new Warmer helper for making warmer API requests.
@@ -9,6 +11,10 @@ module Elastomer
       # index_name - The name of the index as a String
       # name       - The name of the warmer as a String
       def initialize(client, index_name, name)
+        unless client.version_support.supports_warmers?
+          raise IncompatibleVersionException, "ES #{client.version} does not support warmers"
+        end
+
         @client     = client
         @index_name = @client.assert_param_presence(index_name, "index name")
         @name       = @client.assert_param_presence(name, "warmer name")

data/lib/elastomer/notifications.rb

@@ -69,6 +69,7 @@ module Elastomer
         payload[:method]        = response.env[:method]
         payload[:status]        = response.status
         payload[:response_body] = response.body
+        payload[:retries]       = params[:retries]
         response
       end
     end

data/lib/elastomer/version.rb

@@ -1,5 +1,5 @@
 module Elastomer
-  VERSION = "2.3.0"
+  VERSION = "3.0.0"
 
   def self.version
     VERSION

data/lib/elastomer/version_support.rb

@@ -0,0 +1,177 @@
+module Elastomer
+  # VersionSupport holds methods that (a) encapsulate version differences; or
+  # (b) give an intention-revealing name to a conditional check.
+  class VersionSupport
+    COMMON_INDEXING_PARAMETER_NAMES = %i[
+      index
+      type
+      id
+      version
+      version_type
+      op_type
+      routing
+      parent
+      refresh
+    ].freeze
+    ES_2_X_INDEXING_PARAMETER_NAMES = %i[consistency ttl timestamp].freeze
+    ES_5_X_INDEXING_PARAMETER_NAMES = %i[wait_for_active_shards].freeze
+    KNOWN_INDEXING_PARAMETER_NAMES =
+      (COMMON_INDEXING_PARAMETER_NAMES + ES_2_X_INDEXING_PARAMETER_NAMES + ES_5_X_INDEXING_PARAMETER_NAMES).freeze
+
+    attr_reader :version
+
+    # version - an Elasticsearch version string e.g., 2.3.5 or 5.3.0
+    #
+    # Raises ArgumentError if version is unsupported.
+    def initialize(version)
+      if version < "2.3" || version >= "5.7"
+        raise ArgumentError, "Elasticsearch version #{version} is not supported by elastomer-client"
+      end
+
+      @version = version
+    end
+
+    # COMPATIBILITY: Return a boolean indicating if this version supports warmers.
+    # Warmers were removed in ES 5.0.
+    def supports_warmers?
+      es_version_2_x?
+    end
+
+    # COMPATIBILITY: The Tasks API is evolving quickly; features, and request/response
+    # structure can differ across ES versions
+    def tasks_new_response_format?
+      es_version_5_x?
+    end
+
+    # COMPATIBILITY: Return a "text"-type mapping for a field.
+    #
+    # On ES 2.x, this will be a string field. On ES 5+, it will be a text field.
+    def text(**args)
+      reject_args!(args, :type, :index)
+
+      if es_version_2_x?
+        {type: "string"}.merge(args)
+      else
+        {type: "text"}.merge(args)
+      end
+    end
+
+    # COMPATIBILITY: Return a "keyword"-type mapping for a field.
+    #
+    # On ES 2.x, this will be a string field with not_analyzed=true. On ES 5+,
+    # it will be a keyword field.
+    def keyword(**args)
+      reject_args!(args, :type, :index)
+
+      if es_version_2_x?
+        {type: "string", index: "not_analyzed"}.merge(args)
+      else
+        {type: "keyword"}.merge(args)
+      end
+    end
+
+    # Elasticsearch 2.0 changed some request formats in a non-backward-compatible
+    # way. Some tests need to know what version is running to structure requests
+    # as expected.
+    #
+    # Returns true if Elasticsearch version is 2.x.
+    def es_version_2_x?
+      version >= "2.0.0" && version <  "3.0.0"
+    end
+
+    # Elasticsearch 5.0 changed some request formats in a non-backward-compatible
+    # way. Some tests need to know what version is running to structure requests
+    # as expected.
+    #
+    # Returns true if Elasticsearch version is 5.x.
+    def es_version_5_x?
+      version >= "5.0.0" && version < "6.0.0"
+    end
+
+    # Wraps version check and param gen where ES version >= 5.x requires
+    # percolator type + field defined in mappings
+    def percolator_type
+      if es_version_5_x?
+        "percolator"
+      else
+        ".percolator"
+      end
+    end
+
+    # COMPATIBILITY
+    # ES 2.x reports query parsing exceptions as query_parse_exception whereas
+    # ES 5.x reports them as query_shard_exception or parsing_exception
+    # depending on when the error occurs.
+    #
+    # Returns an Array of Strings to match.
+    def query_parse_exception
+      if es_version_2_x?
+        ["query_parsing_exception"]
+      else
+        ["query_shard_exception", "parsing_exception"]
+      end
+    end
+
+    # COMPATIBILITY
+    # ES 5.X supports `delete_by_query` natively again.
+    alias :native_delete_by_query? :es_version_5_x?
+
+    # COMPATIBILITY
+    # Return a Hash of indexing request parameters that are valid for this
+    # version of Elasticsearch.
+    def indexing_directives
+      return @indexing_directives if defined?(@indexing_directives)
+
+      @indexing_directives = indexing_parameter_names.each_with_object({}) do |key, h|
+        h[key] = "_#{key}"
+      end
+      @indexing_directives.freeze
+    end
+
+    # COMPATIBILITY
+    # Return a Hash of indexing request parameters that are known to
+    # elastomer-client, but not supported by the current version of
+    # Elasticsearch.
+    def unsupported_indexing_directives
+      return @unsupported_indexing_directives if defined?(@unsupported_indexing_directives)
+
+      unsupported_keys = KNOWN_INDEXING_PARAMETER_NAMES - indexing_parameter_names
+
+      @unsupported_indexing_directives = unsupported_keys.each_with_object({}) do |key, h|
+        h[key] = "_#{key}"
+      end
+      @unsupported_indexing_directives.freeze
+    end
+
+    # COMPATIBILITY
+    # Return a symbol representing the best supported delete_by_query
+    # implementation for this version of Elasticsearch.
+    def delete_by_query_method
+      if es_version_2_x?
+        :app_delete_by_query
+      else
+        :native_delete_by_query
+      end
+    end
+
+    private
+
+    # Internal: Helper to reject arguments that shouldn't be passed because
+    # merging them in would defeat the purpose of a compatibility layer.
+    def reject_args!(args, *names)
+      names.each do |name|
+        if args.include?(name.to_s) || args.include?(name.to_sym)
+          raise ArgumentError, "Argument '#{name}' is not allowed"
+        end
+      end
+    end
+
+    def indexing_parameter_names
+      if es_version_2_x?
+        COMMON_INDEXING_PARAMETER_NAMES + ES_2_X_INDEXING_PARAMETER_NAMES
+      else
+        COMMON_INDEXING_PARAMETER_NAMES + ES_5_X_INDEXING_PARAMETER_NAMES
+      end
+    end
+  end
+end