ably 1.0.6 → 1.1.3

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

@@ -111,16 +111,12 @@ module Ably::Realtime
         end
       end
 
-      # When a channel becomes detached, suspended or failed,
+      # When a channel becomes suspended or failed,
       # all queued messages should be failed immediately as we don't queue in
       # any of those states
       def fail_queued_messages(error)
         error = Ably::Exceptions::MessageDeliveryFailed.new("Queued messages on channel '#{channel.name}' in state '#{channel.state}' will never be delivered") unless error
         fail_messages_in_queue connection.__outgoing_message_queue__, error
-        channel.__queue__.each do |message|
-          nack_message message, error
-        end
-        channel.__queue__.clear
       end
 
       def fail_messages_in_queue(queue, error)
@@ -214,7 +210,7 @@ module Ably::Realtime
         state_at_time_of_request = channel.state
         @pending_state_change_timer = EventMachine::Timer.new(realtime_request_timeout) do
           if channel.state == state_at_time_of_request
-            error = Ably::Models::ErrorInfo.new(code: 90007, message: "Channel #{new_state} operation failed (timed out)")
+            error = Ably::Models::ErrorInfo.new(code: Ably::Exceptions::Codes::CHANNEL_OPERATION_FAILED_NO_RESPONSE_FROM_SERVER, message: "Channel #{new_state} operation failed (timed out)")
             channel.transition_state_machine state_if_failed, reason: error
           end
         end

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

@@ -25,7 +25,7 @@ module Ably::Realtime
       transition :from => :attached,     :to => [:attaching, :detaching, :detached, :failed, :suspended]
       transition :from => :detaching,    :to => [:detached, :attaching, :attached, :failed, :suspended]
       transition :from => :detached,     :to => [:attaching, :attached, :failed]
-      transition :from => :suspended,    :to => [:attaching, :detached, :failed]
+      transition :from => :suspended,    :to => [:attaching, :attached, :detached, :failed]
       transition :from => :failed,       :to => [:attaching]
 
       after_transition do |channel, transition|
@@ -47,7 +47,7 @@ module Ably::Realtime
 
       after_transition(to: [:detached, :failed, :suspended]) do |channel, current_transition|
         err = error_from_state_change(current_transition)
-        channel.manager.fail_queued_messages err
+        channel.manager.fail_queued_messages(err) if channel.failed? or channel.suspended? #RTL11
         channel.manager.log_channel_error err if err
       end
 

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

@@ -0,0 +1,74 @@
+module Ably::Realtime
+  class Channel
+    # Publisher module adds publishing capabilities to the current object
+    module Publisher
+      private
+
+      # Prepare and queue messages on the connection queue immediately
+      # @return [Ably::Util::SafeDeferrable]
+      def enqueue_messages_on_connection(client, raw_messages, channel_name, channel_options = {})
+        messages = Array(raw_messages).map do |raw_msg|
+          create_message(client, raw_msg, channel_options).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')
+            end
+            if message.client_id && !message.client_id.kind_of?(String)
+              raise Ably::Exceptions::IncompatibleClientId.new('client_id must be a String when publishing messages')
+            end
+            unless client.auth.can_assume_client_id?(message.client_id)
+              raise Ably::Exceptions::IncompatibleClientId.new("Cannot publish with client_id '#{message.client_id}' as it is incompatible with the current configured client_id '#{client.client_id}'")
+            end
+          end
+        end
+
+        connection.send_protocol_message(
+          action:   Ably::Models::ProtocolMessage::ACTION.Message.to_i,
+          channel:  channel_name,
+          messages: messages
+        )
+
+        if messages.count == 1
+          # A message is a Deferrable so, if publishing only one message, simply return that Deferrable
+          messages.first
+        else
+          deferrable_for_multiple_messages(messages)
+        end
+      end
+
+      # A deferrable object that calls the success callback once all messages are delivered
+      # If any message fails, the errback is called immediately
+      # Only one callback or errback is ever called i.e. if a group of messages all fail, only once
+      # errback will be invoked
+      def deferrable_for_multiple_messages(messages)
+        expected_deliveries = messages.count
+        actual_deliveries = 0
+        failed = false
+
+        Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
+          messages.each do |message|
+            message.callback do
+              next if failed
+              actual_deliveries += 1
+              deferrable.succeed messages if actual_deliveries == expected_deliveries
+            end
+            message.errback do |error|
+              next if failed
+              failed = true
+              deferrable.fail error, message
+            end
+          end
+        end
+      end
+
+      def create_message(client, message, channel_options)
+        Ably::Models::Message(message.dup).tap do |msg|
+          msg.encode(client.encoders, channel_options) do |encode_error, error_message|
+            client.logger.error error_message
+          end
+        end
+      end
+    end
+  end
+end
+

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

@@ -0,0 +1,62 @@
+module Ably::Realtime
+  class Channel
+    # A push channel used for push notifications
+    # Each PushChannel maps to exactly one Realtime Channel
+    #
+    # @!attribute [r] channel
+    #   @return [Ably::Realtime::Channel] Underlying channel object
+    #
+    class PushChannel
+      attr_reader :channel
+
+      def initialize(channel)
+        raise ArgumentError, "Unsupported channel type '#{channel.class}'" unless channel.kind_of?(Ably::Realtime::Channel)
+        @channel = channel
+      end
+
+      def to_s
+        "<PushChannel: name=#{channel.name}>"
+      end
+
+      # Subscribe local device for push notifications on this channel
+      #
+      # @note This is unsupported in the Ruby library
+      def subscribe_device(*args)
+        raise_unsupported
+      end
+
+      # Subscribe all devices registered to this client's authenticated client_id for push notifications on this channel
+      #
+      # @note This is unsupported in the Ruby library
+      def subscribe_client_id(*args)
+        raise_unsupported
+      end
+
+      # Unsubscribe local device for push notifications on this channel
+      #
+      # @note This is unsupported in the Ruby library
+      def unsubscribe_device(*args)
+        raise_unsupported
+      end
+
+      # Unsubscribe all devices registered to this client's authenticated client_id for push notifications on this channel
+      #
+      # @note This is unsupported in the Ruby library
+      def unsubscribe_client_id(*args)
+        raise_unsupported
+      end
+
+      # Get list of subscriptions on this channel for this device or authenticate client_id
+      #
+      # @note This is unsupported in the Ruby library
+      def get_subscriptions(*args)
+        raise_unsupported
+      end
+
+      private
+      def raise_unsupported
+        raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. All PushChannel methods are unavailable'
+      end
+    end
+  end
+end

data/lib/ably/realtime/client.rb

@@ -1,4 +1,5 @@
 require 'uri'
+require 'ably/realtime/channel/publisher'
 
 module Ably
   module Realtime
@@ -21,6 +22,9 @@ module Ably
     #
     class Client
       include Ably::Modules::AsyncWrapper
+      include Ably::Realtime::Channel::Publisher
+      include Ably::Modules::Conversions
+
       extend Forwardable
 
       DOMAIN = 'realtime.ably.io'
@@ -38,6 +42,7 @@ module Ably
 
       # 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]
+      # @private
       attr_reader :rest_client
 
       # When false the client suppresses messages originating from this connection being echoed back on the same connection. Defaults to true
@@ -105,9 +110,6 @@ module Ably
         end
 
         @rest_client           = Ably::Rest::Client.new(options.merge(realtime_client: self))
-        @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]
@@ -115,6 +117,10 @@ module Ably
         @recover               = rest_client.options[:recover]
 
         raise ArgumentError, "Recovery key '#{recover}' is invalid" if recover && !recover.match(Connection::RECOVER_REGEX)
+
+        @auth       = Ably::Realtime::Auth.new(self)
+        @channels   = Ably::Realtime::Channels.new(self)
+        @connection = Ably::Realtime::Connection.new(self, options)
       end
 
       # Return a {Ably::Realtime::Channel Realtime Channel} for the given name
@@ -162,6 +168,12 @@ module Ably
         connection.connect(&block)
       end
 
+      # Push notification object for publishing and managing push notifications
+      # @return [Ably::Realtime::Push]
+      def push
+        @push ||= Push.new(self)
+      end
+
       # (see Ably::Rest::Client#request)
       # @yield [Ably::Models::HttpPaginatedResponse<>] An Array of Stats
       #
@@ -172,6 +184,74 @@ module Ably
         end
       end
 
+      # Publish one or more messages to the specified channel.
+      #
+      # This method allows messages to be efficiently published to Ably without instancing a {Ably::Realtime::Channel} object.
+      # If you want to publish a high rate of messages to Ably without instancing channels or using the REST API, then this method
+      # is recommended. However, channel options such as encryption are not supported with this method.  If you need to specify channel options
+      # we recommend you use the {Ably::Realtime::Channel} +publish+ method without attaching to each channel, unless you also want to subscribe
+      # to published messages on that channel.
+      #
+      # Note: This feature is still in beta. As such, we cannot guarantee the API will not change in future.
+      #
+      # @param channel [String]   The channel name you want to publish the message(s) to
+      # @param name [String, Array<Ably::Models::Message|Hash>, nil]   The event name of the message to publish, or an Array of [Ably::Model::Message] objects or [Hash] objects with +:name+ and +:data+ pairs
+      # @param data [String, ByteArray, nil]   The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument
+      # @param attributes [Hash, nil]   Optional additional message attributes such as :client_id or :connection_id, applied when name attribute is nil or a string
+      #
+      # @yield [Ably::Models::Message,Array<Ably::Models::Message>] On success, will call the block with the {Ably::Models::Message} if a single message is published, or an Array of {Ably::Models::Message} when multiple messages are published
+      # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks
+      #
+      # @example
+      #   # Publish a single message
+      #   client.publish 'activityChannel', click', { x: 1, y: 2 }
+      #
+      #   # Publish an array of message Hashes
+      #   messages = [
+      #     { name: 'click', { x: 1, y: 2 } },
+      #     { name: 'click', { x: 2, y: 3 } }
+      #   ]
+      #   client.publish 'activityChannel', messages
+      #
+      #   # Publish an array of Ably::Models::Message objects
+      #   messages = [
+      #     Ably::Models::Message(name: 'click', { x: 1, y: 2 })
+      #     Ably::Models::Message(name: 'click', { x: 2, y: 3 })
+      #   ]
+      #   client.publish 'activityChannel', messages
+      #
+      #   client.publish('activityChannel', 'click', 'body') do |message|
+      #     puts "#{message.name} event received with #{message.data}"
+      #   end
+      #
+      #   client.publish('activityChannel', 'click', 'body').errback do |error, message|
+      #     puts "#{message.name} was not received, error #{error.message}"
+      #   end
+      #
+      def publish(channel_name, name, data = nil, attributes = {}, &success_block)
+        if !connection.can_publish_messages?
+          error = Ably::Exceptions::MessageQueueingDisabled.new("Message cannot be published. Client is not allowed to queue messages when connection is in state #{connection.state}")
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
+        end
+
+        messages = if name.kind_of?(Enumerable)
+          name
+        else
+          name = ensure_utf_8(:name, name, allow_nil: true)
+          ensure_supported_payload data
+          [{ name: name, data: data }.merge(attributes)]
+        end
+
+        if messages.length > Realtime::Connection::MAX_PROTOCOL_MESSAGE_BATCH_SIZE
+          error = Ably::Exceptions::InvalidRequest.new("It is not possible to publish more than #{Realtime::Connection::MAX_PROTOCOL_MESSAGE_BATCH_SIZE} messages with a single publish request.")
+          return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
+        end
+
+        enqueue_messages_on_connection(self, messages, channel_name).tap do |deferrable|
+          deferrable.callback(&success_block) if block_given?
+        end
+      end
+
       # @!attribute [r] endpoint
       # @return [URI::Generic] Default Ably Realtime endpoint used for all requests
       def endpoint
@@ -214,6 +294,14 @@ module Ably
         @fallback_endpoints[fallback_endpoint_index % @fallback_endpoints.count]
       end
 
+      # The local device detilas
+      # @return [Ably::Models::LocalDevice]
+      #
+      # @note This is unsupported in the Ruby library
+      def device
+        raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. The local device object is not unavailable'
+      end
+
       private
       def endpoint_for_host(host)
         port = if use_tls?

data/lib/ably/realtime/client/incoming_message_dispatcher.rb

@@ -102,7 +102,11 @@ module Ably::Realtime
               if channel.attached?
                 channel.manager.duplicate_attached_received protocol_message
               else
-                channel.transition_state_machine :attached, reason: protocol_message.error, resumed: protocol_message.has_channel_resumed_flag?, protocol_message: protocol_message
+                if channel.failed?
+                  logger.warn "Ably::Realtime::Client::IncomingMessageDispatcher - Received an ATTACHED protocol message for FAILED channel #{channel.name}. Ignoring ATTACHED message"
+                else
+                  channel.transition_state_machine :attached, reason: protocol_message.error, resumed: protocol_message.has_channel_resumed_flag?, protocol_message: protocol_message
+                end
               end
             end
 
@@ -132,7 +136,7 @@ module Ably::Realtime
             client.auth.authorize
 
           else
-            error = Ably::Exceptions::ProtocolError.new("Protocol Message Action #{protocol_message.action} is unsupported by this MessageDispatcher", 400, 80013)
+            error = Ably::Exceptions::ProtocolError.new("Protocol Message Action #{protocol_message.action} is unsupported by this MessageDispatcher", 400, Ably::Exceptions::Codes::PROTOCOL_ERROR)
             logger.fatal error.message
         end
       end

data/lib/ably/realtime/client/outgoing_message_dispatcher.rb

@@ -52,7 +52,7 @@ module Ably::Realtime
           protocol_message = outgoing_queue.shift
 
           if (!connection.transport)
-            protocol_message.fail Ably::Exceptions::TransportClosed.new('Transport disconnected unexpectedly', nil, 80003)
+            protocol_message.fail Ably::Exceptions::TransportClosed.new('Transport disconnected unexpectedly', nil, Ably::Exceptions::Codes::DISCONNECTED)
             next
           end
 

data/lib/ably/realtime/connection.rb

@@ -66,7 +66,7 @@ module Ably
       ensure_state_machine_emits 'Ably::Models::ConnectionStateChange'
 
       # Expected format for a connection recover key
-      RECOVER_REGEX = /^(?<recover>[\w!-]+):(?<connection_serial>\-?\w+)$/
+      RECOVER_REGEX = /^(?<recover>[^:]+):(?<connection_serial>[^:]+):(?<msg_serial>\-?\d+)$/
 
       # Defaults for automatic connection recovery and timeouts
       DEFAULTS = {
@@ -79,6 +79,9 @@ module Ably
         websocket_heartbeats_disabled: false,
       }.freeze
 
+      # Max number of messages to bundle in a single ProtocolMessage
+      MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50
+
       # A unique public identifier for this connection, used to identify this member in presence events and messages
       # @return [String]
       attr_reader :id
@@ -134,7 +137,6 @@ module Ably
         @client                        = client
         @__outgoing_message_queue__    = []
         @__pending_message_ack_queue__ = []
-        reset_client_serial
 
         @defaults = DEFAULTS.dup
         options.each do |key, val|
@@ -142,12 +144,25 @@ module Ably
         end if options.kind_of?(Hash)
         @defaults.freeze
 
+        # If a recover client options is provided, then we need to ensure that the msgSerial matches the
+        # recover serial immediately at client library instantiation. This is done immediately so that any queued
+        # publishes use the correct serial number for these queued messages as well.
+        # There is no harm if the msgSerial is higher than expected if the recover fails.
+        recovery_msg_serial = connection_recover_parts && connection_recover_parts[:msg_serial].to_i
+        if recovery_msg_serial
+          @client_msg_serial = recovery_msg_serial
+        else
+          reset_client_msg_serial
+        end
+
         Client::IncomingMessageDispatcher.new client, self
         Client::OutgoingMessageDispatcher.new client, self
 
         @state_machine = ConnectionStateMachine.new(self)
         @state         = STATE(state_machine.current_state)
         @manager       = ConnectionManager.new(self)
+
+        @current_host = client.endpoint.host
       end
 
       # Causes the connection to close, entering the closed state, from any state except
@@ -225,7 +240,7 @@ module Ably
       #
       def ping(&block)
         if initialized? || suspended? || closing? || closed? || failed?
-          error = Ably::Models::ErrorInfo.new(message: "Cannot send a ping when the connection is #{state}", code: 80003)
+          error = Ably::Models::ErrorInfo.new(message: "Cannot send a ping when the connection is #{state}", code: Ably::Exceptions::Codes::DISCONNECTED)
           return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error)
         end
 
@@ -256,7 +271,7 @@ module Ably
           once_or_if([:suspended, :closing, :closed, :failed]) do
             next if finished
             finished = true
-            deferrable.fail Ably::Models::ErrorInfo.new(message: "Ping failed as connection has changed state to #{state}", code: 80003)
+            deferrable.fail Ably::Models::ErrorInfo.new(message: "Ping failed as connection has changed state to #{state}", code: Ably::Exceptions::Codes::DISCONNECTED)
           end
 
           EventMachine.add_timer(defaults.fetch(:realtime_request_timeout)) do
@@ -265,7 +280,7 @@ module Ably
             __incoming_protocol_msgbus__.unsubscribe(:protocol_message, &wait_for_ping)
             error_msg = "Ping timed out after #{defaults.fetch(:realtime_request_timeout)}s"
             logger.warn { error_msg }
-            deferrable.fail Ably::Models::ErrorInfo.new(message: error_msg, code: 50003)
+            deferrable.fail Ably::Models::ErrorInfo.new(message: error_msg, code: Ably::Exceptions::Codes::TIMEOUT_ERROR)
             safe_yield block, nil if block_given?
           end
         end
@@ -280,7 +295,7 @@ module Ably
           EventMachine::HttpRequest.new(url).get.tap do |http|
             http.errback do
               yield false if block_given?
-              deferrable.fail Ably::Exceptions::ConnectionFailed.new("Unable to connect to #{url}", nil, 80000)
+              deferrable.fail Ably::Exceptions::ConnectionFailed.new("Unable to connect to #{url}", nil, Ably::Exceptions::Codes::CONNECTION_FAILED)
             end
             http.callback do
               EventMachine.next_tick do
@@ -289,7 +304,7 @@ module Ably
                 if result
                   deferrable.succeed
                 else
-                  deferrable.fail Ably::Exceptions::ConnectionFailed.new("Unexpected response from #{url} (#{http.response_header.status})", 400, 40000)
+                  deferrable.fail Ably::Exceptions::ConnectionFailed.new("Unexpected response from #{url} (#{http.response_header.status})", 400, Ably::Exceptions::Codes::BAD_REQUEST)
                 end
               end
             end
@@ -300,18 +315,17 @@ module Ably
       # @!attribute [r] recovery_key
       # @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?
+        "#{key}:#{serial}:#{client_msg_serial}" if connection_resumable?
       end
 
       # Following a new connection being made, the connection ID, connection key
-      # and message serial need to match the details provided by the server.
+      # and connection serial need to match the details provided by the server.
       #
       # @return [void]
       # @api private
       def configure_new(connection_id, connection_key, connection_serial)
         @id            = connection_id
         @key           = connection_key
-        @client_serial = connection_serial
 
         update_connection_serial connection_serial
       end
@@ -539,11 +553,11 @@ module Ably
           defaults.fetch(:realtime_request_timeout)
       end
 
-      # Resets the client serial (msgSerial) sent to Ably for each new {Ably::Models::ProtocolMessage}
-      # (see #client_serial)
+      # Resets the client message serial (msgSerial) sent to Ably for each new {Ably::Models::ProtocolMessage}
+      # (see #client_msg_serial)
       # @api private
-      def reset_client_serial
-        @client_serial = -1
+      def reset_client_msg_serial
+        @client_msg_serial = -1
       end
 
       # When a hearbeat or any other message from Ably is received
@@ -565,15 +579,15 @@ module Ably
 
       private
 
-      # The client serial is incremented for every message that is published that requires an ACK.
+      # The client message serial (msgSerial) is incremented for every message that is published that requires an ACK.
       # Note that this is different to the connection serial that contains the last known serial number
       # received from the server.
       #
       # A message serial number does not guarantee a message has been received, only sent.
       # A connection serial guarantees the server has received the message and is thus used for connection recovery and resumes.
       # @return [Integer] starting at -1 indicating no messages sent, 0 when the first message is sent
-      def client_serial
-        @client_serial
+      def client_msg_serial
+        @client_msg_serial
       end
 
       def resume_callbacks
@@ -598,11 +612,11 @@ module Ably
       end
 
       def add_message_serial_to(protocol_message)
-        @client_serial += 1
-        protocol_message[:msgSerial] = client_serial
+        @client_msg_serial += 1
+        protocol_message[:msgSerial] = client_msg_serial
         yield
       rescue StandardError => e
-        @client_serial -= 1
+        @client_msg_serial -= 1
         raise e
       end