restforce 0.0.8 → 0.1.0

data/README.md

@@ -12,6 +12,7 @@ It attempts to solve a couple of key issues that the databasedotcom gem has been
 * Support for the Streaming API
 * Support for blob data types.
 * A clean and modular architecture using [Faraday middleware](https://github.com/technoweenie/faraday)
+* Support for decoding [Force.com Canvas](http://www.salesforce.com/us/developer/docs/platform_connectpre/canvas_framework.pdf) signed requests. (NEW!)
 
 [Documentation](http://rubydoc.info/gems/restforce/frames)
 
@@ -110,6 +111,9 @@ accounts = client.query("select Id, Something__c from Account where Id = 'someid
 account = records.first
 # => #<Restforce::SObject >
 
+account.sobject_type
+# => 'Account'
+
 account.Id
 # => "someid"
 
@@ -204,6 +208,25 @@ _See also: http://www.salesforce.com/us/developer/docs/api_rest/Content/dome_del
 
 * * *
 
+### describe(sobject)
+
+If no parameter is given, it will return the global describe. If the name of an
+sobject is given, it will return the describe for that sobject.
+
+```ruby
+# get the global describe for all sobjects
+client.describe
+# => { ... }
+
+# get the describe for the Account object
+client.describe('Account')
+# => { ... }
+```
+
+_See also: http://www.salesforce.com/us/developer/docs/api_rest/Content/dome_describeGlobal.htm, http://www.salesforce.com/us/developer/docs/api_rest/Content/dome_sobject_describe.htm_
+
+* * *
+
 ### File Uploads
 
 Using the new [Blob Data](http://www.salesforce.com/us/developer/docs/api_rest/Content/dome_sobject_insert_update_blob.htm) api feature (500mb limit):
@@ -269,6 +292,15 @@ Restforce.configure do |config|
 end
 ```
 
+If you enable caching, you can disable caching on a per-request basis by using
+.without_caching:
+
+```ruby
+client.without_caching do
+  client.query('select Id from Account')
+end
+```
+
 * * *
 
 ### Logging/Debugging
@@ -279,25 +311,29 @@ You can easily inspect what Restforce is sending/receiving by setting
 ```ruby
 Restforce.log = true
 client = Restforce.new.query('select Id, Name from Account')
+```
 
-# => I, [2012-09-11T21:54:00.488991 #24032]  INFO -- : post https://login.salesforce.com/services/oauth2/token
-# => D, [2012-09-11T21:54:00.489078 #24032] DEBUG -- request: 
-# => I, [2012-09-11T21:54:00.997295 #24032]  INFO -- Status: 200
-# => D, [2012-09-11T21:54:00.997391 #24032] DEBUG -- response headers: server: ""
-# => content-type: "application/json; charset=UTF-8"
-# => transfer-encoding: "chunked"
-# => date: "Wed, 12 Sep 2012 04:53:59 GMT"
-# => connection: "close"
-# => D, [2012-09-11T21:54:00.997431 #24032] DEBUG -- response body: { ... }
-# => I, [2012-09-11T21:54:00.998985 #24032]  INFO -- : get https://na9.salesforce.com/services/data/v24.0/query?q=select+Id%2C+Name+from+Account
-# => D, [2012-09-11T21:54:00.999040 #24032] DEBUG -- request: Authorization: "OAuth token"
-# => I, [2012-09-11T21:54:01.622874 #24032]  INFO -- Status: 200
-# => D, [2012-09-11T21:54:01.623001 #24032] DEBUG -- response headers: server: ""
-# => content-type: "application/json; charset=UTF-8"
-# => transfer-encoding: "chunked"
-# => date: "Wed, 12 Sep 2012 04:54:00 GMT"
-# => connection: "close"
-# => D, [2012-09-11T21:54:01.623058 #24032] DEBUG -- response body: { ... }
+**Log Output**
+
+```
+I, [2012-09-11T21:54:00.488991 #24032]  INFO -- : post https://login.salesforce.com/services/oauth2/token
+D, [2012-09-11T21:54:00.489078 #24032] DEBUG -- request: 
+I, [2012-09-11T21:54:00.997295 #24032]  INFO -- Status: 200
+D, [2012-09-11T21:54:00.997391 #24032] DEBUG -- response headers: server: ""
+content-type: "application/json; charset=UTF-8"
+transfer-encoding: "chunked"
+date: "Wed, 12 Sep 2012 04:53:59 GMT"
+connection: "close"
+D, [2012-09-11T21:54:00.997431 #24032] DEBUG -- response body: { ... }
+I, [2012-09-11T21:54:00.998985 #24032]  INFO -- : get https://na9.salesforce.com/services/data/v24.0/query?q=select+Id%2C+Name+from+Account
+D, [2012-09-11T21:54:00.999040 #24032] DEBUG -- request: Authorization: "OAuth token"
+I, [2012-09-11T21:54:01.622874 #24032]  INFO -- Status: 200
+D, [2012-09-11T21:54:01.623001 #24032] DEBUG -- response headers: server: ""
+content-type: "application/json; charset=UTF-8"
+transfer-encoding: "chunked"
+date: "Wed, 12 Sep 2012 04:54:00 GMT"
+connection: "close"
+D, [2012-09-11T21:54:01.623058 #24032] DEBUG -- response body: { ... }
 ```
 
 ## Contributing

data/lib/restforce.rb

@@ -3,6 +3,9 @@ require 'faraday_middleware'
 require 'json'
 require 'faye'
 
+require 'openssl'
+require 'base64'
+
 require 'restforce/version'
 require 'restforce/config'
 require 'restforce/mash'

data/lib/restforce/client.rb

@@ -52,21 +52,13 @@ module Restforce
       raise 'Please specify a hash of options' unless options.is_a?(Hash)
       @options = {}.tap do |options|
         [:username, :password, :security_token, :client_id, :client_secret, :host,
-         :api_version, :oauth_token, :refresh_token, :instance_url, :cache].each do |option|
+         :api_version, :oauth_token, :refresh_token, :instance_url, :cache, :authentication_retries].each do |option|
           options[option] = Restforce.configuration.send option
         end
       end
       @options.merge!(options)
     end
 
-    # Public: Get the global describe for all sobjects.
-    #
-    # Returns the Hash representation of the describe call.
-    def describe_sobjects
-      response = api_get 'sobjects'
-      response.body['sobjects']
-    end
-
     # Public: Get the names of all sobjects on the org.
     #
     # Examples
@@ -77,7 +69,7 @@ module Restforce
     #
     # Returns an Array of String names for each SObject.
     def list_sobjects
-      describe_sobjects.collect { |sobject| sobject['name'] }
+      describe.collect { |sobject| sobject['name'] }
     end
     
     # Public: Returns a detailed describe result for the specified sobject
@@ -86,14 +78,23 @@ module Restforce
     #
     # Examples
     #
+    #   # get the global describe for all sobjects
+    #   client.describe
+    #   # => { ... }
+    #
     #   # get the describe for the Account object
     #   client.describe('Account')
     #   # => { ... }
     #
     # Returns the Hash representation of the describe call.
-    def describe(sobject)
-      response = api_get "sobjects/#{sobject.to_s}/describe"
-      response.body
+    def describe(sobject=nil)
+      if sobject
+        response = api_get "sobjects/#{sobject.to_s}/describe"
+        response.body
+      else
+        response = api_get 'sobjects'
+        response.body['sobjects']
+      end
     end
 
     # Public: Get the current organization's Id.
@@ -249,6 +250,18 @@ module Restforce
       true
     end
 
+    # Public: Runs the block with caching disabled.
+    #
+    # block - A query/describe/etc.
+    #
+    # Returns the result of the block
+    def without_caching(&block)
+      @options[:perform_caching] = false
+      block.call
+    ensure
+      @options.delete(:perform_caching)
+    end
+
     # Public: Subscribe to a PushTopic
     #
     # channel - The name of the PushTopic channel to subscribe to.
@@ -267,6 +280,19 @@ module Restforce
       connection.headers.delete('X-ForceAuthenticate')
     end
 
+    # Public: Decodes a signed request received from Force.com Canvas.
+    #
+    # message - The POST message containing the signed request from Salesforce.
+    #
+    # Returns the Hash context if the message is valid.
+    def decode_signed_request(message)
+      raise 'client_secret not set' unless @options[:client_secret]
+      encryped_secret, payload = message.split('.')
+      digest = OpenSSL::Digest::Digest.new('sha256')
+      signature = Base64.encode64(OpenSSL::HMAC.hexdigest(digest, @options[:client_secret], payload))
+      JSON.parse(Base64.decode64(payload)) if encryped_secret == signature
+    end
+
     # Public: Helper methods for performing arbitrary actions against the API using
     # various HTTP verbs.
     #
@@ -328,7 +354,7 @@ module Restforce
         builder.use Restforce::Middleware::InstanceURL, self, @options
         builder.use Restforce::Middleware::RaiseError
         builder.response :json
-        builder.use Restforce::Middleware::Caching, cache if cache
+        builder.use Restforce::Middleware::Caching, cache, @options if cache
         builder.use Restforce::Middleware::Logger, Restforce.configuration.logger if Restforce.log?
         builder.adapter Faraday.default_adapter
       end

data/lib/restforce/config.rb

@@ -60,9 +60,13 @@ module Restforce
     # requests will be cached.
     attr_accessor :cache
 
+    # The number of times reauthentication should be tried before failing.
+    attr_accessor :authentication_retries
+
     def initialize
-      @api_version ||= '24.0'
-      @host        ||= 'login.salesforce.com'
+      @api_version            ||= '24.0'
+      @host                   ||= 'login.salesforce.com'
+      @authentication_retries ||= 3
     end
 
     def logger

data/lib/restforce/middleware/authentication.rb

@@ -7,16 +7,21 @@ module Restforce
   class Middleware::Authentication < Restforce::Middleware
 
     def call(env)
+      retries = @options[:authentication_retries]
       request_body = env[:body]
       request = env[:request]
       begin
         return authenticate! if force_authenticate?(env)
         @app.call(env)
       rescue Restforce::UnauthorizedError
-        authenticate!
-        env[:body] = request_body
-        env[:request] = request
-        @app.call(env)
+        if retries > 0
+          authenticate!
+          env[:body] = request_body
+          env[:request] = request
+          retries -= 1
+          retry
+        end
+        raise
       end
     end
 

data/lib/restforce/middleware/caching.rb

@@ -1,11 +1,19 @@
 module Restforce
   class Middleware::Caching < FaradayMiddleware::Caching
 
+    def call(env)
+      perform_caching? ? super : @app.call(env)
+    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][Restforce::Middleware::Authorization::AUTH_HEADER].gsub(/\s/, '')
     end
 
+    def perform_caching?
+      !@options.has_key?(:perform_caching) || @options[:perform_caching]
+    end
+
   end
 end

data/lib/restforce/version.rb

@@ -1,3 +1,3 @@
 module Restforce
-  VERSION = "0.0.8"
+  VERSION = "0.1.0"
 end

data/spec/lib/client_spec.rb

@@ -52,19 +52,6 @@ shared_examples_for 'methods' do
       it { should eq Restforce::Middleware::Authentication::Token }
     end
   end
-  
-  describe '.describe_sobjects' do
-    before do
-      @request = stub_api_request :sobjects, with: 'sobject/describe_sobjects_success_response'
-    end
-
-    after do
-      @request.should have_been_requested
-    end
-
-    subject { client.describe_sobjects }
-    it { should be_an Array }
-  end
 
   describe '.list_sobjects' do
     before do
@@ -81,16 +68,31 @@ shared_examples_for 'methods' do
   end
 
   describe '.describe' do
-    before do
-      @request = stub_api_request 'sobjects/Whizbang/describe', with: 'sobject/sobject_describe_success_response'
-    end
+    context 'with no arguments' do
+      before do
+        @request = stub_api_request :sobjects, with: 'sobject/describe_sobjects_success_response'
+      end
 
-    after do
-      @request.should have_been_requested
+      after do
+        @request.should have_been_requested
+      end
+
+      subject { client.describe }
+      it { should be_an Array }
     end
 
-    subject { client.describe('Whizbang') }
-    its(['name']) { should eq 'Whizbang' }
+    context 'with an argument' do
+      before do
+        @request = stub_api_request 'sobjects/Whizbang/describe', with: 'sobject/sobject_describe_success_response'
+      end
+
+      after do
+        @request.should have_been_requested
+      end
+
+      subject { client.describe('Whizbang') }
+      its(['name']) { should eq 'Whizbang' }
+    end
   end
 
   describe '.query' do
@@ -333,6 +335,42 @@ shared_examples_for 'methods' do
     subject { client.send :cache }
     it { should eq cache }
   end
+
+  describe '.decode_signed_request' do
+    subject { client.decode_signed_request(message) }
+
+    context 'when the message is valid' do
+      let(:data) { Base64.encode64('{ "key": "value" }') }
+      let(:message) do
+        digest = OpenSSL::Digest::Digest.new('sha256')
+        signature = Base64.encode64(OpenSSL::HMAC.hexdigest(digest, client_secret, data))
+        "#{signature}.#{data}"
+      end
+
+      it { should eq('key' => 'value') }
+    end
+
+    context 'when the message is invalid' do
+      let(:message) { 'foobar.awdkjkj' }
+      it { should be_nil }
+    end
+  end
+
+  describe '.without_caching' do
+    let(:cache) { double('cache') }
+
+    before do
+      @request = stub_api_request 'query\?q=SELECT%20some,%20fields%20FROM%20object', with: 'sobject/query_success_response'
+      cache.should_receive(:fetch).never
+    end
+
+    after do
+      @request.should have_been_requested
+    end
+
+    subject { client.without_caching { client.query('SELECT some, fields FROM object') } }
+    it { should be_an Array }
+  end
 end
 
 describe 'with mashify middleware' do

data/spec/lib/config_spec.rb

@@ -11,8 +11,9 @@ describe Restforce do
     it { should be_a Restforce::Configuration }
 
     context 'by default' do
-      its(:api_version)  { should eq '24.0' }
-      its(:host)         { should eq 'login.salesforce.com' }
+      its(:api_version)            { should eq '24.0' }
+      its(:host)                   { should eq 'login.salesforce.com' }
+      its(:authentication_retries) { should eq 3 }
       [:username, :password, :security_token, :client_id, :client_secret,
        :oauth_token, :refresh_token, :instance_url].each do |attr|
         its(attr) { should be_nil }

data/spec/lib/middleware/authentication_spec.rb

@@ -3,7 +3,8 @@ require 'spec_helper'
 describe Restforce::Middleware::Authentication do
   let(:app)        { double('app')            }
   let(:env)        { { }  }
-  let(:options)    { { host: 'login.salesforce.com' } }
+  let(:retries)    { 3 }
+  let(:options)    { { host: 'login.salesforce.com', authentication_retries: retries } }
   let(:middleware) { described_class.new app, nil, options }
 
   describe '.authenticate!' do
@@ -38,6 +39,18 @@ describe Restforce::Middleware::Authentication do
         middleware.call(env)
       end
     end
+
+    context 'when the retry limit is reached' do
+      before do
+        app.should_receive(:call).twice.and_raise(Restforce::UnauthorizedError)
+        middleware.should_receive(:authenticate!)
+      end
+
+      let(:retries) { 1 }
+      it 'should raise an exception' do
+        expect { middleware.call(env) }.to raise_error Restforce::UnauthorizedError
+      end
+    end
   end
 
   describe '.connection' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-19 00:00:00.000000000 Z
+date: 2012-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake