ably-pubsub-core 0.0.1.pre

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

@@ -0,0 +1,272 @@
+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
+      end
+
+      # Commence attachment
+      def attach
+        if can_transition_to?(:attached)
+          connect_if_connection_initialized
+          send_attach_protocol_message if connection.state?(:connected) # RTL4i
+        end
+      end
+
+      # Commence attachment
+      def detach(error, previous_state)
+        if connection.closed? || connection.connecting? || connection.suspended?
+          channel.transition_state_machine :detached, reason: error
+        elsif can_transition_to?(:detached)
+          send_detach_protocol_message previous_state
+        end
+      end
+
+      # Channel is attached, notify presence if sync is expected
+      def attached(attached_protocol_message)
+        # If no attached ProtocolMessage then this attached request was triggered by the client
+        # library, such as returning to attached when detach has failed
+        if attached_protocol_message
+          channel.presence.manager.on_attach attached_protocol_message.has_presence_flag?
+          channel.properties.set_attach_serial(attached_protocol_message.channel_serial)
+          channel.options.set_modes_from_flags(attached_protocol_message.flags)
+          channel.options.set_params(attached_protocol_message.params)
+        end
+      end
+
+      # An error has occurred on the channel
+      def log_channel_error(error)
+        logger.error { "ChannelManager: Channel '#{channel.name}' error: #{error}" }
+      end
+
+      # Request channel to be reattached by sending an attach protocol message
+      # @param [Ably::Models::ErrorInfo] reason
+      def request_reattach(reason = nil)
+        channel.set_channel_error_reason(reason) if reason
+        channel.transition_state_machine! :attaching, reason: reason unless channel.attaching?
+        send_attach_protocol_message
+        logger.debug { "Explicit channel reattach request sent to Ably due to #{reason}" }
+      end
+
+      def duplicate_attached_received(protocol_message)
+        logger.debug { "Server initiated ATTACHED message received for channel '#{channel.name}' with state #{channel.state}" }
+        if protocol_message.error
+          channel.set_channel_error_reason protocol_message.error
+          log_channel_error protocol_message.error
+        end
+
+        channel.properties.set_attach_serial(protocol_message.channel_serial)
+        channel.options.set_modes_from_flags(protocol_message.flags)
+
+        unless protocol_message.has_channel_resumed_flag?
+          channel.emit :update, Ably::Models::ChannelStateChange.new(
+            current: channel.state,
+            previous: channel.state,
+            event: Ably::Realtime::Channel::EVENT(:update),
+            reason: protocol_message.error,
+            resumed: false,
+          )
+          channel.presence.manager.on_attach protocol_message.has_presence_flag?
+        end
+      end
+
+      # Handle DETACED messages, see #RTL13 for server-initated detaches
+      def detached_received(reason)
+        case channel.state.to_sym
+        when :detaching
+          channel.transition_state_machine :detached, reason: reason
+        when :attached, :suspended
+          channel.transition_state_machine :attaching, reason: reason
+        else
+          logger.debug { "ChannelManager: DETACHED ProtocolMessage received, but no action to take as not DETACHING, ATTACHED OR SUSPENDED" }
+        end
+      end
+
+      # When continuity on the connection is interrupted or channel becomes suspended (implying loss of continuity)
+      # then all messages published but awaiting an ACK from Ably should be failed with a NACK
+      # @param [Hash] options
+      # @option options [Boolean]  :immediately
+      def fail_messages_awaiting_ack(error, options = {})
+        immediately = options[:immediately] || false
+
+        fail_proc = lambda do
+          error = Ably::Exceptions::MessageDeliveryFailed.new("Continuity of connection was lost so published messages awaiting ACK have failed") unless error
+          fail_messages_in_queue connection.__pending_message_ack_queue__, error
+        end
+
+        # Allow a short time for other queued operations to complete before failing all messages
+        if immediately
+          fail_proc.call
+        else
+          EventMachine.add_timer(0.1) { fail_proc.call }
+        end
+      end
+
+      # When a channel becomes suspended or failed,
+      # all queued messages should be failed immediately as we don't queue in
+      # any of those states
+      def fail_queued_messages(error)
+        error = Ably::Exceptions::MessageDeliveryFailed.new("Queued messages on channel '#{channel.name}' in state '#{channel.state}' will never be delivered") unless error
+        fail_messages_in_queue connection.__outgoing_message_queue__, error
+      end
+
+      def fail_messages_in_queue(queue, error)
+        queue.delete_if do |protocol_message|
+          if protocol_message.action.match_any?(:presence, :message)
+            if protocol_message.channel == channel.name
+              nack_messages protocol_message, error
+              true
+            end
+          end
+        end
+      end
+
+      def nack_messages(protocol_message, error)
+        (protocol_message.messages + protocol_message.presence).each do |message|
+          nack_message message, error, protocol_message
+        end
+        logger.debug { "Calling NACK failure callbacks for #{protocol_message.class.name} - #{protocol_message.to_json}" }
+        protocol_message.fail error
+      end
+
+      def nack_message(message, error, protocol_message = nil)
+        logger.debug { "Calling NACK failure callbacks for #{message.class.name} - #{message.to_json} #{"protocol message: #{protocol_message}" if protocol_message}" }
+        message.fail error
+      end
+
+      def drop_pending_queue_from_ack(ack_protocol_message)
+        message_serial_up_to = ack_protocol_message.message_serial + ack_protocol_message.count - 1
+        connection.__pending_message_ack_queue__.drop_while do |protocol_message|
+          if protocol_message.message_serial <= message_serial_up_to
+            yield protocol_message
+            true
+          end
+        end
+      end
+
+      # If the connection is still connected and the channel still suspended after
+      # channel_retry_timeout has passed, then attempt to reattach automatically, see #RTL13b
+      def start_attach_from_suspended_timer
+        cancel_attach_from_suspended_timer
+        if connection.connected?
+          channel.unsafe_once { |event| cancel_attach_from_suspended_timer unless event == :update }
+          connection.unsafe_once { |event| cancel_attach_from_suspended_timer unless event == :update }
+
+          @attach_from_suspended_timer = EventMachine::Timer.new(channel_retry_timeout) do
+            channel.transition_state_machine! :attaching
+          end
+        end
+      end
+
+      # RTL13c
+      def notify_state_change
+        @pending_state_change_timer.cancel if @pending_state_change_timer
+        @pending_state_change_timer = nil
+      end
+
+      private
+      attr_reader :pending_state_change_timer
+
+      def channel
+        @channel
+      end
+
+      def connection
+        @connection
+      end
+
+      def_delegators :channel, :can_transition_to?
+
+      def cancel_attach_from_suspended_timer
+        @attach_from_suspended_timer.cancel if @attach_from_suspended_timer
+        @attach_from_suspended_timer = nil
+      end
+
+      # If the connection has not previously connected, connect now
+      def connect_if_connection_initialized
+        connection.connect if connection.initialized?
+      end
+
+      def realtime_request_timeout
+        connection.defaults.fetch(:realtime_request_timeout)
+      end
+
+      def channel_retry_timeout
+        connection.defaults.fetch(:channel_retry_timeout)
+      end
+
+      def send_attach_protocol_message
+        message_options = {}
+        message_options[:params] = channel.options.params if channel.options.params.any?
+        message_options[:flags] = channel.options.modes_to_flags if channel.options.modes
+        if channel.attach_resume
+          message_options[:flags] = message_options[:flags].to_i | Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[:resume]
+        end
+
+        message_options[:channelSerial] = channel.properties.channel_serial # RTL4c1
+
+        state_at_time_of_request = channel.state
+        attach_action = Ably::Models::ProtocolMessage::ACTION.Attach
+        # RTL4f
+        @pending_state_change_timer = EventMachine::Timer.new(realtime_request_timeout) do
+          if channel.state == state_at_time_of_request
+            error = Ably::Models::ErrorInfo.new(code: Ably::Exceptions::Codes::CHANNEL_OPERATION_FAILED_NO_RESPONSE_FROM_SERVER, message: "Channel #{attach_action} operation failed (timed out)")
+            channel.transition_state_machine :suspended, reason: error # return to suspended state if failed
+          end
+        end
+        # Shouldn't queue attach message as per RTL4i, so message is added top of the queue
+        # to be sent immediately while processing next message
+        connection.send_protocol_message_immediately(
+          action:  attach_action.to_i,
+          channel: channel.name,
+          **message_options.to_h
+        )
+      end
+
+      def send_detach_protocol_message(previous_state)
+        state_at_time_of_request = channel.state
+        detach_action = Ably::Models::ProtocolMessage::ACTION.Detach
+
+        @pending_state_change_timer = EventMachine::Timer.new(realtime_request_timeout) do
+          if channel.state == state_at_time_of_request
+            error = Ably::Models::ErrorInfo.new(code: Ably::Exceptions::Codes::CHANNEL_OPERATION_FAILED_NO_RESPONSE_FROM_SERVER, message: "Channel #{detach_action} operation failed (timed out)")
+            channel.transition_state_machine previous_state, reason: error # return to previous state if failed
+          end
+        end
+
+        on_disconnected_and_connected = lambda do |&block|
+          connection.unsafe_once(:disconnected) do
+            connection.unsafe_once(:connected) do
+              block.call if pending_state_change_timer
+            end if pending_state_change_timer
+          end
+        end
+
+        send_detach_message = lambda do
+          on_disconnected_and_connected.call do
+            send_detach_message.call
+          end
+          connection.send_protocol_message(
+            action:  detach_action.to_i,
+            channel: channel.name
+          )
+        end
+
+        send_detach_message.call
+      end
+
+      def logger
+        connection.logger
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Ably::Realtime
+  class Channel
+    # Describes the properties of the channel state.
+    class ChannelProperties
+      # {Ably::Realtime::Channel} this object associated with
+      #
+      # @return [Ably::Realtime::Channel]
+      #
+      attr_reader :channel
+
+      # Starts unset when a channel is instantiated, then updated with the channelSerial from each
+      # {Ably::Realtime::Channel::STATE.Attached} event that matches the channel.
+      # Used as the value for {Ably::Realtime::Channel#history}.
+      #
+      # @spec CP2a
+      #
+      # @return [String]
+      #
+      attr_reader :attach_serial
+
+      # ChannelSerial contains the channelSerial from latest ProtocolMessage of action type
+      # Message/PresenceMessage received on the channel.
+      #
+      # @spec CP2b, RTL15b
+      #
+      # @return [String]
+      #
+      attr_accessor :channel_serial
+
+      def initialize(channel)
+        @channel = channel
+      end
+
+      # @api private
+      def set_attach_serial(attach_serial)
+        @attach_serial = attach_serial
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+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, :failed]
+      transition :from => :attaching,    :to => [:attached, :detaching, :failed, :suspended]
+      transition :from => :attached,     :to => [:attaching, :detaching, :detached, :failed, :suspended]
+      transition :from => :detaching,    :to => [:detached, :attaching, :attached, :failed, :suspended]
+      transition :from => :detached,     :to => [:attaching, :attached, :failed]
+      transition :from => :suspended,    :to => [:attaching, :attached, :detached, :failed]
+      transition :from => :failed,       :to => [:attaching, :initialized]
+
+      after_transition do |channel, transition|
+        channel.manager.notify_state_change # RTL13c
+        channel.synchronize_state_with_statemachine
+      end
+
+      after_transition(to: [:initialized]) do |channel|
+        channel.clear_error_reason
+      end
+
+      after_transition(to: [:attaching]) do |channel|
+        channel.manager.attach
+      end
+
+      before_transition(to: [:attached]) do |channel, current_transition|
+        channel.manager.attached current_transition.metadata.protocol_message
+        channel.attach_resume!
+      end
+
+      before_transition(to: [:detaching, :failed]) do |channel, _current_transition|
+        channel.reset_attach_resume!
+      end
+
+      after_transition(to: [:detaching]) do |channel, current_transition|
+        err = error_from_state_change(current_transition)
+        channel.manager.detach err, current_transition.metadata.previous
+      end
+
+      after_transition(to: [:detached, :failed, :suspended]) do |channel, current_transition|
+        channel.properties.channel_serial = nil # RTP5a1
+        err = error_from_state_change(current_transition)
+        channel.manager.fail_queued_messages(err) if channel.failed? or channel.suspended? #RTL11
+        channel.manager.log_channel_error err if err
+      end
+
+      after_transition(to: [:suspended]) do |channel, current_transition|
+        channel.manager.start_attach_from_suspended_timer
+      end
+
+      # Transitions responsible for updating channel#error_reason
+      before_transition(to: [:failed, :suspended]) do |channel, current_transition|
+        err = error_from_state_change(current_transition)
+        channel.set_channel_error_reason err if err
+      end
+
+      before_transition(to: [:attached, :detached]) do |channel, current_transition|
+        err = error_from_state_change(current_transition)
+        if err
+          channel.set_channel_error_reason err
+        else
+          # Attached & Detached are "healthy" final states so reset the error reason
+          channel.clear_error_reason
+        end
+      end
+
+      def self.error_from_state_change(current_transition)
+        # ChannelStateChange object is always passed in current_transition metadata object
+        connection_state_change = current_transition.metadata
+        # Reason attribute contains errors
+        err = connection_state_change && connection_state_change.reason
+        err if is_error_type?(err)
+      end
+
+      private
+      def channel
+        object
+      end
+
+      # Logged needs to be defined as it is used by {Ably::Modules::StateMachine}
+      def logger
+        channel.logger
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+module Ably::Realtime
+  class Channel
+    # Publisher module adds publishing capabilities to the current object
+    module Publisher
+      private
+
+      # Prepare and queue messages on the connection queue immediately
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def enqueue_messages_on_connection(client, raw_messages, channel_name, channel_options = {})
+        messages = Array(raw_messages).map do |raw_msg|
+          create_message(client, raw_msg, channel_options).tap do |message|
+            next if message.client_id.nil?
+            if message.client_id == '*'
+              raise Ably::Exceptions::IncompatibleClientId.new('Wildcard client_id is reserved and cannot be used when publishing messages')
+            end
+            if message.client_id && !message.client_id.kind_of?(String)
+              raise Ably::Exceptions::IncompatibleClientId.new('client_id must be a String when publishing messages')
+            end
+            unless client.auth.can_assume_client_id?(message.client_id)
+              raise Ably::Exceptions::IncompatibleClientId.new("Cannot publish with client_id '#{message.client_id}' as it is incompatible with the current configured client_id '#{client.client_id}'")
+            end
+          end
+        end
+
+        max_message_size = connection.details && connection.details.max_message_size || Ably::Models::ConnectionDetails::MAX_MESSAGE_SIZE
+        if messages.sum(&:size) > max_message_size
+          error = Ably::Exceptions::MaxMessageSizeExceeded.new("Message size exceeded #{max_message_size} bytes.")
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
+        end
+
+        connection.send_protocol_message(
+          action:   Ably::Models::ProtocolMessage::ACTION.Message.to_i,
+          channel:  channel_name,
+          messages: messages
+        )
+
+        if messages.count == 1
+          # A message is a Deferrable so, if publishing only one message, simply return that Deferrable
+          messages.first
+        else
+          deferrable_for_multiple_messages(messages)
+        end
+      end
+
+      # A deferrable object that calls the success callback once all messages are delivered
+      # If any message fails, the errback is called immediately
+      # Only one callback or errback is ever called i.e. if a group of messages all fail, only once
+      # errback will be invoked
+      def deferrable_for_multiple_messages(messages)
+        expected_deliveries = messages.count
+        actual_deliveries = 0
+        failed = false
+
+        Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
+          messages.each do |message|
+            message.callback do
+              next if failed
+              actual_deliveries += 1
+              deferrable.succeed messages if actual_deliveries == expected_deliveries
+            end
+            message.errback do |error|
+              next if failed
+              failed = true
+              deferrable.fail error, message
+            end
+          end
+        end
+      end
+
+      def create_message(client, message, channel_options)
+        Ably::Models::Message(message.dup).tap do |msg|
+          msg.encode(client.encoders, channel_options) do |encode_error, error_message|
+            client.logger.error error_message
+          end
+        end
+      end
+    end
+  end
+end
+

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

@@ -0,0 +1,69 @@
+module Ably::Realtime
+  class Channel
+    # Enables devices to subscribe to push notifications for a channel.
+    #
+    class PushChannel
+      attr_reader :channel
+
+      def initialize(channel)
+        raise ArgumentError, "Unsupported channel type '#{channel.class}'" unless channel.kind_of?(Ably::Realtime::Channel)
+        @channel = channel
+      end
+
+      def to_s
+        "<PushChannel: name=#{channel.name}>"
+      end
+
+      # Subscribes the device to push notifications for the channel.
+      #
+      # @spec RSH7a
+      #
+      # @note This is unsupported in the Ruby library
+      def subscribe_device(*args)
+        raise_unsupported
+      end
+
+      # Subscribes all devices associated with the current device's clientId to push notifications for the channel.
+      #
+      # @spec RSH7b
+      #
+      # @note This is unsupported in the Ruby library
+      def subscribe_client_id(*args)
+        raise_unsupported
+      end
+
+      # Unsubscribes the device from receiving push notifications for the channel.
+      #
+      # @spec RSH7c
+      #
+      # @note This is unsupported in the Ruby library
+      def unsubscribe_device(*args)
+        raise_unsupported
+      end
+
+      # Unsubscribes all devices associated with the current device's clientId from receiving push notifications for the channel.
+      #
+      # @spec RSH7d
+      #
+      # @note This is unsupported in the Ruby library
+      def unsubscribe_client_id(*args)
+        raise_unsupported
+      end
+
+      # Retrieves all push subscriptions for the channel. Subscriptions can be filtered using a params object.
+      # Returns a {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::PushChannelSubscription} objects.
+      #
+      # @spec RSH7e
+      #
+      # @note This is unsupported in the Ruby library
+      def get_subscriptions(*args)
+        raise_unsupported
+      end
+
+      private
+      def raise_unsupported
+        raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. All PushChannel methods are unavailable'
+      end
+    end
+  end
+end