ably 0.8.15 → 1.0.0

data/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/ably/models/token_details.rb

@@ -73,7 +73,17 @@ module Ably::Models
     # @!attribute [r] capability
     # @return [Hash] Capabilities assigned to this token
     def capability
-      JSON.parse(attributes.fetch(:capability)) if attributes.has_key?(:capability)
+      if attributes.has_key?(:capability)
+        capability_val = attributes.fetch(:capability)
+        case capability_val
+        when Hash
+          capability_val
+        when Ably::Models::IdiomaticRubyWrapper
+          capability_val.as_json
+        else
+          JSON.parse(attributes.fetch(:capability))
+        end
+      end
     end
 
     # @!attribute [r] client_id

data/lib/ably/models/token_request.rb

@@ -42,7 +42,7 @@ module Ably::Models
     # @!attribute [r] key_name
     # @return [String] API key name of the key against which this request is made.  An API key is made up of an API key name and secret delimited by a +:+
     def key_name
-      attributes.fetch(:key_name)
+      attributes.fetch(:key_name) { raise Ably::Exceptions::InvalidTokenRequest, 'Key name is missing' }
     end
 
     # @!attribute [r] ttl
@@ -59,7 +59,16 @@ module Ably::Models
     #                the capability of the returned token will be the intersection of
     #                this capability with the capability of the issuing key.
     def capability
-      JSON.parse(attributes.fetch(:capability))
+      capability_val = attributes.fetch(:capability) { raise Ably::Exceptions::InvalidTokenRequest, 'Capability is missing' }
+
+      case capability_val
+      when Hash
+        capability_val
+      when Ably::Models::IdiomaticRubyWrapper
+        capability_val.as_json
+      else
+        JSON.parse(attributes.fetch(:capability))
+      end
     end
 
     # @!attribute [r] client_id
@@ -75,7 +84,8 @@ module Ably::Models
     #                token requests from being replayed.
     #                Timestamp when sent to Ably is in milliseconds.
     def timestamp
-      as_time_from_epoch(attributes.fetch(:timestamp), granularity: :ms)
+      timestamp_val = attributes.fetch(:timestamp) { raise Ably::Exceptions::InvalidTokenRequest, 'Timestamp is missing' }
+      as_time_from_epoch(timestamp_val, granularity: :ms)
     end
 
     # @!attribute [r] nonce
@@ -83,21 +93,21 @@ module Ably::Models
     #                   uniqueness of this request. Any subsequent request using the
     #                   same nonce will be rejected.
     def nonce
-      attributes.fetch(:nonce)
+      attributes.fetch(:nonce) { raise Ably::Exceptions::InvalidTokenRequest, 'Nonce is missing' }
     end
 
     # @!attribute [r] mac
     # @return [String]  the Message Authentication Code for this request. See the
     #                   {https://www.ably.io/documentation Ably Authentication documentation} for more details.
     def mac
-      attributes.fetch(:mac)
+      attributes.fetch(:mac) { raise Ably::Exceptions::InvalidTokenRequest, 'MAC is missing' }
     end
 
     # Requests that the token is always persisted
     # @api private
     #
     def persisted
-      attributes.fetch(:persisted)
+      attributes[:persisted]
     end
 
     # @!attribute [r] attributes

data/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/ably/modules/encodeable.rb

@@ -10,20 +10,60 @@ module Ably::Modules
   # - A #raw_hash_object attribute that returns the original hash object used to create this object
   #
   module Encodeable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Return a Message or Presence object from the encoded JSON-like object, using the optional channel options
+      # @param message_object [Hash] JSON-like object representation of an encoded message
+      # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+      # @yield [Ably::Exceptions::BaseAblyException] yields an Ably exception if decoding fails
+      # @return [Message,Presence]
+      def from_encoded(message_object, channel_options = {}, &error_block)
+        new(message_object).tap do |message|
+          message.decode(encoders, channel_options, &error_block)
+        end
+      end
+
+      # Return an Array of Message or Presence objects from the encoded Array of JSON-like objects, using the optional channel options
+      # @param message_objects [Array<Hash>] Array of JSON-like objects with encoded messages
+      # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+      # @return [Array<Message,Presence>]
+      def from_encoded_array(message_object_array, channel_options = {})
+        Array(message_object_array).map do |message_object|
+          from_encoded(message_object, channel_options)
+        end
+      end
+
+      # Register an encoder for this object
+      # @api private
+      def register_encoder(encoder, options = {})
+        encoders << Ably::Models::MessageEncoders.encoder_from(encoder, options)
+      end
+
+      private
+      def encoders
+        @encoders ||= []
+      end
+    end
+
     # Encode a message using the channel options and register encoders for the client
-    # @param channel [Ably::Realtime::Channel]
+    # @param encoders [Array<Ably::Models::MessageEncoders::Base>] List of encoders to apply to the message
+    # @param channel_options [Hash] Channel options, currently reserved for Encryption options
     # @return [void]
     # @api private
-    def encode(channel)
-      apply_encoders :encode, channel
+    def encode(encoders, channel_options, &error_block)
+      apply_encoders :encode, encoders, channel_options, &error_block
     end
 
     # Decode a message using the channel options and registered encoders for the client
-    # @param channel [Ably::Realtime::Channel]
+    # @param encoders [Array<Ably::Models::MessageEncoders::Base>] List of encoders to apply to the message
+    # @param channel_options [Hash] Channel options, currently reserved for Encryption options
     # @return [void]
     # @api private
-    def decode(channel)
-      apply_encoders :decode, channel
+    def decode(encoders, channel_options, &error_block)
+      apply_encoders :decode, encoders, channel_options, &error_block
     end
 
     # The original encoding of this message when it was received as a raw message from the Ably service
@@ -44,7 +84,7 @@ module Ably::Modules
       end
     end
 
-    def apply_encoders(method, channel)
+    def apply_encoders(method, encoders, channel_options, &error_callback)
       max_encoding_length = 512
       message_attributes = attributes.dup
 
@@ -54,16 +94,15 @@ module Ably::Modules
         end
 
         previous_encoding = message_attributes[:encoding]
-        channel.client.encoders.each do |encoder|
-          encoder.send method, message_attributes, channel.options
+        encoders.each do |encoder|
+          encoder.send method, message_attributes, channel_options
         end
       end until previous_encoding == message_attributes[:encoding]
 
       set_attributes_object message_attributes
     rescue Ably::Exceptions::CipherError => cipher_error
-      if channel.respond_to?(:emit)
-        channel.client.logger.error "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"
-        channel.emit :error, cipher_error
+      if block_given?
+        yield cipher_error, "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"
       else
         raise cipher_error
       end

data/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/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
 

data/lib/ably/modules/model_common.rb

@@ -8,6 +8,10 @@ module Ably::Modules
     include Conversions
     include MessagePack
 
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
     # Provide a normal Hash accessor to the underlying raw message object
     #
     # @return [Object]
@@ -32,38 +36,26 @@ module Ably::Modules
       as_json.to_json(*args)
     end
 
-    # Like to_json but encodes all binary fields to hex
-    def to_safe_json(*args)
-      as_json.
-        each_with_object({}) do |(key, val), obj|
-          obj[key] = to_safe_jsonable_val(val)
-        end.to_json(*args)
-    end
-
     # @!attribute [r] hash
     # @return [Integer] Compute a hash-code for this hash. Two hashes with the same content will have the same hash code
     def hash
       attributes.hash
     end
 
-    private
-    def to_safe_jsonable_val(val)
-      case val
-      when Array
-        val.map { |array_val| to_safe_jsonable_val(array_val) }
-      when Hash
-        val.each_with_object({}) { |(key, hash_val), obj| obj[key] = to_safe_jsonable_val(hash_val) }
-      when String
-        if val.encoding == Encoding::ASCII_8BIT
-          val.unpack("H*").first
+    module ClassMethods
+      # Return a new instance of this object using the provided JSON-like object or JSON string
+      # @param [Hash, String] JSON-like object or JSON string
+      # @return a new instance o this object
+      def from_json(json_like_object)
+        if json_like_object.kind_of?(String)
+          new(JSON.parse(json_like_object))
         else
-          val
+          new(json_like_object)
         end
-      else
-        val
       end
     end
 
+    private
     def ensure_utf8_string_for(attribute, value)
       if value
         raise ArgumentError, "#{attribute} must be a String" unless value.kind_of?(String)