google-cloud-bigtable 0.1.0

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

@@ -0,0 +1,373 @@
+# 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.
+
+
+require "google/cloud/bigtable/app_profile/list"
+require "google/cloud/bigtable/app_profile/job"
+
+module Google
+  module Cloud
+    module Bigtable
+      # # AppProfile
+      #
+      # A configuration object describing how Cloud Bigtable should treat traffic
+      # from a particular end user application.
+      #
+      # @example
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #
+      #   instance = bigtable.instance("my-instance")
+      #
+      #   app_profile = bigtable.app_profile("my-instance", "my-app-profile")
+      #
+      #   # Update
+      #   app_profile.description = "User data instance app profile"
+      #   app_profile.routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
+      #   job = app_profile.save
+      #   job.wait_until_done!
+      #
+      #   # Delete
+      #   app_profile.delete
+      #
+      class AppProfile
+        # @private
+        # The gRPC Service object.
+        attr_accessor :service
+
+        # @private
+        #
+        # Creates a new AppProfile instance.
+        def initialize grpc, service
+          @grpc = grpc
+          @service = service
+          @changed_fields = {}
+        end
+
+        # The unique identifier for the project.
+        #
+        # @return [String]
+        def project_id
+          @grpc.name.split("/")[1]
+        end
+
+        # The unique identifier for the instance.
+        #
+        # @return [String]
+        def instance_id
+          @grpc.name.split("/")[3]
+        end
+
+        # The unique identifier for the app profile.
+        #
+        # @return [String]
+        def name
+          @grpc.name.split("/")[5]
+        end
+
+        # The full path for the instance resource. Values are of the form
+        # `projects/<project_id>/instances/<instance_id>`.
+        #
+        # @return [String]
+        def path
+          @grpc.name
+        end
+
+        # Etag for optimistic concurrency control.
+        #
+        # @return [String]
+        def etag
+          @grpc.etag
+        end
+
+        # Description of the AppProfile.
+        #
+        # @return [String]
+        def description
+          @grpc.description
+        end
+
+        # Set description of the AppProfile.
+        #
+        # @param text [String] Description text
+        def description= text
+          @grpc.description = text
+          @changed_fields["description"] = "description"
+        end
+
+        # Get value of multi-cluster routing policy.
+        #
+        # @return [Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
+        def multi_cluster_routing
+          @grpc.multi_cluster_routing_use_any
+        end
+
+        # Get value of single cluster routing policy
+        #
+        # @return [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting]
+        def single_cluster_routing
+          @grpc.single_cluster_routing
+        end
+
+        # Set routing policy
+        #
+        # @param policy [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting | Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
+        #   The routing policy for all read/write requests which use this app profile.
+        #   A value must be explicitly set.
+        #
+        #   Routing Policies:
+        #   * `multi_cluster_routing` - Read/write requests may be routed to any
+        #     cluster in the instance, and will fail over to another cluster in the event
+        #     of transient errors or delays. Choosing this option sacrifices
+        #     read-your-writes consistency to improve availability.
+        #   * `single_cluster_routing` - Unconditionally routes all read/write requests
+        #     to a specific cluster. This option preserves read-your-writes consistency,
+        #     but does not improve availability.
+        #     Value contain `cluster_id` and optional field `allow_transactional_writes`.
+        #
+        # @example Set multi cluster routing policy
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   app_profile = instance.app_profile("my-app-profile")
+        #
+        #   routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
+        #   app_profile.routing_policy = routing_policy
+        #
+        # @example Set single cluster routing policy
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   app_profile = instance.app_profile("my-app-profile")
+        #
+        #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
+        #     "my-instance-cluster-1"
+        #     allow_transactional_writes: true
+        #   )
+        #   app_profile.routing_policy = routing_policy
+        #
+        def routing_policy= policy
+          if policy.is_a?(Google::Bigtable::Admin::V2::AppProfile:: \
+              SingleClusterRouting)
+            @grpc.single_cluster_routing = policy
+            @changed_fields["routing_policy"] = "single_cluster_routing"
+          else
+            @grpc.multi_cluster_routing_use_any = policy
+            @changed_fields["routing_policy"] = "multi_cluster_routing_use_any"
+          end
+        end
+
+        # Get routing policy
+        #
+        # @return [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting, Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
+        #
+        def routing_policy
+          @grpc.single_cluster_routing || @grpc.multi_cluster_routing_use_any
+        end
+
+        # Delete app profile.
+        #
+        # @param ignore_warnings [Boolean]
+        #   Default value is false. If true, ignore safety checks when deleting
+        #   the app profile.
+        # @return [Boolean] Returns `true` if the app profile was deleted.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #   app_profile = bigtable.instance("my-app-profile")
+        #
+        #   app_profile.delete(ignore_warnings: true) # Ignore warnings.
+        #
+        #   # OR : Not ignoring warnings
+        #   app_profile.delete
+        #
+        def delete ignore_warnings: false
+          ensure_service!
+          service.delete_app_profile(
+            instance_id,
+            name,
+            ignore_warnings: ignore_warnings
+          )
+          true
+        end
+
+        # Update app profile.
+        #
+        # @param ignore_warnings [Boolean]
+        #   Default value is false. If true, ignore safety checks when updating
+        #   the app profile.
+        # @return [Google::Cloud::Bigtable::AppProfile::Job]
+        #
+        # @example Update
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   app_profile = bigtable.app_profile("my-app-profile")
+        #
+        #   app_profile.description = "User data instance app profile"
+        #   app_profile.routing_policy = \
+        #     Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
+        #
+        #   job = app_profile.save
+        #   job.wait_until_done!
+        #   if job.error?
+        #     puts job.error
+        #   else
+        #     puts "App profile successfully update."
+        #     app_profile = job.app_profile
+        #   end
+        #
+        #   # OR - Update with ignoring warnings.
+        #   job = app_profile.save(ignore_warnings: true)
+        #   job.wait_until_done!
+        #
+        # @example Update with single cluster routing
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #   app_profile = bigtable.instance("my-app-profile")
+        #
+        #   app_profile.description = "User data instance app profile"
+        #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
+        #     "my-cluster",
+        #     allow_transactional_writes: true
+        #   )
+        #   app_profile.routing_policy = routing_policy
+        #
+        #   job = app_profile.save
+        #
+        #   job.done? #=> false
+        #   job.reload!
+        #   job.done? #=> false
+        #
+        #   # Reload job until completion.
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     puts job.error
+        #   else
+        #     app_profile = job.app_profile
+        #     puts app_profile.name
+        #   end
+
+        def save ignore_warnings: false
+          ensure_service!
+          update_mask = Google::Protobuf::FieldMask.new(
+            paths: @changed_fields.values
+          )
+          grpc = service.update_app_profile(
+            @grpc,
+            update_mask,
+            ignore_warnings: ignore_warnings
+          )
+          @changed_fields.clear
+          AppProfile::Job.from_grpc(grpc, service)
+        end
+        alias update save
+
+        # Reload app profile information.
+        #
+        # @return [Google::Cloud::Bigtable::AppProfile]
+
+        def reload!
+          @grpc = service.get_app_profile(instance_id, name)
+          self
+        end
+
+        # Create instance of multi cluster routing policy.
+        #
+        # Read/write requests may be routed to any cluster in the instance, and will
+        # Fail over to another cluster in the event of transient errors or delays.
+        # Choosing this option sacrifices read-your-writes consistency to improve
+        # availability
+        # @return [Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
+        #
+        # @example Create instance of multi cluster routing
+        #
+        #   Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
+        #
+        def self.multi_cluster_routing
+          Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny.new
+        end
+
+        # Create instance of single cluster routing
+        #
+        # Unconditionally routes all read/write requests to a specific cluster.
+        # This option preserves read-your-writes consistency, but does not improve
+        # availability.
+        #
+        # @param cluster_id [String]
+        #   The cluster to which read/write requests should be routed.
+        # @param allow_transactional_writes [Boolean]
+        #   Whether or not `CheckAndMutateRow` and `ReadModifyWriteRow` requests are
+        #   allowed by this app profile. It is unsafe to send these requests to
+        #   the same table/row/column in multiple clusters.
+        #    Default value is false.
+        # @return [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting]
+        #
+        # @example Create instance of single cluster routing
+        #
+        #   Google::Cloud::Bigtable::AppProfile.single_cluster_routing("my-cluster")
+        #
+        #   # With allowed transactional writes
+        #   Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
+        #     "my-cluster",
+        #     allow_transactional_writes: true
+        #   )
+
+        def self.single_cluster_routing \
+            cluster_id,
+            allow_transactional_writes: false
+          Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting.new(
+            cluster_id: cluster_id,
+            allow_transactional_writes: allow_transactional_writes
+          )
+        end
+
+        # @private
+        #
+        # Creates a new Instance instance from a
+        # Google::Bigtable::Admin::V2::Table.
+        # @param grpc [Google::Bigtable::Admin::V2::Table]
+        # @param service [Google::Cloud::Bigtable::Service]
+        # @return [Google::Cloud::Bigtable::Table]
+        def self.from_grpc grpc, service
+          new(grpc, service)
+        end
+
+        protected
+
+        # @private
+        # Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          raise "Must have active connection to service" unless service
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,253 @@
+# 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
+      # # RowsMutator
+      #
+      # Read chunk and merge 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
+
+          if chunk.commit_row
+            raise_if(
+              chunk.value_size > 0,
+              "A row cant not have value_size and commit_row"
+            )
+          end
+
+          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 > 0)
+
+          raise_if value, "A reset should have no data"
+        end
+
+        # Validate chunk has new row state
+        #
+        # @raise [Google::Cloud::Bigtable::InvalidRowStateError]
+        #   If row has already set key, chunk has emoty row key, chunk state is
+        #   reset, new row key same as last read key, family name or column
+        #   qualifier is 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 valus 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_hash) if condition
+        end
+      end
+    end
+  end
+end