ably-rest 0.8.1 → 0.8.2

data/lib/submodules/ably-ruby/ably.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'faraday', '~> 0.9'
   spec.add_runtime_dependency 'json'
   spec.add_runtime_dependency 'websocket-driver', '~> 0.3'
-  spec.add_runtime_dependency 'msgpack-ably', '~> 0.5.10'
+  spec.add_runtime_dependency 'msgpack', '0.6.0pre1'
 
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'rake'

data/lib/submodules/ably-ruby/lib/ably.rb

@@ -1,5 +1,5 @@
 %w(modules util).each do |namespace|
-  Dir.glob(File.expand_path("ably/#{namespace}/*.rb", File.dirname(__FILE__))).each do |file|
+  Dir.glob(File.expand_path("ably/#{namespace}/*.rb", File.dirname(__FILE__))).sort.each do |file|
     require file
   end
 end

data/lib/submodules/ably-ruby/lib/ably/exceptions.rb

@@ -60,7 +60,7 @@ module Ably
     # The HTTP request has returned a 500 error
     class ServerError < BaseAblyException; end
 
-    # PaginatedResource cannot retrieve the page
+    # PaginatedResult cannot retrieve the page
     class InvalidPageError < BaseAblyException; end
 
     # The expected response from the server was invalid
@@ -74,5 +74,8 @@ module Ably
 
     # The message could not be delivered to the server
     class MessageDeliveryError < BaseAblyException; end
+
+    # The data payload type is not supported
+    class UnsupportedDataTypeError < BaseAblyException; end
   end
 end

data/lib/submodules/ably-ruby/lib/ably/models/{paginated_resource.rb → paginated_result.rb}

@@ -6,10 +6,10 @@ module Ably::Models
   #
   # Paging information is provided by Ably in the LINK HTTP headers
   #
-  class PaginatedResource
+  class PaginatedResult
     include Ably::Modules::AsyncWrapper if defined?(Ably::Realtime)
 
-    # The items contained within this {PaginatedResource}
+    # The items contained within this {PaginatedResult}
     # @return [Array]
     attr_reader :items
 
@@ -17,11 +17,11 @@ module Ably::Models
     # @param [String] base_url Base URL for request that generated the http_response so that subsequent paged requests can be made
     # @param [Client] client {Ably::Client} used to make the request to Ably
     # @param [Hash] options Options for this paged resource
-    # @option options [Symbol,String] :coerce_into symbol or string representing class that should be used to create each item in the PaginatedResource
+    # @option options [Symbol,String] :coerce_into symbol or string representing class that should be used to create each item in the PaginatedResult
     #
     # @yield [Object] block will be called for each resource object for the current page.  This is a useful way to apply a transformation to any page resources after they are retrieved
     #
-    # @return [PaginatedResource]
+    # @return [PaginatedResult]
     def initialize(http_response, base_url, client, options = {}, &each_block)
       @http_response = http_response
       @client        = client
@@ -40,11 +40,11 @@ module Ably::Models
     # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object,
     #   and allows an optional success callback block to be provided.
     #
-    # @return [PaginatedResource,Ably::Util::SafeDeferrable]
+    # @return [PaginatedResult,Ably::Util::SafeDeferrable]
     def first(&success_callback)
       async_wrap_if_realtime(success_callback) do
         return nil unless supports_pagination?
-        PaginatedResource.new(client.get(pagination_url('first')), base_url, client, pagination_options, &each_block)
+        PaginatedResult.new(client.get(pagination_url('first')), base_url, client, pagination_options, &each_block)
       end
     end
 
@@ -52,11 +52,11 @@ module Ably::Models
     # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object,
     #   and allows an optional success callback block to be provided.
     #
-    # @return [PaginatedResource,Ably::Util::SafeDeferrable]
+    # @return [PaginatedResult,Ably::Util::SafeDeferrable]
     def next(&success_callback)
       async_wrap_if_realtime(success_callback) do
         return nil unless has_next?
-        PaginatedResource.new(client.get(pagination_url('next')), base_url, client, pagination_options, &each_block)
+        PaginatedResult.new(client.get(pagination_url('next')), base_url, client, pagination_options, &each_block)
       end
     end
 

data/lib/submodules/ably-ruby/lib/ably/models/presence_message.rb

@@ -20,7 +20,7 @@ module Ably::Models
   # via the Ably Realtime service.
   #
   # @!attribute [r] action
-  #   @return [STATE] the state change event signified by a PresenceMessage
+  #   @return [ACTION] the state change event signified by a PresenceMessage
   # @!attribute [r] client_id
   #   @return [String] The client_id associated with this presence state
   # @!attribute [r] connection_id

data/lib/submodules/ably-ruby/lib/ably/modules/conversions.rb

@@ -96,5 +96,20 @@ module Ably::Modules
     rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError => e
       raise ArgumentError, "#{field_name} could not be converted to UTF-8: #{e.message}"
     end
+
+    # Ensures that the payload is a type supported by all Ably client libraries.
+    # Ably guarantees interoperability between client libraries and subsequently
+    # client libraries must reject unsupported types
+    #
+    # @return <void>
+    #
+    def ensure_supported_payload(payload)
+      return if payload.kind_of?(String) ||
+        payload.kind_of?(Hash) ||
+        payload.kind_of?(Array) ||
+        payload.nil?
+
+      raise Ably::Exceptions::UnsupportedDataTypeError.new('Invalid data payload', 400, 40011)
+    end
   end
 end

data/lib/submodules/ably-ruby/lib/ably/modules/encodeable.rb

@@ -58,9 +58,9 @@ module Ably::Modules
 
       set_hash_object message_hash
     rescue Ably::Exceptions::CipherError => cipher_error
-      if channel.respond_to?(:trigger)
+      if channel.respond_to?(:emit)
         channel.client.logger.error "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"
-        channel.trigger :error, cipher_error
+        channel.emit :error, cipher_error
       else
         raise cipher_error
       end

data/lib/submodules/ably-ruby/lib/ably/modules/event_emitter.rb

@@ -2,7 +2,7 @@ require 'ably/modules/safe_yield'
 
 module Ably
   module Modules
-    # EventEmitter provides methods to attach to public events and trigger events on any class instance
+    # EventEmitter provides methods to attach to public events and emit events on any class instance
     #
     # EventEmitter are typically used for public interfaces, and as such, may be overriden in
     # the classes to enforce `event` names match expected values.
@@ -16,7 +16,7 @@ module Ably
     #
     #   event_emitter = Example.new
     #   event_emitter.on(:signal) { |name| puts "Signal #{name} received" }
-    #   event_emitter.trigger :signal, "Test"
+    #   event_emitter.emit :signal, "Test"
     #   #=> "Signal Test received"
     #
     module EventEmitter
@@ -84,15 +84,15 @@ module Ably
         end
       end
 
-      # Trigger an event with event_name that will in turn call all matching callbacks setup with `on`
-      def trigger(event_name, *args)
+      # Emit an event with event_name that will in turn call all matching callbacks setup with `on`
+      def emit(event_name, *args)
         callbacks[callbacks_event_coerced(event_name)].
           clone.
           select do |proc_hash|
             if proc_hash[:unsafe]
-              proc_hash[:trigger_proc].call *args
+              proc_hash[:emit_proc].call *args
             else
-              safe_yield proc_hash[:trigger_proc], *args
+              safe_yield proc_hash[:emit_proc], *args
             end
           end.each do |callback|
             callbacks[callbacks_event_coerced(event_name)].delete callback
@@ -129,10 +129,10 @@ module Ably
       end
 
       # Create a Hash with a proc that calls the provided block and returns true if option :delete_once_run is set to true.
-      # #trigger automatically deletes any blocks that return true thus allowing a block to be run once
+      # #emit automatically deletes any blocks that return true thus allowing a block to be run once
       def proc_for_block(block, options = {})
         {
-          trigger_proc: Proc.new do |*args|
+          emit_proc: Proc.new do |*args|
             block.call *args
             true if options[:delete_once_run]
           end,

data/lib/submodules/ably-ruby/lib/ably/modules/safe_deferrable.rb

@@ -3,7 +3,7 @@ require 'eventmachine'
 module Ably::Modules
   # SafeDeferrable module provides an EventMachine::Deferrable interface to the object it is included in
   # and is safe to use for for public interfaces of this client library.
-  # Any exceptions raised in the success or failure callbacks is caught and logged to #logger
+  # Any exceptions raised in the success or failure callbacks are caught and logged to #logger
   #
   # An exception in a callback provided by a developer should not break this client library
   # and stop further execution of code.
@@ -18,6 +18,9 @@ module Ably::Modules
     # Specify a block to be executed if and when the Deferrable object receives
     # a status of :succeeded.
     # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#callback-instance_method
+    #
+    # @return [void]
+    #
     def callback(&block)
       super do |*args|
         safe_deferrable_block(*args, &block)
@@ -27,20 +30,29 @@ module Ably::Modules
     # Specify a block to be executed if and when the Deferrable object receives
     # a status of :failed.
     # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#errback-instance_method
+    #
+    # @return [void]
+    #
     def errback(&block)
       super do |*args|
         safe_deferrable_block(*args, &block)
       end
     end
 
-    # Mark the Deferrable as succeeded and trigger all callbacks
+    # Mark the Deferrable as succeeded and trigger all callbacks.
     # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#succeed-instance_method
+    #
+    # @return [void]
+    #
     def succeed(*args)
       super(*args)
     end
 
-    # Mark the Deferrable as failed and trigger all callbacks
+    # Mark the Deferrable as failed and trigger all callbacks.
     # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#fail-instance_method
+    #
+    # @return [void]
+    #
     def fail(*args)
       super(*args)
     end

data/lib/submodules/ably-ruby/lib/ably/modules/state_emitter.rb

@@ -26,7 +26,7 @@ module Ably::Modules
   #   connection.connecting?             # => true
   #   connection.state                   # => STATE.Connecting
   #   connection.state = :invalid        # raises an Exception as only a valid state can be defined
-  #   connection.trigger :invalid        # raises an Exception as only a valid state can be used for EventEmitter
+  #   connection.emit :invalid           # raises an Exception as only a valid state can be used for EventEmitter
   #   connection.change_state :connected # emits :connected event via EventEmitter, returns STATE.Connected
   #   connection.once_or_if(:connected) { puts 'block called once when state is connected or becomes connected' }
   #
@@ -53,7 +53,7 @@ module Ably::Modules
       if state != new_state
         logger.debug("#{self.class}: StateEmitter changed from #{state} => #{new_state}") if respond_to?(:logger, true)
         @state = STATE(new_state)
-        trigger @state, *args
+        emit @state, *args
       end
     end
     alias_method :change_state, :state=

data/lib/submodules/ably-ruby/lib/ably/modules/state_machine.rb

@@ -24,7 +24,7 @@ module Ably::Modules
     def transition_state(state, *args)
       unless result = transition_to(state, *args)
         exception = exception_for_state_change_to(state)
-        object.trigger :error, exception
+        object.emit :error, exception
         logger.fatal "#{self.class}: #{exception.message}"
       end
       result

data/lib/submodules/ably-ruby/lib/ably/realtime/channel.rb

@@ -122,6 +122,7 @@ module Ably
       #
       def publish(name, data, &success_block)
         ensure_utf_8 :name, name
+        ensure_supported_payload data
 
         create_message(name, data).tap do |message|
           message.callback(&success_block) if block_given?
@@ -181,12 +182,9 @@ module Ably
       # presence on the channel and may also be used to obtain presence information
       # and change events for other members of the channel.
       #
-      # When accessing presence, if the channel is not attached, the channel is implicitly attached
-      #
       # @return {Ably::Realtime::Presence}
       #
       def presence
-        attach if initialized?
         @presence
       end
 
@@ -200,7 +198,7 @@ module Ably
       # @option options (see Ably::Rest::Channel#history)
       # @option options [Boolean]  :until_attach  When true, the history request will be limited only to messages published before this channel was attached. Channel must be attached
       #
-      # @yield [Ably::Models::PaginatedResource<Ably::Models::Message>] First {Ably::Models::PaginatedResource page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResource#items #items}.
+      # @yield [Ably::Models::PaginatedResult<Ably::Models::Message>] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}.
       #
       # @return [Ably::Util::SafeDeferrable]
       #

data/lib/submodules/ably-ruby/lib/ably/realtime/channel/channel_manager.rb

@@ -46,7 +46,7 @@ module Ably::Realtime
       # An error has occurred on the channel
       def emit_error(error)
         logger.error "ChannelManager: Channel '#{channel.name}' error: #{error}"
-        channel.trigger :error, error
+        channel.emit :error, error
       end
 
       # Detach a channel as a result of an error

data/lib/submodules/ably-ruby/lib/ably/realtime/client.rb

@@ -44,7 +44,7 @@ module Ably
 
       # When true, as soon as the client library is instantiated it will connect to Ably.  If this attribute is false, a connection must be opened explicitly
       # @return [Boolean]
-      attr_reader :connect_automatically
+      attr_reader :auto_connect
 
       # When a recover option is specified a connection inherits the state of a previous connection that may have existed under a different instance of the Realtime library, please refer to the API documentation for further information on connection state recovery
       # @return [String,Nil]
@@ -62,7 +62,7 @@ module Ably
       # @option options [Boolean] :queue_messages If false, this disables the default behaviour whereby the library queues messages on a connection in the disconnected or connecting states
       # @option options [Boolean] :echo_messages  If false, prevents messages originating from this connection being echoed back on the same connection
       # @option options [String]  :recover        When a recover option is specified a connection inherits the state of a previous connection that may have existed under a different instance of the Realtime library, please refer to the API documentation for further information on connection state recovery
-      # @option options [Boolean] :connect_automatically  By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect.
+      # @option options [Boolean] :auto_connect   By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect.
       #
       # @return [Ably::Realtime::Client]
       #
@@ -79,7 +79,7 @@ module Ably
         @channels              = Ably::Realtime::Channels.new(self)
         @echo_messages         = @rest_client.options.fetch(:echo_messages, true) == false ? false : true
         @custom_realtime_host  = @rest_client.options[:realtime_host] || @rest_client.options[:ws_host]
-        @connect_automatically = @rest_client.options.fetch(:connect_automatically, true) == false ? false : true
+        @auto_connect          = @rest_client.options.fetch(:auto_connect, true) == false ? false : true
         @recover               = @rest_client.options[:recover]
 
         raise ArgumentError, "Recovery key is invalid" if @recover && !@recover.match(Connection::RECOVER_REGEX)
@@ -110,7 +110,7 @@ module Ably
       # @param (see Ably::Rest::Client#stats)
       # @option options (see Ably::Rest::Client#stats)
       #
-      # @yield [Ably::Models::PaginatedResource<Ably::Models::Stats>] An Array of Stats
+      # @yield [Ably::Models::PaginatedResult<Ably::Models::Stats>] An Array of Stats
       #
       # @return [Ably::Util::SafeDeferrable]
       #

data/lib/submodules/ably-ruby/lib/ably/realtime/client/incoming_message_dispatcher.rb

@@ -49,7 +49,7 @@ module Ably::Realtime
               connection
             end
             error_message = "Protocol error, duplicate message received for serial #{protocol_message.connection_serial}"
-            error_target.trigger :error, Ably::Exceptions::ProtocolError.new(error_message, 400, 80013)
+            error_target.emit :error, Ably::Exceptions::ProtocolError.new(error_message, 400, 80013)
             logger.error error_message
             return
           end
@@ -117,7 +117,7 @@ module Ably::Realtime
 
           else
             error = Ably::Exceptions::ProtocolError.new("Protocol Message Action #{protocol_message.action} is unsupported by this MessageDispatcher", 400, 80013)
-            client.connection.trigger :error, error
+            client.connection.emit :error, error
             logger.fatal error.message
         end
       end

data/lib/submodules/ably-ruby/lib/ably/realtime/connection.rb

@@ -200,7 +200,7 @@ module Ably
       end
 
       # @!attribute [r] recovery_key
-      #   @return [String] recovery key that can be used by another client to recover this connection with the :recover option
+      # @return [String] recovery key that can be used by another client to recover this connection with the :recover option
       def recovery_key
         "#{key}:#{serial}" if connection_resumable?
       end
@@ -370,7 +370,7 @@ module Ably
         @error_reason = nil
       end
 
-      # Triggers registered callbacks for a successful connection resume event
+      # Executes registered callbacks for a successful connection resume event
       # @api private
       def resumed
         resume_callbacks.each(&:call)

data/lib/submodules/ably-ruby/lib/ably/realtime/connection/connection_manager.rb

@@ -39,7 +39,7 @@ module Ably::Realtime
 
         EventMachine.next_tick do
           # Connect once Connection object is initialised
-          connection.connect if client.connect_automatically
+          connection.connect if client.auto_connect
         end
       end
 
@@ -144,7 +144,7 @@ module Ably::Realtime
       def fail(error)
         connection.logger.fatal "ConnectionManager: Connection failed - #{error}"
         connection.manager.destroy_transport
-        connection.unsafe_once(:failed) { connection.trigger :error, error }
+        connection.unsafe_once(:failed) { connection.emit :error, error }
       end
 
       # When a connection is disconnected whilst connecting, attempt reconnect and/or set state to :suspended or :failed
@@ -178,7 +178,7 @@ module Ably::Realtime
 
         error = current_transition.metadata
         if error.kind_of?(Ably::Models::ErrorInfo) && error.code != RESOLVABLE_ERROR_CODES.fetch(:token_expired)
-          connection.trigger :error, error
+          connection.emit :error, error
           logger.error "ConnectionManager: Error in Disconnected ProtocolMessage received from the server - #{error}"
         end
 

data/lib/submodules/ably-ruby/lib/ably/realtime/connection/connection_state_machine.rb

@@ -48,7 +48,7 @@ module Ably::Realtime
         protocol_message = current_transition.metadata
         if is_error_type?(protocol_message.error)
           connection.logger.warn "ConnectionManager: Connected with error - #{protocol_message.error.message}"
-          connection.trigger :error, protocol_message.error
+          connection.emit :error, protocol_message.error
         end
       end
 

data/lib/submodules/ably-ruby/lib/ably/realtime/connection/websocket_transport.rb

@@ -25,7 +25,7 @@ module Ably::Realtime
       end
 
       # Disconnect the socket transport connection and write all pending text.
-      # If Disconnected state is not automatically triggered, it will be triggered automatically
+      # If Disconnected state is not automatically emitted, it will be emitted automatically
       # @return [void]
       # @api public
       def disconnect
@@ -149,7 +149,7 @@ module Ably::Realtime
 
           if protocol_message.invalid?
             error = Ably::Exceptions::ProtocolError.new("Invalid Protocol Message received: #{event_data}\nMessage has been discarded", 400, 80013)
-            connection.trigger :error, error
+            connection.emit :error, error
             logger.fatal "WebsocketTransport: #{error.message}"
           else
             __incoming_protocol_msgbus__.publish :protocol_message, protocol_message

data/lib/submodules/ably-ruby/lib/ably/realtime/presence.rb

@@ -1,6 +1,7 @@
 module Ably::Realtime
   # Presence provides access to presence operations and state for the associated Channel
   class Presence
+    include Ably::Modules::Conversions
     include Ably::Modules::EventEmitter
     include Ably::Modules::AsyncWrapper
     include Ably::Modules::MessageEmitter
@@ -69,11 +70,16 @@ module Ably::Realtime
     # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks
     #
     def enter(options = {}, &success_block)
-      @client_id = options.fetch(:client_id, client_id)
-      @data      = options.fetch(:data, nil)
+      client_id  = options.fetch(:client_id, self.client_id)
+      data       = options.fetch(:data, nil)
       deferrable = create_deferrable
 
+      ensure_supported_payload data unless data.nil?
       raise Ably::Exceptions::Standard.new('Unable to enter presence channel without a client_id', 400, 91000) unless client_id
+
+      @data = data
+      @client_id = client_id
+
       return deferrable_succeed(deferrable, &success_block) if state == STATE.Entered
 
       ensure_channel_attached(deferrable) do
@@ -113,6 +119,7 @@ module Ably::Realtime
     #
     def enter_client(client_id, options = {}, &success_block)
       raise ArgumentError, 'options must be a Hash' unless options.kind_of?(Hash)
+      ensure_supported_payload options[:data] if options.has_key?(:data)
       raise Ably::Exceptions::Standard.new('Unable to enter presence channel without a client_id', 400, 91000) unless client_id
 
       send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Enter, client_id, options, &success_block)
@@ -128,10 +135,14 @@ module Ably::Realtime
     # @return (see Presence#enter)
     #
     def leave(options = {}, &success_block)
-      @data      = options.fetch(:data, data) # nil value defaults leave data to existing value
+      data       = options.fetch(:data, self.data) # nil value defaults leave data to existing value
       deferrable = create_deferrable
 
+      ensure_supported_payload data unless data.nil?
       raise Ably::Exceptions::Standard.new('Unable to leave presence channel that is not entered', 400, 91002) unless able_to_leave?
+
+      @data = data
+
       return deferrable_succeed(deferrable, &success_block) if state == STATE.Left
 
       ensure_channel_attached(deferrable) do
@@ -165,6 +176,7 @@ module Ably::Realtime
     #
     def leave_client(client_id, options = {}, &success_block)
       raise ArgumentError, 'options must be a Hash' unless options.kind_of?(Hash)
+      ensure_supported_payload options[:data] if options.has_key?(:data)
       raise Ably::Exceptions::Standard.new('Unable to leave presence channel without a client_id', 400, 91000) unless client_id
 
       send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Leave, client_id, options, &success_block)
@@ -181,9 +193,14 @@ module Ably::Realtime
     # @return (see Presence#enter)
     #
     def update(options = {}, &success_block)
-      @data      = options.fetch(:data, nil)
+      data       = options.fetch(:data, nil)
       deferrable = create_deferrable
 
+      ensure_supported_payload data unless data.nil?
+      raise Ably::Exceptions::Standard.new('Unable to update presence channel without a client_id', 400, 91000) unless client_id
+
+      @data = data
+
       ensure_channel_attached(deferrable) do
         send_protocol_message_and_transition_state_to(
           Ably::Models::PresenceMessage::ACTION.Update,
@@ -210,6 +227,7 @@ module Ably::Realtime
     #
     def update_client(client_id, options = {}, &success_block)
       raise ArgumentError, 'options must be a Hash' unless options.kind_of?(Hash)
+      ensure_supported_payload options[:data] if options.has_key?(:data)
       raise Ably::Exceptions::Standard.new('Unable to enter presence channel without a client_id', 400, 91000) unless client_id
 
       send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Update, client_id, options, &success_block)
@@ -274,7 +292,7 @@ module Ably::Realtime
     # @option options (see Ably::Rest::Presence#history)
     # @option options [Boolean]  :until_attach  When true, request for history will be limited only to messages published before the associated channel was attached. The associated channel must be attached.
     #
-    # @yield [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResource page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResource#items #items}.
+    # @yield [Ably::Models::PaginatedResult<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResult page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResult#items #items}.
     #
     # @return [Ably::Util::SafeDeferrable]
     #