elastomer-client 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d0dde42bf5e2cd7b2a2da696528ec66b8b44c75
-  data.tar.gz: 82b5315520a01408b40c97149649a197196d0d4e
+  metadata.gz: a3bb86cf79cf4c35faa602b5b887790916354830
+  data.tar.gz: 0d20d421a0c1c396efaaa01edfc0c7eb621deb37
 SHA512:
-  metadata.gz: e73b854104d40f4d2310e78f3bb480b1c1ca6b91be50bcd93f263fc7a6373364cacdea81c00a955818788e915d20b23fd9c713cd78b410ea25bdd7d6a4eeab2c
-  data.tar.gz: d2091b590bb120763fbe74c6e4b4ce2fcdef423bb61dd249e39ef17c781cd78f990ebeb5382a32ffbb36808f8103eb1119381207541bfb3ceaabdb3ab9d6e4f0
+  metadata.gz: 0043c22c958488f7952e814a05390df0dfb1b3746414b66d33b22ea5951f489155bd2ac820d47c541f9b3146f73a1a7a9c93af0b88769318ff1229bf112a160e
+  data.tar.gz: ca7cf1438d19f70fa2f73bf4b2ff7a22e8ef74453f8914dfa646b83163b4df0a4216fbd6cc5666b153dc2bcebd3af602f7240f28b449b22f07d61808fd27a608

data/CHANGELOG.md

@@ -1,7 +1,18 @@
+## 0.4.0 (2014-10-08)
+- BREAKING: docs.add alias for docs.index removed
+- BREAKING: Faraday exceptions are now raised as Elastomer exceptions
+- Repository and snapshot support
+- Support cluster state filtering on 1.x
+- Support node stats filtering on 1.x
+- New apis: cluster stats, cluster pending\_tasks
+- Support single-index alias get, add, delete
+
 ## 0.3.3 (2014-08-18)
 - Allow symbols as parameter values #67
+
 ## 0.3.2 (2014-07-02)
 - Make underscore optional in bulk params #66
+
 ## 0.3.1 (2014-06-24)
 - First rubygems release
 - Make `update_aliases` more flexible

data/docs/notifications.md

@@ -20,16 +20,16 @@ The event namespace is `request.client.elastomer`.
 
 ## Valid actions
 - bulk
-- cluster.get_settings
-- cluster.health
-- cluster.reroute
-- cluster.state
-- cluster.update_settings
 - cluster.available
 - cluster.get_aliases
+- cluster.get_settings
+- cluster.health
 - cluster.info
+- cluster.reroute
 - cluster.shutdown
+- cluster.state
 - cluster.update_aliases
+- cluster.update_settings
 - docs.delete
 - docs.delete_by_query
 - docs.explain
@@ -65,7 +65,19 @@ The event namespace is `request.client.elastomer`.
 - nodes.info
 - nodes.shutdown
 - nodes.stats
+- repository.create
+- repository.delete
+- repository.exists
+- repository.get
+- repository.status
+- repository.update
 - search.scan
 - search.scroll
+- snapshot.create
+- snapshot.delete
+- snapshot.exists
+- snapshot.get
+- snapshot.restore
+- snapshot.status
 - template.create
 - template.get

data/lib/elastomer/client.rb

@@ -188,7 +188,22 @@ module Elastomer
       handle_errors response
 
     rescue Faraday::Error::TimeoutError => boom
-      raise ::Elastomer::Client::TimeoutError.new(boom, path)
+      raise TimeoutError.new(boom, method.upcase, path)
+
+    rescue Faraday::Error::ConnectionFailed => boom
+      raise ConnectionFailed.new(boom, method.upcase, path)
+
+    rescue Faraday::Error::ResourceNotFound => boom
+      raise ResourceNotFound.new(boom, method.upcase, path)
+
+    rescue Faraday::Error::ParsingError => boom
+      raise ParsingError.new(boom, method.upcase, path)
+
+    rescue Faraday::Error::SSLError => boom
+      raise SSLError.new(boom, method.upcase, path)
+
+    rescue Faraday::Error::ClientError => boom
+      raise Error.new(boom, method.upcase, path)
 
     # ensure
     #   # FIXME: this is here until we get a real logger in place
@@ -259,8 +274,8 @@ module Elastomer
     # Raises an Elastomer::Client::Error on 500 responses or responses
     # containing and 'error' field.
     def handle_errors( response )
-      raise Error, response if response.status >= 500
-      raise Error, response if Hash === response.body && response.body['error']
+      raise ServerError, response if response.status >= 500
+      raise RequestError, response if Hash === response.body && response.body['error']
 
       response
     end

data/lib/elastomer/client/bulk.rb

@@ -135,7 +135,6 @@ module Elastomer
         params = prepare_params(document, params)
         add_to_actions({:index => params}, document)
       end
-      alias :add :index
 
       # Add a create action to the list of bulk actions to be performed when
       # the bulk API call is made. Parameters can be provided in the

data/lib/elastomer/client/cluster.rb

@@ -19,10 +19,18 @@ module Elastomer
 
       attr_reader :client
 
-      # Simple status on the health of the cluster.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-health/
+      # Simple status on the health of the cluster. The API can also be executed
+      # against one or more indices to get just the specified indices health.
       #
       # params - Parameters Hash
+      #   :index - a single index name or an Array of index names
+      #   :level - one of "cluster", "indices", or "shards"
+      #   :wait_for_status - one of "green", "yellow", or "red"
+      #   :wait_for_relocating_shards - a number controlling to how many relocating shards to wait for
+      #   :wait_for_nodes - the request waits until the specified number N of nodes is available
+      #   :timeout - how long to wait [default is "30s"]
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-health.html
       #
       # Returns the response as a Hash
       def health( params = {} )
@@ -30,22 +38,58 @@ module Elastomer
         response.body
       end
 
-      # Comprehensive state information of the whole cluster.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-state/
+      # Comprehensive state information of the whole cluster. For 1.x metric
+      # and index filtering, use the :metrics and :indices parameter keys.
+      #
+      # The list of available metrics are:
+      #   version, master_node, nodes, routing_table, metadata, blocks
       #
       # params - Parameters Hash
+      #   :metrics - list of metrics to select as an Array
+      #   :indices - a single index name or an Array of index names
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-state.html
       #
       # Returns the response as a Hash
       def state( params = {} )
-        response = client.get '/_cluster/state', params.merge(:action => 'cluster.state')
+        response = client.get '/_cluster/state{/metrics}{/indices}', params.merge(:action => 'cluster.state')
+        response.body
+      end
+
+      # Retrieve statistics from a cluster wide perspective. The API returns
+      # basic index metrics (shard numbers, store size, memory usage) and
+      # information about the current nodes that form the cluster (number,
+      # roles, os, jvm versions, memory usage, cpu and installed plugins).
+      #
+      # params - Parameters Hash
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-stats.html
+      #
+      # Returns the response as a Hash
+      def stats( params = {} )
+        response = client.get '/_cluster/stats', params.merge(:action => 'cluster.stats')
+        response.body
+      end
+
+      # Returns a list of any cluster-level changes (e.g. create index, update
+      # mapping, allocate or fail shard) which have not yet been executed.
+      #
+      # params - Parameters Hash
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-pending.html
+      #
+      # Returns the response as a Hash
+      def pending_tasks( params = {} )
+        response = client.get '/_cluster/pending_tasks', params.merge(:action => 'cluster.pending_tasks')
         response.body
       end
 
       # Cluster wide settings that have been modified via the update API.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-update-settings/
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-update-settings.html
+      #
       # Returns the response as a Hash
       def get_settings( params = {} )
         response = client.get '/_cluster/settings', params.merge(:action => 'cluster.get_settings')
@@ -57,11 +101,11 @@ module Elastomer
       # persistent (applied cross restarts) or transient (will not survive a
       # full cluster restart).
       #
-      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-update-settings/
-      #
       # body   - The new settings as a Hash or a JSON encoded String
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-update-settings.html
+      #
       # Returns the response as a Hash
       def update_settings( body, params = {} )
         response = client.put '/_cluster/settings', params.merge(:body => body, :action => 'cluster.update_settings')
@@ -73,8 +117,6 @@ module Elastomer
       # allocation can be canceled, or an unassigned shard can be explicitly
       # allocated on a specific node.
       #
-      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-reroute/
-      #
       # commands - A command Hash or an Array of command Hashes
       # params   - Parameters Hash
       #
@@ -87,20 +129,23 @@ module Elastomer
       #     { :allocate => { :index => 'test', :shard => 1, :node => 'node3' }}
       #   ])
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-reroute.html
+      #
       # Returns the response as a Hash
       def reroute( commands, params = {} )
-        commands = [commands] unless Array === commands
-        body = {:commands => commands}
+        body = {:commands => Array(commands)}
 
         response = client.post '/_cluster/reroute', params.merge(:body => body, :action => 'cluster.reroute')
         response.body
       end
 
-      # Shutdown the entire cluster.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-nodes-shutdown/
+      # Shutdown the entire cluster. There is also a Nodes#shutdown method for
+      # shutting down individual nodes.
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-nodes-shutdown.html
+      #
       # Returns the response as a Hash
       def shutdown( params = {} )
         response = client.post '/_shutdown', params.merge(:action => 'cluster.shutdown')
@@ -112,15 +157,16 @@ module Elastomer
       # can also use the alias name here since it is acting the part of an
       # index.
       #
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
-      #
       # params - Parameters Hash
+      #   :index - an index name or Array of index names
       #
       # Examples
       #
       #   get_aliases
       #   get_aliases( :index => 'users' )
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-aliases.html
+      #
       # Returns the response body as a Hash
       def get_aliases( params = {} )
         response = client.get '{/index}/_aliases', params.merge(:action => 'cluster.get_aliases')
@@ -133,8 +179,6 @@ module Elastomer
       # actions. This API method will wrap the request in the appropriate
       # {:actions => [...]} body construct.
       #
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
-      #
       # actions - An action Hash or an Array of action Hashes
       # params  - Parameters Hash
       #
@@ -147,6 +191,8 @@ module Elastomer
       #     { :add    => { :index => 'users-2', :alias => 'users' }}
       #   ])
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-aliases.html
+      #
       # Returns the response body as a Hash
       def update_aliases( actions, params = {} )
         if actions.is_a?(Hash) && actions.key?(:actions)
@@ -168,11 +214,17 @@ module Elastomer
       #
       # Returns the template definitions as a Hash
       def templates
-        h = state(
-          :filter_blocks        => true,
-          :filter_nodes         => true,
-          :filter_routing_table => true
-        )
+        # ES 1.x supports state filtering via a path segment called metrics.
+        # ES 0.90 uses query parameters instead.
+        if client.semantic_version >= '1.0.0'
+          h = state(:metrics => 'metadata')
+        else
+          h = state(
+            :filter_blocks        => true,
+            :filter_nodes         => true,
+            :filter_routing_table => true,
+          )
+        end
         h['metadata']['templates']
       end
 
@@ -181,11 +233,17 @@ module Elastomer
       #
       # Returns the indices definitions as a Hash
       def indices
-        h = state(
-          :filter_blocks        => true,
-          :filter_nodes         => true,
-          :filter_routing_table => true
-        )
+        # ES 1.x supports state filtering via a path segment called metrics.
+        # ES 0.90 uses query parameters instead.
+        if client.semantic_version >= '1.0.0'
+          h = state(:metrics => 'metadata')
+        else
+          h = state(
+            :filter_blocks        => true,
+            :filter_nodes         => true,
+            :filter_routing_table => true,
+          )
+        end
         h['metadata']['indices']
       end
 
@@ -195,11 +253,17 @@ module Elastomer
       #
       # Returns the nodes definitions as a Hash
       def nodes
-        h = state(
-          :filter_blocks        => true,
-          :filter_metadata      => true,
-          :filter_routing_table => true
-        )
+        # ES 1.x supports state filtering via a path segment called metrics.
+        # ES 0.90 uses query parameters instead.
+        if client.semantic_version >= '1.0.0'
+          h = state(:metrics => 'nodes')
+        else
+          h = state(
+            :filter_blocks        => true,
+            :filter_metadata      => true,
+            :filter_routing_table => true,
+          )
+        end
         h['nodes']
       end
 

data/lib/elastomer/client/docs.rb

@@ -52,7 +52,6 @@ module Elastomer
 
         response.body
       end
-      alias :add :index
 
       # Delete a document from the index based on the document ID. The :id is
       # provided as part of the params hash.

data/lib/elastomer/client/errors.rb

@@ -14,38 +14,68 @@ module Elastomer
       # extracted from the response body.
       #
       # response - Faraday::Response object or a simple error message String
-      def initialize( response )
-        if response.respond_to? :body
+      #
+      def initialize( *args )
+        @status = nil
+
+        case args.first
+        when Exception
+          exception = args.shift
+          super("#{exception.message} :: #{args.join(' ')}")
+          set_backtrace exception.backtrace
+
+        when Faraday::Response
+          response = args.shift
           message = Hash === response.body && response.body['error'] || response.body.to_s
+          @status = response.status
+          super message
+
         else
-          message, response = response.to_s, nil
+          super args.join(' ')
         end
-
-        @status = response.nil? ? nil : response.status
-
-        super message
       end
 
       # Returns the status code from the `response` or nil if the Error was not
       # created with a response.
       attr_reader :status
 
-    end  # Error
+      # Indicates that the error is fatal. The request should not be tried
+      # again.
+      def fatal?
+        self.class.fatal?
+      end
 
-    # Timeout specific error class.
-    class TimeoutError < ::Elastomer::Error
+      # The inverse of the `fatal?` method. A request can be retried if this
+      # method returns `true`.
+      def retry?
+        !fatal?
+      end
 
-      # Wrap a Farday TimeoutError with our own class and include the HTTP
-      # path where the error originated.
-      #
-      # exception - The originating Faraday::Error::TimeoutError
-      # path      - The path portion of the HTTP request
-      #
-      def initialize( exception, path )
-        super "#{exception.message}: #{path}"
-        set_backtrace exception.backtrace
+      class << self
+        # By default all client errors are fatal and indicate that a request
+        # should not be retried. Only a few errors are retryable.
+        def fatal
+          return @fatal if defined? @fatal
+          @fatal = true
+        end
+        attr_writer :fatal
+        alias :fatal? :fatal
       end
-    end  # TimeoutError
+
+    end  # Error
+
+    # Wrapper classes for specific Faraday errors.
+    TimeoutError     = Class.new Error
+    ConnectionFailed = Class.new Error
+    ResourceNotFound = Class.new Error
+    ParsingError     = Class.new Error
+    SSLError         = Class.new Error
+    ServerError      = Class.new Error
+    RequestError     = Class.new Error
+
+    ServerError.fatal      = false
+    TimeoutError.fatal     = false
+    ConnectionFailed.fatal = false
 
   end  # Client
 end  # Elastomer