ably 1.0.7 → 1.1.0

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
@@ -162,6 +167,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 +183,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 +293,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

@@ -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
@@ -225,7 +228,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 +259,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 +268,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 +283,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 +292,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

data/lib/ably/realtime/connection/connection_manager.rb

@@ -43,7 +43,7 @@ module Ably::Realtime
         end
 
         unless client.auth.authentication_security_requirements_met?
-          connection.transition_state_machine :failed, reason: Ably::Exceptions::InsecureRequest.new('Cannot use Basic Auth over non-TLS connections', 401, 40103)
+          connection.transition_state_machine :failed, reason: Ably::Exceptions::InsecureRequest.new('Cannot use Basic Auth over non-TLS connections', 401, Ably::Exceptions::Codes::INVALID_USE_OF_BASIC_AUTH_OVER_NONTLS_TRANSPORT)
           return
         end
 
@@ -61,7 +61,7 @@ module Ably::Realtime
 
         logger.debug { "ConnectionManager: Setting up automatic connection timeout timer for #{realtime_request_timeout}s" }
         create_timeout_timer_whilst_in_state(:connecting, realtime_request_timeout) do
-          connection_opening_failed Ably::Exceptions::ConnectionTimeout.new("Connection to Ably timed out after #{realtime_request_timeout}s", nil, 80014)
+          connection_opening_failed Ably::Exceptions::ConnectionTimeout.new("Connection to Ably timed out after #{realtime_request_timeout}s", nil, Ably::Exceptions::Codes::CONNECTION_TIMED_OUT)
         end
       end
 
@@ -72,7 +72,7 @@ module Ably::Realtime
         if error.kind_of?(Ably::Exceptions::BaseAblyException)
           # Authentication errors that indicate the authentication failure is terminal should move to the failed state
           if ([401, 403].include?(error.status) && !RESOLVABLE_ERROR_CODES.fetch(:token_expired).include?(error.code)) ||
-             (error.code == Ably::Exceptions::INVALID_CLIENT_ID)
+             (error.code == Ably::Exceptions::Codes::INVALID_CLIENT_ID)
             connection.transition_state_machine :failed, reason: error
             return
           end
@@ -80,7 +80,7 @@ module Ably::Realtime
 
         logger.warn { "ConnectionManager: Connection to #{connection.current_host}:#{connection.port} failed; #{error.message}" }
         next_state = get_next_retry_state_info
-        connection.transition_state_machine next_state.fetch(:state), retry_in: next_state.fetch(:pause), reason: Ably::Exceptions::ConnectionError.new("Connection failed: #{error.message}", nil, 80000, error)
+        connection.transition_state_machine next_state.fetch(:state), retry_in: next_state.fetch(:pause), reason: Ably::Exceptions::ConnectionError.new("Connection failed: #{error.message}", nil, Ably::Exceptions::Codes::CONNECTION_FAILED, error)
       end
 
       # Called whenever a new connection is made
@@ -319,7 +319,7 @@ module Ably::Realtime
         @liveness_timer = EventMachine::Timer.new(connection.heartbeat_interval + 0.1) do
           if connection.connected? && (connection.time_since_connection_confirmed_alive? >= connection.heartbeat_interval)
             msg = "No activity seen from realtime in #{connection.heartbeat_interval}; assuming connection has dropped";
-            error = Ably::Exceptions::ConnectionTimeout.new(msg, 80003, 408)
+            error = Ably::Exceptions::ConnectionTimeout.new(msg, Ably::Exceptions::Codes::DISCONNECTED, 408)
             connection.transition_state_machine! :disconnected, reason: error
           end
         end
@@ -492,9 +492,9 @@ module Ably::Realtime
             connection.transition_state_machine :closed
           elsif !connection.closed? && !connection.disconnected? && !connection.failed? && !connection.suspended?
             exception = if reason
-              Ably::Exceptions::TransportClosed.new(reason, nil, 80003)
+              Ably::Exceptions::TransportClosed.new(reason, nil, Ably::Exceptions::Codes::DISCONNECTED)
             else
-              Ably::Exceptions::TransportClosed.new('Transport disconnected unexpectedly', nil, 80003)
+              Ably::Exceptions::TransportClosed.new('Transport disconnected unexpectedly', nil, Ably::Exceptions::Codes::DISCONNECTED)
             end
             next_state = get_next_retry_state_info
             connection.transition_state_machine next_state.fetch(:state), retry_in: next_state.fetch(:pause), reason: exception

data/lib/ably/realtime/connection/websocket_transport.rb

@@ -157,7 +157,7 @@ module Ably::Realtime
           logger.debug { "WebsocketTransport: Prot msg recv <=: #{action_name} - #{event_data}" }
 
           if protocol_message.invalid?
-            error = Ably::Exceptions::ProtocolError.new("Invalid Protocol Message received: #{event_data}\nConnection moving to the failed state as the protocol is invalid and unsupported", 400, 80013)
+            error = Ably::Exceptions::ProtocolError.new("Invalid Protocol Message received: #{event_data}\nConnection moving to the failed state as the protocol is invalid and unsupported", 400, Ably::Exceptions::Codes::PROTOCOL_ERROR)
             logger.fatal { "WebsocketTransport: #{error.message}" }
             failed_protocol_message = Ably::Models::ProtocolMessage.new(
               action: Ably::Models::ProtocolMessage::ACTION.Error,

data/lib/ably/realtime/presence.rb

@@ -233,7 +233,7 @@ module Ably::Realtime
           deferrable.fail Ably::Exceptions::InvalidState.new(
             'Presence state is out of sync as channel is SUSPENDED. Presence#get on a SUSPENDED channel is only supported with option wait_for_sync: false',
             nil,
-            91005
+            Ably::Exceptions::Codes::PRESENCE_STATE_IS_OUT_OF_SYNC
           )
         end
         return deferrable
@@ -330,7 +330,7 @@ module Ably::Realtime
     def send_presence_protocol_message(presence_action, client_id, data)
       presence_message = create_presence_message(presence_action, client_id, data)
       unless presence_message.client_id
-        raise Ably::Exceptions::Standard.new('Unable to enter create presence message without a client_id', 400, 91000)
+        raise Ably::Exceptions::Standard.new('Unable to enter create presence message without a client_id', 400, Ably::Exceptions::Codes::UNABLE_TO_ENTER_PRESENCE_CHANNEL_NO_CLIENTID)
       end
 
       protocol_message = {
@@ -437,13 +437,13 @@ module Ably::Realtime
 
     def attach_channel_then(deferrable)
       if channel.detached? || channel.failed?
-        deferrable.fail Ably::Exceptions::InvalidState.new("Operation is not allowed when channel is in #{channel.state}", 400, 91001)
+        deferrable.fail Ably::Exceptions::InvalidState.new("Operation is not allowed when channel is in #{channel.state}", 400, Ably::Exceptions::Codes::UNABLE_TO_ENTER_PRESENCE_CHANNEL_INVALID_CHANNEL_STATE)
       else
         channel.unsafe_once(:attached, :detached, :failed) do |channel_state_change|
           if channel_state_change.current == :attached
             yield
           else
-            deferrable.fail Ably::Exceptions::InvalidState.new("Operation failed as channel transitioned to #{channel_state_change.current}", 400, 91001)
+            deferrable.fail Ably::Exceptions::InvalidState.new("Operation failed as channel transitioned to #{channel_state_change.current}", 400, Ably::Exceptions::Codes::UNABLE_TO_ENTER_PRESENCE_CHANNEL_INVALID_CHANNEL_STATE)
           end
         end
         channel.attach

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

@@ -275,7 +275,7 @@ module Ably::Realtime
             presence_message_client_id = presence_message.client_id || client.auth.client_id
             re_enter_error = Ably::Models::ErrorInfo.new(
               message: "unable to automatically re-enter presence channel for client_id '#{presence_message_client_id}'. Source error code #{error.code} and message '#{error.message}'",
-              code: 91004
+              code: Ably::Exceptions::Codes::UNABLE_TO_AUTOMATICALLY_REENTER_PRESENCE_CHANNEL
             )
             channel.emit :update, Ably::Models::ChannelStateChange.new(
               current: channel.state,
@@ -312,14 +312,14 @@ module Ably::Realtime
         when Ably::Models::PresenceMessage::ACTION.Leave
           remove_presence_member presence_message
         else
-          Ably::Exceptions::ProtocolError.new("Protocol error, unknown presence action #{presence_message.action}", 400, 80013)
+          Ably::Exceptions::ProtocolError.new("Protocol error, unknown presence action #{presence_message.action}", 400, Ably::Exceptions::Codes::PROTOCOL_ERROR)
         end
       end
 
       def ensure_presence_message_is_valid(presence_message)
         return true if presence_message.connection_id
 
-        error = Ably::Exceptions::ProtocolError.new("Protocol error, presence message is missing connectionId", 400, 80013)
+        error = Ably::Exceptions::ProtocolError.new("Protocol error, presence message is missing connectionId", 400, Ably::Exceptions::Codes::PROTOCOL_ERROR)
         logger.error { "PresenceMap: On channel '#{channel.name}' error: #{error}" }
       end