ably-rest 0.9.3 → 1.0.0

data/lib/submodules/ably-ruby/lib/ably/models/error_info.rb

@@ -11,7 +11,7 @@ module Ably::Models
   # @!attribute [r] attributes
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #
-  class ErrorInfo
+  class ErrorInfo < Ably::Exceptions::BaseAblyException
     include Ably::Modules::ModelCommon
 
     def initialize(hash_object)

data/lib/submodules/ably-ruby/lib/ably/models/message.rb

@@ -124,6 +124,17 @@ module Ably::Models
       @protocol_message
     end
 
+    # Contains any arbitrary key value pairs which may also contain other primitive JSON types, JSON-encodable objects or JSON-encodable arrays.
+    # The extras field is provided to contain message metadata and/or ancillary payloads in support of specific functionality, e.g. push
+    # @api private
+    def extras
+      attributes[:extras].tap do |val|
+        unless val.kind_of?(IdiomaticRubyWrapper) || val.kind_of?(Array) || val.kind_of?(Hash) || val.nil?
+          raise ArgumentError, "extras contains an unsupported type #{val.class}"
+        end
+      end
+    end
+
     private
     def raw_hash_object
       @raw_hash_object
@@ -134,7 +145,7 @@ module Ably::Models
     end
 
     def set_attributes_object(new_attributes)
-      @attributes = IdiomaticRubyWrapper(new_attributes.clone.freeze, stop_at: [:data])
+      @attributes = IdiomaticRubyWrapper(new_attributes.clone.freeze, stop_at: [:data, :extras])
     end
 
     def logger

data/lib/submodules/ably-ruby/lib/ably/models/message_encoders/base.rb

@@ -7,115 +7,119 @@ require 'ably/modules/conversions'
 # of the message is defined as 'json'.
 # Encrypted messages are encoded & decoded by the Cipher encoder.
 #
-module Ably::Models::MessageEncoders
-  extend Ably::Modules::Conversions
+module Ably
+  module Models
+    module MessageEncoders
+      extend Ably::Modules::Conversions
 
-  # Base interface for an Ably Encoder
-  #
-  class Base
-    attr_reader :client, :options
+      # Base interface for an Ably Encoder
+      #
+      class Base
+        attr_reader :client, :options
 
-    def initialize(client, options = {})
-      @client = client
-      @options = options
-    end
+        def initialize(client, options = {})
+          @client = client
+          @options = options
+        end
 
-    # #encode is called once before a message is sent to Ably
-    #
-    # It is the responsibility of the #encode method to detect the intended encoding and modify the :data & :encoding properties of the message object.
-    #
-    # @param [Hash] message          the message as a Hash object received directly from Ably.
-    #                                The message contains properties :name, :data, :encoding, :timestamp, and optionally :id and :client_id.
-    #                                This #encode method should modify the message Hash if any encoding action is to be taken
-    # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
-    #
-    # @return [void]
-    def encode(message, channel_options)
-      raise "Not yet implemented"
-    end
+        # #encode is called once before a message is sent to Ably
+        #
+        # It is the responsibility of the #encode method to detect the intended encoding and modify the :data & :encoding properties of the message object.
+        #
+        # @param [Hash] message          the message as a Hash object received directly from Ably.
+        #                                The message contains properties :name, :data, :encoding, :timestamp, and optionally :id and :client_id.
+        #                                This #encode method should modify the message Hash if any encoding action is to be taken
+        # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
+        #
+        # @return [void]
+        def encode(message, channel_options)
+          raise "Not yet implemented"
+        end
 
-    # #decode is called once for every encoding step
-    # i.e. if message encoding arrives with 'utf-8/cipher+aes-128-cbc/base64'
-    #      the decoder will call #decode once for each encoding part such as 'base64', then 'cipher+aes-128-cbc', and finally 'utf-8'
-    #
-    # It is the responsibility of the #decode method to detect the current encoding part and modify the :data & :encoding properties of the message object.
-    #
-    # @param [Hash] message          the message as a Hash object received directly from Ably.
-    #                                The message contains properties :name, :data, :encoding, :timestamp, and optionally :id and :client_id.
-    #                                This #encode method should modify the message Hash if any decoding action is to be taken
-    # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
-    #
-    # @return [void]
-    def decode(message, channel_options)
-      raise "Not yet implemented"
-    end
+        # #decode is called once for every encoding step
+        # i.e. if message encoding arrives with 'utf-8/cipher+aes-128-cbc/base64'
+        #      the decoder will call #decode once for each encoding part such as 'base64', then 'cipher+aes-128-cbc', and finally 'utf-8'
+        #
+        # It is the responsibility of the #decode method to detect the current encoding part and modify the :data & :encoding properties of the message object.
+        #
+        # @param [Hash] message          the message as a Hash object received directly from Ably.
+        #                                The message contains properties :name, :data, :encoding, :timestamp, and optionally :id and :client_id.
+        #                                This #encode method should modify the message Hash if any decoding action is to be taken
+        # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
+        #
+        # @return [void]
+        def decode(message, channel_options)
+          raise "Not yet implemented"
+        end
 
-    # Add encoding to the message Hash.
-    # Ensures that encoding delimeter is used where required i.e utf-8/cipher+aes-128-cbc/base64
-    #
-    # @param [Hash]   message   the message as a Hash object received directly from Ably.
-    # @param [String] encoding  encoding to add to the current encoding
-    #
-    # @return [void]
-    def add_encoding_to_message(encoding, message)
-      message[:encoding] = [message[:encoding], encoding].compact.join('/')
-    end
+        # Add encoding to the message Hash.
+        # Ensures that encoding delimeter is used where required i.e utf-8/cipher+aes-128-cbc/base64
+        #
+        # @param [Hash]   message   the message as a Hash object received directly from Ably.
+        # @param [String] encoding  encoding to add to the current encoding
+        #
+        # @return [void]
+        def add_encoding_to_message(encoding, message)
+          message[:encoding] = [message[:encoding], encoding].compact.join('/')
+        end
 
-    # Returns the right most encoding form a meessage encoding, and nil if none exists
-    # i.e. current_encoding_part('utf-8/cipher+aes-128-cbc/base64') => 'base64'
-    #
-    # @return [String,nil]
-    def current_encoding_part(message)
-      if message[:encoding]
-        message[:encoding].split('/')[-1]
-      end
-    end
+        # Returns the right most encoding form a meessage encoding, and nil if none exists
+        # i.e. current_encoding_part('utf-8/cipher+aes-128-cbc/base64') => 'base64'
+        #
+        # @return [String,nil]
+        def current_encoding_part(message)
+          if message[:encoding]
+            message[:encoding].split('/')[-1]
+          end
+        end
 
-    # Strip the current encoding part within the message Hash.
-    #
-    # For example, calling this method on an :encoding value of 'utf-8/cipher+aes-128-cbc/base64' would update the attribute
-    # :encoding to 'utf-8/cipher+aes-128-cbc'
-    #
-    # @param [Hash]   message   the message as a Hash object received directly from Ably.
-    #
-    # @return [void]
-    def strip_current_encoding_part(message)
-      raise "Cannot strip encoding when there is no encoding for this message" unless message[:encoding]
-      message[:encoding] = message[:encoding].split('/')[0...-1].join('/')
-      message[:encoding] = nil if message[:encoding].empty?
-    end
+        # Strip the current encoding part within the message Hash.
+        #
+        # For example, calling this method on an :encoding value of 'utf-8/cipher+aes-128-cbc/base64' would update the attribute
+        # :encoding to 'utf-8/cipher+aes-128-cbc'
+        #
+        # @param [Hash]   message   the message as a Hash object received directly from Ably.
+        #
+        # @return [void]
+        def strip_current_encoding_part(message)
+          raise "Cannot strip encoding when there is no encoding for this message" unless message[:encoding]
+          message[:encoding] = message[:encoding].split('/')[0...-1].join('/')
+          message[:encoding] = nil if message[:encoding].empty?
+        end
 
-    # True of the message data payload is empty
-    #
-    # @param [Hash]   message   the message as a Hash object received directly from Ably.
-    #
-    # @return [Boolean]
-    def is_empty?(message)
-      message[:data].nil? || message[:data] == ''
-    end
-  end
+        # True of the message data payload is empty
+        #
+        # @param [Hash]   message   the message as a Hash object received directly from Ably.
+        #
+        # @return [Boolean]
+        def is_empty?(message)
+          message[:data].nil? || message[:data] == ''
+        end
+      end
 
-  # @api private
-  def self.register_default_encoders(client, options = {})
-    binary_protocol = !!options[:binary_protocol]
-    client.register_encoder Ably::Models::MessageEncoders::Utf8
-    client.register_encoder Ably::Models::MessageEncoders::Json
-    client.register_encoder Ably::Models::MessageEncoders::Cipher
-    client.register_encoder Ably::Models::MessageEncoders::Base64, binary_protocol: binary_protocol
-  end
+      # @api private
+      def self.register_default_encoders(client, options = {})
+        binary_protocol = !!options[:binary_protocol]
+        client.register_encoder Ably::Models::MessageEncoders::Utf8
+        client.register_encoder Ably::Models::MessageEncoders::Json
+        client.register_encoder Ably::Models::MessageEncoders::Cipher
+        client.register_encoder Ably::Models::MessageEncoders::Base64, binary_protocol: binary_protocol
+      end
+
+      # @api private
+      def self.encoder_from(encoder, options)
+        encoder_klass = if encoder.kind_of?(String)
+          encoder.split('::').inject(Kernel) do |base, klass_name|
+            base.public_send(:const_get, klass_name)
+          end
+        else
+          encoder
+        end
 
-  # @api private
-  def self.encoder_from(encoder, options)
-    encoder_klass = if encoder.kind_of?(String)
-      encoder.split('::').inject(Kernel) do |base, klass_name|
-        base.public_send(:const_get, klass_name)
+        raise "Encoder must inherit from `Ably::Models::MessageEncoders::Base`" unless encoder_klass.ancestors.include?(Ably::Models::MessageEncoders::Base)
+        encoder_klass.new(self, options)
       end
-    else
-      encoder
     end
-
-    raise "Encoder must inherit from `Ably::Models::MessageEncoders::Base`" unless encoder_klass.ancestors.include?(Ably::Models::MessageEncoders::Base)
-    encoder_klass.new(self, options)
   end
 end
 

data/lib/submodules/ably-ruby/lib/ably/models/presence_message.rb

@@ -123,7 +123,6 @@ module Ably::Models
       end.to_json
     end
 
-
     # Assign this presence message to a ProtocolMessage before delivery to the Ably system
     # @api private
     def assign_to_protocol_message(protocol_message)
@@ -145,6 +144,19 @@ module Ably::Models
       @protocol_message
     end
 
+    # Create a static shallow clone of this object with the optional attributes to overide existing values
+    # Shallow clones have no dependency on the originating ProtocolMessage as all field values are stored as opposed to calculated
+    # Clones are useful when the original PresenceMessage needs to be mutated, such as storing in a PresenceMap with action :present
+    def shallow_clone(new_attributes = {})
+      new_attributes = IdiomaticRubyWrapper(new_attributes.clone.freeze, stop_at: [:data])
+
+      self.class.new(attributes.to_hash.merge(
+        id: new_attributes[:id] || id,
+        connection_id: new_attributes[:connection_id] || connection_id,
+        timestamp: new_attributes[:timestamp] || as_since_epoch(timestamp)
+      ).merge(new_attributes.to_hash))
+    end
+
     private
     def raw_hash_object
       @raw_hash_object

data/lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb

@@ -8,6 +8,8 @@ module Ably::Models
   #
   # @!attribute [r] action
   #   @return [ACTION] Protocol Message action {Ably::Modules::Enum} from list of {ACTION}. Returns nil if action is unsupported by protocol
+  # @!attribute [r] auth
+  #   @return [Ably::Models::AuthDetails] Authentication details used to perform authentication upgrades over an existing transport
   # @!attribute [r] count
   #   @return [Integer] The count field is used for ACK and NACK actions. See {http://docs.ably.io/client-lib-development-guide/protocol/#message-acknowledgement message acknowledgement protocol}
   # @!attribute [r] error
@@ -15,7 +17,7 @@ module Ably::Models
   # @!attribute [r] channel
   #   @return [String] Channel name for messages
   # @!attribute [r] channel_serial
-  #   @return [String] Contains a serial number for a message on the current channelƒ
+  #   @return [String] Contains a serial number for a message on the current channel
   # @!attribute [r] connection_id
   #   @return [String] Contains a string public identifier for the connection
   # @!attribute [r] connection_key
@@ -62,13 +64,14 @@ module Ably::Models
       detached:     13,
       presence:     14,
       message:      15,
-      sync:         16
+      sync:         16,
+      auth:         17
     )
 
     # Indicates this protocol message action will generate an ACK response such as :message or :presence
     # @api private
     def self.ack_required?(for_action)
-      [ACTION.Presence, ACTION.Message].include?(ACTION(for_action))
+      ACTION(for_action).match_any?(ACTION.Presence, ACTION.Message)
     end
 
     # {ProtocolMessage} initializer
@@ -193,10 +196,24 @@ module Ably::Models
       flags & 1 == 1
     end
 
+    # @api private
+    def has_backlog_flag?
+      flags & 2 == 2
+    end
+
+    # @api private
+    def has_channel_resumed_flag?
+      flags & 4 == 4
+    end
+
     def connection_details
       @connection_details ||= Ably::Models::ConnectionDetails(attributes[:connection_details])
     end
 
+    def auth
+      @auth ||= Ably::Models::AuthDetails(attributes[:auth])
+    end
+
     # Indicates this protocol message will generate an ACK response when sent
     # Examples of protocol messages required ACK include :message and :presence
     # @api private

data/lib/submodules/ably-ruby/lib/ably/modules/async_wrapper.rb

@@ -38,7 +38,7 @@ module Ably::Modules
     # @yield [Object] operation block that is run in a thread
     # @return [Ably::Util::SafeDeferrable]
     #
-    def async_wrap(success_callback = nil)
+    def async_wrap(success_callback = nil, custom_error_handling = nil)
       raise ArgumentError, 'Block required' unless block_given?
 
       Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
@@ -48,8 +48,12 @@ module Ably::Modules
           begin
             yield
           rescue StandardError => err
-            logger.error "An exception in an AsyncWrapper block was caught. #{err.class}: #{err.message}\n#{err.backtrace.join("\n")}"
-            deferrable.fail err
+            if custom_error_handling
+              custom_error_handling.call err, deferrable
+            else
+              logger.error { "An exception in an AsyncWrapper block was caught. #{err.class}: #{err.message}\n#{err.backtrace.join("\n")}" }
+              deferrable.fail err
+            end
           end
         end
 

data/lib/submodules/ably-ruby/lib/ably/modules/enum.rb

@@ -49,11 +49,11 @@ module Ably::Modules
           def get(identifier)
             case identifier
             when Symbol
-              by_symbol.fetch(identifier)
+              by_symbol.fetch(identifier) { raise KeyError, "#{name} key not found: :#{identifier}" }
             when String
-              by_symbol.fetch(convert_to_snake_case_symbol(identifier))
+              by_symbol.fetch(convert_to_snake_case_symbol(identifier)) { raise KeyError, "#{name} key not found: '#{identifier}'" }
             when Numeric
-              by_index.fetch(identifier)
+              by_index.fetch(identifier) { raise KeyError, "#{name} key not found: #{identifier}" }
             when ancestors.first
               identifier
             else
@@ -89,6 +89,12 @@ module Ably::Modules
             @enum_name
           end
 
+          # Array of Enum values as symbols
+          # @return [Array<Symbol>]
+          def to_sym_arr
+            @by_symbol.keys
+          end
+
           private
           def by_index
             @by_index
@@ -158,7 +164,7 @@ module Ably::Modules
 
         # Allow comparison of Enum objects based on:
         #
-        # * Other equivalent Enum objects
+        # * Other equivalent Enum objects compared by Symbol (not Integer value)
         # * Symbol
         # * String
         # * Integer index of Enum
@@ -171,13 +177,17 @@ module Ably::Modules
             self.to_sym == convert_to_snake_case_symbol(other)
           when Numeric
             self.to_i == other.to_i
-          when self.class
-            self.to_i == other.to_i
           else
-            false
+            if other.kind_of?(Ably::Modules::Enum::Base)
+              self.to_sym == other.to_sym
+            end
           end
         end
 
+        def match_any?(*enums)
+          enums.any? { |enum| self.==(enum) }
+        end
+
         private
         def name
           @name

data/lib/submodules/ably-ruby/lib/ably/modules/event_emitter.rb

@@ -54,7 +54,7 @@ module Ably
       end
 
       # Equivalent of {#on} but any exception raised in a block will bubble up and cause this client library to fail.
-      # This method should only be used internally by the client library.
+      # This method is designed to be used internally by the client library.
       # @api private
       def unsafe_on(*event_names, &block)
         add_callback event_names, proc_for_block(block, unsafe: true)
@@ -70,7 +70,7 @@ module Ably
       end
 
       # Equivalent of {#once} but any exception raised in a block will bubble up and cause this client library to fail.
-      # This method should only be used internally by the client library.
+      # This method is designed to be used internally by the client library.
       # @api private
       def unsafe_once(*event_names, &block)
         add_callback event_names, proc_for_block(block, delete_once_run: true, unsafe: true)
@@ -101,30 +101,45 @@ module Ably
       #
       # @return [void]
       def off(*event_names, &block)
+        off_internal(false, *event_names, &block)
+      end
+
+      # Equivalent of {#off} but only unsafe listeners are removed.
+      # This method is designed to be used internally by the client library.
+      # @api private
+      def unsafe_off(*event_names, &block)
+        off_internal(true, *event_names, &block)
+      end
+
+      private
+      def off_internal(unsafe, *event_names, &block)
         keys = if event_names.empty?
           callbacks.keys
         else
           event_names
         end
 
-        keys.each do |event_name|
-          if block_given?
-            callbacks[callbacks_event_coerced(event_name)].delete_if { |proc_hash| proc_hash[:block] == block }
-          else
-            callbacks[callbacks_event_coerced(event_name)].clear
+        if event_names.empty?
+          callbacks_any.delete_if do |proc_hash|
+            if block_given?
+              (proc_hash[:unsafe] == unsafe) && (proc_hash[:block] == block)
+            else
+              proc_hash[:unsafe] == unsafe
+            end
           end
         end
 
-        if event_names.empty?
-          if block_given?
-            callbacks_any.delete_if { |proc_hash| proc_hash[:block] == block }
-          else
-            callbacks_any.clear
+        keys.each do |event_name|
+          callbacks[callbacks_event_coerced(event_name)].delete_if do |proc_hash|
+            if block_given?
+              (proc_hash[:unsafe] == unsafe) && (proc_hash[:block] == block)
+            else
+              proc_hash[:unsafe] == unsafe
+            end
           end
         end
       end
 
-      private
       def self.included(klass)
         klass.extend ClassMethods
       end
@@ -148,7 +163,7 @@ module Ably
             true if options[:delete_once_run]
           end,
           block: block,
-          unsafe: options[:unsafe]
+          unsafe: options[:unsafe] || false
         }
       end