ably 0.6.2 → 0.7.0

data/lib/ably/modules/state_machine.rb

@@ -0,0 +1,53 @@
+require 'statesman'
+require 'ably/modules/statesman_monkey_patch'
+
+module Ably::Modules
+  # Module providing Statesman StateMachine functionality
+  #
+  # Expects method #logger to be defined
+  #
+  # @api private
+  module StateMachine
+    def self.included(klass)
+      klass.class_eval do
+        include Statesman::Machine
+      end
+      klass.extend Ably::Modules::StatesmanMonkeyPatch
+    end
+
+    # Alternative to Statesman's #transition_to that:
+    # * log state change failures to {Logger}
+    # * raise an exception on the {Ably::Realtime::Channel}
+    #
+    # @return [void]
+    def transition_state(state, *args)
+      unless result = transition_to(state, *args)
+        exception = exception_for_state_change_to(state)
+        object.trigger :error, exception
+        logger.fatal "#{self.class}: #{exception.message}"
+      end
+      result
+    end
+
+    # @return [Statesman History Object]
+    def previous_transition
+      history[-2]
+    end
+
+    # @return [Symbol]
+    def previous_state
+      previous_transition.to_state if previous_transition
+    end
+
+    # @return [Ably::Exceptions::StateChangeError]
+    def exception_for_state_change_to(state)
+      error_message = "#{self.class}: Unable to transition from #{current_state} => #{state}"
+      Ably::Exceptions::StateChangeError.new(error_message, nil, 80020)
+    end
+
+    private
+    def self.is_error_type?(error)
+      error.kind_of?(Ably::Models::ErrorInfo) || error.kind_of?(StandardError)
+    end
+  end
+end

data/lib/ably/modules/statesman_monkey_patch.rb

@@ -0,0 +1,33 @@
+module Ably::Modules
+  # @api private
+  module StatesmanMonkeyPatch
+    # Override Statesman's #before_transition to support :from arrays
+    # This can be removed once https://github.com/gocardless/statesman/issues/95 is solved
+    def before_transition(options = nil, &block)
+      arrayify_transition(options) do |options_without_from_array|
+        super *options_without_from_array, &block
+      end
+    end
+
+    # Override Statesman's #after_transition to support :from arrays
+    # This can be removed once https://github.com/gocardless/statesman/issues/95 is solved
+    def after_transition(options = nil, &block)
+      arrayify_transition(options) do |options_without_from_array|
+        super *options_without_from_array, &block
+      end
+    end
+
+    private
+    def arrayify_transition(options, &block)
+      if options.nil?
+        yield []
+      elsif options.fetch(:from, nil).kind_of?(Array)
+        options[:from].each do |from_state|
+          yield [options.merge(from: from_state)]
+        end
+      else
+        yield [options]
+      end
+    end
+  end
+end

data/lib/ably/modules/uses_state_machine.rb

@@ -0,0 +1,74 @@
+module Ably::Modules
+  # Mixing module that assists with {https://github.com/gocardless/statesman Statemans State Machine} state transitions
+  # and maintaining state of this object's #state.
+  #
+  # Expects:
+  #   - @state_machine is set to the StateMachine
+  #   - StateEmitter is included in the object
+  #
+  module UsesStateMachine
+    extend Forwardable
+
+    # Call #transition_to on the StateMachine
+    #
+    # @return [Boolean] true if new_state can be transitioned to by state machine
+    # @api private
+    def transition_state_machine(new_state, emit_object = nil)
+      state_machine.transition_state(new_state, emit_object)
+    end
+
+    # Call #transition_to! on the StateMachine
+    # An exception wil be raised if new_state cannot be transitioned to by state machine
+    #
+    # @return [void]
+    # @api private
+    def transition_state_machine!(new_state, emit_object = nil)
+      state_machine.transition_to!(new_state, emit_object)
+    end
+
+    # Provides an internal method for this object's state to match the StateMachine's current state.
+    # The current object's state will be changed to the StateMachine state and will emit an event
+    # @api private
+    def synchronize_state_with_statemachine(*args)
+      log_state_machine_state_change
+      change_state state_machine.current_state, state_machine.last_transition.metadata
+    end
+
+    # @!attribute [r] previous_state
+    # @return [STATE,nil] The previous state for this connection
+    # @api private
+    def previous_state
+      if state_machine.previous_state
+        STATE(state_machine.previous_state)
+      end
+    end
+
+    # @!attribute [r] state_history
+    # @return [Array<Hash>] All previous states including the current state in date ascending order with Hash properties :state, :metadata, :transitioned_at
+    # @api private
+    def state_history
+      state_machine.history.map do |transition|
+        {
+          state:           STATE(transition.to_state),
+          metadata:        transition.metadata,
+          transitioned_at: transition.created_at
+        }
+      end
+    end
+
+    def_delegators :state_machine, :can_transition_to?
+
+    private
+    attr_reader :state_machine
+
+    def_delegators :state_machine, :exception_for_state_change_to
+
+    def log_state_machine_state_change
+      if state_machine.previous_state
+        logger.debug "#{self.class.name}: Transitioned from #{state_machine.previous_state} => #{state_machine.current_state}"
+      else
+        logger.debug "#{self.class.name}: Transitioned to #{state_machine.current_state}"
+      end
+    end
+  end
+end

data/lib/ably/realtime.rb

@@ -5,6 +5,8 @@ require 'ably/modules/event_emitter'
 
 require 'ably/realtime/channel'
 require 'ably/realtime/channels'
+require 'ably/realtime/channel/channel_manager'
+require 'ably/realtime/channel/channel_state_machine'
 require 'ably/realtime/client'
 require 'ably/realtime/connection'
 require 'ably/realtime/connection/connection_manager'
@@ -55,8 +57,8 @@ module Ably
     #    # create a new client authenticating with basic auth and a client_id
     #    client = Ably::Realtime.new(api_key: 'key.id:secret', client_id: 'john')
     #
-    def self.new(options, &auth_block)
-      Ably::Realtime::Client.new(options, &auth_block)
+    def self.new(options, &token_request_block)
+      Ably::Realtime::Client.new(options, &token_request_block)
     end
   end
 end

data/lib/ably/realtime/channel.rb

@@ -23,14 +23,10 @@ module Ably
     #   Channel::STATE.Detached
     #   Channel::STATE.Failed
     #
+    # Channels emit errors - use `on(:error)` to subscribe to errors
+    #
     # @!attribute [r] state
     #   @return {Ably::Realtime::Connection::STATE} channel state
-    # @!attribute [r] client
-    #   @return {Ably::Realtime::Client} Ably client associated with this channel
-    # @!attribute [r] name
-    #   @return {String} channel name
-    # @!attribute [r] options
-    #   @return {Hash} channel options configured for this channel, see {#initialize} for channel_options
     #
     class Channel
       include Ably::Modules::Conversions
@@ -48,11 +44,31 @@ module Ably
         :failed
       )
       include Ably::Modules::StateEmitter
+      include Ably::Modules::UsesStateMachine
 
       # Max number of messages to bundle in a single ProtocolMessage
       MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50
 
-      attr_reader :client, :name, :options
+      # {Ably::Realtime::Client} associated with this channel
+      # @return [Ably::Realtime::Client]
+      attr_reader :client
+
+      # Channel name
+      # @return [String]
+      attr_reader :name
+
+      # Channel options configured for this channel, see {#initialize} for channel_options
+      # @return [Hash]
+      attr_reader :options
+
+      # When a channel failure occurs this attribute contains the Ably Exception
+      # @return [Ably::Models::ErrorInfo,Ably::Exceptions::BaseAblyException]
+      attr_reader :error_reason
+
+      # The Channel manager responsible for attaching, detaching and handling failures for this channel
+      # @return [Ably::Realtime::Channel::ChannelManager]
+      # @api private
+      attr_reader :manager
 
       # Initialize a new Channel object
       #
@@ -63,12 +79,17 @@ module Ably
       # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of `cipher_params` options
       #
       def initialize(client, name, channel_options = {})
+        ensure_utf_8 :name, name
+
         @client        = client
         @name          = name
         @options       = channel_options.clone.freeze
         @subscriptions = Hash.new { |hash, key| hash[key] = [] }
         @queue         = []
-        @state         = STATE.Initialized
+
+        @state_machine = ChannelStateMachine.new(self)
+        @state         = STATE(state_machine.current_state)
+        @manager       = ChannelManager.new(self, client.connection)
 
         setup_event_handlers
       end
@@ -91,9 +112,11 @@ module Ably
       #     puts "#{message.name} was not received, error #{error.message}"
       #   end
       #
-      def publish(name, data, &callback)
+      def publish(name, data, &success_block)
+        ensure_utf_8 :name, name
+
         create_message(name, data).tap do |message|
-          message.callback(&callback) if block_given?
+          message.callback(&success_block) if block_given?
           queue_message message
         end
       end
@@ -105,9 +128,9 @@ module Ably
       #
       # @return [void]
       #
-      def subscribe(name = :all, &blk)
+      def subscribe(name = :all, &callback)
         attach unless attached? || attaching?
-        subscriptions[message_name_key(name)] << blk
+        subscriptions[message_name_key(name)] << callback
       end
 
       # Unsubscribe the matching block for messages matching providing event name, or all messages if event name not provided.
@@ -117,14 +140,14 @@ module Ably
       #
       # @return [void]
       #
-      def unsubscribe(name = :all, &blk)
+      def unsubscribe(name = :all, &callback)
         if message_name_key(name) == :all
           subscriptions.keys
         else
           Array(message_name_key(name))
         end.each do |key|
           subscriptions[key].delete_if do |block|
-            !block_given? || blk == block
+            !block_given? || callback == block
           end
         end
       end
@@ -134,18 +157,11 @@ module Ably
       # to need to call attach explicitly.
       #
       # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Attached state
-      # @return [void]
+      # @return [EventMachine::Deferrable] Deferrable that supports both success (callback) and failure (errback) callback
       #
-      def attach(&block)
-        if attached?
-          block.call self if block_given?
-        else
-          once(STATE.Attached) { block.call self } if block_given?
-          if !attaching?
-            change_state STATE.Attaching
-            send_attach_protocol_message
-          end
-        end
+      def attach(&success_block)
+        transition_state_machine :attaching if can_transition_to?(:attaching)
+        deferrable_for_state_change_to(STATE.Attached, &success_block)
       end
 
       # Detach this channel, and call the block if provided when in a Detached or Failed state
@@ -153,16 +169,10 @@ module Ably
       # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Detached or Failed state
       # @return [void]
       #
-      def detach(&block)
-        if detached? || failed?
-          block.call self if block_given?
-        else
-          once(STATE.Detached, STATE.Failed) { block.call self } if block_given?
-          if !detaching?
-            change_state STATE.Detaching
-            send_detach_protocol_message
-          end
-        end
+      def detach(&success_block)
+        raise exception_for_state_change_to(:detaching) if failed? || initialized?
+        transition_state_machine :detaching if can_transition_to?(:detaching)
+        deferrable_for_state_change_to(STATE.Detached, &success_block)
       end
 
       # Presence object for this Channel.  This controls this client's
@@ -172,6 +182,7 @@ module Ably
       # @return {Ably::Realtime::Presence}
       #
       def presence
+        attach if initialized?
         @presence ||= Presence.new(self)
       end
 
@@ -198,6 +209,11 @@ module Ably
         )
       end
 
+      # @api private
+      def set_failed_channel_error_reason(error)
+        @error_reason = error
+      end
+
       private
       attr_reader :queue, :subscriptions
 
@@ -212,14 +228,6 @@ module Ably
         on(STATE.Attached) do
           process_queue
         end
-
-        connection.on(Connection::STATE.Closed) do
-          change_state STATE.Detached
-        end
-
-        connection.on(Connection::STATE.Failed) do
-          change_state STATE.Failed unless detached? || initialized?
-        end
       end
 
       # Queue message and process queue if channel is attached.
@@ -254,21 +262,6 @@ module Ably
         )
       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)
-        client.connection.send_protocol_message(
-          action:  state.to_i,
-          channel: name
-        )
-      end
-
       def create_message(name, data)
         message = { name: name }
         message.merge!(data: data) unless data.nil?

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

@@ -0,0 +1,91 @@
+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
+
+        channel.on(:attached, :detached) do
+          channel.set_failed_channel_error_reason nil
+        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
+        if connection.closed?
+          channel.transition_state_machine :detached
+        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
+
+      # Channel has failed
+      def failed(error)
+        logger.error "Channel #{channel.name} error: #{error}"
+        channel.trigger :error, 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