sfdc 0.0.1 → 1.0.0

data/lib/sfdc/mash.rb

@@ -0,0 +1,65 @@
+require 'hashie/mash'
+
+module Sfdc
+  class Mash < Hashie::Mash
+
+    class << self
+
+      # Pass in an Array or Hash and it will be recursively converted into the
+      # appropriate Sfdc::Collection, Sfdc::SObject and
+      # Sfdc::Mash objects.
+      def build(val, client)
+        if val.is_a?(Array)
+          val.collect { |val| self.build(val, client) }
+        elsif val.is_a?(Hash)
+          self.klass(val).new(val, client)
+        else
+          val
+        end
+      end
+
+      # When passed a hash, it will determine what class is appropriate to
+      # represent the data.
+      def klass(val)
+        if val.has_key? 'records'
+          # When the hash has a records key, it should be considered a collection
+          # of sobject records.
+          Sfdc::Collection
+        elsif val.has_key? 'attributes'
+          if val['attributes']['type'] == 'Attachment'
+            Sfdc::Attachment
+          else
+            # When the hash contains an attributes key, it should be considered an
+            # sobject record
+            Sfdc::SObject
+          end
+        else
+          # Fallback to a standard Sfdc::Mash for everything else
+          Sfdc::Mash
+        end
+      end
+
+    end
+
+    def initialize(source_hash = nil, client = nil, default = nil, &blk)
+      @client = client
+      deep_update(source_hash) if source_hash
+      default ? super(default) : super(&blk)
+    end
+
+    def convert_value(val, duping=false)
+      case val
+      when self.class
+        val.dup
+      when ::Hash
+        val = val.dup if duping
+        self.class.klass(val).new(val, @client)
+      when Array
+        val.collect{ |e| convert_value(e) }
+      else
+        val
+      end
+    end
+
+  end
+end

data/lib/sfdc/middleware.rb

@@ -0,0 +1,29 @@
+module Sfdc
+  # Base class that all middleware can extend. Provides some convenient helper
+  # functions.
+  class Middleware < Faraday::Middleware
+    autoload :RaiseError,     'sfdc/middleware/raise_error'
+    autoload :Authentication, 'sfdc/middleware/authentication'
+    autoload :Authorization,  'sfdc/middleware/authorization'
+    autoload :InstanceURL,    'sfdc/middleware/instance_url'
+    autoload :Multipart,      'sfdc/middleware/multipart'
+    autoload :Mashify,        'sfdc/middleware/mashify'
+    autoload :Caching,        'sfdc/middleware/caching'
+    autoload :Logger,         'sfdc/middleware/logger'
+    autoload :Gzip,           'sfdc/middleware/gzip'
+
+    def initialize(app, client, options)
+      @app, @client, @options = app, client, options
+    end
+
+    # Internal: Proxy to the client.
+    def client
+      @client
+    end
+
+    # Internal: Proxy to the client's faraday connection.
+    def connection
+      client.send(:connection)
+    end
+  end
+end

data/lib/sfdc/middleware/authentication.rb

@@ -0,0 +1,63 @@
+module Sfdc
+  # Faraday middleware that allows for on the fly authentication of requests.
+  # When a request fails (a status of 401 is returned), the middleware
+  # will attempt to either reauthenticate (username and password) or refresh
+  # the oauth access token (if a refresh token is present).
+  class Middleware::Authentication < Sfdc::Middleware
+    autoload :Password, 'sfdc/middleware/authentication/password'
+    autoload :Token,    'sfdc/middleware/authentication/token'
+
+    # Rescue from 401's, authenticate then raise the error again so the client
+    # can reissue the request.
+    def call(env)
+      @app.call(env)
+    rescue Sfdc::UnauthorizedError
+      authenticate!
+      raise
+    end
+
+    # Internal: Performs the authentication and returns the response body.
+    def authenticate!
+      response = connection.post '/services/oauth2/token' do |req|
+        req.body = encode_www_form(params)
+      end
+      raise Sfdc::AuthenticationError, error_message(response) if response.status != 200
+      @options[:instance_url] = response.body['instance_url']
+      @options[:oauth_token]  = response.body['access_token']
+      response.body
+    end
+
+    # Internal: The params to post to the OAuth service.
+    def params
+      raise 'not implemented'
+    end
+
+    # Internal: Faraday connection to use when sending an authentication request.
+    def connection
+      @connection ||= Faraday.new(:url => "https://#{@options[:host]}") do |builder|
+        builder.use Sfdc::Middleware::Mashify, nil, @options
+        builder.response :json
+        builder.use Sfdc::Middleware::Logger, Sfdc.configuration.logger, @options if Sfdc.log?
+        builder.adapter Faraday.default_adapter
+      end
+    end
+
+    # Internal: The parsed error response.
+    def error_message(response)
+      "#{response.body['error']}: #{response.body['error_description']}"
+    end
+
+    # Featured detect form encoding.
+    # URI in 1.8 does not include encode_www_form
+    def encode_www_form(params)
+      if URI.respond_to?(:encode_www_form)
+        URI.encode_www_form(params)
+      else
+        params.map do |k, v|
+          k, v = CGI.escape(k.to_s), CGI.escape(v.to_s)
+          "#{k}=#{v}"
+        end.join('&')
+      end
+    end
+  end
+end

data/lib/sfdc/middleware/authentication/password.rb

@@ -0,0 +1,20 @@
+module Sfdc
+
+  # Authentication middleware used if username and password flow is used
+  class Middleware::Authentication::Password < Sfdc::Middleware::Authentication
+
+    def params
+      { :grant_type    => 'password',
+        :client_id     => @options[:client_id],
+        :client_secret => @options[:client_secret],
+        :username      => @options[:username],
+        :password      => password }
+    end
+
+    def password
+      "#{@options[:password]}#{@options[:security_token]}"
+    end
+
+  end
+
+end

data/lib/sfdc/middleware/authentication/token.rb

@@ -0,0 +1,15 @@
+module Sfdc
+
+  # Authentication middleware used if oauth_token and refresh_token are set
+  class Middleware::Authentication::Token < Sfdc::Middleware::Authentication
+
+    def params
+      { :grant_type    => 'refresh_token',
+        :refresh_token => @options[:refresh_token],
+        :client_id     => @options[:client_id],
+        :client_secret => @options[:client_secret] }
+    end
+
+  end
+
+end

data/lib/sfdc/middleware/authorization.rb

@@ -0,0 +1,19 @@
+module Sfdc
+
+  # Piece of middleware that simply injects the OAuth token into the request
+  # headers.
+  class Middleware::Authorization < Sfdc::Middleware
+    AUTH_HEADER = 'Authorization'.freeze
+
+    def call(env)
+      env[:request_headers][AUTH_HEADER] = %(OAuth #{token})
+      @app.call(env)
+    end
+
+    def token
+      @options[:oauth_token]
+    end
+
+  end
+
+end

data/lib/sfdc/middleware/caching.rb

@@ -0,0 +1,24 @@
+module Sfdc
+  class Middleware::Caching < FaradayMiddleware::Caching
+
+    def call(env)
+      expire(cache_key(env)) unless use_cache?
+      super
+    end
+
+    def expire(key)
+      cache.delete(key) if cache
+    end
+
+    # We don't want to cache requests for different clients, so append the
+    # oauth token to the cache key.
+    def cache_key(env)
+      super(env) + env[:request_headers][Sfdc::Middleware::Authorization::AUTH_HEADER].gsub(/\s/, '')
+    end
+
+    def use_cache?
+      !@options.has_key?(:use_cache) || @options[:use_cache]
+    end
+
+  end
+end

data/lib/sfdc/middleware/gzip.rb

@@ -0,0 +1,31 @@
+require 'zlib'
+
+module Sfdc
+  # Middleware to uncompress GZIP compressed responses from Salesforce.
+  class Middleware::Gzip < Sfdc::Middleware
+    ACCEPT_ENCODING_HEADER  = 'Accept-Encoding'.freeze
+    CONTENT_ENCODING_HEADER = 'Content-Encoding'.freeze
+    ENCODING                = 'gzip'.freeze
+
+    def call(env)
+      env[:request_headers][ACCEPT_ENCODING_HEADER] = ENCODING if @options[:compress]
+      @app.call(env).on_complete do |environment|
+        on_complete(environment)
+      end
+    end
+
+    def on_complete(env)
+      env[:body] = decompress(env[:body]) if gzipped?(env)
+    end
+
+    # Internal: Returns true if the response is gzipped.
+    def gzipped?(env)
+      env[:response_headers][CONTENT_ENCODING_HEADER] == ENCODING
+    end
+
+    # Internal: Decompresses a gzipped string.
+    def decompress(body)
+      Zlib::GzipReader.new(StringIO.new(body)).read
+    end
+  end
+end

data/lib/sfdc/middleware/instance_url.rb

@@ -0,0 +1,18 @@
+module Sfdc
+
+  # Middleware which asserts that the instance_url is always set
+  class Middleware::InstanceURL < Sfdc::Middleware
+
+    def call(env)
+      # If the connection url_prefix isn't set, we must not be authenticated.
+      raise Sfdc::UnauthorizedError, 'Connection prefix not set' unless url_prefix_set?
+      @app.call(env)
+    end
+
+    def url_prefix_set?
+      !!(connection.url_prefix && connection.url_prefix.host)
+    end
+
+  end
+
+end

data/lib/sfdc/middleware/logger.rb

@@ -0,0 +1,40 @@
+require 'forwardable'
+
+module Sfdc
+  class Middleware::Logger < Faraday::Response::Middleware
+    extend Forwardable
+
+    def initialize(app, logger, options)
+      super(app)
+      @options = options
+      @logger = logger || begin
+        require 'logger'
+        ::Logger.new(STDOUT)
+      end
+    end
+
+    def_delegators :@logger, :debug, :info, :warn, :error, :fatal
+
+    def call(env)
+      debug('request') do
+        dump :url => env[:url].to_s,
+          :method => env[:method],
+          :headers => env[:request_headers],
+          :body => env[:body]
+      end
+      super
+    end
+
+    def on_complete(env)
+      debug('response') do
+        dump :status => env[:status].to_s,
+          :headers => env[:response_headers],
+          :body => env[:body]
+      end
+    end
+
+    def dump(hash)
+      "\n" + hash.map { |k, v| "  #{k}: #{v.inspect}" }.join("\n")
+    end
+  end
+end

data/lib/sfdc/middleware/mashify.rb

@@ -0,0 +1,18 @@
+module Sfdc
+  # Middleware the converts sobject records from JSON into Sfdc::SObject objects
+  # and collections of records into Sfdc::Collection objects.
+  class Middleware::Mashify < Sfdc::Middleware
+
+    def call(env)
+      @env = env
+      response = @app.call(env)
+      env[:body] = Sfdc::Mash.build(body, client)
+      response
+    end
+
+    def body
+      @env[:body]
+    end
+
+  end
+end

data/lib/sfdc/middleware/multipart.rb

@@ -0,0 +1,53 @@
+module Sfdc
+  class Middleware::Multipart < Faraday::Request::UrlEncoded
+    self.mime_type = 'multipart/form-data'.freeze
+    DEFAULT_BOUNDARY = "--boundary_string".freeze
+
+    def call(env)
+      match_content_type(env) do |params|
+        env[:request] ||= {}
+        env[:request][:boundary] ||= DEFAULT_BOUNDARY
+        env[:request_headers][CONTENT_TYPE] += ";boundary=#{env[:request][:boundary]}"
+        env[:body] = create_multipart(env, params)
+      end
+      @app.call env
+    end
+
+    def process_request?(env)
+      type = request_type(env)
+      env[:body].respond_to?(:each_key) and !env[:body].empty? and (
+        (type.empty? and has_multipart?(env[:body])) or
+        type == self.class.mime_type
+      )
+    end
+
+    def has_multipart?(obj)
+      # string is an enum in 1.8, returning list of itself
+      if obj.respond_to?(:each) && !obj.is_a?(String)
+        (obj.respond_to?(:values) ? obj.values : obj).each do |val|
+          return true if (val.respond_to?(:content_type) || has_multipart?(val))
+        end
+      end
+      false
+    end
+
+    def create_multipart(env, params)
+      boundary = env[:request][:boundary]
+      parts = []
+
+      # Fields
+      parts << Faraday::Parts::Part.new(boundary, 'entity_content', params.reject { |k,v| v.respond_to? :content_type }.to_json)
+
+      # Files
+      params.each do |k,v|
+        parts << Faraday::Parts::Part.new(boundary, k.to_s, v) if v.respond_to? :content_type
+      end
+
+      parts << Faraday::Parts::EpiloguePart.new(boundary)
+
+      body = Faraday::CompositeReadIO.new(parts)
+      env[:request_headers]['Content-Length'] = body.length.to_s
+      return body
+    end
+  end
+end

data/lib/sfdc/middleware/raise_error.rb

@@ -0,0 +1,23 @@
+module Sfdc
+  class Middleware::RaiseError < Faraday::Response::Middleware
+    def on_complete(env)
+      @env = env
+      case env[:status]
+      when 404
+        raise Faraday::Error::ResourceNotFound, message
+      when 401
+        raise Sfdc::UnauthorizedError, message
+      when 400...600
+        raise Faraday::Error::ClientError, message
+      end
+    end
+
+    def message
+      "#{body.first['errorCode']}: #{body.first['message']}"
+    end
+
+    def body
+      JSON.parse(@env[:body])
+    end
+  end
+end

data/lib/sfdc/signed_request.rb

@@ -0,0 +1,48 @@
+require 'openssl'
+require 'base64'
+require 'json'
+
+module Sfdc
+  class SignedRequest
+    # Public: Initializes and decodes the signed request
+    #
+    # signed_request - The POST message containing the signed request from Salesforce.
+    # client_secret  - The oauth client secret used to encrypt the signed request.
+    #
+    # Returns the parsed JSON context.
+    def self.decode(signed_request, client_secret)
+      new(signed_request, client_secret).decode
+    end
+
+    def initialize(signed_request, client_secret)
+      @client_secret = client_secret
+      split_components(signed_request)
+    end
+
+    # Public: Decode the signed request.
+    #
+    # Returns the parsed JSON context.
+    # Returns nil if the signed request is invalid.
+    def decode
+      return nil if signature != hmac
+      JSON.parse(Base64.decode64(payload))
+    end
+
+  private
+    attr_reader :client_secret, :signature, :payload
+
+    def split_components(signed_request)
+      @signature, @payload = signed_request.split('.')
+      @signature = Base64.decode64(@signature)
+    end
+
+    def hmac
+      OpenSSL::HMAC.digest(digest, client_secret, payload)
+    end
+
+    def digest
+      OpenSSL::Digest::Digest.new('sha256')
+    end
+
+  end
+end