ably 0.1.6 → 0.2.0

data/lib/ably/realtime/client/incoming_message_dispatcher.rb

@@ -8,6 +8,7 @@ module Ably::Realtime
       def initialize(client, connection)
         @client     = client
         @connection = connection
+
         subscribe_to_incoming_protocol_messages
       end
 
@@ -21,7 +22,7 @@ module Ably::Realtime
       def get_channel(channel_name)
         channels.fetch(channel_name) do
           logger.warn "Received channel message for non-existent channel"
-          Ably::Models::NilChannel.new
+          Ably::Realtime::Models::NilChannel.new
         end
       end
 
@@ -64,7 +65,9 @@ module Ably::Realtime
           when ACTION.Error
             logger.error "Error received: #{protocol_message.error}"
             if protocol_message.channel && !protocol_message.has_message_serial?
-              get_channel(protocol_message.channel).change_state Ably::Realtime::Channel::STATE.Failed, protocol_message.error
+              dispatch_channel_error protocol_message
+            else
+              connection.transition_state_machine :failed, protocol_message.error
             end
 
           when ACTION.Attach
@@ -90,6 +93,14 @@ module Ably::Realtime
         end
       end
 
+      def dispatch_channel_error(protocol_message)
+        if !protocol_message.has_message_serial?
+          get_channel(protocol_message.channel).change_state Ably::Realtime::Channel::STATE.Failed, protocol_message.error
+        else
+          logger.fatal "Cannot process ProtocolMessage as not yet implemented: #{protocol_message}"
+        end
+      end
+
       def update_connection_id(protocol_message)
         if protocol_message.connection_id && (protocol_message.connection_id != connection.id)
           logger.debug "New connection ID set to #{protocol_message.connection_id}"
@@ -136,7 +147,7 @@ module Ably::Realtime
       end
 
       def subscribe_to_incoming_protocol_messages
-        connection.__incoming_protocol_msgbus__.subscribe(:message) do |*args|
+        connection.__incoming_protocol_msgbus__.subscribe(:protocol_message) do |*args|
           dispatch_protocol_message *args
         end
       end

data/lib/ably/realtime/client/outgoing_message_dispatcher.rb

@@ -11,6 +11,7 @@ module Ably::Realtime
       def initialize(client, connection)
         @client     = client
         @connection = connection
+
         subscribe_to_outgoing_protocol_message_queue
         setup_event_handlers
       end
@@ -34,19 +35,27 @@ module Ably::Realtime
         connection.__pending_message_queue__
       end
 
+      def current_transport_outgoing_message_bus
+        connection.transport.__outgoing_protocol_msgbus__
+      end
+
       def deliver_queued_protocol_messages
         condition = -> { can_send_messages? && messages_in_outgoing_queue? }
 
         non_blocking_loop_while(condition) do
           protocol_message = outgoing_queue.shift
-          pending_queue << protocol_message if protocol_message.ack_required?
-          connection.transport.send_object protocol_message
-          client.logger.debug "Prot msg sent =>: #{protocol_message.action} #{protocol_message}"
+          current_transport_outgoing_message_bus.publish :protocol_message, protocol_message
+
+          if protocol_message.ack_required?
+            pending_queue << protocol_message
+          else
+            protocol_message.succeed protocol_message
+          end
         end
       end
 
       def subscribe_to_outgoing_protocol_message_queue
-        connection.__outgoing_protocol_msgbus__.subscribe(:message) do |*args|
+        connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |*args|
           deliver_queued_protocol_messages
         end
       end

data/lib/ably/realtime/connection.rb

@@ -23,6 +23,12 @@ module Ably
     #   Connection::STATE.Closed
     #   Connection::STATE.Failed
     #
+    # @example
+    #    client = Ably::Realtime::Client.new('key.id:secret')
+    #    client.connection.on(:connected) do
+    #      puts "Connected with connection ID: #{client.connection.id}"
+    #    end
+    #
     # @!attribute [r] state
     #   @return {Ably::Realtime::Connection::STATE} connection state
     # @!attribute [r] id
@@ -31,6 +37,7 @@ module Ably
     #   @return {Ably::Models::ErrorInfo} error information associated with a connection failure
     class Connection
       include Ably::Modules::EventEmitter
+      include Ably::Modules::Conversions
       extend Ably::Modules::Enum
 
       # Valid Connection states
@@ -52,6 +59,11 @@ module Ably
       # @return {Ably::Realtime::Connection::WebsocketTransport}
       attr_reader :transport
 
+      # @api private
+      # The connection manager responsible for creating, maintaining and closing the connection and underlying transport
+      # @return {Ably::Realtime::Connection::ConnectionManager}
+      attr_reader :manager
+
       # @api private
       # An internal queue used to manage unsent outgoing messages.  You should never interface with this array directly
       # @return [Array]
@@ -62,11 +74,6 @@ module Ably
       # @return [Array]
       attr_reader :__pending_message_queue__
 
-      # @api private
-      # Timers used to manage connection state, for internal use by the client library
-      # @return [Hash]
-      attr_reader :timers
-
       # @api public
       def initialize(client)
         @client                     = client
@@ -75,9 +82,6 @@ module Ably
         @__outgoing_message_queue__ = []
         @__pending_message_queue__  = []
 
-        @timers                     = Hash.new { |hash, key| hash[key] = [] }
-        @timers[:initializer]       << EventMachine::Timer.new(0.001) { connect }
-
         Client::IncomingMessageDispatcher.new client, self
         Client::OutgoingMessageDispatcher.new client, self
 
@@ -86,6 +90,7 @@ module Ably
         end
 
         @state_machine              = ConnectionStateMachine.new(self)
+        @manager                    = ConnectionManager.new(self)
         @state                      = STATE(state_machine.current_state)
       end
 
@@ -95,13 +100,13 @@ module Ably
       #
       # @yield [Ably::Realtime::Connection] block is called as soon as this connection is in the Closed state
       #
-      # @return <void>
+      # @return [void]
       def close(&block)
         if closed?
           block.call self
         else
           EventMachine.next_tick do
-            state_machine.transition_to(:closed)
+            transition_state_machine(:closed)
           end
           once(STATE.Closed) { block.call self } if block_given?
         end
@@ -112,46 +117,107 @@ module Ably
       #
       # @yield [Ably::Realtime::Connection] block is called as soon as this connection is in the Connected state
       #
-      # @return <void>
+      # @return [void]
       def connect(&block)
         if connected?
           block.call self
         else
-          state_machine.transition_to(:connecting)
+          transition_state_machine(:connecting) unless connecting?
           once(STATE.Connected) { block.call self } if block_given?
         end
       end
 
+      # Sends a ping to Ably and yields the provided block when a heartbeat ping request is echoed from the server.
+      # This can be useful for measuring true roundtrip client to Ably server latency for a simple message, or checking that an underlying transport is responding currently.
+      # The elapsed milliseconds is passed as an argument to the block and represents the time taken to echo a ping heartbeat once the connection is in the `:connected` state.
+      #
+      # @yield [Integer] if a block is passed to this method, then this block will be called once the ping heartbeat is received with the time elapsed in milliseconds
+      #
+      # @example
+      #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+      #    client.connection.ping do |ms_elapsed|
+      #      puts "Ping took #{ms_elapsed}ms"
+      #    end
+      #
+      def ping(&block)
+        raise RuntimeError, 'Cannot send a ping when connection is in a closed or failed state' if closed? || failed?
+
+        started = nil
+
+        wait_for_ping = Proc.new do |protocol_message|
+          if protocol_message.action == Ably::Models::ProtocolMessage::ACTION.Heartbeat
+            __incoming_protocol_msgbus__.unsubscribe(:protocol_message, &wait_for_ping)
+            time_passed = (Time.now.to_f * 1000 - started.to_f * 1000).to_i
+            block.call time_passed if block_given?
+          end
+        end
+
+        once(STATE.Connected) do
+          started = Time.now
+          send_protocol_message action: Ably::Models::ProtocolMessage::ACTION.Heartbeat.to_i
+          __incoming_protocol_msgbus__.subscribe :protocol_message, &wait_for_ping
+        end
+      end
+
       # Reconfigure the current connection ID
-      # @return <void>
+      # @return [void]
       # @api private
       def update_connection_id(connection_id)
         @id = connection_id
       end
 
-      # Send #transition_to to connection state machine
-      # @return [Boolean] true if new_state can be transitioned_to by state machine
+      # Call #transition_to on {Ably::Realtime::Connection::ConnectionStateMachine}
+      #
+      # @return [Boolean] true if new_state can be transitioned to by state machine
       # @api private
-      def transition_state_machine(new_state)
-        state_machine.transition_to(new_state)
+      def transition_state_machine(new_state, emit_object = nil)
+        state_machine.transition_to(new_state, emit_object)
+      end
+
+      # Call #transition_to! on {Ably::Realtime::Connection::ConnectionStateMachine}.
+      # An exception wil be raised if new_state cannot be transitioned to by state machine
+      #
+      # @return [void]
+      # @api private
+      def transition_state_machine!(new_state, emit_object = nil)
+        state_machine.transition_to!(new_state, emit_object)
+      end
+
+      # Provides an internal method for the {Ably::Realtime::Connection} state to match the {Ably::Realtime::Connection::ConnectionStateMachine}'s state
+      # @api private
+      def synchronize_state_with_statemachine(*args)
+        log_state_machine_state_change
+        change_state state_machine.current_state, state_machine.last_transition.metadata
       end
 
       # @!attribute [r] __outgoing_protocol_msgbus__
-      # @return [Ably::Util::PubSub] Client library internal outgoing message bus
+      # @return [Ably::Util::PubSub] Client library internal outgoing protocol message bus
       # @api private
       def __outgoing_protocol_msgbus__
         @__outgoing_protocol_msgbus__ ||= create_pub_sub_message_bus
       end
 
       # @!attribute [r] __incoming_protocol_msgbus__
-      # @return [Ably::Util::PubSub] Client library internal incoming message bus
+      # @return [Ably::Util::PubSub] Client library internal incoming protocol message bus
       # @api private
       def __incoming_protocol_msgbus__
         @__incoming_protocol_msgbus__ ||= create_pub_sub_message_bus
       end
 
+      # @!attribute [r] host
+      # @return [String] The default host name used for this connection
+      def host
+        client.endpoint.host
+      end
+
+      # @!attribute [r] port
+      # @return [Integer] The default port used for this connection
+      def port
+        client.use_tls? ? 443 : 80
+      end
+
       # @!attribute [r] logger
-      # @return [Logger] The Logger configured for this client when the client was instantiated.
+      # @return [Logger] The {Ably::Logger} for this client.
       #                  Configure the log_level with the `:log_level` option, refer to {Ably::Realtime::Client#initialize}
       def logger
         client.logger
@@ -161,67 +227,99 @@ module Ably
       # ready to be sent
       #
       # @param [Ably::Models::ProtocolMessage] protocol_message
-      # @return <void>
+      # @return [void]
       # @api private
       def send_protocol_message(protocol_message)
         add_message_serial_if_ack_required_to(protocol_message) do
-          Models::ProtocolMessage.new(protocol_message).tap do |protocol_message|
+          Ably::Models::ProtocolMessage.new(protocol_message).tap do |protocol_message|
             add_message_to_outgoing_queue protocol_message
             notify_message_dispatcher_of_new_message protocol_message
-            logger.debug("Prot msg queued =>: #{protocol_message.action} #{protocol_message}")
+            logger.debug("Connection: Prot msg queued =>: #{protocol_message.action} #{protocol_message}")
           end
         end
       end
 
+      # @api private
       def add_message_to_outgoing_queue(protocol_message)
         __outgoing_message_queue__ << protocol_message
       end
 
+      # @api private
       def notify_message_dispatcher_of_new_message(protocol_message)
-        __outgoing_protocol_msgbus__.publish :message, protocol_message
+        __outgoing_protocol_msgbus__.publish :protocol_message, protocol_message
       end
 
-      # Creates and sets up a new {WebSocketTransport} available on attribute #transport
-      # @yield [Ably::Realtime::Connection::WebsocketTransport] block is called with new websocket transport
+      # @!attribute [r] previous_state
+      # @return [Ably::Realtime::Connection::STATE,nil] The previous state for this connection
       # @api private
-      def setup_transport(&block)
-        if transport && !transport.ready_for_release?
-          raise RuntimeError, "Existing WebsocketTransport is connected, and must be closed first"
+      def previous_state
+        if state_machine.previous_state
+          STATE(state_machine.previous_state)
         end
+      end
 
-        @transport = EventMachine.connect(connection_host, connection_port, WebsocketTransport, self) do |websocket|
-          yield websocket
+      # @!attribute [r] state_history
+      # @return [Array<Hash>] All previous states including the current state in date ascending order with Hash properties :state, :metadata, :transitioned_at
+      # @api private
+      def state_history
+        state_machine.history.map do |transition|
+          {
+            state:           STATE(transition.to_state),
+            metadata:        transition.metadata,
+            transitioned_at: transition.created_at
+          }
         end
       end
 
-      # Reconnect the {Ably::Realtime::Connection::WebsocketTransport} following a disconnection
       # @api private
-      def reconnect_transport
-        raise RuntimeError, "WebsocketTransport is not set up" if !transport
-        raise RuntimeError, "WebsocketTransport is not disconnected so cannot be reconnected" if !transport.disconnected?
-
-        transport.reconnect(connection_host, connection_port)
-      end
+      def create_websocket_transport(&block)
+        operation = proc do
+          URI(client.endpoint).tap do |endpoint|
+            endpoint.query = URI.encode_www_form(client.auth.auth_params.merge(
+              timestamp: as_since_epoch(Time.now),
+              format:    client.protocol,
+              echo:      client.echo_messages
+            ))
+          end.to_s
+        end
 
-      private
-      attr_reader :manager, :serial, :state_machine
+        callback = proc do |url|
+          begin
+            @transport = EventMachine.connect(host, port, WebsocketTransport, self, url) do |websocket_transport|
+              yield websocket_transport if block_given?
+            end
+          rescue EventMachine::ConnectionError => error
+            manager.connection_failed error
+          end
+        end
 
-      def connection_host
-        client.endpoint.host
+        # client.auth.auth_params is a blocking call, so defer this into a thread
+        EventMachine.defer operation, callback
       end
 
-      def connection_port
-        client.use_tls? ? 443 : 80
+      # @api private
+      def release_websocket_transport
+        @transport = nil
       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
+
+      private
+      attr_reader :serial, :state_machine
+
       def create_pub_sub_message_bus
         Ably::Util::PubSub.new(
-          coerce_into: Proc.new { |event| Models::ProtocolMessage::ACTION(event) }
+          coerce_into: Proc.new do |event|
+            raise KeyError, "Expected :protocol_message, :#{event} is disallowed" unless event == :protocol_message
+            :protocol_message
+          end
         )
       end
 
       def add_message_serial_if_ack_required_to(protocol_message)
-        if Models::ProtocolMessage.ack_required?(protocol_message[:action])
+        if Ably::Models::ProtocolMessage.ack_required?(protocol_message[:action])
           add_message_serial_to(protocol_message) { yield }
         else
           yield
@@ -236,6 +334,14 @@ module Ably
         @serial -= 1
         raise e
       end
+
+      def log_state_machine_state_change
+        if state_machine.previous_state
+          logger.debug "ConnectionStateMachine: Transitioned from #{state_machine.previous_state} => #{state_machine.current_state}"
+        else
+          logger.debug "ConnectionStateMachine: Transitioned to #{state_machine.current_state}"
+        end
+      end
     end
   end
 end

data/lib/ably/realtime/connection/connection_manager.rb

@@ -0,0 +1,168 @@
+module Ably::Realtime
+  class Connection
+    # ConnectionManager is responsible for all actions relating to underlying connection and transports,
+    # such as opening, closing, attempting reconnects etc.
+    #
+    # This is a private class and should never be used directly by developers as the API is likely to change in future.
+    #
+    # @api private
+    class ConnectionManager
+      CONNECTION_FAILED = { retry_after: 0.5, max_retries: 2, code: 80000 }.freeze
+
+      def initialize(connection)
+        @connection = connection
+
+        @timers               = Hash.new { |hash, key| hash[key] = [] }
+        @timers[:initializer] << EventMachine::Timer.new(0.01) { connection.connect }
+      end
+
+      # Creates and sets up a new {Ably::Realtime::Connection::WebsocketTransport} available on attribute #transport
+      #
+      # @yield [Ably::Realtime::Connection::WebsocketTransport] block is called with new websocket transport
+      # @api private
+      def setup_transport(&block)
+        if transport && !transport.ready_for_release?
+          raise RuntimeError, 'Existing WebsocketTransport is connected, and must be closed first'
+        end
+
+        logger.debug "ConnectionManager: Opening connection to #{connection.host}:#{connection.port}"
+
+        connection.create_websocket_transport do |websocket_transport|
+          subscribe_to_transport_events websocket_transport
+          yield websocket_transport if block_given?
+        end
+      end
+
+      # Called by the transport when a connection attempt fails
+      #
+      # @api private
+      def connection_failed(error)
+        logger.info "ConnectionManager: Connection to #{connection.host}:#{connection.port} failed; #{error.message}"
+        connection.transition_state_machine :disconnected, Ably::Models::ErrorInfo.new(message: "Connection failed; #{error.message}", code: 80000)
+      end
+
+      # Ensures the underlying transport has been disconnected and all event emitter callbacks removed
+      #
+      # @api private
+      def destroy_transport
+        if transport
+          unsubscribe_from_transport_events transport
+          transport.close_connection
+          connection.release_websocket_transport
+        end
+      end
+
+      # Reconnect the {Ably::Realtime::Connection::WebsocketTransport} if possible, otherwise set up a new transport
+      #
+      # @api private
+      def reconnect_transport
+        if !transport || transport.disconnected?
+          setup_transport
+        else
+          transport.reconnect connection.host, connection.port
+        end
+      end
+
+      # Send a Close {Ably::Models::ProtocolMessage} to the server and release the transport
+      #
+      # @api private
+      def close_connection
+        protocol_message = connection.send_protocol_message(action: Ably::Models::ProtocolMessage::ACTION.Close)
+
+        unsubscribe_from_transport_events transport
+
+        protocol_message.callback do
+          destroy_transport
+        end
+      end
+
+      # Remove all timers set up as part of the initialize process.
+      # Typically called by StateMachine when connection is closed and can no longer process the timers
+      #
+      # @api private
+      def cancel_initialized_timers
+        clear_timers :initializer
+      end
+
+      # Remove all timers related to connection attempt retries following a disconnect or suspended connection state.
+      # Typically called by StateMachine when connection is opened to ensure no further connection attempts are made
+      #
+      # @api private
+      def cancel_connection_retry_timers
+        clear_timers :connection_retry_timers
+      end
+
+      # When a connection is disconnected try and reconnect or set the connection state to :failed
+      #
+      # @api private
+      def respond_to_transport_disconnected(current_transition)
+        error_code = current_transition && current_transition.metadata && current_transition.metadata.code
+
+        if connection.previous_state == :connecting && error_code == CONNECTION_FAILED[:code]
+          return if retry_connection_failed
+        end
+
+        # Fallback if no other criteria met
+        connection.transition_state_machine :failed, current_transition.metadata
+      end
+
+      private
+      attr_reader :connection
+
+      # Timers used to manage connection state, for internal use by the client library
+      # @return [Hash]
+      attr_reader :timers
+
+      def transport
+        connection.transport
+      end
+
+      def client
+        connection.client
+      end
+
+      def clear_timers(key)
+        timers.fetch(key, []).each(&:cancel)
+      end
+
+      def retry_connection_failed
+        if retries_for_state(:disconnected, ignore_states: [:connecting]).count < CONNECTION_FAILED[:max_retries]
+          logger.debug "ConnectionManager: Pausing for #{CONNECTION_FAILED[:retry_after]}s before attempting to reconnect"
+          @timers[:connection_retry_timers] << EventMachine::Timer.new(CONNECTION_FAILED[:retry_after]) do
+            connection.connect
+          end
+        end
+      end
+
+      def retries_for_state(state, ignore_states: [])
+        allowed_states = Array(state) + Array(ignore_states)
+
+        connection.state_history.reverse.take_while do |transition|
+          allowed_states.include?(transition[:state].to_sym)
+        end.select do |transition|
+          transition[:state] == state
+        end
+      end
+
+      def subscribe_to_transport_events(transport)
+        transport.__incoming_protocol_msgbus__.on(:protocol_message) do |protocol_message|
+          connection.__incoming_protocol_msgbus__.publish :protocol_message, protocol_message
+        end
+
+        transport.on(:disconnected) do
+          connection.transition_state_machine :disconnected
+        end
+      end
+
+      def unsubscribe_from_transport_events(transport)
+        transport.__incoming_protocol_msgbus__.unsubscribe
+        transport.off
+        logger.debug "ConnectionManager: Unsubscribed from all events from current transport"
+      end
+
+      def logger
+        connection.logger
+      end
+    end
+  end
+end