ably 0.8.15 → 1.0.0

data/lib/ably/modules/state_emitter.rb

@@ -4,7 +4,8 @@ module Ably::Modules
   # module, and the class is an {EventEmitter}.  It then emits state changes.
   #
   # It also ensures the EventEmitter is configured to retrict permitted events to the
-  # the available STATEs and :error.
+  # the available STATEs or EVENTs if defined i.e. if EVENTs includes an additional type such as
+  # :update, then it will support all EVENTs being emitted. EVENTs must be a superset of STATEs
   #
   # @note This module requires that the method #logger is defined.
   #
@@ -51,7 +52,7 @@ module Ably::Modules
     # @api private
     def state=(new_state, *args)
       if state != new_state
-        logger.debug("#{self.class}: StateEmitter changed from #{state} => #{new_state}") if respond_to?(:logger, true)
+        logger.debug { "#{self.class}: StateEmitter changed from #{state} => #{new_state}" } if respond_to?(:logger, true)
         @state = STATE(new_state)
         emit @state, *args
       end
@@ -153,8 +154,10 @@ module Ably::Modules
 
     def self.included(klass)
       klass.configure_event_emitter coerce_into: Proc.new { |event|
-        if event == :error
-          :error
+        # Special case allows EVENT instead of STATE to be emitted
+        # Relies on the assumption that EVENT is a superset of STATE
+        if klass.const_defined?(:EVENT)
+          klass::EVENT(event)
         else
           klass::STATE(event)
         end

data/lib/ably/modules/state_machine.rb

@@ -18,14 +18,12 @@ module Ably::Modules
 
     # 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)
+      unless result = transition_to(state.to_sym, *args)
         exception = exception_for_state_change_to(state)
-        object.emit :error, exception
-        logger.fatal "#{self.class}: #{exception.message}"
+        logger.fatal { "#{self.class}: #{exception.message}" }
       end
       result
     end

data/lib/ably/modules/uses_state_machine.rb

@@ -67,15 +67,19 @@ module Ably::Modules
 
     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}"
+        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}"
+        logger.debug { "#{self.class.name}: Transitioned to #{state_machine.current_state}" }
       end
     end
 
     def emit_object(new_state, emit_params)
       if self.class.emits_klass
-        self.class.emits_klass.new((emit_params || {}).merge(current: STATE(new_state), previous: STATE(state_machine.current_state)))
+        self.class.emits_klass.new((emit_params || {}).merge(
+          current: STATE(new_state),
+          previous: STATE(state_machine.current_state),
+          event: EVENT(new_state)
+        ))
       else
         emit_params
       end

data/lib/ably/realtime.rb

@@ -11,6 +11,8 @@ require 'ably/realtime/client'
 require 'ably/realtime/connection'
 require 'ably/realtime/presence'
 
+require 'ably/models/message_encoders/base'
+
 Dir.glob(File.expand_path("models/*.rb", File.dirname(__FILE__))).each do |file|
   require file
 end

data/lib/ably/realtime/auth.rb

@@ -44,18 +44,20 @@ module Ably
       def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
       def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
       def_delegators :client, :logger
+      def_delegators :client, :connection
 
       def initialize(client)
         @client = client
         @auth_sync = client.rest_client.auth
       end
 
-      # Ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary.
+      # For new connections, ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary.
+      # If a connection is already established, the connection will be upgraded with a new token
       #
       # In the event that a new token request is made, the provided options are used
       #
-      # @param (see Ably::Auth#authorise)
-      # @option (see Ably::Auth#authorise)
+      # @param (see Ably::Auth#authorize)
+      # @option (see Ably::Auth#authorize)
       #
       # @return [Ably::Util::SafeDeferrable]
       # @yield [Ably::Models::TokenDetails]
@@ -63,33 +65,90 @@ module Ably
       # @example
       #    # will issue a simple token request using basic auth
       #    client = Ably::Rest::Client.new(key: 'key.id:secret')
-      #    client.auth.authorise do |token_details|
+      #    client.auth.authorize do |token_details|
       #      token_details #=> Ably::Models::TokenDetails
       #    end
       #
-      def authorise(token_params = nil, auth_options = nil, &success_callback)
-        async_wrap(success_callback) do
-          auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
-        end.tap do |deferrable|
-          deferrable.errback do |error|
-            client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
+      def authorize(token_params = nil, auth_options = nil, &success_callback)
+        Ably::Util::SafeDeferrable.new(logger).tap do |authorize_method_deferrable|
+          # Wrap the sync authorize method and wait for the result from the deferrable
+          async_wrap do
+            authorize_sync(token_params, auth_options)
+          end.tap do |auth_operation|
+            # Authorize operation succeeded and we have a new token, now let's perform inline authentication
+            auth_operation.callback do |token|
+              case connection.state.to_sym
+              when :initialized, :disconnected, :suspended, :closed, :closing, :failed
+                connection.connect
+              when :connected
+                perform_inline_auth token
+              when :connecting
+                # Fail all current connection attempts and try again with the new token, see #RTC8b
+                connection.manager.release_and_establish_new_transport
+              else
+                logger.fatal { "Auth#authorize: unsupported state #{connection.state}" }
+                authorize_method_deferrable.fail Ably::Exceptions::InvalidState.new("Unsupported state #{connection.state} for Auth#authorize")
+                next
+              end
+
+              # Indicate success or failure based on response from realtime, see #RTC8b1
+              auth_deferrable_resolved = false
+
+              connection.unsafe_once(:connected, :update) do
+                auth_deferrable_resolved = true
+                authorize_method_deferrable.succeed token
+              end
+              connection.unsafe_once(:suspended, :closed, :failed) do |state_change|
+                auth_deferrable_resolved = true
+                authorize_method_deferrable.fail state_change.reason
+              end
+            end
+
+            # Authorize failed, likely due to auth_url or auth_callback failing
+            auth_operation.errback do |error|
+              client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
+              authorize_method_deferrable.fail error
+            end
+          end
+
+          # Call the block provided to this method upon success of this deferrable
+          authorize_method_deferrable.callback do |token|
+            yield token if block_given?
           end
         end
       end
 
-      # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
-      # @param (see Ably::Auth#authorise)
-      # @option (see Ably::Auth#authorise)
+      # @deprecated Use {#authorize} instead
+      def authorise(*args, &block)
+        logger.warn { "Auth#authorise is deprecated and will be removed in 1.0. Please use Auth#authorize instead" }
+        authorize(*args, &block)
+      end
+
+      # Synchronous version of {#authorize}. See {Ably::Auth#authorize} for method definition
+      # Please note that authorize_sync will however not upgrade the current connection's token as this requires
+      # an synchronous operation to send the new authentication details to Ably over a realtime connection
+      #
+      # @param (see Ably::Auth#authorize)
+      # @option (see Ably::Auth#authorize)
       # @return [Ably::Models::TokenDetails]
       #
-      def authorise_sync(token_params = nil, auth_options = nil)
-        auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
+      def authorize_sync(token_params = nil, auth_options = nil)
+        @authorization_in_flight = true
+        auth_sync.authorize(token_params, auth_options)
+      ensure
+        @authorization_in_flight = false
       end
 
-      # def_delegator :auth_sync, :request_token, :request_token_sync
-      # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
-      # def_delegator :auth_sync, :auth_header, :auth_header_sync
-      # def_delegator :auth_sync, :auth_params, :auth_params_sync
+      # @api private
+      def authorization_in_flight?
+        @authorization_in_flight
+      end
+
+      # @deprecated Use {#authorize_sync} instead
+      def authorise_sync(*args)
+        logger.warn { "Auth#authorise_sync is deprecated and will be removed in 1.0. Please use Auth#authorize_sync instead" }
+        authorize_sync(*args)
+      end
 
       # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
       #
@@ -113,8 +172,8 @@ module Ably
       end
 
       # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
-      # @param (see Ably::Auth#authorise)
-      # @option (see Ably::Auth#authorise)
+      # @param (see Ably::Auth#authorize)
+      # @option (see Ably::Auth#authorize)
       # @return [Ably::Models::TokenDetails]
       #
       def request_token_sync(token_params = {}, auth_options = {})
@@ -140,8 +199,8 @@ module Ably
       end
 
       # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
-      # @param (see Ably::Auth#authorise)
-      # @option (see Ably::Auth#authorise)
+      # @param (see Ably::Auth#authorize)
+      # @option (see Ably::Auth#authorize)
       # @return [Ably::Models::TokenRequest]
       #
       def create_token_request_sync(token_params = {}, auth_options = {})
@@ -149,7 +208,7 @@ module Ably
       end
 
       # Auth header string used in HTTP requests to Ably
-      # Will reauthorise implicitly if required and capable
+      # Will reauthorize implicitly if required and capable
       #
       # @return [Ably::Util::SafeDeferrable]
       # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
@@ -168,13 +227,22 @@ module Ably
       end
 
       # Auth params used in URI endpoint for Realtime connections
-      # Will reauthorise implicitly if required and capable
+      # Will reauthorize implicitly if required and capable
       #
       # @return [Ably::Util::SafeDeferrable]
       # @yield [Hash] Auth params for a new Realtime connection
       #
       def auth_params(&success_callback)
-        async_wrap(success_callback) do
+        fail_callback = Proc.new do |error, deferrable|
+          logger.error { "Failed to authenticate: #{error}" }
+          if error.kind_of?(Ably::Exceptions::BaseAblyException)
+            # Use base exception if it exists carrying forward the status codes
+            deferrable.fail Ably::Exceptions::AuthenticationFailed.new(error.message, nil, nil, error)
+          else
+            deferrable.fail Ably::Exceptions::AuthenticationFailed.new(error.message, 500, 80019)
+          end
+        end
+        async_wrap(success_callback, fail_callback) do
           auth_params_sync
         end
       end
@@ -197,22 +265,14 @@ module Ably
         @client
       end
 
-      # If authorise is called with true, this block is executed so that it
-      # can perform the authentication upgrade
-      def upgrade_authentication_block(new_token)
-        # This block is called if the authorisation was forced
-        if client.connection.connected? || client.connection.connecting?
-          logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
-          block = Proc.new do
-            if client.connection.transport
-              logger.debug "Realtime::Auth - current transport disconnected"
-              client.connection.transport.disconnect
-            else
-              EventMachine.add_timer(0.1, &block)
-            end
-          end
-          block.call
-        end
+      # Sends an AUTH ProtocolMessage on the existing connection triggering
+      # an inline AUTH process, see #RTC8a
+      def perform_inline_auth(token)
+        logger.debug { "Performing inline AUTH with Ably using token #{token}" }
+        connection.send_protocol_message(
+          action: Ably::Models::ProtocolMessage::ACTION.Auth.to_i,
+          auth: { access_token: token.token }
+        )
       end
     end
   end

data/lib/ably/realtime/channel.rb

@@ -23,8 +23,6 @@ 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
     #
@@ -36,14 +34,24 @@ module Ably
       include Ably::Modules::MessageEmitter
       extend Ably::Modules::Enum
 
+      # ChannelState
+      # The permited states for this channel
       STATE = ruby_enum('STATE',
         :initialized,
         :attaching,
         :attached,
         :detaching,
         :detached,
+        :suspended,
         :failed
       )
+
+      # ChannelEvent
+      # The permitted channel events that are emitted for this channel
+      EVENT = ruby_enum('EVENT',
+        STATE.to_sym_arr + [:update]
+      )
+
       include Ably::Modules::StateEmitter
       include Ably::Modules::UsesStateMachine
       ensure_state_machine_emits 'Ably::Models::ChannelStateChange'
@@ -138,11 +146,14 @@ module Ably
       #   end
       #
       def publish(name, data = nil, attributes = {}, &success_block)
-        raise Ably::Exceptions::ChannelInactive.new('Cannot publish messages on a detached channel') if detached? || detaching?
-        raise Ably::Exceptions::ChannelInactive.new('Cannot publish messages on a failed channel') if failed?
+        if detached? || detaching? || failed?
+          error = Ably::Exceptions::ChannelInactive.new("Cannot publish messages on a channel in state #{state}")
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
+        end
 
         if !connection.can_publish_messages?
-          raise Ably::Exceptions::MessageQueueingDisabled.new("Message cannot be published. Client is configured to disallow queueing of messages and connection is currently #{connection.state}")
+          error = Ably::Exceptions::MessageQueueingDisabled.new("Message cannot be published. Client is configured to disallow queueing of messages and connection is currently #{connection.state}")
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
         end
 
         messages = if name.kind_of?(Enumerable)
@@ -192,10 +203,19 @@ module Ably
       #
       def attach(&success_block)
         if connection.closing? || connection.closed? || connection.suspended? || connection.failed?
-          raise Ably::Exceptions::InvalidStateChange.new("Cannot ATTACH channel when the connection is in a closed, suspended or failed state. Connection state: #{connection.state}")
+          error = Ably::Exceptions::InvalidStateChange.new("Cannot ATTACH channel when the connection is in a closed, suspended or failed state. Connection state: #{connection.state}")
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
+        end
+
+        if !attached?
+          if detaching?
+            # Let the pending operation complete (#RTL4h)
+            once_state_changed { transition_state_machine :attaching if can_transition_to?(:attaching) }
+          else
+            transition_state_machine :attaching if can_transition_to?(:attaching)
+          end
         end
 
-        transition_state_machine :attaching if can_transition_to?(:attaching)
         deferrable_for_state_change_to(STATE.Attached, &success_block)
       end
 
@@ -207,14 +227,24 @@ module Ably
       def detach(&success_block)
         if initialized?
           success_block.call if block_given?
-          return Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
-            EventMachine.next_tick { deferrable.succeed }
-          end
+          return Ably::Util::SafeDeferrable.new_and_succeed_immediately(logger)
         end
 
-        raise exception_for_state_change_to(:detaching) if failed?
+        if failed? || connection.closing? || connection.failed?
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, exception_for_state_change_to(:detaching))
+        end
+
+        if !detached?
+          if attaching?
+            # Let the pending operation complete (#RTL5i)
+            once_state_changed { transition_state_machine :detaching if can_transition_to?(:detaching) }
+          elsif can_transition_to?(:detaching)
+            transition_state_machine :detaching
+          else
+            transition_state_machine! :detached
+          end
+        end
 
-        transition_state_machine :detaching if can_transition_to?(:detaching)
         deferrable_for_state_change_to(STATE.Detached, &success_block)
       end
 
@@ -244,7 +274,10 @@ module Ably
       #
       def history(options = {}, &callback)
         if options.delete(:until_attach)
-          raise ArgumentError, 'option :until_attach is invalid as the channel is not attached' unless attached?
+          unless attached?
+            error = Ably::Exceptions::InvalidRequest.new('option :until_attach is invalid as the channel is not attached' )
+            return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
+          end
           options[:from_serial] = attached_serial
         end
 
@@ -263,7 +296,7 @@ module Ably
       end
 
       # @api private
-      def set_failed_channel_error_reason(error)
+      def set_channel_error_reason(error)
         @error_reason = error
       end
 
@@ -288,22 +321,26 @@ module Ably
         client.logger
       end
 
+      # Internal queue used for messages published that cannot yet be enqueued on the connection
+      # @api private
+      def __queue__
+        @queue
+      end
+
       # As we are using a state machine, do not allow change_state to be used
       # #transition_state_machine must be used instead
       private :change_state
 
       private
-      def queue
-        @queue
-      end
-
       def setup_event_handlers
         __incoming_msgbus__.subscribe(:message) do |message|
-          message.decode self
+          message.decode(client.encoders, options) do |encode_error, error_message|
+            client.logger.error error_message
+          end
           emit_message message.name, message
         end
 
-        on(STATE.Attached) do
+        unsafe_on(STATE.Attached) do
           process_queue
         end
       end
@@ -316,15 +353,18 @@ module Ably
           create_message(raw_msg).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', 400, 40012)
+              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}'", 400, 40012)
+              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
 
-        queue.push(*messages)
+        __queue__.push(*messages)
 
         if attached?
           process_queue
@@ -366,14 +406,14 @@ module Ably
       end
 
       def messages_in_queue?
-        !queue.empty?
+        !__queue__.empty?
       end
 
       # Move messages from Channel Queue into Outgoing Connection Queue
       def process_queue
         condition = -> { attached? && messages_in_queue? }
         non_blocking_loop_while(condition) do
-          send_messages_within_protocol_message queue.shift(MAX_PROTOCOL_MESSAGE_BATCH_SIZE)
+          send_messages_within_protocol_message __queue__.shift(MAX_PROTOCOL_MESSAGE_BATCH_SIZE)
         end
       end
 
@@ -387,7 +427,9 @@ module Ably
 
       def create_message(message)
         Ably::Models::Message(message.dup).tap do |msg|
-          msg.encode self
+          msg.encode(client.encoders, options) do |encode_error, error_message|
+            client.logger.error error_message
+          end
         end
       end