ably 0.1.4 → 0.1.5

data/lib/ably/modules/event_machine_helpers.rb

@@ -0,0 +1,21 @@
+module Ably::Modules
+  module EventMachineHelpers
+    private
+
+    # This method allows looped blocks to be run at the next EventMachine tick
+    # @example
+    #   x = 0
+    #   less_than_3 = -> { x < 3 }
+    #   non_blocking_loop_while(less_than_3) do
+    #     x += 1
+    #   end
+    def non_blocking_loop_while(lambda, &execution_block)
+      if lambda.call
+        yield
+        EventMachine.next_tick do
+          non_blocking_loop_while(lambda, &execution_block)
+        end
+      end
+    end
+  end
+end

data/lib/ably/modules/http_helpers.rb

@@ -1,5 +1,9 @@
 require 'base64'
 
+require 'ably/rest/middleware/external_exceptions'
+require 'ably/rest/middleware/parse_json'
+require 'ably/rest/middleware/parse_message_pack'
+
 module Ably::Modules
   module HttpHelpers
     protected
@@ -10,5 +14,14 @@ module Ably::Modules
     def user_agent
       "Ably Ruby client #{Ably::VERSION} (https://ably.io)"
     end
+
+    def setup_middleware(builder)
+      # Convert request params to "www-form-urlencoded"
+      builder.use Faraday::Request::UrlEncoded
+
+      # Parse JSON / MsgPack response bodies.  ParseJson must be first (default) parsing middleware
+      builder.use Ably::Rest::Middleware::ParseJson
+      builder.use Ably::Rest::Middleware::ParseMessagePack
+    end
   end
 end

data/lib/ably/modules/state.rb

@@ -0,0 +1,67 @@
+module Ably::Modules
+  # State module adds a set of generic state related methods to a class on the assumption that
+  # the instance variable @state is used exclusively, the {Enum} STATE is defined prior to inclusion of this
+  # module, and the class is an {EventEmitter}
+  #
+  # @example
+  #   class Connection
+  #     include Ably::Modules::EventEmitter
+  #     extend  Ably::Modules::Enum
+  #     STATE = ruby_enum('STATE',
+  #       :initialized,
+  #       :connecting,
+  #       :connected
+  #     )
+  #     include Ably::Modules::State
+  #   end
+  #
+  #   connection = Connection.new
+  #   connection.state = :connecting     # emits :connecting event via EventEmitter, returns STATE.Connecting
+  #   connection.state?(:connected)      # => false
+  #   connection.connecting?             # => true
+  #   connection.state                   # => STATE.Connecting
+  #   connection.state = :invalid        # raises an Exception as only a valid state can be defined
+  #   connection.trigger :invalid        # raises an Exception as only a valid state can be used for EventEmitter
+  #   connection.change_state :connected # emits :connected event via EventEmitter, returns STATE.Connected
+  #
+  module State
+    # Current state {Ably::Modules::Enum}
+    #
+    # @return [Symbol] state
+    def state
+      STATE(@state)
+    end
+
+    # Evaluates if check_state matches current state
+    #
+    # @return [Boolean]
+    def state?(check_state)
+      state == check_state
+    end
+
+    # Set the current state {Ably::Modules::Enum}
+    #
+    # @return [Symbol] new state
+    def state=(new_state)
+      if state != new_state
+        logger.debug("#{self.class}: State changed from #{state} => #{new_state}") if respond_to?(:logger, true)
+        @state = STATE(new_state)
+        trigger @state
+      end
+    end
+    alias_method :change_state, :state=
+
+    private
+    def self.included(klass)
+      klass.configure_event_emitter coerce_into: Proc.new { |event| klass::STATE(event) }
+
+      klass::STATE.each do |state_predicate|
+        klass.instance_eval do
+          define_method("#{state_predicate.to_sym}?") do
+            state?(state_predicate)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ably/realtime.rb

@@ -1,7 +1,8 @@
 require "eventmachine"
 require "websocket/driver"
 
-require "ably/realtime/callbacks"
+require "ably/modules/event_emitter"
+
 require "ably/realtime/channel"
 require "ably/realtime/client"
 require "ably/realtime/connection"
@@ -9,8 +10,12 @@ require "ably/realtime/connection"
 require "ably/realtime/models/shared"
 require "ably/realtime/models/error_info"
 require "ably/realtime/models/message"
+require "ably/realtime/models/nil_channel"
 require "ably/realtime/models/protocol_message"
 
+require "ably/realtime/client/incoming_message_dispatcher"
+require "ably/realtime/client/outgoing_message_dispatcher"
+
 module Ably
   module Realtime
     def self.new(*args)

data/lib/ably/realtime/channel.rb

@@ -1,59 +1,118 @@
 module Ably
   module Realtime
+    # The Channel class represents a Channel belonging to this application.
+    # The Channel instance allows messages to be published and
+    # received, and controls the lifecycle of this instance's
+    # attachment to the channel.
+    #
+    # Channels will always be in one of the following states:
+    #
+    #   initialized: 0
+    #   attaching:   1
+    #   attached:    2
+    #   detaching:   3
+    #   detached:    4
+    #   failed:      5
+    #
+    # Note that the states are available as Enum-like constants:
+    #
+    #   Channel::STATE.Initialized
+    #   Channel::STATE.Attaching
+    #   Channel::STATE.Attached
+    #   Channel::STATE.Detaching
+    #   Channel::STATE.Detached
+    #   Channel::STATE.Failed
+    #
+    # @!attribute [r] state
+    #   @return {Ably::Realtime::Connection::STATE} channel state
+    #
     class Channel
       include Ably::Modules::Conversions
-      include Callbacks
-
-      STATES = {
-        initialised: 1,
-        attaching:   2,
-        attached:    3,
-        detaching:   4,
-        detached:    5,
-        failed:      6
-      }.freeze
+      include Ably::Modules::EventEmitter
+      include Ably::Modules::EventMachineHelpers
+      extend Ably::Modules::Enum
+
+      STATE = ruby_enum('STATE',
+        :initialized,
+        :attaching,
+        :attached,
+        :detaching,
+        :detached,
+        :failed
+      )
+      include Ably::Modules::State
+
+      # Max number of messages to bundle in a single ProtocolMessage
+      MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50
 
       attr_reader :client, :name
 
-      # Retrieve a state symbol by the integer value
-      def self.state_sym_for(state_int)
-        @states_index_by_int ||= STATES.invert.freeze
-        @states_index_by_int[state_int]
-      end
-
       def initialize(client, name)
-        @client          = client
-        @name            = name
-        @subscriptions   = Hash.new { |hash, key| hash[key] = [] }
-        @queue           = []
+        @client        = client
+        @name          = name
+        @subscriptions = Hash.new { |hash, key| hash[key] = [] }
+        @queue         = []
+        @state         = STATE.Initialized
 
-        set_state :initialised
+        setup_event_handlers
+      end
 
-        on(:message) do |message|
-          @subscriptions[:all].each { |cb| cb.call(message) }
-          @subscriptions[message.name].each { |cb| cb.call(message) }
+      # Publish a message on the channel
+      #
+      # @param event [String] The event name of the message
+      # @param data [String,ByteArray] payload for the message
+      # @yield [Ably::Realtime::Models::Message] On success, will call the block with the {Ably::Realtime::Models::Message}
+      # @return [Ably::Realtime::Models::Message]
+      #
+      def publish(event, data, &callback)
+        Models::Message.new({
+          name: event,
+          data: data,
+          timestamp: as_since_epoch(Time.now),
+          client_id: client.client_id
+        }, nil).tap do |message|
+          message.callback(&callback) if block_given?
+          queue_message message
         end
+      end
 
-        on(:attached) do
-          set_state :attached
-          process_queue
+      def subscribe(event = :all, &blk)
+        event = event.to_s unless event == :all
+        attach unless attached? || attaching?
+        @subscriptions[event] << blk
+      end
+
+      def attach
+        unless attached? || attaching?
+          change_state STATE.Attaching
+          send_attach_protocol_message
         end
       end
 
-      # Current Channel state, will always be one of {STATES}
-      #
-      # @return [Symbol] state
-      def state
-        self.class.state_sym_for(@state)
+      def __incoming_protocol_msgbus__
+        @__incoming_protocol_msgbus__ ||= Ably::Util::PubSub.new(
+          coerce_into: Proc.new { |event| Models::ProtocolMessage::ACTION(event) }
+        )
       end
 
-      def state?(check_state)
-        check_state = STATES.fetch(check_state) if check_state.kind_of?(Symbol)
-        @state == check_state
+      private
+      attr_reader :queue
+
+      def setup_event_handlers
+        __incoming_protocol_msgbus__.subscribe(:message) do |message|
+          @subscriptions[:all].each         { |cb| cb.call(message) }
+          @subscriptions[message.name].each { |cb| cb.call(message) }
+        end
+
+        on(:attached) do
+          process_queue
+        end
       end
 
-      def publish(event, data)
-        queue << { name: event, data: data, timestamp: as_since_epoch(Time.now) }
+      # Queue message and process queue if channel is attached.
+      # If channel is not yet attached, attempt to attach it before the message queue is processed.
+      def queue_message(message)
+        queue << message
 
         if attached?
           process_queue
@@ -62,34 +121,36 @@ module Ably
         end
       end
 
-      def subscribe(event = :all, &blk)
-        event = event.to_s unless event == :all
-        attach unless attached?
-        @subscriptions[event] << blk
+      def messages_in_queue?
+        !queue.empty?
       end
 
-      def attach
-        unless state?(:attaching)
-          set_state :attaching
-          client.attach_to_channel(name)
+      # Move messages from Channel Queue into Outgoing Connection Queue
+      def process_queue
+        condition = -> { attached? && messages_in_queue? }
+        non_blocking_loop_while(condition) do
+          send_messages_within_protocol_message(queue.shift(MAX_PROTOCOL_MESSAGE_BATCH_SIZE))
         end
       end
 
-      def attached?
-        state?(:attached)
+      def send_messages_within_protocol_message(messages)
+        client.connection.send_protocol_message(
+          action:   Models::ProtocolMessage::ACTION.Message.to_i,
+          channel:  name,
+          messages: messages
+        )
       end
 
-      private
-      attr_reader :queue
-
-      def set_state(new_state)
-        new_state = STATES.fetch(new_state) if new_state.kind_of?(Symbol)
-        raise ArgumentError, "#{new_state} is not a valid state" unless STATES.values.include?(new_state)
-        @state = new_state
+      def send_attach_protocol_message
+        client.connection.send_protocol_message(
+          action:  Models::ProtocolMessage::ACTION.Attach.to_i,
+          channel: name
+        )
       end
 
-      def process_queue
-        client.send_messages(name, queue.shift(100)) until queue.empty?
+      # Used by {Ably::Modules::State} to debug state changes
+      def logger
+        client.logger
       end
     end
   end

data/lib/ably/realtime/client.rb

@@ -13,14 +13,13 @@ module Ably
     # @!attribute [r] environment
     #   (see Ably::Rest::Client#environment)
     class Client
-      include Callbacks
       extend Forwardable
 
       DOMAIN = 'realtime.ably.io'
 
       attr_reader :channels, :auth
       def_delegators :auth, :client_id, :auth_options
-      def_delegators :@rest_client, :tls, :environment, :use_tls?
+      def_delegators :@rest_client, :tls, :environment, :use_tls?, :logger, :log_level
 
       # Creates a {Ably::Realtime::Client Realtime Client} and configures the {Ably::Auth} object for the connection.
       #
@@ -29,7 +28,6 @@ module Ably
       # @option options [Boolean] :queue_messages If false, this disables the default behaviour whereby the library queues messages on a connection in the disconnected or connecting states
       # @option options [Boolean] :echo_messages  If false, prevents messages originating from this connection being echoed back on the same connection
       # @option options [String]  :recover        This option allows a connection to inherit the state of a previous connection that may have existed under an different instance of the Realtime library.
-      # @option options [Boolean] :debug_http     Send HTTP & websocket debugging information for all messages/requests sent and received to STDOUT
       #
       # @yield (see Ably::Rest::Client#initialize)
       # @yieldparam (see Ably::Rest::Client#initialize)
@@ -48,20 +46,6 @@ module Ably
         @rest_client    = Ably::Rest::Client.new(options)
         @auth           = @rest_client.auth
         @message_serial = 0
-
-        on(:attached) do |protocol_message|
-          channel = channel(protocol_message.channel)
-
-          channel.trigger(:attached)
-        end
-
-        on(:message) do |protocol_message|
-          channel = channel(protocol_message.channel)
-
-          protocol_message.messages.each do |message|
-            channel.trigger(:message, message)
-          end
-        end
       end
 
       def token
@@ -77,27 +61,6 @@ module Ably
         @channels[name] ||= Ably::Realtime::Channel.new(self, name)
       end
 
-      def send_messages(channel_name, messages)
-        payload = {
-          action:   Models::ProtocolMessage.action!(:message),
-          channel:  channel_name,
-          messages: messages
-        }
-
-        payload.merge!(clientId: client_id) unless client_id.nil?
-
-        connection.send(payload)
-      end
-
-      def attach_to_channel(channel_name)
-        payload = {
-          action:  Models::ProtocolMessage.action!(:attach),
-          channel: channel_name
-        }
-
-        connection.send(payload)
-      end
-
       # Default Ably Realtime endpoint used for all requests
       #
       # @return [URI::Generic]
@@ -113,21 +76,15 @@ module Ably
           host = endpoint.host
           port = use_tls? ? 443 : 80
 
-          EventMachine.connect(host, port, Connection, self)
+          EventMachine.connect(host, port, Connection, self).tap do |connection|
+            connection.on(:connected) do
+              IncomingMessageDispatcher.new(self)
+              OutgoingMessageDispatcher.new(self)
+            end
+          end
         end
       end
 
-      # When true, will send HTTP & websocket debugging information for all messages/requests sent and received to STDOUT
-      #
-      # @return [Boolean]
-      def debug_http?
-        rest_client.debug_http?
-      end
-
-      def log_http(message)
-        $stdout.puts "#{Time.now.strftime('%H:%M:%S')} #{message}" if debug_http?
-      end
-
       private
       attr_reader :rest_client
     end

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

@@ -0,0 +1,116 @@
+module Ably::Realtime
+  class Client
+    # IncomingMessageDispatcher is a (private) class that is used to dispatch {Ably::Realtime::Models::ProtocolMessage} that are
+    # received from Ably via the {Ably::Realtime::Connection}
+    class IncomingMessageDispatcher
+      ACTION = Models::ProtocolMessage::ACTION
+
+      def initialize(client)
+        @client = client
+        subscribe_to_incoming_protocol_messages
+      end
+
+      private
+      attr_reader :client
+
+      def connection
+        client.connection
+      end
+
+      def channels
+        client.channels
+      end
+
+      def get_channel(channel_name)
+        channels.fetch(channel_name) do
+          logger.warn "Received channel message for non-existent channel"
+          Models::NilChannel.new
+        end
+      end
+
+      def logger
+        client.logger
+      end
+
+      def dispatch_protocol_message(*args)
+        protocol_message = args.first
+
+        unless protocol_message.kind_of?(Models::ProtocolMessage)
+          raise ArgumentError, "Expected a ProtocolMessage. Received #{protocol_message}"
+        end
+
+        unless [:nack, :error].include?(protocol_message.action)
+          logger.debug "#{protocol_message.action} received: #{protocol_message}"
+        end
+
+        case protocol_message.action
+          when ACTION.Heartbeat
+          when ACTION.Ack
+            ack_pending_queue_for_message_serial(protocol_message) if protocol_message.has_message_serial?
+
+          when ACTION.Nack
+            logger.warn "NACK received: #{protocol_message}"
+            nack_pending_queue_for_message_serial(protocol_message) if protocol_message.has_message_serial?
+
+          when ACTION.Connect, ACTION.Connected
+          when ACTION.Disconnect, ACTION.Disconnected
+          when ACTION.Close
+          when ACTION.Closed
+          when ACTION.Error
+            logger.error "Error received: #{protocol_message.error}"
+
+          when ACTION.Attach
+          when ACTION.Attached
+            get_channel(protocol_message.channel).change_state Ably::Realtime::Channel::STATE.Attached
+
+          when ACTION.Detach
+          when ACTION.Detached
+            get_channel(protocol_message.channel).change_state Ably::Realtime::Channel::STATE.Detached
+
+          when ACTION.Presence
+          when ACTION.Message
+            protocol_message.messages.each do |message|
+              get_channel(protocol_message.channel).__incoming_protocol_msgbus__.publish :message, message
+            end
+
+          else
+            raise ArgumentError, "Protocol Message Action #{protocol_message.action} is unsupported by this MessageDispatcher"
+        end
+      end
+
+      def ack_pending_queue_for_message_serial(ack_protocol_message)
+        drop_pending_queue_from_ack(ack_protocol_message) do |protocol_message|
+          protocol_message.messages.each do |message|
+            logger.debug "Calling ACK success callbacks for #{message.to_json}"
+            message.succeed message
+          end
+        end
+      end
+
+      def nack_pending_queue_for_message_serial(nack_protocol_message)
+        drop_pending_queue_from_ack(nack_protocol_message) do |protocol_message|
+          protocol_message.messages.each do |message|
+            logger.debug "Calling NACK failure callbacks for #{message.to_json}"
+            message.fail message, nack_protocol_message.error
+          end
+        end
+      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_queue__.drop_while do |protocol_message|
+          if protocol_message.message_serial <= message_serial_up_to
+            yield protocol_message
+            true
+          end
+        end
+      end
+
+      def subscribe_to_incoming_protocol_messages
+        connection.__incoming_protocol_msgbus__.subscribe(:message) do |*args|
+          dispatch_protocol_message *args
+        end
+      end
+    end
+  end
+end