client.rb in ably-0.2.0

- old
+ new

@@ -18,20 +18,28 @@
     #   @return [String] May contain 'sandbox' when testing the client library against an alternate Ably environment
     # @!attribute [r] log_level
     #   @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
       attr_reader :options
 
@@ -43,10 +51,11 @@
       # @option options [String]                  :api_key             API key comprising the key ID and key secret in a single string
       # @option options [String]                  :environment         Specify 'sandbox' when testing the client library against an alternate Ably environment
       # @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)
       # @yieldreturn (see Ably::Auth#authorise)
       #
@@ -63,17 +72,18 @@
         options = options.clone
         if options.kind_of?(String)
           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
             @protocol = :msgpack
           elsif use_binary_protocol == false
@@ -83,10 +93,13 @@
         raise ArgumentError, 'Protocol is invalid.  Must be either :msgpack or :json' unless [:msgpack, :json].include?(@protocol)
 
         @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
       #
       # @param (see Ably::Rest::Channels#get)
@@ -149,16 +162,14 @@
           host:   [@environment, DOMAIN].compact.join('-')
         )
       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
       # @return [String] Mime type used for HTTP requests
       def mime_type
@@ -168,10 +179,36 @@
         else
           'application/x-msgpack'
         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
           connection.send(method, path, params) do |request|
             unless options[:send_auth_header] == false
@@ -208,12 +245,13 @@
       # @return [Hash]
       def connection_options
         @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,
             timeout:      10
           }
@@ -228,17 +266,18 @@
           setup_outgoing_middleware builder
 
           # Raise exceptions if response code is invalid
           builder.use Ably::Rest::Middleware::Exceptions
 
-          setup_incoming_middleware builder, fail_if_unsupported_mime_type: true
+          setup_incoming_middleware builder, logger, fail_if_unsupported_mime_type: true
 
-          # Log HTTP requests if log level is DEBUG option set
-          builder.response :logger if log_level == Logger::DEBUG
-
           # 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