gcloud 0.11.0 → 0.12.0

data/lib/gcloud/logging/sink.rb

@@ -20,8 +20,8 @@ module Gcloud
     ##
     # # Sink
     #
-    # Used to export log entries outside Cloud Logging. When you create a sink,
-    # new log entries are exported. Cloud Logging does not send
+    # Used to export log entries outside Stackdriver Logging. When you create a
+    # sink, new log entries are exported. Stackdriver Logging does not send
     # previously-ingested log entries to the sink's destination.
     #
     # Before creating the sink, ensure that you have granted
@@ -48,7 +48,7 @@ module Gcloud
     #
     #   bucket = storage.create_bucket "my-logs-bucket"
     #
-    #   # Grant owner permission to Cloud Logging service
+    #   # Grant owner permission to Stackdriver Logging service
     #   email = "cloud-logs@google.com"
     #   bucket.acl.add_owner "group-#{email}"
     #
@@ -99,7 +99,7 @@ module Gcloud
       # that defines the log entries to be exported. The filter must be
       # consistent with the log entry format designed by the `version`
       # parameter, regardless of the format of the log entry that was originally
-      # written to Cloud Logging.
+      # written to Stackdriver Logging.
       def filter
         @grpc.filter
       end
@@ -110,7 +110,7 @@ module Gcloud
       # that defines the log entries to be exported. The filter must be
       # consistent with the log entry format designed by the `version`
       # parameter, regardless of the format of the log entry that was originally
-      # written to Cloud Logging.
+      # written to Stackdriver Logging.
       def filter= filter
         @grpc.filter = filter
       end
@@ -118,7 +118,7 @@ module Gcloud
       ##
       # The log entry version used when exporting log entries from this sink.
       # This version does not have to correspond to the version of the log entry
-      # when it was written to Cloud Logging.
+      # when it was written to Stackdriver Logging.
       def version
         @grpc.output_version_format
       end
@@ -126,7 +126,7 @@ module Gcloud
       ##
       # Updates the log entry version used when exporting log entries from this
       # sink. This version does not have to correspond to the version of the log
-      # entry when it was written to Cloud Logging. Accepted values are
+      # entry when it was written to Stackdriver Logging. Accepted values are
       # `:VERSION_FORMAT_UNSPECIFIED`, `:V2`, and `:V1`.
       def version= version
         @grpc.output_version_format = self.class.resolve_version(version)
@@ -166,8 +166,6 @@ module Gcloud
       def save
         ensure_service!
         @grpc = service.update_sink name, destination, filter, version
-      rescue GRPC::BadStatus => e
-        raise Gcloud::Error.from_error(e)
       end
 
       ##
@@ -176,8 +174,6 @@ module Gcloud
       def reload!
         ensure_service!
         @grpc = service.get_sink name
-      rescue GRPC::BadStatus => e
-        raise Gcloud::Error.from_error(e)
       end
       alias_method :refresh!, :reload!
 
@@ -197,9 +193,7 @@ module Gcloud
       def delete
         ensure_service!
         service.delete_sink name
-        return true
-      rescue GRPC::BadStatus => e
-        raise Gcloud::Error.from_error(e)
+        true
       end
 
       ##

data/lib/gcloud/logging/sink/list.rb

@@ -73,8 +73,6 @@ module Gcloud
           ensure_service!
           list_grpc = @service.list_sinks token: token, max: @max
           self.class.from_grpc list_grpc, @service
-        rescue GRPC::BadStatus => e
-          raise Gcloud::Error.from_error(e)
         end
 
         ##

data/lib/gcloud/pubsub.rb

@@ -36,6 +36,9 @@ module Gcloud
   #   The default scope is:
   #
   #   * `https://www.googleapis.com/auth/pubsub`
+  # @param [Integer] retries Number of times to retry requests on server error.
+  #   The default value is `3`. Optional.
+  # @param [Integer] timeout Default timeout to use in requests. Optional.
   #
   # @return [Gcloud::Pubsub::Project]
   #
@@ -47,7 +50,8 @@ module Gcloud
   #   topic = pubsub.topic "my-topic"
   #   topic.publish "task completed"
   #
-  def self.pubsub project = nil, keyfile = nil, scope: nil
+  def self.pubsub project = nil, keyfile = nil, scope: nil, retries: nil,
+                  timeout: nil
     project ||= Gcloud::Pubsub::Project.default_project
     if ENV["PUBSUB_EMULATOR_HOST"]
       ps = Gcloud::Pubsub::Project.new project, :this_channel_is_insecure
@@ -59,7 +63,9 @@ module Gcloud
     else
       credentials = Gcloud::Pubsub::Credentials.new keyfile, scope: scope
     end
-    Gcloud::Pubsub::Project.new project, credentials
+    Gcloud::Pubsub::Project.new(
+      Gcloud::Pubsub::Service.new(
+        project, credentials, retries: retries, timeout: timeout))
   end
 
   ##
@@ -72,7 +78,7 @@ module Gcloud
   # Cloud Pub/Sub allows developers to communicate between independently written
   # applications.
   #
-  # Gcloud's goal is to provide a API that is familiar and comfortable to
+  # The goal of gcloud-ruby is to provide a API that is comfortable to
   # Rubyists. Authentication is handled by {Gcloud#pubsub}. You can provide the
   # project and credential information to connect to the Pub/Sub service, or if
   # you are running on Google Compute Engine this configuration is taken care
@@ -389,24 +395,23 @@ module Gcloud
   # end
   # ```
   #
-  # ## Configuring Backoff
+  # ## Configuring retries and timeout
   #
-  # The {Gcloud::Backoff} class allows users to globally configure how Cloud API
-  # requests are automatically retried in the case of some errors, such as a
-  # `500` or `503` status code, or a specific internal error code such as
-  # `rateLimitExceeded`.
+  # You can configure how many times API requests may be automatically retried.
+  # When an API request fails, the response will be inspected to see if the
+  # request meets criteria indicating that it may succeed on retry, such as
+  # `500` and `503` status codes or a specific internal error code such as
+  # `rateLimitExceeded`. If it meets the criteria, the request will be retried
+  # after a delay. If another error occurs, the delay will be increased before a
+  # subsequent attempt, until the `retries` limit is reached.
   #
-  # If an API call fails, the response will be inspected to see if the call
-  # should be retried. If the response matches the criteria, then the request
-  # will be retried after a delay. If another error occurs, the delay will be
-  # increased incrementally before a subsequent attempt. The first retry will be
-  # delayed one second, the second retry two seconds, and so on.
+  # You can also set the request `timeout` value in seconds.
   #
   # ```ruby
   # require "gcloud"
-  # require "gcloud/backoff"
   #
-  # Gcloud::Backoff.retries = 5 # Raise the maximum number of retries from 3
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub retries: 10, timeout: 120
   # ```
   #
   # See the [Pub/Sub error codes](https://cloud.google.com/pubsub/error-codes)
@@ -452,7 +457,7 @@ module Gcloud
   # sub.topic.name #=> "projects/other-project-id/topics/other-topic"
   # ```
   #
-  # ## Using the Gcloud SDK Emulator
+  # ## Using the Google Cloud Pub/Sub Emulator
   #
   # To develop and test your application locally, you can use the [Google Cloud
   # Pub/Sub Emulator](https://cloud.google.com/pubsub/emulator), which provides

data/lib/gcloud/pubsub/policy.rb

@@ -0,0 +1,204 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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 "gcloud/errors"
+
+module Gcloud
+  module Pubsub
+    ##
+    # # Policy
+    #
+    # Represents a Cloud IAM Policy for the Pub/Sub service.
+    #
+    # 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, and
+    # then send the modified data for writing. This pattern may result in a
+    # conflict if two or more processes attempt the sequence simultaneously. IAM
+    # solves this problem with the {Gcloud::Pubsub::Policy#etag} property, which
+    # is used to verify whether the policy has changed since the last request.
+    # When you make a request to with an `etag` value, Cloud IAM compares the
+    # `etag` value in the request with the existing `etag` value associated with
+    # the policy. It writes the policy only if the `etag` values match.
+    #
+    # When you update a policy, first read the policy (and its current `etag`)
+    # from the service, then modify the policy locally, and then write the
+    # modified policy to the service. See {Gcloud::Pubsub::Topic#policy} and
+    # {Gcloud::Pubsub::Topic#policy=}.
+    #
+    # @see https://cloud.google.com/iam/docs/managing-policies Managing policies
+    # @see https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#iampolicy
+    #   google.iam.v1.IAMPolicy
+    #
+    # @attr [String] etag Used to verify whether the policy has changed since
+    #   the last request. The policy will be written only if the `etag` values
+    #   match.
+    # @attr [Hash{String => Array<String>}] roles The bindings that associate
+    #   roles with an array of members. See [Understanding
+    #   Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+    #   listing of primitive and curated roles.
+    #   See [Binding](https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#binding)
+    #   for a listing of values and patterns for members.
+    #
+    # @example
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   pubsub = gcloud.pubsub
+    #   topic = pubsub.topic "my-topic"
+    #
+    #   policy = topic.policy # API call
+    #
+    #   policy.remove "roles/owner", "user:owner@example.com" # Local call
+    #   policy.add "roles/owner", "user:newowner@example.com" # Local call
+    #   policy.roles["roles/viewer"] = ["allUsers"] # Local call
+    #
+    #   topic.policy = policy # API call
+    #
+    class Policy
+      attr_reader :etag, :roles
+
+      ##
+      # @private Creates a Policy object.
+      def initialize etag, roles
+        @etag = etag
+        @roles = roles
+      end
+
+      ##
+      # Convenience method for adding a member to a binding on this policy.
+      # See [Understanding
+      # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+      # listing of primitive and curated roles.
+      # See [Binding](https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#binding)
+      # for a listing of values and patterns for members.
+      #
+      # @param [String] role_name A Cloud IAM role, such as
+      #   `"roles/pubsub.admin"`.
+      # @param [String] member A Cloud IAM identity, such as
+      #   `"user:owner@example.com"`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #   topic = pubsub.topic "my-topic"
+      #
+      #   policy = topic.policy # API call
+      #
+      #   policy.add "roles/owner", "user:newowner@example.com" # Local call
+      #
+      #   topic.policy = policy # API call
+      #
+      def add role_name, member
+        role(role_name) << member
+      end
+
+      ##
+      # Convenience method for removing a member from a binding on this policy.
+      # See [Understanding
+      # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+      # listing of primitive and curated roles.
+      # See [Binding](https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#binding)
+      # for a listing of values and patterns for members.
+      #
+      # @param [String] role_name A Cloud IAM role, such as
+      #   `"roles/pubsub.admin"`.
+      # @param [String] member A Cloud IAM identity, such as
+      #   `"user:owner@example.com"`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #   topic = pubsub.topic "my-topic"
+      #
+      #   policy = topic.policy # API call
+      #
+      #   policy.remove "roles/owner", "user:owner@example.com" # Local call
+      #
+      #   topic.policy = policy # API call
+      #
+      def remove role_name, member
+        role(role_name).delete member
+      end
+
+      ##
+      # Convenience method returning the array of members bound to a role in
+      # this policy, or an empty array if no value is present for the role in
+      # {#roles}. See [Understanding
+      # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+      # listing of primitive and curated roles. See
+      # [Binding](https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#binding)
+      # for a listing of values and patterns for members.
+      #
+      # @return [Array<String>] The members strings, or an empty array.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #   topic = pubsub.topic "my-topic"
+      #
+      #   policy = topic.policy
+      #
+      #   policy.role("roles/viewer") << "user:viewer@example.com"
+      #
+      def role role_name
+        roles[role_name] ||= []
+      end
+
+      ##
+      # Returns a deep copy of the policy.
+      #
+      # @return [Policy]
+      #
+      def deep_dup
+        dup.tap do |p|
+          roles_dup = p.roles.each_with_object({}) do |(k, v), memo|
+            memo[k] = v.dup rescue value
+          end
+          p.instance_variable_set "@roles", roles_dup
+        end
+      end
+
+      ##
+      # @private Convert the Policy to a Google::Iam::V1::Policy object.
+      def to_grpc
+        Google::Iam::V1::Policy.new(
+          etag: etag,
+          bindings: roles.keys.map do |role_name|
+            next if roles[role_name].empty?
+            Google::Iam::V1::Binding.new(
+              role: role_name,
+              members: roles[role_name]
+            )
+          end
+        )
+      end
+
+      ##
+      # @private New Policy from a Google::Iam::V1::Policy object.
+      def self.from_grpc grpc
+        roles = grpc.bindings.each_with_object({}) do |binding, memo|
+          memo[binding.role] = binding.members.to_a
+        end
+        new grpc.etag, roles
+      end
+    end
+  end
+end

data/lib/gcloud/pubsub/project.rb

@@ -48,11 +48,9 @@ module Gcloud
       attr_accessor :service
 
       ##
-      # @private Creates a new Connection instance.
-      def initialize project, credentials
-        project = project.to_s # Always cast to a string
-        fail ArgumentError, "project is missing" if project.empty?
-        @service = Service.new project, credentials
+      # @private Creates a new Pub/Sub Project instance.
+      def initialize service
+        @service = service
       end
 
       # The Pub/Sub project connected to.
@@ -142,12 +140,9 @@ module Gcloud
         return Topic.new_lazy(topic_name, service, options) if skip_lookup
         grpc = service.get_topic topic_name
         Topic.from_grpc grpc, service
-      rescue GRPC::BadStatus => e
-        if e.code == 5
-          return create_topic(topic_name) if autocreate
-          return nil
-        end
-        raise Error.from_error(e)
+      rescue Gcloud::NotFoundError
+        return create_topic(topic_name) if autocreate
+        nil
       end
       alias_method :get_topic, :topic
       alias_method :find_topic, :topic
@@ -170,8 +165,6 @@ module Gcloud
         ensure_service!
         grpc = service.create_topic topic_name
         Topic.from_grpc grpc, service
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
       end
       alias_method :new_topic, :create_topic
 
@@ -213,8 +206,6 @@ module Gcloud
         options = { token: token, max: max }
         grpc = service.list_topics options
         Topic::List.from_grpc grpc, service, max
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
       end
       alias_method :find_topics, :topics
       alias_method :list_topics, :topics
@@ -232,8 +223,9 @@ module Gcloud
       # @param [Hash] attributes Optional attributes for the message.
       # @option attributes [Boolean] :autocreate Flag to control whether the
       #   provided topic will be created if it does not exist.
-      # @yield [batch] a block for publishing multiple messages in one request
-      # @yieldparam [Topic::Batch] batch the batch object
+      # @yield [publisher] a block for publishing multiple messages in one
+      #   request
+      # @yieldparam [Topic::Publisher] publisher the topic publisher object
       #
       # @return [Message, Array<Message>] Returns the published message when
       #   called without a block, or an array of messages when called with a
@@ -270,10 +262,10 @@ module Gcloud
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #
-      #   msgs = pubsub.publish "my-topic" do |batch|
-      #     batch.publish "new-message-1", foo: :bar
-      #     batch.publish "new-message-2", foo: :baz
-      #     batch.publish "new-message-3", foo: :bif
+      #   msgs = pubsub.publish "my-topic" do |p|
+      #     p.publish "new-message-1", foo: :bar
+      #     p.publish "new-message-2", foo: :baz
+      #     p.publish "new-message-3", foo: :bif
       #   end
       #
       # @example With `autocreate`:
@@ -293,10 +285,10 @@ module Gcloud
         # extract autocreate option
         autocreate = attributes.delete :autocreate
         ensure_service!
-        batch = Topic::Batch.new data, attributes
-        yield batch if block_given?
-        return nil if batch.messages.count.zero?
-        publish_batch_messages topic_name, batch, autocreate
+        publisher = Topic::Publisher.new data, attributes
+        yield publisher if block_given?
+        return nil if publisher.messages.count.zero?
+        publish_batch_messages topic_name, publisher, autocreate
       end
 
       ##
@@ -363,14 +355,14 @@ module Gcloud
         grpc = service.create_subscription topic_name,
                                            subscription_name, options
         Subscription.from_grpc grpc, service
-      rescue GRPC::BadStatus => e
-        if autocreate && e.code == 5
+      rescue Gcloud::NotFoundError => e
+        if autocreate
           create_topic topic_name
           return subscribe(topic_name, subscription_name,
                            deadline: deadline, endpoint: endpoint,
                            autocreate: false)
         end
-        raise Error.from_error(e)
+        raise e
       end
       alias_method :create_subscription, :subscribe
       alias_method :new_subscription, :subscribe
@@ -417,9 +409,8 @@ module Gcloud
         end
         grpc = service.get_subscription subscription_name
         Subscription.from_grpc grpc, service
-      rescue GRPC::BadStatus => e
-        return nil if e.code == 5
-        raise Error.from_error(e)
+      rescue Gcloud::NotFoundError
+        nil
       end
       alias_method :get_subscription, :subscription
       alias_method :find_subscription, :subscription
@@ -461,8 +452,6 @@ module Gcloud
         options = { token: token, max: max }
         grpc = service.list_subscriptions options
         Subscription::List.from_grpc grpc, service, max
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
       end
       alias_method :find_subscriptions, :subscriptions
       alias_method :list_subscriptions, :subscriptions
@@ -481,13 +470,12 @@ module Gcloud
       def publish_batch_messages topic_name, batch, autocreate = false
         grpc = service.publish topic_name, batch.messages
         batch.to_gcloud_messages Array(grpc.message_ids)
-      rescue GRPC::BadStatus => e
-        if autocreate && e.code == 5
+      rescue Gcloud::NotFoundError => e
+        if autocreate
           create_topic topic_name
-          publish_batch_messages topic_name, batch, false
-        else
-          raise Error.from_error(e)
+          return publish_batch_messages topic_name, batch, false
         end
+        raise e
       end
     end
   end