restforce 0.0.3 → 0.0.4

data/README.md

@@ -47,7 +47,7 @@ authentication method.
 #### OAuth token authentication
 
 ```ruby
-client = Restforce::Client.new :oauth_token => 'oauth token',
+client = Restforce.new :oauth_token => 'oauth token',
   :instance_url  => 'instance url'
 ```
 
@@ -55,7 +55,7 @@ Although the above will work, you'll probably want to take advantage of the
 (re)authentication middleware by specifying a refresh token, client id and client secret:
 
 ```ruby
-client = Restforce::Client.new :oauth_token => 'oauth token',
+client = Restforce.new :oauth_token => 'oauth token',
   :refresh_token => 'refresh token',
   :instance_url  => 'instance url',
   :client_id     => 'client_id',
@@ -67,7 +67,7 @@ client = Restforce::Client.new :oauth_token => 'oauth token',
 If you prefer to use a username and password to authenticate:
 
 ```ruby
-client = Restforce::Client.new :username => 'foo',
+client = Restforce.new :username => 'foo',
   :password       => 'bar',
   :security_token => 'security token'
   :client_id      => 'client_id',
@@ -80,12 +80,12 @@ You can connect to sandbox orgs by specifying a host. The default host is
 'login.salesforce.com':
 
 ```ruby
-client = Restforce::Client.new :host => 'test.salesforce.com'
+client = Restforce.new :host => 'test.salesforce.com'
 ```
 
 #### Global configuration
 
-You can set any of the options passed into Restforce::Client.new globally:
+You can set any of the options passed into Restforce.new globally:
 
 ```ruby
 Restforce.configure do |config|
@@ -185,7 +185,7 @@ pub/sub with Salesforce a trivial task:
 
 ```ruby
 # Initialize a client with your username/password/oauth token/etc
-client = Restforce::Client.new
+client = Restforce.new
 
 # Force an authentication request
 client.authenticate!
@@ -201,6 +201,53 @@ EM.run {
 Boom, you're now receiving push notifications when Accounts are
 created/updated.
 
+### Caching
+
+The gem supports easy caching of GET requests (e.g. queries):
+
+```ruby
+# Memcached example:
+
+cache = Dalli::Client.new
+
+client = Restforce.new cache: cache
+
+# or
+
+Restforce.configure do |config|
+  config.cache = cache
+end
+```
+
+### Logging/Debugging
+
+You can easily inspect what Restforce is sending/receiving by setting
+`Restforce.log = true`.
+
+```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: { ... }
+```
+
 ## Contributing
 
 1. Fork it

data/lib/restforce.rb

@@ -14,6 +14,15 @@ require 'restforce/client'
 require 'restforce/middleware'
 
 module Restforce
+  class << self
+    # Alias for Restforce::Client.new
+    #
+    # Shamelessly pulled from https://github.com/pengwynn/octokit/blob/master/lib/octokit.rb
+    def new(options = {})
+      Restforce::Client.new(options)
+    end
+  end
+
   class AuthenticationError < StandardError; end
   class UnauthorizedError < StandardError; end
   class InstanceURLError < StandardError; end

data/lib/restforce/client.rb

@@ -52,7 +52,7 @@ 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].each do |option|
+         :api_version, :oauth_token, :refresh_token, :instance_url, :cache].each do |option|
           options[option] = Restforce.configuration.send option
         end
       end
@@ -327,8 +327,9 @@ module Restforce
         builder.use Restforce::Middleware::Authorization, self, @options
         builder.use Restforce::Middleware::InstanceURL, self, @options
         builder.use Restforce::Middleware::RaiseError
-        builder.response :logger, Restforce.configuration.logger if Restforce.log?
         builder.response :json
+        builder.use Restforce::Middleware::Caching, cache if cache
+        builder.use Restforce::Middleware::Logger, Restforce.configuration.logger if Restforce.log?
         builder.adapter Faraday.default_adapter
       end
       @connection
@@ -361,6 +362,11 @@ module Restforce
         @options[:client_secret]
     end
 
+    # Internal: Cache to use for the caching middleware
+    def cache
+      @options[:cache]
+    end
+
     # Internal: Returns true if the middlware stack includes the
     # Restforce::Middleware::Mashify middleware.
     def mashify?

data/lib/restforce/config.rb

@@ -56,6 +56,10 @@ module Restforce
     attr_accessor :refresh_token
     attr_accessor :instance_url
 
+    # Set this to an object that responds to read, write and fetch and all GET
+    # requests will be cached.
+    attr_accessor :cache
+
     def initialize
       @api_version ||= '24.0'
       @host        ||= 'login.salesforce.com'

data/lib/restforce/middleware.rb

@@ -29,3 +29,5 @@ require 'restforce/middleware/authorization'
 require 'restforce/middleware/instance_url'
 require 'restforce/middleware/mashify'
 require 'restforce/middleware/multipart'
+require 'restforce/middleware/caching'
+require 'restforce/middleware/logger'

data/lib/restforce/middleware/authentication.rb

@@ -23,7 +23,7 @@ module Restforce
     def connection
       @connection ||= Faraday.new(:url => "https://#{@options[:host]}") do |builder|
         builder.response :json
-        builder.response :logger, Restforce.configuration.logger if Restforce.log?
+        builder.use Restforce::Middleware::Logger, Restforce.configuration.logger if Restforce.log?
         builder.adapter Faraday.default_adapter
       end
     end
@@ -31,6 +31,10 @@ module Restforce
     def force_authenticate?(env)
       env[:request_headers] && env[:request_headers]['X-ForceAuthenticate']
     end
+
+    def error_message(response)
+      "#{response.body['error']}: #{response.body['error_description']}"
+    end
   
   end
 

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

@@ -13,7 +13,7 @@ module Restforce
           :password      => password
         )
       end
-      raise Restforce::AuthenticationError if response.status != 200
+      raise Restforce::AuthenticationError, error_message(response) if response.status != 200
       @options[:instance_url] = response.body['instance_url']
       @options[:oauth_token]  = response.body['access_token']
     end

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

@@ -12,7 +12,7 @@ module Restforce
           :client_secret => @options[:client_secret]
         )
       end
-      raise Restforce::AuthenticationError if response.status != 200
+      raise Restforce::AuthenticationError, error_message(response) if response.status != 200
       @options[:instance_url] = response.body['instance_url']
       @options[:oauth_token]  = response.body['access_token']
     end

data/lib/restforce/middleware/caching.rb

@@ -0,0 +1,11 @@
+module Restforce
+  class Middleware::Caching < FaradayMiddleware::Caching
+
+    # 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
+
+  end
+end

data/lib/restforce/middleware/logger.rb

@@ -0,0 +1,9 @@
+module Restforce
+  class Middleware::Logger < Faraday::Response::Logger
+    def on_complete(env)
+      info('Status') { env[:status].to_s }
+      debug('response headers') { dump_headers env[:response_headers] }
+      debug('response body') { env[:body] }
+    end
+  end
+end

data/lib/restforce/sobject.rb

@@ -5,6 +5,11 @@ module Restforce
       self.attributes.type
     end
 
+    # Public: Get the describe for this sobject type
+    def describe
+      @client.describe(sobject_type)
+    end
+
     # Public: Persist the attributes to Salesforce.
     #
     # Examples

data/lib/restforce/version.rb

@@ -1,3 +1,3 @@
 module Restforce
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/lib/client_spec.rb

@@ -326,6 +326,13 @@ shared_examples_for 'methods' do
     subject { client.authenticate! }
     specify { expect { subject }.to_not raise_error }
   end
+
+  describe '.cache' do
+    let(:cache) { double('cache') }
+
+    subject { client.send :cache }
+    it { should eq cache }
+  end
 end
 
 describe 'with mashify middleware' do

data/spec/lib/middleware/authentication/password_spec.rb

@@ -26,7 +26,7 @@ describe Restforce::Middleware::Authentication::Password do
       stub_request(:post, "https://login.salesforce.com/services/oauth2/token").
         with(:body => "grant_type=password&client_id=client_id&client_secret=" \
         "client_secret&username=foo&password=barsecurity_token").
-        to_return(:status => 400, :body => fixture(:auth_success_response))
+        to_return(:status => 400, :body => fixture(:auth_error_response))
     end
   end
 

data/spec/lib/middleware/authentication/token_spec.rb

@@ -24,7 +24,7 @@ describe Restforce::Middleware::Authentication::Token do
       stub_request(:post, "https://login.salesforce.com/services/oauth2/token").
         with(:body => "grant_type=refresh_token&refresh_token=refresh_token&" \
         "client_id=client_id&client_secret=client_secret").
-        to_return(:status => 400, :body => fixture(:auth_success_response))
+        to_return(:status => 400, :body => fixture(:refresh_error_response))
     end
   end
 end

data/spec/lib/middleware/authentication_spec.rb

@@ -52,7 +52,7 @@ describe Restforce::Middleware::Authentication do
         end
 
         its(:handlers) { should include FaradayMiddleware::ParseJson, Faraday::Adapter::NetHttp }
-        its(:handlers) { should_not include Faraday::Response::Logger  }
+        its(:handlers) { should_not include Restforce::Middleware::Logger  }
       end
 
       context 'with logging enabled' do
@@ -60,7 +60,7 @@ describe Restforce::Middleware::Authentication do
           Restforce.stub!(:log?).and_return(true)
         end
 
-        its(:handlers) { should include FaradayMiddleware::ParseJson, Faraday::Response::Logger, Faraday::Adapter::NetHttp }
+        its(:handlers) { should include FaradayMiddleware::ParseJson, Restforce::Middleware::Logger, Faraday::Adapter::NetHttp }
       end
     end
   end

data/spec/lib/sobject_spec.rb

@@ -90,4 +90,17 @@ describe Restforce::SObject do
       specify { expect { subject }.to_not raise_error }
     end
   end
+
+  describe '.describe' do
+    before do
+      @request = stub_api_request 'sobject/Whizbang/describe', with: 'sobject/sobject_describe_success_response'
+    end
+
+    after do
+      @request.should have_been_requested
+    end
+
+    subject { sobject.describe }
+    it { should be_a Hash }
+  end
 end

data/spec/support/basic_client.rb

@@ -7,6 +7,7 @@ shared_context 'basic client' do
   let(:security_token) { 'security_token' }
   let(:client_id)      { 'client_id'      }
   let(:client_secret)  { 'client_secret'  }
+  let(:cache)          { nil }
 
   let(:base_options) do
     {
@@ -17,7 +18,8 @@ shared_context 'basic client' do
       :password       => password,
       :security_token => security_token,
       :client_id      => client_id,
-      :client_secret  => client_secret
+      :client_secret  => client_secret,
+      :cache          => cache
     }
   end
 

data/spec/support/middleware.rb

@@ -25,7 +25,7 @@ shared_examples_for 'authentication middleware' do
       it 'raises an exception' do
         expect {
           middleware.authenticate!
-        }.to raise_error Restforce::AuthenticationError
+        }.to raise_error Restforce::AuthenticationError, /^invalid_grant: .*/
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-11 00:00:00.000000000 Z
+date: 2012-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -179,7 +179,9 @@ files:
 - lib/restforce/middleware/authentication/password.rb
 - lib/restforce/middleware/authentication/token.rb
 - lib/restforce/middleware/authorization.rb
+- lib/restforce/middleware/caching.rb
 - lib/restforce/middleware/instance_url.rb
+- lib/restforce/middleware/logger.rb
 - lib/restforce/middleware/mashify.rb
 - lib/restforce/middleware/multipart.rb
 - lib/restforce/middleware/raise_error.rb