ably 0.7.2 → 0.7.4

data/lib/ably/modules/safe_deferrable.rb

@@ -0,0 +1,71 @@
+require 'eventmachine'
+
+module Ably::Modules
+  # SafeDeferrable module provides an EventMachine::Deferrable interface to the object it is included in
+  # and is safe to use for for public interfaces of this client library.
+  # Any exceptions raised in the success or failure callbacks is caught and logged to #logger
+  #
+  # An exception in a callback provided by a developer should not break this client library
+  # and stop further execution of code.
+  #
+  # @note this Module requires that the method #logger is available
+  #
+  # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable
+  #
+  module SafeDeferrable
+    include EventMachine::Deferrable
+
+    # Specify a block to be executed if and when the Deferrable object receives
+    # a status of :succeeded.
+    # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#callback-instance_method
+    def callback(&block)
+      super do |*args|
+        safe_deferrable_block(*args, &block)
+      end
+    end
+
+    # Specify a block to be executed if and when the Deferrable object receives
+    # a status of :failed.
+    # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#errback-instance_method
+    def errback(&block)
+      super do |*args|
+        safe_deferrable_block(*args, &block)
+      end
+    end
+
+    # Mark the Deferrable as succeeded and trigger all callbacks
+    # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#succeed-instance_method
+    def succeed(*args)
+      super(*args)
+    end
+
+    # Mark the Deferrable as failed and trigger all callbacks
+    # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#fail-instance_method
+    def fail(*args)
+      super(*args)
+    end
+
+    private
+    def safe_deferrable_block(*args)
+      yield *args
+    rescue StandardError => e
+      message = "An exception in a Deferrable callback was caught. #{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+      if defined?(:logger) && logger.respond_to?(:error)
+        logger.error message
+      else
+        fallback_logger.error message
+      end
+    end
+
+    def fallback_logger
+      @fallback_logger ||= ::Logger.new(STDOUT).tap do |logger|
+        logger.formatter = proc do |severity, datetime, progname, msg|
+          [
+            "#{datetime.strftime("%Y-%m-%d %H:%M:%S.%L")} #{::Logger::SEV_LABEL[severity]} #{msg}",
+            "Warning: SafeDeferrable expects the method #logger to be defined in the class it is included in, the method was not found in #{self.class}"
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ably/modules/safe_yield.rb

@@ -0,0 +1,41 @@
+module Ably::Modules
+  # SafeYield provides the method safe_yield that will yield to the consumer
+  # who provided a block, however any exceptions will be caught, logged, and
+  # operation of the client library will continue.
+  #
+  # An exception in a callback provided by a developer should not break this client library
+  # and stop further execution of code.
+  #
+  # @note this Module requires that the method #logger is available
+  #
+  # @api private
+  module SafeYield
+    private
+
+    def safe_yield(block, *args)
+      block.call *args
+    rescue StandardError => e
+      message = "An exception in an external block was caught. #{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+      safe_yield_log_error message
+    end
+
+    def safe_yield_log_error(message)
+      if defined?(:logger) && logger.respond_to?(:error)
+        return logger.error message
+      end
+    rescue StandardError => e
+      fallback_logger.error message
+    end
+
+    def fallback_logger
+      @fallback_logger ||= ::Logger.new(STDOUT).tap do |logger|
+        logger.formatter = proc do |severity, datetime, progname, msg|
+          [
+            "#{datetime.strftime("%Y-%m-%d %H:%M:%S.%L")} #{::Logger::SEV_LABEL[severity]} #{msg}",
+            "Warning: SafeYield expects the method #logger to be defined in the class it is included in, the method was not found in #{self.class}"
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ably/modules/state_emitter.rb

@@ -6,6 +6,8 @@ module Ably::Modules
   # It also ensures the EventEmitter is configured to retrict permitted events to the
   # the available STATEs and :error.
   #
+  # @note This module requires that the method #logger is defined.
+  #
   # @example
   #   class Connection
   #     include Ably::Modules::EventEmitter
@@ -91,22 +93,29 @@ module Ably::Modules
         end if failure_block
 
         Array(target_states).each do |target_state|
-          once target_state, &success_wrapper
+          safe_unsafe_method options[:unsafe], :once, target_state, &success_wrapper
 
-          once_state_changed do |*args|
+          safe_unsafe_method options[:unsafe], :once_state_changed do |*args|
             failure_wrapper.call *args unless state == target_state
           end if failure_block
         end
       end
     end
 
+    # Equivalent of {#once_or_if} 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.
+    # @api private
+    def unsafe_once_or_if(target_states, options = {}, &block)
+      once_or_if(target_states, options.merge(unsafe: true), &block)
+    end
+
     # Calls the block once when the state changes
     #
     # @yield block is called once the state changes
     # @return [void]
     #
     # @api private
-    def once_state_changed(&block)
+    def once_state_changed(options = {}, &block)
       raise ArgumentError, 'Block required' unless block_given?
 
       once_block = proc do |*args|
@@ -114,17 +123,24 @@ module Ably::Modules
         yield *args
       end
 
-      once *self.class::STATE.map, &once_block
+      safe_unsafe_method options[:unsafe], :once, *self.class::STATE.map, &once_block
+    end
+
+    # Equivalent of {#once_state_changed} 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.
+    # @api private
+    def unsafe_once_state_changed(&block)
+      once_state_changed(unsafe: true, &block)
     end
 
     private
 
-    # Returns an {EventMachine::Deferrable} and once the target state is reached, the
-    # success block if provided and {EventMachine::Deferrable#callback} is called.
-    # If the state changes to any other state, the {EventMachine::Deferrable#errback} is called.
+    # Returns an {Ably::Util::SafeDeferrable} and once the target state is reached, the
+    # success block if provided and {Ably::Util::SafeDeferrable#callback} is called.
+    # If the state changes to any other state, the {Ably::Util::SafeDeferrable#errback} is called.
     #
     def deferrable_for_state_change_to(target_state)
-      EventMachine::DefaultDeferrable.new.tap do |deferrable|
+      Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
         once_or_if(target_state, else: proc { |*args| deferrable.fail self, *args }) do
           yield self if block_given?
           deferrable.succeed self
@@ -149,5 +165,9 @@ module Ably::Modules
         end
       end
     end
+
+    def safe_unsafe_method(unsafe, method_name, *args, &block)
+      public_send("#{'unsafe_' if unsafe}#{method_name}", *args, &block)
+    end
   end
 end

data/lib/ably/realtime.rb

@@ -5,13 +5,8 @@ require 'ably/modules/event_emitter'
 
 require 'ably/realtime/channel'
 require 'ably/realtime/channels'
-require 'ably/realtime/channel/channel_manager'
-require 'ably/realtime/channel/channel_state_machine'
 require 'ably/realtime/client'
 require 'ably/realtime/connection'
-require 'ably/realtime/connection/connection_manager'
-require 'ably/realtime/connection/connection_state_machine'
-require 'ably/realtime/connection/websocket_transport'
 require 'ably/realtime/presence'
 
 Dir.glob(File.expand_path("models/*.rb", File.dirname(__FILE__))).each do |file|

data/lib/ably/realtime/channel.rb

@@ -33,6 +33,7 @@ module Ably
       include Ably::Modules::EventEmitter
       include Ably::Modules::EventMachineHelpers
       include Ably::Modules::AsyncWrapper
+      include Ably::Modules::MessageEmitter
       extend Ably::Modules::Enum
 
       STATE = ruby_enum('STATE',
@@ -84,7 +85,6 @@ module Ably
         @client        = client
         @name          = name
         @options       = channel_options.clone.freeze
-        @subscriptions = Hash.new { |hash, key| hash[key] = [] }
         @queue         = []
 
         @state_machine = ChannelStateMachine.new(self)
@@ -92,6 +92,7 @@ module Ably
         @manager       = ChannelManager.new(self, client.connection)
 
         setup_event_handlers
+        setup_presence
       end
 
       # Publish a message on the channel
@@ -123,33 +124,25 @@ module Ably
 
       # Subscribe to messages matching providing event name, or all messages if event name not provided
       #
-      # @param name [String] The event name of the message to subscribe to if provided.  Defaults to all events.
+      # @param names [String] The event name of the message to subscribe to if provided.  Defaults to all events.
       # @yield [Ably::Models::Message] For each message received, the block is called
       #
       # @return [void]
       #
-      def subscribe(name = :all, &callback)
+      def subscribe(*names, &callback)
         attach unless attached? || attaching?
-        subscriptions[message_name_key(name)] << callback
+        super
       end
 
       # Unsubscribe the matching block for messages matching providing event name, or all messages if event name not provided.
       # If a block is not provided, all subscriptions will be unsubscribed
       #
-      # @param name [String] The event name of the message to subscribe to if provided.  Defaults to all events.
+      # @param names [String] The event name of the message to subscribe to if provided.  Defaults to all events.
       #
       # @return [void]
       #
-      def unsubscribe(name = :all, &callback)
-        if message_name_key(name) == :all
-          subscriptions.keys
-        else
-          Array(message_name_key(name))
-        end.each do |key|
-          subscriptions[key].delete_if do |block|
-            !block_given? || callback == block
-          end
-        end
+      def unsubscribe(*names, &callback)
+        super
       end
 
       # Attach to this channel, and call the block if provided when attached.
@@ -157,7 +150,7 @@ module Ably
       # to need to call attach explicitly.
       #
       # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Attached state
-      # @return [EventMachine::Deferrable] Deferrable that supports both success (callback) and failure (errback) callback
+      # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callback
       #
       def attach(&success_block)
         transition_state_machine :attaching if can_transition_to?(:attaching)
@@ -183,7 +176,7 @@ module Ably
       #
       def presence
         attach if initialized?
-        @presence ||= Presence.new(self)
+        @presence
       end
 
       # Return the message history of the channel
@@ -193,7 +186,7 @@ module Ably
       #
       # @yield [Ably::Models::PaginatedResource<Ably::Models::Message>] An Array of {Ably::Models::Message} objects that supports paging (#next_page, #first_page)
       #
-      # @return [EventMachine::Deferrable]
+      # @return [Ably::Util::SafeDeferrable]
       def history(options = {}, &callback)
         async_wrap(callback) do
           rest_channel.history(options.merge(async_blocking_operations: true))
@@ -214,6 +207,11 @@ module Ably
         @error_reason = error
       end
 
+      # @api private
+      def clear_error_reason
+        @error_reason = nil
+      end
+
       # Used by {Ably::Modules::StateEmitter} to debug state changes
       # @api private
       def logger
@@ -221,14 +219,12 @@ module Ably
       end
 
       private
-      attr_reader :queue, :subscriptions
+      attr_reader :queue
 
       def setup_event_handlers
         __incoming_msgbus__.subscribe(:message) do |message|
           message.decode self
-
-          subscriptions[:all].each         { |cb| cb.call(message) }
-          subscriptions[message.name].each { |cb| cb.call(message) }
+          emit_message message.name, message
         end
 
         on(STATE.Attached) do
@@ -273,7 +269,7 @@ module Ably
         message.merge!(data: data) unless data.nil?
         message.merge!(clientId: client.client_id) if client.client_id
 
-        Ably::Models::Message.new(message, nil).tap do |message|
+        Ably::Models::Message.new(message, logger: logger).tap do |message|
           message.encode self
         end
       end
@@ -286,13 +282,12 @@ module Ably
         client.connection
       end
 
-      def message_name_key(name)
-        if name == :all
-          :all
-        else
-          name.to_s
-        end
+      def setup_presence
+        @presence ||= Presence.new(self)
       end
     end
   end
 end
+
+require 'ably/realtime/channel/channel_manager'
+require 'ably/realtime/channel/channel_state_machine'

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

@@ -13,13 +13,7 @@ module Ably::Realtime
         @channel    = channel
         @connection = connection
 
-        connection.on(:closed) do
-          channel.transition_state_machine :detaching if can_transition_to?(:detaching)
-        end
-
-        connection.on(:failed) do |error|
-          channel.transition_state_machine :failed, error if can_transition_to?(:failed)
-        end
+        setup_connection_event_handlers
       end
 
       # Commence attachment
@@ -39,12 +33,12 @@ module Ably::Realtime
         end
       end
 
-      # Commence presence SYNC if applicable
-      def sync(attached_protocol_message)
+      # Channel is attached, notify presence if sync is expected
+      def attached(attached_protocol_message)
         if attached_protocol_message.has_presence_flag?
-          channel.presence.sync_started
+          channel.presence.manager.sync_expected
         else
-          channel.presence.sync_completed
+          channel.presence.manager.sync_not_expected
         end
       end
 
@@ -59,6 +53,45 @@ module Ably::Realtime
         channel.transition_state_machine! :detaching, error
       end
 
+      # When a channel is no longer attached or has failed,
+      # all messages awaiting an ACK response should fail immediately
+      def fail_messages_awaiting_ack(error)
+        # Allow a short time for other queued operations to complete before failing all messages
+        EventMachine.add_timer(0.1) do
+          error = Ably::Exceptions::MessageDeliveryError.new('Channel is no longer in a state suitable to deliver this message to the server') unless error
+          fail_messages_in_queue connection.__pending_message_ack_queue__, error
+          fail_messages_in_queue connection.__outgoing_message_queue__, error
+        end
+      end
+
+      def fail_messages_in_queue(queue, error)
+        queue.delete_if do |protocol_message|
+          if protocol_message.channel == channel.name
+            nack_messages protocol_message, error
+            true
+          end
+        end
+      end
+
+      def nack_messages(protocol_message, error)
+        (protocol_message.messages + protocol_message.presence).each do |message|
+          logger.debug "Calling NACK failure callbacks for #{message.class.name} - #{message.to_json}, protocol message: #{protocol_message}"
+          message.fail message, error
+        end
+        logger.debug "Calling NACK failure callbacks for #{protocol_message.class.name} - #{protocol_message.to_json}"
+        protocol_message.fail protocol_message, error
+      end
+
+      def drop_pending_queue_from_ack(ack_protocol_message)
+        message_serial_up_to = ack_protocol_message.message_serial + ack_protocol_message.count - 1
+        connection.__pending_message_ack_queue__.drop_while do |protocol_message|
+          if protocol_message.message_serial <= message_serial_up_to
+            yield protocol_message
+            true
+          end
+        end
+      end
+
       private
 
       attr_reader :channel, :connection
@@ -84,6 +117,16 @@ module Ably::Realtime
         )
       end
 
+      def setup_connection_event_handlers
+        connection.unsafe_on(:closed) do
+          channel.transition_state_machine :detaching if can_transition_to?(:detaching)
+        end
+
+        connection.unsafe_on(:failed) do |error|
+          channel.transition_state_machine :failed, error if can_transition_to?(:failed)
+        end
+      end
+
       def logger
         connection.logger
       end

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

@@ -35,7 +35,7 @@ module Ably::Realtime
       end
 
       before_transition(to: [:attached]) do |channel, current_transition|
-        channel.manager.sync current_transition.metadata
+        channel.manager.attached current_transition.metadata
       end
 
       after_transition(to: [:detaching]) do |channel, current_transition|
@@ -43,17 +43,31 @@ module Ably::Realtime
       end
 
       after_transition(to: [:detached]) do |channel, current_transition|
-        channel.manager.emit_error current_transition.metadata if current_transition.metadata
+        channel.manager.fail_messages_awaiting_ack nil_unless_error(current_transition.metadata)
+        channel.manager.emit_error current_transition.metadata if is_error_type?(current_transition.metadata)
       end
 
       after_transition(to: [:failed]) do |channel, current_transition|
-        channel.manager.emit_error current_transition.metadata
+        channel.manager.fail_messages_awaiting_ack nil_unless_error(current_transition.metadata)
+        channel.manager.emit_error current_transition.metadata if is_error_type?(current_transition.metadata)
       end
 
       # Transitions responsible for updating channel#error_reason
-      before_transition(to: [:attached, :detached, :failed]) do |channel, current_transition|
-        reason = current_transition.metadata if is_error_type?(current_transition.metadata)
-        channel.set_failed_channel_error_reason reason
+      before_transition(to: [:failed]) do |channel, current_transition|
+        channel.set_failed_channel_error_reason current_transition.metadata if is_error_type?(current_transition.metadata)
+      end
+
+      before_transition(to: [:attached, :detached]) do |channel, current_transition|
+        if is_error_type?(current_transition.metadata)
+          channel.set_failed_channel_error_reason current_transition.metadata
+        else
+          # Attached & Detached are "healthy" final states so reset the error reason
+          channel.clear_error_reason
+        end
+      end
+
+      def self.nil_unless_error(error_object)
+        error_object if is_error_type?(error_object)
       end
 
       private
@@ -61,6 +75,7 @@ module Ably::Realtime
         object
       end
 
+      # Logged needs to be defined as it is used by {Ably::Modules::StateMachine}
       def logger
         channel.logger
       end