ably 1.0.6 → 1.1.3

data/lib/ably/rest.rb

@@ -1,6 +1,7 @@
 require 'ably/rest/channel'
 require 'ably/rest/channels'
 require 'ably/rest/client'
+require 'ably/rest/push'
 require 'ably/rest/presence'
 
 require 'ably/models/message_encoders/base'

data/lib/ably/rest/channel.rb

@@ -3,8 +3,6 @@ module Ably
     # The Ably Realtime service organises the traffic within any application into named channels.
     # Channels are the "unit" of message distribution; clients attach to channels to subscribe to messages, and every message broadcast by the service is associated with a unique channel.
     #
-    # @!attribute [r] client
-    #   @return {Ably::Realtime::Client} Ably client associated with this channel
     # @!attribute [r] name
     #   @return {String} channel name
     # @!attribute [r] options
@@ -12,7 +10,19 @@ module Ably
     class Channel
       include Ably::Modules::Conversions
 
-      attr_reader :client, :name, :options
+      # Ably client associated with this channel
+      # @return [Ably::Realtime::Client]
+      # @api private
+      attr_reader :client
+
+      attr_reader :name, :options
+
+      # Push channel used for push notification (client-side)
+      # @return [Ably::Rest::Channel::PushChannel]
+      # @api private
+      attr_reader :push
+
+      IDEMPOTENT_LIBRARY_GENERATED_ID_LENGTH = 9 # See spec RSL1k1
 
       # Initialize a new Channel object
       #
@@ -27,17 +37,17 @@ module Ably
         update_options channel_options
         @client  = client
         @name    = name
+        @push    = PushChannel.new(self)
       end
 
-      # Publish one or more messages to the channel.
-      #
-      # @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
+      # Publish one or more messages to the channel. Three overloaded forms
+      # @param name [String, Array<Ably::Models::Message|Hash>, Ably::Models::Message, 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, or a single Ably::Model::Message object
+      # @param data [String, ByteArray, Hash, nil]   The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument, in which case an optional hash of query parameters
+      # @param attributes [Hash, nil]   Optional additional message attributes such as :extras, :id, :client_id or :connection_id, applied when name attribute is nil or a string (Deprecated, will be removed in 2.0 in favour of constructing a Message object)
       # @return [Boolean]  true if the message was published, otherwise false
       #
       # @example
-      #   # Publish a single message
+      #   # Publish a single message with (name, data) form
       #   channel.publish 'click', { x: 1, y: 2 }
       #
       #   # Publish an array of message Hashes
@@ -54,16 +64,28 @@ module Ably
       #   ]
       #   channel.publish messages
       #
-      def publish(name, data = nil, attributes = {})
-        messages = if name.kind_of?(Enumerable)
-          name
+      #   # Publish a single Ably::Models::Message object, with a query params
+      #   # specifying quickAck: true
+      #   message = Ably::Models::Message(name: 'click', { x: 1, y: 2 })
+      #   channel.publish message, quickAck: 'true'
+      #
+      def publish(first, second = nil, third = {})
+        messages, qs_params = if first.kind_of?(Enumerable)
+          # ([Message], qs_params) form
+          [first, second]
+        elsif first.kind_of?(Ably::Models::Message)
+          # (Message, qs_params) form
+          [[first], second]
         else
-          name = ensure_utf_8(:name, name, allow_nil: true)
-          ensure_supported_payload data
-          [{ name: name, data: data }.merge(attributes)]
+          # (name, data, attributes) form
+          first = ensure_utf_8(:name, first, allow_nil: true)
+          ensure_supported_payload second
+          # RSL1h - attributes as an extra method parameter is extra-spec but need to
+          # keep it for backcompat until version 2
+          [[{ name: first, data: second }.merge(third)], nil]
         end
 
-        payload = messages.map do |message|
+        payload = messages.each_with_index.map do |message, index|
           Ably::Models::Message(message.dup).tap do |msg|
             msg.encode client.encoders, options
 
@@ -75,9 +97,21 @@ module Ably
               raise Ably::Exceptions::IncompatibleClientId.new("Cannot publish with client_id '#{msg.client_id}' as it is incompatible with the current configured client_id '#{client.client_id}'")
             end
           end.as_json
+        end.tap do |payload|
+          if client.idempotent_rest_publishing
+            # We cannot mutate for idempotent publishing if one or more messages already has an ID
+            if payload.all? { |msg| !msg['id'] }
+              # Mutate the JSON to support idempotent publishing where a Message.id does not exist
+              idempotent_publish_id = SecureRandom.base64(IDEMPOTENT_LIBRARY_GENERATED_ID_LENGTH)
+              payload.each_with_index do |msg, idx|
+                msg['id'] = "#{idempotent_publish_id}:#{idx}"
+              end
+            end
+          end
         end
 
-        response = client.post("#{base_path}/publish", payload.length == 1 ? payload.first : payload)
+        options = qs_params ? { qs_params: qs_params } : {}
+        response = client.post("#{base_path}/publish", payload.length == 1 ? payload.first : payload, options)
 
         [201, 204].include?(response.status)
       end
@@ -141,3 +175,5 @@ module Ably
     end
   end
 end
+
+require 'ably/rest/channel/push_channel'

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

@@ -0,0 +1,62 @@
+module Ably::Rest
+  class Channel
+    # A push channel used for push notifications
+    # Each PushChannel maps to exactly one Rest Channel
+    #
+    # @!attribute [r] channel
+    #   @return [Ably::Rest::Channel] Underlying channel object
+    #
+    class PushChannel
+      attr_reader :channel
+
+      def initialize(channel)
+        raise ArgumentError, "Unsupported channel type '#{channel.class}'" unless channel.kind_of?(Ably::Rest::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/rest/client.rb

@@ -30,6 +30,15 @@ module Ably
         max_retry_count:    3
       }.freeze
 
+      FALLBACK_RETRY_TIMEOUT = 10 * 60
+
+      # Faraday 1.0 introduced new error types, however we want to support Faraday <1 too which only used Faraday::ClientError
+      FARADAY_CLIENT_OR_SERVER_ERRORS = if defined?(Faraday::ParsingError)
+        [Faraday::ClientError, Faraday::ServerError, Faraday::ConnectionFailed, Faraday::SSLError, Faraday::ParsingError]
+      else
+        Faraday::ClientError
+      end
+
       def_delegators :auth, :client_id, :auth_options
 
       # Custom environment to use such as 'sandbox' when testing the client library against an alternate Ably environment
@@ -83,10 +92,23 @@ module Ably
       # if empty or nil then fallback host functionality is disabled
       attr_reader :fallback_hosts
 
-      # Whethere the {Client} has to add a random identifier to the path of a request
+      # Whether the {Client} has to add a random identifier to the path of a request
       # @return [Boolean]
       attr_reader :add_request_ids
 
+      # Retries are logged by default to warn and error. When true, retries are logged at info level
+      # @return [Boolean]
+      # @api private
+      attr_reader :log_retries_as_info
+
+      # True when idempotent publishing is enabled for all messages published via REST.
+      # When this feature is enabled, the client library will add a unique ID to every published message (without an ID)
+      # ensuring any failed published attempts (due to failures such as HTTP requests failing mid-flight) that are
+      # automatically retried will not result in duplicate messages being published to the Ably platform.
+      # Note: This is a beta unsupported feature!
+      # @return [Boolean]
+      attr_reader :idempotent_rest_publishing
+
       # Creates a {Ably::Rest::Client Rest Client} and configures the {Ably::Auth} object for the connection.
       #
       # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key or Token ID
@@ -117,6 +139,10 @@ module Ably
       #
       # @option options [Boolean]                 :fallback_hosts_use_default  (false) When true, forces the user of fallback hosts even if a non-default production endpoint is being used
       # @option options [Array<String>]           :fallback_hosts              When an array of fallback hosts are provided, these fallback hosts are always used if a request fails to the primary endpoint. If an empty array is provided, the fallback host functionality is disabled
+      # @option options [Integer]                 :fallback_retry_timeout     (600 seconds) amount of time in seconds a REST client will continue to use a working fallback host when the primary fallback host has previously failed
+      #
+      # @option options [Boolean]                 :add_request_ids             (false) When true, adds a unique request_id to each request sent to Ably servers. This is handy when reporting issues, because you can refer to a specific request.
+      # @option options [Boolean]                 :idempotent_rest_publishing  (false if ver < 1.2) When true, idempotent publishing is enabled for all messages published via REST
       #
       # @return [Ably::Rest::Client]
       #
@@ -139,18 +165,21 @@ module Ably
           end
         end
 
-        @realtime_client  = options.delete(:realtime_client)
-        @tls              = options.delete(:tls) == false ? false : true
-        @environment      = options.delete(:environment) # nil is production
-        @environment      = nil if [:production, 'production'].include?(@environment)
-        @protocol         = options.delete(:protocol) || :msgpack
-        @debug_http       = options.delete(:debug_http)
-        @log_level        = options.delete(:log_level) || ::Logger::WARN
-        @custom_logger    = options.delete(:logger)
-        @custom_host      = options.delete(:rest_host)
-        @custom_port      = options.delete(:port)
-        @custom_tls_port  = options.delete(:tls_port)
-        @add_request_ids  = options.delete(:add_request_ids)
+        @realtime_client     = options.delete(:realtime_client)
+        @tls                 = options.delete(:tls) == false ? false : true
+        @environment         = options.delete(:environment) # nil is production
+        @environment         = nil if [:production, 'production'].include?(@environment)
+        @protocol            = options.delete(:protocol) || :msgpack
+        @debug_http          = options.delete(:debug_http)
+        @log_level           = options.delete(:log_level) || ::Logger::WARN
+        @custom_logger       = options.delete(:logger)
+        @custom_host         = options.delete(:rest_host)
+        @custom_port         = options.delete(:port)
+        @custom_tls_port     = options.delete(:tls_port)
+        @add_request_ids     = options.delete(:add_request_ids)
+        @log_retries_as_info = options.delete(:log_retries_as_info)
+        @idempotent_rest_publishing = options.delete(:idempotent_rest_publishing) || Ably.major_minor_version_numeric > 1.1
+
 
         if options[:fallback_hosts_use_default] && options[:fallback_jhosts]
           raise ArgumentError, "fallback_hosts_use_default cannot be set to trye when fallback_jhosts is also provided"
@@ -166,6 +195,10 @@ module Ably
           Ably::FALLBACK_HOSTS
         end
 
+        options[:fallback_retry_timeout] ||= FALLBACK_RETRY_TIMEOUT
+
+        # Take option keys prefixed with `http_`, remove the http_ and
+        # check if the option exists in HTTP_DEFAULTS.  If so, update http_defaults
         @http_defaults = HTTP_DEFAULTS.dup
         options.each do |key, val|
           if http_key = key[/^http_(.+)/, 1]
@@ -190,8 +223,12 @@ module Ably
         raise ArgumentError, 'Protocol is invalid.  Must be either :msgpack or :json' unless [:msgpack, :json].include?(@protocol)
 
         token_params = options.delete(:default_token_params) || {}
-        @options  = options
-        @auth     = Auth.new(self, token_params, options)
+        @options = options
+        init_auth_options = options.select do |key, _|
+          Auth::AUTH_OPTIONS_KEYS.include?(key.to_s)
+        end
+
+        @auth     = Auth.new(self, token_params, init_auth_options)
         @channels = Ably::Rest::Channels.new(self)
         @encoders = []
 
@@ -273,6 +310,24 @@ module Ably
         raw_request(:post, path, params, options)
       end
 
+      # Perform an HTTP PUT request to the API using configured authentication
+      #
+      # @return [Faraday::Response]
+      #
+      # @api private
+      def put(path, params, options = {})
+        raw_request(:put, path, params, options)
+      end
+
+      # Perform an HTTP DELETE request to the API using configured authentication
+      #
+      # @return [Faraday::Response]
+      #
+      # @api private
+      def delete(path, params, options = {})
+        raw_request(:delete, path, params, options)
+      end
+
       # Perform an HTTP request to the Ably API
       # This is a convenience for customers who wish to use bleeding edge REST API functionality
       # that is either not documented or is not included in the API for our client libraries.
@@ -292,14 +347,14 @@ module Ably
 
         response = case method.to_sym
         when :get
-          reauthorize_on_authorisation_failure do
+          reauthorize_on_authorization_failure do
             send_request(method, path, params, headers: headers)
           end
         when :post
           path_with_params = Addressable::URI.new
           path_with_params.query_values = params || {}
           query = path_with_params.query
-          reauthorize_on_authorisation_failure do
+          reauthorize_on_authorization_failure do
             send_request(method, "#{path}#{"?#{query}" unless query.nil? || query.empty?}", body, headers: headers)
           end
         end
@@ -321,6 +376,20 @@ module Ably
         Models::HttpPaginatedResponse.new(response, path, self)
       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
+
+      # Push notification object for publishing and managing push notifications
+      # @return [Ably::Rest::Push]
+      def push
+        @push ||= Push.new(self)
+      end
+
       # @!attribute [r] endpoint
       # @return [URI::Generic] Default Ably REST endpoint used for all requests
       def endpoint
@@ -389,7 +458,6 @@ module Ably
       def fallback_connection
         unless defined?(@fallback_connections) && @fallback_connections
           @fallback_connections = fallback_hosts.shuffle.map { |host| Faraday.new(endpoint_for_host(host).to_s, connection_options) }
-          @fallback_connections << Faraday.new(endpoint.to_s, connection_options) # Try the original host last if all fallbacks have been used
         end
         @fallback_index ||= 0
 
@@ -410,23 +478,58 @@ module Ably
 
       # Allowable duration for an external auth request
       # For REST client this defaults to request_timeout
-      # For Realtime clients this defaults to realtime_request_timeout
+      # For Realtime clients this defaults to 250ms less than the realtime_request_timeout
+      #   ensuring an auth failure will be triggered before the realtime request timeout fires
+      #   which would lead to a misleading error message (connection timeout as opposed to auth request timeout)
       # @api private
       def auth_request_timeout
         if @realtime_client
-          @realtime_client.connection.defaults.fetch(:realtime_request_timeout)
+          @realtime_client.connection.defaults.fetch(:realtime_request_timeout) - 0.25
         else
           http_defaults.fetch(:request_timeout)
         end
       end
 
+      # If the primary host endpoint fails, and a subsequent fallback host succeeds, the fallback
+      #   host that succeeded is used for +ClientOption+ +fallback_retry_timeout+ seconds to avoid
+      #   retries to known failing hosts for a short period of time.
+      # See https://github.com/ably/docs/pull/554, spec id #RSC15f
+      #
+      # @return [nil, String]  Returns nil (falsey) if the primary host is being used, or the currently used host if a fallback host is currently preferred
+      def using_preferred_fallback_host?
+        if preferred_fallback_connection && (preferred_fallback_connection.fetch(:expires_at) > Time.now)
+          preferred_fallback_connection.fetch(:connection_object).host
+        end
+      end
+
       private
+
+      attr_reader :preferred_fallback_connection
+
+      # See #using_preferred_fallback_host? for context
+      def set_preferred_fallback_connection(connection)
+        @preferred_fallback_connection = if connection == @connection
+          # If the succeeded connection is in fact the primary connection (tried after a failed fallback)
+          #   then clear the preferred fallback connection
+          nil
+        else
+          {
+            expires_at: Time.now + options.fetch(:fallback_retry_timeout),
+            connection_object: connection,
+          }
+        end
+      end
+
+      def get_preferred_fallback_connection_object
+        preferred_fallback_connection.fetch(:connection_object) if using_preferred_fallback_host?
+      end
+
       def raw_request(method, path, params = {}, options = {})
         options = options.clone
         if options.delete(:disable_automatic_reauthorize) == true
           send_request(method, path, params, options)
         else
-          reauthorize_on_authorisation_failure do
+          reauthorize_on_authorization_failure do
             send_request(method, path, params, options)
           end
         end
@@ -442,15 +545,30 @@ module Ably
         retry_sequence_id  = nil
         request_id         = SecureRandom.urlsafe_base64(10) if add_request_ids
 
+        preferred_fallback_connection_for_first_request = get_preferred_fallback_connection_object
+
         begin
-          use_fallback = can_fallback_to_alternate_ably_host? && retry_count > 0
+          use_fallback = can_fallback_to_alternate_ably_host? && (retry_count > 0)
+
+          conn = if preferred_fallback_connection_for_first_request
+            case retry_count
+            when 0
+              preferred_fallback_connection_for_first_request
+            when 1
+              # Ensure the root host is used first if the preferred fallback fails, see #RSC15f
+              connection(use_fallback: false)
+            end
+          end || connection(use_fallback: use_fallback) # default to normal connection selection process if not preferred connection set
 
-          connection(use_fallback: use_fallback).send(method, path, params) do |request|
+          conn.send(method, path, params) do |request|
             if add_request_ids
               request.params[:request_id] = request_id
               request.options.context = {} if request.options.context.nil?
               request.options.context[:request_id] = request_id
             end
+            if options[:qs_params]
+              request.params.merge!(options[:qs_params])
+            end
             unless options[:send_auth_header] == false
               request.headers[:authorization] = auth.auth_header
               if options[:headers]
@@ -461,41 +579,45 @@ module Ably
             end
           end.tap do
             if retry_count > 0
-              logger.warn do
+              retry_log_severity = log_retries_as_info ? :info : :warn
+              logger.public_send(retry_log_severity) do
                 "Ably::Rest::Client - Request SUCCEEDED after #{retry_count} #{retry_count > 1 ? 'retries' : 'retry' } for" \
                 " #{method} #{path} #{params} (seq ##{retry_sequence_id}, time elapsed #{(Time.now.to_f - requested_at.to_f).round(2)}s)"
               end
+              set_preferred_fallback_connection conn
             end
           end
 
-        rescue Faraday::TimeoutError, Faraday::ClientError, Ably::Exceptions::ServerError => error
+        rescue *([Faraday::TimeoutError, Ably::Exceptions::ServerError] + FARADAY_CLIENT_OR_SERVER_ERRORS) => error
           retry_sequence_id ||= SecureRandom.urlsafe_base64(4)
           time_passed = Time.now - requested_at
 
-          if can_fallback_to_alternate_ably_host? && retry_count < max_retry_count && time_passed <= max_retry_duration
+          if can_fallback_to_alternate_ably_host? && (retry_count < max_retry_count) && (time_passed <= max_retry_duration)
             retry_count += 1
-            logger.warn { "Ably::Rest::Client - Retry #{retry_count} for #{method} #{path} #{params} as initial attempt failed (seq ##{retry_sequence_id}): #{error}" }
+            retry_log_severity = log_retries_as_info ? :info : :warn
+            logger.public_send(retry_log_severity) { "Ably::Rest::Client - Retry #{retry_count} for #{method} #{path} #{params} as initial attempt failed (seq ##{retry_sequence_id}): #{error}" }
             retry
           end
 
-          logger.error do
+          retry_log_severity = log_retries_as_info ? :info : :error
+          logger.public_send(retry_log_severity) do
             "Ably::Rest::Client - Request FAILED after #{retry_count} #{retry_count > 1 ? 'retries' : 'retry' } for" \
             " #{method} #{path} #{params} (seq ##{retry_sequence_id}, time elapsed #{(Time.now.to_f - requested_at.to_f).round(2)}s)"
           end
 
           case error
             when Faraday::TimeoutError
-              raise Ably::Exceptions::ConnectionTimeout.new(error.message, nil, 80014, error, { request_id: request_id })
-            when Faraday::ClientError
+              raise Ably::Exceptions::ConnectionTimeout.new(error.message, nil, Ably::Exceptions::Codes::CONNECTION_TIMED_OUT, error, { request_id: request_id })
+            when *FARADAY_CLIENT_OR_SERVER_ERRORS
               # request_id is also available in the request context
-              raise Ably::Exceptions::ConnectionError.new(error.message, nil, 80000, error, { request_id: request_id })
+              raise Ably::Exceptions::ConnectionError.new(error.message, nil, Ably::Exceptions::Codes::CONNECTION_FAILED, error, { request_id: request_id })
             else
               raise error
           end
         end
       end
 
-      def reauthorize_on_authorisation_failure
+      def reauthorize_on_authorization_failure
         yield
       rescue Ably::Exceptions::TokenExpired => e
         if auth.token_renewable?