gcloud 0.10.0 → 0.11.0

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

@@ -34,45 +34,121 @@ module Gcloud
 
         ##
         # Whether there is a next page of sinks.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #
+        #   sinks = logging.sinks
+        #   if sinks.next?
+        #     next_sinks = sinks.next
+        #   end
+        #
         def next?
           !token.nil?
         end
 
         ##
         # Retrieve the next page of sinks.
+        #
+        # @return [Sink::List]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #
+        #   sinks = dataset.sinks
+        #   if sinks.next?
+        #     next_sinks = sinks.next
+        #   end
+        #
         def next
           return nil unless next?
           ensure_service!
-          list_grpc = @service.list_sinks token: token
+          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
 
         ##
-        # Retrieves all sinks by repeatedly loading {#next?} until {#next?}
-        # returns `false`. Returns the list instance for method chaining.
+        # Retrieves all sinks by repeatedly loading {#next} until {#next?}
+        # returns `false`. Calls the given block once for each sink, which is
+        # passed as the parameter.
         #
-        # @example
+        # An Enumerator is returned if no block is given.
+        #
+        # This method may make several API calls until all sinks are retrieved.
+        # Be sure to use as narrow a search criteria as possible. Please use
+        # with caution.
+        #
+        # @param [Integer] request_limit The upper limit of API requests to make
+        #   to load all sinks. Default is no limit.
+        # @yield [sink] The block for accessing each sink.
+        # @yieldparam [Sink] sink The sink object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating each sink by passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   sinks = logging.sinks
+        #
+        #   sinks.all do |sink|
+        #     puts "#{sink.name}: #{sink.filter} -> #{sink.destination}"
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
         #   logging = gcloud.logging
-        #   all_sinks = logging.sinks.all # Load all pages of sinks
+        #   sinks = logging.sinks
+        #
+        #   all_names = sinks.all.map do |sink|
+        #     sink.name
+        #   end
         #
-        def all
-          while next?
-            next_records = self.next
-            push(*next_records)
-            self.token = next_records.token
+        # @example Limit the number of API calls made:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   sinks = logging.sinks
+        #
+        #   sinks.all(request_limit: 10) do |sink|
+        #     puts "#{sink.name}: #{sink.filter} -> #{sink.destination}"
+        #   end
+        #
+        def all request_limit: nil
+          request_limit = request_limit.to_i if request_limit
+          unless block_given?
+            return enum_for(:all, request_limit: request_limit)
+          end
+          results = self
+          loop do
+            results.each { |r| yield r }
+            if request_limit
+              request_limit -= 1
+              break if request_limit < 0
+            end
+            break unless results.next?
+            results = results.next
           end
-          self
         end
 
         ##
         # @private New Sink::List from a Google::Logging::V2::ListSinksResponse
         # object.
-        def self.from_grpc grpc_list, service
+        def self.from_grpc grpc_list, service, max = nil
           sinks = new(Array(grpc_list.sinks).map do |grpc|
             Sink.from_grpc grpc, service
           end)
@@ -80,6 +156,7 @@ module Gcloud
           token = nil if token == ""
           sinks.instance_variable_set "@token", token
           sinks.instance_variable_set "@service", service
+          sinks.instance_variable_set "@max", max
           sinks
         end
 

data/lib/gcloud/pubsub.rb

@@ -389,6 +389,29 @@ module Gcloud
   # end
   # ```
   #
+  # ## Configuring Backoff
+  #
+  # 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`.
+  #
+  # 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.
+  #
+  # ```ruby
+  # require "gcloud"
+  # require "gcloud/backoff"
+  #
+  # Gcloud::Backoff.retries = 5 # Raise the maximum number of retries from 3
+  # ```
+  #
+  # See the [Pub/Sub error codes](https://cloud.google.com/pubsub/error-codes)
+  # for a list of error conditions.
+  #
   # ## Working Across Projects
   #
   # All calls to the Pub/Sub service use the same project and credentials

data/lib/gcloud/pubsub/project.rb

@@ -197,29 +197,22 @@ module Gcloud
       #     puts topic.name
       #   end
       #
-      # @example With pagination: (See {Topic::List#token})
+      # @example Retrieve all topics: (See {Topic::List#all})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #
-      #   all_topics = []
-      #   tmp_topics = pubsub.topics
-      #   while tmp_topics.any? do
-      #     tmp_topics.each do |topic|
-      #       all_topics << topic
-      #     end
-      #     # break loop if no more topics available
-      #     break if tmp_topics.token.nil?
-      #     # get the next group of topics
-      #     tmp_topics = pubsub.topics token: tmp_topics.token
+      #   topics = pubsub.topics
+      #   topics.all do |topic|
+      #     puts topic.name
       #   end
       #
       def topics token: nil, max: nil
         ensure_service!
         options = { token: token, max: max }
         grpc = service.list_topics options
-        Topic::List.from_grpc grpc, service
+        Topic::List.from_grpc grpc, service, max
       rescue GRPC::BadStatus => e
         raise Error.from_error(e)
       end
@@ -235,7 +228,7 @@ module Gcloud
       # without a subscription will be lost.
       #
       # @param [String] topic_name Name of a topic.
-      # @param [String] data The message data.
+      # @param [String, File] data The message data.
       # @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.
@@ -254,6 +247,14 @@ module Gcloud
       #
       #   msg = pubsub.publish "my-topic", "new-message"
       #
+      # @example A message can be published using a File object:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   msg = pubsub.publish "my-topic", File.open("message.txt")
+      #
       # @example Additionally, a message can be published with attributes:
       #   require "gcloud"
       #
@@ -426,8 +427,6 @@ module Gcloud
       ##
       # Retrieves a list of subscriptions for the given project.
       #
-      # @param [String] prefix Filter results to subscriptions whose names begin
-      #   with this prefix.
       # @param [String] token A previously-returned page token representing part
       #   of the larger set of results to view.
       # @param [Integer] max Maximum number of subscriptions to return.
@@ -446,29 +445,22 @@ module Gcloud
       #     puts subscription.name
       #   end
       #
-      # @example With pagination: (See {Subscription::List#token})
+      # @example Retrieve all subscriptions: (See {Subscription::List#all})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #
-      #   all_subs = []
-      #   tmp_subs = pubsub.subscriptions
-      #   while tmp_subs.any? do
-      #     tmp_subs.each do |subscription|
-      #       all_subs << subscription
-      #     end
-      #     # break loop if no more subscriptions available
-      #     break if tmp_subs.token.nil?
-      #     # get the next group of subscriptions
-      #     tmp_subs = pubsub.subscriptions token: tmp_subs.token
+      #   subscriptions = pubsub.subscriptions
+      #   subscriptions.all do |subscription|
+      #     puts subscription.name
       #   end
       #
-      def subscriptions prefix: nil, token: nil, max: nil
+      def subscriptions token: nil, max: nil
         ensure_service!
-        options = { prefix: prefix, token: token, max: max }
+        options = { token: token, max: max }
         grpc = service.list_subscriptions options
-        Subscription::List.from_grpc grpc, service
+        Subscription::List.from_grpc grpc, service, max
       rescue GRPC::BadStatus => e
         raise Error.from_error(e)
       end

data/lib/gcloud/pubsub/service.rb

@@ -122,9 +122,7 @@ module Gcloud
           topic: topic_path(topic),
           messages: messages.map do |data, attributes|
             Google::Pubsub::V1::PubsubMessage.new(
-              data: String(data).encode("ASCII-8BIT"),
-              attributes: attributes
-            )
+              data: data, attributes: attributes)
           end
         )
 

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

@@ -28,25 +28,179 @@ module Gcloud
         attr_accessor :token
 
         ##
-        # Create a new Subscription::List with an array of values.
-        def initialize arr = [], token = nil
+        # @private Create a new Subscription::List with an array of values.
+        def initialize arr = []
           super arr
-          @token = token
-          @token = nil if @token == ""
         end
 
         ##
-        # @private New Subscriptions::List from a
-        # Google::Pubsub::V1::ListSubscriptionsRequest object.
-        def self.from_grpc grpc_list, service
-          subs = Array(grpc_list.subscriptions).map do |grpc|
-            if grpc.is_a? String
-              Subscription.new_lazy grpc, service
-            else
-              Subscription.from_grpc grpc, service
+        # Whether there a next page of subscriptions.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   subscriptions = pubsub.subscriptions
+        #   if subscriptions.next?
+        #     next_subscriptions = subscriptions.next
+        #   end
+        #
+        def next?
+          !token.nil?
+        end
+
+        ##
+        # Retrieve the next page of subscriptions.
+        #
+        # @return [Subscription::List]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   subscriptions = pubsub.subscriptions
+        #   if subscriptions.next?
+        #     next_subscriptions = subscriptions.next
+        #   end
+        #
+        def next
+          return nil unless next?
+          ensure_service!
+          if @topic
+            next_topic_subscriptions
+          else
+            next_subscriptions
+          end
+        end
+
+        ##
+        # Retrieves all subscriptions by repeatedly loading {#next} until
+        # {#next?} returns `false`. Calls the given block once for each
+        # subscription, which is passed as the parameter.
+        #
+        # An Enumerator is returned if no block is given.
+        #
+        # This method may make several API calls until all subscriptions are
+        # retrieved. Be sure to use as narrow a search criteria as possible.
+        # Please use with caution.
+        #
+        # @param [Integer] request_limit The upper limit of API requests to make
+        #   to load all subscriptions. Default is no limit.
+        # @yield [subscription] The block for accessing each subscription.
+        # @yieldparam [Subscription] subscription The subscription object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating each subscription by passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   subscriptions = pubsub.subscriptions
+        #   subscriptions.all do |subscription|
+        #     puts subscription.name
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   subscriptions = pubsub.subscriptions
+        #   all_names = subscriptions.all.map do |subscription|
+        #     subscription.name
+        #   end
+        #
+        # @example Limit the number of API calls made:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   subscriptions = pubsub.subscriptions
+        #   subscriptions.all(request_limit: 10) do |subscription|
+        #     puts subscription.name
+        #   end
+        #
+        def all request_limit: nil
+          request_limit = request_limit.to_i if request_limit
+          unless block_given?
+            return enum_for(:all, request_limit: request_limit)
+          end
+          results = self
+          loop do
+            results.each { |r| yield r }
+            if request_limit
+              request_limit -= 1
+              break if request_limit < 0
             end
+            break unless results.next?
+            results = results.next
           end
-          new subs, grpc_list.next_page_token
+        end
+
+        ##
+        # @private New Subscriptions::List from a
+        # Google::Pubsub::V1::ListSubscriptionsRequest object.
+        def self.from_grpc grpc_list, service, max = nil
+          subs = new(Array(grpc_list.subscriptions).map do |grpc|
+            Subscription.from_grpc grpc, service
+          end)
+          token = grpc_list.next_page_token
+          token = nil if token == ""
+          subs.instance_variable_set "@token",   token
+          subs.instance_variable_set "@service", service
+          subs.instance_variable_set "@max",     max
+          subs
+        end
+
+        ##
+        # @private New Subscriptions::List from a
+        # Google::Pubsub::V1::ListTopicSubscriptionsResponse object.
+        def self.from_topic_grpc grpc_list, service, topic, max = nil
+          subs = new(Array(grpc_list.subscriptions).map do |grpc|
+            Subscription.new_lazy grpc, service
+          end)
+          token = grpc_list.next_page_token
+          token = nil if token == ""
+          subs.instance_variable_set "@token",   token
+          subs.instance_variable_set "@service", service
+          subs.instance_variable_set "@topic",   topic
+          subs.instance_variable_set "@max",     max
+          subs
+        end
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          fail "Must have active connection to service" unless @service
+        end
+
+        def next_subscriptions
+          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