gcloud 0.11.0 → 0.12.0

data/lib/gcloud/pubsub/subscription/list.rb

@@ -30,6 +30,10 @@ module Gcloud
         ##
         # @private Create a new Subscription::List with an array of values.
         def initialize arr = []
+          @topic = nil
+          @prefix = nil
+          @token = nil
+          @max = nil
           super arr
         end
 
@@ -191,16 +195,12 @@ module Gcloud
           options = { prefix: @prefix, token: @token, max: @max }
           grpc = @service.list_subscriptions options
           self.class.from_grpc grpc, @service, @max
-        rescue GRPC::BadStatus => e
-          raise Error.from_error(e)
         end
 
         def next_topic_subscriptions
           options = { token: @token, max: @max }
           grpc = @service.list_topics_subscriptions @topic, options
           self.class.from_topic_grpc grpc, @service, @topic, @max
-        rescue GRPC::BadStatus => e
-          raise Error.from_error(e)
         end
       end
     end

data/lib/gcloud/pubsub/topic.rb

@@ -14,9 +14,10 @@
 
 
 require "gcloud/errors"
-require "gcloud/pubsub/topic/batch"
+require "gcloud/pubsub/topic/publisher"
 require "gcloud/pubsub/topic/list"
 require "gcloud/pubsub/subscription"
+require "gcloud/pubsub/policy"
 
 module Gcloud
   module Pubsub
@@ -86,9 +87,7 @@ module Gcloud
       def delete
         ensure_service!
         service.delete_topic name
-        return true
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
+        true
       end
 
       ##
@@ -143,8 +142,6 @@ module Gcloud
         options = { deadline: deadline, endpoint: endpoint }
         grpc = service.create_subscription name, subscription_name, options
         Subscription.from_grpc grpc, service
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
       end
       alias_method :create_subscription, :subscribe
       alias_method :new_subscription, :subscribe
@@ -186,9 +183,8 @@ module Gcloud
         return Subscription.new_lazy subscription_name, service if skip_lookup
         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
@@ -232,8 +228,6 @@ module Gcloud
         options = { token: token, max: max }
         grpc = service.list_topics_subscriptions name, options
         Subscription::List.from_topic_grpc grpc, service, name, max
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
       end
       alias_method :find_subscriptions, :subscriptions
       alias_method :list_subscriptions, :subscriptions
@@ -243,8 +237,9 @@ module Gcloud
       #
       # @param [String, File] data The message data.
       # @param [Hash] attributes Optional attributes for the message.
-      # @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
@@ -286,102 +281,115 @@ module Gcloud
       #   pubsub = gcloud.pubsub
       #
       #   topic = pubsub.topic "my-topic"
-      #   msgs = topic.publish do |batch|
-      #     batch.publish "new-message-1", foo: :bar
-      #     batch.publish "new-message-2", foo: :baz
-      #     batch.publish "new-message-3", foo: :bif
+      #   msgs = topic.publish do |t|
+      #     t.publish "new-message-1", foo: :bar
+      #     t.publish "new-message-2", foo: :baz
+      #     t.publish "new-message-3", foo: :bif
       #   end
       #
       def publish data = nil, attributes = {}
         ensure_service!
-        batch = Batch.new data, attributes
-        yield batch if block_given?
-        return nil if batch.messages.count.zero?
-        publish_batch_messages batch
+        publisher = Publisher.new data, attributes
+        yield publisher if block_given?
+        return nil if publisher.messages.count.zero?
+        publish_batch_messages publisher
       end
 
       ##
-      # Gets the access control policy.
+      # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
+      # policy for this topic.
+      #
+      # @see https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#iampolicy
+      #   google.iam.v1.IAMPolicy
       #
       # @param [Boolean] force Force the latest policy to be retrieved from the
       #   Pub/Sub service when `true`. Otherwise the policy will be memoized to
       #   reduce the number of API calls made to the Pub/Sub service. The
       #   default is `false`.
       #
-      # @return [Hash] Returns a hash that conforms to the following structure:
+      # @yield [policy] A block for updating the policy. The latest policy will
+      #   be read from the Pub/Sub service and passed to the block. After the
+      #   block completes, the modified policy will be written to the service.
+      # @yieldparam [Policy] policy the current Cloud IAM Policy for this topic
       #
-      #   {
-      #     "etag"=>"CAE=",
-      #     "bindings" => [{
-      #       "role" => "roles/viewer",
-      #       "members" => ["serviceAccount:your-service-account"]
-      #     }]
-      #   }
+      # @return [Policy] the current Cloud IAM Policy for this topic
       #
       # @example Policy values are memoized to reduce the number of API calls:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
-      #
       #   topic = pubsub.topic "my-topic"
-      #   puts topic.policy["bindings"]
-      #   puts topic.policy["rules"]
+      #
+      #   policy = topic.policy # API call
+      #   policy_2 = topic.policy # No API call
       #
       # @example Use `force` to retrieve the latest policy from the service:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
+      #   topic = pubsub.topic "my-topic"
       #
+      #   policy = topic.policy force: true # API call
+      #   policy_2 = topic.policy force: true # API call
+      #
+      # @example Update the policy by passing a block:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
       #   topic = pubsub.topic "my-topic"
-      #   policy = topic.policy force: true
+      #
+      #   policy = topic.policy do |p|
+      #     p.add "roles/owner", "user:owner@example.com"
+      #   end # 2 API calls
       #
       def policy force: nil
-        @policy = nil if force
+        @policy = nil if force || block_given?
         @policy ||= begin
           ensure_service!
           grpc = service.get_topic_policy name
-          JSON.parse(Google::Iam::V1::Policy.encode_json(grpc))
-        rescue GRPC::BadStatus => e
-          raise Error.from_error(e)
+          Policy.from_grpc grpc
         end
+        return @policy unless block_given?
+        p = @policy.deep_dup
+        yield p
+        self.policy = p
       end
 
       ##
-      # Sets the access control policy.
+      # Updates the [Cloud IAM](https://cloud.google.com/iam/) access control
+      # policy for this topic. The policy should be read from {#policy}. See
+      # {Gcloud::Pubsub::Policy} for an explanation of the policy `etag`
+      # property and how to modify policies.
       #
-      # @param [String] new_policy A hash that conforms to the following
-      #   structure:
+      # You can also update the policy by passing a block to {#policy}, which
+      # will call this method internally after the block completes.
       #
-      #     {
-      #       "bindings" => [{
-      #         "role" => "roles/viewer",
-      #         "members" => ["serviceAccount:your-service-account"]
-      #       }]
-      #     }
+      # @see https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#iampolicy
+      #   google.iam.v1.IAMPolicy
+      #
+      # @param [Policy] new_policy a new or modified Cloud IAM Policy for this
+      #   topic
       #
       # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
-      #
-      #   viewer_policy = {
-      #     "bindings" => [{
-      #       "role" => "roles/viewer",
-      #       "members" => ["serviceAccount:your-service-account"]
-      #     }]
-      #   }
       #   topic = pubsub.topic "my-topic"
-      #   topic.policy = viewer_policy
+      #
+      #   policy = topic.policy # API call
+      #
+      #   policy.add "roles/owner", "user:owner@example.com"
+      #
+      #   topic.policy = policy # API call
       #
       def policy= new_policy
         ensure_service!
-        grpc = service.set_topic_policy name, new_policy
-        @policy = JSON.parse(Google::Iam::V1::Policy.encode_json(grpc))
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
+        grpc = service.set_topic_policy name, new_policy.to_grpc
+        @policy = Policy.from_grpc grpc
       end
 
       ##
@@ -424,8 +432,6 @@ module Gcloud
         ensure_service!
         grpc = service.test_topic_permissions name, permissions
         grpc.permissions
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
       end
 
       ##
@@ -490,9 +496,8 @@ module Gcloud
         ensure_service!
         return @grpc if @grpc
         @grpc = service.get_topic @name
-      rescue GRPC::BadStatus => e
-        return nil if e.code == 5
-        raise Error.from_error(e)
+      rescue Gcloud::NotFoundError
+        nil
       end
 
       ##
@@ -500,8 +505,6 @@ module Gcloud
       def publish_batch_messages batch
         grpc = service.publish name, batch.messages
         batch.to_gcloud_messages Array(grpc.message_ids)
-      rescue GRPC::BadStatus => e
-        raise Error.from_error(e)
       end
     end
   end

data/lib/gcloud/pubsub/topic/list.rb

@@ -75,8 +75,6 @@ module Gcloud
           options = { token: token, max: @max }
           grpc = @service.list_topics options
           self.class.from_grpc grpc, @service, @max
-        rescue GRPC::BadStatus => e
-          raise Error.from_error(e)
         end
 
         ##

data/lib/gcloud/pubsub/topic/{batch.rb → publisher.rb}

@@ -17,8 +17,21 @@ module Gcloud
   module Pubsub
     class Topic
       ##
-      # Batch object used to publish multiple messages at once.
-      class Batch
+      # Topic Publisher object used to publish multiple messages at once.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   topic = pubsub.topic "my-topic"
+      #   msgs = topic.publish do |t|
+      #     t.publish "new-message-1", foo: :bar
+      #     t.publish "new-message-2", foo: :baz
+      #     t.publish "new-message-3", foo: :bif
+      #   end
+      class Publisher
         ##
         # @private The messages to publish
         attr_reader :messages

data/lib/gcloud/resource_manager.rb

@@ -34,6 +34,9 @@ module Gcloud
   #   The default scope is:
   #
   #   * `https://www.googleapis.com/auth/cloud-platform`
+  # @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::ResourceManager::Manager]
   #
@@ -45,14 +48,17 @@ module Gcloud
   #     puts projects.project_id
   #   end
   #
-  def self.resource_manager keyfile = nil, scope: nil
+  def self.resource_manager keyfile = nil, scope: nil, retries: nil,
+                            timeout: nil
     if keyfile.nil?
       credentials = Gcloud::ResourceManager::Credentials.default scope: scope
     else
       credentials = Gcloud::ResourceManager::Credentials.new keyfile,
                                                              scope: scope
     end
-    Gcloud::ResourceManager::Manager.new credentials
+    Gcloud::ResourceManager::Manager.new(
+      Gcloud::ResourceManager::Service.new(
+        credentials, retries: retries, timeout: timeout))
   end
 
   ##
@@ -97,8 +103,8 @@ module Gcloud
   # ```
   #
   # Also make sure all `GCLOUD` environment variables are cleared of any service
-  # accounts. Then gcloud will be able to detect the user authentication and
-  # connect with those credentials.
+  # accounts. Then gcloud-ruby will be able to detect the user authentication
+  # and connect with those credentials.
   #
   # ```ruby
   # require "gcloud"
@@ -201,24 +207,23 @@ module Gcloud
   # resource_manager.undelete "tokyo-rain-123"
   # ```
   #
-  # ## 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
+  # resource_manager = gcloud.resource_manager retries: 10, timeout: 120
   # ```
   #
   # See the [Resource Manager error
@@ -234,7 +239,8 @@ module Gcloud
   # Overview](https://cloud.google.com/iam/docs/overview) for more information.
   #
   # A project's access control policy can be retrieved. (See
-  # {Gcloud::ResourceManager::Project#policy})
+  # {Gcloud::ResourceManager::Project#policy} and
+  # {Gcloud::ResourceManager::Policy}.)
   #
   # ```ruby
   # require "gcloud"
@@ -245,8 +251,7 @@ module Gcloud
   # policy = project.policy
   # ```
   #
-  # A project's access control policy can also be set. (See
-  # {Gcloud::ResourceManager::Project#policy=})
+  # A project's access control policy can also be updated:
   #
   # ```ruby
   # require "gcloud"
@@ -255,13 +260,9 @@ module Gcloud
   # resource_manager = gcloud.resource_manager
   # project = resource_manager.project "tokyo-rain-123"
   #
-  # viewer_policy = {
-  #   "bindings" => [{
-  #     "role" => "roles/viewer",
-  #     "members" => ["serviceAccount:your-service-account"]
-  #   }]
-  # }
-  # project.policy = viewer_policy
+  # policy = project.policy do |p|
+  #   p.add "roles/viewer", "serviceAccount:your-service-account"
+  # end
   # ```
   #
   # And permissions can be tested on a project. (See

data/lib/gcloud/resource_manager/manager.rb

@@ -13,9 +13,9 @@
 # limitations under the License.
 
 
+require "gcloud/errors"
 require "gcloud/resource_manager/credentials"
-require "gcloud/resource_manager/connection"
-require "gcloud/resource_manager/errors"
+require "gcloud/resource_manager/service"
 require "gcloud/resource_manager/project"
 
 module Gcloud
@@ -37,15 +37,15 @@ module Gcloud
     # See {Gcloud#resource_manager}
     class Manager
       ##
-      # @private The Connection object.
-      attr_accessor :connection
+      # @private The Service object.
+      attr_accessor :service
 
       ##
-      # @private Creates a new Connection instance.
+      # @private Creates a new Service instance.
       #
       # See {Gcloud.resource_manager}
-      def initialize credentials
-        @connection = Connection.new credentials
+      def initialize service
+        @service = service
       end
 
       ##
@@ -113,12 +113,8 @@ module Gcloud
       #   end
       #
       def projects filter: nil, token: nil, max: nil
-        resp = connection.list_project filter: filter, token: token, max: max
-        if resp.success?
-          Project::List.from_response resp, self, filter, max
-        else
-          fail ApiError.from_response(resp)
-        end
+        gapi = service.list_project filter: filter, token: token, max: max
+        Project::List.from_gapi gapi, self, filter, max
       end
 
       ##
@@ -138,12 +134,10 @@ module Gcloud
       #   project.project_id #=> "tokyo-rain-123"
       #
       def project project_id
-        resp = connection.get_project project_id
-        if resp.success?
-          Project.from_gapi resp.data, connection
-        else
-          nil
-        end
+        gapi = service.get_project project_id
+        Project.from_gapi gapi, service
+      rescue NotFoundError
+        nil
       end
 
       ##
@@ -194,14 +188,8 @@ module Gcloud
       #                                             labels: {env: :development}
       #
       def create_project project_id, name: nil, labels: nil
-        resp = connection.create_project project_id,
-                                         name,
-                                         labels
-        if resp.success?
-          Project.from_gapi resp.data, connection
-        else
-          fail ApiError.from_response(resp)
-        end
+        gapi = service.create_project project_id, name, labels
+        Project.from_gapi gapi, service
       end
 
       ##
@@ -233,12 +221,8 @@ module Gcloud
       #   resource_manager.delete "tokyo-rain-123"
       #
       def delete project_id
-        resp = connection.delete_project project_id
-        if resp.success?
-          true
-        else
-          fail ApiError.from_response(resp)
-        end
+        service.delete_project project_id
+        true
       end
 
       ##
@@ -259,12 +243,8 @@ module Gcloud
       #   resource_manager.undelete "tokyo-rain-123"
       #
       def undelete project_id
-        resp = connection.undelete_project project_id
-        if resp.success?
-          true
-        else
-          fail ApiError.from_response(resp)
-        end
+        service.undelete_project project_id
+        true
       end
 
       protected