restforce 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96f8f9560cf8a66a733f7755fd374d741191b7f8
-  data.tar.gz: bbcfa722aefa2285b4f632b98e4109fdb585041c
+  metadata.gz: 3352202fbc4460b9f83a50b93f32dce58142b7ad
+  data.tar.gz: a2680033dec036183f9fcb767cb4935f17ecad27
 SHA512:
-  metadata.gz: 207ba956da9189b584ae3e6362f0f46fe7cb877105d28b4550eb6c071f38aca8f8f326b04e4c7082ce129a719e2b56cb0870ae715e95eb3aee2b7ee0d027eaf0
-  data.tar.gz: fe5cf08c7d393d8720324a8aeceb80456b0ceda886df6cb1a185ab4b35516fe2cf89bacb0697af78fbe6da45c979320e4569d41f842f8d7c392f9fbe38f1d2e3
+  metadata.gz: 8ef0d7d4a741961ce17a76fb5b93e3906f216bbe7bea5dbe2598eead312571e859392e4a54f32414fda1cffb0ffca9a4a3e8283f9eb333baea58529e51d9f86a
+  data.tar.gz: b6f445ee78e3e217b9279b7958744281e9d16dcb5cb7e1606c1a1cdc7d6f462afc8c7278a1de4ce751fd929a8372d5fbdd22c19148bc504b64f6790f1e52cfdb

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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)

data/README.md

@@ -25,7 +25,7 @@ Features include:
 
 Add this line to your application's Gemfile:
 
-    gem 'restforce', '~> 3.0.1'
+    gem 'restforce', '~> 3.1.0'
 
 And then execute:
 
@@ -547,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 SimpleReplayHander
+
+  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.
 

data/lib/restforce/concerns/streaming.rb

@@ -9,7 +9,8 @@ module Restforce
       # block    - A block to run when a new message is received.
       #
       # Returns a Faye::Subscription
-      def subscribe(channels, &block)
+      def subscribe(channels, options = {}, &block)
+        Array(channels).each { |channel| replay_handlers[channel] = options[:replay] }
         faye.subscribe Array(channels).map { |channel| "/topic/#{channel}" }, &block
       end
 
@@ -32,6 +33,64 @@ module Restforce
           client.bind 'transport:up' do
             Restforce.log "[COMETD UP]"
           end
+
+          client.add_extension ReplayExtension.new(replay_handlers)
+        end
+      end
+
+      def replay_handlers
+        @_replay_handlers ||= {}
+      end
+
+      class ReplayExtension
+        def initialize(replay_handlers)
+          @replay_handlers = replay_handlers
+        end
+
+        def incoming(message, callback)
+          callback.call(message).tap do
+            channel = message.fetch('channel').gsub('/topic/', '')
+            replay_id = message.fetch('data', {}).fetch('event', {})['replayId']
+
+            handler = @replay_handlers[channel]
+            if !replay_id.nil? && !handler.nil? && handler.respond_to?(:[]=)
+              # remember the last replay_id for this channel
+              handler[channel] = replay_id
+            end
+          end
+        end
+
+        def outgoing(message, callback)
+          # Leave non-subscribe messages alone
+          unless message['channel'] == '/meta/subscribe'
+            return callback.call(message)
+          end
+
+          channel = message['subscription'].gsub('/topic/', '')
+
+          # Set the replay value for the channel
+          message['ext'] ||= {}
+          message['ext']['replay'] = {
+            "/topic/#{channel}" => replay_id(channel)
+          }
+
+          # Carry on and send the message to the server
+          callback.call message
+        end
+
+        private
+
+        def replay_id(channel)
+          handler = @replay_handlers[channel]
+          if handler.is_a?(Integer)
+            handler # treat it as a scalar
+          elsif handler.respond_to?(:[])
+            # Ask for the latest replayId for this channel
+            handler[channel]
+          else
+            # Just pass it along
+            handler
+          end
         end
       end
     end

data/lib/restforce/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Restforce
-  VERSION = '3.0.1'
+  VERSION = '3.1.0'
 end

data/spec/unit/concerns/streaming_spec.rb

@@ -17,6 +17,33 @@ describe Restforce::Concerns::Streaming, event_machine: true do
 
       client.subscribe(channels, &subscribe_block)
     end
+
+    context "replay_handlers" do
+      before {
+        faye_double.should_receive(:subscribe).at_least(1)
+        client.stub faye: faye_double
+      }
+
+      it 'registers nil handlers when no replay option is given' do
+        client.subscribe(channels, &subscribe_block)
+        client.replay_handlers.should eq('channel1' => nil, 'channel2' => nil)
+      end
+
+      it 'registers a replay_handler for each channel given' do
+        client.subscribe(channels, replay: -2, &subscribe_block)
+        client.replay_handlers.should eq('channel1' => -2, 'channel2' => -2)
+      end
+
+      it 'replaces earlier handlers in subsequent calls' do
+        client.subscribe(%w[channel1 channel2], replay: 2, &subscribe_block)
+        client.subscribe(%w[channel2 channel3], replay: 3, &subscribe_block)
+        client.replay_handlers.should eq(
+          'channel1' => 2,
+          'channel2' => 3,
+          'channel3' => 3
+        )
+      end
+    end
   end
 
   describe '.faye' do
@@ -42,6 +69,8 @@ describe Restforce::Concerns::Streaming, event_machine: true do
         faye_double.should_receive(:set_header).with('Authorization', 'OAuth secret2')
         faye_double.should_receive(:bind).with('transport:down').and_yield
         faye_double.should_receive(:bind).with('transport:up').and_yield
+        faye_double.should_receive(:add_extension).with \
+          kind_of(Restforce::Concerns::Streaming::ReplayExtension)
         subject
       end
     end
@@ -52,4 +81,87 @@ describe Restforce::Concerns::Streaming, event_machine: true do
       end
     end
   end
+
+  describe Restforce::Concerns::Streaming::ReplayExtension do
+    let(:handlers) { {} }
+    let(:extension) { Restforce::Concerns::Streaming::ReplayExtension.new(handlers) }
+
+    it 'sends nil without a specified handler' do
+      output = subscribe(extension, to: "channel1")
+      read_replay(output).should eq('/topic/channel1' => nil)
+    end
+
+    it 'with a scalar replay id' do
+      handlers['channel1'] = -2
+      output = subscribe(extension, to: "channel1")
+      read_replay(output).should eq('/topic/channel1' => -2)
+    end
+
+    it 'with a hash' do
+      hash_handler = { 'channel1' => -1, 'channel2' => -2 }
+
+      handlers['channel1'] = hash_handler
+      handlers['channel2'] = hash_handler
+
+      output = subscribe(extension, to: "channel1")
+      read_replay(output).should eq('/topic/channel1' => -1)
+
+      output = subscribe(extension, to: "channel2")
+      read_replay(output).should eq('/topic/channel2' => -2)
+    end
+
+    it 'with an object' do
+      custom_handler = double('custom_handler')
+      custom_handler.should_receive(:[]).and_return(123)
+      handlers['channel1'] = custom_handler
+
+      output = subscribe(extension, to: "channel1")
+      read_replay(output).should eq('/topic/channel1' => 123)
+    end
+
+    it 'remembers the last replayId' do
+      handler = { 'channel1' => 41 }
+      handlers['channel1'] = handler
+      message = {
+        'channel' => '/topic/channel1',
+        'data' => {
+          'event' => { 'replayId' => 42 }
+        }
+      }
+
+      extension.incoming(message, ->(m) {})
+      handler.should eq('channel1' => 42)
+    end
+
+    it 'when an incoming message has no replayId' do
+      handler = { 'channel1' => 41 }
+      handlers['channel1'] = handler
+
+      message = {
+        'channel' => '/topic/channel1',
+        'data' => {}
+      }
+
+      extension.incoming(message, ->(m) {})
+      handler.should eq('channel1' => 41)
+    end
+
+    private
+
+    def subscribe(extension, options = {})
+      output = nil
+      message = {
+        'channel' => '/meta/subscribe',
+        'subscription' => "/topic/#{options[:to]}"
+      }
+      extension.outgoing(message, ->(m) {
+        output = m
+      })
+      output
+    end
+
+    def read_replay(message)
+      message.fetch('ext', {})['replay']
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Eric J. Holmes
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-04 00:00:00.000000000 Z
+date: 2018-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday