ably 0.6.2 → 0.7.0

data/ably.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'redcarpet'
-  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec', '~> 3.1.0' # version lock, see event_machine_helper.rb#patch_example_block_with_surrounding_eventmachine_reactor
   spec.add_development_dependency 'yard'
   spec.add_development_dependency 'webmock'
 end

data/lib/ably.rb

@@ -10,11 +10,3 @@ require 'ably/logger'
 require 'ably/realtime'
 require 'ably/rest'
 require 'ably/version'
-
-# Ably is the base namespace for the Ably {Ably::Realtime Realtime} & {Ably::Rest Rest} client libraries.
-#
-# Please refer to the {file:README.md Readme} on getting started.
-#
-# @see file:README.md README
-module Ably
-end

data/lib/ably/auth.rb

@@ -34,14 +34,15 @@ module Ably
     # Creates an Auth object
     #
     # @param [Ably::Rest::Client] client  {Ably::Rest::Client} this Auth object uses
-    # @param [Hash] auth_options          see {Ably::Rest::Client#initialize}
-    # @yield [auth_options]               see {Ably::Rest::Client#initialize}
-    def initialize(client, auth_options, &auth_block)
-      auth_options = auth_options.dup
+    # @param options (see Ably::Rest::Client#initialize)
+    # @option (see Ably::Rest::Client#initialize)
+    # @yield  (see Ably::Rest::Client#initialize)
+    def initialize(client, options, &token_request_block)
+      auth_options = options.dup
 
-      @client        = client
-      @options       = auth_options
-      @auth_callback = auth_block if block_given?
+      @client              = client
+      @options             = auth_options
+      @default_token_block = token_request_block if block_given?
 
       unless auth_options.kind_of?(Hash)
         raise ArgumentError, 'Expected auth_options to be a Hash'
@@ -54,16 +55,17 @@ module Ably
       if auth_options[:api_key]
         api_key_parts = auth_options[:api_key].to_s.match(/(?<id>[\w_-]+\.[\w_-]+):(?<secret>[\w_-]+)/)
         raise ArgumentError, 'api_key is invalid' unless api_key_parts
-        auth_options[:key_id] = api_key_parts[:id]
-        auth_options[:key_secret] = api_key_parts[:secret]
+        auth_options[:key_id] = api_key_parts[:id].encode(Encoding::UTF_8)
+        auth_options[:key_secret] = api_key_parts[:secret].encode(Encoding::UTF_8)
       end
 
       if using_basic_auth? && !api_key_present?
         raise ArgumentError, 'api_key is missing. Either an API key, token, or token auth method must be provided'
       end
 
-      if has_client_id? && !api_key_present?
-        raise ArgumentError, 'client_id cannot be provided without a complete API key. Key ID & Secret is needed to authenticate with Ably and obtain a token'
+      if has_client_id?
+        raise ArgumentError, 'client_id cannot be provided without a complete API key. Key ID & Secret is needed to authenticate with Ably and obtain a token' unless api_key_present?
+        ensure_utf_8 :client_id, client_id
       end
 
       @options.freeze
@@ -74,25 +76,14 @@ module Ably
     # In the event that a new token request is made, the specified options are used.
     #
     # @param [Hash] options the options for the token request
-    # @option options [String]  :key_id       key ID for the designated application (defaults to client key_id)
-    # @option options [String]  :key_secret   key secret for the designated application used to sign token requests (defaults to client key_secret)
-    # @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 [Integer] :ttl          validity time in seconds for the requested {Ably::Models::Token}.  Limits may apply, see {http://docs.ably.io/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://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
-    # @option options [Boolean] :force        obtains a new token even if the current token is valid
+    # @option options (see #request_token)
+    # @option options [Boolean] :force   obtains a new token even if the current token is valid
     #
-    # @yield [options] (optional) if an auth block is passed to this method, then this block will be called to create a new token request object
-    # @yieldparam [Hash] options options passed to request_token will be in turn sent to the block in this argument
-    # @yieldreturn [Hash] valid token request object, see {Auth#create_token_request}
+    # @yield (see #request_token)
+    # @yieldparam [Hash] options options passed to {#authorise} will be in turn sent to the block in this argument
+    # @yieldreturn (see #request_token)
     #
-    # @return [Ably::Models::Token]
+    # @return (see #request_token)
     #
     # @example
     #    # will issue a simple token request using basic auth
@@ -105,12 +96,15 @@ module Ably
     #      token_request
     #    end
     #
-    def authorise(options = {}, &block)
+    def authorise(options = {}, &token_request_block)
       if !options[:force] && current_token
         return current_token unless current_token.expired?
       end
 
-      @current_token = request_token(options, &block)
+      @options             = @options.merge(options)
+      @default_token_block = token_request_block if block_given?
+
+      @current_token = request_token(options, &token_request_block)
     end
 
     # Request a {Ably::Models::Token} which can be used to make authenticated token based requests
@@ -129,9 +123,9 @@ module Ably
     # @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
     #
-    # @yield [options] (optional) if an auth block is passed to this method, then this block will be called to create a new token request object
-    # @yieldparam [Hash] options options passed to request_token will be in turn sent to the block in this argument
-    # @yieldreturn [Hash] valid token request object, see {Auth#create_token_request}
+    # @yield [options] (optional) if a token request block is passed to this method, then this block will be called whenever a new token is required
+    # @yieldparam [Hash] options options passed to {#request_token} will be in turn sent to the block in this argument
+    # @yieldreturn [Hash] expects a valid token request object, see {#create_token_request}
     #
     # @return [Ably::Models::Token]
     #
@@ -146,14 +140,14 @@ module Ably
     #      token_request
     #    end
     #
-    def request_token(options = {}, &block)
+    def request_token(options = {}, &token_request_block)
       token_options = self.auth_options.merge(options)
 
       auth_url = token_options.delete(:auth_url)
       token_request = if block_given?
-        yield(token_options)
-      elsif auth_callback
-        auth_callback.call(token_options)
+        token_request_block.call(token_options)
+      elsif default_token_block
+        default_token_block.call(token_options)
       elsif auth_url
         token_request_from_auth_url(auth_url, token_options)
       else
@@ -162,7 +156,7 @@ module Ably
 
       token_request = IdiomaticRubyWrapper(token_request)
 
-      response = client.post("/keys/#{token_request.fetch(:id)}/requestToken", token_request.hash, send_auth_header: false)
+      response = client.post("/keys/#{token_request.fetch(:id)}/requestToken", token_request.hash, send_auth_header: false, disable_automatic_reauthorise: true)
       body = IdiomaticRubyWrapper(response.body)
 
       Ably::Models::Token.new(body.fetch(:access_token))
@@ -220,8 +214,9 @@ module Ably
         token_request[:capability] = token_request[:capability].to_json
       end
 
-      token_request[:mac] = sign_params(token_request, request_key_secret)
+      ensure_utf_8 :nonce, token_request[:nonce], allow_nil: true
 
+      token_request[:mac] = sign_params(token_request, request_key_secret)
       token_request
     end
 
@@ -244,6 +239,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_id || current_token || has_client_id? || token_creatable_externally?
     end
 
@@ -280,26 +276,38 @@ module Ably
     # True if prerequisites for creating a new token request are present
     #
     # One of the following criterion must be met:
-    # * Valid key id and secret
+    # * Valid key id and secret and token_id option not provided as token options cannot be determined
     # * Authentication callback for new token requests
     # * Authentication URL for new token requests
     #
     # @return [Boolean]
     def token_renewable?
-      token_creatable_externally? || api_key_present?
+      token_creatable_externally? || (api_key_present? && !token_id)
+    end
+
+    # Returns false when attempting to send an API Key over a non-secure connection
+    # Token auth must be used for non-secure connections
+    #
+    # @return [Boolean]
+    def authentication_security_requirements_met?
+      client.use_tls? || using_token_auth?
     end
 
     private
-    attr_reader :auth_callback
+    attr_reader :default_token_block
+
+    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?
+    end
 
     # Basic Auth HTTP Authorization header value
     def basic_auth_header
-      raise Ably::Exceptions::InsecureRequestError, 'Cannot use Basic Auth over non-TLS connections' unless client.use_tls?
+      ensure_api_key_sent_over_secure_connection
       "Basic #{encode64("#{api_key}")}"
     end
 
     def token_auth_id
-      current_token_id = if token_id
+      if token_id
         token_id
       else
         authorise.id
@@ -313,7 +321,7 @@ module Ably
 
     # Basic Auth params to authenticate the Realtime connection
     def basic_auth_params
-      raise Ably::Exceptions::InsecureRequestError, 'Cannot use Basic Auth over non-TLS connections' unless client.use_tls?
+      ensure_api_key_sent_over_secure_connection
       # TODO: Change to key_secret when API is updated
       {
         key_id: key_id,
@@ -403,7 +411,7 @@ module Ably
     end
 
     def token_callback_present?
-      !!auth_callback
+      !!default_token_block
     end
 
     def token_url_present?

data/lib/ably/exceptions.rb

@@ -33,23 +33,37 @@ module Ably
     # Encoding or decoding failure
     class EncoderError < BaseAblyException; end
 
+    # Connection error from Realtime or REST service
+    class ConnectionError < BaseAblyException
+      def initialize(message, status = nil, code = nil, base_error = nil)
+        super message, status, code
+        @base_error = base_error
+      end
+    end
+
+    # Connection Timeout accessing Realtime or REST service
+    class ConnectionTimeoutError < ConnectionError; end
+
+    # Invalid State Change error on a {https://github.com/gocardless/statesman Statesman State Machine}
+    class StateChangeError < 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
     class Standard < BaseAblyException; end
 
     # The HTTP request has returned a 500 error
-    class ServerError < StandardError; end
+    class ServerError < BaseAblyException; end
 
     # PaginatedResource cannot retrieve the page
-    class InvalidPageError < StandardError; end
+    class InvalidPageError < BaseAblyException; end
 
     # The expected response from the server was invalid
-    class InvalidResponseBody < StandardError; end
+    class InvalidResponseBody < BaseAblyException; end
 
     # The request cannot be performed because it is insecure
-    class InsecureRequestError < StandardError; end
+    class InsecureRequestError < BaseAblyException; end
 
     # The token request could not be created
-    class TokenRequestError < StandardError; end
+    class TokenRequestError < BaseAblyException; end
   end
 end

data/lib/ably/logger.rb

@@ -66,7 +66,7 @@ module Ably
     end
 
     def realtime?
-      client.respond_to?(:connection)
+      defined?(Ably::Realtime::Client) && client.kind_of?(Ably::Realtime::Client)
     end
 
     def default_logger

data/lib/ably/models/error_info.rb

@@ -19,7 +19,7 @@ module Ably::Models
       @hash_object     = IdiomaticRubyWrapper(hash_object.clone.freeze)
     end
 
-    %w( message code status_code ).each do |attribute|
+    %w(message code status_code).each do |attribute|
       define_method attribute do
         hash[attribute.to_sym]
       end

data/lib/ably/models/idiomatic_ruby_wrapper.rb

@@ -50,7 +50,9 @@ module Ably::Models
     # @attribute [Hash] mixedCaseHashObject mixed case Hash object
     # @attribute [Array<Symbol,String>] stop_at array of keys that this wrapper should stop wrapping at to preserve the underlying Hash as is
     #
-    def initialize(mixedCaseHashObject, stop_at: [])
+    def initialize(mixedCaseHashObject, options = {})
+      stop_at = options.fetch(:stop_at, [])
+
       if mixedCaseHashObject.kind_of?(IdiomaticRubyWrapper)
         $stderr.puts "<IdiomaticRubyWrapper#initialize> WARNING: Wrapping a IdiomaticRubyWrapper with another IdiomaticRubyWrapper"
       end
@@ -203,14 +205,14 @@ module Ably::Models
     # key is not found in mixedCase.
     def source_key_for(symbolized_key)
       format_preferences = [
-        -> (key_sym) { convert_to_mixed_case(key_sym) },
-        -> (key_sym) { key_sym.to_sym },
-        -> (key_sym) { key_sym.to_s },
-        -> (key_sym) { convert_to_mixed_case(key_sym).to_sym },
-        -> (key_sym) { convert_to_lower_case(key_sym) },
-        -> (key_sym) { convert_to_lower_case(key_sym).to_sym },
-        -> (key_sym) { convert_to_mixed_case(key_sym, force_camel: true) },
-        -> (key_sym) { convert_to_mixed_case(key_sym, force_camel: true).to_sym }
+        proc { |key_sym| convert_to_mixed_case(key_sym) },
+        proc { |key_sym| key_sym.to_sym },
+        proc { |key_sym| key_sym.to_s },
+        proc { |key_sym| convert_to_mixed_case(key_sym).to_sym },
+        proc { |key_sym| convert_to_lower_case(key_sym) },
+        proc { |key_sym| convert_to_lower_case(key_sym).to_sym },
+        proc { |key_sym| convert_to_mixed_case(key_sym, force_camel: true) },
+        proc { |key_sym| convert_to_mixed_case(key_sym, force_camel: true).to_sym }
       ]
 
       preferred_format = format_preferences.detect do |format|

data/lib/ably/models/message.rb

@@ -32,12 +32,15 @@ module Ably::Models
   #   @return [Time] Timestamp when the message was received by the Ably the real-time service
   # @!attribute [r] id
   #   @return [String] A globally unique message ID
+  # @!attribute [r] connection_id
+  #   @return [String] The connection_id of the publisher of the message
   # @!attribute [r] hash
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #
   class Message
-    include Ably::Modules::ModelCommon
+    include Ably::Modules::Conversions
     include Ably::Modules::Encodeable
+    include Ably::Modules::ModelCommon
     include EventMachine::Deferrable
 
     # {Message} initializer
@@ -50,9 +53,13 @@ module Ably::Models
       @raw_hash_object  = hash_object
 
       set_hash_object hash_object
+
+      ensure_utf_8 :name,      name,      allow_nil: true
+      ensure_utf_8 :client_id, client_id, allow_nil: true
+      ensure_utf_8 :encoding,  encoding,  allow_nil: true
     end
 
-    %w( name client_id encoding ).each do |attribute|
+    %w( name client_id encoding connection_id ).each do |attribute|
       define_method attribute do
         hash[attribute.to_sym]
       end
@@ -63,7 +70,11 @@ module Ably::Models
     end
 
     def id
-      hash[:id] || "#{protocol_message.id!}:#{protocol_message_index}"
+      hash.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
+    end
+
+    def connection_id
+      hash.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? }
     end
 
     def timestamp
@@ -111,15 +122,7 @@ module Ably::Models
     attr_reader :raw_hash_object
 
     def protocol_message_index
-      protocol_message.messages.index(self)
-    end
-
-    def connection_id
-      protocol_message.connection_id
-    end
-
-    def message_serial
-      protocol_message.message_serial
+      protocol_message.messages.map(&:object_id).index(self.object_id)
     end
 
     def set_hash_object(hash)

data/lib/ably/models/message_encoders/base.rb

@@ -1,3 +1,5 @@
+require 'ably/modules/conversions'
+
 # MessageEncoders are registered with the Ably client library and are responsible
 # for encoding & decoding messages.
 #
@@ -93,11 +95,6 @@ module Ably::Models::MessageEncoders
   end
 
   def self.register_default_encoders(client)
-    Dir.glob(File.expand_path("*.rb", File.dirname(__FILE__))).each do |file|
-      next if __FILE__ == file
-      require file
-    end
-
     client.register_encoder Ably::Models::MessageEncoders::Utf8
     client.register_encoder Ably::Models::MessageEncoders::Json
     client.register_encoder Ably::Models::MessageEncoders::Cipher
@@ -105,3 +102,7 @@ module Ably::Models::MessageEncoders
   end
 end
 
+require 'ably/models/message_encoders/base64'
+require 'ably/models/message_encoders/cipher'
+require 'ably/models/message_encoders/json'
+require 'ably/models/message_encoders/utf8'

data/lib/ably/models/message_encoders/base64.rb

@@ -1,4 +1,5 @@
 require 'base64'
+require 'ably/models/message_encoders/base'
 
 module Ably::Models::MessageEncoders
   # Base64 binary Encoder and Decoder

data/lib/ably/models/message_encoders/cipher.rb

@@ -1,3 +1,7 @@
+require 'ably/exceptions'
+require 'ably/models/message_encoders/base'
+require 'ably/util/crypto'
+
 module Ably::Models::MessageEncoders
   # Cipher Encoder & Decoder that automatically encrypts & decrypts messages using Ably::Util::Crypto
   # when a channel has option encrypted: true.
@@ -41,7 +45,6 @@ module Ably::Models::MessageEncoders
         end
 
         message[:data] = crypto.decrypt(message[:data])
-        message[:data].force_encoding(Encoding::ASCII_8BIT) if is_binary?(message)
         strip_current_encoding_part message
       end
     rescue OpenSSL::Cipher::CipherError => e
@@ -70,11 +73,11 @@ module Ably::Models::MessageEncoders
     end
 
     def cipher_algorithm(message)
-      current_encoding_part(message).to_s[/^#{ENCODING_ID}\+([\w\d_-]+)$/, 1]
+      current_encoding_part(message).to_s[/^#{ENCODING_ID}\+([\w_-]+)$/, 1]
     end
 
     def already_encrypted?(message)
-      message.fetch(:encoding, '').to_s.match(%r{(^|/)#{ENCODING_ID}\+([\w\d_-]+)($|/)})
+      message.fetch(:encoding, '').to_s.match(%r{(^|/)#{ENCODING_ID}\+([\w_-]+)($|/)})
     end
   end
 end