ably 0.1.5 → 0.1.6

data/lib/ably/rest.rb

@@ -1,12 +1,20 @@
 require "ably/rest/channel"
 require "ably/rest/channels"
 require "ably/rest/client"
-require "ably/rest/models/message"
-require "ably/rest/models/paged_resource"
-require "ably/rest/models/presence_message"
 require "ably/rest/presence"
 
+Dir.glob(File.expand_path("ably/models/*.rb", File.dirname(__FILE__))).each do |file|
+  require file
+end
+
 module Ably
+  # Rest provides the top-level class to be instanced for the Ably Rest library
+  #
+  # @example
+  #   client = Ably::Rest.new("xxxxx")
+  #   channel = client.channel("test")
+  #   channel.publish "greeting", "data"
+  #
   module Rest
     # Convenience method providing an alias to {Ably::Rest::Client} constructor.
     #
@@ -23,6 +31,9 @@ module Ably
     #    # create a new client authenticating with basic auth
     #    client = Ably::Rest.new('key.id:secret')
     #
+    #    # create a new client authenticating with basic auth and a client_id
+    #    client = Ably::Rest.new(api_key: 'key.id:secret', client_id: 'john')
+    #
     def self.new(options, &auth_block)
       Ably::Rest::Client.new(options, &auth_block)
     end

data/lib/ably/rest/channel.rb

@@ -31,7 +31,7 @@ module Ably
 
         response = client.post("#{base_path}/publish", payload)
 
-        response.status == 201
+        [201, 204].include?(response.status)
       end
 
       # Return the message history of the channel
@@ -43,7 +43,7 @@ module Ably
       # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 10,000
       # @option options [Symbol]       :by         `:message`, `:bundle` or `:hour`. Defaults to `:message`
       #
-      # @return [Models::PagedResource<Models::Message>] An Array of hashes representing the message history that supports paging (next, first)
+      # @return [Ably::Models::PaginatedResource<Ably::Models::Message>] An Array of hashes representing the message history that supports paging (next, first)
       def history(options = {})
         url = "#{base_path}/messages"
 
@@ -52,7 +52,7 @@ module Ably
 
         response = client.get(url, options.merge(merge_options))
 
-        Models::PagedResource.new(response, url, client, coerce_into: 'Ably::Rest::Models::Message')
+        Ably::Models::PaginatedResource.new(response, url, client, coerce_into: 'Ably::Models::Message')
       end
 
       def presence

data/lib/ably/rest/channels.rb

@@ -1,29 +1,43 @@
 module Ably
   module Rest
     class Channels
-      attr_reader :client
+      include Ably::Modules::ChannelsCollection
 
-      # Initialize a new Channels object
-      #
-      # {Ably::Rest::Channels} provides simple accessor methods to access a {Ably::Rest::Channel} object
+      # @return [Ably::Rest::Channels]
       def initialize(client)
-        @client   = client
-        @channels = {}
+        super client, Ably::Rest::Channel
       end
 
-      # Return a REST {Ably::Rest::Channel} for the given name
+      # @!method get(name, channel_options = {})
+      # Return a {Ably::Rest::Channel} for the given name
       #
       # @param name [String] The name of the channel
       # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+      # @return [Ably::Rest::Channel}
+      def get(*args)
+        super
+      end
+
+      # @!method fetch(name, &missing_block)
+      # Return a {Ably::Rest::Channel} for the given name if it exists, else the block will be called.
+      # This method is intentionally similar to {http://ruby-doc.org/core-2.1.3/Hash.html#method-i-fetch Hash#fetch} providing a simple way to check if a channel exists or not without creating one
       #
+      # @param name [String] The name of the channel
+      # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called
+      # @yieldparam [String] name of the missing channel
       # @return [Ably::Rest::Channel]
-      def get(name, channel_options = {})
-        @channels[name] ||= Ably::Rest::Channel.new(client, name, channel_options)
+      def fetch(*args)
+        super
       end
-      alias_method :[], :get
 
-      def close(channel)
-        @channels.delete(channel)
+      # Destroy the {Ably::Rest::Channel} and releases the associated resources.
+      #
+      # Releasing a {Ably::Rest::Channel} is not typically necessary as a channel consumes no resources other than the memory footprint of the
+      # {Ably::Rest::Channel} object. Explicitly release channels to free up resources if required
+      #
+      # @return [void]
+      def release(*args)
+        super
       end
     end
   end

data/lib/ably/rest/client.rb

@@ -14,10 +14,12 @@ module Ably
     #   @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
@@ -25,18 +27,24 @@ module Ably
 
       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)
@@ -53,19 +61,28 @@ module Ably
       #
       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
@@ -79,7 +96,7 @@ module Ably
         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 = {})
@@ -95,7 +112,7 @@ module Ably
         end
       end
 
-      # Return the Ably service time
+      # Retrieve the Ably service time
       #
       # @return [Time] The time as reported by the Ably service
       def time
@@ -104,9 +121,8 @@ module Ably
         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
@@ -125,9 +141,8 @@ module Ably
         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",
@@ -135,15 +150,17 @@ module Ably
         )
       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
@@ -174,7 +191,7 @@ module Ably
             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
@@ -208,16 +225,16 @@ module Ably
       # @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

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

@@ -4,35 +4,33 @@ module Ably
   module Rest
     module Middleware
       # HTTP exceptions raised by Ably due to an error status code
-      # Ably returns JSON error codes and messages so include this if possible in the exception messages
+      # Ably returns JSON/Msgpack error codes and messages so include this if possible in the exception messages
       class Exceptions < Faraday::Response::Middleware
-        def call(env)
-          @app.call(env).on_complete do
-            if env[:status] >= 400
-              error_status_code = env[:status]
-              error_code = nil
+        def on_complete(env)
+          if env.status >= 400
+            error_status_code = env.status
+            error_code = nil
 
-              begin
-                error = JSON.parse(env[:body])['error']
-                error_status_code = error['statusCode'].to_i if error['statusCode']
-                error_code = error['code'].to_i if error['code']
+            if env.body.kind_of?(Hash)
+              error = env.body.fetch('error', {})
+              error_status_code = error['statusCode'].to_i if error['statusCode']
+              error_code = error['code'].to_i if error['code']
 
-                if error
-                  message = "#{error['message']} (status: #{error_status_code}, code: #{error_code})"
-                else
-                  message = env[:body]
-                end
-              rescue JSON::ParserError
-                message = env[:body]
+              if error
+                message = "#{error['message']} (status: #{error_status_code}, code: #{error_code})"
+              else
+                message = env.body
               end
+            else
+              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
-              else
-                raise Ably::Exceptions::InvalidRequest.new(message, status: error_status_code, code: error_code)
-              end
+            if env.status >= 500
+              raise Ably::Exceptions::ServerError, message
+            else
+              raise Ably::Exceptions::InvalidRequest.new(message, error_status_code, error_code)
             end
           end
         end

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

@@ -6,17 +6,15 @@ module Ably
       # HTTP exceptions raised due to a status code error on a 3rd party site
       # Used by auth calls
       class ExternalExceptions < Faraday::Response::Middleware
-        def call(env)
-          @app.call(env).on_complete do
-            if env[:status] >= 400
-              error_status_code = env[:status]
-              message = "Error #{error_status_code}: #{(env[:body] || '')[0...200]}"
+        def on_complete(env)
+          if env.status >= 400
+            error_status_code = env.status
+            message = "Error #{error_status_code}: #{(env.body || '')[0...200]}"
 
-              if error_status_code >= 500
-                raise Ably::Exceptions::ServerError, message
-              else
-                raise Ably::Exceptions::InvalidRequest, message
-              end
+            if error_status_code >= 500
+              raise Ably::Exceptions::ServerError, message
+            else
+              raise Ably::Exceptions::InvalidRequest, message
             end
           end
         end

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

@@ -0,0 +1,17 @@
+require 'faraday'
+require 'json'
+
+module Ably
+  module Rest
+    module Middleware
+      class FailIfUnsupportedMimeType < Faraday::Response::Middleware
+        def on_complete(env)
+          unless env.response_headers['Ably-Middleware-Parsed'] == true
+            raise Ably::Exceptions::InvalidResponseBody,
+                  "Content Type #{env.response_headers['Content-Type']} is not supported by this client library"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,11 +6,18 @@ module Ably
     module Middleware
       class ParseJson < Faraday::Response::Middleware
         def on_complete(env)
-          env.body = parse(env.body) unless env.response_headers['Ably-Middleware-Parsed'] == true
+          if env.response_headers['Content-Type'] == 'application/json'
+            env.body = parse(env.body) unless env.response_headers['Ably-Middleware-Parsed'] == true
+            env.response_headers['Ably-Middleware-Parsed'] = true
+          end
         end
 
         def parse(body)
-          JSON.parse(body)
+          if body.length > 0
+            JSON.parse(body)
+          else
+            body
+          end
         rescue JSON::ParserError => e
           raise Ably::Exceptions::InvalidResponseBody, "Expected JSON response: #{e.message}"
         end

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

@@ -7,13 +7,17 @@ module Ably
       class ParseMessagePack < Faraday::Response::Middleware
         def on_complete(env)
           if env.response_headers['Content-Type'] == 'application/x-msgpack'
-            env.body = parse(env.body)
+            env.body = parse(env.body) unless env.response_headers['Ably-Middleware-Parsed'] == true
             env.response_headers['Ably-Middleware-Parsed'] = true
           end
         end
 
         def parse(body)
-          MessagePack.unpack(body)
+          if body.length > 0
+            MessagePack.unpack(body)
+          else
+            body
+          end
         rescue MessagePack::MalformedFormatError => e
           raise Ably::Exceptions::InvalidResponseBody, "Expected MessagePack response: #{e.message}"
         end

data/lib/ably/rest/presence.rb

@@ -16,11 +16,11 @@ module Ably
 
       # Obtain the set of members currently present for a channel
       #
-      # @return [Models::PagedResource<Models::PresenceMessage>] An Array of presence-message Hash objects that supports paging (next, first)
+      # @return [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] An Array of presence-message Hash objects that supports paging (next, first)
       #
       def get(options = {})
         response = client.get(base_path, options)
-        Models::PagedResource.new(response, base_path, client, coerce_into: 'Ably::Rest::Models::PresenceMessage')
+        Ably::Models::PaginatedResource.new(response, base_path, client, coerce_into: 'Ably::Models::PresenceMessage')
       end
 
       # Return the presence messages history for the channel
@@ -31,7 +31,7 @@ module Ably
       # @option options [Symbol]       :direction  `:forwards` or `:backwards`
       # @option options [Integer]      :limit      Maximum number of presence messages to retrieve up to 10,000
       #
-      # @return [Models::PagedResource<Models::PresenceMessage>] An Array of presence-message Hash objects that supports paging (next, first)
+      # @return [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] An Array of presence-message Hash objects that supports paging (next, first)
       #
       def history(options = {})
         url = "#{base_path}/history"
@@ -41,7 +41,7 @@ module Ably
 
         response = client.get(url, options.merge(merge_options))
 
-        Models::PagedResource.new(response, url, client, coerce_into: 'Ably::Rest::Models::PresenceMessage')
+        Ably::Models::PaginatedResource.new(response, url, client, coerce_into: 'Ably::Models::PresenceMessage')
       end
 
       private