ably 0.1.6 → 0.2.0

data/lib/ably/rest/channel.rb

@@ -2,6 +2,13 @@ module Ably
   module Rest
     # The Ably Realtime service organises the traffic within any application into named channels.
     # Channels are the "unit" of message distribution; clients attach to channels to subscribe to messages, and every message broadcast by the service is associated with a unique channel.
+    #
+    # @!attribute [r] client
+    #   @return {Ably::Realtime::Client} Ably client associated with this channel
+    # @!attribute [r] name
+    #   @return {String} channel name
+    # @!attribute [r] options
+    #   @return {Hash} channel options configured for this channel, see {#initialize} for channel_options
     class Channel
       include Ably::Modules::Conversions
 
@@ -11,7 +18,10 @@ module Ably
       #
       # @param client [Ably::Rest::Client]
       # @param name [String] The name of the channel
-      # @param channel_options [Hash] Channel options, currently reserved for future Encryption options
+      # @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
+      #
       def initialize(client, name, channel_options = {})
         @client  = client
         @name    = name
@@ -29,7 +39,11 @@ module Ably
           data: data
         }
 
-        response = client.post("#{base_path}/publish", payload)
+        message = Ably::Models::Message.new(payload, nil).tap do |message|
+          message.encode self
+        end
+
+        response = client.post("#{base_path}/publish", message)
 
         [201, 204].include?(response.status)
       end
@@ -52,9 +66,16 @@ module Ably
 
         response = client.get(url, options.merge(merge_options))
 
-        Ably::Models::PaginatedResource.new(response, url, client, coerce_into: 'Ably::Models::Message')
+        Ably::Models::PaginatedResource.new(response, url, client, coerce_into: 'Ably::Models::Message') do |message|
+          message.tap do |message|
+            message.decode self
+          end
+        end
       end
 
+      # Return the {Ably::Rest::Presence} object
+      #
+      # @return [Ably::Rest::Presence]
       def presence
         @presence ||= Presence.new(client, self)
       end

data/lib/ably/rest/client.rb

@@ -20,16 +20,24 @@ module Ably
     #   @return [Logger::Severity] Log level configured for this {Client}
     # @!attribute [r] channels
     #   @return [Aby::Rest::Channels] The collection of {Ably::Rest::Channel}s that have been created
+    # @!attribute [r] protocol
+    #   @return [Symbol] The protocol configured for this client, either binary `:msgpack` or text based `:json`
+    #
     class Client
       include Ably::Modules::Conversions
       include Ably::Modules::HttpHelpers
       extend Forwardable
 
-      DOMAIN = "rest.ably.io"
+      DOMAIN = 'rest.ably.io'
 
       attr_reader :environment, :protocol, :auth, :channels, :log_level
       def_delegators :auth, :client_id, :auth_options
 
+      # @api private
+      # The registered encoders that are used to encode and decode message payloads
+      # @return [Array<Ably::Models::MessageEncoder::Base>]
+      attr_reader :encoders
+
       # The additional options passed to this Client's #initialize method not available as attributes of this class
       # @return [Hash]
       # @api private
@@ -45,6 +53,7 @@ module Ably
       # @option options [Symbol]                  :protocol            Protocol used to communicate with Ably, :json and :msgpack currently supported. Defaults to :msgpack
       # @option options [Boolean]                 :use_binary_protocol Protocol used to communicate with Ably, defaults to true and uses MessagePack protocol.  This option will overide :protocol option
       # @option options [Logger::Severity,Symbol] :log_level           Log level for the standard Logger that outputs to STDOUT.  Defaults to Logger::ERROR, can be set to :fatal (Logger::FATAL), :error (Logger::ERROR), :warn (Logger::WARN), :info (Logger::INFO), :debug (Logger::DEBUG)
+      # @option options [Logger]                  :logger              A custom logger can be used however it must adhere to the Ruby Logger interface, see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html
       #
       # @yield (see Ably::Auth#authorise)
       # @yieldparam (see Ably::Auth#authorise)
@@ -65,13 +74,14 @@ module Ably
           options = { api_key: options }
         end
 
-        @tls                 = options.delete(:tls) == false ? false : true
-        @environment         = options.delete(:environment) # nil is production
-        @protocol            = options.delete(:protocol) || :msgpack
-        @debug_http          = options.delete(:debug_http)
-        @log_level           = options.delete(:log_level) || Logger::ERROR
+        @tls           = options.delete(:tls) == false ? false : true
+        @environment   = options.delete(:environment) # nil is production
+        @protocol      = options.delete(:protocol) || :msgpack
+        @debug_http    = options.delete(:debug_http)
+        @log_level     = options.delete(:log_level) || ::Logger::ERROR
+        @custom_logger = options.delete(:logger)
 
-        @log_level = Logger.const_get(log_level.to_s.upcase) if log_level.kind_of?(Symbol) || log_level.kind_of?(String)
+        @log_level     = ::Logger.const_get(log_level.to_s.upcase) if log_level.kind_of?(Symbol) || log_level.kind_of?(String)
 
         options.delete(:use_binary_protocol).tap do |use_binary_protocol|
           if use_binary_protocol == true
@@ -85,6 +95,9 @@ module Ably
         @options  = options.freeze
         @auth     = Auth.new(self, options, &auth_block)
         @channels = Ably::Rest::Channels.new(self)
+        @encoders = []
+
+        initialize_default_encoders
       end
 
       # Return a REST {Ably::Rest::Channel} for the given name
@@ -151,12 +164,10 @@ module Ably
       end
 
       # @!attribute [r] logger
-      # @return [Logger] The Logger configured for this client when the client was instantiated.
+      # @return [Logger] The {Ably::Logger} for this client.
       #                  Configure the log_level with the `:log_level` option, refer to {Client#initialize}
       def logger
-        @logger ||= Logger.new(STDOUT).tap do |logger|
-          logger.level = log_level
-        end
+        @logger ||= Ably::Logger.new(self, log_level, @custom_logger)
       end
 
       # @!attribute [r] mime_type
@@ -170,6 +181,32 @@ module Ably
         end
       end
 
+      # Register a message encoder and decoder that implements Ably::Models::MessageEncoders::Base interface.
+      # Message encoders are used to encode and decode message payloads automatically.
+      # @note Encoders and decoders are processed in the order they are added so the first encoder will be given priority when encoding and decoding
+      #
+      # @param [Ably::Models::MessageEncoders::Base] encoder
+      # @return [void]
+      #
+      # @api private
+      def register_encoder(encoder)
+        encoder_klass = if encoder.kind_of?(String)
+          Object.const_get(encoder)
+        else
+          encoder
+        end
+
+        raise "Encoder must inherit from `Ably::Models::MessageEncoders::Base`" unless encoder_klass.ancestors.include?(Ably::Models::MessageEncoders::Base)
+
+        encoders << encoder_klass.new(self)
+      end
+
+      # @!attribute [r] protocol_binary?
+      # @return [Boolean] True of the transport #protocol communicates with Ably with a binary protocol
+      def protocol_binary?
+        protocol == :msgpack
+      end
+
       private
       def request(method, path, params = {}, options = {})
         reauthorise_on_authorisation_failure do
@@ -210,8 +247,9 @@ module Ably
         @connection_options ||= {
           builder: middleware,
           headers: {
-            accept:     mime_type,
-            user_agent: user_agent
+            content_type: mime_type,
+            accept:       mime_type,
+            user_agent:   user_agent
           },
           request: {
             open_timeout: 5,
@@ -230,15 +268,16 @@ module Ably
           # Raise exceptions if response code is invalid
           builder.use Ably::Rest::Middleware::Exceptions
 
-          setup_incoming_middleware builder, fail_if_unsupported_mime_type: true
-
-          # Log HTTP requests if log level is DEBUG option set
-          builder.response :logger if log_level == Logger::DEBUG
+          setup_incoming_middleware builder, logger, fail_if_unsupported_mime_type: true
 
           # Set Faraday's HTTP adapter
           builder.adapter Faraday.default_adapter
         end
       end
+
+      def initialize_default_encoders
+        Ably::Models::MessageEncoders.register_default_encoders self
+      end
     end
   end
 end

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

@@ -0,0 +1,49 @@
+require 'faraday'
+require 'json'
+
+module Ably
+  module Rest
+    module Middleware
+      # Encode the body of the message according to the mime type
+      class Encoder < ::Faraday::Response::Middleware
+        CONTENT_TYPE = 'Content-Type'.freeze unless defined? CONTENT_TYPE
+
+        def call(env)
+          encode env if env.body
+          @app.call env
+        end
+
+        private
+        def encode(env)
+          env.body = case request_type(env)
+          when 'application/x-msgpack'
+            to_msgpack(env.body)
+          when 'application/json', '', nil
+            env.request_headers[CONTENT_TYPE] = 'application/json'
+            to_json(env.body)
+          else
+            env.body
+          end
+        end
+
+        def to_msgpack(body)
+          body.to_msgpack
+        end
+
+        def to_json(body)
+          if body.kind_of?(String)
+            body
+          else
+            body.to_json
+          end
+        end
+
+        def request_type(env)
+          type = env.request_headers[CONTENT_TYPE].to_s
+          type = type.split(';', 2).first if type.index(';')
+          type
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,5 @@
-require "json"
+require 'faraday'
+require 'json'
 
 module Ably
   module Rest
@@ -25,7 +26,7 @@ module Ably
               message = env.body
             end
 
-            message = "Unknown server error" if message.to_s.strip == ''
+            message = 'Unknown server error' if message.to_s.strip == ''
 
             if env.status >= 500
               raise Ably::Exceptions::ServerError, message

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

@@ -0,0 +1,37 @@
+require 'faraday'
+
+module Ably
+  module Rest
+    module Middleware
+      class Logger < Faraday::Response::Middleware
+        extend Forwardable
+
+        def initialize(app, logger = nil)
+          super(app)
+          @logger = logger || begin
+            require 'logger'
+            ::Logger.new(STDOUT)
+          end
+        end
+
+        def_delegators :@logger, :debug, :info, :warn, :error, :fatal
+
+        def call(env)
+          debug "=> URL: #{env.method} #{env.url}, Headers: #{dump_headers env.request_headers}"
+          debug "=> Body: #{env.body}"
+          @app.call env
+        end
+
+        def on_complete(env)
+          debug "<= Status: #{env.status}, Headers: #{dump_headers env.response_headers}"
+          debug "<= Body: #{env.body}"
+        end
+
+        private
+        def dump_headers(headers)
+          headers.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+        end
+      end
+    end
+  end
+end

data/lib/ably/rest/presence.rb

@@ -20,7 +20,11 @@ module Ably
       #
       def get(options = {})
         response = client.get(base_path, options)
-        Ably::Models::PaginatedResource.new(response, base_path, client, coerce_into: 'Ably::Models::PresenceMessage')
+        Ably::Models::PaginatedResource.new(response, base_path, client, coerce_into: 'Ably::Models::PresenceMessage') do |presence_message|
+          presence_message.tap do |message|
+            message.decode self.channel
+          end
+        end
       end
 
       # Return the presence messages history for the channel
@@ -41,7 +45,11 @@ module Ably
 
         response = client.get(url, options.merge(merge_options))
 
-        Ably::Models::PaginatedResource.new(response, url, client, coerce_into: 'Ably::Models::PresenceMessage')
+        Ably::Models::PaginatedResource.new(response, url, client, coerce_into: 'Ably::Models::PresenceMessage') do |presence_message|
+          presence_message.tap do |message|
+            message.decode self.channel
+          end
+        end
       end
 
       private

data/lib/ably/util/crypto.rb

@@ -7,67 +7,95 @@ module Ably::Util
       algorithm: 'AES',
       mode: 'CBC',
       key_length: 128,
-      block_length: 16
     }
 
+    BLOCK_LENGTH = 16
+
+    # Configured options for this Crypto object, see {#initialize} for a list of configured options
+    #
+    # @return [Hash]
     attr_reader :options
 
-    def initialize(options = {})
-      raise ArgumentError, ":secret is required" unless options.has_key?(:secret)
+    # 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}
+    #
+    # @return [Ably::Util::Crypto]
+    #
+    # @example
+    #    crypto = Ably::Util::Crypto.new(key: 'mysecret')
+    #    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
     end
 
-    def encrypt(payload)
+    # Encrypt payload using configured Cipher
+    #
+    # @param [String] payload           the payload to be encrypted
+    # @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
+    #
+    def encrypt(payload, encrypt_options = {})
       cipher = openssl_cipher
       cipher.encrypt
-      cipher.key = secret
-      iv = cipher.random_iv
+      cipher.key = key
+      iv = encrypt_options[:iv] || options[:iv] || cipher.random_iv
       cipher.iv = iv
 
-      iv << cipher.update(pack(payload)) << cipher.final
+      iv << cipher.update(payload) << cipher.final
     end
 
+    # Decrypt payload using configured Cipher
+    #
+    # @param [String] encrypted_payload_with_iv  the encrypted payload to be decrypted
+    #
+    # @return [String]
+    #
     def decrypt(encrypted_payload_with_iv)
-      raise Ably::Exceptions::EncryptionError, "iv is missing" unless encrypted_payload_with_iv.length >= block_length*2
+      raise Ably::Exceptions::EncryptionError, 'iv is missing or not long enough' unless encrypted_payload_with_iv.length >= BLOCK_LENGTH*2
 
-      iv = encrypted_payload_with_iv.slice(0..15)
-      encrypted_payload = encrypted_payload_with_iv.slice(16..-1)
+      iv = encrypted_payload_with_iv.slice(0...BLOCK_LENGTH)
+      encrypted_payload = encrypted_payload_with_iv.slice(BLOCK_LENGTH..-1)
 
       decipher = openssl_cipher
       decipher.decrypt
-      decipher.key = secret
+      decipher.key = key
       decipher.iv = iv
 
-      unpack(decipher.update(encrypted_payload) << decipher.final)
+      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
 
-    private
-    def pack(object)
-      object.to_msgpack
-    end
-
-    def unpack(msgpack_binary)
-      MessagePack.unpack(msgpack_binary)
-    end
-
-    def secret
-      options[:secret]
-    end
-
-    def block_length
-      options[:block_length]
+    # The Cipher algorithm string such as AES-128-CBC
+    # @return [String]
+    def cipher_type
+      (options[:combined] || "#{options[:algorithm]}-#{options[:key_length]}-#{options[:mode]}").to_s.upcase
     end
 
-    def cipher_type
-      "#{options[:algorithm]}-#{options[:key_length]}-#{options[:mode]}"
+    private
+    def key
+      options[:key]
     end
 
     def openssl_cipher