restforce 3.0.1 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 96f8f9560cf8a66a733f7755fd374d741191b7f8
-  data.tar.gz: bbcfa722aefa2285b4f632b98e4109fdb585041c
+SHA256:
+  metadata.gz: d1eb25f3f88951d1770c5850c41a9d673d3b0406a76d0c35e54288d52ee5dc00
+  data.tar.gz: 51af3a7a4a1e701a4f5e8a79c21452ca5417581aa889188e7f5b5e010fb8f39a
 SHA512:
-  metadata.gz: 207ba956da9189b584ae3e6362f0f46fe7cb877105d28b4550eb6c071f38aca8f8f326b04e4c7082ce129a719e2b56cb0870ae715e95eb3aee2b7ee0d027eaf0
-  data.tar.gz: fe5cf08c7d393d8720324a8aeceb80456b0ceda886df6cb1a185ab4b35516fe2cf89bacb0697af78fbe6da45c979320e4569d41f842f8d7c392f9fbe38f1d2e3
+  metadata.gz: eabc94739d7bbdb2e88fcf3b2ff4bfb3c0b4272f74f50d6fef3f549ca559cd52ab212b5fbd6988da0237257aef7d092b4f654e275a797beb28947b268263f07d
+  data.tar.gz: 56ac8e739182f941a45cffe4c8b28364d8b99243128c8c7864820e15e752785af3938c8f99377e3428dcc9a61ac98a72703850675455cc88effe5b68bdca454b

data/.circleci/config.yml

@@ -34,23 +34,23 @@ references:
         destination: test-results
 
 jobs:
-  build-ruby251:
+  build-ruby265:
     docker:
-       - image: circleci/ruby:2.5.1
+       - image: circleci/ruby:2.6.5
     steps: *steps
-  build-ruby244:
+  build-ruby257:
     docker:
-       - image: circleci/ruby:2.4.4
+       - image: circleci/ruby:2.5.7
     steps: *steps
-  build-ruby237:
+  build-ruby249:
     docker:
-       - image: circleci/ruby:2.3.7
+       - image: circleci/ruby:2.4.9
     steps: *steps
 
 workflows:
   version: 2
   tests:
     jobs:
-      - build-ruby251
-      - build-ruby244
-      - build-ruby237
+      - build-ruby265
+      - build-ruby257
+      - build-ruby249

data/.rubocop.yml

@@ -4,46 +4,44 @@ inherit_from: .rubocop_todo.yml
 
 AllCops:
   DisplayCopNames: true
-  Include:
-    - Rakefile
   Exclude:
     - .*/**/*
     - vendor/**/*
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 2.4
 
 # Limit lines to 80 characters.
-LineLength:
+Metrics/LineLength:
   Max: 90
 
-ClassLength:
+Metrics/ClassLength:
   Enabled: false
 
-ModuleLength:
+Metrics/ModuleLength:
   Enabled: false
 
 # Avoid methods longer than 30 lines of code
-MethodLength:
+Metrics/MethodLength:
   CountComments: false  # count full line comments?
   Max: 87
 
 # Avoid single-line methods.
-SingleLineMethods:
+Style/SingleLineMethods:
   AllowIfMethodIsEmpty: true
 
-StringLiterals:
+Style/StringLiterals:
   Enabled: false
 
-GlobalVars:
+Style/GlobalVars:
   Enabled: false # We use them Redis + StatsD (though maybe we shouldn't?)
 
 # Wants underscores in all large numbers. Pain in the ass for things like
 # unix timestamps.
-NumericLiterals:
+Style/NumericLiterals:
   Enabled: false
 
 # Wants you to use the same argument names for every reduce. This seems kinda
 # naff compared to naming them semantically
-SingleLineBlockParams:
+Style/SingleLineBlockParams:
   Enabled: false
 
 Style/SignalException:

data/.rubocop_todo.yml

@@ -1,117 +1,164 @@
-# This configuration was generated by `rubocop --auto-gen-config`
-# on 2015-06-06 22:47:07 +0100 using RuboCop version 0.32.0.
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2019-10-09 21:39:40 +0100 using RuboCop version 0.75.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 50
+# Offense count: 17
 # Cop supports --auto-correct.
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/AlignHash:
+  Exclude:
+    - 'lib/restforce/middleware/logger.rb'
+    - 'restforce.gemspec'
+    - 'spec/integration/abstract_client_spec.rb'
+    - 'spec/unit/config_spec.rb'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: special_inside_parentheses, consistent, align_braces
+Layout/IndentFirstHashElement:
+  Exclude:
+    - 'lib/restforce/concerns/connection.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: AllowForAlignment.
+Layout/SpaceAroundOperators:
+  Exclude:
+    - 'lib/restforce.rb'
+
+# Offense count: 8
+# Cop supports --auto-correct.
+# Configuration parameters: IgnoreEmptyBlocks, AllowUnusedKeywordArguments.
 Lint/UnusedBlockArgument:
-  Enabled: false
+  Exclude:
+    - 'lib/restforce/concerns/api.rb'
+    - 'lib/restforce/concerns/batch_api.rb'
+    - 'lib/restforce/middleware/multipart.rb'
+    - 'spec/unit/config_spec.rb'
 
-# Offense count: 187
+# Offense count: 9
 Metrics/AbcSize:
-  Max: 61
+  Max: 38
 
-# Offense count: 26
+# Offense count: 1
 Metrics/CyclomaticComplexity:
-  Max: 10
+  Max: 8
 
-# Offense count: 11
+# Offense count: 1
 Metrics/PerceivedComplexity:
-  Max: 10
+  Max: 9
 
-# Offense count: 12
-Naming/AccessorMethodName:
-  Enabled: false
-
-# Offense count: 164
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle, SupportedLastArgumentHashStyles.
-Layout/AlignHash:
-  Enabled: false
+# Offense count: 5
+# Configuration parameters: EnforcedStyleForLeadingUnderscores.
+# SupportedStylesForLeadingUnderscores: disallowed, required, optional
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - 'lib/restforce/concerns/picklists.rb'
+    - 'lib/restforce/concerns/streaming.rb'
+
+# Offense count: 2
+# Configuration parameters: NamePrefix, NamePrefixBlacklist, NameWhitelist, MethodDefinitionMacros.
+# NamePrefix: is_, has_, have_
+# NamePrefixBlacklist: is_, has_, have_
+# NameWhitelist: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicateName:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/restforce/collection.rb'
+    - 'lib/restforce/middleware/multipart.rb'
 
-# Offense count: 3
+# Offense count: 12
 # Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, SupportedStyles, ProceduralMethods, FunctionalMethods, IgnoredMethods.
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, IgnoredMethods, AllowBracesOnProceduralOneLiners.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# IgnoredMethods: lambda, proc, it
 Style/BlockDelimiters:
-  Enabled: false
+  Exclude:
+    - 'lib/restforce/concerns/batch_api.rb'
+    - 'spec/support/event_machine.rb'
+    - 'spec/support/middleware.rb'
+    - 'spec/unit/concerns/base_spec.rb'
+    - 'spec/unit/concerns/batch_api_spec.rb'
+    - 'spec/unit/concerns/caching_spec.rb'
+    - 'spec/unit/concerns/streaming_spec.rb'
+    - 'spec/unit/middleware/authentication_spec.rb'
+    - 'spec/unit/middleware/mashify_spec.rb'
 
-# Offense count: 128
-# Configuration parameters: EnforcedStyle, SupportedStyles.
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-# Offense count: 21
-# Cop supports --auto-correct.
-Layout/ClosingParenthesisIndentation:
-  Enabled: false
-
-# Offense count: 13
+# Offense count: 12
 # Cop supports --auto-correct.
-# Configuration parameters: Keywords.
-Style/CommentAnnotation:
-  Enabled: false
-
-# Offense count: 743
+# Configuration parameters: AutoCorrect, EnforcedStyle.
+# SupportedStyles: nested, compact
+Style/ClassAndModuleChildren:
+  Exclude:
+    - 'lib/restforce/middleware/authentication.rb'
+    - '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/custom_headers.rb'
+    - 'lib/restforce/middleware/gzip.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'
+
+# Offense count: 36
 Style/Documentation:
   Enabled: false
 
-# Offense count: 9
+# Offense count: 3
 Style/DoubleNegation:
-  Enabled: false
+  Exclude:
+    - 'lib/restforce/concerns/picklists.rb'
+    - 'lib/restforce/middleware/instance_url.rb'
 
-# Offense count: 109
+# Offense count: 1
 # Configuration parameters: MinBodyLength.
 Style/GuardClause:
-  Enabled: false
-
-# Offense count: 48
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, SupportedStyles.
-Layout/IndentHash:
-  Enabled: false
+  Exclude:
+    - 'lib/restforce/middleware/authentication.rb'
 
-# Offense count: 70
+# Offense count: 25
 # Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: line_count_dependent, lambda, literal
 Style/Lambda:
-  Enabled: false
-
-# Offense count: 577
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, SupportedStyles.
-Layout/MultilineOperationIndentation:
-  Enabled: false
-
-# Offense count: 21
-# Configuration parameters: NamePrefix, NamePrefixBlacklist.
-Naming/PredicateName:
-  Enabled: false
+  Exclude:
+    - 'lib/restforce/config.rb'
+    - 'spec/integration/abstract_client_spec.rb'
+    - 'spec/unit/concerns/base_spec.rb'
+    - 'spec/unit/concerns/streaming_spec.rb'
+    - 'spec/unit/middleware/authentication_spec.rb'
+    - 'spec/unit/middleware/authorization_spec.rb'
+    - 'spec/unit/middleware/custom_headers_spec.rb'
+    - 'spec/unit/middleware/gzip_spec.rb'
+    - 'spec/unit/middleware/instance_url_spec.rb'
+    - 'spec/unit/middleware/logger_spec.rb'
+    - 'spec/unit/sobject_spec.rb'
 
-# Offense count: 4
-# Cop supports --auto-correct.
-Style/Proc:
-  Enabled: false
-
-# Offense count: 173
+# Offense count: 5
 # Cop supports --auto-correct.
 Style/RedundantSelf:
-  Enabled: false
+  Exclude:
+    - 'lib/restforce/mash.rb'
+    - 'lib/restforce/sobject.rb'
 
-# Offense count: 28
-# Cop supports --auto-correct.
-Layout/SpaceBeforeFirstArg:
-  Enabled: false
-
-# Offense count: 3
-# Cop supports --auto-correct.
-# Configuration parameters: MultiSpaceAllowedForOperators.
-Layout/SpaceAroundOperators:
-  Enabled: false
-
-# Offense count: 5
+# Offense count: 1
 # Cop supports --auto-correct.
 # Configuration parameters: ExactNameMatch, AllowPredicates, AllowDSLWriters, IgnoreClassMethods, Whitelist.
+# Whitelist: to_ary, to_a, to_c, to_enum, to_h, to_hash, to_i, to_int, to_io, to_open, to_path, to_proc, to_r, to_regexp, to_str, to_s, to_sym
 Style/TrivialAccessors:
-  Enabled: false
+  Exclude:
+    - 'lib/restforce/middleware.rb'

data/CHANGELOG.md

@@ -1,16 +1,45 @@
+## 4.2.0 (Oct 23, 2019)
+
+* Add support for platform events, CDC, generic events, etc. in the Streaming API (@nathanKramer)
+
+## 4.1.0 (Oct 20, 2019)
+
+* Add support for JWT authentication (@nathanKramer, @tagCincy)
+
+## 4.0.0 (Oct 9, 2019)
+
+* __Deprecate support for Ruby 2.3__, since [Ruby 2.3 reached its end-of-life](https://www.ruby-lang.org/en/news/2019/03/31/support-of-ruby-2-3-has-ended/) in March 2019. (This is the only breaking change included in this version.)
+
+## 3.2.0 (Oct 9, 2019)
+
+* Add support for the Batch API (@gaiottino, @teoulas)
+* Return specific exceptions for errors that might be returned from Salesforce.com - instead of getting a generic `Faraday::Error::ClientError`, you might get something like a `Restforce::EntityTooLargeError` (@boblail)
+* Expose the full response in exceptions' messages to make debugging easier (@boblail)
+* Properly escape IDs with spaces in them when working with existing records (@pushups)
+
+## 3.1.0 (Aug 16, 2018)
+
+* Add support for replaying missed messages when using the Salesforce Streaming API (@andreimaxim, @drteeth, @panozzaj)
+
 ## 3.0.1 (Aug 4, 2018)
 
 * Fix `NoMethodError` when upserting an existing record (@opti)
 
 ## 3.0.0 (Aug 2, 2018)
 
-* __Deprecate support for Ruby 2.0, 2.1 and 2.2__, since [even Ruby 2.2 reached its end-of-life]##(https://www.ruby-lang.org/en/news/2018/06/20/support-of-ruby-2-2-has-ended/) in June 2018. (This is the only breaking change included in this version.)
+* __Deprecate support for Ruby 2.0, 2.1 and 2.2__, since [even Ruby 2.2 reached its end-of-life](https://www.ruby-lang.org/en/news/2018/06/20/support-of-ruby-2-2-has-ended/) in June 2018. (This is the only breaking change included in this version.)
 * Fix `NoMethodError` when trying to upsert a record using a `Fixnum` as the external ID (@AlexandruCD)
 * Escape record IDs passed in to the client to identify records to find, delete, etc. (@jmdx)
 * Stop relying on our middleware for Gzip compression if you're using `httpclient`, since Faraday enables this automatically using `httpclient`'s built-in support (@shivanshgaur)
 * Fix `get_updated` and `get_deleted` API calls by removing the erroneous leading forward slash from the path (@scottolsen)
 * Fix unpacking of dependent picklist options (@parkm)
 
+## 2.5.4 (May 15, 2019)
+
+See the [`v2`](https://github.com/restforce/restforce/tree/v2) branch for this release.
+
+* Escape record IDs passed in to the client to identify records to find, delete, etc. (@jmdx, @apanzerj)
+
 ## 2.5.3 (Apr 25, 2017)
 
 * Raise an error where a custom external ID field name is supplied to `upsert` and `upsert!`, but it is missing from the provided attributes (@velveret)

data/Gemfile

@@ -3,8 +3,9 @@
 source 'https://rubygems.org'
 gemspec
 
-gem 'faraday', '~> 0.15.0'
+gem 'faraday', '~> 0.17.0'
 gem 'jruby-openssl', platforms: :jruby
+gem 'jwt'
 gem 'rake'
 
 group :development do

data/README.md

@@ -25,7 +25,7 @@ Features include:
 
 Add this line to your application's Gemfile:
 
-    gem 'restforce', '~> 3.0.1'
+    gem 'restforce', '~> 4.2.0'
 
 And then execute:
 
@@ -35,7 +35,7 @@ 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 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 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,7 +43,7 @@ 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
 
@@ -111,6 +111,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:
 
@@ -473,11 +488,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 +528,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 +540,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 +555,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 +564,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.