ably 0.8.2 → 0.8.3

data/ably.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'faraday', '~> 0.9'
   spec.add_runtime_dependency 'json'
   spec.add_runtime_dependency 'websocket-driver', '~> 0.3'
-  spec.add_runtime_dependency 'msgpack', '0.6.0pre1'
+  spec.add_runtime_dependency 'msgpack', '>= 0.6.2'
 
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'rake'

data/lib/ably.rb

@@ -1,5 +1,5 @@
 %w(modules util).each do |namespace|
-  Dir.glob(File.expand_path("ably/#{namespace}/*.rb", File.dirname(__FILE__))).each do |file|
+  Dir.glob(File.expand_path("ably/#{namespace}/*.rb", File.dirname(__FILE__))).sort.each do |file|
     require file
   end
 end

data/lib/ably/auth.rb

@@ -22,44 +22,53 @@ module Ably
   # @!attribute [r] key_secret
   #   @return [String] Key secret (private secure part of the API key), if present
   # @!attribute [r] options
-  #   @return [Hash] {Ably::Auth} options configured for this client
-
+  #   @return [Hash] Default {Ably::Auth} options configured for this client
+  # @!attribute [r] token_params
+  #   @return [Hash] Default token params used for token requests, see {#request_token}
+  #
   class Auth
     include Ably::Modules::Conversions
     include Ably::Modules::HttpHelpers
 
     # Default capability Hash object and TTL in seconds for issued tokens
     TOKEN_DEFAULTS = {
-      capability: { '*' => ['*'] },
-      ttl:        60 * 60 # 1 hour in seconds
-    }
+      capability:         { '*' => ['*'] },
+      ttl:                60 * 60, # 1 hour in seconds
+      renew_token_buffer: 10 # buffer to allow a token to be reissued before the token is considered expired (Ably::Models::TokenDetails::TOKEN_EXPIRY_BUFFER)
+    }.freeze
 
-    attr_reader :options, :current_token_details
+    attr_reader :options, :token_params, :current_token_details
     alias_method :auth_options, :options
 
     # Creates an Auth object
     #
     # @param [Ably::Rest::Client] client  {Ably::Rest::Client} this Auth object uses
-    # @param [Hash] options (see Ably::Rest::Client#initialize)
-    # @option (see Ably::Rest::Client#initialize)
+    # @param [Hash] auth_options the authentication options used as a default future token requests
+    # @param [Hash] token_params the token params used as a default for future token requests
+    # @option (see #request_token)
     #
-    def initialize(client, options)
-      ensure_valid_auth_attributes options
+    def initialize(client, auth_options, token_params)
+      unless auth_options.kind_of?(Hash)
+        raise ArgumentError, 'Expected auth_options to be a Hash'
+      end
 
-      auth_options = options.dup
+      unless token_params.kind_of?(Hash)
+        raise ArgumentError, 'Expected token_params to be a Hash'
+      end
+
+      ensure_valid_auth_attributes auth_options
 
       @client              = client
-      @options             = auth_options
+      @options             = auth_options.dup
+      @token_params        = token_params.dup
 
-      unless auth_options.kind_of?(Hash)
-        raise ArgumentError, 'Expected auth_options to be a Hash'
-      end
+      @options.delete :force # Forcing token auth for every request is not a valid default
 
-      if auth_options[:key] && (auth_options[:key_secret] || auth_options[:key_name])
+      if options[:key] && (options[:key_secret] || options[:key_name])
         raise ArgumentError, 'key and key_name or key_secret are mutually exclusive. Provider either a key or key_name & key_secret'
       end
 
-      split_api_key_into_key_and_secret! auth_options if auth_options[:key]
+      split_api_key_into_key_and_secret! options if options[:key]
 
       if using_basic_auth? && !api_key_present?
         raise ArgumentError, 'key is missing. Either an API key, token, or token auth method must be provided'
@@ -71,85 +80,90 @@ module Ably
       end
 
       @options.freeze
+      @token_params.freeze
     end
 
     # Ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary.
     #
-    # In the event that a new token request is made, the specified options are used.
+    # In the event that a new token request is made, the provided options are used.
     #
-    # @param [Hash] options the options for the token request
-    # @option options (see #request_token)
-    # @option options [String]  :key            API key comprising the key name and key secret in a single string
-    # @option options [Boolean] :force          obtains a new token even if the current token is valid
+    # @param [Hash] auth_options the authentication options used for future token requests
+    # @param [Hash] token_params the token params used for future token requests
+    # @option auth_options [Boolean]   :force   obtains a new token even if the current token is valid
+    # @option (see #request_token)
     #
-    # @return (see #request_token)
+    # @return (see #create_token_request)
     #
     # @example
     #    # will issue a simple token request using basic auth
     #    client = Ably::Rest::Client.new(key: 'key.id:secret')
-    #    token = client.auth.authorise
+    #    token_details = client.auth.authorise
     #
     #    # will use token request from block to authorise if not already authorised
-    #    token = client.auth.authorise do |options|
+    #    token_details = client.auth.authorise auth_callback: Proc.new do
     #      # create token_request object
     #      token_request
     #    end
     #
-    def authorise(options = {})
-      ensure_valid_auth_attributes options
+    def authorise(auth_options = {}, token_params = {})
+      ensure_valid_auth_attributes auth_options
+
+      auth_options = auth_options.clone
 
-      if current_token_details && !options[:force]
+      if current_token_details && !auth_options.delete(:force)
         return current_token_details unless current_token_details.expired?
       end
 
-      options = options.clone
-      split_api_key_into_key_and_secret! options if options[:key]
-      @options = @options.merge(options) # update default options
+      split_api_key_into_key_and_secret! auth_options if auth_options[:key]
+      @options = @options.merge(auth_options) # update defaults
+
+      token_params = (auth_options.delete(:token_params) || {}).merge(token_params)
+      @token_params = @token_params.merge(token_params) # update defaults
 
-      @current_token_details = request_token(options)
+      @current_token_details = request_token(auth_options, token_params)
     end
 
     # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
     #
-    # @param [Hash] options the options for the token request
-    # @option options [String]  :key           complete API key for the designated application
-    # @option options [String]  :client_id     client ID identifying this connection to other clients (defaults to client client_id if configured)
-    # @option options [String]  :auth_url      a URL to be used to GET or POST a set of token request params, to obtain a signed token request.
-    # @option options [Hash]    :auth_headers  a set of application-specific headers to be added to any request made to the authUrl
-    # @option options [Hash]    :auth_params   a set of application-specific query params to be added to any request made to the authUrl
-    # @option options [Symbol]  :auth_method   HTTP method to use with auth_url, must be either `:get` or `:post` (defaults to :get)
-    # @option options [Proc]    :auth_callback this Proc / block will be called with the {#auth_options Auth#auth_options Hash} as the first argument whenever a new token is required.
-    #                                          The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent
-    # @option options [Integer] :ttl           validity time in seconds for the requested {Ably::Models::TokenDetails}.  Limits may apply, see {https://www.ably.io/documentation/other/authentication}
-    # @option options [Hash]    :capability    canonicalised representation of the resource paths and associated operations
-    # @option options [Boolean] :query_time    when true will query the {https://www.ably.io Ably} system for the current time instead of using the local time
-    # @option options [Time]    :timestamp     the time of the of the request
-    # @option options [String]  :nonce         an unquoted, unescaped random string of at least 16 characters
+    # @param [Hash] auth_options (see #create_token_request)
+    # @option auth_options [String]  :auth_url      a URL to be used to GET or POST a set of token request params, to obtain a signed token request
+    # @option auth_options [Hash]    :auth_headers  a set of application-specific headers to be added to any request made to the +auth_url+
+    # @option auth_options [Hash]    :auth_params   a set of application-specific query params to be added to any request made to the +auth_url+
+    # @option auth_options [Symbol]  :auth_method   (:get) HTTP method to use with +auth_url+, must be either +:get+ or +:post+
+    # @option auth_options [Proc]    :auth_callback when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required.
+    #                                               The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent
+    # @param [Hash] token_params (see #create_token_request)
+    # @option (see #create_token_request)
     #
     # @return [Ably::Models::TokenDetails]
     #
     # @example
     #    # simple token request using basic auth
     #    client = Ably::Rest::Client.new(key: 'key.id:secret')
-    #    token = client.auth.request_token
+    #    token_details = client.auth.request_token
+    #
+    #    # token request with token params
+    #    client.auth.request_token token_params: { ttl: 1.hour }
     #
     #    # token request using auth block
-    #    token = client.auth.request_token do |options|
+    #    token_details = client.auth.request_token auth_callback: Proc.new do
     #      # create token_request object
     #      token_request
     #    end
     #
-    def request_token(options = {})
-      ensure_valid_auth_attributes options
+    def request_token(auth_options = {}, token_params = {})
+      ensure_valid_auth_attributes auth_options
 
-      token_options = auth_options.merge(options)
+      token_params = (auth_options[:token_params] || {}).merge(token_params)
+      token_params = self.token_params.merge(token_params)
+      auth_options = self.options.merge(auth_options)
 
-      token_request = if auth_callback = token_options.delete(:auth_callback)
-        auth_callback.call(token_options)
-      elsif auth_url = token_options.delete(:auth_url)
-        token_request_from_auth_url(auth_url, token_options)
+      token_request = if auth_callback = auth_options.delete(:auth_callback)
+        auth_callback.call(token_params)
+      elsif auth_url = auth_options.delete(:auth_url)
+        token_request_from_auth_url(auth_url, auth_options)
       else
-        create_token_request(token_options)
+        create_token_request(auth_options, token_params)
       end
 
       case token_request
@@ -172,19 +186,23 @@ module Ably
 
     # Creates and signs a token request that can then subsequently be used by any client to request a token
     #
-    # @param [Hash] options the options for the token request
-    # @option options [String]  :key        complete API key for the designated application
-    # @option options [String]  :client_id  client ID identifying this connection to other clients
-    # @option options [Integer] :ttl        validity time in seconds for the requested {Ably::Models::TokenDetails}.  Limits may apply, see {https://www.ably.io/documentation/other/authentication}
-    # @option options [Hash]    :capability canonicalised representation of the resource paths and associated operations
-    # @option options [Boolean] :query_time when true will query the {https://www.ably.io Ably} system for the current time instead of using the local time
-    # @option options [Time]    :timestamp  the time of the of the request
-    # @option options [String]  :nonce      an unquoted, unescaped random string of at least 16 characters
+    # @param [Hash] auth_options the authentication options for the token request
+    # @option auth_options [String]  :key           API key comprising the key name and key secret in a single string
+    # @option auth_options [String]  :client_id     client ID identifying this connection to other clients (will use +client_id+ specified when library was instanced if provided)
+    # @option auth_options [Boolean] :query_time    when true will query the {https://www.ably.io Ably} system for the current time instead of using the local time
+    # @option auth_options [Hash]    :token_params   convenience to pass in +token_params+ within the +auth_options+ argument, this helps avoid the following +authorise({key: key}, {ttl: 23})+ by allowing +authorise(key:key,token_params:{ttl:23})+
+    #
+    # @param [Hash] token_params the token params used in the token request
+    # @option token_params [String]  :client_id     A client ID to associate with this token. The generated token may be used to authenticate as this +client_id+
+    # @option token_params [Integer] :ttl           validity time in seconds for the requested {Ably::Models::TokenDetails}.  Limits may apply, see {https://www.ably.io/documentation/other/authentication}
+    # @option token_params [Hash]    :capability    canonicalised representation of the resource paths and associated operations
+    # @option token_params [Time]    :timestamp     the time of the request
+    # @option token_params [String]  :nonce         an unquoted, unescaped random string of at least 16 characters
     #
     # @return [Models::TokenRequest]
     #
     # @example
-    #    client.auth.create_token_request(id: 'asd.asd', ttl: 3600)
+    #    client.auth.create_token_request(id: 'asd.asd', token_params: { ttl: 3600 })
     #    #<Ably::Models::TokenRequest:0x007fd5d919df78
     #    #  @hash={
     #    #   :id=>"asds.adsa",
@@ -196,30 +214,37 @@ module Ably
     #    #   :mac=>"881oZHeFo6oMim7....uE56a8gUxHw="
     #    #  }
     #    #>>
-    def create_token_request(options = {})
-      ensure_valid_auth_attributes options
+    def create_token_request(auth_options = {}, token_params = {})
+      ensure_valid_auth_attributes auth_options
 
-      token_options = options.clone
+      auth_options = auth_options.clone
+      token_params = (auth_options[:token_params] || {}).merge(token_params)
 
-      split_api_key_into_key_and_secret! token_options if token_options[:key]
-      request_key_name   = token_options.delete(:key_name) || key_name
-      request_key_secret = token_options.delete(:key_secret) || key_secret
-      raise Ably::Exceptions::TokenRequestError, 'Key Name and Key Secret are required to generate a new token request' unless request_key_name && request_key_secret
+      split_api_key_into_key_and_secret! auth_options if auth_options[:key]
+      request_key_name   = auth_options.delete(:key_name) || key_name
+      request_key_secret = auth_options.delete(:key_secret) || key_secret
 
-      timestamp = if token_options[:query_time]
+      raise Ably::Exceptions::TokenRequestFailed, 'Key Name and Key Secret are required to generate a new token request' unless request_key_name && request_key_secret
+
+      timestamp = if auth_options[:query_time]
         client.time
       else
-        token_options.delete(:timestamp) || Time.now
+        token_params.delete(:timestamp) || Time.now
       end
       timestamp = Time.at(timestamp) if timestamp.kind_of?(Integer)
 
+      ttl = [
+        (token_params[:ttl] || TOKEN_DEFAULTS.fetch(:ttl)),
+        Ably::Models::TokenDetails::TOKEN_EXPIRY_BUFFER + TOKEN_DEFAULTS.fetch(:renew_token_buffer) # never issue a token that will be immediately considered expired due to the buffer
+      ].max
+
       token_request = {
-        keyName:    token_options[:key_name] || request_key_name,
-        clientId:   token_options[:client_id] || client_id,
-        ttl:        ((token_options[:ttl] || TOKEN_DEFAULTS.fetch(:ttl)) * 1000).to_i,
+        keyName:    request_key_name,
+        clientId:   token_params[:client_id] || auth_options[:client_id] || client_id,
+        ttl:        (ttl * 1000).to_i,
         timestamp:  (timestamp.to_f * 1000).round,
-        capability: token_options[:capability] || TOKEN_DEFAULTS.fetch(:capability),
-        nonce:      token_options[:nonce] || SecureRandom.hex.force_encoding('UTF-8')
+        capability: token_params[:capability] || TOKEN_DEFAULTS.fetch(:capability),
+        nonce:      token_params[:nonce] || SecureRandom.hex.force_encoding('UTF-8')
       }
 
       token_request[:capability] = JSON.dump(token_request[:capability]) if token_request[:capability].is_a?(Hash)
@@ -227,7 +252,7 @@ module Ably
       token_request[:mac] = sign_params(token_request, request_key_secret)
 
       # Undocumented feature to request a persisted token
-      token_request[:persisted] = options[:persisted] if options[:persisted]
+      token_request[:persisted] = token_params[:persisted] if token_params[:persisted]
 
       Models::TokenRequest.new(token_request)
     end
@@ -252,7 +277,7 @@ module Ably
     # True when Token Auth is being used to authenticate with Ably
     def using_token_auth?
       return options[:use_token_auth] if options.has_key?(:use_token_auth)
-      token || current_token_details || has_client_id? || token_creatable_externally?
+      !!(token || current_token_details || has_client_id? || token_creatable_externally?)
     end
 
     def client_id
@@ -270,6 +295,7 @@ module Ably
     end
 
     # Auth header string used in HTTP requests to Ably
+    # Will reauthorise implicitly if required and capable
     #
     # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
     def auth_header
@@ -281,6 +307,7 @@ module Ably
     end
 
     # Auth params used in URI endpoint for Realtime connections
+    # Will reauthorise implicitly if required and capable
     #
     # @return [Hash] Auth params for a new Realtime connection
     def auth_params
@@ -353,7 +380,7 @@ module Ably
     end
 
     def ensure_api_key_sent_over_secure_connection
-      raise Ably::Exceptions::InsecureRequestError, 'Cannot use Basic Auth over non-TLS connections' unless authentication_security_requirements_met?
+      raise Ably::Exceptions::InsecureRequest, 'Cannot use Basic Auth over non-TLS connections' unless authentication_security_requirements_met?
     end
 
     # Basic Auth HTTP Authorization header value
@@ -424,18 +451,18 @@ module Ably
     # Retrieve a token request from a specified URL, expects a JSON response
     #
     # @return [Hash]
-    def token_request_from_auth_url(auth_url, options = {})
+    def token_request_from_auth_url(auth_url, auth_options)
       uri = URI.parse(auth_url)
       connection = Faraday.new("#{uri.scheme}://#{uri.host}", connection_options)
-      method = options[:auth_method] || :get
+      method = auth_options[:auth_method] || :get
 
       response = connection.send(method) do |request|
         request.url uri.path
-        request.params = options[:auth_params] || {}
-        request.headers = options[:auth_headers] || {}
+        request.params = CGI.parse(uri.query || '').merge(auth_options[:auth_params] || {})
+        request.headers = auth_options[:auth_headers] || {}
       end
 
-      if !response.body.kind_of?(Hash) && response.headers['Content-Type'] != 'text/plain'
+      if !response.body.kind_of?(Hash) && !response.headers['Content-Type'].to_s.match(%r{text/plain}i)
         raise Ably::Exceptions::InvalidResponseBody,
               "Content Type #{response.headers['Content-Type']} is not supported by this client library"
       end

data/lib/ably/exceptions.rb

@@ -16,14 +16,22 @@ module Ably
         @status = status
         @code = code
       end
+
+      def to_s
+        message = [super]
+        if status || code
+          additional_info = []
+          additional_info << "code: #{code}" if code
+          additional_info << "http status: #{status}" if status
+          message << "(#{additional_info.join(', ')})"
+        end
+        message.join(' ')
+      end
     end
 
     # An invalid request was received by Ably
     class InvalidRequest < BaseAblyException; end
 
-    # The token is invalid
-    class InvalidToken < BaseAblyException; end
-
     # Ably Protocol message received that is invalid
     class ProtocolError < BaseAblyException; end
 
@@ -39,19 +47,28 @@ module Ably
         super message, status, code
         @base_error = base_error
       end
+
+      def to_s
+        message = [super]
+        message << "#{@base_error}" if @base_error
+        message.join(' < ')
+      end
     end
 
     # Connection Timeout accessing Realtime or REST service
-    class ConnectionTimeoutError < ConnectionError; end
+    class ConnectionTimeout < ConnectionError; end
 
     # Connection closed unexpectedly
-    class ConnectionClosedError < ConnectionError; end
+    class ConnectionClosed < ConnectionError; end
 
-    # Invalid State Change error on a {https://github.com/gocardless/statesman Statesman State Machine}
-    class StateChangeError < BaseAblyException; end
+    # Connection suspended
+    class ConnectionSuspended < ConnectionError; end
 
-    # The state of the object is not suitable for this operation
-    class IncompatibleStateForOperation < BaseAblyException; end
+    # Connection failed
+    class ConnectionFailed < ConnectionError; end
+
+    # Invalid State Change error on a {https://github.com/gocardless/statesman Statesman State Machine}
+    class InvalidStateChange < BaseAblyException; end
 
     # A generic Ably exception taht supports a status & code.
     # See https://github.com/ably/ably-common/blob/master/protocol/errors.json for a list of Ably errors
@@ -61,21 +78,30 @@ module Ably
     class ServerError < BaseAblyException; end
 
     # PaginatedResult cannot retrieve the page
-    class InvalidPageError < BaseAblyException; end
+    class PageMissing < BaseAblyException; end
 
     # The expected response from the server was invalid
     class InvalidResponseBody < BaseAblyException; end
 
     # The request cannot be performed because it is insecure
-    class InsecureRequestError < BaseAblyException; end
+    class InsecureRequest < BaseAblyException; end
 
     # The token request could not be created
-    class TokenRequestError < BaseAblyException; end
+    class TokenRequestFailed < BaseAblyException; end
+
+    # The token has expired
+    class TokenExpired < BaseAblyException; end
 
     # The message could not be delivered to the server
-    class MessageDeliveryError < BaseAblyException; end
+    class MessageDeliveryFailed < BaseAblyException; end
+
+    # The client has been configured to not queue messages i.e. only publish down an active connection
+    class MessageQueueingDisabled < BaseAblyException; end
 
     # The data payload type is not supported
-    class UnsupportedDataTypeError < BaseAblyException; end
+    class UnsupportedDataType < BaseAblyException; end
+
+    # When a channel is detached / failed, certain operations are not permitted such as publishing messages
+    class ChannelInactive < BaseAblyException; end
   end
 end