google-api-client 0.4.7 → 0.5.0

data/lib/google/api_client/auth/jwt_asserter.rb

@@ -0,0 +1,139 @@
+# Copyright 2010 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 'jwt'
+require 'signet/oauth_2/client'
+require 'delegate'
+
+module Google
+  class APIClient
+    ##
+    # Generates access tokens using the JWT assertion profile. Requires a
+    # service account & access to the private key.
+    #
+    # @example
+    #
+    #    client = Google::APIClient.new
+    #    key = Google::APIClient::PKCS12.load_key('client.p12', 'notasecret')
+    #    service_account = Google::APIClient::JWTAsserter(
+    #        '123456-abcdef@developer.gserviceaccount.com',
+    #        'https://www.googleapis.com/auth/prediction',
+    #        key)
+    #    client.authorization = service_account.authorize
+    #    client.execute(...)
+    #
+    # @see https://developers.google.com/accounts/docs/OAuth2ServiceAccount
+    class JWTAsserter
+      # @return [String] ID/email of the issuing party
+      attr_accessor :issuer
+      # @return [Fixnum] How long, in seconds, the assertion is valid for
+      attr_accessor :expiry
+      # @return [Fixnum] Seconds to expand the issued at/expiry window to account for clock skew
+      attr_accessor :skew
+      # @return [String] Scopes to authorize
+      attr_reader :scope
+      # @return [OpenSSL::PKey] key for signing assertions
+      attr_writer :key
+
+      ##
+      # Initializes the asserter for a service account.
+      #
+      # @param [String] issuer
+      #    Name/ID of the client issuing the assertion
+      # @param [String, Array] scope
+      #   Scopes to authorize. May be a space delimited string or array of strings
+      # @param [OpenSSL::PKey] key
+      #   RSA private key for signing assertions
+      def initialize(issuer, scope, key)
+        self.issuer = issuer
+        self.scope = scope
+        self.expiry = 60 # 1 min default 
+        self.skew = 60      
+        self.key = key
+      end
+
+      ##
+      # Set the scopes to authorize
+      #
+      # @param [String, Array] new_scope
+      #   Scopes to authorize. May be a space delimited string or array of strings
+      def scope=(new_scope)
+        case new_scope
+        when Array
+          @scope = new_scope.join(' ')
+        when String
+          @scope = new_scope
+        when nil
+          @scope = ''
+        else
+          raise TypeError, "Expected Array or String, got #{new_scope.class}"
+        end
+      end
+      
+      ##
+      # Builds & signs the assertion.
+      # 
+      # @param [String] person
+      #   Email address of a user, if requesting a token to act on their behalf
+      # @return [String] Encoded JWT
+      def to_jwt(person=nil)
+        now = Time.new        
+        assertion = {
+          "iss" => @issuer,
+          "scope" => self.scope,
+          "aud" => "https://accounts.google.com/o/oauth2/token",
+          "exp" => (now + expiry).to_i,
+          "iat" => (now - skew).to_i
+        }
+        assertion['prn'] = person unless person.nil?
+        return JWT.encode(assertion, @key, "RS256")
+      end
+
+      ##
+      # Request a new access token.
+      # 
+      # @param [String] person
+      #   Email address of a user, if requesting a token to act on their behalf
+      # @param [Hash] options
+      #   Pass through to Signet::OAuth2::Client.fetch_access_token
+      # @return [Signet::OAuth2::Client] Access token 
+      #
+      # @see Signet::OAuth2::Client.fetch_access_token
+      def authorize(person = nil, options={})
+        assertion = self.to_jwt(person)
+        authorization = Signet::OAuth2::Client.new(
+          :token_credential_uri => 'https://accounts.google.com/o/oauth2/token'
+        )
+        authorization.grant_type = 'urn:ietf:params:oauth:grant-type:jwt-bearer'
+        authorization.extension_parameters = { :assertion => assertion }
+        authorization.fetch_access_token!(options)
+        return JWTAuthorization.new(authorization, self, person)
+      end
+    end
+    
+    class JWTAuthorization < DelegateClass(Signet::OAuth2::Client)
+      def initialize(authorization, asserter, person = nil)
+        @asserter = asserter
+        @person = person
+        super(authorization)
+      end
+      
+      def fetch_access_token!(options={})
+        new_authorization = @asserter.authorize(@person, options)
+        __setobj__(new_authorization)
+        self
+      end
+    end
+  end
+end

data/lib/google/api_client/auth/pkcs12.rb

@@ -0,0 +1,48 @@
+# Copyright 2010 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.
+
+module Google
+  class APIClient
+    ##
+    # Helper for loading keys from the PKCS12 files downloaded when
+    # setting up service accounts at the APIs Console.
+    #
+    module PKCS12
+      ##
+      # Loads a key from PKCS12 file, assuming a single private key
+      # is present.
+      #
+      # @param [String] keyfile
+      #    Path of the PKCS12 file to load. If not a path to an actual file,
+      #    assumes the string is the content of the file itself. 
+      # @param [String] passphrase
+      #   Passphrase for unlocking the private key
+      #
+      # @return [OpenSSL::PKey] The private key for signing assertions.
+      def self.load_key(keyfile, passphrase)
+        begin
+          if File.exists?(keyfile)
+            content = File.read(keyfile)
+          else
+            content = keyfile
+          end  
+          pkcs12 = OpenSSL::PKCS12.new(content, passphrase)
+          return pkcs12.key
+        rescue OpenSSL::PKCS12::PKCS12Error
+          raise ArgumentError.new("Invalid keyfile or passphrase")
+        end
+      end
+    end
+  end
+end

data/lib/google/api_client/batch.rb

@@ -13,57 +13,91 @@
 # limitations under the License.
 
 require 'addressable/uri'
+require 'google/api_client/reference'
 require 'uuidtools'
 
 module Google
   class APIClient
 
+    ##
     # Helper class to contain a response to an individual batched call.
+    #
+    # @api private
     class BatchedCallResponse
+      # @return [String] UUID of the call
       attr_reader :call_id
-      attr_accessor :status, :headers, :body
+      # @return [Fixnum] HTTP status code
+      attr_accessor :status
+      # @return [Hash] HTTP response headers
+      attr_accessor :headers
+      # @return [String] HTTP response body
+      attr_accessor :body
 
+      ##
+      # Initialize the call response
+      # 
+      # @param [String] call_id
+      #   UUID of the original call
+      # @param [Fixnum] status
+      #   HTTP status
+      # @param [Hash] headers
+      #   HTTP response headers
+      # @param [#read, #to_str] body
+      #   Response body
       def initialize(call_id, status = nil, headers = nil, body = nil)
         @call_id, @status, @headers, @body = call_id, status, headers, body
       end
     end
-
-    ##
+    
     # Wraps multiple API calls into a single over-the-wire HTTP request.
-    class BatchRequest
-
+    #
+    # @example
+    #
+    #     client = Google::APIClient.new
+    #     urlshortener = client.discovered_api('urlshortener')
+    #     batch = Google::APIClient::BatchRequest.new do |result|
+    #        puts result.data
+    #     end
+    # 
+    #     batch.add(:api_method=>urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/foo' })
+    #     batch.add(:api_method=>urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/bar' })
+    #
+    #     client.execute(batch)
+    #
+    
+    class BatchRequest < Request
       BATCH_BOUNDARY = "-----------RubyApiBatchRequest".freeze
 
-      attr_accessor :options
-      attr_reader :calls, :callbacks
+      # @api private
+      # @return [Array<(String,Google::APIClient::Request,Proc)] List of API calls in the batch
+      attr_reader :calls
 
       ##
       # Creates a new batch request.
       #
       # @param [Hash] options
-      #   Set of options for this request, the only important one being
-      #   :connection, which specifies an HTTP connection to use.
+      #   Set of options for this request.
       # @param [Proc] block
       #   Callback for every call's response. Won't be called if a call defined
       #   a callback of its own.
       #
-      # @return [Google::APIClient::BatchRequest] The constructed object.
+      # @return [Google::APIClient::BatchRequest] 
+      #   The constructed object.
+      #
+      # @yield [Google::APIClient::Result]
+      #   block to be called when result ready
       def initialize(options = {}, &block)
-        # Request options, ignoring method and parameters.
-        @options = options
-        # Batched calls to be made, indexed by call ID.
-        @calls = {}
-        # Callbacks per batched call, indexed by call ID.
-        @callbacks = {}
-        # Order for the call IDs, since Ruby 1.8 hashes are unordered.
-        @order = []
-        # Global callback to be used for every call. If a specific callback
-        # has been defined for a request, this won't be called.
+        @calls = []
         @global_callback = block if block_given?
-        # The last auto generated ID.
         @last_auto_id = 0
-        # Base ID for the batch request.
-        @base_id = nil
+        
+        # TODO(sgomes): Use SecureRandom.uuid, drop UUIDTools when we drop 1.8
+        @base_id = UUIDTools::UUID.random_create.to_s
+
+        options[:uri] ||= 'https://www.googleapis.com/batch'
+        options[:http_method] ||= 'POST'
+
+        super options
       end
 
       ##
@@ -72,69 +106,84 @@ module Google
       # automatically be generated, avoiding collisions. If duplicate call IDs
       # are provided, an error will be thrown.
       #
-      # @param [Hash, Google::APIClient::Reference] call: the call to be added.
-      # @param [String] call_id: the ID to be used for this call. Must be unique
-      # @param [Proc] block: callback for this call's response.
+      # @param [Hash, Google::APIClient::Request] call 
+      #   the call to be added.
+      # @param [String] call_id
+      #   the ID to be used for this call. Must be unique
+      # @param [Proc] block
+      #   callback for this call's response.
+      #
+      # @return [Google::APIClient::BatchRequest]
+      #   the BatchRequest, for chaining
       #
-      # @return [Google::APIClient::BatchRequest] The BatchRequest, for chaining
+      # @yield [Google::APIClient::Result]
+      #   block to be called when result ready
       def add(call, call_id = nil, &block)
         unless call.kind_of?(Google::APIClient::Reference)
           call = Google::APIClient::Reference.new(call)
         end
-        if call_id.nil?
-          call_id = new_id
-        end
-        if @calls.include?(call_id)
+        call_id ||= new_id
+        if @calls.assoc(call_id)
           raise BatchError,
               'A call with this ID already exists: %s' % call_id
         end
-        @calls[call_id] = call
-        @order << call_id
-        if block_given?
-          @callbacks[call_id] = block
-        elsif @global_callback
-          @callbacks[call_id] = @global_callback
-        end
+        callback = block_given? ? block : @global_callback
+        @calls << [call_id, call, callback]        
         return self
       end
 
-      ##
-      # Convert this batch request into an HTTP request.
-      #
-      # @return [Array<String, String, Hash, String>]
-      #   An array consisting of, in order: HTTP method, request path, request
-      #   headers and request body.
-      def to_http_request
-        return ['POST', request_uri, request_headers, request_body]
-      end
-
       ##
       # Processes the HTTP response to the batch request, issuing callbacks.
       #
-      # @param [Faraday::Response] response: the HTTP response.
-      def process_response(response)
+      # @api private
+      #
+      # @param [Faraday::Response] response
+      #   the HTTP response.
+      def process_http_response(response)
         content_type = find_header('Content-Type', response.headers)
         boundary = /.*boundary=(.+)/.match(content_type)[1]
         parts = response.body.split(/--#{Regexp.escape(boundary)}/)
         parts = parts[1...-1]
         parts.each do |part|
           call_response = deserialize_call_response(part)
-          callback = @callbacks[call_response.call_id]
-          call = @calls[call_response.call_id]
-          result = Google::APIClient::Result.new(call, nil, call_response)
+          _, call, callback = @calls.assoc(call_response.call_id)
+          result = Google::APIClient::Result.new(call, call_response)
           callback.call(result) if callback
         end
+        Google::APIClient::Result.new(self, response)
       end
 
-      private
+      ##
+      # Return the request body for the BatchRequest's HTTP request.
+      #
+      # @api private
+      #
+      # @return [String]
+      #   the request body.
+      def to_http_request
+        if @calls.nil? || @calls.empty?
+          raise BatchError, 'Cannot make an empty batch request'
+        end
+        parts = @calls.map {|(call_id, call, callback)| serialize_call(call_id, call)}
+        build_multipart(parts, 'multipart/mixed', BATCH_BOUNDARY)
+        super
+      end
+      
+      
+      protected
 
       ##
       # Helper method to find a header from its name, regardless of case.
       #
-      # @param [String] name: The name of the header to find.
-      # @param [Hash] headers: The hash of headers and their values.
+      # @api private
+      #
+      # @param [String] name
+      #   the name of the header to find.
+      # @param [Hash] headers
+      #   the hash of headers and their values.
       #
-      # @return [String] The value of the desired header.
+      # @return [String] 
+      #   the value of the desired header.
       def find_header(name, headers)
         _, header = headers.detect do |h, v|
           h.downcase == name.downcase
@@ -145,40 +194,29 @@ module Google
       ##
       # Create a new call ID. Uses an auto-incrementing, conflict-avoiding ID.
       #
-      # @return [String] the new, unique ID.
+      # @api private
+      #
+      # @return [String] 
+      #  the new, unique ID.
       def new_id
         @last_auto_id += 1
-        while @calls.include?(@last_auto_id)
+        while @calls.assoc(@last_auto_id)
           @last_auto_id += 1
         end
         return @last_auto_id.to_s
       end
 
-      ##
-      # Convert an id to a Content-ID header value.
-      #
-      # @param [String] call_id: identifier of individual call.
-      #
-      # @return [String]
-      #   A Content-ID header with the call_id encoded into it. A UUID is
-      #   prepended to the value because Content-ID headers are supposed to be
-      #   universally unique.
-      def id_to_header(call_id)
-        if @base_id.nil?
-          # TODO(sgomes): Use SecureRandom.uuid, drop UUIDTools when we drop 1.8
-          @base_id = UUIDTools::UUID.random_create.to_s
-        end
-
-        return '<%s+%s>' % [@base_id, Addressable::URI.encode(call_id)]
-      end
-
       ##
       # Convert a Content-ID header value to an id. Presumes the Content-ID
       # header conforms to the format that id_to_header() returns.
       #
-      # @param [String] header: Content-ID header value.
+      # @api private
+      #
+      # @param [String] header
+      #   Content-ID header value.
       #
-      # @return [String] The extracted ID value.
+      # @return [String] 
+      #   The extracted ID value.
       def header_to_id(header)
         if !header.start_with?('<') || !header.end_with?('>') ||
             !header.include?('+')
@@ -189,36 +227,16 @@ module Google
         return Addressable::URI.unencode(call_id)
       end
 
-      ##
-      # Convert a single batched call into a string.
-      #
-      # @param [Google::APIClient::Reference] call: the call to serialize.
-      #
-      # @return [String] The request as a string in application/http format.
-      def serialize_call(call)
-        http_request = call.to_request
-        method = http_request.method.to_s.upcase
-        path = http_request.path.to_s
-        status_line = method + " " + path + " HTTP/1.1"
-        serialized_call = status_line
-        if http_request.headers
-          http_request.headers.each do |header, value|
-            serialized_call << "\r\n%s: %s" % [header, value]
-          end
-        end
-        if http_request.body
-          serialized_call << "\r\n\r\n"
-          serialized_call << http_request.body
-        end
-        return serialized_call
-      end
-
       ##
       # Auxiliary method to split the headers from the body in an HTTP response.
       #
-      # @param [String] response: the response to parse.
+      # @api private
       #
-      # @return [Array<Hash>, String] The headers and the body, separately.
+      # @param [String] response
+      #   the response to parse.
+      #
+      # @return [Array<Hash>, String] 
+      #   the headers and the body, separately.
       def split_headers_and_body(response)
         headers = {}
         payload = response.lstrip
@@ -239,10 +257,13 @@ module Google
       ##
       # Convert a single batched response into a BatchedCallResponse object.
       #
-      # @param [Google::APIClient::Reference] response:
+      # @api private
+      #
+      # @param [String] call_response
       #   the request to deserialize.
       #
-      # @return [BatchedCallResponse] The parsed and converted response.
+      # @return [Google::APIClient::BatchedCallResponse] 
+      #   the parsed and converted response.
       def deserialize_call_response(call_response)
         outer_headers, outer_body = split_headers_and_body(call_response)
         status_line, payload = outer_body.split("\n", 2)
@@ -255,42 +276,49 @@ module Google
       end
 
       ##
-      # Return the request headers for the BatchRequest's HTTP request.
+      # Serialize a single batched call for assembling the multipart message
       #
-      # @return [Hash] The HTTP headers.
-      def request_headers
-        return {
-          'Content-Type' => 'multipart/mixed; boundary=%s' % BATCH_BOUNDARY
-        }
-      end
-
-      ##
-      # Return the request path for the BatchRequest's HTTP request.
+      # @api private
       #
-      # @return [String] The request path.
-      def request_uri
-        if @calls.nil? || @calls.empty?
-          raise BatchError, 'Cannot make an empty batch request'
+      # @param [Google::APIClient::Request] call
+      #   the call to serialize.
+      #
+      # @return [Faraday::UploadIO] 
+      #   the serialized request
+      def serialize_call(call_id, call)
+        method, uri, headers, body = call.to_http_request
+        request = "#{method.to_s.upcase} #{Addressable::URI.parse(uri).path} HTTP/1.1"
+        headers.each do |header, value|
+          request << "\r\n%s: %s" % [header, value]
+        end
+        if body
+          # TODO - CompositeIO if body is a stream 
+          request << "\r\n\r\n"
+          if body.respond_to?(:read)
+            request << body.read
+          else
+            request << body.to_s
+          end
         end
-        # All APIs have the same batch path, so just get the first one.
-        return @calls.first[1].api_method.api.batch_path
+        Faraday::UploadIO.new(StringIO.new(request), 'application/http', 'ruby-api-request', 'Content-ID' => id_to_header(call_id))
       end
-
+      
       ##
-      # Return the request body for the BatchRequest's HTTP request.
+      # Convert an id to a Content-ID header value.
       #
-      # @return [String] The request body.
-      def request_body
-        body = ""
-        @order.each do |call_id|
-          body << "--" + BATCH_BOUNDARY + "\r\n"
-          body << "Content-Type: application/http\r\n"
-          body << "Content-ID: %s\r\n\r\n" % id_to_header(call_id)
-          body << serialize_call(@calls[call_id]) + "\r\n\r\n"
-        end
-        body << "--" + BATCH_BOUNDARY + "--"
-        return body
+      # @api private
+      #
+      # @param [String] call_id
+      #   identifier of individual call.
+      #
+      # @return [String]
+      #   A Content-ID header with the call_id encoded into it. A UUID is
+      #   prepended to the value because Content-ID headers are supposed to be
+      #   universally unique.
+      def id_to_header(call_id)
+        return '<%s+%s>' % [@base_id, Addressable::URI.encode(call_id)]
       end
+      
     end
   end
 end