gcloud 0.10.0 → 0.11.0

data/lib/gcloud/dns/zone/transaction.rb

@@ -103,7 +103,7 @@ module Gcloud
         #   end
         #
         def remove name, type
-          @deletions += @zone.records(name, type).all
+          @deletions += @zone.records(name, type).all.to_a
         end
 
         ##

data/lib/gcloud/logging.rb

@@ -302,6 +302,25 @@ module Gcloud
   # logger.info "Job started."
   # ```
   #
+  # ## 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
+  # ```
   #
   module Logging
   end

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

@@ -34,12 +34,40 @@ module Gcloud
 
         ##
         # Whether there is a next page of entries.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #
+        #   entries = logging.entries
+        #   if entries.next?
+        #     next_entries = entries.next
+        #   end
+        #
         def next?
           !token.nil?
         end
 
         ##
         # Retrieve the next page of entries.
+        #
+        # @return [Sink::List]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #
+        #   entries = dataset.entries
+        #   if entries.next?
+        #     next_entries = entries.next
+        #   end
+        #
         def next
           return nil unless next?
           ensure_service!
@@ -51,30 +79,71 @@ module Gcloud
         end
 
         ##
-        # Retrieves all log entries by repeatedly loading {#next} until
-        # {#next?} returns `false`. Returns the list instance for method
-        # chaining.
+        # Retrieves all log entries by repeatedly loading {#next} until {#next?}
+        # returns `false`. Calls the given block once for each log entry, which
+        # is passed as the parameter.
+        #
+        # An Enumerator is returned if no block is given.
         #
         # This method may make several API calls until all log entries are
         # retrieved. Be sure to use as narrow a search criteria as possible.
         # Please use with caution.
         #
-        # @example
+        # @param [Integer] request_limit The upper limit of API requests to make
+        #   to load all log entries. Default is no limit.
+        # @yield [entry] The block for accessing each log entry.
+        # @yieldparam [Entry] entry The log entry object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating each log entry by passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   entries = logging.entries order: "timestamp desc"
+        #
+        #   entries.all do |entry|
+        #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
         #   logging = gcloud.logging
-        #   hour_ago = (Time.now - 60*60).utc.strftime('%FT%TZ')
-        #   recent_errors = "timestamp >= \"#{hour_ago}\" severity >= ERROR"
-        #   entries = logging.entries(filter: recent_errors).all
-        #
-        def all
-          while next?
-            next_records = self.next
-            push(*next_records)
-            self.token = next_records.token
+        #   entries = logging.entries order: "timestamp desc"
+        #
+        #   all_payloads = entries.all.map do |entry|
+        #     entry.payload
+        #   end
+        #
+        # @example Limit the number of API calls made:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   entries = logging.entries order: "timestamp desc"
+        #
+        #   entries.all(request_limit: 10) do |entry|
+        #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+        #   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
 
         ##

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

@@ -34,45 +34,121 @@ module Gcloud
 
         ##
         # Whether there is a next page of metrics.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #
+        #   metrics = logging.metrics
+        #   if metrics.next?
+        #     next_metrics = metrics.next
+        #   end
+        #
         def next?
           !token.nil?
         end
 
         ##
         # Retrieve the next page of metrics.
+        #
+        # @return [Sink::List]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #
+        #   metrics = dataset.metrics
+        #   if metrics.next?
+        #     next_metrics = metrics.next
+        #   end
+        #
         def next
           return nil unless next?
           ensure_service!
-          grpc = @service.list_metrics token: token
+          grpc = @service.list_metrics token: token, max: @max
           self.class.from_grpc grpc, @service
         rescue GRPC::BadStatus => e
           raise Gcloud::Error.from_error(e)
         end
 
         ##
-        # Retrieves all metrics by repeatedly loading {#next?} until {#next?}
-        # returns `false`. Returns the list instance for method chaining.
+        # Retrieves all metrics by repeatedly loading {#next} until {#next?}
+        # returns `false`. Calls the given block once for each metric, 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 metrics 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 metrics. Default is no limit.
+        # @yield [metric] The block for accessing each metric.
+        # @yieldparam [Metric] metric The metric object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating each metric by passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   metrics = logging.metrics
+        #
+        #   metrics.all do |metric|
+        #     puts "#{metric.name}: #{metric.filter}"
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
         #   logging = gcloud.logging
-        #   all_metrics = logging.metrics.all # Load all pages of metrics
+        #   metrics = logging.metrics
+        #
+        #   all_names = metrics.all.map do |metric|
+        #     metric.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
+        #   metrics = logging.metrics
+        #
+        #   metrics.all(request_limit: 10) do |metric|
+        #     puts "#{metric.name}: #{metric.filter}"
+        #   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 Metric::List from a
         # Google::Logging::V2::ListLogMetricsResponse object.
-        def self.from_grpc grpc_list, service
+        def self.from_grpc grpc_list, service, max = nil
           metrics = new(Array(grpc_list.metrics).map do |grpc_metric|
             Metric.from_grpc grpc_metric, service
           end)
@@ -80,6 +156,7 @@ module Gcloud
           token = nil if token == ""
           metrics.instance_variable_set "@token", token
           metrics.instance_variable_set "@service", service
+          metrics.instance_variable_set "@max", max
           metrics
         end
 

data/lib/gcloud/logging/project.rb

@@ -132,18 +132,15 @@ module Gcloud
       #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
       #   end
       #
-      # @example With pagination: (See {Gcloud::Logging::Entry::List})
+      # @example Retrieve all log entries: (See {Entry::List#all})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   logging = gcloud.logging
       #   entries = logging.entries
-      #   loop do
-      #     entries.each do |e|
-      #       puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
-      #     end
-      #     break unless entries.next?
-      #     entries = entries.next
+      #
+      #   entries.all do |e|
+      #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
       #   end
       #
       def entries projects: nil, filter: nil, order: nil, token: nil, max: nil
@@ -341,18 +338,15 @@ module Gcloud
       #   gcloud = Gcloud.new
       #   logging = gcloud.logging
       #   resource_descriptors = logging.resource_descriptors
-      #   loop do
-      #     resource_descriptors.each do |rd|
-      #       puts rd.type
-      #     end
-      #     break unless resource_descriptors.next?
-      #     resource_descriptors = resource_descriptors.next
+      #
+      #   resource_descriptors.all do |rd|
+      #     puts rd.type
       #   end
       #
       def resource_descriptors token: nil, max: nil
         ensure_service!
         list_grpc = service.list_resource_descriptors token: token, max: max
-        ResourceDescriptor::List.from_grpc list_grpc, service
+        ResourceDescriptor::List.from_grpc list_grpc, service, max
       rescue GRPC::BadStatus => e
         raise Gcloud::Error.from_error(e)
       end
@@ -401,24 +395,21 @@ module Gcloud
       #     puts "#{s.name}: #{s.filter} -> #{s.destination}"
       #   end
       #
-      # @example With pagination: (See {Gcloud::Logging::Sink::List})
+      # @example Retrieve all sinks: (See {Sink::List#all})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   logging = gcloud.logging
       #   sinks = logging.sinks
-      #   loop do
-      #     sinks.each do |s|
-      #       puts "#{s.name}: #{s.filter} -> #{s.destination}"
-      #     end
-      #     break unless sinks.next?
-      #     sinks = sinks.next
+      #
+      #   sinks.all do |s|
+      #     puts "#{s.name}: #{s.filter} -> #{s.destination}"
       #   end
       #
       def sinks token: nil, max: nil
         ensure_service!
         list_grpc = service.list_sinks token: token, max: max
-        Sink::List.from_grpc list_grpc, service
+        Sink::List.from_grpc list_grpc, service, max
       rescue GRPC::BadStatus => e
         raise Gcloud::Error.from_error(e)
       end
@@ -545,24 +536,21 @@ module Gcloud
       #     puts "#{m.name}: #{m.filter}"
       #   end
       #
-      # @example With pagination: (See {Gcloud::Logging::Metric::List})
+      # @example Retrieve all metrics: (See {Metric::List#all})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   logging = gcloud.logging
       #   metrics = logging.metrics
-      #   loop do
-      #     metrics.each do |m|
-      #       puts "#{m.name}: #{m.filter}"
-      #     end
-      #     break unless metrics.next?
-      #     metrics = metrics.next
+      #
+      #   metrics.all do |m|
+      #     puts "#{m.name}: #{m.filter}"
       #   end
       #
       def metrics token: nil, max: nil
         ensure_service!
         grpc = service.list_metrics token: token, max: max
-        Metric::List.from_grpc grpc, service
+        Metric::List.from_grpc grpc, service, max
       rescue GRPC::BadStatus => e
         raise Gcloud::Error.from_error(e)
       end

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

@@ -35,33 +35,132 @@ module Gcloud
 
         ##
         # Whether there is a next page of resource descriptors.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #
+        #   resource_descriptors = logging.resource_descriptors
+        #   if resource_descriptors.next?
+        #     next_resource_descriptors = resource_descriptors.next
+        #   end
+        #
         def next?
           !token.nil?
         end
 
         ##
         # Retrieve the next page of resource descriptors.
+        #
+        # @return [Sink::List]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #
+        #   resource_descriptors = logging.resource_descriptors
+        #   if resource_descriptors.next?
+        #     next_resource_descriptors = resource_descriptors.next
+        #   end
+        #
         def next
           return nil unless next?
           ensure_service!
-          list_grpc = @service.list_resource_descriptors token: token
+          list_grpc = @service.list_resource_descriptors token: token, max: @max
           self.class.from_grpc list_grpc, @service
         rescue GRPC::BadStatus => e
           raise Gcloud::Error.from_error(e)
         end
 
+        ##
+        # Retrieves all resource descriptors by repeatedly loading {#next} until
+        # {#next?} returns `false`. Calls the given block once for each resource
+        # descriptor, which is passed as the parameter.
+        #
+        # An Enumerator is returned if no block is given.
+        #
+        # This method may make several API calls until all resource descriptors
+        # 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 resource descriptors. Default is no limit.
+        # @yield [resource_descriptor] The block for accessing each resource
+        #   descriptor.
+        # @yieldparam [ResourceDescriptor] resource_descriptor The resource
+        #   descriptor object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating each resource descriptor by passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   resource_descriptors = logging.resource_descriptors
+        #
+        #   resource_descriptors.all do |rd|
+        #     puts rd.type
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   resource_descriptors = logging.resource_descriptors
+        #
+        #   all_types = resource_descriptors.all.map do |rd|
+        #     rd.type
+        #   end
+        #
+        # @example Limit the number of API calls made:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   resource_descriptors = logging.resource_descriptors
+        #
+        #   resource_descriptors.all(request_limit: 10) do |rd|
+        #     puts rd.type
+        #   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
+        end
+
         ##
         # @private New ResourceDescriptor::List from a
         # Google::Logging::V2::ListMonitoredResourceDescriptorsResponse object.
-        def self.from_grpc grpc_list, service
-          sinks = new(Array(grpc_list.resource_descriptors).map do |grpc|
+        def self.from_grpc grpc_list, service, max = nil
+          rds = new(Array(grpc_list.resource_descriptors).map do |grpc|
             ResourceDescriptor.from_grpc grpc
           end)
           token = grpc_list.next_page_token
           token = nil if token == ""
-          sinks.instance_variable_set "@token", token
-          sinks.instance_variable_set "@service", service
-          sinks
+          rds.instance_variable_set "@token", token
+          rds.instance_variable_set "@service", service
+          rds.instance_variable_set "@max", max
+          rds
         end
 
         protected