ably 1.1.8 → 1.2.0

data/lib/ably/rest/channel.rb

@@ -28,21 +28,20 @@ module Ably
       #
       # @param client [Ably::Rest::Client]
       # @param name [String] The name of the channel
-      # @param channel_options [Hash] Channel options, currently reserved for Encryption options
-      # @option channel_options [Hash,Ably::Models::CipherParams]   :cipher   A hash of options or a {Ably::Models::CipherParams} to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +:cipher+ options
+      # @param channel_options [Hash, Ably::Models::ChannelOptions]     A hash of options or a {Ably::Models::ChannelOptions}
       #
       def initialize(client, name, channel_options = {})
         name = (ensure_utf_8 :name, name)
 
-        update_options channel_options
+        @options = Ably::Models::ChannelOptions(channel_options)
         @client  = client
         @name    = name
         @push    = PushChannel.new(self)
       end
 
-      # Publish one or more messages to the channel. Three overloaded forms
+      # Publish one or more messages to the channel. Five overloaded forms
       # @param name [String, Array<Ably::Models::Message|Hash>, Ably::Models::Message, nil]   The event name of the message to publish, or an Array of [Ably::Model::Message] objects or [Hash] objects with +:name+ and +:data+ pairs, or a single Ably::Model::Message object
-      # @param data [String, ByteArray, Hash, nil]   The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument, in which case an optional hash of query parameters
+      # @param data [String, Array, Hash, nil]   The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument, in which case an optional hash of query parameters
       # @param attributes [Hash, nil]   Optional additional message attributes such as :extras, :id, :client_id or :connection_id, applied when name attribute is nil or a string (Deprecated, will be removed in 2.0 in favour of constructing a Message object)
       # @return [Boolean]  true if the message was published, otherwise false
       #
@@ -50,42 +49,33 @@ module Ably
       #   # Publish a single message with (name, data) form
       #   channel.publish 'click', { x: 1, y: 2 }
       #
-      #   # Publish an array of message Hashes
+      #   # Publish a single message with single Hash form
+      #   message = { name: 'click', data: { x: 1, y: 2 } }
+      #   channel.publish message
+      #
+      #   # Publish an array of message Hashes form
       #   messages = [
       #     { name: 'click', data: { x: 1, y: 2 } },
       #     { name: 'click', data: { x: 2, y: 3 } }
       #   ]
       #   channel.publish messages
       #
-      #   # Publish an array of Ably::Models::Message objects
+      #   # Publish an array of Ably::Models::Message objects form
       #   messages = [
-      #     Ably::Models::Message(name: 'click', { x: 1, y: 2 })
-      #     Ably::Models::Message(name: 'click', { x: 2, y: 3 })
+      #     Ably::Models::Message(name: 'click', data: { x: 1, y: 2 })
+      #     Ably::Models::Message(name: 'click', data: { x: 2, y: 3 })
       #   ]
       #   channel.publish messages
       #
-      #   # Publish a single Ably::Models::Message object, with a query params
-      #   # specifying quickAck: true
-      #   message = Ably::Models::Message(name: 'click', { x: 1, y: 2 })
-      #   channel.publish message, quickAck: 'true'
+      #   # Publish a single Ably::Models::Message object form
+      #   message = Ably::Models::Message(name: 'click', data: { x: 1, y: 2 })
+      #   channel.publish message
       #
-      def publish(first, second = nil, third = {})
-        messages, qs_params = if first.kind_of?(Enumerable)
-          # ([Message], qs_params) form
-          [first, second]
-        elsif first.kind_of?(Ably::Models::Message)
-          # (Message, qs_params) form
-          [[first], second]
-        else
-          # (name, data, attributes) form
-          first = ensure_utf_8(:name, first, allow_nil: true)
-          ensure_supported_payload second
-          # RSL1h - attributes as an extra method parameter is extra-spec but need to
-          # keep it for backcompat until version 2
-          [[{ name: first, data: second }.merge(third)], nil]
-        end
+      def publish(name, data = nil, attributes = {})
+        qs_params = nil
+        qs_params = data if name.kind_of?(Enumerable) || name.kind_of?(Ably::Models::Message)
 
-        messages.map! { |message| Ably::Models::Message(message.dup) }
+        messages = build_messages(name, data, attributes) # (RSL1a, RSL1b)
 
         if messages.sum(&:size) > (max_message_size = client.max_message_size || Ably::Rest::Client::MAX_MESSAGE_SIZE)
           raise Ably::Exceptions::MaxMessageSizeExceeded.new("Maximum message size exceeded #{max_message_size} bytes.")
@@ -163,14 +153,16 @@ module Ably
         @presence ||= Presence.new(client, self)
       end
 
-      # @api private
-      def update_options(channel_options)
-        @options = channel_options.clone.freeze
+      # Sets or updates the stored channel options. (#RSL7)
+      # @param channel_options [Hash, Ably::Models::ChannelOptions]  A hash of options or a {Ably::Models::ChannelOptions}
+      # @return [Ably::Models::ChannelOptions]
+      def set_options(channel_options)
+        @options = Ably::Models::ChannelOptions(channel_options)
       end
-      alias set_options update_options # (RSL7)
-      alias options= update_options
+      alias options= set_options
 
       private
+
       def base_path
         "/channels/#{URI.encode_www_form_component(name)}"
       end

data/lib/ably/rest/client.rb

@@ -199,10 +199,13 @@ module Ably
         @custom_tls_port     = options.delete(:tls_port)
         @add_request_ids     = options.delete(:add_request_ids)
         @log_retries_as_info = options.delete(:log_retries_as_info)
-        @idempotent_rest_publishing = options.delete(:idempotent_rest_publishing) || Ably.major_minor_version_numeric > 1.1
         @max_message_size    = options.delete(:max_message_size) || MAX_MESSAGE_SIZE
         @max_frame_size      = options.delete(:max_frame_size) || MAX_FRAME_SIZE
 
+        if (@idempotent_rest_publishing = options.delete(:idempotent_rest_publishing)).nil?
+          @idempotent_rest_publishing = Ably::PROTOCOL_VERSION.to_f > 1.1
+        end
+
         if options[:fallback_hosts_use_default] && options[:fallback_hosts]
           raise ArgumentError, "fallback_hosts_use_default cannot be set to try when fallback_hosts is also provided"
         end

data/lib/ably/util/crypto.rb

@@ -30,7 +30,7 @@ module Ably::Util
     #    crypto.decrypt(decrypted) # => 'secret text'
     #
     def initialize(params)
-      @fixed_iv = params.delete(:fixed_iv) if params.kind_of?(Hash)
+      @fixed_iv = params[:fixed_iv]
       @cipher_params = Ably::Models::CipherParams(params)
     end
 

data/lib/ably/version.rb

@@ -1,6 +1,6 @@
 module Ably
-  VERSION = '1.1.8'
-  PROTOCOL_VERSION = '1.1'
+  VERSION = '1.2.0'
+  PROTOCOL_VERSION = '1.2'
 
   # @api private
   def self.major_minor_version_numeric

data/spec/acceptance/realtime/channel_spec.rb

@@ -117,6 +117,94 @@ describe Ably::Realtime::Channel, :event_machine do
           end
         end
 
+        context 'context when channel options contain modes' do
+          before do
+            channel.options = { modes: %i[publish] }
+          end
+
+          it 'sends an ATTACH with options as flags (#RTL4l)' do
+            connection.once(:connected) do
+              client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                next if protocol_message.action != :attach
+
+                expect(protocol_message.has_attach_publish_flag?).to eq(true)
+                stop_reactor
+              end
+
+              channel.attach
+            end
+          end
+
+          context 'when channel is reattaching' do
+            it 'sends ATTACH_RESUME flag along with other modes (RTL4j)' do
+              channel.attach do
+                channel.on(:suspended) do
+                  client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                    next if protocol_message.action != :attach
+
+                    expect(protocol_message.has_attach_resume_flag?).to eq(true)
+                    expect(protocol_message.has_attach_publish_flag?).to eq(true)
+                    stop_reactor
+                  end
+
+                  client.connection.connect
+                end
+                client.connection.transition_state_machine :suspended
+              end
+            end
+          end
+        end
+
+        context 'context when channel options contain params' do
+          let(:params) do
+            { foo: 'foo', bar: 'bar'}
+          end
+
+          before do
+            channel.options = { params: params }
+          end
+
+          it 'sends an ATTACH with params (#RTL4k)' do
+            connection.once(:connected) do
+              client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                next if protocol_message.action != :attach
+
+                expect(protocol_message.params).to eq(params)
+                stop_reactor
+              end
+
+              channel.attach
+            end
+          end
+        end
+
+        context 'when received attached' do
+          it 'decodes flags and sets it as modes on channel options (#RTL4m)'do
+            channel.on(:attached) do
+              expect(channel.options.modes.map(&:to_sym)).to eq(%i[subscribe])
+              stop_reactor
+            end
+
+            channel.transition_state_machine(:attaching)
+            attached_message = Ably::Models::ProtocolMessage.new(action: 11, channel: channel_name, flags: 262144)
+            client.connection.__incoming_protocol_msgbus__.publish :protocol_message, attached_message
+          end
+
+          it 'set params as channel options params (#RTL4k1)' do
+            params = { param: :something }
+
+            channel.on(:attached) do
+              expect(channel.params).to eq(channel.options.params)
+              expect(channel.params).to eq(params)
+              stop_reactor
+            end
+
+            channel.transition_state_machine(:attaching)
+            attached_message = Ably::Models::ProtocolMessage.new(action: 11, channel: channel_name, params: params)
+            client.connection.__incoming_protocol_msgbus__.publish :protocol_message, attached_message
+          end
+        end
+
         it 'implicitly attaches the channel (#RTL7c)' do
           expect(channel).to be_initialized
           channel.subscribe { |message| }
@@ -368,6 +456,42 @@ describe Ably::Realtime::Channel, :event_machine do
           end
         end
       end
+
+      describe 'clean attach (RTL4j)' do
+        context "when channel wasn't previously attached" do
+          it "doesn't send ATTACH_RESUME" do
+            client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+              next if protocol_message.action != :attach
+
+              expect(protocol_message.has_attach_resume_flag?).to eq(false)
+              stop_reactor
+            end
+
+            channel.attach
+          end
+        end
+
+        context "when channel was explicitly detached" do
+          it "doesn't send ATTACH_RESUME" do
+            channel.once(:detached) do
+              client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                next if protocol_message.action != :attach
+
+                expect(protocol_message.has_attach_resume_flag?).to eq(false)
+                stop_reactor
+              end
+
+              channel.attach
+            end
+
+            channel.once(:attached) do
+              channel.detach
+            end
+
+            channel.attach
+          end
+        end
+      end
     end
 
     describe '#detach' do
@@ -1936,15 +2060,33 @@ describe Ably::Realtime::Channel, :event_machine do
             end
           end
 
-          it 'transitions state automatically to :attaching once the connection is re-established (#RTN15c3)' do
-            channel.attach do
-              channel.on(:suspended) do
-                client.connection.connect
-                channel.once(:attached) do
-                  stop_reactor
+          describe 'reattaching (#RTN15c3)' do
+            it 'transitions state automatically to :attaching once the connection is re-established ' do
+              channel.attach do
+                channel.on(:suspended) do
+                  client.connection.connect
+                  channel.once(:attached) do
+                    stop_reactor
+                  end
                 end
+                client.connection.transition_state_machine :suspended
+              end
+            end
+
+            it 'sends ATTACH_RESUME flag when reattaching (RTL4j)' do
+              channel.attach do
+                channel.on(:suspended) do
+                  client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                    next if protocol_message.action != :attach
+
+                    expect(protocol_message.has_attach_resume_flag?).to eq(true)
+                    stop_reactor
+                  end
+
+                  client.connection.connect
+                end
+                client.connection.transition_state_machine :suspended
               end
-              client.connection.transition_state_machine :suspended
             end
           end
         end
@@ -2134,6 +2276,68 @@ describe Ably::Realtime::Channel, :event_machine do
       end
     end
 
+    describe '#set_options (#RTL16a)' do
+      let(:modes) { %i[subscribe] }
+      let(:channel_options) do
+        { modes: modes }
+      end
+
+      def self.build_flags(flags)
+        flags.map { |flag| Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[flag] }.reduce(:|)
+      end
+
+      shared_examples 'an update that sends ATTACH message' do |state, flags|
+        it 'sends an ATTACH message on options change' do
+          attach_sent = nil
+
+          client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+            if protocol_message.action == :attach && protocol_message.flags.nonzero?
+              attach_sent = true
+              expect(protocol_message.flags).to eq(flags)
+            end
+          end
+
+          channel.once(state) do
+            channel.options = channel_options
+          end
+
+          channel.on(:attached) do
+            client.connection.__incoming_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+              next if protocol_message.action != :attached
+
+              expect(attach_sent).to eq(true)
+              stop_reactor
+            end
+          end
+
+          channel.attach
+        end
+      end
+
+      context 'when channel is attaching' do
+        it_behaves_like 'an update that sends ATTACH message', :attaching, build_flags(%i[subscribe])
+      end
+
+      context 'when channel is attaching' do
+        it_behaves_like 'an update that sends ATTACH message', :attached, build_flags(%i[resume subscribe])
+      end
+
+      context 'when channel is initialized' do
+        it "doesn't send ATTACH message" do
+          client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+            raise "Unexpected message" if protocol_message.action == :attach
+          end
+
+          channel.options = channel_options
+          expect(channel.options.modes.map(&:to_sym)).to eq(modes)
+
+          EventMachine.next_tick do
+            stop_reactor
+          end
+        end
+      end
+    end
+
     context 'channel state change' do
       it 'emits a ChannelStateChange object' do
         channel.on(:attached) do |channel_state_change|
@@ -2375,11 +2579,20 @@ describe Ably::Realtime::Channel, :event_machine do
       end
 
       context 'and channel is attached' do
-        it 'reattaches immediately (#RTL13a)' do
-          channel.attach do
+        it 'reattaches immediately (#RTL13a) with ATTACH_RESUME flag(RTL4j)' do
+          resume_flag = false
+
+          channel.once(:attached) do
+            client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+              next if protocol_message.action != :attach
+
+              resume_flag = protocol_message.has_attach_resume_flag?
+            end
+
             channel.once(:attaching) do |state_change|
               expect(state_change.reason.code).to eql(50505)
               channel.once(:attached) do
+                expect(resume_flag).to eq(true)
                 stop_reactor
               end
             end
@@ -2387,26 +2600,39 @@ describe Ably::Realtime::Channel, :event_machine do
             detach_message = Ably::Models::ProtocolMessage.new(action: detached_action, channel: channel_name, error: { code: 50505 })
             client.connection.__incoming_protocol_msgbus__.publish :protocol_message, detach_message
           end
+
+          channel.attach
         end
       end
 
       context 'and channel is suspended' do
-        it 'reattaches immediately (#RTL13a)' do
-          channel.attach do
-            channel.once(:suspended) do
-              channel.once(:attaching) do |state_change|
-                expect(state_change.reason.code).to eql(50505)
-                channel.once(:attached) do
-                  stop_reactor
-                end
-              end
+        it 'reattaches immediately (#RTL13a) with ATTACH_RESUME flag(RTL4j)' do
+          resume_flag = false
 
-              detach_message = Ably::Models::ProtocolMessage.new(action: detached_action, channel: channel_name, error: { code: 50505 })
-              client.connection.__incoming_protocol_msgbus__.publish :protocol_message, detach_message
+          channel.once(:attached) do
+            channel.transition_state_machine! :suspended
+          end
+
+          channel.once(:suspended) do
+            client.connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+              next if protocol_message.action != :attach
+
+              resume_flag = protocol_message.has_attach_resume_flag?
             end
 
-            channel.transition_state_machine! :suspended
+            channel.once(:attaching) do |state_change|
+              expect(state_change.reason.code).to eql(50505)
+              channel.once(:attached) do
+                expect(resume_flag).to eq(true)
+                stop_reactor
+              end
+            end
+
+            detach_message = Ably::Models::ProtocolMessage.new(action: detached_action, channel: channel_name, error: { code: 50505 })
+            client.connection.__incoming_protocol_msgbus__.publish :protocol_message, detach_message
           end
+
+          channel.attach
         end
 
         context 'when connection is no longer connected' do

data/spec/acceptance/realtime/channels_spec.rb

@@ -10,17 +10,56 @@ describe Ably::Realtime::Channels, :event_machine do
     end
 
     it 'returns channel object and passes the provided options' do
-      expect(channel_with_options.options).to eql(options)
+      expect(channel_options).to be_a(Ably::Models::ChannelOptions)
+      expect(channel_options.to_h).to eq(options)
       stop_reactor
     end
   end
 
   vary_by_protocol do
+    let(:client_options) do
+      { key: api_key, environment: environment, protocol: protocol }
+    end
     let(:client) do
-      auto_close Ably::Realtime::Client.new(key: api_key, environment: environment, protocol: protocol)
+      auto_close Ably::Realtime::Client.new(client_options)
     end
     let(:channel_name) { random_str }
-    let(:options)      { { key: 'value' } }
+    let(:options) do
+      { params: { key: 'value' } }
+    end
+
+    subject(:channel_options) { channel_with_options.options }
+
+    context 'when channel supposed to trigger reattachment per RTL16a (#RTS3c1)' do
+      it 'will raise an error' do
+        channel = client.channels.get(channel_name, options)
+
+        channel.on(:attached) do
+          expect { client.channels.get(channel_name, { modes: [] }) }.to raise_error ArgumentError, /use Channel#set_options directly/
+          stop_reactor
+        end
+
+        channel.attach
+      end
+
+      context 'params keys are the same but values are different' do
+        let(:options)      do
+          { params: { x: '1' } }
+        end
+
+        it 'will raise an error' do
+          channel = client.channels.get(channel_name, options)
+
+          channel.on(:attached) do
+            expect { client.channels.get(channel_name, { params: { x: '2' } }) }.to raise_error ArgumentError, /use Channel#set_options directly/
+
+            stop_reactor
+          end
+
+          channel.attach
+        end
+      end
+    end
 
     describe 'using shortcut method #channel on the client object' do
       let(:channel) { client.channel(channel_name) }
@@ -35,26 +74,39 @@ describe Ably::Realtime::Channels, :event_machine do
     end
 
     describe 'accessing an existing channel object with different options' do
+      let(:client_options)  { super().merge(logger: custom_logger_object) }
+      let(:custom_logger_object) { TestLogger.new }
       let(:new_channel_options) { { encrypted: true } }
-      let(:original_channel)    { client.channels.get(channel_name, options) }
+      let!(:original_channel)    { client.channels.get(channel_name, options) }
 
       it 'overrides the existing channel options and returns the channel object' do
-        expect(original_channel.options).to_not include(:encrypted)
+        expect(original_channel.options.to_h).to_not include(:encrypted)
         new_channel = client.channels.get(channel_name, new_channel_options)
         expect(new_channel).to be_a(Ably::Realtime::Channel)
         expect(new_channel.options[:encrypted]).to eql(true)
         stop_reactor
       end
+
+      it 'shows deprecation warning' do
+        client.channels.get(channel_name, new_channel_options)
+
+        warning = custom_logger_object.logs.find do |severity, message|
+          message.match(/Using this method to update channel options is deprecated and may be removed/)
+        end
+
+        expect(warning).to_not be_nil
+        stop_reactor
+      end
     end
 
     describe 'accessing an existing channel object without specifying any channel options' do
       let(:original_channel) { client.channels.get(channel_name, options) }
 
       it 'returns the existing channel without modifying the channel options' do
-        expect(original_channel.options).to eql(options)
+        expect(original_channel.options.to_h).to eq(options)
         new_channel = client.channels.get(channel_name)
         expect(new_channel).to be_a(Ably::Realtime::Channel)
-        expect(original_channel.options).to eql(options)
+        expect(original_channel.options.to_h).to eq(options)
         stop_reactor
       end
     end

data/spec/acceptance/realtime/connection_spec.rb

@@ -2083,7 +2083,7 @@ describe Ably::Realtime::Connection, :event_machine do
       it 'sends the protocol version param v (#G4, #RTN2f)' do
         expect(EventMachine).to receive(:connect) do |host, port, transport, object, url|
           uri = URI.parse(url)
-          expect(CGI::parse(uri.query)['v'][0]).to eql('1.1')
+          expect(CGI::parse(uri.query)['v'][0]).to eql('1.2')
           stop_reactor
         end
         client

data/spec/acceptance/realtime/message_spec.rb

@@ -75,6 +75,83 @@ describe 'Ably::Realtime::Channel Message', :event_machine do
       end
     end
 
+    context 'a single Message object (#RSL1a)' do
+      let(:name) { random_str }
+      let(:data) { random_str }
+      let(:message) { Ably::Models::Message.new(name: name, data: data) }
+
+      it 'publishes the message' do
+        channel.attach
+        channel.publish(message)
+        channel.subscribe do |msg|
+          expect(msg.name).to eq(message.name)
+          expect(msg.data).to eq(message.data)
+          stop_reactor
+        end
+      end
+    end
+
+    context 'an array of Message objects (#RSL1a)' do
+      let(:data) { random_str }
+      let(:message1) { Ably::Models::Message.new(name: random_str, data: data) }
+      let(:message2) { Ably::Models::Message.new(name: random_str, data: data) }
+      let(:message3) { Ably::Models::Message.new(name: random_str, data: data) }
+
+      it 'publishes three messages' do
+        channel.attach
+        channel.publish([message1, message2, message3])
+        counter = 0
+        channel.subscribe do |message|
+          counter += 1
+          expect(message.data).to eq(data)
+          expect(message.name).to eq(message1.name) if counter == 1
+          expect(message.name).to eq(message2.name) if counter == 2
+          if counter == 3
+            expect(message.name).to eq(message3.name)
+            stop_reactor
+          end
+        end
+      end
+    end
+
+    context 'an array of hashes (#RSL1a)' do
+      let(:data) { random_str }
+      let(:message1) { { name: random_str, data: data } }
+      let(:message2) { { name: random_str, data: data } }
+      let(:message3) { { name: random_str, data: data } }
+
+      it 'publishes three messages' do
+        channel.attach
+        channel.publish([message1, message2, message3])
+        counter = 0
+        channel.subscribe do |message|
+          counter += 1
+          expect(message.data).to eq(data)
+          expect(message.name).to eq(message1[:name]) if counter == 1
+          expect(message.name).to eq(message2[:name]) if counter == 2
+          if counter == 3
+            expect(message.name).to eq(message3[:name])
+            stop_reactor
+          end
+        end
+      end
+    end
+
+    context 'a name with data payload (#RSL1a, #RSL1b)' do
+      let(:name) { random_str }
+      let(:data) { random_str }
+
+      it 'publishes a message' do
+        channel.attach
+        channel.publish(name, data)
+        channel.subscribe do |message|
+          expect(message.name).to eql(name)
+          expect(message.data).to eq(data)
+          stop_reactor
+        end
+      end
+    end
+
     context 'with supported extra payload content type (#RTL6h, #RSL6a2)' do
       let(:channel) { client.channel("pushenabled:#{random_str}") }