ably-rest 0.7.1 → 0.7.3

data/lib/submodules/ably-ruby/lib/ably/realtime/channel/channel_manager.rb

@@ -0,0 +1,92 @@
+module Ably::Realtime
+  class Channel
+    # ChannelManager is responsible for all actions relating to channel state: attaching, detaching or failure
+    # Channel state changes are performed by this class and executed from {ChannelStateMachine}
+    #
+    # 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 ChannelManager
+      extend Forwardable
+
+      def initialize(channel, connection)
+        @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
+      end
+
+      # Commence attachment
+      def attach
+        if can_transition_to?(:attached)
+          connect_if_connection_initialized
+          send_attach_protocol_message
+        end
+      end
+
+      # Commence attachment
+      def detach(error = nil)
+        if connection.closed? || connection.connecting?
+          channel.transition_state_machine :detached, error
+        elsif can_transition_to?(:detached)
+          send_detach_protocol_message
+        end
+      end
+
+      # Commence presence SYNC if applicable
+      def sync(attached_protocol_message)
+        if attached_protocol_message.has_presence_flag?
+          channel.presence.sync_started
+        else
+          channel.presence.sync_completed
+        end
+      end
+
+      # An error has occurred on the channel
+      def emit_error(error)
+        logger.error "ChannelManager: Channel '#{channel.name}' error: #{error}"
+        channel.trigger :error, error
+      end
+
+      # Detach a channel as a result of an error
+      def suspend(error)
+        channel.transition_state_machine! :detaching, error
+      end
+
+      private
+
+      attr_reader :channel, :connection
+      def_delegators :channel, :can_transition_to?
+
+      # If the connection has not previously connected, connect now
+      def connect_if_connection_initialized
+        connection.connect if connection.initialized?
+      end
+
+      def send_attach_protocol_message
+        send_state_change_protocol_message Ably::Models::ProtocolMessage::ACTION.Attach
+      end
+
+      def send_detach_protocol_message
+        send_state_change_protocol_message Ably::Models::ProtocolMessage::ACTION.Detach
+      end
+
+      def send_state_change_protocol_message(state)
+        connection.send_protocol_message(
+          action:  state.to_i,
+          channel: channel.name
+        )
+      end
+
+      def logger
+        connection.logger
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/realtime/channel/channel_state_machine.rb

@@ -0,0 +1,69 @@
+require 'ably/modules/state_machine'
+
+module Ably::Realtime
+  class Channel
+    # Internal class to manage channel state for {Ably::Realtime::Channel}
+    #
+    # @api private
+    #
+    class ChannelStateMachine
+      include Ably::Modules::StateMachine
+
+      # States supported by this StateMachine match #{Channel::STATE}s
+      #   :initialized
+      #   :attaching
+      #   :attached
+      #   :detaching
+      #   :detached
+      #   :failed
+      Channel::STATE.each_with_index do |state_enum, index|
+        state state_enum.to_sym, initial: index == 0
+      end
+
+      transition :from => :initialized,  :to => [:attaching]
+      transition :from => :attaching,    :to => [:attached, :detaching, :failed]
+      transition :from => :attached,     :to => [:detaching, :failed]
+      transition :from => :detaching,    :to => [:detached, :attaching, :failed]
+      transition :from => :failed,       :to => [:attaching]
+
+      after_transition do |channel, transition|
+        channel.synchronize_state_with_statemachine
+      end
+
+      after_transition(to: [:attaching]) do |channel|
+        channel.manager.attach
+      end
+
+      before_transition(to: [:attached]) do |channel, current_transition|
+        channel.manager.sync current_transition.metadata
+      end
+
+      after_transition(to: [:detaching]) do |channel, current_transition|
+        channel.manager.detach current_transition.metadata
+      end
+
+      after_transition(to: [:detached]) do |channel, current_transition|
+        channel.manager.emit_error current_transition.metadata if current_transition.metadata
+      end
+
+      after_transition(to: [:failed]) do |channel, current_transition|
+        channel.manager.emit_error 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
+      end
+
+      private
+      def channel
+        object
+      end
+
+      def logger
+        channel.logger
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/realtime/channels.rb

@@ -0,0 +1,50 @@
+module Ably
+  module Realtime
+    # Class that maintains a map of Channels ensuring Channels are reused
+    class Channels
+      include Ably::Modules::ChannelsCollection
+
+      # @return [Ably::Realtime::Channels]
+      def initialize(client)
+        super client, Ably::Realtime::Channel
+      end
+
+      # @!method get(name, channel_options = {})
+      # Return a {Ably::Realtime::Channel} for the given name
+      #
+      # @param name [String] The name of the channel
+      # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+      # @return [Ably::Realtime::Channel}
+      #
+      def get(*args)
+        super
+      end
+
+      # @!method fetch(name, &missing_block)
+      # Return a {Ably::Realtime::Channel} for the given name if it exists, else the block will be called.
+      # This method is intentionally similar to {http://ruby-doc.org/core-2.1.3/Hash.html#method-i-fetch Hash#fetch} providing a simple way to check if a channel exists or not without creating one
+      #
+      # @param name [String] The name of the channel
+      # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called
+      # @yieldparam [String] name of the missing channel
+      # @return [Ably::Realtime::Channel]
+      #
+      def fetch(*args)
+        super
+      end
+
+      # Detaches the {Ably::Realtime::Channel Realtime Channel} and releases all associated resources.
+      #
+      # Releasing a Realtime Channel is not typically necessary as a channel, once detached, consumes no resources other than
+      # the memory footprint of the {Ably::Realtime::Channel Realtime Channel object}. Release channels to free up resources if required
+      #
+      # @return [void]
+      #
+      def release(channel)
+        get(channel).detach do
+          @channels.delete(channel)
+        end if @channels.has_key?(channel)
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/realtime/client.rb

@@ -0,0 +1,184 @@
+module Ably
+  module Realtime
+    # Client for the Ably Realtime API
+    #
+    # @!attribute [r] client_id
+    #   (see Ably::Rest::Client#client_id)
+    # @!attribute [r] auth_options
+    #   (see Ably::Rest::Client#auth_options)
+    # @!attribute [r] environment
+    #   (see Ably::Rest::Client#environment)
+    # @!attribute [r] channels
+    #   @return [Aby::Realtime::Channels] The collection of {Ably::Realtime::Channel}s that have been created
+    # @!attribute [r] encoders
+    #   (see Ably::Rest::Client#encoders)
+    # @!attribute [r] protocol
+    #   (see Ably::Rest::Client#protocol)
+    # @!attribute [r] protocol_binary?
+    #   (see Ably::Rest::Client#protocol_binary?)
+    #
+    class Client
+      include Ably::Modules::AsyncWrapper
+      extend Forwardable
+
+      DOMAIN = 'realtime.ably.io'
+
+      # The collection of {Ably::Realtime::Channel}s that have been created
+      # @return [Aby::Realtime::Channels]
+      attr_reader :channels
+
+      # (see Ably::Rest::Client#auth)
+      attr_reader :auth
+
+      # The {Ably::Rest::Client REST client} instantiated with the same credentials and configuration that is used for all REST operations such as authentication
+      # @return [Ably::Rest::Client]
+      attr_reader :rest_client
+
+      # When false the client suppresses messages originating from this connection being echoed back on the same connection.  Defaults to true
+      # @return [Boolean]
+      attr_reader :echo_messages
+
+      # The custom realtime websocket host that is being used if it was provided with the option `:ws_host` when the {Client} was created
+      # @return [String,Nil]
+      attr_reader :custom_realtime_host
+
+      # When true, as soon as the client library is instantiated it will connect to Ably.  If this attribute is false, a connection must be opened explicitly
+      # @return [Boolean]
+      attr_reader :connect_automatically
+
+      # When a recover option is specified a connection inherits the state of a previous connection that may have existed under a different instance of the Realtime library, please refer to the API documentation for further information on connection state recovery
+      # @return [String,Nil]
+      attr_reader :recover
+
+      def_delegators :auth, :client_id, :auth_options
+      def_delegators :@rest_client, :encoders
+      def_delegators :@rest_client, :environment, :use_tls?, :protocol, :protocol_binary?, :custom_host
+      def_delegators :@rest_client, :log_level
+
+      # Creates a {Ably::Realtime::Client Realtime Client} and configures the {Ably::Auth} object for the connection.
+      #
+      # @param (see Ably::Rest::Client#initialize)
+      # @option options (see Ably::Rest::Client#initialize)
+      # @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        When a recover option is specified a connection inherits the state of a previous connection that may have existed under a different instance of the Realtime library, please refer to the API documentation for further information on connection state recovery
+      # @option options [Boolean] :connect_automatically  By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect.
+      #
+      # @yield (see Ably::Rest::Client#initialize)
+      # @yieldparam (see Ably::Rest::Client#initialize)
+      # @yieldreturn (see Ably::Rest::Client#initialize)
+      #
+      # @return [Ably::Realtime::Client]
+      #
+      # @example
+      #    # create a new client authenticating with basic auth
+      #    client = Ably::Realtime::Client.new('key.id:secret')
+      #
+      #    # create a new client and configure a client ID used for presence
+      #    client = Ably::Realtime::Client.new(api_key: 'key.id:secret', client_id: 'john')
+      #
+      def initialize(options, &token_request_block)
+        @rest_client           = Ably::Rest::Client.new(options, &token_request_block)
+        @auth                  = @rest_client.auth
+        @channels              = Ably::Realtime::Channels.new(self)
+        @echo_messages         = @rest_client.options.fetch(:echo_messages, true) == false ? false : true
+        @custom_realtime_host  = @rest_client.options[:realtime_host] || @rest_client.options[:ws_host]
+        @connect_automatically = @rest_client.options.fetch(:connect_automatically, true) == false ? false : true
+        @recover               = @rest_client.options[:recover]
+
+        raise ArgumentError, "Recovery key is invalid" if @recover && !@recover.match(Connection::RECOVER_REGEX)
+      end
+
+      # Return a {Ably::Realtime::Channel Realtime Channel} for the given name
+      #
+      # @param (see Ably::Realtime::Channels#get)
+      # @return (see Ably::Realtime::Channels#get)
+      #
+      def channel(name, channel_options = {})
+        channels.get(name, channel_options)
+      end
+
+      # Retrieve the Ably service time
+      #
+      # @yield [Time] The time as reported by the Ably service
+      # @return [EventMachine::Deferrable]
+      #
+      def time(&success_callback)
+        async_wrap(success_callback) do
+          rest_client.time
+        end
+      end
+
+      # Retrieve the stats for the application
+      #
+      # @param (see Ably::Rest::Client#stats)
+      # @option options (see Ably::Rest::Client#stats)
+      #
+      # @yield [Ably::Models::PaginatedResource<Ably::Models::Stat>] An Array of Stats
+      #
+      # @return [EventMachine::Deferrable]
+      #
+      def stats(options = {}, &success_callback)
+        async_wrap(success_callback) do
+          rest_client.stats(options)
+        end
+      end
+
+      # (see Ably::Realtime::Connection#close)
+      def close(&block)
+        connection.close(&block)
+      end
+
+      # @!attribute [r] endpoint
+      # @return [URI::Generic] Default Ably Realtime endpoint used for all requests
+      def endpoint
+        endpoint_for_host(custom_realtime_host || [environment, DOMAIN].compact.join('-'))
+      end
+
+      # @!attribute [r] connection
+      # @return [Aby::Realtime::Connection] The underlying connection for this client
+      def connection
+        @connection ||= Connection.new(self)
+      end
+
+      # (see Ably::Rest::Client#register_encoder)
+      def register_encoder(encoder)
+        rest_client.register_encoder encoder
+      end
+
+      # (see Ably::Rest::Client#logger)
+      def logger
+        @logger ||= Ably::Logger.new(self, log_level, rest_client.logger.custom_logger)
+      end
+
+      # Disable connection recovery, typically used after a connection has been recovered
+      # @return [void]
+      # @api private
+      def disable_automatic_connection_recovery
+        @recover = nil
+      end
+
+      # @!attribute [r] fallback_endpoint
+      # @return [URI::Generic] Fallback endpoint used to connect to the realtime Ably service. Note, after each connection attempt, a new random {Ably::FALLBACK_HOSTS fallback host} is used
+      # @api private
+      def fallback_endpoint
+        unless @fallback_endpoints
+          @fallback_endpoints = Ably::FALLBACK_HOSTS.shuffle.map { |fallback_host| endpoint_for_host(fallback_host) }
+        end
+
+        fallback_endpoint_index = connection.manager.retry_count_for_state(:disconnected) + connection.manager.retry_count_for_state(:suspended)
+
+        @fallback_endpoints[fallback_endpoint_index % @fallback_endpoints.count]
+      end
+
+      private
+      def endpoint_for_host(host)
+        URI::Generic.build(
+          scheme: use_tls? ? 'wss' : 'ws',
+          host:   host
+        )
+      end
+    end
+  end
+end
+

data/lib/submodules/ably-ruby/lib/ably/realtime/client/incoming_message_dispatcher.rb

@@ -0,0 +1,184 @@
+module Ably::Realtime
+  class Client
+    # IncomingMessageDispatcher is a (private) class that is used to dispatch {Ably::Models::ProtocolMessage} that are
+    # received from Ably via the {Ably::Realtime::Connection}
+    class IncomingMessageDispatcher
+      ACTION = Ably::Models::ProtocolMessage::ACTION
+
+      def initialize(client, connection)
+        @client     = client
+        @connection = connection
+
+        subscribe_to_incoming_protocol_messages
+      end
+
+      private
+      attr_reader :client, :connection
+
+      def channels
+        client.channels
+      end
+
+      def get_channel(channel_name)
+        channels.fetch(channel_name) do
+          logger.warn "Received channel message for non-existent channel"
+          Ably::Realtime::Models::NilChannel.new
+        end
+      end
+
+      def logger
+        client.logger
+      end
+
+      def dispatch_protocol_message(*args)
+        protocol_message = args.first
+
+        unless protocol_message.kind_of?(Ably::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
+
+        update_connection_recovery_info protocol_message
+
+        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
+          when ACTION.Connected
+            connection.transition_state_machine :connected, protocol_message.error
+
+          when ACTION.Disconnect, ACTION.Disconnected
+            connection.transition_state_machine :disconnected, protocol_message.error
+
+          when ACTION.Close
+          when ACTION.Closed
+            connection.transition_state_machine :closed
+
+          when ACTION.Error
+            if protocol_message.channel && !protocol_message.has_message_serial?
+              dispatch_channel_error protocol_message
+            else
+              process_connection_error protocol_message
+            end
+
+          when ACTION.Attach
+          when ACTION.Attached
+            get_channel(protocol_message.channel).transition_state_machine :attached, protocol_message
+
+          when ACTION.Detach
+          when ACTION.Detached
+            get_channel(protocol_message.channel).transition_state_machine :detached
+
+          when ACTION.Sync
+            presence = get_channel(protocol_message.channel).presence
+            protocol_message.presence.each do |presence_message|
+              presence.__incoming_msgbus__.publish :sync, presence_message
+            end
+            presence.update_sync_serial protocol_message.channel_serial
+
+          when ACTION.Presence
+            presence = get_channel(protocol_message.channel).presence
+            protocol_message.presence.each do |presence_message|
+              presence.__incoming_msgbus__.publish :presence, presence_message
+            end
+
+          when ACTION.Message
+            channel = get_channel(protocol_message.channel)
+            protocol_message.messages.each do |message|
+              channel.__incoming_msgbus__.publish :message, message
+            end
+
+          else
+            raise ArgumentError, "Protocol Message Action #{protocol_message.action} is unsupported by this MessageDispatcher"
+        end
+      end
+
+      def dispatch_channel_error(protocol_message)
+        logger.warn "Channel Error message received: #{protocol_message.error}"
+        if !protocol_message.has_message_serial?
+          get_channel(protocol_message.channel).transition_state_machine :failed, protocol_message.error
+        else
+          logger.fatal "Cannot process ProtocolMessage as not yet implemented: #{protocol_message}"
+        end
+      end
+
+      def process_connection_error(protocol_message)
+        connection.manager.error_received_from_server protocol_message.error
+      end
+
+      def update_connection_recovery_info(protocol_message)
+        if protocol_message.connection_key && (protocol_message.connection_key != connection.key)
+          logger.debug "New connection ID set to #{protocol_message.connection_id} with connection key #{protocol_message.connection_key}"
+          detach_attached_channels protocol_message.error if protocol_message.error
+          connection.configure_new protocol_message.connection_id, protocol_message.connection_key, protocol_message.connection_serial
+        end
+
+        if protocol_message.has_connection_serial?
+          connection.update_connection_serial protocol_message.connection_serial
+        end
+      end
+
+      def detach_attached_channels(error)
+        channels.select do |channel|
+          channel.attached? || channel.attaching?
+        end.each do |channel|
+          logger.warn "Detaching channel '#{channel.name}': #{error}"
+          channel.manager.suspend error
+        end
+      end
+
+      def ack_pending_queue_for_message_serial(ack_protocol_message)
+        drop_pending_queue_from_ack(ack_protocol_message) do |protocol_message|
+          ack_messages protocol_message.messages
+          ack_messages protocol_message.presence
+        end
+      end
+
+      def nack_pending_queue_for_message_serial(nack_protocol_message)
+        drop_pending_queue_from_ack(nack_protocol_message) do |protocol_message|
+          nack_messages protocol_message.messages, nack_protocol_message
+          nack_messages protocol_message.presence, nack_protocol_message
+        end
+      end
+
+      def ack_messages(messages)
+        messages.each do |message|
+          logger.debug "Calling ACK success callbacks for #{message.class.name} - #{message.to_json}"
+          message.succeed message
+        end
+      end
+
+      def nack_messages(messages, protocol_message)
+        messages.each do |message|
+          logger.debug "Calling NACK failure callbacks for #{message.class.name} - #{message.to_json}, protocol message: #{protocol_message}"
+          message.fail message, protocol_message.error
+        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(:protocol_message) do |*args|
+          dispatch_protocol_message *args
+        end
+      end
+    end
+  end
+end