google-cloud-bigtable 1.0.2 → 1.3.0

data/lib/google/cloud/bigtable/backup/job.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Bigtable
+      class Backup
+        ##
+        # # Job
+        #
+        # A resource representing the long-running, asynchronous processing of an backup create operation. The job can
+        # be refreshed to retrieve the backup object once the operation has been completed.
+        #
+        # See {Cluster#create_backup}.
+        #
+        # @see https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.longrunning#google.longrunning.Operation
+        #   Long-running Operation
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #   table = instance.table("my-table")
+        #
+        #   expire_time = Time.now + 60 * 60 * 7
+        #   job = cluster.create_backup(table, "my-backup", expire_time)
+        #
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     backup = job.backup
+        #   end
+        #
+        class Job < LongrunningJob
+          ##
+          # Get the backup object from operation results.
+          #
+          # @return [Google::Cloud::Bigtable::Backup, nil] The backup instance, or `nil` if the operation is not
+          #   complete.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #   table = instance.table("my-table")
+          #
+          #   expire_time = Time.now + 60 * 60 * 7
+          #   job = cluster.create_backup(table, "my-backup", expire_time)
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          #   if job.error?
+          #     status = job.error
+          #   else
+          #     backup = job.backup
+          #   end
+          #
+          def backup
+            Backup.from_grpc results, service if results
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/bigtable/backup/list.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Bigtable
+      class Backup
+        ##
+        # Backup::List is a special-case array with additional values.
+        class List < DelegateClass(::Array)
+          # @private
+          # The gRPC Service object.
+          attr_accessor :service
+
+          # @private
+          # The gRPC page enumerable object.
+          attr_accessor :grpc
+
+          # @private
+          # Creates a new Backup::List with an array of backups.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of backups.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   backups = cluster.backups
+          #
+          #   if backups.next?
+          #     next_backups = backups.next
+          #   end
+          #
+          def next?
+            grpc.next_page?
+          end
+
+          ##
+          # Retrieves the next page of backups.
+          #
+          # @return [Backup::List] The list of backups.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   backups = cluster.backups
+          #
+          #   if backups.next?
+          #     next_backups = backups.next
+          #   end
+          #
+          def next
+            ensure_grpc!
+
+            return nil unless next?
+            grpc.next_page
+            self.class.from_grpc grpc, service
+          end
+
+          ##
+          # Retrieves remaining results by repeatedly invoking {#next} until {#next?} returns `false`. Calls the given
+          # block once for each result, which is passed as the argument to the block.
+          #
+          # An enumerator is returned if no block is given.
+          #
+          # This method will make repeated API calls until all remaining results are retrieved (unlike `#each`, for
+          # example, which merely iterates over the results returned by a single API call). Use with caution.
+          #
+          # @yield [backup] The block for accessing each backup.
+          # @yieldparam [Backup] backup The backup object.
+          #
+          # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
+          #
+          # @example Iterating each backup by passing a block:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   cluster.backups.all do |backup|
+          #     puts backup.backup_id
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   all_backup_ids = cluster.backups.all.map do |backup|
+          #     backup.backup_id
+          #   end
+          #
+          def all
+            return enum_for :all unless block_given?
+
+            results = self
+            loop do
+              results.each { |r| yield r }
+              break unless next?
+              grpc.next_page
+              results = self.class.from_grpc grpc, service
+            end
+          end
+
+          # @private
+          # New Snapshot::List from a Google::Gax::PagedEnumerable<Google::Bigtable::Admin::V2::Backup> object.
+          # @param grpc [Google::Gax::PagedEnumerable<Google::Bigtable::Admin::V2::Backup> ]
+          # @param service [Google::Cloud::Bigtable::Service]
+          # @return [Array<Google::Cloud::Bigtable::Backup>]
+          def self.from_grpc grpc, service
+            backups = List.new(
+              Array(grpc.response.backups).map do |backup|
+                Backup.from_grpc backup, service
+              end
+            )
+            backups.grpc = grpc
+            backups.service = service
+            backups
+          end
+
+          protected
+
+          # @private
+          #
+          # Raises an error if an active gRPC call is not available.
+          def ensure_grpc!
+            raise "Must have active gRPC call" unless grpc
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/bigtable/cluster.rb

@@ -15,6 +15,7 @@
 # limitations under the License.
 
 
+require "google/cloud/bigtable/backup"
 require "google/cloud/bigtable/cluster/list"
 require "google/cloud/bigtable/cluster/job"
 
@@ -196,6 +197,104 @@ module Google
           @grpc.location
         end
 
+        ##
+        # Creates a new Cloud Bigtable Backup.
+        #
+        # @param source_table [Table, String] The table object, or the name of the table,
+        #   from which the backup is to be created. The table needs to be in the same
+        #   instance as the backup. Required.
+        # @param backup_id [String] The id of the backup to be created. This string must
+        #   be between 1 and 50 characters in length and match the regex
+        #   `[_a-zA-Z0-9][-_.a-zA-Z0-9]*`. Required.
+        # @param expire_time [Time] The expiration time of the backup, with microseconds
+        #     granularity that must be at least 6 hours and at most 30 days
+        #     from the time the request is received. Once the `expire_time`
+        #     has passed, Cloud Bigtable will delete the backup and free the
+        #     resources used by the backup. Required.
+        # @return [Google::Cloud::Bigtable::Backup::Job]
+        #   The job representing the long-running, asynchronous processing of
+        #   a backup create operation.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #   table = instance.table("my-table")
+        #
+        #   expire_time = Time.now + 60 * 60 * 7
+        #   job = cluster.create_backup(table, "my-backup", expire_time)
+        #
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     backup = job.backup
+        #   end
+        #
+        def create_backup source_table, backup_id, expire_time
+          source_table_id = source_table.respond_to?(:name) ? source_table.name : source_table
+          grpc = service.create_backup instance_id:     instance_id,
+                                       cluster_id:      cluster_id,
+                                       backup_id:       backup_id,
+                                       source_table_id: source_table_id,
+                                       expire_time:     expire_time
+          Backup::Job.from_grpc grpc, service
+        end
+
+        ##
+        # Gets a backup in the cluster.
+        #
+        # @param backup_id [String] The unique ID of the requested backup.
+        #
+        # @return [Google::Cloud::Bigtable::Backup, nil] The backup object, or `nil` if not found in the service.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #
+        #   backup = cluster.backup("my-backup")
+        #
+        #   if backup
+        #     puts backup.backup_id
+        #   end
+        #
+        def backup backup_id
+          grpc = service.get_backup instance_id, cluster_id, backup_id
+          Backup.from_grpc grpc, service
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+
+        ##
+        # Lists all backups in the cluster.
+        #
+        # @return [Array<Google::Cloud::Bigtable::Backup>] (See {Google::Cloud::Bigtable::Backup::List})
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #
+        #   cluster.backups.all do |backup|
+        #     puts backup.backup_id
+        #   end
+        #
+        def backups
+          grpc = service.list_backups instance_id, cluster_id
+          Backup::List.from_grpc grpc, service
+        end
+
         ##
         # Updates the cluster.
         #

data/lib/google/cloud/bigtable/cluster/list.rb

@@ -109,7 +109,7 @@ module Google
           # @yield [cluster] The block for accessing each cluster.
           # @yieldparam [Cluster] cluster The cluster object.
           #
-          # @return [Enumerator]
+          # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
           #
           # @example Iterating each cluster by passing a block:
           #   require "google/cloud/bigtable"

data/lib/google/cloud/bigtable/column_family_map.rb

@@ -117,7 +117,7 @@ module Google
         # @yieldparam [String] name the column family name.
         # @yieldparam [ColumnFamily] column_family the column family object.
         #
-        # @return [Enumerator]
+        # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
         #
         def each
           return enum_for :each unless block_given?

data/lib/google/cloud/bigtable/instance.rb

@@ -854,7 +854,7 @@ module Google
         #   policy.add("roles/owner", "user:owner@example.com")
         #   updated_policy = instance.update_policy(policy)
         #
-        #   puts update_policy.roles
+        #   puts updated_policy.roles
         #
         def update_policy new_policy
           ensure_service!
@@ -884,7 +884,7 @@ module Google
         #   * bigtable.tables.get
         #   * bigtable.tables.list
         #
-        # @return [Array<Strings>] The permissions that have access.
+        # @return [Array<String>] The permissions that are configured for the policy.
         #
         # @example
         #   require "google/cloud/bigtable"
@@ -902,11 +902,8 @@ module Google
         #
         def test_iam_permissions *permissions
           ensure_service!
-          grpc = service.test_instance_permissions(
-            instance_id,
-            Array(permissions).flatten
-          )
-          grpc.permissions
+          grpc = service.test_instance_permissions instance_id, permissions.flatten
+          grpc.permissions.to_a
         end
 
         # @private

data/lib/google/cloud/bigtable/instance/list.rb

@@ -106,7 +106,7 @@ module Google
           # @yield [instance] The block for accessing each instance.
           # @yieldparam [Instance] instance The instance object.
           #
-          # @return [Enumerator]
+          # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
           #
           # @example Iterating each instance by passing a block:
           #   require "google/cloud/bigtable"

data/lib/google/cloud/bigtable/longrunning_job.rb

@@ -97,6 +97,17 @@ module Google
           @grpc.wait_until_done!
         end
 
+        ##
+        # @private Gets the metadata object of the operation.
+        #
+        # @return [Object, nil] `nil` if the operation is not complete.
+        #
+        def metadata
+          return nil unless done?
+          return nil unless @grpc.grpc_op.result == :response
+          @grpc.metadata
+        end
+
         # @private
         # New BasicJob from a Google::Gax::Operation object.
         def self.from_grpc grpc, service

data/lib/google/cloud/bigtable/policy.rb

@@ -19,7 +19,7 @@ module Google
       ##
       # # Policy
       #
-      # Represents a Cloud IAM Policy for Bigtable instance resources.
+      # Represents a Cloud IAM Policy for Bigtable resources.
       #
       # A common pattern for updating a resource's metadata, such as its policy,
       # is to read the current data from the service, update the data locally,