restforce 2.5.4 → 4.0.0

data/CONTRIBUTING.md

@@ -1,11 +1,11 @@
 # Contributing
 
 We love pull requests from everyone. By participating in this project, you
-agree to abide by our [code of conduct](https://github.com/ejholmes/restforce/blob/master/CODE_OF_CONDUCT.md).
+agree to abide by our [code of conduct](https://github.com/restforce/restforce/blob/master/CODE_OF_CONDUCT.md).
 
 Fork, then clone the repo:
 
-    git clone git@github.com:ejholmes/restforce.git
+    git clone git@github.com:restforce/restforce.git
 
 Set up your machine:
 
@@ -23,7 +23,7 @@ Make your change. Add tests for your change. Make the tests pass:
 
     script/test
 
-Push to your fork and [submit a pull request](https://github.com/ejholmes/restforce/compare/).
+Push to your fork and [submit a pull request](https://github.com/restforce/restforce/compare/).
 
 At this point you're waiting on us. We like to at least comment on pull requests
 within a few days. We may suggest

data/Gemfile

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 gemspec
 
+gem 'faraday', '~> 0.17.0'
+gem 'jruby-openssl', platforms: :jruby
 gem 'rake'
-gem 'jruby-openssl', :platforms => :jruby
-gem 'faraday', '~> 0.11.0'
 
 group :development do
   gem 'guard-rspec'

data/Guardfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 guard 'rspec', cmd: 'bundle exec rspec', all_on_start: false, all_after_pass: false do
   watch(%r{^spec/.+_spec\.rb$})
   watch('spec/spec_helper.rb') { "spec" }
@@ -8,6 +10,6 @@ guard 'rspec', cmd: 'bundle exec rspec', all_on_start: false, all_after_pass: fa
 end
 
 guard :rubocop, all_on_start: false do
-  watch(%r{.+\.rb$})
+  watch(/.+\.rb$/)
   watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
 end

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Eric J. Holmes
+Copyright (c) 2018 Eric J. Holmes and Tim Rogers
 
 MIT License
 

data/README.md

@@ -1,6 +1,6 @@
 # Restforce
 
-[![travis-ci](https://travis-ci.org/ejholmes/restforce.png?branch=master)](https://travis-ci.org/ejholmes/restforce) [![Code Climate](https://codeclimate.com/github/ejholmes/restforce.png)](https://codeclimate.com/github/ejholmes/restforce) [![Dependency Status](https://gemnasium.com/ejholmes/restforce.png)](https://gemnasium.com/ejholmes/restforce)
+[![CircleCI](https://circleci.com/gh/restforce/restforce.svg?style=svg)](https://circleci.com/gh/restforce/restforce) [![Code Climate](https://codeclimate.com/github/restforce/restforce.png)](https://codeclimate.com/github/restforce/restforce) [![Dependency Status](https://gemnasium.com/restforce/restforce.png)](https://gemnasium.com/restforce/restforce)
 ![](https://img.shields.io/gem/dt/restforce.svg)
 
 Restforce is a ruby gem for the [Salesforce REST api](http://www.salesforce.com/us/developer/docs/api_rest/index.htm).
@@ -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/ejholmes/restforce/tree/master/CHANGELOG.md)
+[Official Website](http://restforce.org/) | [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', '~> 2.5.3'
+    gem 'restforce', '~> 4.0.0'
 
 And then execute:
 
@@ -35,15 +35,15 @@ Or install it yourself as:
 
     $ gem install restforce
 
-__As of [version 2.5.0](https://github.com/ejholmes/restforce/blob/master/CHANGELOG.md#250-dec-5-2016), this gem is only compatible with Ruby 2.0.0 and later.__ To use Ruby 1.9.3, you'll need to manually specify that you wish to use version 2.4.2, or 1.5.3 for Ruby 1.9.2 support.
+__As of [version 4.0.0](https://github.com/restforce/restforce/blob/master/CHANGELOG.md#400-oct-9-2019), this gem is only compatible with Ruby 2.4.0 and later.__ You'll need to use version 3.2.0 or earlier if you're running on Ruby 2.3. If you're running on Ruby 2.2, 2.1 or 2.0, use version 2.5.3 or earlier. For Ruby 1.9.3, you'll need to manually specify that you wish to 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 2.3.0 to 3.0.0 would be allowed to include incompatible API changes). See the [changelog](https://github.com/ejholmes/restforce/tree/master/CHANGELOG.md) for details on what has changed in each version.
+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.
 
 ## Usage
 
 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
 
@@ -63,7 +63,7 @@ It is also important to note that the client object should not be reused across
 ```ruby
 client = Restforce.new(oauth_token: 'access_token',
                        instance_url: 'instance url',
-                       api_version: '38.0')
+                       api_version: '41.0')
 ```
 
 Although the above will work, you'll probably want to take advantage of the (re)authentication middleware by specifying `refresh_token`, `client_id`, `client_secret`, and `authentication_callback`:
@@ -75,7 +75,7 @@ client = Restforce.new(oauth_token: 'access_token',
                        client_id: 'client_id',
                        client_secret: 'client_secret',
                        authentication_callback: Proc.new { |x| Rails.logger.debug x.to_s },
-                       api_version: '38.0')
+                       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.
@@ -108,7 +108,7 @@ client = Restforce.new(username: 'foo',
                        security_token: 'security token',
                        client_id: 'client_id',
                        client_secret: 'client_secret',
-                       api_version: '38.0')
+                       api_version: '41.0')
 ```
 
 You can also set the username, password, security token, client ID, client
@@ -120,7 +120,7 @@ export SALESFORCE_PASSWORD="password"
 export SALESFORCE_SECURITY_TOKEN="security token"
 export SALESFORCE_CLIENT_ID="client id"
 export SALESFORCE_CLIENT_SECRET="client secret"
-export SALESFORCE_API_VERSION="38.0"
+export SALESFORCE_API_VERSION="41.0"
 ```
 
 ```ruby
@@ -138,7 +138,7 @@ client = Restforce.new(username: 'foo',
                        client_id: 'client_id',
                        client_secret: 'client_secret',
                        proxy_uri: 'http://proxy.example.com:123',
-                       api_version: '38.0')
+                       api_version: '41.0')
 ```
 
 You may specify a username and password for the proxy with a URL along the lines of 'http://user:password@proxy.example.com:123'.
@@ -168,19 +168,19 @@ end
 
 By default, the gem defaults to using Version 26.0 (Winter '13) of the Salesforce API. This maintains backwards compatibility for existing users.
 
-__We strongly suggest configuring Restforce to use the most recent API version, currently Version 38.0 (Winter '17) to get the best Salesforce API experience__ - for example, some more recently-added API endpoints will not be available without moving to a more recent
+__We strongly suggest configuring Restforce to use the most recent API version, currently Version 41.0 (Winter '18) to get the best Salesforce API experience__ - for example, some more recently-added API endpoints will not be available without moving to a more recent
 version. If you're trying to use a method that is unavailable with your API version,
 Restforce will raise an `APIVersionError`.
 
 There are three ways to set the API version:
 
-* Passing in an `api_version` option when instantiating `Restforce` (i.e. `Restforce.new(api_version: '38.0')`)
-* Setting the `SALESFORCE_API_VERSION` environment variable (i.e. `export SALESFORCE_API_VERSION="38.0"`)
+* Passing in an `api_version` option when instantiating `Restforce` (i.e. `Restforce.new(api_version: '41.0')`)
+* Setting the `SALESFORCE_API_VERSION` environment variable (i.e. `export SALESFORCE_API_VERSION="41.0"`)
 * Configuring the version globally with `Restforce.configure`:
 
 ```ruby
 Restforce.configure do |config|
-  config.api_version = '38.0'
+  config.api_version = '41.0'
   # ...
 end
 ```
@@ -206,7 +206,7 @@ to include the `sforce-auto-assign` header in all client HTTP requests:
 ```ruby
 client = Restforce.new(oauth_token: 'access_token',
                        instance_url: 'instance url',
-                       api_version: '38.0',
+                       api_version: '41.0',
                        request_headers: { 'sforce-auto-assign' => 'FALSE' })
 
 ```
@@ -473,6 +473,12 @@ 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, 
+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) 
+
 * * *
 
 ### Custom Apex REST endpoints
@@ -517,7 +523,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')
 
@@ -541,7 +547,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.subscribe '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.subscribe '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.
 
@@ -645,7 +746,7 @@ Callbacks.
 
 We welcome all contributions - they help us make Restforce the best gem possible.
 
-See our [CONTRIBUTING.md](https://github.com/ejholmes/restforce/blob/master/CONTRIBUTING.md) file for help with getting set up to work on the project locally.
+See our [CONTRIBUTING.md](https://github.com/restforce/restforce/blob/master/CONTRIBUTING.md) file for help with getting set up to work on the project locally.
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/Rakefile

@@ -1,4 +1,5 @@
-#!/usr/bin/env rake
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 
 task default: [:spec]

data/lib/restforce.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'faraday'
 require 'faraday_middleware'
 require 'json'
@@ -27,6 +29,7 @@ module Restforce
     autoload :Verbs,          'restforce/concerns/verbs'
     autoload :Base,           'restforce/concerns/base'
     autoload :API,            'restforce/concerns/api'
+    autoload :BatchAPI,       'restforce/concerns/batch_api'
   end
 
   module Data
@@ -42,6 +45,25 @@ module Restforce
   AuthenticationError = Class.new(Error)
   UnauthorizedError   = Class.new(Error)
   APIVersionError     = Class.new(Error)
+  BatchAPIError       = Class.new(Error)
+
+  # Inherit from Faraday::Error::ResourceNotFound for backwards-compatibility
+  # Consumers of this library that rescue and handle Faraday::Error::ResourceNotFound
+  # can continue to do so.
+  NotFoundError       = Class.new(Faraday::Error::ResourceNotFound)
+
+  # Inherit from Faraday::Error::ClientError for backwards-compatibility
+  # Consumers of this library that rescue and handle Faraday::Error::ClientError
+  # can continue to do so.
+  ResponseError       = Class.new(Faraday::Error::ClientError)
+  MatchesMultipleError= Class.new(ResponseError)
+  EntityTooLargeError = Class.new(ResponseError)
+
+  module ErrorCode
+    def self.const_missing(constant_name)
+      const_set constant_name, Class.new(ResponseError)
+    end
+  end
 
   class << self
     # Alias for Restforce::Data::Client.new
@@ -72,7 +94,7 @@ module Restforce
       self
     end
   end
-  Object.send :include, Restforce::CoreExtensions unless Object.respond_to? :tap
+  Object.include Restforce::CoreExtensions unless Object.respond_to? :tap
 end
 
 if ENV['PROXY_URI']

data/lib/restforce/abstract_client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Restforce
   class AbstractClient
     include Restforce::Concerns::Base
@@ -5,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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Restforce
   class Attachment < Restforce::SObject
     # Public: Returns the body of the attachment.
@@ -15,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/client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Restforce
   Client = Data::Client
 end

data/lib/restforce/collection.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Restforce
   class Collection
     include Enumerable
@@ -29,7 +31,7 @@ module Restforce
     def size
       @raw_page['totalSize']
     end
-    alias_method :length, :size
+    alias length size
 
     # Return array of the elements on the current page
     def current_page

data/lib/restforce/concerns/api.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+require 'erb'
 require 'uri'
 require 'restforce/concerns/verbs'
 
@@ -81,7 +84,7 @@ module Restforce
       def get_updated(sobject, start_time, end_time)
         start_time = start_time.utc.iso8601
         end_time = end_time.utc.iso8601
-        url = "/sobjects/#{sobject}/updated/?start=#{start_time}&end=#{end_time}"
+        url = "sobjects/#{sobject}/updated/?start=#{start_time}&end=#{end_time}"
         api_get(url).body
       end
 
@@ -101,7 +104,7 @@ module Restforce
       def get_deleted(sobject, start_time, end_time)
         start_time = start_time.utc.iso8601
         end_time = end_time.utc.iso8601
-        url = "/sobjects/#{sobject}/deleted/?start=#{start_time}&end=#{end_time}"
+        url = "sobjects/#{sobject}/deleted/?start=#{start_time}&end=#{end_time}"
         api_get(url).body
       end
 
@@ -265,7 +268,7 @@ module Restforce
       rescue *exceptions
         false
       end
-      alias_method :insert, :create
+      alias insert create
 
       # Public: Insert a new record.
       #
@@ -283,7 +286,7 @@ module Restforce
       def create!(sobject, attrs)
         api_post("sobjects/#{sobject}", attrs).body['id']
       end
-      alias_method :insert!, :create!
+      alias insert! create!
 
       # Public: Update a record.
       #
@@ -316,8 +319,9 @@ module Restforce
       # Returns true if the sobject was successfully updated.
       # Raises an exception if an error is returned from Salesforce.
       def update!(sobject, attrs)
-        id = attrs.fetch(attrs.keys.find { |k, v| k.to_s.downcase == 'id' }, nil)
+        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
@@ -363,7 +367,7 @@ module Restforce
       def upsert!(sobject, field, attrs)
         attrs = attrs.dup
         external_id =
-          extract_case_insensitive_string_or_symbol_key_from_hash!(attrs, field)
+          extract_case_insensitive_string_or_symbol_key_from_hash!(attrs, field).to_s
         if field.to_s != "Id" && (external_id.nil? || external_id.strip.empty?)
           raise ArgumentError, 'Specified external ID field missing from provided ' \
                                'attributes'
@@ -375,10 +379,11 @@ 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 && response.body['id']) ? response.body['id'] : true
+        response.body.respond_to?(:fetch) ? response.body.fetch('id', true) : true
       end
 
       # Public: Delete a record.
@@ -412,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
 
@@ -426,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
@@ -444,11 +449,12 @@ 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 << "?fields=#{select.join(',')}" if select && select.any?
+
+        path = "#{path}?fields=#{select.join(',')}" if select&.any?
 
         api_get(path).body
       end