google-ads-common 0.4.0 → 0.5.0

data/ChangeLog

@@ -1,3 +1,8 @@
+0.5.0:
+  - Now support Savon 0.9.6.
+  - No longer depend on Soap4r.
+  - Support for OAuth authentication method.
+
 0.4.0:
   - Extracted soap4r specific code from main path.
   - APIs with Savon backend are now ruby1.9 - compatible.

data/README

@@ -17,8 +17,7 @@ Install it using the gem install command.
    $ gem install --local google-ads-common-VERSION.gem
 
 The following gem libraries are required:
- - soap4r v1.5.8 (only for soap4r-based libraries);
- - savon v0.9.1 or greater (for savon-enabled libraries);
+ - savon v0.9.6;
  - httpi v0.9.2 or greater;
  - httpclient v2.1.6 or greater.
 
@@ -33,8 +32,6 @@ The following gem libraries are required:
     build-time tasks for client libraries (not for google-ads-common).
   - +savon_headers/+: Contains classes that handle header injection into savon
     requests.
-  - +soap4r_headers/+: Contains classes that handle header injection into soap4r
-    requests.
 - +test/+: Contains the unit tests for the library.
 
 == 2 - Commands

data/Rakefile

@@ -47,10 +47,10 @@ spec = Gem::Specification.new do |s|
   s.test_files = tests
   s.has_rdoc = true
   s.extra_rdoc_files = docs
-  s.add_dependency('savon', '~> 0.9.1')
-  s.add_dependency('soap4r', '= 1.5.8')
+  s.add_dependency('savon', '= 0.9.6')
   s.add_dependency('httpclient', '>= 2.1.6')
   s.add_dependency('httpi', '~> 0.9.2')
+  s.add_dependency('oauth', '~> 0.4.5')
 end
 
 desc 'Default target - build'

data/lib/ads_common/api.rb

@@ -21,9 +21,10 @@
 
 require 'logger'
 
+require 'ads_common/config'
 require 'ads_common/errors'
-require 'ads_common/auth/base_handler'
 require 'ads_common/auth/client_login_handler'
+require 'ads_common/auth/oauth_handler'
 
 module AdsCommon
   class Api
@@ -46,17 +47,18 @@ module AdsCommon
           create_default_logger() : provided_logger
 
       # Check for valid environment.
-      env_string = config.read('service.environment')
+      env_string = @config.read('service.environment')
       environment = (env_string.nil?) ? api_config.default_environment :
           env_string.to_s.upcase.to_sym
       if api_config.environments.include?(environment)
-        config.set('service.environment', environment)
+        @config.set('service.environment', environment)
       else
         raise AdsCommon::Errors::Error,
             "Unknown or unspecified environment: \"%s\"" % env_string
       end
 
-      @wrappers = Hash.new
+      # Service wrappers.
+      @wrappers = {}
     end
 
     # Sets the logger to use.
@@ -112,6 +114,43 @@ module AdsCommon
       return wrapper
     end
 
+    # Authorize with specified authentication method.
+    #
+    # Args:
+    #  - parameters - hash of credentials to add to configuration
+    #  - block - code block to handle auth login url
+    #
+    # Returns:
+    #  - Auth token for the method
+    #
+    # Throws:
+    #  - AdsCommon::Errors::AuthError or derived if authetication error has
+    #    occured
+    #
+    def authorize(parameters = {}, &block)
+      parameters.each_pair do |key, value|
+        @credential_handler.set_credential(key, value)
+      end
+      @auth_handler = get_auth_handler(@config.read('service.environment'))
+
+      # Token might still be valid, if not ask for a new one.
+      token = @auth_handler.get_token() ||
+        begin
+          @auth_handler.get_token(@credential_handler.credentials)
+        rescue AdsCommon::Errors::OAuthVerificationRequired => e
+          verification_code = (block_given?) ? yield(e.oauth_url) : nil
+          # Retry with verification code if one provided.
+          if verification_code
+            @credential_handler.set_credential(
+                :oauth_verification_code, verification_code)
+            retry
+          else
+            raise e
+          end
+        end
+      return token
+    end
+
     private
 
     # Retrieve the SOAP header handlers to plug into the drivers. Needs to
@@ -132,33 +171,77 @@ module AdsCommon
       raise NotImplementedError, 'soap_header_handlers not overriden.'
     end
 
-    # Auxiliary method to create an authentication handler. Needs to be
-    # implemented on the specific API because of the different nesting models
-    # used in different APIs and API versions.
+    # Auxiliary method to get an authentication handler. Creates a new one if
+    # the handler has not been initialized yet.
     #
     # Args:
     # - environment: the current working environment (production, sandbox, etc.)
-    # - version: intended API version
+    # - version: intended API version, must be a symbol, optional
+    #
+    # Returns:
+    # - auth handler
+    #
+    def get_auth_handler(environment, version = nil)
+      @auth_handler ||= create_auth_handler(environment, version)
+      return @auth_handler
+    end
+
+    # Auxiliary method to create an authentication handler.
+    #
+    # Args:
+    # - environment: the current working environment (production, sandbox, etc.)
+    # - version: intended API version, must be a symbol, optional
     #
     # Returns:
     # - auth handler
     #
-    def create_auth_handler(environment, version)
-      raise NotImplementedError, 'create_auth_handler not overriden.'
+    def create_auth_handler(environment, version = nil)
+      auth_method_str = @config.read('authentication.method', 'ClientLogin')
+      auth_method = auth_method_str.to_s.upcase.to_sym
+      return case auth_method
+        when :CLIENTLOGIN
+          auth_server = api_config.auth_server(environment)
+          AdsCommon::Auth::ClientLoginHandler.new(config, auth_server,
+              api_config.headers_config[:LOGIN_SERVICE_NAME])
+        when :OAUTH
+          scope = api_config.environment_config()[environment][:oauth_scope]
+          AdsCommon::Auth::OAuthHandler.new(config, scope)
+        else
+          raise AdsCommon::Errors::Error,
+              "Unknown authentication method '%s'." % auth_method_str
+        end
     end
 
-    # Handle loading of a single service wrapper. Needs to be implemented on
-    # specific API level.
+    # Handle loading of a single service.
+    # Creates the driver, sets up handlers, declares the appropriate wrapper
+    # class and creates an instance of it.
     #
     # Args:
-    # - version: intended API version. Must be a symbol.
-    # - service: name for the intended service. Must be a symbol.
+    # - version: intended API version, must be a symbol
+    # - service: name for the intended service
     #
     # Returns:
-    # - a wrapper generated for the service.
+    # - a simplified wrapper generated for the driver
     #
     def prepare_wrapper(version, service)
-      raise NotImplementedError, 'prepare_wrapper not overriden.'
+      environment = config.read('service.environment')
+      api_config.do_require(version, service)
+      endpoint = api_config.endpoint(environment, version, service)
+      interface_class_name = api_config.interface_name(version, service)
+      endpoint_url = endpoint.nil? ? nil : endpoint + service.to_s
+      wrapper = class_for_path(interface_class_name).new(self, endpoint_url)
+
+      auth_handler = get_auth_handler(environment, version)
+      header_list =
+          auth_handler.header_list(@credential_handler.credentials(version))
+
+      soap_handlers = soap_header_handlers(auth_handler, header_list,
+                                           version, wrapper.namespace)
+      soap_handlers.each do |handler|
+        wrapper.headerhandler << handler
+      end
+
+      return wrapper
     end
 
     # Auxiliary method to create a default Logger.
@@ -196,5 +279,12 @@ module AdsCommon
       end
       return result
     end
+
+    # Converts complete class path into class object.
+    def class_for_path(path)
+      path.split('::').inject(Kernel) do |scope, const_name|
+        scope.const_get(const_name)
+      end
+    end
   end
 end

data/lib/ads_common/api_config.rb

@@ -26,7 +26,7 @@ module AdsCommon
   # Contains helper methods for loading and managing the available services.
   # This module is meant to be imported into API-specific modules.
   module ApiConfig
-    ADS_COMMON_VERSION = '0.4.0'
+    ADS_COMMON_VERSION = '0.5.0'
 
     # Get the available API versions.
     #
@@ -156,8 +156,7 @@ module AdsCommon
     def auth_server(environment)
       auth_server_url =
           ENV['ADSAPI_AUTH_URL'] ||
-          auth_server_config[environment] ||
-          auth_server_config[default_environment()]
+          auth_server_config[environment]
       return auth_server_url
     end
 

data/lib/ads_common/auth/base_handler.rb

@@ -2,7 +2,7 @@
 #
 # Authors:: api.sgomes@gmail.com (Sérgio Gomes)
 #
-# Copyright:: Copyright 2010, Google Inc. All Rights Reserved.
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
 # License:: Licensed under the Apache License, Version 2.0 (the "License");
 #           you may not use this file except in compliance with the License.
@@ -24,6 +24,13 @@
 module AdsCommon
   module Auth
     class BaseHandler
+      # Default initializer.
+      def initialize(config)
+        @config = config
+        @logger = @config.read('library.logger')
+        @token = nil
+      end
+
       # Callback to be used by CredentialHandlers to notify the auth handler of
       # a change in one of the credentials. Useful for e.g. invalidating a
       # token. The generic method does nothing.
@@ -40,13 +47,25 @@ module AdsCommon
       # This method returns the set of fields to be included in the header.
       # The generic method simply returns everything passed to it.
       def header_list(credentials)
-        return credentials.keys
+        return credentials.keys.dup()
       end
 
       # This method returns the key value pairs to be included in the header.
       # The generic method simply returns everything passed to it.
       def headers(credentials)
-        return credentials
+        return credentials.dup()
+      end
+
+      # Returns authorization token of some kind. Attempts to create a new one
+      # if the token has not yet been created and credentials present.
+      def get_token(credentials = nil)
+        @token = create_token(credentials) if @token.nil? and credentials
+        return @token
+      end
+
+      # Creates authorization token. Needs to be overriden.
+      def create_token(credentials)
+        raise NotImplementedError, 'create_token not overriden.'
       end
     end
   end

data/lib/ads_common/auth/client_login_handler.rb

@@ -1,7 +1,6 @@
 #!/usr/bin/ruby
 #
-# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
-#           api.dklimkin@gmail.com (Danial Klimkin)
+# Authors:: api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
@@ -32,15 +31,13 @@ module AdsCommon
 
     # Credentials class to handle ClientLogin authentication.
     class ClientLoginHandler < AdsCommon::Auth::BaseHandler
-
       ACCOUNT_TYPE = 'GOOGLE'
       AUTH_PATH = '/accounts/ClientLogin'
       IGNORED_FIELDS = [:email, :password, :auth_token]
 
       # Initializes the ClientLoginHandler with all the necessary details.
       def initialize(config, server, service_name)
-        @token = config.read('authentication.auth_token')
-        @config = config
+        super(config)
         @server = server
         @service_name = service_name
       end
@@ -48,10 +45,7 @@ module AdsCommon
       # Invalidates the stored token if the email, password or provided auth
       # token have changed.
       def property_changed(prop, value)
-        case prop
-        when :auth_token
-          @token = config.read('authentication.auth_token')
-        when :email, :password
+        if [:auth_token, :email, :password].include?(prop)
           @token = nil
         end
       end
@@ -65,23 +59,20 @@ module AdsCommon
 
       # Returns all of the fields that this auth handler will fill.
       def header_list(credentials)
-        result = []
-        result << :authToken
-        credentials.each do |p, v|
-          result << p unless IGNORED_FIELDS.include?(p)
+        result = credentials.keys.map.reject do |field|
+          IGNORED_FIELDS.include?(field)
         end
+        result << :authToken
         return result
       end
 
       # Returns all of the credentials received from the CredentialHandler,
-      # except for email and password.
+      # except for ignored fields.
       def headers(credentials)
-        @token = generate_token(credentials) if @token == nil
-        result = {}
-        result[:authToken] = @token
-        credentials.each do |p, v|
-          result[p] = v unless IGNORED_FIELDS.include?(p)
+        result = credentials.reject do |field, value|
+          IGNORED_FIELDS.include?(field)
         end
+        result[:authToken] = get_token(credentials)
         return result
       end
 
@@ -93,9 +84,8 @@ module AdsCommon
       # - credentials: a hash with the credentials for the account being
       #   accessed
       #
-      #
       # Raises:
-      # AdsCommon::Errors::AuthError if validation fails.
+      # - AdsCommon::Errors::AuthError if validation fails
       #
       def validate_credentials(credentials)
         if credentials.nil?
@@ -114,7 +104,7 @@ module AdsCommon
         end
       end
 
-      # Auxiliary method to generate an authentication token for logging via
+      # Auxiliary method to generate an authentication token for login in via
       # the ClientLogin API.
       #
       # Args:
@@ -122,11 +112,18 @@ module AdsCommon
       #   accessed
       #
       # Returns:
-      # The auth token for the account (as a string).
+      # - The auth token for the account (as a string)
       #
       # Raises:
-      # AdsCommon::Errors::AuthError if authentication fails.
+      # - AdsCommon::Errors::AuthError if authentication fails
       #
+      def create_token(credentials)
+        token = @config.read('authentication.auth_token') ||
+            generate_token(credentials)
+        return token
+      end
+
+      # Generates new client login token based on credentials.
       def generate_token(credentials)
         validate_credentials(credentials)
 
@@ -147,25 +144,23 @@ module AdsCommon
         else
           error_message = "Login failed for email %s: HTTP code %d." %
               [credentials[:email], response.code]
-          if results.include?(:Error)
-            error_message += " Error: %s." % results[:Error]
-          else
-            error_message += " Raw error: %s." % response.body
-          end
+          error_str = results[:Error] || response.body
+          error_message += " Error: %s." % error_str if error_str
           if results.include?(:Info)
             error_message += " Info: %s." % results[:Info]
           end
-          raise AdsCommon::Errors::AuthError, error_message
+          raise AdsCommon::Errors::AuthError.new(error_message, error_str,
+              results[:Info])
         end
       end
 
       # Extracts key-value pairs from ClientLogin server response.
       #
       # Args:
-      # - text: server response string.
+      # - text: server response string
       #
       # Returns:
-      #   Hash of key-value pairs.
+      #   Hash of key-value pairs
       #
       def parse_token_text(text)
         result = {}

data/lib/ads_common/auth/oauth_handler.rb

@@ -0,0 +1,260 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+#
+# License:: 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.
+#
+# This module manages OAuth authentication.
+
+require 'oauth'
+
+require 'ads_common/auth/base_handler'
+require 'ads_common/errors'
+
+module AdsCommon
+  module Auth
+
+    # Credentials class to handle OAuth authentication.
+    class OAuthHandler < AdsCommon::Auth::BaseHandler
+      IGNORED_FIELDS = [
+          :email, :password, :auth_token,
+          :oauth_verification_code, :oauth_consumer_secret, :oauth_consumer_key
+      ]
+
+      OAUTH_CONFIG = {
+          :site => "https://www.google.com",
+          :request_token_path => "/accounts/OAuthGetRequestToken",
+          :access_token_path => "/accounts/OAuthGetAccessToken",
+          :authorize_path => "/accounts/OAuthAuthorizeToken"
+      }
+
+      DEFAULT_CALLBACK = 'oob'
+      DEFAULT_METHOD = 'HMAC-SHA1'
+
+      # Initializes the OAuthHandler with all the necessary details.
+      #
+      # Args:
+      # - config: Config object with library configuration
+      # - scope: OAuth authorization scope
+      #
+      def initialize(config, scope)
+        super(config)
+        @scope = scope
+      end
+
+      def handle_error(error)
+        # TODO: Add support.
+        raise error
+      end
+
+      # Returns all of the fields that this auth handler will fill.
+      #
+      # Args:
+      # - credentials: request credentials
+      #
+      # Returns:
+      # - array with header names
+      #
+      def header_list(credentials)
+        result = credentials.keys.map.reject do |field|
+          IGNORED_FIELDS.include?(field)
+        end
+        result << :access_token
+        return result
+      end
+
+      # Returns all of the credentials received from the CredentialHandler,
+      # except for ignored fields.
+      #
+      # Args:
+      # - credentials: request credentials
+      #
+      # Returns:
+      # - hash with header names and values
+      #
+      def headers(credentials)
+        result = credentials.reject do |field, value|
+          IGNORED_FIELDS.include?(field)
+        end
+        result[:access_token] = get_token(credentials)
+        return result
+      end
+
+      # Returns OAuth-specific Consumer object.
+      def get_oauth_consumer()
+        return @consumer
+      end
+
+      private
+
+      # Auxiliary method to validate the credentials for token generation.
+      #
+      # Args:
+      # - credentials: a hash with the credentials for the account being
+      #   accessed
+      #
+      # Raises:
+      # - AdsCommon::Errors::AuthError if validation fails
+      #
+      def validate_credentials(credentials)
+        if credentials.nil?
+          raise AdsCommon::Errors::AuthError, 'No credentials supplied.'
+        end
+
+        if credentials[:oauth_consumer_key].nil?
+          raise AdsCommon::Errors::AuthError,
+              'Consumer key not included in credentials.'
+        end
+
+        if credentials[:oauth_consumer_secret].nil?
+          raise AdsCommon::Errors::AuthError,
+              'Consumer secret not included in credentials.'
+        end
+      end
+
+      # Auxiliary method to generate an authentication token for logging via
+      # the OAuth API.
+      #
+      # Args:
+      # - credentials: a hash with the credentials for the account being
+      #   accessed
+      #
+      # Returns:
+      # - The auth token for the account (as an AccessToken)
+      #
+      # Raises:
+      # - AdsCommon::Errors::AuthError if authentication fails
+      # - AdsCommon::Errors::OAuthVerificationRequired if OAuth verification
+      #   code required
+      #
+      def create_token(credentials)
+        validate_credentials(credentials)
+        if @consumer.nil?
+          oauth_config = OAUTH_CONFIG.merge({:scope => @scope})
+          @consumer = OAuth::Consumer.new(credentials[:oauth_consumer_key],
+              credentials[:oauth_consumer_secret], oauth_config)
+        end
+        return create_token_from_credentials(credentials) ||
+            generate_access_token(credentials)
+      end
+
+      # Creates access token based on data from credentials.
+      #
+      # Args:
+      # - credentials: a hash with the credentials for the account being
+      #   accessed
+      #
+      # Returns:
+      # - The auth token for the account (as an AccessToken)
+      #
+      def create_token_from_credentials(credentials)
+        access_token = nil
+
+        token = credentials[:oauth_token]
+        if !token.nil? and !token.empty?
+          method = credentials[:oauth_method] || DEFAULT_METHOD
+          access_token = case method
+            when 'RSA-SHA1'
+              OAuth::AccessToken.from_hash(@consumer, {:oauth_token => token})
+            when 'HMAC-SHA1'
+              token_secret = credentials[:oauth_token_secret]
+              if token_secret.nil? or token_secret.empty?
+                @logger.warn(("The 'token' specified for method %s but " +
+                    "'token secret' is not available, ignoring token") % method)
+                nil
+              else
+                OAuth::AccessToken.from_hash(@consumer, {
+                    :oauth_token => token, :oauth_token_secret => token_secret})
+              end
+          end
+        end
+        return access_token
+      end
+
+      # Generates new request tokens and authorizes it to get access token.
+      #
+      # Args:
+      # - credentials: a hash with the credentials for the account being
+      #   accessed
+      #
+      # Returns:
+      # - The auth token for the account (as an AccessToken)
+      #
+      def generate_access_token(credentials)
+        token = nil
+        callback = credentials[:oauth_callback] || DEFAULT_CALLBACK
+        begin
+          if @request_token.nil?
+            @request_token = @consumer.get_request_token(
+                {:oauth_callback => callback}, {:scope => @scope})
+            raise_oauth_verification_error(@request_token, callback)
+          end
+          verification_code = credentials[:oauth_verification_code]
+          if verification_code.nil? || verification_code.empty?
+            raise_oauth_verification_error(@request_token, callback)
+          else
+            token = @request_token.get_access_token(
+                {:oauth_verifier => verification_code})
+            @request_token = nil
+          end
+        rescue OAuth::Unauthorized => e
+          if @request_token
+            raise_oauth_verification_error(@request_token, callback)
+          else
+            raise AdsCommon::Errors::AuthError,
+                "Authorization error occured: %s" % e
+          end
+        end
+        return token
+      end
+
+      # Raises a OAuthVerificationRequired error with auth URL for given
+      # request token.
+      #
+      # Args:
+      # - request_token: an initialized OAuth request token
+      # - callback: OAuth callback URL
+      #
+      # Returns:
+      # - never returns
+      #
+      # Raises:
+      # - AdsCommon::Errors::OAuthVerificationRequired in all cases
+      #
+      def raise_oauth_verification_error(request_token, callback)
+        oauth_url = request_token.authorize_url({:oauth_callback => callback})
+        raise AdsCommon::Errors::OAuthVerificationRequired, oauth_url
+      end
+
+      # Extracts key-value pairs from OAuth server response.
+      #
+      # Args:
+      # - text: server response string
+      #
+      # Returns:
+      # - Hash of key-value pairs
+      #
+      def parse_token_text(text)
+        result = {}
+        text.split('&').each do |line|
+          key, value = line.split("=")
+          result[key.to_sym] = value
+        end
+        return result
+      end
+    end
+  end
+end