ably 1.0.7 → 1.1.4.rc

data/ably.gemspec

@@ -21,32 +21,37 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'eventmachine', '~> 1.2.6'
   spec.add_runtime_dependency 'em-http-request', '~> 1.1'
   spec.add_runtime_dependency 'statesman', '~> 1.0.0'
-  spec.add_runtime_dependency 'faraday', '~> 0.12'
-  spec.add_runtime_dependency 'excon', '~> 0.55'
+  spec.add_runtime_dependency 'faraday', '~> 1.0'
+  spec.add_runtime_dependency 'typhoeus', '~> 1.4'
 
-  if RUBY_VERSION.match(/^1/)
+  if RUBY_VERSION.match(/^1\./)
     spec.add_runtime_dependency 'json', '< 2.0'
   else
     spec.add_runtime_dependency 'json'
   end
   spec.add_runtime_dependency 'websocket-driver', '~> 0.7'
-  spec.add_runtime_dependency 'msgpack', '>= 0.6.2'
+  spec.add_runtime_dependency 'msgpack', '>= 1.3.0'
   spec.add_runtime_dependency 'addressable', '>= 2.0.0'
 
-  spec.add_development_dependency 'bundler', '~> 1.3'
-  spec.add_development_dependency 'rake', '~> 11.3'
+  spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'redcarpet', '~> 3.3'
-  spec.add_development_dependency 'rspec', '~> 3.2.0' # version lock, see config.around(:example, :event_machine) in event_machine_helper.rb
-  spec.add_development_dependency 'rspec-retry', '~> 0.4'
+  spec.add_development_dependency 'rspec', '~> 3.10.0' # version lock, see config.around(:example, :event_machine) in event_machine_helper.rb
+  spec.add_development_dependency 'rspec-retry', '~> 0.6'
   spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'rspec-instafail', '~> 1.0'
+  spec.add_development_dependency 'bundler', '~> 2.2.1'
 
-  if RUBY_VERSION.match(/^1/)
+  if RUBY_VERSION.match(/^1\./)
     spec.add_development_dependency 'public_suffix', '~> 1.4.6' # Later versions do not support Ruby 1.9
     spec.add_development_dependency 'webmock', '2.2'
+    spec.add_development_dependency 'parallel_tests', '~> 2.9.0'
   else
     spec.add_development_dependency 'webmock', '~> 2.2'
     spec.add_development_dependency 'coveralls'
-    spec.add_development_dependency 'pry'
-    spec.add_development_dependency 'pry-byebug'
+    spec.add_development_dependency 'parallel_tests', '~> 2.22'
+    if !RUBY_VERSION.match(/^2\.[0123]/)
+      spec.add_development_dependency 'pry'
+      spec.add_development_dependency 'pry-byebug'
+    end
   end
 end

data/lib/ably/auth.rb

@@ -35,6 +35,28 @@ module Ably
 
     API_KEY_REGEX = /^[\w-]{2,}\.[\w-]{2,}:[\w-]{2,}$/
 
+    # Supported AuthOption keys, see https://www.ably.io/documentation/realtime/types#auth-options
+    # TODO: Review client_id usage embedded incorrectly within AuthOptions.
+    #       This is legacy code to configure a client with a client_id from the ClientOptions
+    # TODO: Review inclusion of use_token_auth, ttl, token_params in auth options
+    AUTH_OPTIONS_KEYS = %w(
+      auth_callback
+      auth_url
+      auth_method
+      auth_headers
+      auth_params
+      client_id
+      key
+      key_name
+      key_secret
+      query_time
+      token
+      token_details
+      token_params
+      ttl
+      use_token_auth
+    )
+
     attr_reader :options, :token_params, :current_token_details
     alias_method :auth_options, :options
 
@@ -231,7 +253,7 @@ module Ably
             auth_callback.call(token_params)
           end
         rescue StandardError => err
-          raise Ably::Exceptions::AuthenticationFailed.new("auth_callback failed: #{err.message}", nil, nil, err, fallback_status: 500, fallback_code: 80019)
+          raise Ably::Exceptions::AuthenticationFailed.new("auth_callback failed: #{err.message}", nil, nil, err, fallback_status: 500, fallback_code: Ably::Exceptions::Codes::CONNECTION_NOT_ESTABLISHED_NO_TRANSPORT_HANDLE)
         end
       elsif auth_url = auth_options.delete(:auth_url)
         begin
@@ -239,7 +261,7 @@ module Ably
             token_request_from_auth_url(auth_url, auth_options, token_params)
           end
         rescue StandardError => err
-          raise Ably::Exceptions::AuthenticationFailed.new("auth_url failed: #{err.message}", nil, nil, err, fallback_status: 500, fallback_code: 80019)
+          raise Ably::Exceptions::AuthenticationFailed.new("auth_url failed: #{err.message}", nil, nil, err, fallback_status: 500, fallback_code: Ably::Exceptions::Codes::CONNECTION_NOT_ESTABLISHED_NO_TRANSPORT_HANDLE)
         end
       else
         create_token_request(token_params, auth_options)
@@ -504,6 +526,10 @@ module Ably
     end
 
     def ensure_valid_auth_attributes(attributes)
+      (attributes.keys.map(&:to_s) - AUTH_OPTIONS_KEYS).tap do |unsupported_keys|
+        raise ArgumentError, "The key(s) #{unsupported_keys.map { |k| ":#{k}" }.join(', ')} are not valid AuthOptions" unless unsupported_keys.empty?
+      end
+
       if attributes[:timestamp]
         unless attributes[:timestamp].kind_of?(Time) || attributes[:timestamp].kind_of?(Numeric)
           raise ArgumentError, ':timestamp must be a Time or positive Integer value of seconds since epoch'

data/lib/ably/exceptions.rb

@@ -1,10 +1,11 @@
+require 'ably/modules/exception_codes'
+
 module Ably
   module Exceptions
     TOKEN_EXPIRED_CODE = 40140..40149
-    INVALID_CLIENT_ID = 40012
 
     # Base Ably exception class that contains status and code values used by Ably
-    # Refer to https://github.com/ably/ably-common/blob/master/protocol/errors.json
+    # Refer to https://github.com/ably/ably-common/blob/main/protocol/errors.json
     #
     # @!attribute [r] message
     #   @return [String] Error message from Ably
@@ -37,6 +38,7 @@ module Ably
           additional_info << "base exception: #{@base_exception.class}" if @base_exception
           additional_info << "request_id: #{request_id}" if request_id
           message << "(#{additional_info.join(', ')})"
+          message << "-> see https://help.ably.io/error/#{code} for help" if code
         end
         message.join(' ')
       end
@@ -53,6 +55,8 @@ module Ably
     # An invalid request was received by Ably
     class InvalidRequest < BaseAblyException; end
 
+    class InvalidCredentials < BaseAblyException; end
+
     # Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided
     class UnauthorizedRequest < BaseAblyException; end
 
@@ -112,7 +116,7 @@ module Ably
     class InvalidState < BaseAblyException; end
 
     # A generic Ably exception taht supports a status & code.
-    # See https://github.com/ably/ably-common/blob/master/protocol/errors.json for a list of Ably errors
+    # See https://github.com/ably/ably-common/blob/main/protocol/errors.json for a list of Ably errors
     class Standard < BaseAblyException; end
 
     # The HTTP request has returned a 500 error
@@ -146,12 +150,14 @@ module Ably
     class ChannelInactive < BaseAblyException; end
 
     class IncompatibleClientId < BaseAblyException
-      def initialize(messages, status = 400, code = INVALID_CLIENT_ID, *args)
+      def initialize(messages, status = 400, code = Ably::Exceptions::Codes::INVALID_CLIENT_ID, *args)
         super(message, status, code, *args)
       end
     end
 
     # Token request has missing or invalid attributes
     class InvalidTokenRequest < BaseAblyException; end
+
+    class PushNotificationsNotSupported < BaseAblyException; end
   end
 end

data/lib/ably/logger.rb

@@ -20,6 +20,8 @@ module Ably
       ensure_logger_interface_is_valid
 
       @logger.level = log_level
+
+      @log_mutex = Mutex.new
     end
 
     # The logger used by this class, defaults to {http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html Ruby Logger}
@@ -38,7 +40,9 @@ module Ably
     %w(fatal error warn info debug).each do |method_name|
       define_method(method_name) do |*args, &block|
         begin
-          logger.public_send(method_name, *args, &block)
+          log_mutex.synchronize do
+            logger.public_send(method_name, *args, &block)
+          end
         rescue StandardError => e
           logger.error "Logger: Failed to log #{method_name} block - #{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
         end
@@ -46,6 +50,8 @@ module Ably
     end
 
     private
+    attr_reader :log_mutex
+
     def client
       @client
     end

data/lib/ably/models/channel_state_change.rb

@@ -48,7 +48,7 @@ module Ably::Models
     end
 
     def to_s
-      "ChannelStateChange: current state #{current}, previous state #{previous}"
+      "<ChannelStateChange: current state #{current}, previous state #{previous}>"
     end
   end
 end

data/lib/ably/models/connection_state_change.rb

@@ -38,7 +38,7 @@ module Ably::Models
     end
 
     def to_s
-      "ConnectionStateChange: current state #{current}, previous state #{previous}"
+      "<ConnectionStateChange: current state #{current}, previous state #{previous}>"
     end
   end
 end

data/lib/ably/models/device_details.rb

@@ -0,0 +1,87 @@
+module Ably::Modules
+  module Conversions
+    private
+    # Convert device_details argument to a {Ably::Models::DeviceDetails} object
+    #
+    # @param device_details [Ably::Models::DeviceDetails,Hash,nil] A device details object
+    #
+    # @return [Ably::Models::DeviceDetails]
+    def DeviceDetails(device_details)
+      case device_details
+      when Ably::Models::DeviceDetails
+        device_details
+      else
+        Ably::Models::DeviceDetails.new(device_details)
+      end
+    end
+  end
+end
+
+module Ably::Models
+  # An object representing a devices details, used currently for push notifications
+  #
+  # @!attribute [r] id
+  #   @return [String] Unique device identifier assigned randomly by the device
+  # @!attribute [r] platform
+  #   @return [String] Device platform such as android, ios or browser
+  # @!attribute [r] form_factor
+  #   @return [String] Device form factor such as phone, tablet, watch
+  # @!attribute [r] client_id
+  #   @return [String] The authenticated client identifier for this device. See {https://www.ably.io/documentation/general/authentication#identified-clients auth documentation}.
+  # @!attribute [r] metadata
+  #   @return [Hash] Arbitrary metadata that can be associated with a device
+  # @!attribute [r] device_secret
+  #   @return [String] This secret is used internally by Ably client libraries to authenticate with Ably when push registration updates are required such as when the GCM token expires and needs renewing
+  # @!attribute [r] push
+  #   @return [DevicePushDetails] The push notification specific properties for this device allowing push notifications to be delivered to the device
+  #
+  class DeviceDetails < Ably::Exceptions::BaseAblyException
+    include Ably::Modules::ModelCommon
+
+    # @param hash_object   [Hash,nil]  Device detail attributes
+    #a
+    def initialize(hash_object = {})
+      @raw_hash_object = hash_object || {}
+      @hash_object     = IdiomaticRubyWrapper(hash_object)
+    end
+
+    %w(id platform form_factor client_id device_secret).each do |attribute|
+      define_method attribute do
+        attributes[attribute.to_sym]
+      end
+
+      define_method "#{attribute}=" do |val|
+        unless val.nil? || val.kind_of?(String)
+          raise ArgumentError, "#{attribute} must be nil or a string value"
+        end
+        attributes[attribute.to_sym] = val
+      end
+    end
+
+    def metadata
+      attributes[:metadata] || {}
+    end
+
+    def metadata=(val)
+      unless val.nil? || val.kind_of?(Hash)
+        raise ArgumentError, "metadata must be nil or a Hash value"
+      end
+      attributes[:metadata] = val
+    end
+
+    def push
+      DevicePushDetails(attributes[:push] || {})
+    end
+
+    def push=(val)
+      unless val.nil? || val.kind_of?(Hash) || val.kind_of?(Ably::Models::DevicePushDetails)
+        raise ArgumentError, "push must be nil, a Hash value or a DevicePushDetails object"
+      end
+      attributes[:push] = DevicePushDetails(val)
+    end
+
+    def attributes
+      @hash_object
+    end
+  end
+end

data/lib/ably/models/device_push_details.rb

@@ -0,0 +1,86 @@
+module Ably::Modules
+  module Conversions
+    private
+    # Convert device_push_details argument to a {Ably::Models::DevicePushDetails} object
+    #
+    # @param device_push_details [Ably::Models::DevicePushDetails,Hash,nil] A device push notification details object
+    #
+    # @return [Ably::Models::DevicePushDetails]
+    def DevicePushDetails(device_push_details)
+      case device_push_details
+      when Ably::Models::DevicePushDetails
+        device_push_details
+      else
+        Ably::Models::DevicePushDetails.new(device_push_details)
+      end
+    end
+  end
+end
+
+module Ably::Models
+  # An object with the push notification details for {DeviceDetails} object
+  #
+  # @!attribute [r] transport_type
+  #   @return [String] Transport type for push notifications such as gcm, apns, web
+  # @!attribute [r] state
+  #   @return [String] The current state of this push target such as Active, Failing or Failed
+  # @!attribute [r] error_reason
+  #   @return [ErrorInfo] If the state is Failing of Failed, this field may optionally contain a reason
+  # @!attribute [r] metadata
+  #   @return [Hash] Arbitrary metadata that can be associated with this object
+  #
+  class DevicePushDetails < Ably::Exceptions::BaseAblyException
+    include Ably::Modules::ModelCommon
+
+    # @param hash_object   [Hash,nil]  Device push detail attributes
+    #a
+    def initialize(hash_object = {})
+      @raw_hash_object = hash_object || {}
+      @hash_object     = IdiomaticRubyWrapper(@raw_hash_object)
+    end
+
+    %w(state).each do |attribute|
+      define_method attribute do
+        attributes[attribute.to_sym]
+      end
+
+      define_method "#{attribute}=" do |val|
+        unless val.nil? || val.kind_of?(String)
+          raise ArgumentError, "#{attribute} must be nil or a string value"
+        end
+        attributes[attribute.to_sym] = val
+      end
+    end
+
+    def recipient
+      attributes[:recipient] || {}
+    end
+
+    def recipient=(val)
+      unless val.nil? || val.kind_of?(Hash)
+        raise ArgumentError, "recipient must be nil or a Hash value"
+      end
+      attributes[:recipient] = val
+    end
+
+    def error_reason
+      attributes[:error_reason]
+    end
+
+    def error_reason=(val)
+      unless val.nil? || val.kind_of?(Hash) || val.kind_of?(Ably::Models::ErrorInfo)
+        raise ArgumentError, "error_reason must be nil, a Hash value or a ErrorInfo object"
+      end
+
+      attributes[:error_reason] = if val.nil?
+        nil
+      else
+        ErrorInfo(val)
+      end
+    end
+
+    def attributes
+      @hash_object
+    end
+  end
+end

data/lib/ably/models/error_info.rb

@@ -1,3 +1,22 @@
+module Ably::Modules
+  module Conversions
+    private
+    # Convert error_details argument to a {ErrorInfo} object
+    #
+    # @param error_details [ErrorInfo,Hash] Error info attributes
+    #
+    # @return [ErrorInfo]
+    def ErrorInfo(error_details)
+      case error_details
+      when Ably::Models::ErrorInfo
+        error_details
+      else
+        Ably::Models::ErrorInfo.new(error_details)
+      end
+    end
+  end
+end
+
 module Ably::Models
   # An exception type encapsulating error information containing
   # an Ably-specific error code and generic status code.
@@ -19,7 +38,7 @@ module Ably::Models
       @hash_object     = IdiomaticRubyWrapper(hash_object.clone.freeze)
     end
 
-    %w(message code status_code).each do |attribute|
+    %w(message code href status_code).each do |attribute|
       define_method attribute do
         attributes[attribute.to_sym]
       end
@@ -31,7 +50,9 @@ module Ably::Models
     end
 
     def to_s
-      "Error: #{message} (code: #{code}, http status: #{status})"
+      error_href = href || (code ? "https://help.ably.io/error/#{code}" : '')
+      see_msg = " -> see #{error_href} for help" unless message.to_s.include?(error_href.to_s)
+      "<Error: #{message} (code: #{code}, http status: #{status})>#{see_msg}"
     end
   end
 end

data/lib/ably/models/idiomatic_ruby_wrapper.rb

@@ -144,11 +144,11 @@ module Ably::Models
       @attributes
     end
 
-    # Takes the underlying Hash object and returns it in as a JSON ready Hash object using snakeCase for compability with the Ably service.
+    # Takes the underlying Hash object and returns it in as a JSON ready Hash object using camelCase for compability with the Ably service.
     # Note name clashes are ignored and will result in loss of one or more values
     # @example
     #   wrapper = IdiomaticRubyWrapper({ 'mixedCase': true, mixed_case: false, 'snake_case': 1 })
-    #   wrapper.as_json({ 'mixedCase': true, 'snakeCase': 1 })
+    #   wrapper.as_json => { 'mixedCase': true, 'snakeCase': 1 }
     def as_json(*args)
       attributes.each_with_object({}) do |key_val, new_hash|
         key                      = key_val[0]
@@ -161,7 +161,7 @@ module Ably::Models
     end
 
     # Converts the current wrapped mixedCase object to JSON
-    # using mixedCase syntax as expected by the Realtime API
+    # using snakedCase syntax as expected by the Realtime API
     def to_json(*args)
       as_json(args).to_json
     end
@@ -170,7 +170,7 @@ module Ably::Models
     # Note name clashes are ignored and will result in loss of one or more values
     # @example
     #   wrapper = IdiomaticRubyWrapper({ 'mixedCase': true, mixed_case: false, 'snake_case': 1 })
-    #   wrapper.to_hash({ mixed_case: true, snake_case: 1 })
+    #   wrapper.to_hash => { mixed_case: true, snake_case: 1 }
     def to_hash(*args)
       each_with_object({}) do |key_val, object|
         key, val    = key_val