ably 0.7.2 → 0.7.4

data/lib/ably/auth.rb

@@ -34,7 +34,7 @@ module Ably
     # Creates an Auth object
     #
     # @param [Ably::Rest::Client] client  {Ably::Rest::Client} this Auth object uses
-    # @param options (see Ably::Rest::Client#initialize)
+    # @param [Hash] options (see Ably::Rest::Client#initialize)
     # @option (see Ably::Rest::Client#initialize)
     # @yield  (see Ably::Rest::Client#initialize)
     #
@@ -53,12 +53,7 @@ module Ably
         raise ArgumentError, 'api_key and key_id or key_secret are mutually exclusive. Provider either an api_key or key_id & key_secret'
       end
 
-      if auth_options[:api_key]
-        api_key_parts = auth_options[:api_key].to_s.match(/(?<id>[\w_-]+\.[\w_-]+):(?<secret>[\w_-]+)/)
-        raise ArgumentError, 'api_key is invalid' unless api_key_parts
-        auth_options[:key_id] = api_key_parts[:id].encode(Encoding::UTF_8)
-        auth_options[:key_secret] = api_key_parts[:secret].encode(Encoding::UTF_8)
-      end
+      split_api_key_into_key_and_secret! auth_options if auth_options[:api_key]
 
       if using_basic_auth? && !api_key_present?
         raise ArgumentError, 'api_key is missing. Either an API key, token, or token auth method must be provided'
@@ -78,6 +73,7 @@ module Ably
     #
     # @param [Hash] options the options for the token request
     # @option options (see #request_token)
+    # @option options [String]  :api_key API key comprising the key ID and key secret in a single string
     # @option options [Boolean] :force   obtains a new token even if the current token is valid
     #
     # @yield (see #request_token)
@@ -102,6 +98,9 @@ module Ably
         return current_token unless current_token.expired?
       end
 
+      options = options.clone
+      split_api_key_into_key_and_secret! options if options[:api_key]
+
       @options             = @options.merge(options)
       @default_token_block = token_request_block if block_given?
 
@@ -157,10 +156,13 @@ module Ably
 
       token_request = IdiomaticRubyWrapper(token_request)
 
-      response = client.post("/keys/#{token_request.fetch(:id)}/requestToken", token_request.hash, send_auth_header: false, disable_automatic_reauthorise: true)
-      body = IdiomaticRubyWrapper(response.body)
-
-      Ably::Models::Token.new(body.fetch(:access_token))
+      if token_request.has_key?(:issued_at) && token_request.has_key?(:expires)
+        Ably::Models::Token.new(token_request)
+      else
+        response = client.post("/keys/#{token_request.fetch(:id)}/requestToken", token_request.hash, send_auth_header: false, disable_automatic_reauthorise: true)
+        body = IdiomaticRubyWrapper(response.body)
+        Ably::Models::Token.new(body.fetch(:access_token))
+      end
     end
 
     # Creates and signs a token request that can then subsequently be used by any client to request a token
@@ -191,6 +193,7 @@ module Ably
       token_attributes   = %w(id client_id ttl timestamp capability nonce)
 
       token_options      = options.clone
+
       request_key_id     = token_options.delete(:key_id) || key_id
       request_key_secret = token_options.delete(:key_secret) || key_secret
 
@@ -296,7 +299,7 @@ module Ably
     end
 
     private
-    attr_reader :default_token_block
+    attr_reader :client, :default_token_block
 
     def ensure_api_key_sent_over_secure_connection
       raise Ably::Exceptions::InsecureRequestError, 'Cannot use Basic Auth over non-TLS connections' unless authentication_security_requirements_met?
@@ -308,6 +311,14 @@ module Ably
       "Basic #{encode64("#{api_key}")}"
     end
 
+    def split_api_key_into_key_and_secret!(options)
+      api_key_parts = options[:api_key].to_s.match(/(?<id>[\w_-]+\.[\w_-]+):(?<secret>[\w_-]+)/)
+      raise ArgumentError, 'api_key is invalid' unless api_key_parts
+
+      options[:key_id]     = api_key_parts[:id].encode(Encoding::UTF_8)
+      options[:key_secret] = api_key_parts[:secret].encode(Encoding::UTF_8)
+    end
+
     def token_auth_id
       if token_id
         token_id
@@ -431,8 +442,5 @@ module Ably
     def api_key_present?
       key_id && key_secret
     end
-
-    private
-    attr_reader :client
   end
 end

data/lib/ably/exceptions.rb

@@ -44,9 +44,15 @@ module Ably
     # Connection Timeout accessing Realtime or REST service
     class ConnectionTimeoutError < ConnectionError; end
 
+    # Connection closed unexpectedly
+    class ConnectionClosedError < ConnectionError; end
+
     # Invalid State Change error on a {https://github.com/gocardless/statesman Statesman State Machine}
     class StateChangeError < BaseAblyException; end
 
+    # The state of the object is not suitable for this operation
+    class IncompatibleStateForOperation < 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
     class Standard < BaseAblyException; end
@@ -65,5 +71,8 @@ module Ably
 
     # The token request could not be created
     class TokenRequestError < BaseAblyException; end
+
+    # The message could not be delivered to the server
+    class MessageDeliveryError < BaseAblyException; end
   end
 end

data/lib/ably/models/message.rb

@@ -2,17 +2,17 @@ module Ably::Models
   # Convert messsage argument to a {Message} object and associate with a protocol message if provided
   #
   # @param message [Message,Hash] A message object or Hash of message properties
-  # @param protocol_message [ProtocolMessage] An optional protocol message to assocate the message with
+  # @param [Hash] options (see Message#initialize)
   #
   # @return [Message]
-  def self.Message(message, protocol_message = nil)
+  def self.Message(message, options = {})
     case message
     when Message
       message.tap do
-        message.assign_to_protocol_message protocol_message
+        message.assign_to_protocol_message options[:protocol_message] if options[:protocol_message]
       end
     else
-      Message.new(message, protocol_message)
+      Message.new(message, options)
     end
   end
 
@@ -41,15 +41,18 @@ module Ably::Models
     include Ably::Modules::Conversions
     include Ably::Modules::Encodeable
     include Ably::Modules::ModelCommon
-    include EventMachine::Deferrable
+    include Ably::Modules::SafeDeferrable if defined?(Ably::Realtime)
 
     # {Message} initializer
     #
-    # @param hash_object      [Hash]            object with the underlying message details
-    # @param protocol_message [ProtocolMessage] if this message has been published, then it is associated with a {ProtocolMessage}
+    # @param  hash_object [Hash]            object with the underlying message details
+    # @param  [Hash]      options           an options Hash for this initializer
+    # @option options     [ProtocolMessage] :protocol_message  An optional protocol message to assocate the presence message with
+    # @option options     [Logger]          :logger            An optional Logger to be used by {Ably::Modules::SafeDeferrable} if an exception is caught in a callback
     #
-    def initialize(hash_object, protocol_message = nil)
-      @protocol_message = protocol_message
+    def initialize(hash_object, options = {})
+      @logger           = options[:logger] # Logger expected for SafeDeferrable
+      @protocol_message = options[:protocol_message]
       @raw_hash_object  = hash_object
 
       set_hash_object hash_object
@@ -128,5 +131,10 @@ module Ably::Models
     def set_hash_object(hash)
       @hash_object = IdiomaticRubyWrapper(hash.clone.freeze, stop_at: [:data])
     end
+
+    def logger
+      return logger if logger
+      protocol_message.logger if protocol_message
+    end
   end
 end

data/lib/ably/models/paginated_resource.rb

@@ -31,23 +31,23 @@ module Ably::Models
     end
 
     # Retrieve the first page of results.
-    # When used as part of the {Ably::Realtime} library, it will return a {EventMachine::Deferrable} object,
+    # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object,
     #   and allows an optional success callback block to be provided.
     #
-    # @return [PaginatedResource,EventMachine::Deferrable]
+    # @return [PaginatedResource,Ably::Util::SafeDeferrable]
     def first_page(&success_callback)
-      async_wrap_if(make_async, success_callback) do
+      async_wrap_if_realtime(success_callback) do
         PaginatedResource.new(client.get(pagination_url('first')), base_url, client, pagination_options, &each_block)
       end
     end
 
     # Retrieve the next page of results.
-    # When used as part of the {Ably::Realtime} library, it will return a {EventMachine::Deferrable} object,
+    # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object,
     #   and allows an optional success callback block to be provided.
     #
-    # @return [PaginatedResource,EventMachine::Deferrable]
+    # @return [PaginatedResource,Ably::Util::SafeDeferrable]
     def next_page(&success_callback)
-      async_wrap_if(make_async, success_callback) do
+      async_wrap_if_realtime(success_callback) do
         raise Ably::Exceptions::InvalidPageError, 'There are no more pages' if supports_pagination? && last_page?
         PaginatedResource.new(client.get(pagination_url('next')), base_url, client, pagination_options, &each_block)
       end
@@ -161,13 +161,17 @@ module Ably::Models
       }
     end
 
-    def async_wrap_if(is_realtime, success_callback, &operation)
-      if is_realtime
+    def async_wrap_if_realtime(success_callback, &operation)
+      if make_async
         raise 'EventMachine is required for asynchronous operations' unless defined?(EventMachine)
         async_wrap success_callback, &operation
       else
         yield
       end
     end
+
+    def logger
+      client.logger
+    end
   end
 end

data/lib/ably/models/presence_message.rb

@@ -2,17 +2,17 @@ module Ably::Models
   # Convert presence_messsage argument to a {PresenceMessage} object and associate with a protocol message if provided
   #
   # @param presence_message [PresenceMessage,Hash] A presence message object or Hash of presence message properties
-  # @param protocol_message [ProtocolMessage] An optional protocol message to assocate the presence message with
+  # @param [Hash] options (see PresenceMessage#initialize)
   #
   # @return [PresenceMessage]
-  def self.PresenceMessage(presence_message, protocol_message = nil)
+  def self.PresenceMessage(presence_message, options = {})
     case presence_message
     when PresenceMessage
       presence_message.tap do
-        presence_message.assign_to_protocol_message protocol_message
+        presence_message.assign_to_protocol_message options[:protocol_message] if options[:protocol_message]
       end
     else
-      PresenceMessage.new(presence_message, protocol_message)
+      PresenceMessage.new(presence_message, options)
     end
   end
 
@@ -41,7 +41,7 @@ module Ably::Models
     include Ably::Modules::Conversions
     include Ably::Modules::Encodeable
     include Ably::Modules::ModelCommon
-    include EventMachine::Deferrable
+    include Ably::Modules::SafeDeferrable if defined?(Ably::Realtime)
     extend Ably::Modules::Enum
 
     ACTION = ruby_enum('ACTION',
@@ -52,13 +52,16 @@ module Ably::Models
       :update
     )
 
-    # {Message} initializer
+    # {PresenceMessage} initializer
     #
-    # @param hash_object      [Hash]             object with the underlying message details
-    # @param protocol_message [ProtocolMessage] if this message has been published, then it is associated with a {ProtocolMessage}
+    # @param  hash_object [Hash]            object with the underlying presence message details
+    # @param  [Hash]      options           an options Hash for this initializer
+    # @option options     [ProtocolMessage] :protocol_message  An optional protocol message to assocate the presence message with
+    # @option options     [Logger]          :logger            An optional Logger to be used by {Ably::Modules::SafeDeferrable} if an exception is caught in a callback
     #
-    def initialize(hash_object, protocol_message = nil)
-      @protocol_message = protocol_message
+    def initialize(hash_object, options = {})
+      @logger           = options[:logger] # Logger expected for SafeDeferrable
+      @protocol_message = options[:protocol_message]
       @raw_hash_object  = hash_object
 
       set_hash_object hash_object
@@ -143,5 +146,10 @@ module Ably::Models
     def set_hash_object(hash)
       @hash_object = IdiomaticRubyWrapper(hash.clone.freeze, stop_at: [:data])
     end
+
+    def logger
+      return logger if logger
+      protocol_message.logger if protocol_message
+    end
   end
 end

data/lib/ably/models/protocol_message.rb

@@ -37,7 +37,7 @@ module Ably::Models
   #
   class ProtocolMessage
     include Ably::Modules::ModelCommon
-    include EventMachine::Deferrable if defined?(Ably::Realtime)
+    include Ably::Modules::SafeDeferrable if defined?(Ably::Realtime)
     extend Ably::Modules::Enum
 
     # Actions which are sent by the Ably Realtime API
@@ -69,7 +69,15 @@ module Ably::Models
       [ACTION.Presence, ACTION.Message].include?(ACTION(for_action))
     end
 
-    def initialize(hash_object)
+    # {ProtocolMessage} initializer
+    #
+    # @param  hash_object [Hash]            object with the underlying protocol message data
+    # @param  [Hash]      options           an options Hash for this initializer
+    # @option options     [Logger]          :logger            An optional Logger to be used by {Ably::Modules::SafeDeferrable} if an exception is caught in a callback
+    #
+    def initialize(hash_object, options = {})
+      @logger = options[:logger] # Logger expected for SafeDeferrable
+
       @raw_hash_object = hash_object
       @hash_object     = IdiomaticRubyWrapper(@raw_hash_object.clone)
 
@@ -147,7 +155,7 @@ module Ably::Models
     def messages
       @messages ||=
         Array(hash[:messages]).map do |message|
-          Ably::Models.Message(message, self)
+          Ably::Models.Message(message, protocol_message: self)
         end
     end
 
@@ -158,7 +166,7 @@ module Ably::Models
     def presence
       @presence ||=
         Array(hash[:presence]).map do |message|
-          Ably::Models.PresenceMessage(message, self)
+          Ably::Models.PresenceMessage(message, protocol_message: self)
         end
     end
 
@@ -206,5 +214,8 @@ module Ably::Models
       action_enum = action rescue nil
       !action_enum || (ack_required? && !has_serial?)
     end
+
+    private
+    attr_reader :logger
   end
 end

data/lib/ably/modules/async_wrapper.rb

@@ -7,6 +7,7 @@ module Ably::Modules
   #
   # @note using this AsyncWrapper should only be used for methods that are used less frequently and typically
   #       not run with levels of concurrency due to the limited number of threads available to EventMachine by default.
+  #       This module requires that the method #logger is defined.
   #
   # @example
   #   class BlockingOperation
@@ -32,15 +33,15 @@ module Ably::Modules
   module AsyncWrapper
     private
 
-    # Will yield the provided block in a new thread and return an {EventMachine::Deferrable http://www.rubydoc.info/github/eventmachine/eventmachine/EventMachine/Deferrable}
+    # Will yield the provided block in a new thread and return an {Ably::Util::SafeDeferrable}
     #
     # @yield [Object] operation block that is run in a thread
-    # @return [EventMachine::Deferrable]
+    # @return [Ably::Util::SafeDeferrable]
     #
     def async_wrap(success_callback = nil)
       raise ArgumentError, 'Block required' unless block_given?
 
-      EventMachine::DefaultDeferrable.new.tap do |deferrable|
+      Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
         deferrable.callback &success_callback if success_callback
 
         operation_with_exception_handling = proc do

data/lib/ably/modules/event_emitter.rb

@@ -1,3 +1,5 @@
+require 'ably/modules/safe_yield'
+
 module Ably
   module Modules
     # EventEmitter provides methods to attach to public events and trigger events on any class instance
@@ -5,6 +7,8 @@ module Ably
     # EventEmitter are typically used for public interfaces, and as such, may be overriden in
     # the classes to enforce `event` names match expected values.
     #
+    # @note This module requires that the method #logger is defined.
+    #
     # @example
     #   class Example
     #     include Modules::EventEmitter
@@ -16,6 +20,8 @@ module Ably
     #   #=> "Signal Test received"
     #
     module EventEmitter
+      include Ably::Modules::SafeYield
+
       module ClassMethods
         attr_reader :event_emitter_coerce_proc
 
@@ -49,6 +55,15 @@ module Ably
         end
       end
 
+      # Equivalent of {#on} but any exception raised in a block will bubble up and cause this client library to fail.
+      # This method should only be used internally by the client library.
+      # @api private
+      def unsafe_on(*event_names, &block)
+        event_names.each do |event_name|
+          callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block, unsafe: true)
+        end
+      end
+
       # On receiving an event maching the event_name, call the provided block only once and remove the registered callback
       #
       # @param [Array<String>] event_names event name
@@ -60,12 +75,25 @@ module Ably
         end
       end
 
+      # Equivalent of {#once} but any exception raised in a block will bubble up and cause this client library to fail.
+      # This method should only be used internally by the client library.
+      # @api private
+      def unsafe_once(*event_names, &block)
+        event_names.each do |event_name|
+          callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block, delete_once_run: true, unsafe: true)
+        end
+      end
+
       # Trigger an event with event_name that will in turn call all matching callbacks setup with `on`
       def trigger(event_name, *args)
         callbacks[callbacks_event_coerced(event_name)].
           clone.
           select do |proc_hash|
-            proc_hash[:trigger_proc].call(*args)
+            if proc_hash[:unsafe]
+              proc_hash[:trigger_proc].call *args
+            else
+              safe_yield proc_hash[:trigger_proc], *args
+            end
           end.each do |callback|
             callbacks[callbacks_event_coerced(event_name)].delete callback
           end
@@ -108,7 +136,8 @@ module Ably
             block.call *args
             true if options[:delete_once_run]
           end,
-          block: block
+          block: block,
+          unsafe: options[:unsafe]
         }
       end
 

data/lib/ably/modules/message_emitter.rb

@@ -0,0 +1,77 @@
+require 'ably/util/pub_sub'
+
+module Ably::Modules
+  # Message emitter, subscriber and unsubscriber (Pub/Sub) functionality common to Channels and Presence
+  # In addition to standard Pub/Sub functionality, it allows subscribers to subscribe to :all.
+  module MessageEmitter
+    # Subscribe to events on this object
+    #
+    # @param name [String,Symbol] Optional, the event name to subscribe to. Defaults to `:all` events
+    # @yield [Object] For each event, the provided block is called with the event payload object
+    #
+    # @return [void]
+    #
+    def subscribe(*names, &callback)
+      raise ArgumentError, 'Block required to subscribe to events' unless block_given?
+      names = :all unless names && !names.empty?
+      Array(names).uniq.each do |name|
+        message_emitter_subscriptions[message_emitter_subscriptions_message_name_key(name)] << callback
+      end
+    end
+
+    # Unsubscribe the matching block for events on the this object.
+    # If a block is not provided, all subscriptions will be unsubscribed
+    #
+    # @param name [String,Symbol] Optional, the event name to unsubscribe from. Defaults to `:all` events
+    #
+    # @return [void]
+    #
+    def unsubscribe(*names, &callback)
+      names = :all unless names && !names.empty?
+      Array(names).each do |name|
+        if name == :all
+          message_emitter_subscriptions.keys
+        else
+          Array(message_emitter_subscriptions_message_name_key(name))
+        end.each do |key|
+          message_emitter_subscriptions[key].delete_if do |block|
+            !block_given? || callback == block
+          end
+        end
+      end
+    end
+
+    # Emit a message to message subscribers
+    #
+    # param name [String,Symbol] the event name
+    # param payload [Object] the event object to emit
+    #
+    # @return [void]
+    #
+    # @api private
+    def emit_message(name, payload)
+      raise 'Event name is required' unless name
+
+      message_emitter_subscriptions[:all].each { |cb| cb.call(payload) }
+      message_emitter_subscriptions[name].each { |cb| cb.call(payload) }
+    end
+
+    private
+    def message_emitter_subscriptions
+      @message_emitter_subscriptions ||= Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def message_emitter_subscriptions_message_name_key(name)
+      if name == :all
+        :all
+      else
+        message_emitter_subscriptions_coerce_message_key(name)
+      end
+    end
+
+    # this method can be overwritten easily to enforce use of set key types§
+    def message_emitter_subscriptions_coerce_message_key(name)
+      name.to_s
+    end
+  end
+end