restforce 3.0.1 → 5.1.1

data/README.md

@@ -8,7 +8,7 @@ Restforce is a ruby gem for the [Salesforce REST api](http://www.salesforce.com/
 Features include:
 
 * A clean and modular architecture using [Faraday middleware](https://github.com/technoweenie/faraday) and [Hashie::Mash](https://github.com/intridea/hashie/tree/v1.2.0)'d responses.
-* Support for interacting with multiple users from different orgs.
+* Support for interacting with multiple users from different organizations.
 * Support for parent-to-child relationships.
 * Support for aggregate queries.
 * Support for the [Streaming API](#streaming)
@@ -19,13 +19,13 @@ Features include:
 * Support for dependent picklists.
 * Support for decoding [Force.com Canvas](http://www.salesforce.com/us/developer/docs/platform_connectpre/canvas_framework.pdf) signed requests. (NEW!)
 
-[Official Website](http://restforce.org/) | [Documentation](http://rubydoc.info/gems/restforce/frames) | [Changelog](https://github.com/restforce/restforce/tree/master/CHANGELOG.md)
+[Official Website](https://restforce.github.io/) | [Documentation](http://rubydoc.info/gems/restforce/frames) | [Changelog](https://github.com/restforce/restforce/tree/master/CHANGELOG.md)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'restforce', '~> 3.0.1'
+    gem 'restforce', '~> 5.1.1'
 
 And then execute:
 
@@ -35,7 +35,13 @@ Or install it yourself as:
 
     $ gem install restforce
 
-__As of [version 3.0.0](https://github.com/restforce/restforce/blob/master/CHANGELOG.md#300-aug-2-2018), this gem is only compatible with Ruby 2.3.0 and later.__ You'll need to use version 2.5.3 or earlier if you're running on Ruby 2.2, 2.1 or 2.0. For Ruby 1.9.3, you'll need to manually specify that you wish to use version 2.4.2.
+__As of version 5.1.0, this gem is only compatible with Ruby 2.6.0 and later.__ If you're using an earlier Ruby version:
+
+* for Ruby 2.5, use version 5.0.6 or earlier
+* for Ruby 2.4, use version 4.3.0 or earlier
+* for Ruby 2.3, use version 3.2.0 or earlier
+* for Ruby versions 2.2, 2.1 and 2.0, use version 2.5.3 or earlier
+* for Ruby 1.9.3, use version 2.4.2
 
 This gem is versioned using [Semantic Versioning](http://semver.org/), so you can be confident when updating that there will not be breaking changes outside of a major version (following format MAJOR.MINOR.PATCH, so for instance moving from 3.1.0 to 4.0.0 would be allowed to include incompatible API changes). See the [changelog](https://github.com/restforce/restforce/tree/master/CHANGELOG.md) for details on what has changed in each version.
 
@@ -43,12 +49,12 @@ This gem is versioned using [Semantic Versioning](http://semver.org/), so you ca
 
 Restforce is designed with flexibility and ease of use in mind. By default, all API calls will
 return [Hashie::Mash](https://github.com/intridea/hashie/tree/v1.2.0) objects,
-so you can do things like `client.query('select Id, (select Name from Children__r) from Account').Children__r.first.Name`.
+so you can do things like `client.query('select Id, (select Name from Children__r) from Account').first.Children__r.first.Name`.
 
 ### Initialization
 
 Which authentication method you use really depends on your use case. If you're
-building an application where many users from different orgs are authenticated
+building an application where many users from different organizations are authenticated
 through oauth and you need to interact with data in their org on their behalf,
 you should use the OAuth token authentication method.
 
@@ -78,7 +84,7 @@ client = Restforce.new(oauth_token: 'access_token',
                        api_version: '41.0')
 ```
 
-The middleware will use the `refresh_token` automatically to acquire a new `access_token` if the existing `access_token` is invalid.
+The middleware will use the `refresh_token` automatically to acquire a new `access_token` if the existing `access_token` is invalid. The refresh process uses the `host` option so make sure that is set correctly for sandbox organizations.
 
 `authentication_callback` is a proc that handles the response from Salesforce when the `refresh_token` is used to obtain a new `access_token`. This allows the `access_token` to be saved for re-use later - otherwise subsequent API calls will continue the cycle of "auth failure/issue new access_token/auth success".
 
@@ -111,6 +117,21 @@ client = Restforce.new(username: 'foo',
                        api_version: '41.0')
 ```
 
+#### JWT Bearer Token
+
+If you prefer to use a [JWT Bearer Token](https://developer.salesforce.com/page/Digging_Deeper_into_OAuth_2.0_on_Force.com#Obtaining_an_Access_Token_using_a_JWT_Bearer_Token) to authenticate:
+
+```ruby
+client = Restforce.new(username: 'foo',
+                       client_id: 'client_id',
+                       instance_url: 'instance_url',
+                       jwt_key: 'certificate_private_key',
+                       api_version: '38.0')
+```
+
+The `jwt_key` option is the private key of the certificate uploaded to your Connected App in Salesforce.
+Choose "use digital signatures" in the Connected App configuration screen to upload your certificate.
+
 You can also set the username, password, security token, client ID, client
 secret and API version in environment variables:
 
@@ -127,7 +148,17 @@ export SALESFORCE_API_VERSION="41.0"
 client = Restforce.new
 ```
 
-### Proxy Support
+#### Sandbox Organizations
+
+You can connect to sandbox organizations by specifying a host. The default host is
+'login.salesforce.com':
+
+```ruby
+client = Restforce.new(host: 'test.salesforce.com')
+```
+The host can also be set with the environment variable `SALESFORCE_HOST`.
+
+#### Proxy Support
 
 You can specify a HTTP proxy using the `proxy_uri` option, as follows, or by setting the `SALESFORCE_PROXY_URI` environment variable:
 
@@ -143,16 +174,6 @@ client = Restforce.new(username: 'foo',
 
 You may specify a username and password for the proxy with a URL along the lines of 'http://user:password@proxy.example.com:123'.
 
-#### Sandbox Orgs
-
-You can connect to sandbox orgs by specifying a host. The default host is
-'login.salesforce.com':
-
-```ruby
-client = Restforce.new(host: 'test.salesforce.com')
-```
-The host can also be set with the environment variable `SALESFORCE_HOST`.
-
 #### Global configuration
 
 You can set any of the options passed into `Restforce.new` globally:
@@ -313,8 +334,11 @@ client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
 ```ruby
 # Update the record with external `External__c` external ID set to '12'
 client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar')
+# => true or "RecordId"
 ```
 
+The upsert method will return the record Id if included in the response body from the Salesforce API; otherwise, it returns true. Currently the Salesforce API only returns the Id for newly created records.
+
 ### destroy
 
 ```ruby
@@ -436,13 +460,13 @@ info.user_id
 
 ### 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):
+Using the new [Blob Data](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_insert_update_blob.htm) api feature (500mb limit):
 
 ```ruby
 client.create('Document', FolderId: '00lE0000000FJ6H',
                           Description: 'Document test',
                           Name: 'My image',
-                          Body: Restforce::UploadIO.new(File.expand_path('image.jpg', __FILE__), 'image/jpeg')
+                          Body: Restforce::FilePart.new(File.expand_path('image.jpg', __FILE__), 'image/jpeg')
 ```
 
 Using base64 encoded data (37.5mb limit):
@@ -454,7 +478,7 @@ client.create('Document', FolderId: '00lE0000000FJ6H',
                           Body: Base64::encode64(File.read('image.jpg'))
 ```
 
-_See also: [Inserting or updating blob data](http://www.salesforce.com/us/developer/docs/api_rest/Content/dome_sobject_insert_update_blob.htm)_
+_See also: [Inserting or updating blob data](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_insert_update_blob.htm)_
 
 * * *
 
@@ -473,11 +497,11 @@ document = client.query('select Id, Name, Body from Document').first
 File.open(document.Name, 'wb') { |f| f.write(document.Body) }
 ```
 
-**Note:** The example above is only applicable if your SOQL query returns a single Document record. If more than one record is returned, 
+**Note:** The example above is only applicable if your SOQL query returns a single Document record. If more than one record is returned,
 the Body field contains an URL to retrieve the BLOB content for the first 2000 records returned. Subsequent records contain the BLOB content
-in the Body field. This is confusing and hard to debug. See notes in [Issue #301](https://github.com/restforce/restforce/issues/301#issuecomment-298972959) explaining this detail. 
-**Executive Summary:** Don't retrieve the Body field in a SOQL query; instead, use the BLOB retrieval URL documented 
-in [SObject BLOB Retrieve](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_blob_retrieve.htm) 
+in the Body field. This is confusing and hard to debug. See notes in [Issue #301](https://github.com/restforce/restforce/issues/301#issuecomment-298972959) explaining this detail.
+**Executive Summary:** Don't retrieve the Body field in a SOQL query; instead, use the BLOB retrieval URL documented
+in [SObject BLOB Retrieve](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_blob_retrieve.htm)
 
 * * *
 
@@ -513,8 +537,10 @@ client.get('/services/apexrest/FieldCase', company: 'GenePoint')
 
 ### Streaming
 
-Restforce supports the [Streaming API](http://wiki.developerforce.com/page/Getting_Started_with_the_Force.com_Streaming_API), and makes implementing
-pub/sub with Salesforce a trivial task:
+Restforce supports the [Streaming API](https://trailhead.salesforce.com/en/content/learn/modules/api_basics/api_basics_streaming), and makes implementing
+pub/sub with Salesforce a trivial task.
+
+Here is an example of creating and subscribing to a `PushTopic`:
 
 ```ruby
 # Restforce uses faye as the underlying implementation for CometD.
@@ -523,7 +549,7 @@ require 'faye'
 # Initialize a client with your username/password/oauth token/etc.
 client = Restforce.new(username: 'foo',
                        password: 'bar',
-                       security_token: 'security token'
+                       security_token: 'security token',
                        client_id: 'client_id',
                        client_secret: 'client_secret')
 
@@ -538,7 +564,7 @@ client.create!('PushTopic',
 
 EM.run do
   # Subscribe to the PushTopic.
-  client.subscribe 'AllAccounts' do |message|
+  client.subscription '/topic/AllAccounts' do |message|
     puts message.inspect
   end
 end
@@ -547,7 +573,102 @@ end
 Boom, you're now receiving push notifications when Accounts are
 created/updated.
 
-_See also: [Force.com Streaming API docs](http://www.salesforce.com/us/developer/docs/api_streaming/index.htm)_
+#### Replaying Events
+
+Since API version 37.0, Salesforce stores events for 24 hours and they can be
+replayed if your application experienced some downtime.
+
+In order to replay past events, all you need to do is specify the last known
+event ID when subscribing and you will receive all events that happened since
+that event ID:
+
+```ruby
+EM.run {
+  # Subscribe to the PushTopic.
+  client.subscription '/topic/AllAccounts', replay: 10 do |message|
+    puts message.inspect
+  end
+}
+```
+
+In this specific case you will see events with replay ID 11, 12 and so on.
+
+There are two magic values for the replay ID accepted by Salesforce:
+
+* `-2`, for getting all the events that appeared in the last 24 hours
+* `-1`, for getting only newer events
+
+**Warning**: Only use a replay ID of a event from the last 24 hours otherwise
+Salesforce will not send anything, including newer events. If in doubt, use one
+of the two magic replay IDs mentioned above.
+
+You might want to store the replay ID in some sort of datastore so you can
+access it, for example between application restarts. In that case, there is the
+option of passing a custom replay handler which responds to `[]` and `[]=`.
+
+Below is a sample replay handler that stores the replay ID for each channel in
+memory using a Hash, stores a timestamp and has some rudimentary logic that
+will use one of the magic IDs depending on the value of the timestamp:
+
+```ruby
+class SimpleReplayHandler
+
+  MAX_AGE = 86_400 # 24 hours
+
+  INIT_REPLAY_ID = -1
+  DEFAULT_REPLAY_ID = -2
+
+  def initialize
+    @channels = {}
+    @last_modified = nil
+  end
+
+  # This method is called during the initial subscribe phase
+  # in order to send the correct replay ID.
+  def [](channel)
+    if @last_modified.nil?
+      puts "[#{channel}] No timestamp defined, sending magic replay ID #{INIT_REPLAY_ID}"
+
+      INIT_REPLAY_ID
+    elsif old_replay_id?
+      puts "[#{channel}] Old timestamp, sending magic replay ID #{DEFAULT_REPLAY_ID}"
+
+      DEFAULT_REPLAY_ID
+    else
+      @channels[channel]
+    end
+  end
+
+  def []=(channel, replay_id)
+    puts "[#{channel}] Writing replay ID: #{replay_id}"
+
+    @last_modified = Time.now
+    @channels[channel] = replay_id
+  end
+
+  def old_replay_id?
+    @last_modified.is_a?(Time) && Time.now - @last_modified > MAX_AGE
+  end
+end
+```
+
+In order to use it, simply pass the object as the value of the `replay` option
+of the subscription:
+
+```ruby
+EM.run {
+  # Subscribe to the PushTopic and use the custom replay handler to store any
+  # received replay ID.
+  client.subscription '/topic/AllAccounts', replay: SimpleReplayHandler.new do |message|
+    puts message.inspect
+  end
+}
+```
+
+_See also_:
+
+* [Force.com Streaming API docs](http://www.salesforce.com/us/developer/docs/api_streaming/index.htm)
+* [Message Durability docs](https://developer.salesforce.com/docs/atlas.en-us.api_streaming.meta/api_streaming/using_streaming_api_durability.htm)
 
 *Note:* Restforce's streaming implementation is known to be compatible with version `0.8.9` of the faye gem.
 
@@ -576,7 +697,23 @@ client.without_caching do
 end
 ```
 
-Caching is done on based on your authentication credentials, so cached responses will not be shared between different Salesforce logins.
+If you prefer to opt in to caching on a per-request, you can do so by using .with_caching and
+setting the `use_cache` config option to false:
+
+```ruby
+Restforce.configure do |config|
+  config.cache = Rails.cache
+  config.use_cache = false
+end
+```
+
+```ruby
+client.with_caching do
+  client.query('select Id from Account')
+end
+```
+
+Caching is done based on your authentication credentials, so cached responses will not be shared between different Salesforce logins.
 
 * * *
 

data/UPGRADING.md

@@ -0,0 +1,38 @@
+# Upgrading from Restforce 4.x to 5.x
+
+__There are three breaking changes introduced in Restforce 5.x__. In this guide, you'll learn about these changes and what you should check in your code to make sure that it will work with the latest version of the library.
+
+## Error classes are now defined up-front, rather than dynamically at runtime
+
+__Likelyhood of impact__: Moderate
+
+The Salesforce REST API can return a range of `errorCode`s representing different kinds of errors. To make these easy to
+handle in your code, we want to turn these into individual, specific exception classes in the `Restforce::ErrorCode` namespace that inherit from `Restforce:: ResponseError`.
+
+Up until now, these exception classes have been defined dynamically at runtime which has some disadvantages - see the [pull request](https://github.com/restforce/restforce/pull/551) for more details.
+
+In this version, we switch to defining them up-front in the code based on a list in the Salesforce documentation. There is a risk that we might have missed some errors which should be defined. If any errors are missed, they will be added in patch versions (e.g. `5.0.1`). 
+
+If your application won't run because you are referring to an exception class that no longer exists, or you see warnings logged anywhere, please [create an issue](https://github.com/restforce/restforce/issues/new?template=unhandled-salesforce-error.md&title=Unhandled+Salesforce+error%3A+%3Cinsert+error+code+here%3E).
+
+## Ruby 2.4 is no longer supported
+
+__Likelyhood of impact__: Moderate
+
+As of [5th April 2020](https://www.ruby-lang.org/en/news/2020/04/05/support-of-ruby-2-4-has-ended/), Ruby 2.4 is no longer officially supported as an active version of the Ruby language. That means that it will not receive patches and security fixes.
+
+Accordingly, we've dropped support for Ruby 2.4 and earlier in the Restforce library. It *may* be compatible, bu we don't guarantee this or enforce it with automated tests.
+
+Before you update to Restforce 5.x, you'll need to switch to Ruby 2.5 or later. The current version of Ruby at the time of wriing is 2.7.
+
+## `Restforce::UnauthorizedError` no longer inherits from `Restforce::Error`
+
+__Likelyhood of impact__: Low
+
+Previously, the `Restforce::UnauthorizedError` returned when the library couldn't authenticate with the Salesforce API inherits from `Restforce::Error`. So, if you used `rescue Restforce::Error` in your code, you'd catch these exceptions.
+
+We've now changed this exception class to inherit from `Faraday::ClientError` which allows the response body returned from the Salesforce API to be attached to the error.
+
+If you refer to `Restforce::Error` anywhere in your code, you should check whether you also need to take into account `Restforce::UnauthorizedError`.
+
+If you refer to `Faraday::ClientError` anywhere in your code, you should check that you want the case where Restforce can't authenticate to be included.

data/docker-compose.yml

@@ -0,0 +1,7 @@
+version: "3.6"
+services:
+  restforce:
+    build: .
+    image: restforce:dev
+    volumes:
+      - .:/srv

data/lib/restforce/abstract_client.rb

@@ -7,5 +7,6 @@ module Restforce
     include Restforce::Concerns::Authentication
     include Restforce::Concerns::Caching
     include Restforce::Concerns::API
+    include Restforce::Concerns::BatchAPI
   end
 end

data/lib/restforce/attachment.rb

@@ -17,6 +17,7 @@ module Restforce
 
     def ensure_body
       return true if self.Body?
+
       raise 'You need to query the Body for the record first.'
     end
   end

data/lib/restforce/collection.rb

@@ -12,12 +12,12 @@ module Restforce
     end
 
     # Yield each value on each page.
-    def each
+    def each(&block)
       @raw_page['records'].each { |record| yield Restforce::Mash.build(record, @client) }
 
       np = next_page
       while np
-        np.current_page.each { |record| yield record }
+        np.current_page.each(&block)
         np = np.next_page
       end
     end
@@ -33,6 +33,11 @@ module Restforce
     end
     alias length size
 
+    # Returns true if the size of the Collection is zero.
+    def empty?
+      size.zero?
+    end
+
     # Return array of the elements on the current page
     def current_page
       first(@raw_page['records'].size)

data/lib/restforce/concerns/api.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'erb'
 require 'uri'
 require 'restforce/concerns/verbs'
 
@@ -320,6 +321,7 @@ module Restforce
       def update!(sobject, attrs)
         id = attrs.fetch(attrs.keys.find { |k, v| k.to_s.casecmp('id').zero? }, nil)
         raise ArgumentError, 'ID field missing from provided attributes' unless id
+
         attrs_without_id = attrs.reject { |k, v| k.to_s.casecmp("id").zero? }
         api_patch "sobjects/#{sobject}/#{CGI.escape(id)}", attrs_without_id
         true
@@ -377,7 +379,8 @@ module Restforce
               api_post "sobjects/#{sobject}/#{field}", attrs
             end
           else
-            api_patch "sobjects/#{sobject}/#{field}/#{CGI.escape(external_id)}", attrs
+            api_patch "sobjects/#{sobject}/#{field}/" \
+                      "#{ERB::Util.url_encode(external_id)}", attrs
           end
 
         response.body.respond_to?(:fetch) ? response.body.fetch('id', true) : true
@@ -414,7 +417,7 @@ module Restforce
       # Returns true of the sobject was successfully deleted.
       # Raises an exception if an error is returned from Salesforce.
       def destroy!(sobject, id)
-        api_delete "sobjects/#{sobject}/#{CGI.escape(id)}"
+        api_delete "sobjects/#{sobject}/#{ERB::Util.url_encode(id)}"
         true
       end
 
@@ -428,9 +431,9 @@ module Restforce
       # Returns the Restforce::SObject sobject record.
       def find(sobject, id, field = nil)
         url = if field
-                "sobjects/#{sobject}/#{field}/#{CGI.escape(id)}"
+                "sobjects/#{sobject}/#{field}/#{ERB::Util.url_encode(id)}"
               else
-                "sobjects/#{sobject}/#{CGI.escape(id)}"
+                "sobjects/#{sobject}/#{ERB::Util.url_encode(id)}"
               end
         api_get(url).body
       end
@@ -446,9 +449,9 @@ module Restforce
       #
       def select(sobject, id, select, field = nil)
         path = if field
-                 "sobjects/#{sobject}/#{field}/#{CGI.escape(id)}"
+                 "sobjects/#{sobject}/#{field}/#{ERB::Util.url_encode(id)}"
                else
-                 "sobjects/#{sobject}/#{CGI.escape(id)}"
+                 "sobjects/#{sobject}/#{ERB::Util.url_encode(id)}"
                end
 
         path = "#{path}?fields=#{select.join(',')}" if select&.any?
@@ -507,7 +510,7 @@ module Restforce
 
       # Internal: Errors that should be rescued from in non-bang methods
       def exceptions
-        [Faraday::Error::ClientError]
+        [Faraday::Error]
       end
     end
   end

data/lib/restforce/concerns/authentication.rb

@@ -19,6 +19,8 @@ module Restforce
           Restforce::Middleware::Authentication::Password
         elsif oauth_refresh?
           Restforce::Middleware::Authentication::Token
+        elsif jwt?
+          Restforce::Middleware::Authentication::JWTBearer
         end
       end
 
@@ -38,6 +40,14 @@ module Restforce
           options[:client_id] &&
           options[:client_secret]
       end
+
+      # Internal: Returns true if jwt bearer token flow should be used for
+      # authentication.
+      def jwt?
+        options[:jwt_key] &&
+          options[:username] &&
+          options[:client_id]
+      end
     end
   end
 end

data/lib/restforce/concerns/base.rb

@@ -28,6 +28,8 @@ module Restforce
       #                                   password and oauth authentication
       #        :client_secret           - The oauth client secret to use.
       #
+      #        :jwt_key                 - The private key for JWT authentication
+      #
       #        :host                    - The String hostname to use during
       #                                   authentication requests
       #                                   (default: 'login.salesforce.com').
@@ -59,9 +61,9 @@ module Restforce
       def initialize(opts = {})
         raise ArgumentError, 'Please specify a hash of options' unless opts.is_a?(Hash)
 
-        @options = Hash[Restforce.configuration.options.map do |option|
+        @options = Restforce.configuration.options.map do |option|
           [option, Restforce.configuration.send(option)]
-        end]
+        end.to_h
 
         @options.merge! opts
         yield builder if block_given?

data/lib/restforce/concerns/batch_api.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'restforce/concerns/verbs'
+
+module Restforce
+  module Concerns
+    module BatchAPI
+      extend Restforce::Concerns::Verbs
+
+      define_verbs :post
+
+      def batch(halt_on_error: false)
+        subrequests = Subrequests.new(options)
+        yield(subrequests)
+        subrequests.requests.each_slice(25).map do |requests|
+          properties = {
+            batchRequests: requests,
+            haltOnError: halt_on_error
+          }
+          response = api_post('composite/batch', properties.to_json)
+          body = response.body
+          results = body['results']
+          if halt_on_error && body['hasErrors']
+            last_error_index = results.rindex { |result| result['statusCode'] != 412 }
+            last_error = results[last_error_index]
+            raise BatchAPIError, last_error['result'][0]['errorCode']
+          end
+          results.map(&:compact)
+        end.flatten
+      end
+
+      def batch!(&block)
+        batch(halt_on_error: true, &block)
+      end
+
+      class Subrequests
+        def initialize(options)
+          @options = options
+          @requests = []
+        end
+        attr_reader :options, :requests
+
+        def create(sobject, attrs)
+          requests << { method: 'POST', url: batch_api_path(sobject), richInput: attrs }
+        end
+
+        def update(sobject, attrs)
+          id = attrs.fetch(attrs.keys.find { |k, v| k.to_s.casecmp?('id') }, nil)
+          raise ArgumentError, 'Id field missing from attrs.' unless id
+
+          attrs_without_id = attrs.reject { |k, v| k.to_s.casecmp?('id') }
+          requests << {
+            method: 'PATCH',
+            url: batch_api_path("#{sobject}/#{id}"),
+            richInput: attrs_without_id
+          }
+        end
+
+        def destroy(sobject, id)
+          requests << { method: 'DELETE', url: batch_api_path("#{sobject}/#{id}") }
+        end
+
+        def upsert(sobject, ext_field, attrs)
+          raise ArgumentError, 'External id field missing.' unless ext_field
+
+          ext_id = attrs.fetch(attrs.keys.find { |k, v|
+            k.to_s.casecmp?(ext_field.to_s)
+          }, nil)
+          raise ArgumentError, 'External id missing from attrs.' unless ext_id
+
+          attrs_without_ext_id = attrs.reject { |k, v| k.to_s.casecmp?(ext_field) }
+          requests << {
+            method: 'PATCH',
+            url: batch_api_path("#{sobject}/#{ext_field}/#{ext_id}"),
+            richInput: attrs_without_ext_id
+          }
+        end
+
+        private
+
+        def batch_api_path(path)
+          "v#{options[:api_version]}/sobjects/#{path}"
+        end
+      end
+    end
+  end
+end

data/lib/restforce/concerns/caching.rb

@@ -15,6 +15,13 @@ module Restforce
         options.delete(:use_cache)
       end
 
+      def with_caching
+        options[:use_cache] = true
+        yield
+      ensure
+        options[:use_cache] = false
+      end
+
       private
 
       # Internal: Cache to use for the caching middleware

data/lib/restforce/concerns/canvas.rb

@@ -5,6 +5,7 @@ module Restforce
     module Canvas
       def decode_signed_request(signed_request)
         raise 'client_secret not set.' unless options[:client_secret]
+
         SignedRequest.decode(signed_request, options[:client_secret])
       end
     end

data/lib/restforce/concerns/connection.rb

@@ -72,9 +72,9 @@ module Restforce
       # Internal: Faraday Connection options
       def connection_options
         { request: {
-            timeout: options[:timeout],
-            open_timeout: options[:timeout]
-},
+          timeout: options[:timeout],
+          open_timeout: options[:timeout]
+        },
           proxy: options[:proxy_uri],
           ssl: options[:ssl] }
       end