ably-rest 0.8.5 → 0.8.6

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

@@ -106,5 +106,7 @@ module Ably
 
     # When a channel is detached / failed, certain operations are not permitted such as publishing messages
     class ChannelInactive < BaseAblyException; end
+
+    class IncompatibleClientId < BaseAblyException; end
   end
 end

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

@@ -3,9 +3,9 @@ module Ably::Models
   # when a state change occurs
   #
   # @!attribute [r] current
-  #   @return [Connection::STATE] Current connection state
+  #   @return [Connection::STATE] Current channel state
   # @!attribute [r] previous
-  #   @return [Connection::STATE] Previous connection state
+  #   @return [Connection::STATE] Previous channel state
   # @!attribute [r] reason
   #   @return [Ably::Models::ErrorInfo] Object describing the reason for a state change when not initiated by the consumer of the client library
   #
@@ -20,7 +20,6 @@ module Ably::Models
       @hash_object = {
         current: hash_object.fetch(:current),
         previous: hash_object.fetch(:previous),
-        retry_in: hash_object[:retry_in],
         reason: hash_object[:reason],
         protocol_message: hash_object[:protocol_message]
       }

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

@@ -0,0 +1,54 @@
+module Ably::Models
+  # Convert connection details attributes to a {ConnectionDetails} object
+  #
+  # @param attributes (see #initialize)
+  #
+  # @return [ConnectionDetails]
+  def self.ConnectionDetails(attributes)
+    case attributes
+    when ConnectionDetails
+      return attributes
+    else
+      ConnectionDetails.new(attributes || {})
+    end
+  end
+
+  # ConnectionDetails are optionally passed to the client library in the +CONNECTED+ {Ably::Models::ProtocolMessage#connectionDetails} attribute
+  # to inform the client about any constraints it should adhere to and provide additional metadata about the connection.
+  # For example, if a request is made to publish a message that exceeds the +maxMessageSize+, the client library can reject
+  # the message immediately, without communicating with the Ably service
+  #
+  class ConnectionDetails
+    include Ably::Modules::ModelCommon
+
+    # @param attributes [Hash]
+    # @option attributes [String]    :client_id             contains the client ID assigned to the connection
+    # @option attributes [String]    :connection_key        the connection secret key string that is used to resume a connection and its state
+    # @option attributes [Integer]   :max_message_size      maximum individual message size in bytes
+    # @option attributes [Integer]   :max_frame_size        maximum size for a single frame of data sent to Ably. This restriction applies to a {Ably::Models::ProtocolMessage} sent over a realtime connection, or the total body size for a REST request
+    # @option attributes [Integer]   :max_inbound_rate      maximum allowable number of requests per second from a client
+    # @option attributes [Integer]   :connection_state_ttl  duration in seconds that Ably will persist the connection state when a Realtime client is abruptly disconnected
+    #
+    def initialize(attributes = {})
+      @hash_object = IdiomaticRubyWrapper(attributes.clone)
+      hash[:connection_state_ttl] = (hash[:connection_state_ttl].to_f / 1000).round if hash[:connection_state_ttl]
+      hash.freeze
+    end
+
+    %w(client_id connection_key max_message_size max_frame_size max_inbound_rate connection_state_ttl).each do |attribute|
+      define_method attribute do
+        hash[attribute.to_sym]
+      end
+    end
+
+    def has_client_id?
+      hash.has_key?(:client_id)
+    end
+
+    # @!attribute [r] hash
+    # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
+    def hash
+      @hash_object
+    end
+  end
+end

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

@@ -10,12 +10,12 @@ module Ably::Models
   #   @return [ACTION] Protocol Message action {Ably::Modules::Enum} from list of {ACTION}. Returns nil if action is unsupported by protocol
   # @!attribute [r] count
   #   @return [Integer] The count field is used for ACK and NACK actions. See {http://docs.ably.io/client-lib-development-guide/protocol/#message-acknowledgement message acknowledgement protocol}
-  # @!attribute [r] error_info
+  # @!attribute [r] error
   #   @return [ErrorInfo] Contains error information
   # @!attribute [r] channel
   #   @return [String] Channel name for messages
   # @!attribute [r] channel_serial
-  #   @return [String] Contains a serial number for a message on the current channel
+  #   @return [String] Contains a serial number for a message on the current channelƒ
   # @!attribute [r] connection_id
   #   @return [String] Contains a string public identifier for the connection
   # @!attribute [r] connection_key
@@ -88,12 +88,18 @@ module Ably::Models
       @hash_object.freeze
     end
 
-    %w(id channel channel_serial connection_id connection_key).each do |attribute|
+    %w(id channel channel_serial connection_id).each do |attribute|
       define_method attribute do
         hash[attribute.to_sym]
       end
     end
 
+    def connection_key
+      # connection_key in connection details takes precedence over connection_key on the ProtocolMessage
+      # connection_key in the ProtocolMessage will be deprecated in future protocol versions > 0.8
+      connection_details.connection_key || hash[:connection_key]
+    end
+
     def id!
       raise RuntimeError, 'ProtocolMessage #id is nil' unless id
       id
@@ -106,7 +112,7 @@ module Ably::Models
     end
 
     def error
-      @error_info ||= ErrorInfo.new(hash[:error]) if hash[:error]
+      @error ||= ErrorInfo.new(hash[:error]) if hash[:error]
     end
 
     def timestamp
@@ -181,6 +187,10 @@ module Ably::Models
       flags & 1 == 1
     end
 
+    def connection_details
+      @connection_details ||= Ably::Models::ConnectionDetails(hash[:connection_details])
+    end
+
     # Indicates this protocol message will generate an ACK response when sent
     # Examples of protocol messages required ACK include :message and :presence
     def ack_required?

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

@@ -1,8 +1,7 @@
 module Ably::Models
   # Convert token details argument to a {TokenDetails} object
   #
-  # @param attributes [TokenDetails,Hash] A {TokenDetails} object or Hash of token and meta data attributes
-  # @option attributes (see TokenDetails#initialize)
+  # @param attributes (see #initialize)
   #
   # @return [TokenDetails]
   def self.TokenDetails(attributes)
@@ -27,10 +26,6 @@ module Ably::Models
     # For example, if buffer is 10s, the token can no longer be used for new requests 9s before it expires
     TOKEN_EXPIRY_BUFFER = 15
 
-    def initialize(attributes)
-      @hash_object = IdiomaticRubyWrapper(attributes.clone.freeze)
-    end
-
     # @param attributes
     # @option attributes [String]       :token      token used to authenticate requests
     # @option attributes [String]       :key_name   API key name used to create this token
@@ -76,7 +71,7 @@ module Ably::Models
     # @!attribute [r] capability
     # @return [Hash] Capabilities assigned to this token
     def capability
-      JSON.parse(hash.fetch(:capability)) if hash.fetch(:capability)
+      JSON.parse(hash.fetch(:capability)) if hash.has_key?(:capability)
     end
 
     # @!attribute [r] client_id
@@ -94,10 +89,21 @@ module Ably::Models
       expires < Time.now + TOKEN_EXPIRY_BUFFER
     end
 
+    # True if the TokenDetails was created from an opaque string i.e. no metadata exists for this token
+    # @return [Boolean]
+    # @api private
+    def from_token_string?
+      hash.keys == [:token]
+    end
+
     # @!attribute [r] hash
     # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
     def hash
       @hash_object
     end
+
+    def to_s
+      "<TokenDetails token=#{token} client_id=#{client_id} key_name=#{key_name} issued=#{issued} expires=#{expires} capability=#{capability} expired?=#{expired?}>"
+    end
   end
 end

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

@@ -1,8 +1,7 @@
 module Ably::Models
   # Convert token request argument to a {TokenRequest} object
   #
-  # @param attributes [TokenRequest,Hash] A {TokenRequest} object or Hash of attributes to create a new token request
-  # @option attributes (see TokenRequest#initialize)
+  # @param attributes (see #initialize)
   #
   # @return [TokenRequest]
   def self.TokenRequest(attributes)

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

@@ -7,9 +7,10 @@ module Ably
   # Fallback hosts to use when a connection to rest/realtime.ably.io is not possible due to
   # network failures either at the client, between the client and Ably, within an Ably data center, or at the IO domain registrar
   #
-  FALLBACK_HOSTS = %w(A.ably-realtime.com B.ably-realtime.com C.ably-realtime.com D.ably-realtime.com E.ably-realtime.com)
+  FALLBACK_HOSTS = %w(A.ably-realtime.com B.ably-realtime.com C.ably-realtime.com D.ably-realtime.com E.ably-realtime.com).freeze
+
   INTERNET_CHECK = {
     url:     '//internet-up.ably-realtime.com/is-the-internet-up.txt',
     ok_text: 'yes'
-  }
+  }.freeze
 end

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

@@ -50,10 +50,8 @@ module Ably::Modules
     #
     # @api private
     def emit_message(name, payload)
-      raise 'Event name is required' unless name
-
       message_emitter_subscriptions[:all].each { |cb| cb.call(payload) }
-      message_emitter_subscriptions[name].each { |cb| cb.call(payload) }
+      message_emitter_subscriptions[name].each { |cb| cb.call(payload) } if name
     end
 
     private

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

@@ -71,11 +71,11 @@ module Ably::Modules
     # @yield block is called if the state is matched immediately or once when the state is reached
     #
     # @return [void]
-    def once_or_if(target_states, options = {})
+    def once_or_if(target_states, options = {}, &block)
       raise ArgumentError, 'Block required' unless block_given?
 
       if Array(target_states).any? { |target_state| state == target_state }
-        yield
+        safe_yield block
       else
         failure_block   = options.fetch(:else, nil)
         failure_wrapper = nil

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

@@ -37,6 +37,8 @@ module Ably
       include Ably::Modules::AsyncWrapper
 
       def_delegators :auth_sync, :client_id
+      def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
+      def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
       def_delegators :auth_sync, :current_token_details, :token
       def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
       def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
@@ -68,6 +70,10 @@ module Ably
       def authorise(token_params = {}, auth_options = {}, &success_callback)
         async_wrap(success_callback) do
           auth_sync.authorise(token_params, auth_options)
+        end.tap do |deferrable|
+          deferrable.errback do |error|
+            client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
+          end
         end
       end
 

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

@@ -309,9 +309,20 @@ module Ably
 
       # Queue messages and process queue if channel is attached.
       # If channel is not yet attached, attempt to attach it before the message queue is processed.
-      # @returns [Ably::Util::SafeDeferrable]
+      # @return [Ably::Util::SafeDeferrable]
       def queue_messages(raw_messages)
-        messages = Array(raw_messages).map { |msg| create_message(msg) }
+        messages = Array(raw_messages).map do |raw_msg|
+          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)
+            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)
+            end
+          end
+        end
+
         queue.push *messages
 
         if attached?
@@ -340,12 +351,12 @@ module Ably
         Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
           messages.each do |message|
             message.callback do
-              return if failed
+              next if failed
               actual_deliveries += 1
               deferrable.succeed messages if actual_deliveries == expected_deliveries
             end
             message.errback do |error|
-              return if failed
+              next if failed
               failed = true
               deferrable.fail error, message
             end

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

@@ -123,6 +123,8 @@ module Ably::Realtime
       # It is up to Ably to ensure that duplicate messages are not retransmitted on the channel
       # base on the serial numbers
       #
+      # TODO: Move this into the Connection class, it does not belong in a Channel class
+      #
       # @api private
       def resend_pending_message_ack_queue
         connection.__pending_message_ack_queue__.delete_if do |protocol_message|

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

@@ -30,6 +30,10 @@ module Ably
       # (see Ably::Rest::Client#auth)
       attr_reader :auth
 
+      # The underlying connection for this client
+      # @return [Aby::Realtime::Connection]
+      attr_reader :connection
+
       # The {Ably::Rest::Client REST client} instantiated with the same credentials and configuration that is used for all REST operations such as authentication
       # @return [Ably::Rest::Client]
       attr_reader :rest_client
@@ -69,6 +73,9 @@ module Ably
       # @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] :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.
       #
+      # @option options [Integer] :disconnected_retry_timeout  (15 seconds). When the connection enters the DISCONNECTED state, after this delay in milliseconds, if the state is still DISCONNECTED, the client library will attempt to reconnect automatically
+      # @option options [Integer] :suspended_retry_timeout     (30 seconds). When the connection enters the SUSPENDED state, after this delay in milliseconds, if the state is still SUSPENDED, the client library will attempt to reconnect automatically
+      #
       # @return [Ably::Realtime::Client]
       #
       # @example
@@ -82,6 +89,7 @@ module Ably
         @rest_client           = Ably::Rest::Client.new(options)
         @auth                  = Ably::Realtime::Auth.new(self)
         @channels              = Ably::Realtime::Channels.new(self)
+        @connection            = Ably::Realtime::Connection.new(self, options)
         @echo_messages         = @rest_client.options.fetch(:echo_messages, true) == false ? false : true
         @queue_messages        = @rest_client.options.fetch(:queue_messages, true) == false ? false : true
         @custom_realtime_host  = @rest_client.options[:realtime_host] || @rest_client.options[:ws_host]
@@ -142,10 +150,9 @@ module Ably
         endpoint_for_host(custom_realtime_host || [environment, DOMAIN].compact.join('-'))
       end
 
-      # @!attribute [r] connection
-      # @return [Aby::Realtime::Connection] The underlying connection for this client
+
       def connection
-        @connection ||= Connection.new(self)
+        @connection
       end
 
       # (see Ably::Rest::Client#register_encoder)

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

@@ -73,7 +73,7 @@ module Ably::Realtime
             elsif connection.connected?
               logger.error "CONNECTED ProtocolMessage should not have been received when the connection is in the CONNECTED state"
             else
-              connection.transition_state_machine :connected, reason: protocol_message.error, protocol_message: protocol_message
+              process_connected_message protocol_message
             end
 
           when ACTION.Disconnect, ACTION.Disconnected
@@ -141,6 +141,16 @@ module Ably::Realtime
         connection.manager.error_received_from_server protocol_message.error
       end
 
+      def process_connected_message(protocol_message)
+        if client.auth.token_client_id_allowed?(protocol_message.connection_details.client_id)
+          client.auth.configure_client_id protocol_message.connection_details.client_id
+          connection.transition_state_machine :connected, reason: protocol_message.error, protocol_message: protocol_message
+        else
+          reason = Ably::Exceptions::IncompatibleClientId.new("Client ID '#{protocol_message.connection_details.client_id}' specified by the server is incompatible with the library's configured client ID '#{client.client_id}'", 400, 40012)
+          connection.transition_state_machine :failed, reason: reason, protocol_message: protocol_message
+        end
+      end
+
       def update_connection_recovery_info(protocol_message)
         connection.update_connection_serial protocol_message.connection_serial if protocol_message.has_connection_serial?
       end

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

@@ -60,6 +60,14 @@ module Ably
       # Expected format for a connection recover key
       RECOVER_REGEX = /^(?<recover>[\w-]+):(?<connection_serial>\-?\w+)$/
 
+      # Defaults for automatic connection recovery and timeouts
+      DEFAULTS = {
+        disconnected_retry_timeout: 15, # when the connection enters the DISCONNECTED state, after this delay in milliseconds, if the state is still DISCONNECTED, the client library will attempt to reconnect automatically
+        suspended_retry_timeout:    30, # when the connection enters the SUSPENDED state, after this delay in milliseconds, if the state is still SUSPENDED, the client library will attempt to reconnect automatically
+        connection_state_ttl:       60, # the duration that Ably will persist the connection state when a Realtime client is abruptly disconnected
+        realtime_request_timeout:   10  # default timeout when establishing a connection, or sending a HEARTBEAT, CONNECT, ATTACH, DETACH or CLOSE ProtocolMessage
+      }.freeze
+
       # A unique public identifier for this connection, used to identify this member in presence events and messages
       # @return [String]
       attr_reader :id
@@ -90,23 +98,35 @@ module Ably
       # @api private
       attr_reader :manager
 
-      # An internal queue used to manage unsent outgoing messages.  You should never interface with this array directly
+      # An internal queue used to manage unsent outgoing messages. You should never interface with this array directly
       # @return [Array]
       # @api private
       attr_reader :__outgoing_message_queue__
 
-      # An internal queue used to manage sent messages.  You should never interface with this array directly
+      # An internal queue used to manage sent messages. You should never interface with this array directly
       # @return [Array]
       # @api private
       attr_reader :__pending_message_ack_queue__
 
+      # Configured recovery and timeout defaults for this {Connection}.
+      # See the configurable options in {Ably::Realtime::Client#initialize}.
+      # The defaults are immutable
+      # @return [Hash]
+      attr_reader :defaults
+
       # @api public
-      def initialize(client)
+      def initialize(client, options)
         @client                        = client
         @client_serial                 = -1
         @__outgoing_message_queue__    = []
         @__pending_message_ack_queue__ = []
 
+        @defaults = DEFAULTS.dup
+        options.each do |key, val|
+          @defaults[key] = val if DEFAULTS.has_key?(key)
+        end if options.kind_of?(Hash)
+        @defaults.freeze
+
         Client::IncomingMessageDispatcher.new client, self
         Client::OutgoingMessageDispatcher.new client, self
 
@@ -133,6 +153,11 @@ module Ably
 
       # Causes the library to attempt connection.  If it was previously explicitly
       # closed by the user, or was closed as a result of an unrecoverable error, a new connection will be opened.
+      # Succeeds when connection is established i.e. state is @Connected@
+      # Fails when state becomes either @Closing@, @Closed@ or @Failed@
+      #
+      # Note that if the connection remains in the disconnected ans suspended states indefinitely,
+      # the Deferrable or block provided may never be called
       #
       # @yield block is called as soon as this connection is in the Connected state
       #
@@ -143,14 +168,32 @@ module Ably
           raise exception_for_state_change_to(:connecting) unless can_transition_to?(:connecting)
           transition_state_machine :connecting
         end
-        deferrable_for_state_change_to(STATE.Connected, &success_block)
+
+        Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
+          deferrable.callback do
+            yield if block_given?
+          end
+          succeed_callback = deferrable.method(:succeed)
+          fail_callback    = deferrable.method(:fail)
+
+          once(:connected) do
+            deferrable.succeed
+            off &fail_callback
+          end
+
+          once(:failed, :closed, :closing) do
+            deferrable.fail
+            off &succeed_callback
+          end
+        end
       end
 
       # Sends a ping to Ably and yields the provided block when a heartbeat ping request is echoed from the server.
       # This can be useful for measuring true roundtrip client to Ably server latency for a simple message, or checking that an underlying transport is responding currently.
       # The elapsed milliseconds is passed as an argument to the block and represents the time taken to echo a ping heartbeat once the connection is in the `:connected` state.
       #
-      # @yield [Integer] if a block is passed to this method, then this block will be called once the ping heartbeat is received with the time elapsed in milliseconds
+      # @yield [Integer] if a block is passed to this method, then this block will be called once the ping heartbeat is received with the time elapsed in milliseconds.
+      #                  If the ping is not received within an acceptable timeframe, the block will be called with +nil+ as he first argument
       #
       # @example
       #    client = Ably::Rest::Client.new(key: 'key.id:secret')
@@ -165,9 +208,12 @@ module Ably
         raise RuntimeError, 'Cannot send a ping when connection is in a closed or failed state' if closed? || failed?
 
         started = nil
+        finished = false
 
         wait_for_ping = Proc.new do |protocol_message|
+          next if finished
           if protocol_message.action == Ably::Models::ProtocolMessage::ACTION.Heartbeat
+            finished = true
             __incoming_protocol_msgbus__.unsubscribe(:protocol_message, &wait_for_ping)
             time_passed = (Time.now.to_f * 1000 - started.to_f * 1000).to_i
             safe_yield block, time_passed if block_given?
@@ -175,10 +221,19 @@ module Ably
         end
 
         once_or_if(STATE.Connected) do
+          next if finished
           started = Time.now
           send_protocol_message action: Ably::Models::ProtocolMessage::ACTION.Heartbeat.to_i
           __incoming_protocol_msgbus__.subscribe :protocol_message, &wait_for_ping
         end
+
+        EventMachine.add_timer(defaults.fetch(:realtime_request_timeout)) do
+          next if finished
+          finished = true
+          __incoming_protocol_msgbus__.unsubscribe(:protocol_message, &wait_for_ping)
+          logger.warn "Ping timed out after #{defaults.fetch(:realtime_request_timeout)}s"
+          safe_yield block, nil if block_given?
+        end
       end
 
       # @yield [Boolean] True if an internet connection check appears to be up following an HTTP request to a reliable CDN
@@ -327,11 +382,12 @@ module Ably
           client.auth.auth_params.tap do |auth_deferrable|
             auth_deferrable.callback do |auth_params|
               url_params = auth_params.merge(
-                timestamp: as_since_epoch(Time.now),
                 format:    client.protocol,
                 echo:      client.echo_messages
               )
 
+              url_params['clientId'] = client.auth.client_id if client.auth.has_client_id?
+
               if connection_resumable?
                 url_params.merge! resume: key, connection_serial: serial
                 logger.debug "Resuming connection key #{key} with serial #{serial}"