ably 0.1.6 → 0.2.0

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

@@ -0,0 +1,107 @@
+# MessageEncoders are registered with the Ably client library and are responsible
+# for encoding & decoding messages.
+#
+# For example, if a message body is detected as JSON, it is encoded as a String and the encoding attribute
+# of the message is defined as 'json'.
+# Encrypted messages are encoded & decoded by the Cipher encoder.
+#
+module Ably::Models::MessageEncoders
+  extend Ably::Modules::Conversions
+
+  # Base interface for an Ably Encoder
+  #
+  class Base
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # #encode is called once before a message is sent to Ably
+    #
+    # It is the responsibility of the #encode method to detect the intended encoding and modify the :data & :encoding properties of the message object.
+    #
+    # @param [Hash] message          the message as a Hash object received directly from Ably.
+    #                                The message contains properties :name, :data, :encoding, :timestamp, and optionally :id and :client_id.
+    #                                This #encode method should modify the message Hash if any encoding action is to be taken
+    # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
+    #
+    # @return [void]
+    def encode(message, channel_options)
+      raise "Not yet implemented"
+    end
+
+    # #decode is called once for every encoding step
+    # i.e. if message encoding arrives with 'utf-8/cipher+aes-128-cbc/base64'
+    #      the decoder will call #decode once for each encoding part such as 'base64', then 'cipher+aes-128-cbc', and finally 'utf-8'
+    #
+    # It is the responsibility of the #decode method to detect the current encoding part and modify the :data & :encoding properties of the message object.
+    #
+    # @param [Hash] message          the message as a Hash object received directly from Ably.
+    #                                The message contains properties :name, :data, :encoding, :timestamp, and optionally :id and :client_id.
+    #                                This #encode method should modify the message Hash if any decoding action is to be taken
+    # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
+    #
+    # @return [void]
+    def decode(message, channel_options)
+      raise "Not yet implemented"
+    end
+
+    # Add encoding to the message Hash.
+    # Ensures that encoding delimeter is used where required i.e utf-8/cipher+aes-128-cbc/base64
+    #
+    # @param [Hash]   message   the message as a Hash object received directly from Ably.
+    # @param [String] encoding  encoding to add to the current encoding
+    #
+    # @return [void]
+    def add_encoding_to_message(encoding, message)
+      message[:encoding] = [message[:encoding], encoding].compact.join('/')
+    end
+
+    # Returns the right most encoding form a meessage encoding, and nil if none exists
+    # i.e. current_encoding_part('utf-8/cipher+aes-128-cbc/base64') => 'base64'
+    #
+    # @return [String,nil]
+    def current_encoding_part(message)
+      if message[:encoding]
+        message[:encoding].split('/')[-1]
+      end
+    end
+
+    # Strip the current encoding part within the message Hash.
+    #
+    # For example, calling this method on an :encoding value of 'utf-8/cipher+aes-128-cbc/base64' would update the attribute
+    # :encoding to 'utf-8/cipher+aes-128-cbc'
+    #
+    # @param [Hash]   message   the message as a Hash object received directly from Ably.
+    #
+    # @return [void]
+    def strip_current_encoding_part(message)
+      raise "Cannot strip encoding when there is no encoding for this message" unless message[:encoding]
+      message[:encoding] = message[:encoding].split('/')[0...-1].join('/')
+      message[:encoding] = nil if message[:encoding].empty?
+    end
+
+    # True of the message data payload is empty
+    #
+    # @param [Hash]   message   the message as a Hash object received directly from Ably.
+    #
+    # @return [Boolean]
+    def is_empty?(message)
+      message[:data].nil? || message[:data] == ''
+    end
+  end
+
+  def self.register_default_encoders(client)
+    Dir.glob(File.expand_path("*.rb", File.dirname(__FILE__))).each do |file|
+      next if __FILE__ == file
+      require file
+    end
+
+    client.register_encoder Ably::Models::MessageEncoders::Utf8
+    client.register_encoder Ably::Models::MessageEncoders::Json
+    client.register_encoder Ably::Models::MessageEncoders::Cipher
+    client.register_encoder Ably::Models::MessageEncoders::Base64
+  end
+end
+

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

@@ -0,0 +1,39 @@
+require 'base64'
+
+module Ably::Models::MessageEncoders
+  # Base64 binary Encoder and Decoder
+  # Uses encoding identifier 'base64'
+  #
+  class Base64 < Base
+    ENCODING_ID = 'base64'
+
+    def encode(message, channel_options)
+      return if is_empty?(message)
+
+      if is_binary?(message) && transport_protocol_text?
+        message[:data] = ::Base64.encode64(message[:data])
+        add_encoding_to_message ENCODING_ID, message
+      end
+    end
+
+    def decode(message, channel_options)
+      if is_base64_encoded?(message)
+        message[:data] = ::Base64.decode64(message[:data])
+        strip_current_encoding_part message
+      end
+    end
+
+    private
+    def is_binary?(message)
+      message[:data].kind_of?(String) && message[:data].encoding == Encoding::ASCII_8BIT
+    end
+
+    def is_base64_encoded?(message)
+      current_encoding_part(message).to_s.match(/^#{ENCODING_ID}$/i)
+    end
+
+    def transport_protocol_text?
+      !client.protocol_binary?
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+module Ably::Models::MessageEncoders
+  # Cipher Encoder & Decoder that automatically encrypts & decrypts messages using Ably::Util::Crypto
+  # when a channel has option encrypted: true.
+  #
+  class Cipher < Base
+    ENCODING_ID = 'cipher'
+
+    def initialize(*args)
+      super
+      @cryptos = Hash.new
+    end
+
+    def encode(message, channel_options)
+      return if is_empty?(message)
+      return if already_encrypted?(message)
+
+      if channel_configured_for_encryption?(channel_options)
+        add_encoding_to_message 'utf-8', message unless is_binary?(message) || is_utf8_encoded?(message)
+
+        crypto = crypto_for(channel_options)
+        message[:data] = crypto.encrypt(message[:data])
+        add_encoding_to_message "#{ENCODING_ID}+#{crypto.cipher_type.downcase}", message
+      end
+    rescue ArgumentError => e
+      raise Ably::Exceptions::CipherError.new(e.message, nil, 92005)
+    rescue RuntimeError => e
+      if e.message.match(/unsupported cipher algorithm/i)
+        raise Ably::Exceptions::CipherError.new(e.message, nil, 92004)
+      end
+    end
+
+    def decode(message, channel_options)
+      if is_cipher_encoded?(message)
+        unless channel_configured_for_encryption?(channel_options)
+          raise Ably::Exceptions::CipherError.new('Message cannot be decrypted as the channel is not set up for encryption & decryption', nil, 92001)
+        end
+
+        crypto = crypto_for(channel_options)
+        unless crypto.cipher_type == cipher_algorithm(message).upcase
+          raise Ably::Exceptions::CipherError.new("Cipher algorithm #{crypto.cipher_type} does not match message cipher algorithm of #{cipher_algorithm(message).upcase}", nil, 92002)
+        end
+
+        message[:data] = crypto.decrypt(message[:data])
+        message[:data].force_encoding(Encoding::ASCII_8BIT) if is_binary?(message)
+        strip_current_encoding_part message
+      end
+    rescue OpenSSL::Cipher::CipherError => e
+      raise Ably::Exceptions::CipherError.new("CipherError decrypting data, the private key may not be correct", nil, 92003)
+    end
+
+    private
+    def is_binary?(message)
+      message.fetch(:data, '').encoding == Encoding::ASCII_8BIT
+    end
+
+    def is_utf8_encoded?(message)
+      current_encoding_part(message).to_s.match(/^utf-8$/i)
+    end
+
+    def crypto_for(channel_options)
+      @cryptos[channel_options.fetch(:cipher_params, :default)] ||= Ably::Util::Crypto.new(channel_options.fetch(:cipher_params, {}))
+    end
+
+    def channel_configured_for_encryption?(channel_options)
+      channel_options.fetch(:encrypted, false)
+    end
+
+    def is_cipher_encoded?(message)
+      !cipher_algorithm(message).nil?
+    end
+
+    def cipher_algorithm(message)
+      current_encoding_part(message).to_s[/^#{ENCODING_ID}\+([\w\d_-]+)$/, 1]
+    end
+
+    def already_encrypted?(message)
+      message.fetch(:encoding, '').to_s.match(%r{(^|/)#{ENCODING_ID}\+([\w\d_-]+)($|/)})
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+require 'json'
+
+module Ably::Models::MessageEncoders
+  # JSON Encoder and Decoder
+  # Uses encoding identifier 'json' and encodes all objects that are not strings or byte arrays
+  #
+  class Json < Base
+    ENCODING_ID = 'json'
+
+    def encode(message, channel_options)
+      if needs_json_encoding?(message)
+        message[:data] = ::JSON.dump(message[:data])
+        add_encoding_to_message ENCODING_ID, message
+      end
+    end
+
+    def decode(message, channel_options)
+      if is_json_encoded?(message)
+        message[:data] = ::JSON.parse(message[:data])
+        strip_current_encoding_part message
+      end
+    end
+
+    private
+    def needs_json_encoding?(message)
+      !message[:data].kind_of?(String) && !message[:data].nil?
+    end
+
+    def is_json_encoded?(message)
+      current_encoding_part(message).to_s.match(/^#{ENCODING_ID}$/i)
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+require 'json'
+
+module Ably::Models::MessageEncoders
+  # Utf8 Encoder and Decoder
+  # Uses encoding identifier 'utf-8' and encodes all JSON objects as UTF-8, and sets the encoding when decoding
+  #
+  class Utf8 < Base
+    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
+    end
+
+    def decode(message, channel_options)
+      if is_utf8_encoded?(message)
+        message[:data] = message[:data].force_encoding(Encoding::UTF_8)
+        strip_current_encoding_part message
+      end
+    end
+
+    private
+    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/paginated_resource.rb

@@ -1,6 +1,6 @@
 module Ably::Models
   # Wraps any Ably HTTP response that supports paging and automatically provides methdos to iterated through
-  # the array of resources using {#first}, {#next}, {#last?} and {#first?}
+  # the array of resources using {#first_page}, {#next_page}, {#first_page?} and {#last_page?}
   #
   # Paging information is provided by Ably in the LINK HTTP headers
   class PaginatedResource
@@ -13,12 +13,13 @@ module Ably::Models
     # @option options [Symbol,String] :coerce_into symbol or string representing class that should be used to create each item in the PaginatedResource
     #
     # @return [PaginatedResource]
-    def initialize(http_response, base_url, client, options = {})
+    def initialize(http_response, base_url, client, options = {}, &each_block)
       @http_response = http_response
       @client        = client
       @base_url      = "#{base_url.gsub(%r{/[^/]*$}, '')}/"
       @coerce_into   = options[:coerce_into]
       @raw_body      = http_response.body
+      @each_block    = each_block
 
       @body = if @coerce_into
         http_response.body.map do |item|
@@ -27,21 +28,25 @@ module Ably::Models
       else
         http_response.body
       end
+
+      @body = @body.map do |resource|
+        each_block.call(resource)
+      end if block_given?
     end
 
     # Retrieve the first page of results
     #
     # @return [PaginatedResource]
     def first_page
-      PaginatedResource.new(client.get(pagination_url('first')), base_url, client, coerce_into: coerce_into)
+      PaginatedResource.new(client.get(pagination_url('first')), base_url, client, coerce_into: coerce_into, &each_block)
     end
 
     # Retrieve the next page of results
     #
     # @return [PaginatedResource]
     def next_page
-      raise Ably::Exceptions::InvalidPageError, "There are no more pages" if supports_pagination? && last_page?
-      PaginatedResource.new(client.get(pagination_url('next')), base_url, client, coerce_into: coerce_into)
+      raise Ably::Exceptions::InvalidPageError, 'There are no more pages' if supports_pagination? && last_page?
+      PaginatedResource.new(client.get(pagination_url('next')), base_url, client, coerce_into: coerce_into, &each_block)
     end
 
     # True if this is the last page in the paged resource set
@@ -100,8 +105,20 @@ module Ably::Models
       body.last
     end
 
+    def inspect
+      <<-EOF.gsub(/^        /, '')
+        #<#{self.class.name}:#{self.object_id}
+         @base_url="#{base_url}",
+         @first_page?=#{!!first_page?},
+         @last_page?=#{!!first_page?},
+         @body=
+           #{body.map { |item| item.inspect }.join(",\n           ") }
+        >
+      EOF
+    end
+
     private
-    attr_reader :body, :http_response, :base_url, :client, :coerce_into, :raw_body
+    attr_reader :body, :http_response, :base_url, :client, :coerce_into, :raw_body, :each_block
 
     def pagination_headers
       link_regex = %r{<(?<url>[^>]+)>; rel="(?<rel>[^"]+)"}

data/lib/ably/models/presence_message.rb

@@ -25,8 +25,11 @@ module Ably::Models
   #   @return [String] The client_id associated with this presence state
   # @!attribute [r] member_id
   #   @return [String] A unique member identifier, disambiguating situations where a given client_id is present on multiple connections simultaneously
-  # @!attribute [r] client_data
+  # @!attribute [r] data
   #   @return [Object] Optional client-defined status or other event payload associated with this state
+  # @!attribute [r] encoding
+  #   @return [Object] The encoding for the message data. Encoding and decoding of messages is handled automatically by the client library.
+  #                    Therefore, the `encoding` attribute should always be nil unless an Ably library decoding error has occurred.
   # @!attribute [r] timestamp
   #   @return [Time] Timestamp when the message was received by the Ably the real-time service
   # @!attribute [r] hash
@@ -34,6 +37,7 @@ module Ably::Models
   #
   class PresenceMessage
     include Ably::Modules::ModelCommon
+    include Ably::Modules::Encodeable
     include EventMachine::Deferrable
     extend Ably::Modules::Enum
 
@@ -51,10 +55,11 @@ module Ably::Models
     def initialize(hash_object, protocol_message = nil)
       @protocol_message = protocol_message
       @raw_hash_object  = hash_object
-      @hash_object      = IdiomaticRubyWrapper(hash_object.clone.freeze, stop_at: [:data])
+
+      set_hash_object hash_object
     end
 
-    %w( client_id member_id client_data ).each do |attribute|
+    %w( client_id member_id data encoding ).each do |attribute|
       define_method attribute do
         hash[attribute.to_sym]
       end
@@ -82,11 +87,12 @@ module Ably::Models
 
     # Return a JSON ready object from the underlying #hash using Ably naming conventions for keys
     def as_json(*args)
-      hash.dup.tap do |hash|
-        hash['action'] = action.to_i
+      hash.dup.tap do |presence_message|
+        presence_message['action'] = action.to_i
+        decode_binary_data_before_to_json presence_message
       end.as_json
     rescue KeyError
-      raise KeyError, ":action is missing or invalid, cannot generate a valid Hash for ProtocolMessage"
+      raise KeyError, ':action is missing or invalid, cannot generate a valid Hash for ProtocolMessage'
     end
 
     # Assign this presence message to a ProtocolMessage before delivery to the Ably system
@@ -106,11 +112,13 @@ module Ably::Models
     # @return [Ably::Models::ProtocolMessage]
     # @api private
     def protocol_message
-      raise RuntimeError, "Presence Message is not yet published with a ProtocolMessage. ProtocolMessage is nil" if @protocol_message.nil?
+      raise RuntimeError, 'Presence Message is not yet published with a ProtocolMessage. ProtocolMessage is nil' if @protocol_message.nil?
       @protocol_message
     end
 
     private
+    attr_reader :raw_hash_object
+
     def protocol_message_index
       protocol_message.presence.index(self)
     end
@@ -122,5 +130,9 @@ module Ably::Models
     def message_serial
       protocol_message.message_serial
     end
+
+    def set_hash_object(hash)
+      @hash_object = IdiomaticRubyWrapper(hash.clone.freeze, stop_at: [:data])
+    end
   end
 end

data/lib/ably/models/protocol_message.rb

@@ -33,6 +33,7 @@ module Ably::Models
   #
   class ProtocolMessage
     include Ably::Modules::ModelCommon
+    include EventMachine::Deferrable
     extend Ably::Modules::Enum
 
     # Actions which are sent by the Ably Realtime API
@@ -67,7 +68,7 @@ module Ably::Models
       @raw_hash_object = hash_object
       @hash_object     = IdiomaticRubyWrapper(@raw_hash_object.clone)
 
-      raise ArgumentError, "Invalid ProtocolMessage, action cannot be nil" if @hash_object[:action].nil?
+      raise ArgumentError, 'Invalid ProtocolMessage, action cannot be nil' if @hash_object[:action].nil?
       @hash_object[:action] = ACTION(@hash_object[:action]).to_i unless @hash_object[:action].kind_of?(Integer)
 
       @hash_object.freeze
@@ -80,7 +81,7 @@ module Ably::Models
     end
 
     def id!
-      raise RuntimeError, "ProtocolMessage #id is nil" unless id
+      raise RuntimeError, 'ProtocolMessage #id is nil' unless id
       id
     end
 
@@ -168,8 +169,8 @@ module Ably::Models
 
     # Return a JSON ready object from the underlying #hash using Ably naming conventions for keys
     def as_json(*args)
-      raise TypeError, ":action is missing, cannot generate a valid Hash for ProtocolMessage" unless action
-      raise TypeError, ":msg_serial or :connection_serial is missing, cannot generate a valid Hash for ProtocolMessage" if ack_required? && !has_serial?
+      raise TypeError, ':action is missing, cannot generate a valid Hash for ProtocolMessage' unless action
+      raise TypeError, ':msg_serial or :connection_serial is missing, cannot generate a valid Hash for ProtocolMessage' if ack_required? && !has_serial?
 
       hash.dup.tap do |hash_object|
         hash_object['action']   = action.to_i