[API] [1.0] Added the "Snapshot & Restore" API

See: http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-snapshots.html

Related:

* elastic/elasticsearch#3070
* elastic/elasticsearch#3826

elasticsearch-api/lib/elasticsearch/api.rb

@@ -28,7 +28,8 @@ def self.included(base)
                 Elasticsearch::API::Actions,
                 Elasticsearch::API::Cluster,
                 Elasticsearch::API::Nodes,
-                Elasticsearch::API::Indices
+                Elasticsearch::API::Indices,
+                Elasticsearch::API::Snapshot
     end
   end
 end

elasticsearch-api/lib/elasticsearch/api/actions/snapshot/create.rb

@@ -0,0 +1,48 @@
+module Elasticsearch
+  module API
+    module Snapshot
+      module Actions
+
+        # Create a new snapshot in the repository
+        #
+        # @example Create a snapshot of the whole cluster in the `my-backups` repository
+        #
+        #     client.snapshot.create repository: 'my-backups', snapshot: 'snapshot-1'
+        #
+        # @example Create a snapshot for specific indices in the `my-backups` repository
+        #
+        #     client.snapshot.create repository: 'my-backups',
+        #                            snapshot: 'snapshot-2',
+        #                            body: { indices: 'foo,bar', ignore_unavailable: true }
+        #
+        # @option arguments [String] :repository A repository name (*Required*)
+        # @option arguments [String] :snapshot A snapshot name (*Required*)
+        # @option arguments [Hash] :body The snapshot definition
+        # @option arguments [Time] :master_timeout Explicit operation timeout for connection to master node
+        # @option arguments [Boolean] :wait_for_completion Whether the request should block and wait until
+        #                                                  the operation has completed
+        #
+        # @see http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-snapshots.html
+        #
+        def create(arguments={})
+          raise ArgumentError, "Required argument 'repository' missing" unless arguments[:repository]
+          raise ArgumentError, "Required argument 'snapshot' missing"   unless arguments[:snapshot]
+          valid_params = [
+            :master_timeout,
+            :wait_for_completion ]
+
+          repository = arguments.delete(:repository)
+          snapshot   = arguments.delete(:snapshot)
+
+          method = 'PUT'
+          path   = Utils.__pathify( '_snapshot', Utils.__escape(repository), Utils.__escape(snapshot) )
+
+          params = Utils.__validate_and_extract_params arguments, valid_params
+          body   = arguments[:body]
+
+          perform_request(method, path, params, body).body
+        end
+      end
+    end
+  end
+end

elasticsearch-api/lib/elasticsearch/api/actions/snapshot/create_repository.rb

@@ -0,0 +1,44 @@
+module Elasticsearch
+  module API
+    module Snapshot
+      module Actions
+
+        # Create a repository for storing snapshots
+        #
+        # @example Create a repository at `/tmp/backup`
+        #
+        #     client.snapshot.create_repository repository: 'my-backups',
+        #                                       body: {
+        #                                         type: 'fs',
+        #                                         settings: { location: '/tmp/backup', compress: true  }
+        #                                       }
+        #
+        # @option arguments [String] :repository A repository name (*Required*)
+        # @option arguments [Hash] :body The repository definition (*Required*)
+        # @option arguments [Time] :master_timeout Explicit operation timeout for connection to master node
+        # @option arguments [Time] :timeout Explicit operation timeout
+        #
+        # @see http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-snapshots.html
+        #
+        def create_repository(arguments={})
+          raise ArgumentError, "Required argument 'repository' missing" unless arguments[:repository]
+          raise ArgumentError, "Required argument 'body' missing"       unless arguments[:body]
+          valid_params = [
+            :repository,
+            :master_timeout,
+            :timeout ]
+
+          repository = arguments.delete(:repository)
+
+          method = 'PUT'
+          path   = Utils.__pathify( '_snapshot', Utils.__escape(repository) )
+
+          params = Utils.__validate_and_extract_params arguments, valid_params
+          body   = arguments[:body]
+
+          perform_request(method, path, params, body).body
+        end
+      end
+    end
+  end
+end

elasticsearch-api/lib/elasticsearch/api/actions/snapshot/delete.rb

@@ -0,0 +1,41 @@
+module Elasticsearch
+  module API
+    module Snapshot
+      module Actions
+
+        # Delete a snapshot from the repository
+        #
+        # @note Will also abort a currently running snapshot.
+        #
+        # @example Delete the `snapshot-1` snapshot
+        #
+        #     client.snapshot.delete repository: 'my-backups', snapshot: 'snapshot-1'
+        #
+        # @option arguments [String] :repository A repository name (*Required*)
+        # @option arguments [String] :snapshot A snapshot name (*Required*)
+        # @option arguments [Time] :master_timeout Explicit operation timeout for connection to master node
+        #
+        # @see http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-snapshots.html
+        #
+        def delete(arguments={})
+          raise ArgumentError, "Required argument 'repository' missing" unless arguments[:repository]
+          raise ArgumentError, "Required argument 'snapshot' missing"   unless arguments[:snapshot]
+
+          valid_params = [
+            :master_timeout ]
+
+          repository = arguments.delete(:repository)
+          snapshot   = arguments.delete(:snapshot)
+
+          method = 'DELETE'
+          path   = Utils.__pathify( '_snapshot', Utils.__escape(repository), Utils.__listify(snapshot) )
+
+          params = Utils.__validate_and_extract_params arguments, valid_params
+          body   = nil
+
+          perform_request(method, path, params, body).body
+        end
+      end
+    end
+  end
+end

elasticsearch-api/lib/elasticsearch/api/actions/snapshot/delete_repository.rb

@@ -0,0 +1,38 @@
+module Elasticsearch
+  module API
+    module Snapshot
+      module Actions
+
+        # Delete a specific repository or repositories
+        #
+        # @example Delete the `my-backups` repository
+        #
+        #     client.snapshot.delete_repository repository: 'my-backups'
+        #
+        # @option arguments [List] :repository A comma-separated list of repository names (*Required*)
+        # @option arguments [Time] :master_timeout Explicit operation timeout for connection to master node
+        # @option arguments [Time] :timeout Explicit operation timeout
+        #
+        # @see http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-snapshots.html
+        #
+        def delete_repository(arguments={})
+          raise ArgumentError, "Required argument 'repository' missing" unless arguments[:repository]
+
+          valid_params = [
+            :master_timeout,
+            :timeout ]
+
+          repository = arguments.delete(:repository)
+
+          method = 'DELETE'
+          path   = Utils.__pathify( '_snapshot', Utils.__listify(repository) )
+
+          params = Utils.__validate_and_extract_params arguments, valid_params
+          body   = nil
+
+          perform_request(method, path, params, body).body
+        end
+      end
+    end
+  end
+end

elasticsearch-api/lib/elasticsearch/api/actions/snapshot/get.rb

@@ -0,0 +1,47 @@
+module Elasticsearch
+  module API
+    module Snapshot
+      module Actions
+
+        # Return information about specific (or all) snapshots
+        #
+        # @example Return information about the `snapshot-2` snapshot
+        #
+        #     client.snapshot.get repository: 'my-backup', snapshot: 'snapshot-2'
+        #
+        # @example Return information about multiple snapshots
+        #
+        #     client.snapshot.get repository: 'my-backup', snapshot: ['snapshot-2', 'snapshot-3']
+        #
+        # @example Return information about all snapshots in the repository
+        #
+        #     client.snapshot.get repository: 'my-backup', snapshot: '_all'
+        #
+        # @option arguments [String] :repository A repository name (*Required*)
+        # @option arguments [List] :snapshot A comma-separated list of snapshot names (*Required*)
+        # @option arguments [Time] :master_timeout Explicit operation timeout for connection to master node
+        #
+        # @see http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-snapshots.html
+        #
+        def get(arguments={})
+          raise ArgumentError, "Required argument 'repository' missing" unless arguments[:repository]
+          raise ArgumentError, "Required argument 'snapshot' missing"   unless arguments[:snapshot]
+
+          valid_params = [
+            :master_timeout ]
+
+          repository = arguments.delete(:repository)
+          snapshot   = arguments.delete(:snapshot)
+
+          method = 'GET'
+          path   = Utils.__pathify( '_snapshot', Utils.__escape(repository), Utils.__listify(snapshot) )
+
+          params = Utils.__validate_and_extract_params arguments, valid_params
+          body   = nil
+
+          perform_request(method, path, params, body).body
+        end
+      end
+    end
+  end
+end

elasticsearch-api/lib/elasticsearch/api/actions/snapshot/get_repository.rb

@@ -0,0 +1,42 @@
+module Elasticsearch
+  module API
+    module Snapshot
+      module Actions
+
+        # Get information about snapshot repositories or a specific repository
+        #
+        # @example Get all repositories
+        #
+        #     client.snapshot.get_repository
+        #
+        # @example Get a specific repository
+        #
+        #     client.snapshot.get_repository repository: 'my-backups'
+        #
+        # @option arguments [List] :repository A comma-separated list of repository names. Leave blank or use `_all`
+        #                                      to get a list of repositories
+        # @option arguments [Time] :master_timeout Explicit operation timeout for connection to master node
+        # @option arguments [Boolean] :local Return local information, do not retrieve the state from master node
+        #                                    (default: false)
+        #
+        # @see http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-snapshots.html
+        #
+        def get_repository(arguments={})
+          valid_params = [
+            :master_timeout,
+            :local ]
+
+          repository = arguments.delete(:repository)
+
+          method = 'GET'
+          path   = Utils.__pathify( '_snapshot', Utils.__escape(repository) )
+
+          params = Utils.__validate_and_extract_params arguments, valid_params
+          body   = nil
+
+          perform_request(method, path, params, body).body
+        end
+      end
+    end
+  end
+end

elasticsearch-api/lib/elasticsearch/api/actions/snapshot/restore.rb

@@ -0,0 +1,53 @@
+module Elasticsearch
+  module API
+    module Snapshot
+      module Actions
+
+        # Restore the state from a snapshot
+        #
+        # @example Restore from the `snapshot-1` snapshot
+        #
+        #     client.snapshot.restore repository: 'my-backups', snapshot: 'snapshot-1'
+        #
+        # @example Restore a specific index under a different name
+        #
+        #     client.snapshot.restore repository: 'my-backups',
+        #                             snapshot: 'snapshot-5',
+        #                             body: {
+        #                               rename_pattern: "^(.*)$",
+        #                               rename_replacement: "restored_$1"
+        #                             }
+        #
+        # @note You cannot restore into an open index, you have to {Indices::Actions#close} it first
+        #
+        # @option arguments [String] :repository A repository name (*Required*)
+        # @option arguments [String] :snapshot A snapshot name (*Required*)
+        # @option arguments [Hash] :body Details of what to restore
+        # @option arguments [Time] :master_timeout Explicit operation timeout for connection to master node
+        # @option arguments [Boolean] :wait_for_completion Should this request wait until the operation has completed before returning
+        #
+        # @see http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-snapshots.html
+        #
+        def restore(arguments={})
+          raise ArgumentError, "Required argument 'repository' missing" unless arguments[:repository]
+          raise ArgumentError, "Required argument 'snapshot' missing"   unless arguments[:snapshot]
+
+          valid_params = [
+            :master_timeout,
+            :wait_for_completion ]
+
+          repository = arguments.delete(:repository)
+          snapshot   = arguments.delete(:snapshot)
+
+          method = 'POST'
+          path   = Utils.__pathify( '_snapshot', Utils.__escape(repository), Utils.__escape(snapshot), '_restore' )
+
+          params = Utils.__validate_and_extract_params arguments, valid_params
+          body   = arguments[:body]
+
+          perform_request(method, path, params, body).body
+        end
+      end
+    end
+  end
+end

elasticsearch-api/lib/elasticsearch/api/namespace/snapshot.rb

@@ -0,0 +1,20 @@
+module Elasticsearch
+  module API
+    module Snapshot
+      module Actions; end
+
+      # Client for the "snapshot" namespace (includes the {Snapshot::Actions} methods)
+      #
+      class SnapshotClient
+        include Common::Client, Common::Client::Base, Snapshot::Actions
+      end
+
+      # Proxy method for {SnapshotClient}, available in the receiving object
+      #
+      def snapshot
+        @snapshot ||= SnapshotClient.new(self)
+      end
+
+    end
+  end
+end

elasticsearch-api/test/unit/snapshot/create_repository_test.rb

@@ -0,0 +1,38 @@
+require 'test_helper'
+
+module Elasticsearch
+  module Test
+    class SnapshotCreateRepositoryTest < ::Test::Unit::TestCase
+
+      context "Snapshot: Create repository" do
+        subject { FakeClient.new }
+
+        should "require the :repository argument" do
+          assert_raise ArgumentError do
+            subject.snapshot.create_repository :body => {}
+          end
+        end
+
+        should "require the :body argument" do
+          assert_raise ArgumentError do
+            subject.snapshot.create_repository :repository => 'foo'
+          end
+        end
+
+        should "perform correct request" do
+          subject.expects(:perform_request).with do |method, url, params, body|
+            assert_equal 'PUT', method
+            assert_equal '_snapshot/foo', url
+            assert_equal Hash.new, params
+            assert_equal Hash.new, body
+            true
+          end.returns(FakeResponse.new)
+
+          subject.snapshot.create_repository :repository => 'foo', :body => {}
+        end
+
+      end
+
+    end
+  end
+end