ably 0.8.8 → 0.8.9

data/lib/ably/modules/async_wrapper.rb

@@ -2,7 +2,7 @@ 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}.
+  # {http://www.rubydoc.info/github/eventmachine/eventmachine/EventMachine#defer-class_method EventMachine#defer}.
   # The async_wrap method can only be called from within an EventMachine reactor, and must be thread safe.
   #
   # @note using this AsyncWrapper should only be used for methods that are used less frequently and typically

data/lib/ably/modules/encodeable.rb

@@ -5,9 +5,9 @@ module Ably::Modules
   # Provides methods to allow this model's `data` property to be encoded and decoded based on the `encoding` property.
   #
   # This module expects the following:
-  # - A #hash method that returns the underlying hash object
-  # - A #set_hash_object(hash) method that updates the underlying hash object
-  # - A #raw_hash_object attribute that returns the original hash used to create this object
+  # - A #attributes method that returns the underlying hash object
+  # - A #set_attributes_object(attributes) method that updates the underlying hash object
+  # - A #raw_hash_object attribute that returns the original hash object used to create this object
   #
   module Encodeable
     # Encode a message using the channel options and register encoders for the client
@@ -46,20 +46,20 @@ module Ably::Modules
 
     def apply_encoders(method, channel)
       max_encoding_length = 512
-      message_hash = hash.dup
+      message_attributes = attributes.dup
 
       begin
-        if message_hash[:encoding].to_s.length > max_encoding_length
-          raise Ably::Exceptions::EncoderError("Encoding error, encoding value is too long: '#{message_hash[:encoding]}'", nil, 92100)
+        if message_attributes[:encoding].to_s.length > max_encoding_length
+          raise Ably::Exceptions::EncoderError("Encoding error, encoding value is too long: '#{message_attributes[:encoding]}'", nil, 92100)
         end
 
-        previous_encoding = message_hash[:encoding]
+        previous_encoding = message_attributes[:encoding]
         channel.client.encoders.each do |encoder|
-          encoder.send method, message_hash, channel.options
+          encoder.send method, message_attributes, channel.options
         end
-      end until previous_encoding == message_hash[:encoding]
+      end until previous_encoding == message_attributes[:encoding]
 
-      set_hash_object message_hash
+      set_attributes_object message_attributes
     rescue Ably::Exceptions::CipherError => cipher_error
       if channel.respond_to?(:emit)
         channel.client.logger.error "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"

data/lib/ably/modules/model_common.rb

@@ -12,24 +12,32 @@ module Ably::Modules
     #
     # @return [Object]
     def [](key)
-      hash[key]
+      attributes[key]
     end
 
     def ==(other)
       other.kind_of?(self.class) &&
-        hash == other.hash
+        attributes == other.attributes
     end
 
-    # Return a JSON ready object from the underlying #hash using Ably naming conventions for keys
+    # Return a JSON ready object from the underlying #attributes using Ably naming conventions for keys
+    # @return [Hash]
     def as_json
-      hash.as_json.reject { |key, val| val.nil? }
+      attributes.as_json.reject { |key, val| val.nil? }
     end
 
-    # Stringify the JSON representation of this object from the underlying #hash
+    # Stringify the JSON representation of this object from the underlying #attributes
+    # @return [String]
     def to_json(*args)
       as_json.to_json(*args)
     end
 
+    # @!attribute [r] hash
+    # @return [Integer] Compute a hash-code for this hash. Two hashes with the same content will have the same hash code
+    def hash
+      attributes.hash
+    end
+
     private
     def ensure_utf8_string_for(attribute, value)
       if value

data/lib/ably/realtime/channel.rb

@@ -82,8 +82,7 @@ module Ably
       # @param  client [Ably::Rest::Client]
       # @param  name [String] The name of the channel
       # @param  channel_options [Hash]     Channel options, currently reserved for Encryption options
-      # @option channel_options [Boolean]  :encrypted       setting this to true for this channel will encrypt & decrypt all messages automatically
-      # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +cipher_params+ options
+      # @option channel_options [Hash,Ably::Models::CipherParams]   :cipher   A hash of options or a {Ably::Models::CipherParams} to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +:cipher+ options
       #
       def initialize(client, name, channel_options = {})
         ensure_utf_8 :name, name

data/lib/ably/realtime/presence.rb

@@ -59,26 +59,16 @@ module Ably::Realtime
     # Enter this client into this channel. This client will be added to the presence set
     # and presence subscribers will see an enter message for this client.
     #
-    # @param [Hash] options an options Hash to specify client data and/or client ID
-    # @option options [String] :data      optional data (eg a status message) for this member
-    # @option options [String] :client_id the optional id of the client.
-    #                                     This option is provided to support connections from server instances that act on behalf of
-    #                                     multiple client_ids. In order to be able to enter the channel with this method, the client
-    #                                     library must have been instanced either with a key, or with a token bound to the wildcard clientId.
+    # @param [String,Hash,nil]   data   optional data (eg a status message) for this member
     #
     # @yield [Ably::Realtime::Presence] On success, will call the block with this {Ably::Realtime::Presence} object
     # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks
     #
-    def enter(options = {}, &success_block)
-      client_id  = options.fetch(:client_id, self.client_id)
-      data       = options.fetch(:data, nil)
+    def enter(data = nil, &success_block)
       deferrable = create_deferrable
 
-      ensure_supported_client_id client_id
-      ensure_supported_payload data unless data.nil?
-
+      ensure_supported_payload data
       @data = data
-      @client_id = client_id
 
       return deferrable_succeed(deferrable, &success_block) if state == STATE.Entered
 
@@ -94,8 +84,8 @@ module Ably::Realtime
             Ably::Models::PresenceMessage::ACTION.Enter,
             deferrable:   deferrable,
             target_state: STATE.Entered,
-            client_id:    client_id,
             data:         data,
+            client_id:    client_id,
             failed_state: STATE.Failed,
             &success_block
           )
@@ -111,36 +101,30 @@ module Ably::Realtime
     # either with a key, or with a token bound to the wildcard client_id
     #
     # @param [String]  client_id   id of the client
-    #
-    # @param [Hash]    options         an options Hash for this client event
-    # @option options [String] :data   optional data (eg a status message) for this member
+    # @param [String,Hash,nil]   data   optional data (eg a status message) for this member
     #
     # @yield [Ably::Realtime::Presence] On success, will call the block with this {Ably::Realtime::Presence} object
     # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks
     #
-    def enter_client(client_id, options = {}, &success_block)
-      raise ArgumentError, 'options must be a Hash' unless options.kind_of?(Hash)
+    def enter_client(client_id, data = nil, &success_block)
       ensure_supported_client_id client_id
-      ensure_supported_payload options[:data] if options.has_key?(:data)
+      ensure_supported_payload data
 
-      send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Enter, client_id, options, &success_block)
+      send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Enter, client_id, data, &success_block)
     end
 
     # Leave this client from this channel. This client will be removed from the presence
     # set and presence subscribers will see a leave message for this client.
     #
-    # @param [Hash,String] options an options Hash to specify client data and/or client ID
-    # @option options [String] :data      optional data (eg a status message) for this member
+    # @param (see Presence#enter)
     #
     # @yield (see Presence#enter)
     # @return (see Presence#enter)
     #
-    def leave(options = {}, &success_block)
-      data       = options.fetch(:data, self.data) # nil value defaults leave data to existing value
+    def leave(data = nil, &success_block)
       deferrable = create_deferrable
 
-      ensure_supported_client_id client_id
-      ensure_supported_payload data unless data.nil?
+      ensure_supported_payload data
       raise Ably::Exceptions::Standard.new('Unable to leave presence channel that is not entered', 400, 91002) unless able_to_leave?
 
       @data = data
@@ -159,8 +143,8 @@ module Ably::Realtime
             Ably::Models::PresenceMessage::ACTION.Leave,
             deferrable:   deferrable,
             target_state: STATE.Left,
-            client_id:    client_id,
             data:         data,
+            client_id:    client_id,
             failed_state: STATE.Failed,
             &success_block
           )
@@ -172,35 +156,30 @@ module Ably::Realtime
     # presence set and presence subscribers will see a leave message for this client.
     #
     # @param (see Presence#enter_client)
-    # @option options (see Presence#enter_client)
     #
     # @yield (see Presence#enter_client)
     # @return (see Presence#enter_client)
     #
-    def leave_client(client_id, options = {}, &success_block)
-      raise ArgumentError, 'options must be a Hash' unless options.kind_of?(Hash)
+    def leave_client(client_id, data = nil, &success_block)
       ensure_supported_client_id client_id
-      ensure_supported_payload options[:data] if options.has_key?(:data)
+      ensure_supported_payload data
 
-      send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Leave, client_id, options, &success_block)
+      send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Leave, client_id, data, &success_block)
     end
 
     # Update the presence data for this client. If the client is not already a member of
     # the presence set it will be added, and presence subscribers will see an enter or
     # update message for this client.
     #
-    # @param [Hash,String] options an options Hash to specify client data
-    # @option options [String] :data      optional data (eg a status message) for this member
+    # @param (see Presence#enter)
     #
     # @yield (see Presence#enter)
     # @return (see Presence#enter)
     #
-    def update(options = {}, &success_block)
-      data       = options.fetch(:data, nil)
+    def update(data = nil, &success_block)
       deferrable = create_deferrable
 
-      ensure_supported_client_id client_id
-      ensure_supported_payload data unless data.nil?
+      ensure_supported_payload data
 
       @data = data
 
@@ -224,17 +203,15 @@ module Ably::Realtime
     # enables it to represent an arbitrary clientId.
     #
     # @param (see Presence#enter_client)
-    # @option options (see Presence#enter_client)
     #
     # @yield (see Presence#enter_client)
     # @return (see Presence#enter_client)
     #
-    def update_client(client_id, options = {}, &success_block)
-      raise ArgumentError, 'options must be a Hash' unless options.kind_of?(Hash)
+    def update_client(client_id, data = nil, &success_block)
       ensure_supported_client_id client_id
-      ensure_supported_payload options[:data] if options.has_key?(:data)
+      ensure_supported_payload data
 
-      send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Update, client_id, options, &success_block)
+      send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Update, client_id, data, &success_block)
     end
 
     # Get the presence state for this Channel.
@@ -344,8 +321,8 @@ module Ably::Realtime
     end
 
     # @return [Ably::Models::PresenceMessage] presence message is returned allowing callbacks to be added
-    def send_presence_protocol_message(presence_action, client_id, options = {})
-      presence_message = create_presence_message(presence_action, client_id, options)
+    def send_presence_protocol_message(presence_action, client_id, data)
+      presence_message = create_presence_message(presence_action, client_id, data)
       unless presence_message.client_id
         raise Ably::Exceptions::Standard.new('Unable to enter create presence message without a client_id', 400, 91000)
       end
@@ -361,12 +338,12 @@ module Ably::Realtime
       presence_message
     end
 
-    def create_presence_message(action, client_id, options = {})
+    def create_presence_message(action, client_id, data)
       model = {
         action:   Ably::Models::PresenceMessage.ACTION(action).to_i,
-        clientId: client_id
+        clientId: client_id,
+        data:     data
       }
-      model.merge!(data: options.fetch(:data)) if options.has_key?(:data)
 
       Ably::Models::PresenceMessage.new(model, logger: logger).tap do |presence_message|
         presence_message.encode self.channel
@@ -406,13 +383,7 @@ module Ably::Realtime
       target_state = options.fetch(:target_state, nil)
       failed_state = options.fetch(:failed_state, nil)
 
-      protocol_message_options = if options.has_key?(:data)
-        { data: options.fetch(:data) }
-      else
-        { }
-      end
-
-      send_presence_protocol_message(action, client_id, protocol_message_options).tap do |protocol_message|
+      send_presence_protocol_message(action, client_id, options[:data]).tap do |protocol_message|
         protocol_message.callback do |message|
           change_state target_state, message if target_state
           deferrable_succeed deferrable, &success_block
@@ -437,12 +408,12 @@ module Ably::Realtime
       deferrable
     end
 
-    def send_presence_action_for_client(action, client_id, options = {}, &success_block)
+    def send_presence_action_for_client(action, client_id, data, &success_block)
       ensure_presence_publishable_on_connection
 
       deferrable = create_deferrable
       ensure_channel_attached(deferrable) do
-        send_presence_protocol_message(action, client_id, options).tap do |protocol_message|
+        send_presence_protocol_message(action, client_id, data).tap do |protocol_message|
           protocol_message.callback { |message| deferrable_succeed deferrable, &success_block }
           protocol_message.errback  { |error| deferrable_fail deferrable, error }
         end

data/lib/ably/realtime/presence/members_map.rb

@@ -60,8 +60,8 @@ module Ably::Realtime
       # Get the list of presence members
       #
       # @param [Hash,String] options an options Hash to filter members
-      # @option options [String] :client_id      optional client_id for the member
-      # @option options [String] :connection_id  optional connection_id for the member
+      # @option options [String] :client_id      optional client_id filter for the member
+      # @option options [String] :connection_id  optional connection_id filter for the member
       # @option options [String] :wait_for_sync  defaults to false, if true the get method waits for the initial presence sync following channel attachment to complete before returning the members present
       #
       # @yield [Array<Ably::Models::PresenceMessage>] array of present members

data/lib/ably/rest/channel.rb

@@ -19,8 +19,7 @@ module Ably
       # @param client [Ably::Rest::Client]
       # @param name [String] The name of the channel
       # @param channel_options [Hash] Channel options, currently reserved for Encryption options
-      # @option channel_options [Boolean]  :encrypted       setting this to true for this channel will encrypt & decrypt all messages automatically
-      # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +cipher_params+ options
+      # @option channel_options [Hash,Ably::Models::CipherParams]   :cipher   A hash of options or a {Ably::Models::CipherParams} to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +:cipher+ options
       #
       def initialize(client, name, channel_options = {})
         ensure_utf_8 :name, name

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

@@ -30,12 +30,22 @@ module Ably
 
             message = 'Unknown server error' if message.to_s.strip == ''
 
+            exception_args = [message, error_status_code, error_code]
+
             if env.status >= 500
-              raise Ably::Exceptions::ServerError.new(message, error_status_code, error_code)
-            elsif env.status == 401 && TOKEN_EXPIRED_CODE.include?(error_code)
-              raise Ably::Exceptions::TokenExpired.new(message, error_status_code, error_code)
+              raise Ably::Exceptions::ServerError.new(*exception_args)
+            elsif env.status == 401
+              if TOKEN_EXPIRED_CODE.include?(error_code)
+                raise Ably::Exceptions::TokenExpired.new(*exception_args)
+              else
+                raise Ably::Exceptions::UnauthorizedRequest.new(*exception_args)
+              end
+            elsif env.status == 403
+              raise Ably::Exceptions::ForbiddenRequest.new(*exception_args)
+            elsif env.status == 404
+              raise Ably::Exceptions::ResourceMissing.new(*exception_args)
             else
-              raise Ably::Exceptions::InvalidRequest.new(message, error_status_code, error_code)
+              raise Ably::Exceptions::InvalidRequest.new(*exception_args)
             end
           end
         end

data/lib/ably/rest/presence.rb

@@ -23,7 +23,9 @@ module Ably
       # Obtain the set of members currently present for a channel
       #
       # @param [Hash] options the options for the set of members present
-      # @option options [Integer]      :limit      Maximum number of members to retrieve up to 1,000, defaults to 100
+      # @option options [Integer]   :limit           Maximum number of members to retrieve up to 1,000, defaults to 100
+      # @option options [String]    :client_id       optional client_id filter for the member
+      # @option options [String]    :connection_id   optional connection_id filter for the member
       #
       # @return [Ably::Models::PaginatedResult<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResult page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResult#items #items}.
       #

data/lib/ably/util/crypto.rb

@@ -4,52 +4,65 @@ require 'openssl'
 module Ably::Util
   class Crypto
     DEFAULTS = {
-      algorithm: 'AES',
-      mode: 'CBC',
-      key_length: 128,
+      algorithm: 'aes',
+      mode: 'cbc',
+      key_length: 256,
     }
 
     BLOCK_LENGTH = 16
 
-    # Configured options for this Crypto object, see {#initialize} for a list of configured options
+    # Configured {Ably::Models::CipherParams} for this Crypto object, see {#initialize} for a list of configureable options
     #
-    # @return [Hash]
-    attr_reader :options
+    # @return [Ably::Models::CipherParams]
+    attr_reader :cipher_params
 
     # Creates a {Ably::Util::Crypto} object
     #
-    # @param [Hash] options an options Hash used to configure the Crypto library
-    # @option options [String]  :key                 Required secret key used for encrypting and decrypting
-    # @option options [String]  :algorithm           optional (default AES), specify the encryption algorithm supported by {http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html OpenSSL::Cipher}
-    # @option options [String]  :mode                optional (default CBC), specify the cipher mode supported by {http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html OpenSSL::Cipher}
-    # @option options [Integer] :key_length          optional (default 128), specify the key length of the cipher supported by {http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html OpenSSL::Cipher}
-    # @option options [String]  :combined            optional (default AES-128-CBC), specify in one option the algorithm, key length and cipher of the cipher supported by {http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html OpenSSL::Cipher}
+    # @param [Hash] params a Hash used to configure the Crypto library's {Ably::Models::CipherParams}
+    # @option params (see Ably::Models::CipherParams#initialize)
     #
     # @return [Ably::Util::Crypto]
     #
     # @example
-    #    crypto = Ably::Util::Crypto.new(key: 'mysecret')
+    #    key = Ably::Util::Crypto.generate_random_key
+    #    crypto = Ably::Util::Crypto.new(key: key)
     #    encrypted = crypto.encrypt('secret text')
     #    crypto.decrypt(decrypted) # => 'secret text'
     #
-    def initialize(options)
-      raise ArgumentError, ':key is required' unless options.has_key?(:key)
-      @options = DEFAULTS.merge(options).freeze
+    def initialize(params)
+      @fixed_iv = params.delete(:fixed_iv) if params.kind_of?(Hash)
+      @cipher_params = Ably::Models::CipherParams(params)
     end
 
-    # Obtain a default CipherParams. This uses default algorithm, mode and
-    # padding and key length. A key and IV are generated using the default
-    # system SecureRandom; the key may be obtained from the returned CipherParams
+    # Obtain a default {Ably::Models::CipherParams}. This uses default algorithm, mode and
+    # padding and key length. An IV is generated using the default
+    # system SecureRandom; the key may be obtained from the returned {Ably::Models::CipherParams}
     # for out-of-band distribution to other clients.
+
+    # @param [Hash]  params  a Hash used to configure the Crypto library's {Ably::Models::CipherParams}
+    # @option params  (see Ably::Models::CipherParams#initialize)
+    #
+    # @return [Ably::Models::CipherParams]   Configured cipher params with :key, :algorithm, :mode, :key_length attributes
+    #
+    def self.get_default_params(params = {})
+      Ably::Models::CipherParams(params)
+    end
+
+    # Generate a random encryption key from the supplied keylength (or the
+    # default key_length of 256 if none supplied)
     #
-    # @return [Hash]   CipherParam options Hash with attributes :key, :algorithn, :mode, :key_length
+    # @param  [Integer]  key_length  Optional (default 256) key length for the generated random key. 128 and 256 bit key lengths are supported
+    # @return   Binary   String (byte array) with ASCII_8BIT encoding
     #
-    def self.get_default_params(key = nil)
-      params = DEFAULTS.merge(key: key)
-      params[:key_length] = key.unpack('b*').first.length if params[:key]
-      cipher_type = "#{params[:algorithm]}-#{params[:key_length]}-#{params[:mode]}"
-      params[:key] = OpenSSL::Cipher.new(cipher_type.upcase).random_key unless params[:key]
-      params
+    def self.generate_random_key(key_length = DEFAULTS.fetch(:key_length))
+      params = DEFAULTS.merge(key_length: key_length)
+      OpenSSL::Cipher.new(cipher_type(params)).random_key
+    end
+
+    # The Cipher algorithm string such as AES-128-CBC
+    # @api private
+    def self.cipher_type(options)
+      Ably::Models::CipherParams.cipher_type(options)
     end
 
     # Encrypt payload using configured Cipher
@@ -58,13 +71,13 @@ module Ably::Util
     # @param [Hash]   encrypt_options   an options Hash to configure the encrypt action
     # @option encrypt_options [String]  :iv optionally use the provided Initialization Vector instead of a randomly generated IV
     #
-    # @return [String] binary string with {Encoding::ASCII_8BIT} encoding
+    # @return [String] binary string with +Encoding::ASCII_8BIT+ encoding
     #
     def encrypt(payload, encrypt_options = {})
       cipher = openssl_cipher
       cipher.encrypt
       cipher.key = key
-      iv = encrypt_options[:iv] || options[:iv] || cipher.random_iv
+      iv = encrypt_options[:iv] || fixed_iv || cipher.random_iv
       cipher.iv = iv
 
       iv << cipher.update(payload) << cipher.final
@@ -90,31 +103,28 @@ module Ably::Util
       decipher.update(encrypted_payload) << decipher.final
     end
 
-    # Generate a random key
-    # @return [String]
-    def random_key
-      openssl_cipher.random_key
-    end
-
     # Generate a random IV
     # @return [String]
     def random_iv
       openssl_cipher.random_iv
     end
 
-    # The Cipher algorithm string such as AES-128-CBC
+    private
+    # Used solely for tests to fix the IV instead of randomly generate one
+    attr_reader :fixed_iv
+
+    # Generate a random key
     # @return [String]
-    def cipher_type
-      (options[:combined] || "#{options[:algorithm]}-#{options[:key_length]}-#{options[:mode]}").to_s.upcase
+    def random_key
+      openssl_cipher.random_key
     end
 
-    private
     def key
-      options[:key]
+      cipher_params.key
     end
 
     def openssl_cipher
-      OpenSSL::Cipher.new(cipher_type)
+      @openssl_cipher ||= OpenSSL::Cipher.new(cipher_params.cipher_type)
     end
   end
 end