google-api-client 0.7.0.rc2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c9fdb163b06a237193bbfdb00789efa0477f9f25
-  data.tar.gz: f69ac3dfb9612faee06a4621a68f8cc76cdac706
+  metadata.gz: 25f7fed5190421b20ce39568ea716d2a5a52627e
+  data.tar.gz: f511d420725a7e69600d7654090d7794743c8591
 SHA512:
-  metadata.gz: f26c7cc3ab8beab47c95b2763c8f0c5bc5df4ea04e6daae3ad5f5e9f8c24e3358a295d642ec3c315e269d5a2837ab83fc02122723604fe9c467740b6689e8f0c
-  data.tar.gz: 1432deab452fc436913508288081f4febf770d995e8dcdbd9ce0f5bf1145e894c4b44ba4a4cf7839e6e48d21d77c80a0c5a90f892ecce341f946118f11072966
+  metadata.gz: 4a889315a2b6d96b6d56ac808880203c7dbe6c108a214c610440182e784162a93c753367d49d9cc16b22a50a8d2668e507590d45f6665c3227fe31faed8adf88
+  data.tar.gz: 49493d0cb5c148bd88962b1eaca02acba2f21bfc04ef115a6e75958f2677a386a6945698f3ea2054b2f3e635be08fc441441aef149f60aa880503809b7618d90

data/CHANGELOG.md

@@ -1,8 +1,11 @@
-# 0.7.0.rc2
+# 0.7.0
+* Remove CLI
+* SUpport for automatic retires & backoff. Off by default, enable by setting `retries` on `APIClient`
+* Experimental new interface (see `Google::APIClient::Service`)
 * Fix warnings when using Faraday separately
 * Support Google Compute Engine service accounts
 * Enable gzip compression for responses
-* Upgrade to Faraday 0.9.x. Resolves multiple issues with query parameter encodings.
+* Upgrade to Faraday 0.9.0. Resolves multiple issues with query parameter encodings.
 * Use bundled root certificates for verifying SSL certificates
 * Rewind media when retrying uploads
 

data/Gemfile

@@ -6,10 +6,11 @@ gem 'signet', '>= 0.5.0'
 gem 'addressable', '>= 2.3.2'
 gem 'uuidtools', '>= 2.1.0'
 gem 'autoparse', '>= 0.3.3'
-gem 'faraday', '>= 0.9.0.rc5'
+gem 'faraday', '>= 0.9.0'
 gem 'multi_json', '>= 1.0.0'
 gem 'extlib', '>= 0.9.15'
 gem 'jwt', '~> 0.1.5'
+gem 'retriable', '>= 1.4'
 gem 'jruby-openssl', :platforms => :jruby
 
 group :development do
@@ -18,6 +19,13 @@ group :development do
   gem 'kramdown'
 end
 
+
+platforms :rbx do
+  gem 'rubysl', '~> 2.0'
+  gem 'psych'
+end
+
+
 group :examples do
   gem 'sinatra'
 end
@@ -29,4 +37,5 @@ group :test, :development do
   gem 'rcov', '>= 0.9.9', :platform => :mri_18
 end
 
+
 gem 'idn', :platform => :mri_18

data/README.md

@@ -107,6 +107,16 @@ client.authorization.fetch_access_token!
 client.execute(...)
 ```
 
+Service accounts are also used for delegation in Google Apps domains. The target user for impersonation is specified by setting the `:person` parameter to the user's email address
+in the credentials. Detailed instructions on how to enable delegation for your domain can be found at [developers.google.com](https://developers.google.com/drive/delegation).
+
+### Automatic Retries & Backoff
+
+The API client can automatically retry requests for recoverable errors. To enable retries, set the `client.retries` property to
+the number of additional attempts. To avoid flooding servers, retries invovle a 1 second delay that increases on each subsequent retry.
+
+The default value for retries is 0, but will be enabled by default in future releases.
+
 ### Batching Requests
 
 Some Google APIs support batching requests into a single HTTP request. Use `Google::APIClient::BatchRequest`
@@ -194,7 +204,7 @@ For more information, use `google-api --help`
 
 ## Samples
 
-See the full list of [samples on Google Code](http://code.google.com/p/google-api-ruby-client/source/browse?repo=samples).
+See the full list of [samples on Github](https://github.com/google/google-api-ruby-client-samples).
 
 
 ## Support

data/Rakefile

@@ -11,7 +11,7 @@ PKG_DISPLAY_NAME   = 'Google API Client'
 PKG_NAME           = PKG_DISPLAY_NAME.downcase.gsub(/\s/, '-')
 PKG_VERSION        = Google::APIClient::VERSION::STRING
 PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
-PKG_HOMEPAGE       = 'http://code.google.com/p/google-api-ruby-client/'
+PKG_HOMEPAGE       = 'https://github.com/google/google-api-ruby-client'
 
 RELEASE_NAME       = "REL #{PKG_VERSION}"
 

data/lib/google/api_client.rb

@@ -17,6 +17,7 @@ require 'faraday'
 require 'multi_json'
 require 'compat/multi_json'
 require 'stringio'
+require 'retriable'
 
 require 'google/api_client/version'
 require 'google/api_client/logging'
@@ -107,6 +108,7 @@ module Google
       self.auto_refresh_token = options.fetch(:auto_refresh_token) { true }
       self.key = options[:key]
       self.user_ip = options[:user_ip]
+      self.retries = options.fetch(:retries) { 0 }
       @discovery_uris = {}
       @discovery_documents = {}
       @discovered_apis = {}
@@ -230,6 +232,13 @@ module Google
     #   The base path. Should almost always be '/discovery/v1'.
     attr_accessor :discovery_path
 
+    ##
+    # Number of times to retry on recoverable errors
+    # 
+    # @return [FixNum]
+    #  Number of retries
+    attr_accessor :retries
+
     ##
     # Returns the URI for the directory document.
     #
@@ -424,6 +433,8 @@ module Google
     # Verifies an ID token against a server certificate. Used to ensure that
     # an ID token supplied by an untrusted client-side mechanism is valid.
     # Raises an error if the token is invalid or missing.
+    # 
+    # @deprecated Use the google-id-token gem for verifying JWTs
     def verify_id_token!
       require 'jwt'
       require 'openssl'
@@ -533,6 +544,8 @@ module Google
     #       authenticated, `false` otherwise.
     #     - (TrueClass, FalseClass) :gzip (default: true) - 
     #       `true` if gzip enabled, `false` otherwise.
+    #     - (FixNum) :retries -
+    #       # of times to retry on recoverable errors
     #
     # @return [Google::APIClient::Result] The result from the API, nil if batch.
     #
@@ -547,7 +560,7 @@ module Google
     #   )
     #
     # @see Google::APIClient#generate_request
-    def execute(*params)
+    def execute!(*params)
       if params.first.kind_of?(Google::APIClient::Request)
         request = params.shift
         options = params.shift || {}
@@ -572,53 +585,60 @@ module Google
       
       request.headers['User-Agent'] ||= '' + self.user_agent unless self.user_agent.nil?
       request.headers['Accept-Encoding'] ||= 'gzip' unless options[:gzip] == false
+      request.headers['Content-Type'] ||= ''
       request.parameters['key'] ||= self.key unless self.key.nil?
       request.parameters['userIp'] ||= self.user_ip unless self.user_ip.nil?
 
       connection = options[:connection] || self.connection
       request.authorization = options[:authorization] || self.authorization unless options[:authenticated] == false
-
-      result = request.send(connection)
-      if result.status == 401 && request.authorization.respond_to?(:refresh_token) && auto_refresh_token
-        begin
-          logger.debug("Attempting refresh of access token & retry of request")
-          request.authorization.fetch_access_token!
-          result = request.send(connection, true)
-        rescue Signet::AuthorizationError
-           # Ignore since we want the original error
+      tries = 1 + (options[:retries] || self.retries)
+      Retriable.retriable :tries => tries, 
+                          :on => [TransmissionError], 
+                          :interval => lambda {|attempts| (2 ** attempts) + rand} do
+        result = request.send(connection, true)
+
+        case result.status
+          when 200...300
+            result
+          when 301, 302, 303, 307
+            request = generate_request(request.to_hash.merge({
+              :uri => result.headers['location'],
+              :api_method => nil
+            }))
+            raise RedirectError.new(result.headers['location'], result)
+          when 400...500
+            if result.status == 401 && request.authorization.respond_to?(:refresh_token) && auto_refresh_token
+              begin
+                logger.debug("Attempting refresh of access token & retry of request")
+                request.authorization.fetch_access_token!
+              rescue Signet::AuthorizationError
+                 # Ignore since we want the original error
+              end
+            end
+            raise ClientError.new(result.error_message || "A client error has occurred", result)
+          when 500...600
+            raise ServerError.new(result.error_message || "A server error has occurred", result)
+          else
+            raise TransmissionError.new(result.error_message || "A transmission error has occurred", result)
         end
       end
-      
-      return result
     end
 
     ##
-    # Same as Google::APIClient#execute, but raises an exception if there was
-    # an error.
+    # Same as Google::APIClient#execute!, but does not raise an exception for
+    # normal API errros.
     #
     # @see Google::APIClient#execute
-    def execute!(*params)
-      result = self.execute(*params)
-      if result.error?
-        error_message = result.error_message
-        case result.response.status
-          when 400...500
-            exception_type = ClientError
-            error_message ||= "A client error has occurred."
-          when 500...600
-            exception_type = ServerError
-            error_message ||= "A server error has occurred."
-          else
-            exception_type = TransmissionError
-            error_message ||= "A transmission error has occurred."
-        end
-        raise exception_type, error_message
+    def execute(*params)
+      begin
+        return self.execute!(*params)
+      rescue TransmissionError => e
+        return e.result
       end
-      return result
     end
-    
+
     protected
-    
+
     ##
     # Resolves a URI template against the client's configured base.
     #
@@ -646,6 +666,7 @@ module Google
     end
     
   end
+
 end
 
 require 'google/api_client/version'

data/lib/google/api_client/errors.rb

@@ -19,6 +19,17 @@ module Google
     # An error which is raised when there is an unexpected response or other
     # transport error that prevents an operation from succeeding.
     class TransmissionError < StandardError
+      attr_reader :result
+      def initialize(message = nil, result = nil)
+        super(message)
+        @result = result
+      end
+    end
+
+    ##
+    # An exception that is raised if a redirect is required
+    #
+    class RedirectError < TransmissionError
     end
 
     ##

data/lib/google/api_client/request.rb

@@ -287,6 +287,7 @@ module Google
             raise ArgumentError, "Can not specify body & body object for simple uploads"
           end
           self.headers['Content-Type'] ||= self.media.content_type
+          self.headers['Content-Length'] ||= self.media.length.to_s
           self.body = self.media
         when "multipart"
           unless options[:body_object]

data/lib/google/api_client/service.rb

@@ -0,0 +1,233 @@
+# Copyright 2013 Google Inc.
+#
+# 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 'google/api_client'
+require 'google/api_client/service/stub_generator'
+require 'google/api_client/service/resource'
+require 'google/api_client/service/request'
+require 'google/api_client/service/result'
+require 'google/api_client/service/batch'
+require 'google/api_client/service/simple_file_store'
+
+module Google
+  class APIClient
+
+    ##
+    # Experimental new programming interface at the API level.
+    # Hides Google::APIClient. Designed to be easier to use, with less code.
+    #
+    # @example
+    #   calendar = Google::APIClient::Service.new('calendar', 'v3')
+    #   result = calendar.events.list('calendarId' => 'primary').execute()
+    class Service
+      include Google::APIClient::Service::StubGenerator
+      extend Forwardable
+
+      DEFAULT_CACHE_FILE = 'discovery.cache'
+
+      # Cache for discovered APIs.
+      @@discovered = {}
+
+      ##
+      # Creates a new Service.
+      #
+      # @param [String, Symbol] api_name
+      #   The name of the API this service will access.
+      # @param [String, Symbol] api_version
+      #   The version of the API this service will access.
+      # @param [Hash] options
+      #   The configuration parameters for the service.
+      # @option options [Symbol, #generate_authenticated_request] :authorization
+      #   (:oauth_1)
+      #   The authorization mechanism used by the client.  The following
+      #   mechanisms are supported out-of-the-box:
+      #   <ul>
+      #     <li><code>:two_legged_oauth_1</code></li>
+      #     <li><code>:oauth_1</code></li>
+      #     <li><code>:oauth_2</code></li>
+      #   </ul>
+      # @option options [Boolean] :auto_refresh_token (true)
+      #   The setting that controls whether or not the api client attempts to
+      #   refresh authorization when a 401 is hit in #execute. If the token does
+      #   not support it, this option is ignored.
+      # @option options [String] :application_name
+      #   The name of the application using the client.
+      # @option options [String] :application_version
+      #   The version number of the application using the client.
+      # @option options [String] :host ("www.googleapis.com")
+      #   The API hostname used by the client. This rarely needs to be changed.
+      # @option options [String] :port (443)
+      #   The port number used by the client. This rarely needs to be changed.
+      # @option options [String] :discovery_path ("/discovery/v1")
+      #   The discovery base path. This rarely needs to be changed.
+      # @option options [String] :ca_file
+      #   Optional set of root certificates to use when validating SSL connections.
+      #   By default, a bundled set of trusted roots will be used.
+      # @option options [#generate_authenticated_request] :authorization
+      #   The authorization mechanism for requests. Used only if
+      #   `:authenticated` is `true`.
+      # @option options [TrueClass, FalseClass] :authenticated (default: true)
+      #   `true` if requests must be signed or somehow
+      #   authenticated, `false` otherwise.
+      # @option options [TrueClass, FalseClass] :gzip (default: true)
+      #   `true` if gzip enabled, `false` otherwise.
+      # @option options [Faraday::Connection] :connection
+      #   A custom connection to be used for all requests.
+      # @option options [ActiveSupport::Cache::Store, :default] :discovery_cache
+      #   A cache store to place the discovery documents for loaded APIs.
+      #   Avoids unnecessary roundtrips to the discovery service.
+      #   :default loads the default local file cache store.
+      def initialize(api_name, api_version, options = {})
+        @api_name = api_name.to_s
+        if api_version.nil?
+          raise ArgumentError,
+            "API version must be set"
+        end
+        @api_version = api_version.to_s
+        if options && !options.respond_to?(:to_hash)
+          raise ArgumentError,
+            "expected options Hash, got #{options.class}"
+        end
+
+        params = {}
+        [:application_name, :application_version, :authorization, :host, :port,
+         :discovery_path, :auto_refresh_token, :key, :user_ip,
+         :ca_file].each do |option|
+          if options.include? option
+            params[option] = options[option]
+          end
+        end
+
+        @client = Google::APIClient.new(params)
+
+        @connection = options[:connection] || @client.connection
+
+        @options = options
+
+        # Initialize cache store. Default to SimpleFileStore if :cache_store
+        # is not provided and we have write permissions.
+        if options.include? :cache_store
+          @cache_store = options[:cache_store]
+        else
+          cache_exists = File.exist?(DEFAULT_CACHE_FILE)
+          if (cache_exists && File.writable?(DEFAULT_CACHE_FILE)) ||
+             (!cache_exists && File.writable?(Dir.pwd))
+            @cache_store = Google::APIClient::Service::SimpleFileStore.new(
+              DEFAULT_CACHE_FILE)
+          end
+        end
+
+        # Attempt to read API definition from memory cache.
+        # Not thread-safe, but the worst that can happen is a cache miss.
+        unless @api = @@discovered[[api_name, api_version]]
+          # Attempt to read API definition from cache store, if there is one.
+          # If there's a miss or no cache store, call discovery service.
+          if !@cache_store.nil?
+            @api = @cache_store.fetch("%s/%s" % [api_name, api_version]) do
+              @client.discovered_api(api_name, api_version)
+            end
+          else
+            @api = @client.discovered_api(api_name, api_version)
+          end
+          @@discovered[[api_name, api_version]] = @api
+        end
+
+        generate_call_stubs(self, @api)
+      end
+
+      ##
+      # Returns the authorization mechanism used by the service.
+      #
+      # @return [#generate_authenticated_request] The authorization mechanism.
+      def_delegators :@client, :authorization, :authorization=
+
+      ##
+      # The setting that controls whether or not the service attempts to
+      # refresh authorization when a 401 is hit during an API call.
+      #
+      # @return [Boolean]
+      def_delegators :@client, :auto_refresh_token, :auto_refresh_token=
+
+      ##
+      # The application's API key issued by the API console.
+      #
+      # @return [String] The API key.
+      def_delegators :@client, :key, :key=
+
+      ##
+      # The Faraday/HTTP connection used by this service.
+      #
+      # @return [Faraday::Connection]
+      attr_accessor :connection
+
+      ##
+      # The cache store used for storing discovery documents.
+      #
+      # @return [ActiveSupport::Cache::Store,
+      #          Google::APIClient::Service::SimpleFileStore,
+      #          nil]
+      attr_reader :cache_store
+
+      ##
+      # Prepares a Google::APIClient::BatchRequest object to make batched calls.
+      # @param [Array] calls
+      #   Optional array of Google::APIClient::Service::Request to initialize
+      #   the batch request with.
+      # @param [Proc] block
+      #   Callback for every call's response. Won't be called if a call defined
+      #   a callback of its own.
+      #
+      # @yield [Google::APIClient::Service::Result]
+      #   block to be called when result ready
+      def batch(calls = nil, &block)
+        Google::APIClient::Service::BatchRequest.new(self, calls, &block)
+      end
+
+      ##
+      # Executes an API request.
+      # Do not call directly; this method is only used by Request objects when
+      # executing.
+      #
+      # @param [Google::APIClient::Service::Request,
+      #         Google::APIClient::Service::BatchCall] request
+      #   The request to be executed.
+      def execute(request)
+        if request.instance_of? Google::APIClient::Service::Request
+          params = {:api_method => request.method,
+            :parameters => request.parameters,
+            :connection => @connection}
+          if request.respond_to? :body
+            if request.body.respond_to? :to_hash
+              params[:body_object] = request.body
+            else
+              params[:body] = request.body
+            end
+          end
+          if request.respond_to? :media
+            params[:media] = request.media
+          end
+          [:authenticated, :gzip].each do |option|
+            if @options.include? option
+              params[option] = @options[option]
+            end
+          end
+          result = @client.execute(params)
+          return Google::APIClient::Service::Result.new(request, result)
+        elsif request.instance_of? Google::APIClient::Service::BatchRequest
+          @client.execute(request.base_batch)
+        end
+      end
+    end
+  end
+end