restforce 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4d4058f81fe1d435976494baa2c81caa57515d21f1ffcb0784286d5a608af39
-  data.tar.gz: ddd80cd062c00f2c9d249e63e2cec5103da55a225c42d443e4370c2d234fae36
+  metadata.gz: d1eb25f3f88951d1770c5850c41a9d673d3b0406a76d0c35e54288d52ee5dc00
+  data.tar.gz: 51af3a7a4a1e701a4f5e8a79c21452ca5417581aa889188e7f5b5e010fb8f39a
 SHA512:
-  metadata.gz: 2b37491f67c8f1494aa849b6118c6b5d0bcfae35ebc5f8e313c68d1989fd4fda486ff661a8dfb74181526958b6baa8cff2b477b7297bdeb9bf98a6e44becfb1f
-  data.tar.gz: c046776763a2d2bc13890f6c64241052d25d8e1ded812770ef99aa7df407662065f9bbc349c94d902a66cf71d400770b63dd964a355ea9d2cd57cffe3500156f
+  metadata.gz: eabc94739d7bbdb2e88fcf3b2ff4bfb3c0b4272f74f50d6fef3f549ca559cd52ab212b5fbd6988da0237257aef7d092b4f654e275a797beb28947b268263f07d
+  data.tar.gz: 56ac8e739182f941a45cffe4c8b28364d8b99243128c8c7864820e15e752785af3938c8f99377e3428dcc9a61ac98a72703850675455cc88effe5b68bdca454b

data/CHANGELOG.md

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

data/README.md

@@ -25,7 +25,7 @@ Features include:
 
 Add this line to your application's Gemfile:
 
-    gem 'restforce', '~> 4.1.0'
+    gem 'restforce', '~> 4.2.0'
 
 And then execute:
 
@@ -528,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.
@@ -553,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
@@ -574,7 +576,7 @@ that event ID:
 ```ruby
 EM.run {
   # Subscribe to the PushTopic.
-  client.subscribe 'AllAccounts', replay: 10 do |message|
+  client.subscription '/topic/AllAccounts', replay: 10 do |message|
     puts message.inspect
   end
 }
@@ -648,7 +650,7 @@ of the subscription:
 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|
+  client.subscription '/topic/AllAccounts', replay: SimpleReplayHandler.new do |message|
     puts message.inspect
   end
 }

data/lib/restforce/concerns/streaming.rb

@@ -5,13 +5,28 @@ module Restforce
     module Streaming
       # Public: Subscribe to a PushTopic
       #
-      # channels - The name of the PushTopic channel(s) to subscribe to.
+      # topics   - The name of the PushTopic channel(s) to subscribe to.
       # block    - A block to run when a new message is received.
       #
       # Returns a Faye::Subscription
-      def subscribe(channels, options = {}, &block)
-        Array(channels).each { |channel| replay_handlers[channel] = options[:replay] }
-        faye.subscribe Array(channels).map { |channel| "/topic/#{channel}" }, &block
+      def legacy_subscribe(topics, options = {}, &block)
+        topics = Array(topics).map { |channel| "/topic/#{channel}" }
+        subscription(topics, options, &block)
+      end
+      alias subscribe legacy_subscribe
+
+      # Public: Subscribe to one or more Streaming API channels
+      #
+      # channels - The name of the Streaming API (cometD) channel(s) to subscribe to.
+      # block    - A block to run when a new message is received.
+      #
+      # Returns a Faye::Subscription
+      def subscription(channels, options = {}, &block)
+        one_or_more_channels = Array(channels)
+        one_or_more_channels.each do |channel|
+          replay_handlers[channel] = options[:replay]
+        end
+        faye.subscribe(one_or_more_channels, &block)
       end
 
       # Public: Faye client to use for subscribing to PushTopics
@@ -49,7 +64,7 @@ module Restforce
 
         def incoming(message, callback)
           callback.call(message).tap do
-            channel = message.fetch('channel').gsub('/topic/', '')
+            channel = message.fetch('channel')
             replay_id = message.fetch('data', {}).fetch('event', {})['replayId']
 
             handler = @replay_handlers[channel]
@@ -64,12 +79,12 @@ module Restforce
           # Leave non-subscribe messages alone
           return callback.call(message) unless message['channel'] == '/meta/subscribe'
 
-          channel = message['subscription'].gsub('/topic/', '')
+          channel = message['subscription']
 
           # Set the replay value for the channel
           message['ext'] ||= {}
           message['ext']['replay'] = {
-            "/topic/#{channel}" => replay_id(channel)
+            channel => replay_id(channel)
           }
 
           # Carry on and send the message to the server

data/lib/restforce/version.rb

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

data/spec/unit/concerns/streaming_spec.rb

@@ -4,18 +4,19 @@ require 'spec_helper'
 
 describe Restforce::Concerns::Streaming, event_machine: true do
   describe '.subscribe' do
-    let(:channels)        { %w[channel1 channel2] }
-    let(:topics)          { channels.map { |c| "/topic/#{c}" } }
+    let(:channels) do
+      ['/topic/topic1', '/event/MyCustomEvent__e', '/data/ChangeEvents']
+    end
     let(:subscribe_block) { lambda { 'subscribe' } }
     let(:faye_double)     { double('Faye') }
 
     it 'subscribes to the topics with faye' do
       faye_double.
         should_receive(:subscribe).
-        with(topics, &subscribe_block)
+        with(channels, &subscribe_block)
       client.stub faye: faye_double
 
-      client.subscribe(channels, &subscribe_block)
+      client.subscription(channels, &subscribe_block)
     end
 
     context "replay_handlers" do
@@ -25,24 +26,51 @@ describe Restforce::Concerns::Streaming, event_machine: true do
       }
 
       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)
+        client.subscription(channels, &subscribe_block)
+        client.replay_handlers.should eq(
+          '/topic/topic1' => nil,
+          '/event/MyCustomEvent__e' => nil,
+          '/data/ChangeEvents' => 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)
+        client.subscription(channels, replay: -2, &subscribe_block)
+        client.replay_handlers.should eq(
+          '/topic/topic1' => -2,
+          '/event/MyCustomEvent__e' => -2,
+          '/data/ChangeEvents' => -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.subscription(
+          ['/topic/channel1', '/topic/channel2'],
+          replay: 2,
+          &subscribe_block
+        )
+        client.subscription(
+          ['/topic/channel2', '/topic/channel3'],
+          replay: 3,
+          &subscribe_block
+        )
+
         client.replay_handlers.should eq(
-          'channel1' => 2,
-          'channel2' => 3,
-          'channel3' => 3
+          '/topic/channel1' => 2,
+          '/topic/channel2' => 3,
+          '/topic/channel3' => 3
         )
       end
+
+      context 'backwards compatibility' do
+        it 'it assumes channels are push topics' do
+          client.subscribe(%w[channel1 channel2], replay: -2, &subscribe_block)
+          client.replay_handlers.should eq(
+            '/topic/channel1' => -2,
+            '/topic/channel2' => -2
+          )
+        end
+      end
     end
   end
 
@@ -87,41 +115,41 @@ describe Restforce::Concerns::Streaming, event_machine: true do
     let(:extension) { Restforce::Concerns::Streaming::ReplayExtension.new(handlers) }
 
     it 'sends nil without a specified handler' do
-      output = subscribe(extension, to: "channel1")
+      output = subscribe(extension, to: "/topic/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")
+      handlers['/topic/channel1'] = -2
+      output = subscribe(extension, to: "/topic/channel1")
       read_replay(output).should eq('/topic/channel1' => -2)
     end
 
     it 'with a hash' do
-      hash_handler = { 'channel1' => -1, 'channel2' => -2 }
+      hash_handler = { '/topic/channel1' => -1, '/topic/channel2' => -2 }
 
-      handlers['channel1'] = hash_handler
-      handlers['channel2'] = hash_handler
+      handlers['/topic/channel1'] = hash_handler
+      handlers['/topic/channel2'] = hash_handler
 
-      output = subscribe(extension, to: "channel1")
+      output = subscribe(extension, to: "/topic/channel1")
       read_replay(output).should eq('/topic/channel1' => -1)
 
-      output = subscribe(extension, to: "channel2")
+      output = subscribe(extension, to: "/topic/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
+      handlers['/topic/channel1'] = custom_handler
 
-      output = subscribe(extension, to: "channel1")
+      output = subscribe(extension, to: "/topic/channel1")
       read_replay(output).should eq('/topic/channel1' => 123)
     end
 
     it 'remembers the last replayId' do
-      handler = { 'channel1' => 41 }
-      handlers['channel1'] = handler
+      handler = { '/topic/channel1' => 41 }
+      handlers['/topic/channel1'] = handler
       message = {
         'channel' => '/topic/channel1',
         'data' => {
@@ -130,12 +158,12 @@ describe Restforce::Concerns::Streaming, event_machine: true do
       }
 
       extension.incoming(message, ->(m) {})
-      handler.should eq('channel1' => 42)
+      handler.should eq('/topic/channel1' => 42)
     end
 
     it 'when an incoming message has no replayId' do
-      handler = { 'channel1' => 41 }
-      handlers['channel1'] = handler
+      handler = { '/topic/channel1' => 41 }
+      handlers['/topic/channel1'] = handler
 
       message = {
         'channel' => '/topic/channel1',
@@ -143,7 +171,7 @@ describe Restforce::Concerns::Streaming, event_machine: true do
       }
 
       extension.incoming(message, ->(m) {})
-      handler.should eq('channel1' => 41)
+      handler.should eq('/topic/channel1' => 41)
     end
 
     private
@@ -152,7 +180,7 @@ describe Restforce::Concerns::Streaming, event_machine: true do
       output = nil
       message = {
         'channel' => '/meta/subscribe',
-        'subscription' => "/topic/#{options[:to]}"
+        'subscription' => options[:to]
       }
       extension.outgoing(message, ->(m) {
         output = m

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Eric J. Holmes
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-20 00:00:00.000000000 Z
+date: 2019-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday