ably 1.0.7 → 1.1.0

data/lib/ably/rest/client.rb

@@ -30,6 +30,8 @@ module Ably
         max_retry_count:    3
       }.freeze
 
+      FALLBACK_RETRY_TIMEOUT = 10 * 60
+
       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 +85,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,7 +132,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]
       #
@@ -140,18 +158,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"
@@ -167,6 +188,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]
@@ -191,8 +216,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 = []
 
@@ -274,6 +303,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.
@@ -293,14 +340,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
@@ -322,6 +369,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
@@ -390,7 +451,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
 
@@ -421,13 +481,46 @@ module Ably
         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
@@ -443,10 +536,22 @@ 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?
@@ -462,10 +567,12 @@ 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
 
@@ -473,30 +580,32 @@ module Ably
           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 })
+              raise Ably::Exceptions::ConnectionTimeout.new(error.message, nil, Ably::Exceptions::Codes::CONNECTION_TIMED_OUT, error, { request_id: request_id })
             when Faraday::ClientError
               # 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?

data/lib/ably/rest/middleware/parse_message_pack.rb

@@ -10,6 +10,14 @@ module Ably
             env.body = parse(env.body) unless env.response_headers['Ably-Middleware-Parsed'] == true
             env.response_headers['Ably-Middleware-Parsed'] = true
           end
+        rescue Ably::Exceptions::InvalidResponseBody => e
+          debug_info = {
+            method: env.method,
+            url: env.url,
+            base64_body: base64_body(env.body),
+            response_headers: env.response_headers
+          }
+          raise Ably::Exceptions::InvalidResponseBody, "#{e.message}\nRequest env: #{debug_info}"
         end
 
         def parse(body)
@@ -18,8 +26,16 @@ module Ably
           else
             body
           end
+        rescue MessagePack::UnknownExtTypeError => e
+          raise Ably::Exceptions::InvalidResponseBody, "MessagePack::UnknownExtTypeError body could not be decoded: #{e.message}. Got Base64:\n#{base64_body(body)}"
         rescue MessagePack::MalformedFormatError => e
-          raise Ably::Exceptions::InvalidResponseBody, "Expected MessagePack response: #{e.message}"
+          raise Ably::Exceptions::InvalidResponseBody, "MessagePack::MalformedFormatError body could not be decoded: #{e.message}. Got Base64:\n#{base64_body(body)}"
+        end
+
+        def base64_body(body)
+          Base64.encode64(body)
+        rescue => err
+          "[#{err.message}! Could not base64 encode body: '#{body}']"
         end
       end
     end

data/lib/ably/rest/presence.rb

@@ -5,6 +5,7 @@ module Ably
 
       # {Ably::Rest::Client} for this Presence object
       # @return {Ably::Rest::Client}
+      # @private
       attr_reader :client
 
       # {Ably::Rest::Channel} this Presence object is associated with

data/lib/ably/rest/push.rb

@@ -0,0 +1,42 @@
+require 'ably/rest/push/admin'
+
+module Ably
+  module Rest
+    # Class providing push notification functionality
+    class Push
+      include Ably::Modules::Conversions
+
+      # @private
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Admin features for push notifications like managing devices and channel subscriptions
+      # @return [Ably::Rest::Push::Admin]
+      def admin
+        @admin ||= Admin.new(self)
+      end
+
+      # Activate this device for push notifications by registering with the push transport such as GCM/APNS
+      #
+      # @note This is unsupported in the Ruby library
+      def activate(*arg)
+        raise_unsupported
+      end
+
+      # Deactivate this device for push notifications by removing the registration with the push transport such as GCM/APNS
+      #
+      # @note This is unsupported in the Ruby library
+      def deactivate(*arg)
+        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/push/admin.rb

@@ -0,0 +1,54 @@
+require 'ably/rest/push/device_registrations'
+require 'ably/rest/push/channel_subscriptions'
+
+module Ably::Rest
+  class Push
+    # Class providing push notification administrative functionality
+    # for registering devices and attaching to channels etc.
+    class Admin
+      include Ably::Modules::Conversions
+
+      # @api private
+      attr_reader :client
+
+      # @api private
+      attr_reader :push
+
+      def initialize(push)
+        @push = push
+        @client = push.client
+      end
+
+      # Publish a push message directly to a single recipient
+      #
+      # @param recipient [Hash] A recipient device, client_id or raw APNS/GCM target. Refer to push documentation
+      # @param data      [Hash] The notification payload data and fields. Refer to push documentation
+      #
+      # @return [void]
+      #
+      def publish(recipient, data)
+        raise ArgumentError, "Expecting a Hash object for recipient, got #{recipient.class}" unless recipient.kind_of?(Hash)
+        raise ArgumentError, "Recipient data is empty. You must provide recipient details" if recipient.empty?
+        raise ArgumentError, "Expecting a Hash object for data, got #{data.class}" unless data.kind_of?(Hash)
+        raise ArgumentError, "Push data field is empty. You must provide attributes for the push notification" if data.empty?
+
+        publish_data = data.merge(recipient: IdiomaticRubyWrapper(recipient))
+        # Co-erce to camelCase for notitication fields which are always camelCase
+        publish_data[:notification] = IdiomaticRubyWrapper(data[:notification]) if publish_data[:notification].kind_of?(Hash)
+        client.post('/push/publish', publish_data)
+      end
+
+      # Manage device registrations
+      # @return [Ably::Rest::Push::DeviceRegistrations]
+      def device_registrations
+        @device_registrations ||= DeviceRegistrations.new(self)
+      end
+
+      # Manage channel subscriptions for devices or clients
+      # @return [Ably::Rest::Push::ChannelSubscriptions]
+      def channel_subscriptions
+        @channel_subscriptions ||= ChannelSubscriptions.new(self)
+      end
+    end
+  end
+end

data/lib/ably/rest/push/channel_subscriptions.rb

@@ -0,0 +1,121 @@
+module Ably::Rest
+  class Push
+    # Manage push notification channel subscriptions for devices or client identifiers
+    class ChannelSubscriptions
+      include Ably::Modules::Conversions
+
+      # @api private
+      attr_reader :client
+
+      # @api private
+      attr_reader :admin
+
+      def initialize(admin)
+        @admin = admin
+        @client = admin.client
+      end
+
+      # List channel subscriptions filtered by optional params
+      #
+      # @param [Hash] params   the filter options for the list channel subscription request. At least one of channel, client_id or device_id is required
+      # @option params [String]   :channel    filter by realtime pub/sub channel name
+      # @option params [String]   :client_id  filter by devices registered to a client identifier. If provided with device_id param, a concat operation is used so that any device with this client_id or provided device_id is returned.
+      # @option params [String]   :device_id  filter by unique device ID. If provided with client_id param, a concat operation is used so that any device with this device_id or provided client_id is returned.
+      # @option params [Integer]  :limit      maximum number of subscriptions to retrieve up to 1,000, defaults to 100
+      #
+      # @return [Ably::Models::PaginatedResult<Ably::Models::PushChannelSubscription>]  Paginated list of matching {Ably::Models::PushChannelSubscription}
+      #
+      def list(params)
+        raise ArgumentError, "params must be a Hash" unless params.kind_of?(Hash)
+
+        if (IdiomaticRubyWrapper(params).keys & [:channel, :client_id, :device_id]).length == 0
+          raise ArgumentError, "at least one channel, client_id or device_id filter param must be provided"
+        end
+
+        params = params.clone
+
+        paginated_options = {
+          coerce_into: 'Ably::Models::PushChannelSubscription',
+          async_blocking_operations: params.delete(:async_blocking_operations),
+        }
+
+        response = client.get('/push/channelSubscriptions', IdiomaticRubyWrapper(params).as_json)
+
+        Ably::Models::PaginatedResult.new(response, '', client, paginated_options)
+      end
+
+      # List channels with at least one subscribed device
+      #
+      # @param [Hash] params   the options for the list channels request
+      # @option params [Integer]  :limit      maximum number of channels to retrieve up to 1,000, defaults to 100
+      #
+      # @return [Ably::Models::PaginatedResult<String>]  Paginated list of matching {Ably::Models::PushChannelSubscription}
+      #
+      def list_channels(params = {})
+        params = {} if params.nil?
+        raise ArgumentError, "params must be a Hash" unless params.kind_of?(Hash)
+
+        params = params.clone
+
+        paginated_options = {
+          coerce_into: 'String',
+          async_blocking_operations: params.delete(:async_blocking_operations),
+        }
+
+        response = client.get('/push/channels', IdiomaticRubyWrapper(params).as_json)
+
+        Ably::Models::PaginatedResult.new(response, '', client, paginated_options)
+      end
+
+      # Save push channel subscription for a device or client ID
+      #
+      # @param [Ably::Models::PushChannelSubscription,Hash]   push_channel_subscription   the push channel subscription details to save
+      #
+      # @return [void]
+      #
+      def save(push_channel_subscription)
+        push_channel_subscription_object = PushChannelSubscription(push_channel_subscription)
+        raise ArgumentError, "Channel is required yet is empty" if push_channel_subscription_object.channel.to_s.empty?
+
+        client.post("/push/channelSubscriptions", push_channel_subscription_object.as_json)
+      end
+
+      # Remove a push channel subscription
+      #
+      # @param [Ably::Models::PushChannelSubscription,Hash]   push_channel_subscription   the push channel subscription details to remove
+      #
+      # @return [void]
+      #
+      def remove(push_channel_subscription)
+        push_channel_subscription_object = PushChannelSubscription(push_channel_subscription)
+        raise ArgumentError, "Channel is required yet is empty" if push_channel_subscription_object.channel.to_s.empty?
+        if push_channel_subscription_object.client_id.to_s.empty? && push_channel_subscription_object.device_id.to_s.empty?
+          raise ArgumentError, "Either client_id or device_id must be present"
+        end
+
+        client.delete("/push/channelSubscriptions", push_channel_subscription_object.as_json)
+      end
+
+      # Remove all matching push channel subscriptions
+      #
+      # @param [Hash] params   the filter options for the list channel subscription request. At least one of channel, client_id or device_id is required
+      # @option params [String]   :channel    filter by realtime pub/sub channel name
+      # @option params [String]   :client_id  filter by devices registered to a client identifier. If provided with device_id param, a concat operation is used so that any device with this client_id or provided device_id is returned.
+      # @option params [String]   :device_id  filter by unique device ID. If provided with client_id param, a concat operation is used so that any device with this device_id or provided client_id is returned.
+      #
+      # @return [void]
+      #
+      def remove_where(params)
+        raise ArgumentError, "params must be a Hash" unless params.kind_of?(Hash)
+
+        if (IdiomaticRubyWrapper(params).keys & [:channel, :client_id, :device_id]).length == 0
+          raise ArgumentError, "at least one channel, client_id or device_id filter param must be provided"
+        end
+
+        params = params.clone
+
+        client.delete("/push/channelSubscriptions", IdiomaticRubyWrapper(params).as_json)
+      end
+    end
+  end
+end