google-cloud-bigtable 0.1.0

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

@@ -0,0 +1,92 @@
+# 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 Cluster
+        # # Job
+        #
+        # A resource representing the long-running, asynchronous processing of
+        # an cluster create or update operation. The job can be refreshed to
+        # retrieve the cluster object once the operation has been completed.
+        #
+        # See {Instance#create_cluster} and {Cluster#save}.
+        #
+        # @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")
+        #   job = instance.create_cluster(
+        #     "my-new-cluster",
+        #     "us-east-1b",
+        #     nodes: 3,
+        #     storage_type: :SSD
+        #   )
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   # OR wail until  complete
+        #   job.wait_until_done!
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     cluster = job.cluster
+        #   end
+        #
+        class Job < LongrunningJob
+          # Get the cluster object from job results
+          #
+          # @return [Google::Cloud::Bigtable::Cluster, nil] The cluster instance, or
+          #   `nil` if the operation is not complete.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   job = instance.create_cluster(
+          #     "my-new-cluster",
+          #     "us-east-1b",
+          #     nodes: 3,
+          #     storage_type: :SSD
+          #   )
+          #
+          #   job.done? #=> false
+          #   job.reload!
+          #   job.done? #=> true
+          #
+          #   # OR wait utill complete
+          #
+          #   job.wait_until_done!
+          #   cluster = job.cluster
+          #
+          def cluster
+            Cluster.from_grpc(results, service) if results
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+# 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 Cluster
+        # Cluster::List is a special case Array with additional
+        # values.
+        class List < DelegateClass(::Array)
+          # @private
+          # The gRPC Service object.
+          attr_accessor :service
+
+          # @private
+          # Instance id
+          attr_accessor :instance_id
+
+          # If not empty, indicates that there are more records that match
+          # the request and this value should be passed to continue.
+          attr_accessor :token
+
+          # Locations from which Cluster information could not be retrieved,
+          # due to an outage or some other transient condition.
+          # Clusters from these locations may be missing from `clusters`,
+          # or may only have partial information returned.
+          attr_accessor :failed_locations
+
+          # @private
+          # Create a new Cluster::List with an array of
+          # Cluster 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
+          #
+          #   clusters = bigtable.clusters("instance-id")
+          #   if clusters.next?
+          #     next_clusters = clusters.next
+          #   end
+          def next?
+            !token.nil?
+          end
+
+          # Retrieve the next page of clusters.
+          #
+          # @return [Cluster::List] The list of clusters.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   clusters = bigtable.clusters("instance-id")
+          #   if instances.next?
+          #     next_clusters = clusters.next
+          #   end
+          def next
+            return nil unless next?
+            ensure_service!
+            grpc = service.list_clusters(instance_id, token: token)
+            next_list = self.class.from_grpc(
+              grpc,
+              service,
+              instance_id: instance_id
+            )
+            if failed_locations
+              next_list.failed_locations.concat(failed_locations.map(&:to_s))
+            end
+            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 [cluster] The block for accessing each cluster.
+          # @yieldparam [Cluster] cluster The cluster object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each cluster by passing a block:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   bigtable.clusters("instance-id").all do |cluster|
+          #     puts cluster.cluster_id
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   all_cluster_ids = bigtable.clusters("instance-id").all.map do |cluster|
+          #     puts cluster.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 Cluster::List from a Google::Bigtable::Admin::V2::ListClustersResponse object.
+          def self.from_grpc grpc, service, instance_id: nil
+            clusters = List.new(Array(grpc.clusters).map do |cluster|
+              Cluster.from_grpc(cluster, service)
+            end)
+            token = grpc.next_page_token
+            token = nil if token == "".freeze
+            clusters.token = token
+            clusters.instance_id = instance_id
+            clusters.service = service
+            clusters.failed_locations = grpc.failed_locations.map(&:to_s)
+            clusters
+          end
+
+          protected
+
+          # @private
+          #
+          # Raise 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/cluster.rb

@@ -0,0 +1,264 @@
+# 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/cluster/list"
+require "google/cloud/bigtable/cluster/job"
+
+module Google
+  module Cloud
+    module Bigtable
+      # # Cluster
+      #
+      # 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")
+      #   cluster = instance.cluster("my-cluster")
+      #
+      #   # Update
+      #   cluster.nodes = 3
+      #   cluster.save
+      #
+      #   # Delete
+      #   cluster.delete
+      #
+      class Cluster
+        # @private
+        # The gRPC Service object.
+        attr_accessor :service
+
+        # @private
+        #
+        # Creates a new Cluster instance.
+        def initialize grpc, service
+          @grpc = grpc
+          @service = service
+        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 cluster.
+        #
+        # @return [String]
+        def cluster_id
+          @grpc.name.split("/")[5]
+        end
+
+        # The unique name of the cluster. Value in the form
+        # `projects/<project_id>/instances/<instance_id>/clusters/<cluster_id>`.
+        #
+        # @return [String]
+        def path
+          @grpc.name
+        end
+
+        # The current instance state.
+        # Possible values are
+        # `:CREATING`, `:READY`, `:STATE_NOT_KNOWN`, `:RESIZING`, `:DISABLED`.
+        #
+        # @return [Symbol]
+        def state
+          @grpc.state
+        end
+
+        # The cluster has been successfully created and is ready to serve requests.
+        #
+        # @return [Boolean]
+        def ready?
+          state == :READY
+        end
+
+        # The instance is currently being created, and may be destroyed if the
+        # creation process encounters an error.
+        #
+        # @return [Boolean]
+        def creating?
+          state == :CREATING
+        end
+
+        # The cluster is currently being resized, and may revert to its previous
+        # node count if the process encounters an error.
+        # A cluster is still capable of serving requests while being resized,
+        # but may exhibit performance as if its number of allocated nodes is
+        # between the starting and requested states.
+        #
+        # @return [Boolean]
+        def resizing?
+          state == :RESIZING
+        end
+
+        # The cluster has no backing nodes. The data (tables) still
+        # exist, but no operations can be performed on the cluster.
+        #
+        # @return [Boolean]
+        def disabled?
+          state == :DISABLED
+        end
+
+        # The number of nodes allocated to this cluster.
+        #
+        # @return [Integer]
+        def nodes
+          @grpc.serve_nodes
+        end
+
+        # The number of nodes allocated to this cluster. More nodes enable higher
+        # throughput and more consistent performance.
+        #
+        # @param serve_nodes [Integer] Number of nodes
+        def nodes= serve_nodes
+          @grpc.serve_nodes = serve_nodes
+        end
+
+        # The type of storage used by this cluster to serve its
+        # parent instance's tables, unless explicitly overridden.
+        # Valid values are `:SSD`(Flash (SSD) storage should be used),
+        # `:HDD`(Magnetic drive (HDD) storage should be used)
+        #
+        # @return [Symbol]
+        def storage_type
+          @grpc.default_storage_type
+        end
+
+        # Cluster location.
+        # i.e "us-east-1b"
+        #
+        # @return [String]
+        def location
+          @grpc.location.split("/")[3]
+        end
+
+        # Cluster location path in form of
+        # `projects/<project_id>/locations/<zone>`
+        #
+        # @return [String]
+        def location_path
+          @grpc.location
+        end
+
+        # Update cluster.
+        #
+        # Updatable fields are no of nodes.
+        #
+        # @return [Google::Cloud::Bigtable::Cluster::Job]
+        #   The job representing the long-running, asynchronous processing of
+        #   an update cluster operation.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #   cluster.nodes = 3
+        #   job = cluster.save
+        #
+        #   job.done? #=> false
+        #
+        #   # To block until the operation completes.
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     cluster = job.cluster
+        #   end
+        #
+        def save
+          ensure_service!
+          grpc = service.update_cluster(
+            instance_id,
+            cluster_id,
+            location_path,
+            nodes
+          )
+          Cluster::Job.from_grpc(grpc, service)
+        end
+        alias update save
+
+        # Reload cluster information.
+        #
+        # @return [Google::Cloud::Bigtable::Cluster]
+
+        def reload!
+          @grpc = service.get_cluster(instance_id, cluster_id)
+          self
+        end
+
+        # Permanently deletes the cluster
+        #
+        # @return [Boolean] Returns `true` if the cluster was deleted.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #   cluster.delete
+        #
+        def delete
+          ensure_service!
+          service.delete_cluster(instance_id, cluster_id)
+          true
+        end
+
+        # @private
+        #
+        # Creates a new Cluster instance from a
+        # Google::Bigtable::Admin::V2::Cluster.
+        #
+        # @param grpc [Google::Bigtable::Admin::V2::Cluster]
+        # @param service [Google::Cloud::Bigtable::Service]
+        # @return [Google::Cloud::Bigtable::Cluster]
+        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