ably 0.6.2 → 0.7.0

data/lib/ably/models/message_encoders/json.rb

@@ -1,4 +1,5 @@
 require 'json'
+require 'ably/models/message_encoders/base'
 
 module Ably::Models::MessageEncoders
   # JSON Encoder and Decoder

data/lib/ably/models/message_encoders/utf8.rb

@@ -1,4 +1,4 @@
-require 'json'
+require 'ably/models/message_encoders/base'
 
 module Ably::Models::MessageEncoders
   # Utf8 Encoder and Decoder
@@ -8,10 +8,7 @@ module Ably::Models::MessageEncoders
     ENCODING_ID = 'utf-8'
 
     def encode(message, channel_options)
-      if is_json_encoded?(message)
-        message[:data] = message[:data].force_encoding(Encoding::UTF_8)
-        add_encoding_to_message ENCODING_ID, message
-      end
+      # no encoding of UTF-8 required
     end
 
     def decode(message, channel_options)
@@ -25,9 +22,5 @@ module Ably::Models::MessageEncoders
     def is_utf8_encoded?(message)
       current_encoding_part(message).to_s.match(/^#{ENCODING_ID}$/i)
     end
-
-    def is_json_encoded?(message)
-      current_encoding_part(message).to_s.match(/^json$/i)
-    end
   end
 end

data/lib/ably/models/nil_logger.rb

@@ -0,0 +1,20 @@
+module Ably::Models
+  # When Log Level set to none, this NilLogger is used to silence all logging
+  # NilLogger provides a Ruby Logger compatible interface
+  class NilLogger
+    def null_method(*args)
+    end
+
+    def level
+      :none
+    end
+
+    def level=(value)
+      level
+    end
+
+    [:fatal, :error, :warn, :info, :debug].each do |method|
+      alias_method method, :null_method
+    end
+  end
+end

data/lib/ably/models/paginated_resource.rb

@@ -5,7 +5,7 @@ module Ably::Models
   # Paging information is provided by Ably in the LINK HTTP headers
   class PaginatedResource
     include Enumerable
-    include Ably::Modules::AsyncWrapper
+    include Ably::Modules::AsyncWrapper if defined?(EventMachine)
 
     # @param [Faraday::Response] http_response Initial HTTP response from an Ably request to a paged resource
     # @param [String] base_url Base URL for request that generated the http_response so that subsequent paged requests can be made
@@ -27,7 +27,9 @@ module Ably::Models
 
       @body = if @coerce_into
         http_response.body.map do |item|
-          Kernel.const_get(@coerce_into).new(item)
+          @coerce_into.split('::').inject(Kernel) do |base, klass_name|
+            base.public_send(:const_get, klass_name)
+          end.new(item)
         end
       else
         http_response.body
@@ -168,6 +170,7 @@ module Ably::Models
 
     def async_wrap_if(is_realtime, success_callback, &operation)
       if is_realtime
+        raise 'EventMachine is required for asynchronous operations' unless defined?(EventMachine)
         async_wrap success_callback, &operation
       else
         yield

data/lib/ably/models/presence_message.rb

@@ -23,8 +23,10 @@ module Ably::Models
   #   @return [STATE] the state change event signified by a PresenceMessage
   # @!attribute [r] client_id
   #   @return [String] The client_id associated with this presence state
-  # @!attribute [r] member_id
+  # @!attribute [r] connection_id
   #   @return [String] A unique member identifier, disambiguating situations where a given client_id is present on multiple connections simultaneously
+  # @!attribute [r] member_key
+  #   @return [String] A unique connection and client_id identifier ensuring multiple connected clients with the same client_id are unique
   # @!attribute [r] data
   #   @return [Object] Optional client-defined status or other event payload associated with this state
   # @!attribute [r] encoding
@@ -36,12 +38,15 @@ module Ably::Models
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #
   class PresenceMessage
-    include Ably::Modules::ModelCommon
+    include Ably::Modules::Conversions
     include Ably::Modules::Encodeable
+    include Ably::Modules::ModelCommon
     include EventMachine::Deferrable
     extend Ably::Modules::Enum
 
     ACTION = ruby_enum('ACTION',
+      :absent,
+      :present,
       :enter,
       :leave,
       :update
@@ -57,16 +62,28 @@ module Ably::Models
       @raw_hash_object  = hash_object
 
       set_hash_object hash_object
+
+      ensure_utf_8 :client_id,     client_id,     allow_nil: true
+      ensure_utf_8 :connection_id, connection_id, allow_nil: true
+      ensure_utf_8 :encoding,      encoding,      allow_nil: true
     end
 
-    %w( client_id member_id data encoding ).each do |attribute|
+    %w( client_id data encoding ).each do |attribute|
       define_method attribute do
         hash[attribute.to_sym]
       end
     end
 
     def id
-      hash[:id] || "#{protocol_message.id!}:#{protocol_message_index}"
+      hash.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
+    end
+
+    def connection_id
+      hash.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? }
+    end
+
+    def member_key
+      "#{connection_id}:#{client_id}"
     end
 
     def timestamp
@@ -123,14 +140,6 @@ module Ably::Models
       protocol_message.presence.index(self)
     end
 
-    def connection_id
-      protocol_message.connection_id
-    end
-
-    def message_serial
-      protocol_message.message_serial
-    end
-
     def set_hash_object(hash)
       @hash_object = IdiomaticRubyWrapper(hash.clone.freeze, stop_at: [:data])
     end

data/lib/ably/models/protocol_message.rb

@@ -7,7 +7,7 @@ module Ably::Models
   # for further details on the members of a ProtocolMessage
   #
   # @!attribute [r] action
-  #   @return [ACTION] Protocol Message action {Ably::Modules::Enum} from list of {ACTION}. Returns nil if action is unsupported by protocol.
+  #   @return [ACTION] Protocol Message action {Ably::Modules::Enum} from list of {ACTION}. Returns nil if action is unsupported by protocol
   # @!attribute [r] count
   #   @return [Integer] The count field is used for ACK and NACK actions. See {http://docs.ably.io/client-lib-development-guide/protocol/#message-acknowledgement message acknowledgement protocol}
   # @!attribute [r] error_info
@@ -17,7 +17,9 @@ module Ably::Models
   # @!attribute [r] channel_serial
   #   @return [String] Contains a serial number for a message on the current channel
   # @!attribute [r] connection_id
-  #   @return [String] Contains a string connection ID
+  #   @return [String] Contains a string public identifier for the connection
+  # @!attribute [r] connection_key
+  #   @return [String] Contains a string private connection key used to recover this connection
   # @!attribute [r] connection_serial
   #   @return [Bignum] Contains a serial number for a message sent from the server to the client
   # @!attribute [r] message_serial
@@ -25,9 +27,11 @@ module Ably::Models
   # @!attribute [r] timestamp
   #   @return [Time] An optional timestamp, applied by the service in messages sent to the client, to indicate the system time at which the message was sent (milliseconds past epoch)
   # @!attribute [r] messages
-  #   @return [Message] A {ProtocolMessage} with a `:message` action contains one or more messages belonging to a channel.
+  #   @return [Message] A {ProtocolMessage} with a `:message` action contains one or more messages belonging to a channel
   # @!attribute [r] presence
-  #   @return [PresenceMessage] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to a channel.
+  #   @return [PresenceMessage] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to a channel
+  # @!attribute [r] flags
+  #   @return [Integer] Flags inidicating special ProtocolMessage states
   # @!attribute [r] hash
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #
@@ -56,7 +60,8 @@ module Ably::Models
       detach:       12,
       detached:     13,
       presence:     14,
-      message:      15
+      message:      15,
+      sync:         16
     )
 
     # Indicates this protocol message action will generate an ACK response such as :message or :presence
@@ -74,7 +79,7 @@ module Ably::Models
       @hash_object.freeze
     end
 
-    %w( id channel channel_serial connection_id ).each do |attribute|
+    %w(id channel channel_serial connection_id connection_key).each do |attribute|
       define_method attribute do
         hash[attribute.to_sym]
       end
@@ -157,6 +162,17 @@ module Ably::Models
         end
     end
 
+    # Flags as bits
+    def flags
+      Integer(hash[:flags])
+    rescue TypeError
+      0
+    end
+
+    def has_presence_flag?
+      flags & 1 == 1
+    end
+
     # Indicates this protocol message will generate an ACK response when sent
     # Examples of protocol messages required ACK include :message and :presence
     def ack_required?

data/lib/ably/modules/ably.rb

@@ -0,0 +1,11 @@
+# Ably is the base namespace for the Ably {Ably::Realtime Realtime} & {Ably::Rest Rest} client libraries.
+#
+# Please refer to the {file:README.md Readme} on getting started.
+#
+# @see file:README.md README
+module Ably
+  # Fallback hosts to use when a connection to rest/realtime.ably.io is not possible due to
+  # network failures either at the client, between the client and Ably, within an Ably data center, or at the IO domain registrar
+  #
+  FALLBACK_HOSTS = %w(A.ably-realtime.com B.ably-realtime.com C.ably-realtime.com D.ably-realtime.com E.ably-realtime.com)
+end

data/lib/ably/modules/async_wrapper.rb

@@ -1,3 +1,5 @@
+require 'eventmachine'
+
 module Ably::Modules
   # Provides methods to convert synchronous operations into async operations through the use of
   # {EventMachine#defer http://www.rubydoc.info/github/eventmachine/eventmachine/EventMachine#defer-class_method}.

data/lib/ably/modules/conversions.rb

@@ -5,7 +5,9 @@ module Ably::Modules
     extend self
 
     private
-    def as_since_epoch(time, granularity: :ms)
+    def as_since_epoch(time, options = {})
+      granularity = options.fetch(:granularity, :ms)
+
       case time
       when Time
         time.to_f * multiplier_from_granularity(granularity)
@@ -16,7 +18,9 @@ module Ably::Modules
       end.to_i
     end
 
-    def as_time_from_epoch(time, granularity: :ms)
+    def as_time_from_epoch(time, options = {})
+      granularity = options.fetch(:granularity, :ms)
+
       case time
       when Numeric
         Time.at(time / multiplier_from_granularity(granularity))
@@ -39,7 +43,9 @@ module Ably::Modules
     end
 
     # Convert key to mixedCase from mixed_case
-    def convert_to_mixed_case(key, force_camel: false)
+    def convert_to_mixed_case(key, options = {})
+      force_camel = options.fetch(:force_camel, false)
+
       key.to_s.
         split('_').
         each_with_index.map do |str, index|
@@ -66,5 +72,19 @@ module Ably::Modules
     def convert_to_lower_case(key)
       key.to_s.gsub('_', '')
     end
+
+    # Ensures that the string value is converted to UTF-8 encoding
+    # Unless option allow_nil: true, an {ArgumentError} is raised if the string_value is not a string
+    #
+    # @return <void>
+    #
+    def ensure_utf_8(field_name, string_value, options = {})
+      unless options[:allow_nil] && string_value.nil?
+        raise ArgumentError, "#{field_name} must be a String" unless string_value.kind_of?(String)
+      end
+      string_value.encode!(Encoding::UTF_8) if string_value
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError => e
+      raise ArgumentError, "#{field_name} could not be converted to UTF-8: #{e.message}"
+    end
   end
 end

data/lib/ably/modules/encodeable.rb

@@ -1,4 +1,5 @@
 require 'base64'
+require 'ably/exceptions'
 
 module Ably::Modules
   # Provides methods to allow this model's `data` property to be encoded and decoded based on the `encoding` property.
@@ -57,8 +58,8 @@ module Ably::Modules
 
       set_hash_object message_hash
     rescue Ably::Exceptions::CipherError => cipher_error
-      channel.client.logger.error "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"
       if channel.respond_to?(:trigger)
+        channel.client.logger.error "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"
         channel.trigger :error, cipher_error
       else
         raise cipher_error

data/lib/ably/modules/enum.rb

@@ -1,3 +1,5 @@
+require 'ably/modules/conversions'
+
 module Ably::Modules
   # Enum brings Enum like functionality used in other languages to Ruby
   #

data/lib/ably/modules/event_emitter.rb

@@ -62,7 +62,13 @@ module Ably
 
       # 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)].delete_if { |proc_hash| proc_hash[:trigger_proc].call(*args) }
+        callbacks[callbacks_event_coerced(event_name)].
+          clone.
+          select do |proc_hash|
+            proc_hash[:trigger_proc].call(*args)
+          end.each do |callback|
+            callbacks[callbacks_event_coerced(event_name)].delete callback
+          end
       end
 
       # Remove all callbacks for event_name.

data/lib/ably/modules/event_machine_helpers.rb

@@ -1,3 +1,5 @@
+require 'eventmachine'
+
 module Ably::Modules
   # EventMachineHelpers module provides common private methods to classes simplifying interaction with EventMachine
   module EventMachineHelpers

data/lib/ably/modules/http_helpers.rb

@@ -1,5 +1,7 @@
 require 'base64'
 
+require 'ably/version'
+
 require 'ably/rest/middleware/encoder'
 require 'ably/rest/middleware/external_exceptions'
 require 'ably/rest/middleware/fail_if_unsupported_mime_type'

data/lib/ably/modules/model_common.rb

@@ -1,10 +1,12 @@
 require 'base64'
+require 'ably/modules/conversions'
+require 'ably/modules/message_pack'
 
 module Ably::Modules
   # Common model functionality shared across many {Ably::Models}
   module ModelCommon
-    include Ably::Modules::Conversions
-    include Ably::Modules::MessagePack
+    include Conversions
+    include MessagePack
 
     # Provide a normal Hash accessor to the underlying raw message object
     #
@@ -27,5 +29,13 @@ module Ably::Modules
     def to_json(*args)
       as_json.to_json(*args)
     end
+
+    private
+    def ensure_utf8_string_for(attribute, value)
+      if value
+        raise ArgumentError, "#{attribute} must be a String" unless value.kind_of?(String)
+        raise ArgumentError, "#{attribute} cannot use ASCII_8BIT encoding, please use UTF_8 encoding" unless value.encoding == Encoding::UTF_8
+      end
+    end
   end
 end

data/lib/ably/modules/state_emitter.rb

@@ -26,6 +26,7 @@ module Ably::Modules
   #   connection.state = :invalid        # raises an Exception as only a valid state can be defined
   #   connection.trigger :invalid        # raises an Exception as only a valid state can be used for EventEmitter
   #   connection.change_state :connected # emits :connected event via EventEmitter, returns STATE.Connected
+  #   connection.once_or_if(:connected) { puts 'block called once when state is connected or becomes connected' }
   #
   module StateEmitter
     # Current state {Ably::Modules::Enum}
@@ -55,7 +56,82 @@ module Ably::Modules
     end
     alias_method :change_state, :state=
 
+    # If the current state matches the target_state argument the block is called immediately.
+    # Else the block is called once when the target_state is reached.
+    #
+    # If the option block :else is provided then if any state other than target_state is reached, the :else block is called,
+    # however only one of the blocks will ever be called
+    #
+    # @param [Symbol,Ably::Modules::Enum,Array] target_states a single state or array of states that once met, will fire the success block only once
+    # @param [Hash] options
+    # @option options [Proc] :else block called once the state has changed to anything but target_state
+    #
+    # @yield block is called if the state is matched immediately or once when the state is reached
+    #
+    # @return [void]
+    def once_or_if(target_states, options = {}, &success_block)
+      raise ArgumentError, 'Block is expected' unless block_given?
+
+      if Array(target_states).any? { |target_state| state == target_state }
+        success_block.call
+      else
+        failure_block   = options.fetch(:else, nil)
+        failure_wrapper = nil
+
+        success_wrapper = Proc.new do
+          success_block.call
+          off &success_wrapper
+          off &failure_wrapper if failure_wrapper
+        end
+
+        failure_wrapper = proc do |*args|
+          failure_block.call *args
+          off &success_wrapper
+          off &failure_wrapper
+        end if failure_block
+
+        Array(target_states).each do |target_state|
+          once target_state, &success_wrapper
+
+          once_state_changed do |*args|
+            failure_wrapper.call *args unless state == target_state
+          end if failure_block
+        end
+      end
+    end
+
+    # Calls the block once when the state changes
+    #
+    # @yield block is called once the state changes
+    # @return [void]
+    #
+    # @api private
+    def once_state_changed(&block)
+      raise ArgumentError, 'Block is expected' unless block_given?
+
+      once_block = proc do |*args|
+        off *self.class::STATE.map, &once_block
+        yield *args
+      end
+
+      once *self.class::STATE.map, &once_block
+    end
+
     private
+
+    # Returns an {EventMachine::Deferrable} and once the target state is reached, the
+    # success_block if provided and {EventMachine::Deferrable#callback} is called.
+    # If the state changes to any other state, the {EventMachine::Deferrable#errback} is called.
+    #
+    def deferrable_for_state_change_to(target_state, &success_block)
+      EventMachine::DefaultDeferrable.new.tap do |deferrable|
+        once_or_if(target_state, else: proc { |*args| deferrable.fail self, *args }) do
+          success_block.call self if block_given?
+          deferrable.succeed self
+        end
+      end
+    end
+
     def self.included(klass)
       klass.configure_event_emitter coerce_into: Proc.new { |event|
         if event == :error