ably-pubsub-core 0.0.1.pre

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

@@ -0,0 +1,225 @@
+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
+      def client
+        @client
+      end
+
+      def connection
+        @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" }
+          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
+
+        # RTL15b
+        if protocol_message.has_channel_serial? &&
+          (
+            protocol_message.action == :message ||
+              protocol_message.action == :presence ||
+              protocol_message.action == :attached
+          )
+          get_channel(protocol_message.channel).tap do |channel|
+            logger.info "Setting channel serial for channel #{channel.name}, " <<
+                          "Previous: #{channel.properties.channel_serial}, New: #{protocol_message.channel_serial}"
+            channel.properties.channel_serial = protocol_message.channel_serial
+          end
+        end
+
+        unless protocol_message.action.match_any?(:nack, :error)
+          logger.debug { "#{protocol_message.action} received: #{protocol_message}" }
+        end
+
+        connection.set_connection_confirmed_alive
+
+        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
+            if connection.closing?
+              logger.debug { "Out-of-order incoming CONNECTED ProtocolMessage discarded as connection has moved on and is in state: #{connection.state}" }
+            elsif connection.disconnected? || connection.closing? || connection.closed? || connection.failed?
+              logger.warn { "Out-of-order incoming CONNECTED ProtocolMessage discarded as connection has moved on and is in state: #{connection.state}" }
+            elsif connection.connected?
+              logger.debug { "Updated CONNECTED ProtocolMessage received (whilst connected)" }
+              process_connected_update_message protocol_message
+              connection.set_connection_confirmed_alive # Connection protocol messages can change liveness settings such as max_idle_interval
+            else
+              process_connected_message protocol_message
+              connection.set_connection_confirmed_alive # Connection protocol messages can change liveness settings such as max_idle_interval
+            end
+
+          when ACTION.Disconnect, ACTION.Disconnected
+            connection.transition_state_machine :disconnected, reason: protocol_message.error unless connection.disconnected?
+
+          when ACTION.Close
+          when ACTION.Closed
+            connection.transition_state_machine :closed unless connection.closed?
+
+          when ACTION.Error
+            if protocol_message.channel
+              dispatch_channel_error protocol_message
+            else
+              process_connection_error protocol_message
+            end
+
+          when ACTION.Attach
+          when ACTION.Attached
+            get_channel(protocol_message.channel).tap do |channel|
+              if channel.attached?
+                channel.manager.duplicate_attached_received protocol_message
+              else
+                if channel.failed?
+                  logger.warn "Ably::Realtime::Client::IncomingMessageDispatcher - Received an ATTACHED protocol message for FAILED channel #{channel.name}. Ignoring ATTACHED message"
+                else
+                  channel.transition_state_machine :attached, reason: protocol_message.error, resumed: protocol_message.has_channel_resumed_flag?, protocol_message: protocol_message
+                end
+              end
+            end
+
+          when ACTION.Detach
+          when ACTION.Detached
+            get_channel(protocol_message.channel).tap do |channel|
+              channel.manager.detached_received protocol_message.error
+            end
+
+          when ACTION.Sync
+            presence = get_channel(protocol_message.channel).presence
+            presence.manager.sync_process_messages protocol_message.channel_serial, protocol_message.presence
+
+          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
+
+          when ACTION.Auth
+            client.auth.authorize
+
+          else
+            error = Ably::Exceptions::ProtocolError.new("Protocol Message Action #{protocol_message.action} is unsupported by this MessageDispatcher", 400, Ably::Exceptions::Codes::PROTOCOL_ERROR)
+            logger.fatal error.message
+        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, reason: protocol_message.error
+        else
+          logger.fatal { "Cannot process ProtocolMessage ERROR with message serial as not yet implemented: #{protocol_message}" }
+        end
+      end
+
+      def process_connection_error(protocol_message)
+        connection.manager.error_received_from_server(protocol_message.error || Ably::Models::ErrorInfo.new(message: 'Error reason unknown'))
+      end
+
+      def process_connected_message(protocol_message)
+        if client.auth.token_client_id_allowed?(protocol_message.connection_details.client_id)
+          connection.transition_state_machine :connected, reason: protocol_message.error, protocol_message: protocol_message
+        else
+          reason = Ably::Exceptions::IncompatibleClientId.new("Client ID '#{protocol_message.connection_details.client_id}' specified by the server is incompatible with the library's configured client ID '#{client.client_id}'")
+          connection.transition_state_machine :failed, reason: reason, protocol_message: protocol_message
+        end
+      end
+
+      def process_connected_update_message(protocol_message)
+        if client.auth.token_client_id_allowed?(protocol_message.connection_details.client_id)
+          connection.manager.connected_update protocol_message
+        else
+          reason = Ably::Exceptions::IncompatibleClientId.new("Client ID '#{protocol_message.connection_details.client_id}' in CONNECTED update specified by the server is incompatible with the library's configured client ID '#{client.client_id}'")
+          connection.transition_state_machine :failed, reason: reason, protocol_message: protocol_message
+        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 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
+
+        while !connection.__pending_message_ack_queue__.empty?
+          next_message = connection.__pending_message_ack_queue__.first
+          return if next_message.message_serial > message_serial_up_to
+          yield connection.__pending_message_ack_queue__.shift
+        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

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

@@ -0,0 +1,87 @@
+module Ably::Realtime
+  class Client
+    # OutgoingMessageDispatcher is a (private) class that is used to deliver
+    # outgoing {Ably::Models::ProtocolMessage}s using the {Ably::Realtime::Connection}
+    # when the connection state is capable of delivering messages
+    class OutgoingMessageDispatcher
+      include Ably::Modules::EventMachineHelpers
+
+      ACTION = Ably::Models::ProtocolMessage::ACTION
+
+      def initialize(client, connection)
+        @client     = client
+        @connection = connection
+
+        subscribe_to_outgoing_protocol_message_queue
+        setup_event_handlers
+      end
+
+      private
+      def client
+        @client
+      end
+
+      def connection
+        @connection
+      end
+
+      def can_send_messages?
+        connection.connected? || connection.closing?
+      end
+
+      def messages_in_outgoing_queue?
+        !outgoing_queue.empty?
+      end
+
+      def outgoing_queue
+        connection.__outgoing_message_queue__
+      end
+
+      def pending_ack_queue
+        connection.__pending_message_ack_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
+
+          if (!connection.transport)
+            protocol_message.fail Ably::Exceptions::TransportClosed.new('Transport disconnected unexpectedly', nil, Ably::Exceptions::Codes::DISCONNECTED)
+            next
+          end
+
+          current_transport_outgoing_message_bus.publish :protocol_message, protocol_message
+
+          if protocol_message.ack_required?
+            pending_ack_queue << protocol_message
+          else
+            protocol_message.succeed protocol_message
+          end
+        end
+      end
+
+      def subscribe_to_outgoing_protocol_message_queue
+        connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |*args|
+          deliver_queued_protocol_messages
+        end
+      end
+
+      def setup_event_handlers
+        connection.unsafe_on(:connected) do
+          # Give connection manager enough time to prevent message delivery if necessary
+          # For example, if reconnecting and connection and channel state is lost,
+          # then the queued messages must be NACK'd
+          EventMachine.next_tick do
+            deliver_queued_protocol_messages
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ably/realtime/client.rb

@@ -0,0 +1,363 @@
+require 'uri'
+require 'ably/realtime/channel/publisher'
+require 'ably/realtime/recovery_key_context'
+
+module Ably
+  module Realtime
+    # A client that extends the functionality of the {Ably::Realtime::Client} and provides additional realtime-specific features.
+    #
+    class Client
+      include Ably::Modules::AsyncWrapper
+      include Ably::Realtime::Channel::Publisher
+      include Ably::Modules::Conversions
+
+      extend Forwardable
+      using Ably::Util::AblyExtensions
+
+      DOMAIN = 'realtime.ably.io'
+
+      # A {Aby::Realtime::Channels} object.
+      #
+      # @spec RTC3, RTS1
+      #
+      # @return [Aby::Realtime::Channels]
+      #
+      attr_reader :channels
+
+      # An {Ably::Auth} object.
+      #
+      # @spec RTC4
+      #
+      # @return [Ably::Auth]
+      #
+      attr_reader :auth
+
+      # A {Aby::Realtime::Connection} object.
+      #
+      # @spec RTC2
+      #
+      # @return [Aby::Realtime::Connection]
+      #
+      attr_reader :connection
+
+      # 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]
+
+      # @private
+      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
+
+      # If false, this disables the default behaviour whereby the library queues messages on a connection in the disconnected or connecting states. Defaults to true
+      # @return [Boolean]
+      attr_reader :queue_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 :auto_connect
+
+      # 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
+
+      # Additional parameters to be sent in the querystring when initiating a realtime connection
+      # @return [Hash]
+      attr_reader :transport_params
+
+      def_delegators :auth, :client_id, :auth_options
+      def_delegators :@rest_client, :encoders
+      def_delegators :@rest_client, :use_tls?, :protocol, :protocol_binary?
+      def_delegators :@rest_client, :environment, :custom_host, :custom_port, :custom_tls_port
+      def_delegators :@rest_client, :log_level
+      def_delegators :@rest_client, :options
+
+      # Creates a {Ably::Realtime::Client Realtime Client} and configures the {Ably::Auth} object for the connection.
+      #
+      # @spec RSC1
+      #
+      # @param (see {Ably::Rest::Client#initialize})
+      # @option options (see Ably::Rest::Client#initialize) An options {Hash} object.
+      # @option options [Proc]                    :auth_callback       when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required.
+      #                                                                Whilst the proc is called synchronously, it does not block the EventMachine reactor as it is run in a separate thread.
+      #                                                                The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent
+      # @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] :auto_connect   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.
+      # @option options [Hash]    :transport_params   Additional parameters to be sent in the querystring when initiating a realtime connection. Keys are Strings, values are Stringifiable(a value must respond to #to_s)
+      #
+      # @option options [Integer] :channel_retry_timeout       (15 seconds). When a channel becomes SUSPENDED, after this delay in seconds, the channel will automatically attempt to reattach if the connection is CONNECTED
+      # @option options [Integer] :disconnected_retry_timeout  (15 seconds). When the connection enters the DISCONNECTED state, after this delay in seconds, if the state is still DISCONNECTED, the client library will attempt to reconnect automatically
+      # @option options [Integer] :suspended_retry_timeout     (30 seconds). When the connection enters the SUSPENDED state, after this delay in seconds, if the state is still SUSPENDED, the client library will attempt to reconnect automatically
+      # @option options [Boolean] :disable_websocket_heartbeats   WebSocket heartbeats are more efficient than protocol level heartbeats, however they can be disabled for development purposes
+      #
+      # @return [Ably::Realtime::Client]
+      #
+      # @example
+      #    # Constructs a {Ably::Realtime::Client} object using an Ably API key or token string.
+      #    client = Ably::Realtime::Client.new('key.id:secret')
+      #
+      #    # Constructs a {Ably::Realtime::Client} object using an Ably options object.
+      #    client = Ably::Realtime::Client.new(key: 'key.id:secret', client_id: 'john')
+      #
+      def initialize(options)
+        raise ArgumentError, 'Options Hash is expected' if options.nil?
+
+        options = options.clone
+        if options.kind_of?(String)
+          options = if options.match(Ably::Auth::API_KEY_REGEX)
+            { key: options }
+          else
+            { token: options }
+          end
+        end
+
+        @transport_params      = options.delete(:transport_params).to_h.each_with_object({}) do |(key, value), acc|
+          acc[key.to_s] = value.to_s
+        end
+        @rest_client           = Ably::Rest::Client.new(options.merge(realtime_client: self))
+        @echo_messages         = rest_client.options.fetch_with_default(:echo_messages, true)
+        @queue_messages        = rest_client.options.fetch_with_default(:queue_messages, true)
+        @custom_realtime_host  = rest_client.options[:realtime_host] || rest_client.options[:ws_host]
+        @auto_connect          = rest_client.options.fetch_with_default(:auto_connect, true)
+        @recover               = rest_client.options.fetch_with_default(:recover, '')
+
+        @auth       = Ably::Realtime::Auth.new(self)
+        @channels   = Ably::Realtime::Channels.new(self)
+        @connection = Ably::Realtime::Connection.new(self, options)
+
+        unless @recover.nil_or_empty?
+          recovery_context = RecoveryKeyContext.from_json(@recover, logger)
+          unless recovery_context.nil?
+            @channels.set_channel_serials recovery_context.channel_serials # RTN16j
+            @connection.set_msg_serial_from_recover = recovery_context.msg_serial  # RTN16f
+          end
+        end
+      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
+
+      # Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access
+      # to a sufficiently well maintained time source and wish to issue Ably {Ably::Models::TokenRequests} with
+      # a more accurate timestamp should use the queryTime property instead of this method.
+      #
+      # @spec RTC6a
+      #
+      # @yield [Time] The time as milliseconds since the Unix epoch.
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def time(&success_callback)
+        async_wrap(success_callback) do
+          rest_client.time
+        end
+      end
+
+      # Queries the REST /stats API and retrieves your application's usage statistics.
+      # Returns a {Ably::Util::SafeDeferrable} object, containing an array of {Ably::Models::Stats} objects. See the Stats docs.
+      #
+      # @spec RTC5
+      #
+      # @param (see Ably::Rest::Client#stats)
+      # @option options (see Ably::Rest::Client#stats)
+      #
+      # @yield [Ably::Models::PaginatedResult<Ably::Models::Stats>] A {Ably::Util::SafeDeferrable} object containing an array of {Ably::Models::Stats} objects.
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def stats(options = {}, &success_callback)
+        async_wrap(success_callback) do
+          rest_client.stats(options)
+        end
+      end
+
+      # Calls {Connection#close} and causes the connection to close, entering the closing state.
+      # Once closed, the library will not attempt to re-establish the connection without an explicit call to {Connection#connect}.
+      # @spec RTN12
+      # (see Ably::Realtime::Connection#close)
+      def close(&block)
+        connection.close(&block)
+      end
+
+      # Calls {Ably::Realtime::Connection#connect} and causes the connection to open, entering the connecting
+      # state. Explicitly calling connect() is unnecessary unless the autoConnect property is disabled.
+      # @spec RTN11
+      # (see Ably::Realtime::Connection#connect)
+      def connect(&block)
+        connection.connect(&block)
+      end
+
+      # A {Ably::Realtime::Push} object.
+      # @return [Ably::Realtime::Push]
+      def push
+        @push ||= Push.new(self)
+      end
+
+      # Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST
+      # API functionality that is either not documented or is not yet included in the public API, without having to
+      # directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support.
+      #
+      # @spec RTC9
+      #
+      # (see {Ably::Rest::Client#request})
+      # @yield [Ably::Models::HttpPaginatedResponse<>] An Array of Stats
+      #
+      # @return [Ably::Util::SafeDeferrable] An {Ably::Util::SafeDeferrable} response object returned by the HTTP request, containing an empty or JSON-encodable object.
+      def request(method, path, params = {}, body = nil, headers = {}, &callback)
+        async_wrap(callback) do
+          rest_client.request(method, path, params, body, headers, async_blocking_operations: true)
+        end
+      end
+
+      # Publish one or more messages to the specified channel.
+      #
+      # This method allows messages to be efficiently published to Ably without instancing a {Ably::Realtime::Channel} object.
+      # If you want to publish a high rate of messages to Ably without instancing channels or using the REST API, then this method
+      # is recommended. However, channel options such as encryption are not supported with this method.  If you need to specify channel options
+      # we recommend you use the {Ably::Realtime::Channel} +publish+ method without attaching to each channel, unless you also want to subscribe
+      # to published messages on that channel.
+      #
+      # Note: This feature is still in beta. As such, we cannot guarantee the API will not change in future.
+      #
+      # @param channel [String]   The channel name you want to publish the message(s) to
+      # @param name [String, Array<Ably::Models::Message|Hash>, nil]   The event name of the message to publish, or an Array of [Ably::Model::Message] objects or [Hash] objects with +:name+ and +:data+ pairs
+      # @param data [String, ByteArray, nil]   The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument
+      # @param attributes [Hash, nil]   Optional additional message attributes such as :client_id or :connection_id, applied when name attribute is nil or a string
+      #
+      # @yield [Ably::Models::Message,Array<Ably::Models::Message>] On success, will call the block with the {Ably::Models::Message} if a single message is published, or an Array of {Ably::Models::Message} when multiple messages are published
+      # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks
+      #
+      # @example
+      #   # Publish a single message
+      #   client.publish 'activityChannel', click', { x: 1, y: 2 }
+      #
+      #   # Publish an array of message Hashes
+      #   messages = [
+      #     { name: 'click', { x: 1, y: 2 } },
+      #     { name: 'click', { x: 2, y: 3 } }
+      #   ]
+      #   client.publish 'activityChannel', messages
+      #
+      #   # Publish an array of Ably::Models::Message objects
+      #   messages = [
+      #     Ably::Models::Message(name: 'click', { x: 1, y: 2 })
+      #     Ably::Models::Message(name: 'click', { x: 2, y: 3 })
+      #   ]
+      #   client.publish 'activityChannel', messages
+      #
+      #   client.publish('activityChannel', 'click', 'body') do |message|
+      #     puts "#{message.name} event received with #{message.data}"
+      #   end
+      #
+      #   client.publish('activityChannel', 'click', 'body').errback do |error, message|
+      #     puts "#{message.name} was not received, error #{error.message}"
+      #   end
+      #
+      def publish(channel_name, name, data = nil, attributes = {}, &success_block)
+        if !connection.can_publish_messages?
+          error = Ably::Exceptions::MessageQueueingDisabled.new("Message cannot be published. Client is not allowed to queue messages when connection is in state #{connection.state}")
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
+        end
+
+        messages = if name.kind_of?(Enumerable)
+          name
+        else
+          name = ensure_utf_8(:name, name, allow_nil: true)
+          ensure_supported_payload data
+          [{ name: name, data: data }.merge(attributes)]
+        end
+
+        if messages.length > Realtime::Connection::MAX_PROTOCOL_MESSAGE_BATCH_SIZE
+          error = Ably::Exceptions::InvalidRequest.new("It is not possible to publish more than #{Realtime::Connection::MAX_PROTOCOL_MESSAGE_BATCH_SIZE} messages with a single publish request.")
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
+        end
+
+        enqueue_messages_on_connection(self, messages, channel_name).tap do |deferrable|
+          deferrable.callback(&success_block) if block_given?
+        end
+      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
+
+      # (see Ably::Rest::Client#register_encoder)
+      def register_encoder(encoder)
+        rest_client.register_encoder encoder
+      end
+
+      # (see Ably::Rest::Client#fallback_hosts)
+      def fallback_hosts
+        rest_client.fallback_hosts
+      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} or provided fallback hosts are used
+      # @api private
+      def fallback_endpoint
+        unless defined?(@fallback_endpoints) && @fallback_endpoints
+          @fallback_endpoints = fallback_hosts.shuffle.map { |fallback_host| endpoint_for_host(fallback_host) }
+          @fallback_endpoints << endpoint # Try the original host last if all fallbacks have been used
+        end
+
+        fallback_endpoint_index = connection.manager.retry_count_for_state(:disconnected) + connection.manager.retry_count_for_state(:suspended) - 1
+
+        @fallback_endpoints[fallback_endpoint_index % @fallback_endpoints.count]
+      end
+
+      # Retrieves a {Ably::Models::LocalDevice} object that represents the current state of the device as a target for push notifications.
+      # @spec RSH8
+      # @return [Ably::Models::LocalDevice] A {Ably::Models::LocalDevice} object.
+      #
+      # @note This is unsupported in the Ruby library
+      def device
+        raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. The local device object is not unavailable'
+      end
+
+      private
+      def endpoint_for_host(host)
+        port = if use_tls?
+          custom_tls_port
+        else
+          custom_port
+        end
+
+        raise ArgumentError, "Custom port must be an Integer or nil" if port && !port.kind_of?(Integer)
+
+        options = {
+          scheme: use_tls? ? 'wss' : 'ws',
+          host:   host
+        }
+        options.merge!(port: port) if port
+
+        URI::Generic.build(options)
+      end
+    end
+  end
+end