ably-pubsub-core 0.0.1.pre → 2.0.0

data/lib/ably/{realtime → pubsub/realtime}/client/incoming_message_dispatcher.rb

@@ -1,7 +1,7 @@
-module Ably::Realtime
+module Ably::PubSub::Realtime
   class Client
     # IncomingMessageDispatcher is a (private) class that is used to dispatch {Ably::Models::ProtocolMessage} that are
-    # received from Ably via the {Ably::Realtime::Connection}
+    # received from Ably via the {Ably::PubSub::Realtime::Connection}
     class IncomingMessageDispatcher
       ACTION = Ably::Models::ProtocolMessage::ACTION
 
@@ -28,7 +28,7 @@ module Ably::Realtime
       def get_channel(channel_name)
         channels.fetch(channel_name) do
           logger.warn { "Received channel message for non-existent channel" }
-          Ably::Realtime::Models::NilChannel.new
+          Ably::PubSub::Realtime::Models::NilChannel.new
         end
       end
 
@@ -108,7 +108,7 @@ module Ably::Realtime
                 channel.manager.duplicate_attached_received protocol_message
               else
                 if channel.failed?
-                  logger.warn "Ably::Realtime::Client::IncomingMessageDispatcher - Received an ATTACHED protocol message for FAILED channel #{channel.name}. Ignoring ATTACHED message"
+                  logger.warn "Ably::PubSub::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
@@ -178,9 +178,12 @@ module Ably::Realtime
       end
 
       def ack_pending_queue_for_message_serial(ack_protocol_message)
+        res_index = 0
         drop_pending_queue_from_ack(ack_protocol_message) do |protocol_message|
-          ack_messages protocol_message.messages
+          publish_result = ack_protocol_message.res[res_index] if ack_protocol_message.res
+          ack_messages protocol_message.messages, publish_result
           ack_messages protocol_message.presence
+          res_index += 1
         end
       end
 
@@ -191,11 +194,43 @@ module Ably::Realtime
         end
       end
 
-      def ack_messages(messages)
-        messages.each do |message|
+      def ack_messages(messages, publish_result = nil)
+        messages.each_with_index do |message, index|
           logger.debug { "Calling ACK success callbacks for #{message.class.name} - #{message.to_json}" }
-          message.succeed message
+          if publish_result && message.respond_to?(:action) && message.action &&
+             message.action.match_any?(
+               Ably::Models::Message::ACTION.MessageUpdate,
+               Ably::Models::Message::ACTION.MessageDelete,
+               Ably::Models::Message::ACTION.MessageAppend
+             )
+            serials = extract_serials(publish_result)
+            version_serial = serials[index] if serials
+            result = Ably::Models::UpdateDeleteResult.new(version_serial: version_serial)
+            message.succeed result
+          elsif publish_result && message.is_a?(Ably::Models::Message)
+            serials = extract_serials(publish_result)
+            serial = serials ? serials[index] : nil
+            result = Ably::Models::PublishResult.new(serials: [serial])
+            message.succeed result
+          else
+            message.succeed message
+          end
+        end
+      end
+
+      def extract_serials(publish_result)
+        return nil unless publish_result
+
+        if publish_result.is_a?(Hash)
+          publish_result['serials'] || publish_result[:serials]
+        elsif publish_result.respond_to?(:[])
+          publish_result[:serials]
+        else
+          nil
         end
+      rescue StandardError => e
+        logger.warn { "Failed to extract serials from publish_result (#{publish_result.class}): #{e.message}" }
+        nil
       end
 
       def nack_messages(messages, protocol_message)

data/lib/ably/{realtime → pubsub/realtime}/client/outgoing_message_dispatcher.rb

@@ -1,7 +1,7 @@
-module Ably::Realtime
+module Ably::PubSub::Realtime
   class Client
     # OutgoingMessageDispatcher is a (private) class that is used to deliver
-    # outgoing {Ably::Models::ProtocolMessage}s using the {Ably::Realtime::Connection}
+    # outgoing {Ably::Models::ProtocolMessage}s using the {Ably::PubSub::Realtime::Connection}
     # when the connection state is capable of delivering messages
     class OutgoingMessageDispatcher
       include Ably::Modules::EventMachineHelpers

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

@@ -0,0 +1,372 @@
+require 'uri'
+require 'ably/pubsub/realtime/channel/publisher'
+require 'ably/pubsub/realtime/recovery_key_context'
+
+module Ably
+  module PubSub
+    module Realtime
+      # A client that extends the functionality of the {Ably::PubSub::Realtime::Client} and provides additional realtime-specific features.
+      #
+      class Client
+        include Ably::Modules::AsyncWrapper
+        include Ably::PubSub::Realtime::Channel::Publisher
+        include Ably::Modules::Conversions
+
+        extend Forwardable
+        using Ably::Util::AblyExtensions
+
+        # A {Aby::Realtime::Channels} object.
+        #
+        # @spec RTC3, RTS1
+        #
+        # @return [Aby::Realtime::Channels]
+        #
+        attr_reader :channels
+
+        # An {Ably::Auth} object.
+        #
+        # @spec RTC4
+        #
+        # @return [Ably::Auth]
+        #
+        attr_reader :auth
+
+        # A {Aby::Realtime::Connection} object.
+        #
+        # @spec RTC2
+        #
+        # @return [Aby::Realtime::Connection]
+        #
+        attr_reader :connection
+
+        # The {Ably::PubSub::Http::Client REST client} instantiated with the same credentials and configuration that is used for all REST operations such as authentication
+        # @return [Ably::PubSub::Http::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
+        # @return [Boolean]
+        attr_reader :echo_messages
+
+        # If false, this disables the default behaviour whereby the library queues messages on a connection in the disconnected or connecting states. Defaults to true
+        # @return [Boolean]
+        attr_reader :queue_messages
+
+        # 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 :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]
+        attr_reader :recover
+
+        # Additional parameters to be sent in the querystring when initiating a realtime connection
+        # @return [Hash]
+        attr_reader :transport_params
+
+        def_delegators :auth, :client_id, :auth_options
+        def_delegators :@rest_client, :encoders
+        def_delegators :@rest_client, :use_tls?, :protocol, :protocol_binary?
+        def_delegators :@rest_client, :endpoint, :primary_domain, :custom_port, :custom_tls_port
+        def_delegators :@rest_client, :log_level
+        def_delegators :@rest_client, :options
+
+        # Refuses direct construction: the package a client is created from is what declares
+        # the client's side to the platform, and a directly constructed client declares none.
+        # Use {Ably::PubSub::Server.create_realtime_client} from the +ably-pubsub-server+ gem.
+        #
+        # @raise [Ably::Exceptions::DirectConstructionNotSupported] always
+        def self.new(*args, **kwargs, &block)
+          raise Ably::Internal.direct_construction_error(
+            'Ably::PubSub::Realtime::Client.new', 'Ably::PubSub::Server.create_realtime_client(options)'
+          )
+        end
+
+        # Creates a {Ably::PubSub::Realtime::Client Realtime Client} and configures the {Ably::Auth} object for the connection.
+        #
+        # @spec RSC1
+        #
+        # @param (see {Ably::PubSub::Http::Client#initialize})
+        # @option options (see Ably::PubSub::Http::Client#initialize) An options {Hash} object.
+        # @option options [Proc]                    :auth_callback       when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required.
+        #                                                                Whilst the proc is called synchronously, it does not block the EventMachine reactor as it is run in a separate thread.
+        #                                                                The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent
+        # @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] :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 [Hash]    :transport_params   Additional parameters to be sent in the querystring when initiating a realtime connection. Keys are Strings, values are Stringifiable(a value must respond to #to_s)
+        #
+        # @option options [Integer] :channel_retry_timeout       (15 seconds). When a channel becomes SUSPENDED, after this delay in seconds, the channel will automatically attempt to reattach if the connection is CONNECTED
+        # @option options [Integer] :disconnected_retry_timeout  (15 seconds). When the connection enters the DISCONNECTED state, after this delay in seconds, 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 seconds, if the state is still SUSPENDED, the client library will attempt to reconnect automatically
+        # @option options [Boolean] :disable_websocket_heartbeats   WebSocket heartbeats are more efficient than protocol level heartbeats, however they can be disabled for development purposes
+        #
+        # @return [Ably::PubSub::Realtime::Client]
+        #
+        # @example
+        #    # Constructs a client using an Ably API key or token string.
+        #    client = Ably::PubSub::Server.create_realtime_client('key.id:secret')
+        #
+        #    # Constructs a client using an Ably options object.
+        #    client = Ably::PubSub::Server.create_realtime_client(key: 'key.id:secret', client_id: 'john')
+        #
+        # Applications do not call this constructor: {.new} refuses direct construction, and
+        # a per-side package reaches it through {Ably::Internal.create_realtime_client}.
+        #
+        def initialize(options)
+          raise ArgumentError, 'Options Hash is expected' if options.nil?
+
+          options = options.clone
+          if options.kind_of?(String)
+            options = if options.match(Ably::Auth::API_KEY_REGEX)
+              { key: options }
+            else
+              { token: options }
+            end
+          end
+
+          @transport_params      = options.delete(:transport_params).to_h.each_with_object({}) do |(key, value), acc|
+            acc[key.to_s] = value.to_s
+          end
+          @rest_client           = Ably::Internal.create_http_client(options.merge(realtime_client: self))
+          @echo_messages         = rest_client.options.fetch_with_default(:echo_messages, true)
+          @queue_messages        = rest_client.options.fetch_with_default(:queue_messages, true)
+          @auto_connect          = rest_client.options.fetch_with_default(:auto_connect, true)
+          @recover               = rest_client.options.fetch_with_default(:recover, '')
+
+          @auth       = Ably::PubSub::Realtime::Auth.new(self)
+          @channels   = Ably::PubSub::Realtime::Channels.new(self)
+          @connection = Ably::PubSub::Realtime::Connection.new(self, options)
+
+          unless @recover.nil_or_empty?
+            recovery_context = RecoveryKeyContext.from_json(@recover, logger)
+            unless recovery_context.nil?
+              @channels.set_channel_serials recovery_context.channel_serials # RTN16j
+              @connection.set_msg_serial_from_recover = recovery_context.msg_serial  # RTN16f
+            end
+          end
+        end
+
+        # Return a {Ably::PubSub::Realtime::Channel Realtime Channel} for the given name
+        #
+        # @param (see Ably::PubSub::Realtime::Channels#get)
+        # @return (see Ably::PubSub::Realtime::Channels#get)
+        #
+        def channel(name, channel_options = {})
+          channels.get(name, channel_options)
+        end
+
+        # Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access
+        # to a sufficiently well maintained time source and wish to issue Ably {Ably::Models::TokenRequests} with
+        # a more accurate timestamp should use the queryTime property instead of this method.
+        #
+        # @spec RTC6a
+        #
+        # @yield [Time] The time as milliseconds since the Unix epoch.
+        # @return [Ably::Util::SafeDeferrable]
+        #
+        def time(&success_callback)
+          async_wrap(success_callback) do
+            rest_client.time
+          end
+        end
+
+        # Queries the REST /stats API and retrieves your application's usage statistics.
+        # Returns a {Ably::Util::SafeDeferrable} object, containing an array of {Ably::Models::Stats} objects. See the Stats docs.
+        #
+        # @spec RTC5
+        #
+        # @param (see Ably::PubSub::Http::Client#stats)
+        # @option options (see Ably::PubSub::Http::Client#stats)
+        #
+        # @yield [Ably::Models::PaginatedResult<Ably::Models::Stats>] A {Ably::Util::SafeDeferrable} object containing an array of {Ably::Models::Stats} objects.
+        #
+        # @return [Ably::Util::SafeDeferrable]
+        #
+        def stats(options = {}, &success_callback)
+          async_wrap(success_callback) do
+            rest_client.stats(options)
+          end
+        end
+
+        # Calls {Connection#close} and causes the connection to close, entering the closing state.
+        # Once closed, the library will not attempt to re-establish the connection without an explicit call to {Connection#connect}.
+        # @spec RTN12
+        # (see Ably::PubSub::Realtime::Connection#close)
+        def close(&block)
+          connection.close(&block)
+        end
+
+        # Calls {Ably::PubSub::Realtime::Connection#connect} and causes the connection to open, entering the connecting
+        # state. Explicitly calling connect() is unnecessary unless the autoConnect property is disabled.
+        # @spec RTN11
+        # (see Ably::PubSub::Realtime::Connection#connect)
+        def connect(&block)
+          connection.connect(&block)
+        end
+
+        # A {Ably::PubSub::Realtime::Push} object.
+        # @return [Ably::PubSub::Realtime::Push]
+        def push
+          @push ||= Push.new(self)
+        end
+
+        # Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST
+        # API functionality that is either not documented or is not yet included in the public API, without having to
+        # directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support.
+        #
+        # @spec RTC9
+        #
+        # (see {Ably::PubSub::Http::Client#request})
+        # @yield [Ably::Models::HttpPaginatedResponse<>] An Array of Stats
+        #
+        # @return [Ably::Util::SafeDeferrable] An {Ably::Util::SafeDeferrable} response object returned by the HTTP request, containing an empty or JSON-encodable object.
+        def request(method, path, params = {}, body = nil, headers = {}, &callback)
+          async_wrap(callback) do
+            rest_client.request(method, path, params, body, headers, async_blocking_operations: true)
+          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::PubSub::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::PubSub::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] uri
+        # @return [URI::Generic] Ably WebSocket URI for the {#primary_domain}, shared with REST requests (RTN2)
+        def uri
+          uri_for_host(primary_domain)
+        end
+
+        # (see Ably::PubSub::Http::Client#register_encoder)
+        def register_encoder(encoder)
+          rest_client.register_encoder encoder
+        end
+
+        # (see Ably::PubSub::Http::Client#fallback_hosts)
+        def fallback_hosts
+          rest_client.fallback_hosts
+        end
+
+        # (see Ably::PubSub::Http::Client#logger)
+        def logger
+          @logger ||= Ably::Logger.new(self, log_level, rest_client.logger.custom_logger)
+        end
+
+        # Disable connection recovery, typically used after a connection has been recovered
+        # @return [void]
+        # @api private
+        def disable_automatic_connection_recovery
+          @recover = nil
+        end
+
+        # @!attribute [r] fallback_endpoint
+        # @return [URI::Generic] Fallback endpoint used to connect to the realtime Ably service. Note, after each connection attempt, a new random {Ably::FALLBACK_HOSTS fallback host} or provided fallback hosts are used
+        # @api private
+        def fallback_endpoint
+          unless defined?(@fallback_endpoints) && @fallback_endpoints
+            @fallback_endpoints = fallback_hosts.shuffle.map { |fallback_host| uri_for_host(fallback_host) }
+            @fallback_endpoints << uri # Try the original host last if all fallbacks have been used
+          end
+
+          fallback_endpoint_index = connection.manager.retry_count_for_state(:disconnected) + connection.manager.retry_count_for_state(:suspended) - 1
+
+          @fallback_endpoints[fallback_endpoint_index % @fallback_endpoints.count]
+        end
+
+        # Retrieves a {Ably::Models::LocalDevice} object that represents the current state of the device as a target for push notifications.
+        # @spec RSH8
+        # @return [Ably::Models::LocalDevice] A {Ably::Models::LocalDevice} object.
+        #
+        # @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 uri_for_host(host)
+          port = if use_tls?
+            custom_tls_port
+          else
+            custom_port
+          end
+
+          raise ArgumentError, "Custom port must be an Integer or nil" if port && !port.kind_of?(Integer)
+
+          options = {
+            scheme: use_tls? ? 'wss' : 'ws',
+            host:   host
+          }
+          options.merge!(port: port) if port
+
+          URI::Generic.build(options)
+        end
+      end
+    end
+  end
+end

data/lib/ably/{realtime → pubsub/realtime}/connection/connection_manager.rb

@@ -1,6 +1,6 @@
-require 'ably/rest/middleware/exceptions'
+require 'ably/pubsub/http/middleware/exceptions'
 
-module Ably::Realtime
+module Ably::PubSub::Realtime
   class Connection
     # ConnectionManager is responsible for all actions relating to underlying connection and transports,
     # such as opening, closing, attempting reconnects etc.
@@ -35,9 +35,9 @@ module Ably::Realtime
         end
       end
 
-      # Creates and sets up a new {Ably::Realtime::Connection::WebsocketTransport} available on attribute #transport
+      # Creates and sets up a new {Ably::PubSub::Realtime::Connection::WebsocketTransport} available on attribute #transport
       #
-      # @yield [Ably::Realtime::Connection::WebsocketTransport] block is called with new websocket transport
+      # @yield [Ably::PubSub::Realtime::Connection::WebsocketTransport] block is called with new websocket transport
       # @api private
       def setup_transport
         if transport && !transport.ready_for_release?
@@ -151,7 +151,7 @@ module Ably::Realtime
         state_change = Ably::Models::ConnectionStateChange.new(
           current: connection.state,
           previous: connection.state,
-          event: Ably::Realtime::Connection::EVENT(:update),
+          event: Ably::PubSub::Realtime::Connection::EVENT(:update),
           reason: protocol_message.error,
           protocol_message: protocol_message
         )
@@ -175,7 +175,7 @@ module Ably::Realtime
         setup_transport
       end
 
-      # Reconnect the {Ably::Realtime::Connection::WebsocketTransport} if possible, otherwise set up a new transport
+      # Reconnect the {Ably::PubSub::Realtime::Connection::WebsocketTransport} if possible, otherwise set up a new transport
       #
       # @api private
       def reconnect_transport

data/lib/ably/{realtime → pubsub/realtime}/connection/connection_state_machine.rb

@@ -1,8 +1,8 @@
 require 'ably/modules/state_machine'
 
-module Ably::Realtime
+module Ably::PubSub::Realtime
   class Connection
-    # Internal class to manage connection state, recovery and state transitions for {Ably::Realtime::Connection}
+    # Internal class to manage connection state, recovery and state transitions for {Ably::PubSub::Realtime::Connection}
     class ConnectionStateMachine
       include Ably::Modules::StateMachine
 

data/lib/ably/{realtime → pubsub/realtime}/connection/websocket_transport.rb

@@ -1,6 +1,6 @@
 require 'openssl'
 
-module Ably::Realtime
+module Ably::PubSub::Realtime
   class Connection
     # EventMachine WebSocket transport
     # @api private