google-cloud-bigtable 1.3.0

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

@@ -0,0 +1,74 @@
+# 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
+      class Instance
+        ##
+        # Instance::ClusterMap is a hash with cluster ID keys and cluster configuration values.
+        # It is used to create a cluster.
+        #
+        # @example
+        #
+        #  clusters = Google::Cloud::Bigtable::Instance::ClusterMap.new
+        #
+        #  clusters.add("cluster-1", "us-east1-b", nodes: 3, storage_type: :SSD)
+        #
+        #  # Or
+        #  clusters.add("cluster-2", "us-east1-b")
+        #
+        class ClusterMap < DelegateClass(::Hash)
+          # @private
+          #
+          # Creates a new Instance::ClusterMap with an hash of Cluster name and
+          # cluster grpc instances.
+          def initialize value = {}
+            super value
+          end
+
+          ##
+          # Adds a cluster to the cluster map.
+          #
+          # @param name [String] The unique identifier for the cluster.
+          # @param location [String]
+          #   The location where this cluster's nodes and storage reside. For best
+          #   performance, clients should be located as close as possible to this
+          #   cluster. Currently only zones are supported.
+          # @param nodes [Integer] Number of nodes for the cluster. When creating
+          #   an instance of type `:DEVELOPMENT`, `nodes` must not be set.
+          # @param storage_type [Symbol]
+          #   Valid values are:
+          #   * `:SSD`(Flash (SSD) storage should be used),
+          #   *`:HDD`(Magnetic drive (HDD) storage should be used)
+          #
+          #   If not set then default will set to `:STORAGE_TYPE_UNSPECIFIED`
+          #
+          def add name, location, nodes: nil, storage_type: nil
+            attrs = {
+              serve_nodes:          nodes,
+              location:             location,
+              default_storage_type: storage_type
+            }.delete_if { |_, v| v.nil? }
+
+            self[name] = Google::Bigtable::Admin::V2::Cluster.new attrs
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# 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
+      class Instance
+        ##
+        # # Job
+        #
+        # A resource representing the long-running, asynchronous processing of
+        # an instance create or update operation. The job can be refreshed to
+        # retrieve the instance object once the operation has been completed.
+        #
+        # See {Project#create_instance} and {Instance#update}.
+        #
+        # @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
+        #
+        #   job = bigtable.create_instance(
+        #     "my-instance",
+        #     display_name: "Instance for user data",
+        #     type: :DEVELOPMENT,
+        #     labels: { "env" => "dev"}
+        #   ) do |clusters|
+        #     clusters.add("test-cluster", "us-east1-b") # nodes not allowed
+        #   end
+        #
+        #   # Check and reload.
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   # OR - Wailt until complete
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     instance = job.instance
+        #   end
+        #
+        class Job < LongrunningJob
+          ##
+          # Get the instance object from operation results.
+          #
+          # @return [Google::Cloud::Bigtable::Instance, nil] The Instance instance, or
+          #   `nil` if the operation is not complete.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   job = bigtable.create_instance(
+          #     "my-instance",
+          #     display_name: "Instance for user data",
+          #     type: :DEVELOPMENT,
+          #     labels: { "env" => "dev"}
+          #   ) do |clusters|
+          #     clusters.add("test-cluster", "us-east1-b") # nodes not allowed
+          #   end
+          #
+          #   job.done? #=> false
+          #   job.reload!
+          #   job.done? #=> true
+          #
+          #   # OR
+          #   job.wait_until_done!
+          #
+          #   instance = job.instance
+          #
+          def instance
+            Instance.from_grpc results, service if results
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,164 @@
+# 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 "delegate"
+
+module Google
+  module Cloud
+    module Bigtable
+      class Instance
+        ##
+        # Instance::List is a special-case array with additional
+        # values and failed_locations.
+        class List < DelegateClass(::Array)
+          # @private
+          # The gRPC Service object.
+          attr_accessor :service
+
+          ##
+          # If not empty, indicates that more records match
+          # the request and this value should be passed to continue.
+          attr_accessor :token
+
+          ##
+          # Locations from which instance information could not be retrieved,
+          # due to an outage or some other transient condition.
+          # Instances whose clusters are all in one of the failed locations
+          # may be missing from `instances`, and instances with at least one
+          # cluster in a failed location may only have partial information returned.
+          attr_accessor :failed_locations
+
+          # @private
+          # Creates a new Instance::List with an array of
+          # Instance instances.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of instances.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instances = bigtable.instances
+          #   if instances.next?
+          #     next_instances = instances.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieves the next page of instances.
+          #
+          # @return [Instance::List] The list of instances.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instances = bigtable.instances
+          #   if instances.next?
+          #     next_instances = instances.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            grpc = service.list_instances token: token
+            next_list = self.class.from_grpc grpc, service
+            next_list.failed_locations.concat(failed_locations.map(&:to_s)) if failed_locations
+            next_list
+          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 [instance] The block for accessing each instance.
+          # @yieldparam [Instance] instance The instance object.
+          #
+          # @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"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   bigtable.instances.all do |instance|
+          #     puts instance.instance_id
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   all_instance_ids = bigtable.instances.all.map do |instance|
+          #     puts instance.instance_id
+          #   end
+          #
+          def all
+            return enum_for :all unless block_given?
+
+            results = self
+            loop do
+              results.each { |r| yield r }
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          # @private
+          # New Instance::List from a Google::Bigtable::Admin::V2::Instance object.
+          def self.from_grpc grpc, service
+            instances = List.new(Array(grpc.instances).map do |instance|
+              Instance.from_grpc instance, service
+            end)
+            token = grpc.next_page_token
+            token = nil if token == ""
+            instances.token = token
+            instances.service = service
+            instances.failed_locations = grpc.failed_locations.map(&:to_s)
+            instances
+          end
+
+          protected
+
+          # Raises an error unless an active service is available.
+          def ensure_service!
+            raise "Must have active connection" unless service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# 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
+      ##
+      # # LongrunningJob
+      #
+      # A resource representing the long-running, asynchronous processing operation.
+      # The job can be refreshed to retrieve the result object once the operation has been completed.
+      #
+      # @see https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.longrunning#google.longrunning.Operation
+      #   Long-running Operation
+      #
+      class LongrunningJob
+        # @private
+        # The Google::Gax::Operation gRPC object.
+        attr_accessor :grpc
+
+        # @private
+        # The gRPC Service object.
+        attr_accessor :service
+
+        ##
+        # Gets the result object of the operation.
+        #
+        # @return [Object, nil]
+        #   `nil` if the operation is not complete.
+        #
+        def results
+          return nil unless done?
+          return nil unless @grpc.grpc_op.result == :response
+          @grpc.results
+        end
+
+        ##
+        # Checks if the processing of the instance operation is complete.
+        #
+        # @return [boolean] `true` when complete, `false` otherwise.
+        #
+        def done?
+          @grpc.done?
+        end
+
+        ##
+        # Checks if the processing of the instance operation has errored.
+        #
+        # @return [boolean] `true` when errored, `false` otherwise.
+        #
+        def error?
+          @grpc.error?
+        end
+
+        ##
+        # The status when the operation associated with this job produced an
+        # error.
+        #
+        # @return [Object, Google::Rpc::Status, nil] A status object with
+        #   the status code and message, or `nil` if no error occurred.
+        #
+        def error
+          return nil unless error?
+          @grpc.error
+        end
+
+        ##
+        # Reloads the job with current data from the long-running,
+        # asynchronous processing of an operation.
+        #
+        # @return [Google::Cloud::Bigtable::Instance::Job] The same job instance.
+        #
+        def reload!
+          @grpc.reload!
+          self
+        end
+
+        ##
+        # Reloads the job until the operation is complete. The delay between
+        # reloads will incrementally increase.
+        #
+        def wait_until_done!
+          @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
+          new.tap do |job|
+            job.grpc =  grpc
+            job.service = service
+          end
+        end
+      end
+    end
+  end
+end