ably 1.1.8 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba8f2b01b35fceead7297645f54cb854017e14c8a004882d5b414becc450feef
-  data.tar.gz: c116cce13d8ed06a9858e252a81918530d54f15e1a20c4b3ef30e5334408ec1b
+  metadata.gz: f42d74184e0de100d535fa3c01595727b78a6d2cd6018d1743e2593c20fe7ed7
+  data.tar.gz: db674f894bc006187816c0e51df19b84a7473d178b8360271a27640e7b3e4f6e
 SHA512:
-  metadata.gz: e0761591d9f838201f208c3d44d8068ad77c87591e737083cab548e77a104a6d7bd2da2cc360e01ad661c33f3af09220813ad19fe7d93f6759a7a88de82180d9
-  data.tar.gz: ca14639736fc07b1d00323df0073b37e0e2f51d6a2681bf868173708aafd45a89fbc872d4c16c600a41ebea9488c336a5422bdddbf8b80daa912ce9ef231945c
+  metadata.gz: 5950df21ad66e4c59eb6bd772ab71aa91b421679139166ddaa9076ea4fc7cc9a6eb9993a3f4e15e30a2d362a05c008587b153617c967da6a41aa6e0efdc3f091
+  data.tar.gz: a9d61d9b6c12397df274f55028a1fcbd6c285235cb489027188c799949466a6a74c4e6ea3829bd44851be48af14e05a2f7d49494ea61d1ea190176773079df23

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Change Log
 
+## [v1.2.0](https://github.com/ably/ably-ruby/tree/v1.2.0)
+
+[Full Changelog](https://github.com/ably/ably-ruby/compare/v1.1.8...v1.2.0)
+
+This release updates ably-ruby to be compliant with the 1.2 version of the Ably client library feature specification. There are some minor breaking changes, please see [the migration guide](./UPDATING.md) for more information.
+
+**Closed issues:**
+
+- create migration guide for the upgrade to ruby 1.2  [\#347](https://github.com/ably/ably-ruby/issues/347)
+- Write spec tests for RTL17 [\#304](https://github.com/ably/ably-ruby/issues/304)
+- Write spec tests for RTL16, RTL16a [\#303](https://github.com/ably/ably-ruby/issues/303)
+- Write spec tests for RTL4m [\#302](https://github.com/ably/ably-ruby/issues/302)
+- Write spec tests for RTL4l [\#301](https://github.com/ably/ably-ruby/issues/301)
+- Write spec tests for RTL4k, RTL4k1 [\#300](https://github.com/ably/ably-ruby/issues/300)
+- Write spec tests for RTL4j, RTL4j1, RTL4j2 [\#299](https://github.com/ably/ably-ruby/issues/299)
+- Write spec tests for RTS3c, RTS3c1 [\#298](https://github.com/ably/ably-ruby/issues/298)
+- Write spec tests for RTS3a [\#297](https://github.com/ably/ably-ruby/issues/297)
+- Add support for RTL21 [\#296](https://github.com/ably/ably-ruby/issues/296)
+- Add support for RTL17 [\#292](https://github.com/ably/ably-ruby/issues/292)
+- Add support for RTL16, RTL16a [\#291](https://github.com/ably/ably-ruby/issues/291)
+- Add support for RTL4m [\#290](https://github.com/ably/ably-ruby/issues/290)
+- Add support for RTL4l [\#289](https://github.com/ably/ably-ruby/issues/289)
+- Add support for RTL4k, RTL4k1 [\#288](https://github.com/ably/ably-ruby/issues/288)
+- Add support for RTL4j, RTL4j1, RTL4j2 [\#287](https://github.com/ably/ably-ruby/issues/287)
+- Add support for RTS3c, RTS3c1 [\#286](https://github.com/ably/ably-ruby/issues/286)
+- Add support for RTS3a [\#285](https://github.com/ably/ably-ruby/issues/285)
+- Write spec tests for RSL1a, b, h, k1, k2, l, l1 \(Channels\) [\#283](https://github.com/ably/ably-ruby/issues/283)
+- Write spec tests for RSN3a, c \(Channels\) [\#282](https://github.com/ably/ably-ruby/issues/282)
+- Write spec tests for RSA4b, b1, c, RSA16 \(Authentication\) [\#281](https://github.com/ably/ably-ruby/issues/281)
+- Add support for RSN3a, c \(Channels\) [\#269](https://github.com/ably/ably-ruby/issues/269)
+- Add support for RSA4b, b1, c, RSA16 \(Authentication\) [\#268](https://github.com/ably/ably-ruby/issues/268)
+- Add support for RSC7a, RSC7c \(RestClient\)
+ [\#266](https://github.com/ably/ably-ruby/issues/266)
+- Add support for Test Guidance G4 [\#265](https://github.com/ably/ably-ruby/issues/265)
+- Add support for TO3o, TO3p [\#264](https://github.com/ably/ably-ruby/issues/264)
+
+**Merged pull requests:**
+
+- Add migration guide from 1.1.8 to 1.2.0 [\#348](https://github.com/ably/ably-ruby/pull/348) ([TheSmartnik](https://github.com/TheSmartnik))
+- RTL21 [\#345](https://github.com/ably/ably-ruby/pull/345) ([lukaszsliwa](https://github.com/lukaszsliwa))
+- RTL4j [\#341](https://github.com/ably/ably-ruby/pull/341) ([TheSmartnik](https://github.com/TheSmartnik))
+- RSL1a, RSL1b [\#340](https://github.com/ably/ably-ruby/pull/340) ([lukaszsliwa](https://github.com/lukaszsliwa))
+- Add support for RSA4b, b1, c, RSA16 \(Authentication\) [\#338](https://github.com/ably/ably-ruby/pull/338) ([lukaszsliwa](https://github.com/lukaszsliwa))
+- ChannelOptions related tasks [\#336](https://github.com/ably/ably-ruby/pull/336) ([TheSmartnik](https://github.com/TheSmartnik))
+- Update RSC7 [\#334](https://github.com/ably/ably-ruby/pull/334) ([TheSmartnik](https://github.com/TheSmartnik))
+
 ## [v1.1.8](https://github.com/ably/ably-ruby/tree/v1.1.8)
 
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v1.1.7...v1.1.8)

data/README.md

@@ -5,7 +5,7 @@
 
 _[Ably](https://ably.com) is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the [Ably documentation](https://ably.com/documentation)._
 
-This is a Ruby client library for Ably. The library currently targets the [Ably 1.1 client library specification](https://ably.com/documentation/client-lib-development-guide/features/). You can see the complete list of features this client library supports in [our client library SDKs feature support matrix](https://ably.com/download/sdk-feature-support-matrix).
+This is a Ruby client library for Ably. The library currently targets the [Ably 1.2 client library specification](https://ably.com/documentation/client-lib-development-guide/features/). You can see the complete list of features this client library supports in [our client library SDKs feature support matrix](https://ably.com/download/sdk-feature-support-matrix).
 
 ## Supported platforms
 

data/UPDATING.md

@@ -0,0 +1,30 @@
+# Upgrade / Migration Guide
+
+## Version 1.1.8 to 1.2.0
+
+### Notable Changes
+This release is all about channel options. Here is the full [changelog](https://github.com/ably/ably-ruby/blob/main/CHANGELOG.md)
+
+* Channel options were extracted into a seperate model [ChannelOptions](https://github.com/ably/ably-ruby/blob/main/lib/ably/models/channel_options.rb). However it's still backward campatible with `Hash` and you don't need to do make any adjustments to your code
+
+* The `ChannelOptions` class now supports `:params`, `:modes` and `:cipher` as options. Previously only `:cipher` was available
+
+* The client `:idempotent_rest_publishing` option is `true` by default. Previously `:idempotent_rest_publishing` was `false` by default.
+
+### Breaking Changes
+
+* Changing channel options with `Channels#get` is now deprecated in favor of explicit options change
+
+  1. If channel state is attached or attaching an exception will be raised
+  2. Otherwise the library will emit a warning
+
+For example, the following code
+```
+  client.channels.get(channel_name, new_channel_options)
+```
+
+Should be changed to:
+```
+  channel = client.channels.get(channel_name)
+  channel.options = new_channel_options
+```

data/lib/ably/auth.rb

@@ -510,11 +510,11 @@ module Ably
     end
 
     def authorize_when_necessary
-      if current_token_details && !current_token_details.expired?
+      if current_token_details && !current_token_details.expired?(from: current_time)
         return current_token_details
-      else
-        authorize
       end
+
+      authorize
     end
 
     # Returns the current device clock time unless the

data/lib/ably/models/channel_options.rb

@@ -0,0 +1,97 @@
+module Ably::Models
+  # Convert token details argument to a {ChannelOptions} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [ChannelOptions]
+  def self.ChannelOptions(attributes)
+    case attributes
+    when ChannelOptions
+      return attributes
+    else
+      ChannelOptions.new(attributes)
+    end
+  end
+
+  # Represents options of a channel
+  class ChannelOptions
+    extend Ably::Modules::Enum
+    extend Forwardable
+    include Ably::Modules::ModelCommon
+
+    MODES = ruby_enum('MODES',
+      presence: 0,
+      publish: 1,
+      subscribe: 2,
+      presence_subscribe: 3
+    )
+
+    attr_reader :attributes
+
+    alias_method :to_h, :attributes
+
+    def_delegators :attributes, :fetch, :size, :empty?
+    # Initialize a new ChannelOptions
+    #
+    # @option params [Hash] (TB2c) params (for realtime client libraries only) a  of key/value pairs
+    # @option modes [Hash] modes (for realtime client libraries only) an array of ChannelMode
+    # @option cipher [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.
+    #
+    def initialize(attrs)
+      @attributes = IdiomaticRubyWrapper(attrs.clone)
+
+      attributes[:modes] = modes.to_a.map { |mode| Ably::Models::ChannelOptions::MODES[mode] } if modes
+      attributes[:cipher] = Ably::Models::CipherParams(cipher) if cipher
+      attributes.clone
+    end
+
+    # @!attribute cipher
+    #
+    # @return [CipherParams]
+    def cipher
+      attributes[:cipher]
+    end
+
+    # @!attribute params
+    #
+    # @return [Hash]
+    def params
+      attributes[:params].to_h
+    end
+
+    # @!attribute modes
+    #
+    # @return [Array<ChannelOptions::MODES>]
+    def modes
+      attributes[:modes]
+    end
+
+    # Converts modes to a bitfield that coresponds to ProtocolMessage#flags
+    #
+    # @return [Integer]
+    def modes_to_flags
+      modes.map { |mode| Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[mode.to_sym] }.reduce(:|)
+    end
+
+    # @return [Hash]
+    # @api private
+    def set_params(hash)
+      attributes[:params] = hash
+    end
+
+    # Sets modes from ProtocolMessage#flags
+    #
+    # @return [Array<ChannelOptions::MODES>]
+    # @api private
+    def set_modes_from_flags(flags)
+      return unless flags
+
+      message_modes = MODES.select do |mode|
+        flag = Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[mode.to_sym]
+        flags & flag == flag
+      end
+
+      attributes[:modes] = message_modes.map { |mode| Ably::Models::ChannelOptions::MODES[mode] }
+    end
+  end
+end

data/lib/ably/models/idiomatic_ruby_wrapper.rb

@@ -94,6 +94,10 @@ module Ably::Models
       attributes.size
     end
 
+    def empty?
+      attributes.empty?
+    end
+
     def keys
       map { |key, value| key }
     end

data/lib/ably/models/message.rb

@@ -162,15 +162,15 @@ module Ably::Models
       @delta_extras ||= DeltaExtras.new(attributes[:extras][:delta]).freeze
     end
 
+    def protocol_message_index
+      protocol_message.messages.map(&:object_id).index(self.object_id)
+    end
+
     private
     def raw_hash_object
       @raw_hash_object
     end
 
-    def protocol_message_index
-      protocol_message.messages.map(&:object_id).index(self.object_id)
-    end
-
     def set_attributes_object(new_attributes)
       @attributes = IdiomaticRubyWrapper(new_attributes.clone, stop_at: [:data, :extras])
     end

data/lib/ably/models/protocol_message.rb

@@ -66,6 +66,14 @@ module Ably::Models
       auth:         17
     )
 
+    ATTACH_FLAGS_MAPPING = {
+      resume: 32, # 2^5
+      presence: 65536, # 2^16
+      publish: 131072, # 2^17
+      subscribe: 262144, # 2^18
+      presence_subscribe: 524288, # 2^19
+    }
+
     # Indicates this protocol message action will generate an ACK response such as :message or :presence
     # @api private
     def self.ack_required?(for_action)
@@ -185,6 +193,10 @@ module Ably::Models
       message_size <= connection_details.max_message_size
     end
 
+    def params
+      @params ||= attributes[:params].to_h
+    end
+
     def flags
       Integer(attributes[:flags])
     rescue TypeError
@@ -218,27 +230,27 @@ module Ably::Models
 
     # @api private
     def has_attach_resume_flag?
-      flags & 32 == 32 # 2^5
+      flags & ATTACH_FLAGS_MAPPING[:resume] == ATTACH_FLAGS_MAPPING[:resume] # 2^5
     end
 
     # @api private
     def has_attach_presence_flag?
-      flags & 65536 == 65536 # 2^16
+      flags & ATTACH_FLAGS_MAPPING[:presence] == ATTACH_FLAGS_MAPPING[:presence] # 2^16
     end
 
     # @api private
     def has_attach_publish_flag?
-      flags & 131072 == 131072 # 2^17
+      flags & ATTACH_FLAGS_MAPPING[:publish] == ATTACH_FLAGS_MAPPING[:publish] # 2^17
     end
 
     # @api private
     def has_attach_subscribe_flag?
-      flags & 262144 == 262144 # 2^18
+      flags & ATTACH_FLAGS_MAPPING[:subscribe] == ATTACH_FLAGS_MAPPING[:subscribe] # 2^18
     end
 
     # @api private
     def has_attach_presence_subscribe_flag?
-      flags & 524288 == 524288 # 2^19
+      flags & ATTACH_FLAGS_MAPPING[:presence_subscribe] == ATTACH_FLAGS_MAPPING[:presence_subscribe] # 2^19
     end
 
     def connection_details

data/lib/ably/models/token_details.rb

@@ -95,10 +95,15 @@ module Ably::Models
     # Returns true if token is expired or about to expire
     # For tokens that have not got an explicit expires attribute expired? will always return true
     #
+    # @param attributes [Hash]
+    # @option attributes [Time] :from   Sets a current time from which token expires
+    #
     # @return [Boolean]
-    def expired?
+    def expired?(attributes = {})
       return false if !expires
-      expires < Time.now + TOKEN_EXPIRY_BUFFER
+
+      from = attributes[:from] || Time.now
+      expires < from + TOKEN_EXPIRY_BUFFER
     end
 
     # True if the TokenDetails was created from an opaque string i.e. no metadata exists for this token

data/lib/ably/modules/channels_collection.rb

@@ -13,14 +13,21 @@ module Ably::Modules
     # Return a Channel for the given name
     #
     # @param name [String] The name of the channel
-    # @param channel_options [Hash] Channel options including the encryption options
+    # @param channel_options [Hash, Ably::Models::ChannelOptions] A hash of options or a {Ably::Models::ChannelOptions}
     #
     # @return [Channel]
     #
     def get(name, channel_options = {})
       if channels.has_key?(name)
         channels[name].tap do |channel|
-          channel.update_options channel_options if channel_options && !channel_options.empty?
+          if channel_options && !channel_options.empty?
+            if channel.respond_to?(:need_reattach?) && channel.need_reattach?
+              raise_implicit_options_update
+            else
+              warn_implicit_options_update
+              channel.options = channel_options
+            end
+          end
         end
       else
         channels[name] ||= channel_klass.new(client, name, channel_options)
@@ -70,6 +77,19 @@ module Ably::Modules
     end
 
     private
+
+    def raise_implicit_options_update
+      raise ArgumentError, "You are trying to indirectly update channel options which will trigger reattachment of the channel. Please use Channel#set_options directly if you wish to continue"
+    end
+
+    def warn_implicit_options_update
+      logger.warn { "Channels#get: Using this method to update channel options is deprecated and may be removed in a future version of ably-ruby. Please use Channel#setOptions instead" }
+    end
+
+    def logger
+      client.logger
+    end
+
     def client
       @client
     end

data/lib/ably/modules/conversions.rb

@@ -115,5 +115,39 @@ module Ably::Modules
 
       raise Ably::Exceptions::UnsupportedDataType.new('Invalid data payload', 400, Ably::Exceptions::Codes::INVALID_MESSAGE_DATA_OR_ENCODING)
     end
+
+    # Converts the name, data, attributes into the array of Message objects
+    #
+    # @return [Array<Ably::Models::Message>]
+    #
+    def build_messages(name, data = nil, attributes = {})
+      return [Ably::Models::Message(ensure_supported_name_and_payload(nil, data, attributes))] if name.nil?
+
+      Array(name).map do |item|
+        Ably::Models::Message(ensure_supported_name_and_payload(item, data, attributes))
+      end
+    end
+
+    # Ensures if the first argument (name) is a String, Hash or Ably::Models::Message object,
+    # second argument (data) should be a String, Hash, Array or nil (see ensure_supported_payload() method).
+    #
+    # @return [Hash]        Contains :name, :data and other attributes
+    #
+    # (RSL1a, RSL1b)
+    #
+    def ensure_supported_name_and_payload(name, data = nil, attributes = {})
+      return name.attributes.dup if name.kind_of?(Ably::Models::Message)
+
+      payload = data
+      if (hash = name).kind_of?(Hash)
+        name, payload = hash[:name], (hash[:data] || payload)
+        attributes.merge!(hash)
+      end
+
+      name = ensure_utf_8(:name, name, allow_nil: true)
+      ensure_supported_payload payload
+
+      attributes.merge({ name: name, data: payload })
+    end
   end
 end

data/lib/ably/realtime/channel/channel_manager.rb

@@ -38,6 +38,8 @@ module Ably::Realtime
         if attached_protocol_message
           update_presence_sync_state_following_attached attached_protocol_message
           channel.properties.set_attach_serial(attached_protocol_message.channel_serial)
+          channel.options.set_modes_from_flags(attached_protocol_message.flags)
+          channel.options.set_params(attached_protocol_message.params)
         end
       end
 
@@ -64,6 +66,7 @@ module Ably::Realtime
         end
 
         channel.properties.set_attach_serial(protocol_message.channel_serial)
+        channel.options.set_modes_from_flags(protocol_message.flags)
 
         if protocol_message.has_channel_resumed_flag?
           logger.debug { "ChannelManager: Additional resumed ATTACHED message received for #{channel.state} channel '#{channel.name}'" }
@@ -199,14 +202,21 @@ module Ably::Realtime
       end
 
       def send_attach_protocol_message
-        send_state_change_protocol_message Ably::Models::ProtocolMessage::ACTION.Attach, :suspended # move to suspended
+        message_options = {}
+        message_options[:params] = channel.options.params if channel.options.params.any?
+        message_options[:flags] = channel.options.modes_to_flags if channel.options.modes
+        if channel.attach_resume
+          message_options[:flags] = message_options[:flags].to_i | Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[:resume]
+        end
+
+        send_state_change_protocol_message Ably::Models::ProtocolMessage::ACTION.Attach, :suspended, message_options
       end
 
       def send_detach_protocol_message(previous_state)
         send_state_change_protocol_message Ably::Models::ProtocolMessage::ACTION.Detach, previous_state # return to previous state if failed
       end
 
-      def send_state_change_protocol_message(new_state, state_if_failed)
+      def send_state_change_protocol_message(new_state, state_if_failed, message_options = {})
         state_at_time_of_request = channel.state
         @pending_state_change_timer = EventMachine::Timer.new(realtime_request_timeout) do
           if channel.state == state_at_time_of_request
@@ -227,7 +237,8 @@ module Ably::Realtime
               next unless pending_state_change_timer
               connection.send_protocol_message(
                 action:  new_state.to_i,
-                channel: channel.name
+                channel: channel.name,
+                **message_options.to_h
               )
               resend_if_disconnected_and_connected.call
             end
@@ -237,7 +248,8 @@ module Ably::Realtime
 
         connection.send_protocol_message(
           action:  new_state.to_i,
-          channel: channel.name
+          channel: channel.name,
+          **message_options.to_h
         )
       end
 

data/lib/ably/realtime/channel/channel_state_machine.rb

@@ -42,6 +42,11 @@ module Ably::Realtime
 
       before_transition(to: [:attached]) do |channel, current_transition|
         channel.manager.attached current_transition.metadata.protocol_message
+        channel.attach_resume!
+      end
+
+      before_transition(to: [:detaching, :failed]) do |channel, _current_transition|
+        channel.reset_attach_resume!
       end
 
       after_transition(to: [:detaching]) do |channel, current_transition|

data/lib/ably/realtime/channel.rb

@@ -36,6 +36,7 @@ module Ably
       include Ably::Modules::MessageEmitter
       include Ably::Realtime::Channel::Publisher
       extend Ably::Modules::Enum
+      extend Forwardable
 
       # ChannelState
       # The permited states for this channel
@@ -92,17 +93,25 @@ module Ably
       # @api private
       attr_reader :manager
 
+      # Flag that specifies whether channel is resuming attachment(reattach) or is doing a 'clean attach' RTL4j1
+      # @return [Bolean]
+      # @api private
+      attr_reader :attach_resume
+
+      # ChannelOptions params attrribute (#RTL4k)
+      # return [Hash]
+      def_delegators :options, :params
+
       # Initialize a new Channel object
       #
       # @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
         @queue         = []
@@ -112,6 +121,7 @@ module Ably
         @manager       = ChannelManager.new(self, client.connection)
         @push          = PushChannel.new(self)
         @properties    = ChannelProperties.new(self)
+        @attach_resume = false
 
         setup_event_handlers
         setup_presence
@@ -129,23 +139,31 @@ module Ably
       # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks
       #
       # @example
-      #   # Publish a single message
+      #   # Publish a single message 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', { x: 1, y: 2 } },
-      #     { name: 'click', { x: 2, y: 3 } }
+      #     { 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 an array of Ably::Models::Message objects form
+      #   message = Ably::Models::Message(name: 'click', data: { x: 1, y: 2 })
+      #   channel.publish message
+      #
       #   channel.publish('click', 'body') do |message|
       #     puts "#{message.name} event received with #{message.data}"
       #   end
@@ -165,13 +183,7 @@ module Ably
           return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
         end
 
-        messages = if name.kind_of?(Enumerable)
-          name
-        else
-          name = ensure_utf_8(:name, name, allow_nil: true)
-          ensure_supported_payload data
-          [{ name: name, data: data }.merge(attributes)]
-        end
+        messages = build_messages(name, data, attributes) # (RSL1a, RSL1b)
 
         if messages.length > Realtime::Connection::MAX_PROTOCOL_MESSAGE_BATCH_SIZE
           error = Ably::Exceptions::InvalidRequest.new("It is not possible to publish more than #{Realtime::Connection::MAX_PROTOCOL_MESSAGE_BATCH_SIZE} messages with a single publish request.")
@@ -309,6 +321,16 @@ module Ably
         )
       end
 
+      # Sets or updates the stored channel options. (#RTL16)
+      # @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)
+
+        manager.request_reattach if need_reattach?
+      end
+      alias options= set_options
+
       # @api private
       def set_channel_error_reason(error)
         @error_reason = error
@@ -319,24 +341,32 @@ module Ably
         @error_reason = nil
       end
 
-      # @api private
-      def update_options(channel_options)
-        @options = channel_options.clone.freeze
-      end
-      alias set_options update_options # (RSL7)
-      alias options= update_options
-
       # Used by {Ably::Modules::StateEmitter} to debug state changes
       # @api private
       def logger
         client.logger
       end
 
+      # @api private
+      def attach_resume!
+        @attach_resume = true
+      end
+
+      # @api private
+      def reset_attach_resume!
+        @attach_resume = false
+      end
+
       # As we are using a state machine, do not allow change_state to be used
       # #transition_state_machine must be used instead
       private :change_state
 
+      def need_reattach?
+        !!(attaching? || attached?) && !!(options.modes || options.params)
+      end
+
       private
+
       def setup_event_handlers
         __incoming_msgbus__.subscribe(:message) do |message|
           message.decode(client.encoders, options) do |encode_error, error_message|

data/lib/ably/realtime/channels.rb

@@ -13,7 +13,7 @@ module Ably
       # Return a {Ably::Realtime::Channel} for the given name
       #
       # @param name [String] The name of the channel
-      # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+      # @param channel_options [Hash, Ably::Models::ChannelOptions] A hash of options or a {Ably::Models::ChannelOptions}
       # @return [Ably::Realtime::Channel}
       #
       def get(*args)