google-cloud-bigtable 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/chunk_processor.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+# Copyright 2018 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
+      # @private
+      # # ChunkProcessor
+      #
+      # Read a chunk of data and merge it based on states and build rows and cells
+      #
+      class ChunkProcessor
+        # Row states
+        NEW_ROW = 1
+        ROW_IN_PROGRESS = 2
+        CELL_IN_PROGRESS = 3
+
+        # Current state
+        attr_accessor :state, :last_key
+
+        # Current cached row data
+        attr_accessor :chunk, :row
+
+        # Current cell values
+        attr_accessor :cur_family, :cur_qaul, :cur_ts, :cur_val, :cur_labels
+
+        # @private
+        #
+        # Create chunk reader object and set row state to new
+        #
+        def initialize
+          reset_to_new_row
+        end
+
+        ##
+        # Process chunk and build full row with cells
+        #
+        # @param chunk [Google::Bigtable::V2::ReadRowsResponse::CellChunk]
+        #
+        def process chunk
+          self.chunk = chunk
+
+
+          raise_if chunk.value_size.positive?, "Commit rows cannot have a non-zero value_size." if chunk.commit_row
+
+          if state == NEW_ROW
+            process_new_row
+          elsif state == CELL_IN_PROGRESS
+            process_cell_in_progress
+          elsif state == ROW_IN_PROGRESS
+            process_row_in_progress
+          end
+        end
+
+        ##
+        # Validate row status commit or reset
+        #
+        # @raise [Google::Cloud::Bigtable::InvalidRowStateError]
+        #   if chunk has data on reset row state
+        #
+        def validate_reset_row
+          return unless chunk.reset_row
+
+          value = (!chunk.row_key.empty? ||
+              chunk.family_name ||
+              chunk.qualifier ||
+              !chunk.value.empty? ||
+              chunk.timestamp_micros.positive?)
+
+          raise_if value, "A reset should have no data"
+        end
+
+        ##
+        # Validate chunk has new row state
+        #
+        # @raise [Google::Cloud::Bigtable::InvalidRowStateError]
+        #   If row already has a set key, chunk has an empty row key, chunk
+        #   state is reset, new row key is the same as the last-read key,
+        #   or if family name or column qualifier are empty
+        #
+        def validate_new_row
+          raise_if row.key, "A new row cannot have existing state"
+          raise_if chunk.row_key.empty?, "A row key must be set"
+          raise_if chunk.reset_row, "A new row cannot be reset"
+          raise_if last_key == chunk.row_key, "A commit happened but the same key followed"
+          raise_if chunk.family_name.nil?, "A family must be set"
+          raise_if chunk.qualifier.nil?, "A column qualifier must be set"
+        end
+
+        ##
+        # Validate chunk merge is in progress to build new row
+        #
+        # @raise [Google::Cloud::Bigtable::InvalidRowStateError]
+        #   If row and chunk row key are not same or chunk row key is empty.
+        #
+        def validate_row_in_progress
+          raise_if !chunk.row_key.empty? && chunk.row_key != row.key, "A commit is required between row keys"
+
+          raise_if chunk.family_name && chunk.qualifier.nil?, "A qualifier must be specified"
+
+          validate_reset_row
+        end
+
+        ##
+        # Process new row by setting values from current chunk.
+        #
+        # @return [Google::Cloud::Bigtable::Row]
+        #
+        def process_new_row
+          validate_new_row
+
+          return if chunk.family_name.nil? || chunk.qualifier.nil?
+
+          row.key = chunk.row_key
+          self.cur_family = chunk.family_name.value
+          self.cur_qaul = chunk.qualifier.value
+          self.cur_ts = chunk.timestamp_micros
+          self.cur_labels = chunk.labels
+
+          next_state!
+        end
+
+        ##
+        # Process chunk if row state is in progress
+        #
+        # @return [Google::Cloud::Bigtable::Row]
+        #
+        def process_row_in_progress
+          validate_row_in_progress
+
+          return reset_to_new_row if chunk.reset_row
+
+          self.cur_family = chunk.family_name.value if chunk.family_name
+          self.cur_qaul = chunk.qualifier.value if chunk.qualifier
+          self.cur_ts = chunk.timestamp_micros
+          self.cur_labels = chunk.labels if chunk.labels
+          next_state!
+        end
+
+        ##
+        # Process chunk if row cell state is in progress
+        #
+        # @return [Google::Cloud::Bigtable::Row]
+        #
+        def process_cell_in_progress
+          validate_reset_row
+
+          return reset_to_new_row if chunk.reset_row
+
+          next_state!
+        end
+
+        ##
+        # Set next state of row.
+        #
+        # @return [Google::Cloud::Bigtable::Row]
+        #
+        def next_state!
+          if cur_val
+            self.cur_val += chunk.value
+          else
+            self.cur_val = chunk.value
+          end
+
+          if chunk.value_size.zero?
+            persist_cell
+            self.state = ROW_IN_PROGRESS
+          else
+            self.state = CELL_IN_PROGRESS
+          end
+
+          return unless chunk.commit_row
+
+          self.last_key = row.key
+          completed_row = row
+          reset_to_new_row
+          completed_row
+        end
+
+        # Build cell and append to row.
+        def persist_cell
+          cell = Row::Cell.new cur_family, cur_qaul, cur_ts, cur_val, cur_labels
+          row.cells[cur_family] << cell
+
+          # Clear cached cell values
+          self.cur_val = nil
+          self.cur_ts = nil
+          self.cur_labels = nil
+        end
+
+        # Reset read state and cached data
+        def reset_to_new_row
+          self.row = Row.new
+          self.state = NEW_ROW
+          self.cur_family = nil
+          self.cur_qaul = nil
+          self.cur_ts = nil
+          self.cur_val = nil
+          self.cur_labels = nil
+        end
+
+        ##
+        # Validate last row is completed
+        #
+        # @raise [Google::Cloud::Bigtable::InvalidRowStateError]
+        #   If read rows response end without last row completed
+        #
+        def validate_last_row_complete
+          return if row.key.nil?
+
+          raise_if !chunk.commit_row, "Response ended with pending row without commit"
+        end
+
+        private
+
+        ##
+        # Raise error on condition failure
+        #
+        # @raise [Google::Cloud::Bigtable::InvalidRowStateError]
+        #
+        def raise_if condition, message
+          raise InvalidRowStateError.new(message, chunk.to_h) if condition
+        end
+      end
+    end
+  end
+end