lib/ably/rest/client.rb in ably-0.1.5 vs lib/ably/rest/client.rb in ably-0.1.6

- old
+ new

@@ -12,33 +12,41 @@ # @return {Ably::Auth} authentication object configured for this connection # @!attribute [r] client_id # @return [String] A client ID, used for identifying this client for presence purposes # @!attribute [r] auth_options # @return [Hash] {Ably::Auth} options configured for this client - # @!attribute [r] tls - # @return [Boolean] True if client is configured to use TLS for all Ably communication # @!attribute [r] environment # @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 class Client include Ably::Modules::Conversions include Ably::Modules::HttpHelpers extend Forwardable DOMAIN = "rest.ably.io" - attr_reader :tls, :environment, :protocol, :auth, :channels, :log_level + attr_reader :environment, :protocol, :auth, :channels, :log_level def_delegators :auth, :client_id, :auth_options + # The additional options passed to this Client's #initialize method not available as attributes of this class + # @return [Hash] + # @api private + attr_reader :options + # Creates a {Ably::Rest::Client Rest Client} and configures the {Ably::Auth} object for the connection. # # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key # @option options (see Ably::Auth#authorise) - # @option options [Boolean] :tls TLS is used by default, providing a value of false disbles TLS. Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections. - # @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 [Logger::Severity] :log_level Log level for the standard Logger that outputs to STDOUT. Defaults to Logger::WARN, can be set to Logger::FATAL, Logger::ERROR, Logger::WARN, Logger::INFO, Logger::DEBUG + # @option options [Boolean] :tls TLS is used by default, providing a value of false disbles TLS. Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections. + # @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) # # @yield (see Ably::Auth#authorise) # @yieldparam (see Ably::Auth#authorise) # @yieldreturn (see Ably::Auth#authorise) # @@ -51,23 +59,32 @@ # # create a new client and configure a client ID used for presence # client = Ably::Rest::Client.new(api_key: 'key.id:secret', client_id: 'john') # def initialize(options, &auth_block) 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) || :json # TODO: Default to :msgpack when protocol MsgPack support added + @protocol = options.delete(:protocol) || :msgpack @debug_http = options.delete(:debug_http) - @log_level = options.delete(:log_level) || Logger::WARN + @log_level = options.delete(:log_level) || Logger::ERROR + @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 + @protocol = :json + end + end 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) end # Return a REST {Ably::Rest::Channel} for the given name @@ -77,11 +94,11 @@ # @return (see Ably::Rest::Channels#get) def channel(name, channel_options = {}) channels.get(name, channel_options) end - # Return the stats for the application + # Retrieve the stats for the application # # @return [Array] An Array of hashes representing the stats def stats(params = {}) default_params = { :direction => :forwards, @@ -93,22 +110,21 @@ response.body.map do |stat| IdiomaticRubyWrapper(stat) end end - # Return the Ably service time + # Retrieve the Ably service time # # @return [Time] The time as reported by the Ably service def time response = get('/time', {}, send_auth_header: false) as_time_from_epoch(response.body.first) end - # True if client is configured to use TLS for all Ably communication - # - # @return [Boolean] + # @!attribute [r] use_tls? + # @return [Boolean] True if client is configured to use TLS for all Ably communication def use_tls? @tls == true end # Perform an HTTP GET request to the API using configured authentication @@ -123,29 +139,30 @@ # @return [Faraday::Response] def post(path, params, options = {}) request(:post, path, params, options) end - # Default Ably REST endpoint used for all requests - # - # @return [URI::Generic] + # @!attribute [r] endpoint + # @return [URI::Generic] Default Ably REST endpoint used for all requests def endpoint URI::Generic.build( scheme: use_tls? ? "https" : "http", host: [@environment, DOMAIN].compact.join('-') ) end + # @!attribute [r] logger + # @return [Logger] The Logger configured for this client when the client was instantiated. + # 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 end - # Mime type used for HTTP requests - # - # @return [String] + # @!attribute [r] mime_type + # @return [String] Mime type used for HTTP requests def mime_type case protocol when :json 'application/json' else @@ -172,11 +189,11 @@ attempts += 1 if attempts == 1 && e.code == 40140 && auth.token_renewable? auth.authorise force: true retry else - raise Ably::Exceptions::InvalidToken.new(e.message, status: e.status, code: e.code) + raise Ably::Exceptions::InvalidToken.new(e.message, e.status, e.code) end end end # Return a Faraday::Connection to use to make HTTP requests @@ -206,18 +223,18 @@ # Return a Faraday middleware stack to initiate the Faraday::Connection with # # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/ def middleware @middleware ||= Faraday::RackBuilder.new do |builder| - setup_middleware builder + 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 # 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