ably 0.8.15 → 1.0.0

data/lib/ably/realtime/presence/presence_manager.rb

@@ -28,6 +28,25 @@ module Ably::Realtime
         presence.members.change_state :sync_starting
       end
 
+      # Process presence messages from SYNC messages. Sync can be server-initiated or triggered following ATTACH
+      #
+      # @return [void]
+      #
+      # @api private
+      def sync_process_messages(serial, presence_messages)
+        unless presence.members.sync_starting?
+          presence.members.change_state :sync_starting
+        end
+
+        presence.members.update_sync_serial serial
+
+        presence_messages.each do |presence_message|
+          presence.__incoming_msgbus__.publish :sync, presence_message
+        end
+
+        presence.members.change_state :finalizing_sync if presence.members.sync_serial_cursor_at_end?
+      end
+
       # There server has indicated that there are no SYNC ProtocolMessages to come because
       # there are no members on this channel
       #
@@ -35,7 +54,8 @@ module Ably::Realtime
       #
       # @api private
       def sync_not_expected
-        presence.members.change_state :in_sync
+        logger.debug { "#{self.class.name}: Emitting leave events for all members as a SYNC is not expected and thus there are no members on the channel" }
+        presence.members.change_state :sync_none
       end
 
       private
@@ -43,16 +63,20 @@ module Ably::Realtime
 
       def setup_channel_event_handlers
         channel.unsafe_on(:detached) do
-          presence.transition_state_machine :left if presence.can_transition_to?(:left)
+          if !presence.initialized?
+            presence.transition_state_machine :left if presence.can_transition_to?(:left)
+          end
         end
 
         channel.unsafe_on(:failed) do |metadata|
-          presence.transition_state_machine :failed, metadata if presence.can_transition_to?(:failed)
+          if !presence.initialized?
+            presence.transition_state_machine :left, metadata if presence.can_transition_to?(:left)
+          end
         end
+      end
 
-        presence.unsafe_on(:entered) do |message|
-          presence.set_connection_id message.connection_id
-        end
+      def logger
+        presence.channel.client.logger
       end
     end
   end

data/lib/ably/realtime/presence/presence_state_machine.rb

@@ -15,19 +15,16 @@ module Ably::Realtime
       #   :entered
       #   :leaving
       #   :left
-      #   :failed
       Presence::STATE.each_with_index do |state_enum, index|
         state state_enum.to_sym, initial: index == 0
       end
 
       # Entering or entered states can skip leaving and go straight to left if a channel is detached
       # A channel that detaches very quickly will also go straight to :left from :initialized
-      # Failed states only occur when present and the channel fails or presence fails
       transition :from => :initialized,  :to => [:entering, :left]
-      transition :from => :entering,     :to => [:entered, :leaving, :left, :failed]
-      transition :from => :entered,      :to => [:leaving, :left, :failed]
-      transition :from => :leaving,      :to => [:left, :entering, :failed]
-      transition :from => :failed,       :to => [:entering]
+      transition :from => :entering,     :to => [:entered, :leaving, :left]
+      transition :from => :entered,      :to => [:leaving, :left]
+      transition :from => :leaving,      :to => [:left, :entering]
 
       after_transition do |presence, transition|
         presence.synchronize_state_with_statemachine
@@ -41,13 +38,9 @@ module Ably::Realtime
         presence.manager.leave current_transition.metadata
       end
 
-      after_transition(to: [:failed]) do |presence, current_transition|
-        presence.manager.emit_error current_transition.metadata
-      end
-
       # Transitions responsible for updating channel#error_reason
-      before_transition(to: [:left, :failed]) do |presence, current_transition|
-        presence.channel.set_failed_channel_error_reason current_transition.metadata if is_error_type?(current_transition.metadata)
+      before_transition(to: [:left]) do |presence, current_transition|
+        presence.channel.set_channel_error_reason current_transition.metadata if is_error_type?(current_transition.metadata)
       end
 
       private

data/lib/ably/rest.rb

@@ -3,12 +3,12 @@ require 'ably/rest/channels'
 require 'ably/rest/client'
 require 'ably/rest/presence'
 
+require 'ably/models/message_encoders/base'
+
 Dir.glob(File.expand_path("models/*.rb", File.dirname(__FILE__))).each do |file|
   require file
 end
 
-require 'ably/models/message_encoders/base'
-
 module Ably
   # Rest provides the top-level class to be instanced for the Ably Rest library
   #

data/lib/ably/rest/channel.rb

@@ -65,14 +65,14 @@ module Ably
 
         payload = messages.map do |message|
           Ably::Models::Message(message.dup).tap do |msg|
-            msg.encode self
+            msg.encode client.encoders, options
 
             next if msg.client_id.nil?
             if msg.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
             unless client.auth.can_assume_client_id?(msg.client_id)
-              raise Ably::Exceptions::IncompatibleClientId.new("Cannot publish with client_id '#{msg.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 '#{msg.client_id}' as it is incompatible with the current configured client_id '#{client.client_id}'")
             end
           end.as_json
         end
@@ -134,9 +134,9 @@ module Ably
       end
 
       def decode_message(message)
-        message.decode self
+        message.decode client.encoders, options
       rescue Ably::Exceptions::CipherError, Ably::Exceptions::EncoderError => e
-        client.logger.error "Decoding Error on channel '#{name}', message event name '#{message.name}'. #{e.class.name}: #{e.message}"
+        client.logger.error { "Decoding Error on channel '#{name}', message event name '#{message.name}'. #{e.class.name}: #{e.message}" }
       end
     end
   end

data/lib/ably/rest/client.rb

@@ -1,6 +1,7 @@
 require 'faraday'
 require 'json'
 require 'logger'
+require 'uri'
 
 require 'ably/rest/middleware/exceptions'
 
@@ -24,8 +25,8 @@ module Ably
       # Configuration for HTTP timeouts and HTTP request reattempts to fallback hosts
       HTTP_DEFAULTS = {
         open_timeout:       4,
-        request_timeout:    15,
-        max_retry_duration: 10,
+        request_timeout:    10,
+        max_retry_duration: 15,
         max_retry_count:    3
       }.freeze
 
@@ -103,12 +104,12 @@ module Ably
       # @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.
       #                                                                The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent
       # @option options [Boolean]                 :query_time          when true will query the {https://www.ably.io Ably} system for the current time instead of using the local time
-      # @option options [Hash]                    :token_params        convenience to pass in +token_params+ that will be used as a default for all token requests. See {Auth#create_token_request}
+      # @option options [Hash]                    :default_token_params   convenience to pass in +token_params+ that will be used as a default for all token requests. See {Auth#create_token_request}
       #
       # @option options [Integer]                 :http_open_timeout       (4 seconds) timeout in seconds for opening an HTTP connection for all HTTP requests
-      # @option options [Integer]                 :http_request_timeout    (15 seconds) timeout in seconds for any single complete HTTP request and response
+      # @option options [Integer]                 :http_request_timeout    (10 seconds) timeout in seconds for any single complete HTTP request and response
       # @option options [Integer]                 :http_max_retry_count    (3) maximum number of fallback host retries for HTTP requests that fail due to network issues or server problems
-      # @option options [Integer]                 :http_max_retry_duration (10 seconds) maximum elapsed time in which fallback host retries for HTTP requests will be attempted i.e. if the first default host attempt takes 5s, and then the subsequent fallback retry attempt takes 7s, no further fallback host attempts will be made as the total elapsed time of 12s exceeds the default 10s limit
+      # @option options [Integer]                 :http_max_retry_duration (15 seconds) maximum elapsed time in which fallback host retries for HTTP requests will be attempted i.e. if the first default host attempt takes 5s, and then the subsequent fallback retry attempt takes 7s, no further fallback host attempts will be made as the total elapsed time of 12s exceeds the default 10s limit
       #
       # @option options [Boolean]                 :fallback_hosts_use_default  (false) When true, forces the user of fallback hosts even if a non-default production endpoint is being used
       # @option options [Array<String>]           :fallback_hosts              When an array of fallback hosts are provided, these fallback hosts are always used if a request fails to the primary endpoint. If an empty array is provided, the fallback host functionality is disabled
@@ -127,13 +128,14 @@ module Ably
 
         options = options.clone
         if options.kind_of?(String)
-          options = if options.match(/^[\w-]{2,}\.[\w-]{2,}:[\w-]{2,}$/)
+          options = if options.match(Auth::API_KEY_REGEX)
             { key: options }
           else
             { token: options }
           end
         end
 
+        @realtime_client  = options.delete(:realtime_client)
         @tls              = options.delete(:tls) == false ? false : true
         @environment      = options.delete(:environment) # nil is production
         @environment      = nil if [:production, 'production'].include?(@environment)
@@ -182,7 +184,7 @@ module Ably
         end
         raise ArgumentError, 'Protocol is invalid.  Must be either :msgpack or :json' unless [:msgpack, :json].include?(@protocol)
 
-        token_params = options.delete(:token_params) || {}
+        token_params = options.delete(:default_token_params) || {}
         @options  = options
         @auth     = Auth.new(self, token_params, options)
         @channels = Ably::Rest::Channels.new(self)
@@ -285,14 +287,14 @@ module Ably
 
         response = case method.to_sym
         when :get
-          reauthorise_on_authorisation_failure do
+          reauthorize_on_authorisation_failure do
             send_request(method, path, params, headers: headers)
           end
         when :post
           path_with_params = Addressable::URI.new
           path_with_params.query_values = params || {}
           query = path_with_params.query
-          reauthorise_on_authorisation_failure do
+          reauthorize_on_authorisation_failure do
             send_request(method, "#{path}#{"?#{query}" unless query.nil? || query.empty?}", body, headers: headers)
           end
         end
@@ -346,18 +348,8 @@ module Ably
       # @return [void]
       #
       # @api private
-      def register_encoder(encoder)
-        encoder_klass = if encoder.kind_of?(String)
-          encoder.split('::').inject(Kernel) do |base, klass_name|
-            base.public_send(:const_get, klass_name)
-          end
-        else
-          encoder
-        end
-
-        raise "Encoder must inherit from `Ably::Models::MessageEncoders::Base`" unless encoder_klass.ancestors.include?(Ably::Models::MessageEncoders::Base)
-
-        encoders << encoder_klass.new(self)
+      def register_encoder(encoder, options = {})
+        encoders << Ably::Models::MessageEncoders.encoder_from(encoder, options)
       end
 
       # @!attribute [r] protocol_binary?
@@ -411,13 +403,25 @@ module Ably
         ].compact.join('-')
       end
 
+      # Allowable duration for an external auth request
+      # For REST client this defaults to request_timeout
+      # For Realtime clients this defaults to realtime_request_timeout
+      # @api private
+      def auth_request_timeout
+        if @realtime_client
+          @realtime_client.connection.defaults.fetch(:realtime_request_timeout)
+        else
+          http_defaults.fetch(:request_timeout)
+        end
+      end
+
       private
       def raw_request(method, path, params = {}, options = {})
         options = options.clone
-        if options.delete(:disable_automatic_reauthorise) == true
+        if options.delete(:disable_automatic_reauthorize) == true
           send_request(method, path, params, options)
         else
-          reauthorise_on_authorisation_failure do
+          reauthorize_on_authorisation_failure do
             send_request(method, path, params, options)
           end
         end
@@ -449,7 +453,7 @@ module Ably
           time_passed = Time.now - requested_at
           if can_fallback_to_alternate_ably_host? && retry_count < max_retry_count && time_passed <= max_retry_duration
             retry_count += 1
-            logger.warn "Ably::Rest::Client - Retry #{retry_count} for #{method} #{path} #{params} as initial attempt failed: #{error}"
+            logger.warn { "Ably::Rest::Client - Retry #{retry_count} for #{method} #{path} #{params} as initial attempt failed: #{error}" }
             retry
           end
 
@@ -464,11 +468,11 @@ module Ably
         end
       end
 
-      def reauthorise_on_authorisation_failure
+      def reauthorize_on_authorisation_failure
         yield
       rescue Ably::Exceptions::TokenExpired => e
         if auth.token_renewable?
-          auth.authorise(nil, force: true)
+          auth.authorize
           yield
         else
           raise e
@@ -535,7 +539,7 @@ module Ably
       end
 
       def initialize_default_encoders
-        Ably::Models::MessageEncoders.register_default_encoders self
+        Ably::Models::MessageEncoders.register_default_encoders self, binary_protocol: protocol == :msgpack
       end
     end
   end

data/lib/ably/rest/middleware/exceptions.rb

@@ -7,8 +7,6 @@ module Ably
       # HTTP exceptions raised by Ably due to an error status code
       # Ably returns JSON/Msgpack error codes and messages so include this if possible in the exception messages
       class Exceptions < Faraday::Response::Middleware
-        TOKEN_EXPIRED_CODE = 40140..40149
-
         def on_complete(env)
           if env.status >= 400
             error_status_code = env.status
@@ -35,7 +33,7 @@ module Ably
             if env.status >= 500
               raise Ably::Exceptions::ServerError.new(*exception_args)
             elsif env.status == 401
-              if TOKEN_EXPIRED_CODE.include?(error_code)
+              if Ably::Exceptions::TOKEN_EXPIRED_CODE.include?(error_code)
                 raise Ably::Exceptions::TokenExpired.new(*exception_args)
               else
                 raise Ably::Exceptions::UnauthorizedRequest.new(*exception_args)

data/lib/ably/rest/middleware/logger.rb

@@ -17,8 +17,8 @@ module Ably
         def_delegators :@logger, :debug, :info, :warn, :error, :fatal
 
         def call(env)
-          debug "=> URL: #{env.method} #{env.url}, Headers: #{dump_headers env.request_headers}"
-          debug "=> Body: #{body_for(env)}"
+          debug { "=> URL: #{env.method} #{env.url}, Headers: #{dump_headers env.request_headers}" }
+          debug { "=> Body: #{body_for(env)}" }
           super
         end
 

data/lib/ably/rest/presence.rb

@@ -88,9 +88,9 @@ module Ably
       end
 
       def decode_message(presence_message)
-        presence_message.decode channel
+        presence_message.decode client.encoders, channel.options
       rescue Ably::Exceptions::CipherError, Ably::Exceptions::EncoderError => e
-        client.logger.error "Decoding Error on presence channel '#{channel.name}', presence message client_id '#{presence_message.client_id}'. #{e.class.name}: #{e.message}"
+        client.logger.error { "Decoding Error on presence channel '#{channel.name}', presence message client_id '#{presence_message.client_id}'. #{e.class.name}: #{e.message}" }
       end
     end
   end

data/lib/ably/util/pub_sub.rb

@@ -38,7 +38,7 @@ module Ably::Util
 
         alias_method :subscribe, :unsafe_on
         alias_method :publish, :emit
-        alias_method :unsubscribe, :off
+        alias_method :unsubscribe, :unsafe_off
       end
     end
   end

data/lib/ably/util/safe_deferrable.rb

@@ -14,5 +14,31 @@ module Ably::Util
     def initialize(logger)
       @logger = logger
     end
+
+    # Create a new {SafeDeferrable} and fail immediately with the provided error in the next eventloop cycle
+    #
+    # @param error [Ably::Exceptions::BaseAblyException, Ably::Models::ErrorInfo]   The error used to fail the newly created {SafeDeferrable}
+    #
+    # @return [SafeDeferrable]
+    #
+    def self.new_and_fail_immediately(logger, error)
+      new(logger).tap do |deferrable|
+        EventMachine.next_tick do
+          deferrable.fail error
+        end
+      end
+    end
+
+    # Create a new {SafeDeferrable} and succeed immediately with the provided arguments in the next eventloop cycle
+    #
+    # @return [SafeDeferrable]
+    #
+    def self.new_and_succeed_immediately(logger, *args)
+      new(logger).tap do |deferrable|
+        EventMachine.next_tick do
+          deferrable.succeed *args
+        end
+      end
+    end
   end
 end

data/lib/ably/version.rb

@@ -1,6 +1,6 @@
 module Ably
-  VERSION = '0.8.15'
-  PROTOCOL_VERSION = '0.8'
+  VERSION = '1.0.0'
+  PROTOCOL_VERSION = '1.0'
 
   # Allow a variant to be configured for all instances of this client library
   # such as ruby-rest-[VERSION]

data/spec/acceptance/realtime/auth_spec.rb

@@ -5,6 +5,14 @@ require 'spec_helper'
 # wrapper around the Ably::Auth object
 #
 describe Ably::Realtime::Auth, :event_machine do
+  def disconnect_transport(connection)
+    if connection.transport
+      connection.transport.close_connection_after_writing
+    else
+      EventMachine.next_tick { disconnect_transport connection }
+    end
+  end
+
   vary_by_protocol do
     let(:default_options) { { key: api_key, environment: environment, protocol: protocol } }
     let(:client_options)  { default_options }
@@ -73,7 +81,7 @@ describe Ably::Realtime::Auth, :event_machine do
       context '#current_token_details' do
         it 'contains the current token after auth' do
           expect(auth.current_token_details).to be_nil
-          auth.authorise do
+          auth.authorize do
             expect(auth.current_token_details).to be_a(Ably::Models::TokenDetails)
             stop_reactor
           end
@@ -88,12 +96,13 @@ describe Ably::Realtime::Auth, :event_machine do
       end
 
       context '#options (auth_options)' do
+        let(:token_str) { auth.request_token_sync.token }
         let(:auth_url) { "https://echo.ably.io/?type=text" }
-        let(:auth_params) { { :body => random_str } }
+        let(:auth_params) { { :body => token_str } }
         let(:client_options) { default_options.merge(auto_connect: false) }
 
         it 'contains the configured auth options' do
-          auth.authorise({}, auth_url: auth_url, auth_params: auth_params) do
+          auth.authorize({}, auth_url: auth_url, auth_params: auth_params) do
             expect(auth.options[:auth_url]).to eql(auth_url)
             stop_reactor
           end
@@ -104,7 +113,7 @@ describe Ably::Realtime::Auth, :event_machine do
         let(:custom_ttl) { 33 }
 
         it 'contains the configured auth options' do
-          auth.authorise(ttl: custom_ttl) do
+          auth.authorize(ttl: custom_ttl) do
             expect(auth.token_params[:ttl]).to eql(custom_ttl)
             stop_reactor
           end
@@ -113,7 +122,7 @@ describe Ably::Realtime::Auth, :event_machine do
 
       context '#using_basic_auth?' do
         it 'is false when using Token Auth' do
-          auth.authorise do
+          auth.authorize do
             expect(auth).to_not be_using_basic_auth
             stop_reactor
           end
@@ -122,7 +131,7 @@ describe Ably::Realtime::Auth, :event_machine do
 
       context '#using_token_auth?' do
         it 'is true when using Token Auth' do
-          auth.authorise do
+          auth.authorize do
             expect(auth).to be_using_token_auth
             stop_reactor
           end
@@ -130,7 +139,7 @@ describe Ably::Realtime::Auth, :event_machine do
       end
     end
 
-    context do
+    context 'methods' do
       let(:custom_ttl)       { 33 }
       let(:custom_client_id) { random_str }
 
@@ -176,13 +185,17 @@ describe Ably::Realtime::Auth, :event_machine do
         end
       end
 
-      context '#authorise' do
-        it 'returns a token asynchronously' do
-          auth.authorise(ttl: custom_ttl, client_id: custom_client_id) do |token_details|
-            expect(token_details).to be_a(Ably::Models::TokenDetails)
-            expect(token_details.expires.to_i).to be_within(3).of(Time.now.to_i + custom_ttl)
-            expect(token_details.client_id).to eql(custom_client_id)
-            stop_reactor
+      context '#authorize' do
+        context 'with token auth' do
+          let(:client_options) { default_options.merge(use_token_auth: true) }
+
+          it 'returns a token asynchronously' do
+            auth.authorize(ttl: custom_ttl, client_id: custom_client_id) do |token_details|
+              expect(token_details).to be_a(Ably::Models::TokenDetails)
+              expect(token_details.expires.to_i).to be_within(3).of(Time.now.to_i + custom_ttl)
+              expect(token_details.client_id).to eql(custom_client_id)
+              stop_reactor
+            end
           end
         end
 
@@ -223,10 +236,11 @@ describe Ably::Realtime::Auth, :event_machine do
           context 'and an incompatible client_id in a TokenDetails object passed to the auth callback' do
             let(:auth_token_object) { rest_auth_client.auth.request_token }
 
-            it 'rejects a TokenDetails object with an incompatible client_id and raises an exception' do
+            it 'rejects a TokenDetails object with an incompatible client_id and fails with an exception' do
               client.connect
-              client.connection.on(:error) do |error|
-                expect(error).to be_a(Ably::Exceptions::IncompatibleClientId)
+              client.connection.on(:failed) do |state_change|
+                expect(state_change.reason).to be_a(Ably::Exceptions::AuthenticationFailed)
+                expect(state_change.reason.code).to eql(40012)
                 EventMachine.add_timer(0.1) do
                   expect(client.connection).to be_failed
                   stop_reactor
@@ -235,13 +249,14 @@ describe Ably::Realtime::Auth, :event_machine do
             end
           end
 
-          context 'and an incompatible client_id in a TokenRequest object passed to the auth callback and raises an exception' do
+          context 'and an incompatible client_id in a TokenRequest object passed to the auth callback and fails with an exception' do
             let(:auth_token_object) { rest_auth_client.auth.create_token_request }
 
-            it 'rejects a TokenRequests object with an incompatible client_id and raises an exception' do
+            it 'rejects a TokenRequests object with an incompatible client_id and fails with an exception' do
               client.connect
-              client.connection.on(:error) do |error|
-                expect(error).to be_a(Ably::Exceptions::IncompatibleClientId)
+              client.connection.on(:failed) do |state_change|
+                expect(state_change.reason).to be_a(Ably::Exceptions::AuthenticationFailed)
+                expect(state_change.reason.code).to eql(40012)
                 EventMachine.add_timer(0.1) do
                   expect(client.connection).to be_failed
                   stop_reactor
@@ -269,11 +284,12 @@ describe Ably::Realtime::Auth, :event_machine do
           let(:invalid_auth_token) { Ably::Rest::Client.new(default_options.merge(key: api_key, client_id: 'invalid')).auth.request_token }
 
           context 'and an incompatible client_id in a TokenDetails object passed to the auth callback' do
-            it 'rejects a TokenDetails object with an incompatible client_id and raises an exception' do
+            it 'rejects a TokenDetails object with an incompatible client_id and fails with an exception' do
               client.connection.once(:connected) do
-                client.auth.authorise({}, force: true)
-                client.connection.on(:error) do |error|
-                  expect(error).to be_a(Ably::Exceptions::IncompatibleClientId)
+                client.auth.authorize({})
+                client.connection.on(:failed) do |state_change|
+                  expect(state_change.reason).to be_a(Ably::Exceptions::IncompatibleClientId)
+                  expect(state_change.reason.code).to eql(40012)
                   EventMachine.add_timer(0.1) do
                     expect(client.connection).to be_failed
                     stop_reactor
@@ -284,7 +300,7 @@ describe Ably::Realtime::Auth, :event_machine do
           end
         end
 
-        context 'with force: true to trigger an authentication upgrade' do
+        context 'when already authenticated with a valid token' do
           let(:rest_client)      { Ably::Rest::Client.new(default_options) }
           let(:client_publisher) { auto_close Ably::Realtime::Client.new(default_options) }
           let(:basic_capability) { JSON.dump("foo" => ["subscribe"]) }
@@ -304,29 +320,268 @@ describe Ably::Realtime::Auth, :event_machine do
           end }
 
           let(:client_options) { default_options.merge(auth_callback: basic_token_cb) }
+          let(:connection) { client.connection }
+
+          context 'when INITIALIZED' do
+            let(:client_options) { default_options.merge(auth_callback: basic_token_cb, auto_connect: false) }
+
+            it 'obtains a token and connects to Ably (#RTC8c, #RTC8b1)' do
+              has_connected = false
+              EventMachine.add_timer(0.2) do
+                expect(client.connection).to be_initialized
+                connection.once(:connected) do
+                  expect(client.auth.client_id).to_not be_nil
+                  has_connected = true
+                end
+                client.auth.authorize(nil, auth_callback: identified_token_cb) do |token|
+                  expect(token.client_id).to eql('bob')
+                  EventMachine.add_timer(0.25) do
+                    expect(has_connected).to be_truthy
+                    stop_reactor
+                  end
+                end
+              end
+            end
+          end
 
-          it 'forces the connection to disconnect and reconnect with a new token when in the CONNECTED state' do
-            client.connection.once(:connected) do
-              existing_token = client.auth.current_token_details
-              client.auth.authorise(nil, force: true)
-              client.connection.once(:disconnected) do
+          context 'when CONNECTING' do
+            let(:client_options) { default_options.merge(auth_callback: basic_token_cb) }
+
+            it 'aborts the current connection process, obtains a token, and connects to Ably again (#RTC8b)' do
+              connected_count = 0
+              connection.once(:connecting) do
+                connection.once(:connected) { connected_count += 1 }
+
+                client.auth.authorize(nil, auth_callback: identified_token_cb) do |token|
+                  expect(token.client_id).to eql('bob')
+                  EventMachine.add_timer(0.25) do
+                    expect(connected_count).to eql(1)
+                    stop_reactor
+                  end
+                end
+              end
+            end
+          end
+
+          context 'when FAILED' do
+            let(:client_options) { default_options.merge(token: 'this.token:is.invalid', log_level: :none) }
+
+            it 'obtains a token and connects to Ably (#RTC8c, #RTC8b1)' do
+              has_connected = false
+              connection.once(:failed) do
                 client.connection.once(:connected) do
-                  expect(existing_token).to_not eql(client.auth.current_token_details)
-                  stop_reactor
+                  has_connected = true
+                end
+                client.auth.authorize(nil, auth_callback: basic_token_cb) do
+                  EventMachine.add_timer(0.25) do
+                    expect(has_connected).to be_truthy
+                    stop_reactor
+                  end
+                end
+              end
+            end
+          end
+
+          context 'when CLOSED' do
+            it 'obtains a token and connects to Ably (#RTC8c, #RTC8b1, #RTC8a3)' do
+              has_connected = false
+              connection.once(:connected) do
+                connection.once(:closed) do
+                  client.connection.once(:connected) do
+                    has_connected = true
+                  end
+                  client.auth.authorize(nil, auth_callback: basic_token_cb) do
+                    EventMachine.add_timer(0.25) do
+                      expect(has_connected).to be_truthy
+                      stop_reactor
+                    end
+                  end
                 end
+                connection.close
               end
             end
           end
 
-          it 'forces the connection to disconnect and reconnect with a new token when in the CONNECTING state' do
-            client.connection.once(:connecting) do
-              existing_token = client.auth.current_token_details
-              client.auth.authorise(nil, force: true)
-              client.connection.once(:disconnected) do
+          context 'when in the CONNECTED state' do
+            context 'with a valid token in the AUTH ProtocolMessage sent' do
+              let(:client_options) { default_options.merge(use_token_auth: true) }
+
+              it 'obtains a new token (that upgrades from anonymous to identified) and upgrades the connection after receiving an updated CONNECTED ProtocolMessage (#RTC8a, #RTC8a3)' do
+                skip "This capability to upgrade from anonymous to identified is not yet implemented, see https://github.com/ably/wiki/issues/182"
+
                 client.connection.once(:connected) do
-                  expect(existing_token).to_not eql(client.auth.current_token_details)
-                  stop_reactor
+                  existing_token = client.auth.current_token_details
+                  expect(client.connection.details.client_id).to be_nil
+                  auth_sent = false
+                  has_updated = false
+                  new_connected_message_received = false
+
+                  client.connection.once(:disconnected) { raise "Should not disconnnect during auth process"}
+                  client.connection.once(:update) do
+                    expect(auth_sent).to be_truthy
+                    expect(new_connected_message_received).to be_truthy
+                    expect(existing_token).to_not eql(client.auth.current_token_details)
+                    expect(client.auth.client_id).to_not be_nil
+                    expect(client.connection.details.client_id).to_not be_nil
+                    has_updated = true
+                  end
+
+                  connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                    auth_sent = true if protocol_message.action == :auth
+                  end
+                  connection.__incoming_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                    new_connected_message_received = true if protocol_message.action == :connected
+                  end
+
+                  client.auth.authorize(nil, auth_callback: identified_token_cb) do
+                    EventMachine.add_timer(0.25) do
+                      expect(has_updated).to be_truthy
+                      stop_reactor
+                    end
+                  end
+                end
+              end
+
+              it 'obtains a new token (as anonymous user before & after) and upgrades the connection after receiving an updated CONNECTED ProtocolMessage (#RTC8a, #RTC8a3)' do
+                client.connection.once(:connected) do
+                  existing_token = client.auth.current_token_details
+                  auth_sent = false
+                  has_updated = false
+                  new_connected_message_received = false
+
+                  client.connection.once(:disconnected) { raise "Should not disconnnect during auth process"}
+                  client.connection.once(:update) do
+                    EventMachine.next_tick do
+                      expect(auth_sent).to be_truthy
+                      expect(new_connected_message_received).to be_truthy
+                      expect(existing_token).to_not eql(client.auth.current_token_details)
+                      has_updated = true
+                    end
+                  end
+
+                  connection.__outgoing_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                    auth_sent = true if protocol_message.action == :auth
+                  end
+                  connection.__incoming_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+                    new_connected_message_received = true if protocol_message.action == :connected
+                  end
+
+                  client.auth.authorize do
+                    EventMachine.add_timer(0.25) do
+                      expect(has_updated).to be_truthy
+                      stop_reactor
+                    end
+                  end
+                end
+              end
+            end
+          end
+
+          context 'when DISCONNECTED' do
+            it 'obtains a token, upgrades from anonymous to identified, and connects to Ably immediately (#RTC8c, #RTC8b1)' do
+              skip "This capability to upgrade from anonymous to identified is not yet implemented, see https://github.com/ably/wiki/issues/182"
+
+              disconnected_waiting = false
+              has_connected = false
+
+              connection.once(:connected) do
+                expect(client.auth.client_id).to be_nil
+
+                connection.on(:disconnected) do |connection_state_change|
+                  # Once we detect the connection will remain DISCONNECTED for 15s, then we can call authorize
+                  # else we can't be sure authorize was responsible for the reconnect
+                  if connection_state_change.retry_in > 1
+                    disconnected_waiting = true
+
+                    client.connection.once(:connected) do
+                      expect(client.auth.client_id).to_not be_nil
+                      has_connected = true
+                    end
+
+                    client.auth.authorize(nil, auth_callback: identified_token_cb) do
+                      EventMachine.add_timer(0.25) do
+                        expect(has_connected).to be_truthy
+                        stop_reactor
+                      end
+                    end
+                  end
+                end
+
+                connection.on(:connecting) do
+                  disconnect_transport connection unless disconnected_waiting
+                end
+                disconnect_transport connection
+              end
+            end
+
+            it 'obtains a similar anonymous token and connects to Ably immediately (#RTC8c, #RTC8b1)' do
+              disconnected_waiting = false
+              has_connected = false
+
+              connection.once(:connected) do
+                expect(client.auth.client_id).to be_nil
+
+                connection.on(:disconnected) do |connection_state_change|
+                  # Once we detect the connection will remain DISCONNECTED for 15s, then we can call authorize
+                  # else we can't be sure authorize was responsible for the reconnect
+                  if connection_state_change.retry_in > 1
+                    disconnected_waiting = true
+
+                    client.connection.once(:connected) do
+                      expect(client.auth.client_id).to be_nil
+                      has_connected = true
+                    end
+
+                    client.auth.authorize do
+                      EventMachine.add_timer(0.25) do
+                        expect(has_connected).to be_truthy
+                        stop_reactor
+                      end
+                    end
+                  end
+                end
+
+                connection.on(:connecting) do
+                  disconnect_transport connection unless disconnected_waiting
+                end
+                disconnect_transport connection
+              end
+            end
+          end
+
+          context 'when SUSPENDED' do
+            let(:client_options) do
+              default_options.merge(
+                disconnected_retry_timeout: 0.1,
+                max_connection_state_ttl: 0.3,
+                use_token_auth: true
+              )
+            end
+
+            it 'obtains a token and connects to Ably immediately (#RTC8c, #RTC8b1)' do
+              been_suspended = false
+              has_connected = false
+
+              connection.once(:connected) do
+                connection.on(:suspended) do |connection_state_change|
+                  been_suspended = true
+
+                  client.connection.once(:connected) do
+                    has_connected = true
+                  end
+
+                  client.auth.authorize do
+                    EventMachine.add_timer(0.25) do
+                      expect(has_connected).to be_truthy
+                      stop_reactor
+                    end
+                  end
+                end
+
+                connection.on(:connecting) do
+                  disconnect_transport connection unless been_suspended
                 end
+                disconnect_transport connection
               end
             end
           end
@@ -338,47 +593,100 @@ describe Ably::Realtime::Auth, :event_machine do
               rest_client.auth.create_token_request({ client_id: 'mike', capability: basic_capability })
             end }
 
-            it 'transisitions the connection state to FAILED if the client_id changes' do
+            it 'transitions the connection state to FAILED if the client_id changes (#RSA15c, #RTC8a2)' do
               client.connection.once(:connected) do
-                client.auth.authorise(nil, auth_callback: identified_token_cb, force: true)
+                client.auth.authorize(nil, auth_callback: identified_token_cb)
                 client.connection.once(:failed) do
-                  expect(client.connection.error_reason.message).to match(/incompatible.*client ID/)
+                  expect(client.connection.error_reason.message).to match(/incompatible.*clientId/i)
+                  expect(client.connection.error_reason.code).to eql(40012)
                   stop_reactor
                 end
               end
             end
           end
 
+          context 'when auth fails' do
+            let(:client_options) { default_options.merge(auth_callback: basic_token_cb, log_level: :none) }
+
+            it 'transitions the connection state to the FAILED state (#RSA15c, #RTC8a2, #RTC8a3)' do
+              connection_failed = false
+
+              client.connection.once(:connected) do
+                client.auth.authorize(nil, auth_callback: Proc.new { 'invalid.token:will.cause.failure' }).tap do |deferrable|
+                  deferrable.errback do |error|
+                    EventMachine.add_timer(0.2) do
+                      expect(connection_failed).to eql(true)
+                      expect(error.message).to match(/Invalid accessToken/i)
+                      expect(error.code).to eql(40005)
+                      stop_reactor
+                    end
+                  end
+                  deferrable.callback { raise "Authorize should not succed" }
+                end
+              end
+
+              client.connection.once(:failed) do
+                expect(client.connection.error_reason.message).to match(/Invalid accessToken/i)
+                expect(client.connection.error_reason.code).to eql(40005)
+                connection_failed = true
+              end
+            end
+          end
+
+          context 'when the authCallback fails' do
+            let(:client_options) { default_options.merge(auth_callback: basic_token_cb, log_level: :none) }
+
+            it 'calls the error callback of authorize and leaves the connection intact (#RSA4c3)' do
+              client.connection.once(:connected) do
+                client.auth.authorize(nil, auth_callback: Proc.new { raise 'Exception raised' }).errback do |error|
+                  EventMachine.add_timer(0.2) do
+                    expect(connection).to be_connected
+                    expect(error.message).to match(/Exception raised/i)
+                    stop_reactor
+                  end
+                end
+                client.connection.once(:failed) do
+                  raise "Connection should not fail"
+                end
+              end
+            end
+          end
+
           context 'when upgrading capabilities' do
             let(:client_options) { default_options.merge(auth_callback: basic_token_cb, log_level: :error) }
 
-            it 'is allowed' do
+            it 'is allowed (#RTC8a1)' do
               client.connection.once(:connected) do
+                client.connection.once(:disconnected) { raise 'Upgrade does not require a disconnect' }
+
                 channel = client.channels.get('foo')
                 channel.publish('not-allowed').errback do |error|
                   expect(error.code).to eql(40160)
                   expect(error.message).to match(/permission denied/)
-                  client.auth.authorise(nil, auth_callback: upgraded_token_cb, force: true)
-                  client.connection.once(:connected) do
+
+                  client.auth.authorize(nil, auth_callback: upgraded_token_cb)
+                  client.connection.once(:update) do
                     expect(client.connection.error_reason).to be_nil
-                    channel.subscribe('allowed') do |message|
+                    channel.subscribe('now-allowed') do |message|
                       stop_reactor
                     end
-                    channel.publish 'allowed'
+                    channel.publish 'now-allowed'
                   end
                 end
               end
             end
           end
 
-          context 'when downgrading capabilities' do
+          context 'when downgrading capabilities (#RTC8a1)' do
             let(:client_options) { default_options.merge(auth_callback: basic_token_cb, log_level: :none) }
 
             it 'is allowed and channels are detached' do
               client.connection.once(:connected) do
+                client.connection.once(:disconnected) { raise 'Upgrade does not require a disconnect' }
+
                 channel = client.channels.get('foo')
                 channel.attach do
-                  client.auth.authorise(nil, auth_callback: downgraded_token_cb, force: true)
+                  client.auth.authorize(nil, auth_callback: downgraded_token_cb)
                   channel.once(:failed) do
                     expect(channel.error_reason.code).to eql(40160)
                     expect(channel.error_reason.message).to match(/Channel denied access/)
@@ -389,11 +697,13 @@ describe Ably::Realtime::Auth, :event_machine do
             end
           end
 
-          it 'ensures message delivery continuity whilst upgrading' do
+          it 'ensures message delivery continuity whilst upgrading (#RTC8a1)' do
             received_messages = []
             subscriber_channel = client.channels.get('foo')
             publisher_channel  = client_publisher.channels.get('foo')
             subscriber_channel.attach do
+              client.connection.once(:disconnected) { raise 'Upgrade does not require a disconnect' }
+
               subscriber_channel.subscribe do |message|
                 received_messages << message
               end
@@ -401,86 +711,93 @@ describe Ably::Realtime::Auth, :event_machine do
                 publisher_channel.publish('foo') do
                   EventMachine.add_timer(2) do
                     expect(received_messages.length).to eql(1)
-                    client.auth.authorise(nil, force: true)
-                    client.connection.once(:disconnected) do
-                      publisher_channel.publish('bar') do
-                        expect(received_messages.length).to eql(1)
-                      end
-                    end
-                    client.connection.once(:connected) do
+
+                    client.connection.once(:update) do
                       EventMachine.add_timer(2) do
                         expect(received_messages.length).to eql(2)
                         stop_reactor
                       end
                     end
+
+                    client.auth.authorize(nil)
+
+                    publisher_channel.publish('bar')
                   end
                 end
               end
             end
           end
+        end
+      end
 
-          it 'does not change the connection state if current connection state is closing' do
-            client.connection.once(:connected) do
-              client.connection.once(:closing) do
-                client.auth.authorise(nil, force: true)
-                client.connection.once(:connected) do
-                  raise "Should not reconnect following auth force: true"
-                end
-                EventMachine.add_timer(4) do
-                  expect(client.connection).to be_closed
-                  stop_reactor
-                end
-              end
-              client.connection.close
-            end
+      context '#authorize_async' do
+        it 'returns a token synchronously' do
+          auth.authorize_sync(ttl: custom_ttl, client_id: custom_client_id).tap do |token_details|
+            expect(auth.authorize_sync).to be_a(Ably::Models::TokenDetails)
+            expect(token_details.expires.to_i).to be_within(3).of(Time.now.to_i + custom_ttl)
+            expect(token_details.client_id).to eql(custom_client_id)
+            stop_reactor
           end
+        end
+      end
+    end
 
-          it 'does not change the connection state if current connection state is closed' do
-            client.connection.once(:connected) do
-              client.connection.once(:closed) do
-                client.auth.authorise(nil, force: true)
-                client.connection.once(:connected) do
-                  raise "Should not reconnect following auth force: true"
-                end
-                EventMachine.add_timer(4) do
-                  expect(client.connection).to be_closed
-                  stop_reactor
-                end
-              end
-              client.connection.close
-            end
-          end
+    context 'server initiated AUTH ProtocolMessage' do
+      before do
+        stub_const 'Ably::Models::TokenDetails::TOKEN_EXPIRY_BUFFER', 0 # allow token to be used even if about to expire
+        stub_const 'Ably::Auth::TOKEN_DEFAULTS', Ably::Auth::TOKEN_DEFAULTS.merge(renew_token_buffer: 0) # Ensure tokens issued expire immediately after issue
+      end
 
-          context 'when state is failed' do
-            let(:client_options) { default_options.merge(auth_callback: basic_token_cb, log_level: :none) }
+      context 'when received' do
+        # Ably in all environments other than locla will send AUTH 30 seconds before expiry
+        # We set the TTL to 33s and wait (3s window)
+        # In local env, that window is 5 seconds instead of 30 seconds
+        let(:local_offset) { ENV['ABLY_ENV'] == 'local' ? 25 : 0 }
+        let(:client_options) { default_options.merge(use_token_auth: :true, default_token_params: { ttl: 33 - local_offset }) }
 
-            it 'does not change the connection state' do
-              client.connection.once(:connected) do
-                client.connection.once(:failed) do
-                  client.auth.authorise(nil, force: true)
-                  client.connection.once(:connected) do
-                    raise "Should not reconnect following auth force: true"
-                  end
-                  EventMachine.add_timer(4) do
-                    expect(client.connection).to be_failed
-                    stop_reactor
-                  end
-                end
-                protocol_message = Ably::Models::ProtocolMessage.new(action: Ably::Models::ProtocolMessage::ACTION.Error.to_i)
-                client.connection.__incoming_protocol_msgbus__.publish :protocol_message, protocol_message
-              end
+        it 'should immediately start a new authentication process (#RTN22)' do
+          client.connection.once(:connected) do
+            original_token = auth.current_token_details
+            received_auth = false
+
+            client.connection.__incoming_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+              received_auth = true if protocol_message.action == :auth
+            end
+
+            client.connection.once(:update) do
+              expect(received_auth).to be_truthy
+              expect(original_token).to_not eql(auth.current_token_details)
+              stop_reactor
             end
           end
         end
       end
 
-      context '#authorise_async' do
-        it 'returns a token synchronously' do
-          auth.authorise_sync(ttl: custom_ttl, client_id: custom_client_id).tap do |token_details|
-            expect(auth.authorise_sync).to be_a(Ably::Models::TokenDetails)
-            expect(token_details.expires.to_i).to be_within(3).of(Time.now.to_i + custom_ttl)
-            expect(token_details.client_id).to eql(custom_client_id)
-            stop_reactor
+      context 'when not received' do
+        # Ably in all environments other than production will send AUTH 5 seconds before expiry, so
+        # set TTL to 5s so that the window for Realtime to send has passed
+        let(:client_options) { default_options.merge(use_token_auth: :true, default_token_params: { ttl: 5 }) }
+
+        it 'should expect the connection to be disconnected by the server but should resume automatically (#RTN22a)' do
+          client.connection.once(:connected) do
+            original_token = auth.current_token_details
+            original_conn_id = client.connection.id
+            received_auth = false
+
+            client.connection.__incoming_protocol_msgbus__.subscribe(:protocol_message) do |protocol_message|
+              received_auth = true if protocol_message.action == :auth
+            end
+
+            client.connection.once(:disconnected) do |state_change|
+              expect(state_change.reason.code).to eql(40142)
+
+              client.connection.once(:connected) do
+                expect(received_auth).to be_falsey
+                expect(original_token).to_not eql(auth.current_token_details)
+                expect(original_conn_id).to eql(client.connection.id)
+                stop_reactor
+              end
+            end
           end
         end
       end
@@ -696,5 +1013,47 @@ describe Ably::Realtime::Auth, :event_machine do
         end
       end
     end
+
+    context 'deprecated #authorise' do
+      let(:client_options)  { default_options.merge(key: api_key, logger: custom_logger_object, use_token_auth: true) }
+      let(:custom_logger) do
+        Class.new do
+          def initialize
+            @messages = []
+          end
+
+          [:fatal, :error, :warn, :info, :debug].each do |severity|
+            define_method severity do |message|
+              @messages << [severity, message]
+            end
+          end
+
+          def logs
+            @messages
+          end
+
+          def level
+            1
+          end
+
+          def level=(new_level)
+          end
+        end
+      end
+      let(:custom_logger_object) { custom_logger.new }
+
+      it 'logs a deprecation warning (#RSA10l)' do
+        client.auth.authorise
+        expect(custom_logger_object.logs.find { |severity, message| message.match(/authorise.*deprecated/i)} ).to_not be_nil
+        stop_reactor
+      end
+
+      it 'returns a valid token (#RSA10l)' do
+        client.auth.authorise do |response|
+          expect(response).to be_a(Ably::Models::TokenDetails)
+          stop_reactor
+        end
+      end
+    end
   end
 end