ably-rest 0.8.5 → 0.8.6

data/ably-rest.gemspec

@@ -14,10 +14,10 @@ Gem::Specification.new do |spec|
   spec.version       = Ably::VERSION
   spec.authors       = ['Matthew O\'Riordan']
   spec.email         = ['matt@ably.io']
-  spec.description   = %q{A Ruby REST only client library for ably.io, the real-time messaging service}
-  spec.summary       = %q{A Ruby REST only client library for ably.io, the real-time messaging service}
+  spec.description   = %q{A Ruby REST only client library for ably.io realtime messaging}
+  spec.summary       = %q{A Ruby REST only client library for ably.io realtime messaging}
   spec.homepage      = 'http://github.com/ably/ably-ruby-rest'
-  spec.license       = 'MIT'
+  spec.license       = 'Apache 2'
 
   submodule_path  = File.expand_path('../lib/submodules/ably-ruby', __FILE__)
   submodule_files = Dir.chdir(submodule_path) do
@@ -33,13 +33,19 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'faraday', '~> 0.9'
   spec.add_runtime_dependency 'json'
-  spec.add_runtime_dependency 'msgpack-ably', '~> 0.5.10'
+  spec.add_runtime_dependency 'msgpack', '>= 0.6.2'
+  spec.add_runtime_dependency 'addressable', '>= 2.0.0'
 
   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.2.0'
   spec.add_development_dependency 'rspec-retry'
   spec.add_development_dependency 'yard'
   spec.add_development_dependency 'webmock'
+
+  if RUBY_VERSION.match(/^2/)
+    spec.add_development_dependency 'pry'
+    spec.add_development_dependency 'pry-byebug'
+  end
 end

data/lib/submodules/ably-ruby/.travis.yml

@@ -1,5 +1,5 @@
 sudo: false
-env: RSPEC_RETRY=true
+env: RSPEC_RETRY=false
 language: ruby
 rvm:
 - 1.9.3

data/lib/submodules/ably-ruby/CHANGELOG.md

@@ -1,29 +1,59 @@
 # Change Log
 
-## [Unreleased](https://github.com/ably/ably-ruby/tree/HEAD)
+## [v0.8.6](https://github.com/ably/ably-ruby/tree/v0.8.6) (2015-12-02)
 
-[Full Changelog](https://github.com/ably/ably-ruby/compare/v0.8.2...HEAD)
+[Full Changelog](https://github.com/ably/ably-ruby/compare/v0.8.5...v0.8.6)
+
+**Merged pull requests:**
+
+- Some intermittent test fixes & enable tests that were blocked [\#70](https://github.com/ably/ably-ruby/pull/70) ([mattheworiordan](https://github.com/mattheworiordan))
+
+- Output detailed log for any text failures [\#67](https://github.com/ably/ably-ruby/pull/67) ([mattheworiordan](https://github.com/mattheworiordan))
+
+- 0.8 final spec \(98% compliance\) [\#66](https://github.com/ably/ably-ruby/pull/66) ([mattheworiordan](https://github.com/mattheworiordan))
+
+## [v0.8.5](https://github.com/ably/ably-ruby/tree/v0.8.5) (2015-10-08)
+[Full Changelog](https://github.com/ably/ably-ruby/compare/v0.8.4...v0.8.5)
 
 **Implemented enhancements:**
 
-- Add compatibility support for default Crypto params [\#53](https://github.com/ably/ably-ruby/issues/53)
+- Switch arity of auth methods [\#61](https://github.com/ably/ably-ruby/issues/61)
 
-- EventEmitter on connection [\#52](https://github.com/ably/ably-ruby/issues/52)
+**Fixed bugs:**
 
+- Switch arity of auth methods [\#61](https://github.com/ably/ably-ruby/issues/61)
+- Add test: Message published, connection dropped, then restores to point before last message was published [\#56](https://github.com/ably/ably-ruby/issues/56)
+- Documentation for constructor is incorrect [\#49](https://github.com/ably/ably-ruby/issues/49)
+
+**Merged pull requests:**
+
+- Ensure connections are always closed in tests [\#63](https://github.com/ably/ably-ruby/pull/63) ([mattheworiordan](https://github.com/mattheworiordan))
+
+## [v0.8.4](https://github.com/ably/ably-ruby/tree/v0.8.4) (2015-09-08)
+[Full Changelog](https://github.com/ably/ably-ruby/compare/v0.8.3...v0.8.4)
+
+**Implemented enhancements:**
+
+- Add compatibility support for default Crypto params [\#53](https://github.com/ably/ably-ruby/issues/53)
+- EventEmitter on connection [\#52](https://github.com/ably/ably-ruby/issues/52)
 - Add test for connectionId attribute for a message sent over REST [\#50](https://github.com/ably/ably-ruby/issues/50)
 
-- Implement :queue\_messages option [\#36](https://github.com/ably/ably-ruby/issues/36)
+**Merged pull requests:**
 
-- Check that a non 200-299 status code for REST requests uses fallback hosts [\#35](https://github.com/ably/ably-ruby/issues/35)
+- Spec update to fix a number of issues [\#60](https://github.com/ably/ably-ruby/pull/60) ([mattheworiordan](https://github.com/mattheworiordan))
+- Allow clientId to be provided on init if using externally created token [\#58](https://github.com/ably/ably-ruby/pull/58) ([SimonWoolf](https://github.com/SimonWoolf))
 
-- Move stats fixtures into ably-common [\#34](https://github.com/ably/ably-ruby/issues/34)
+## [v0.8.3](https://github.com/ably/ably-ruby/tree/v0.8.3) (2015-08-19)
+[Full Changelog](https://github.com/ably/ably-ruby/compare/v0.8.2...v0.8.3)
 
-- Add tests for messages with no data or name fields [\#21](https://github.com/ably/ably-ruby/issues/21)
+**Implemented enhancements:**
 
+- Implement :queue\_messages option [\#36](https://github.com/ably/ably-ruby/issues/36)
+- Check that a non 200-299 status code for REST requests uses fallback hosts [\#35](https://github.com/ably/ably-ruby/issues/35)
+- Move stats fixtures into ably-common [\#34](https://github.com/ably/ably-ruby/issues/34)
+- Add tests for messages with no data or name fields [\#21](https://github.com/ably/ably-ruby/issues/21)
 - Namespace MsgPack as MsgPack5 because compliance is not merged in [\#12](https://github.com/ably/ably-ruby/issues/12)
-
 - Add test coverage for receiving messages more than once i.e. historical messages resent somehow on reconnect [\#11](https://github.com/ably/ably-ruby/issues/11)
-
 - Add async methods for Authentication in the realtime library [\#8](https://github.com/ably/ably-ruby/issues/8)
 
 **Fixed bugs:**
@@ -33,41 +63,28 @@
 **Closed issues:**
 
 - Scope default token params in arguments [\#55](https://github.com/ably/ably-ruby/issues/55)
-
 - Channel options can be reset when accessing a channel with \#get [\#46](https://github.com/ably/ably-ruby/issues/46)
 
 **Merged pull requests:**
 
-- Spec update to fix a number of issues [\#60](https://github.com/ably/ably-ruby/pull/60) ([mattheworiordan](https://github.com/mattheworiordan))
-
-- Allow clientId to be provided on init if using externally created token [\#58](https://github.com/ably/ably-ruby/pull/58) ([SimonWoolf](https://github.com/SimonWoolf))
-
 - Separate token params for auth [\#57](https://github.com/ably/ably-ruby/pull/57) ([mattheworiordan](https://github.com/mattheworiordan))
-
 - Ensure files are required in a consistent order [\#51](https://github.com/ably/ably-ruby/pull/51) ([SimonWoolf](https://github.com/SimonWoolf))
 
 ## [v0.8.2](https://github.com/ably/ably-ruby/tree/v0.8.2) (2015-05-20)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.8.1...v0.8.2)
 
 **Implemented enhancements:**
 
 - Ensure Array object can be used in place of Hash for payload [\#44](https://github.com/ably/ably-ruby/issues/44)
-
 - Change connect\_automatically option to auto\_connect for consistency [\#42](https://github.com/ably/ably-ruby/issues/42)
-
 - Rename PaginatedResource to PaginatedResult for consistency [\#40](https://github.com/ably/ably-ruby/issues/40)
-
 - EventEmitter should use `emit` not `trigger` to be consistent with other libs [\#31](https://github.com/ably/ably-ruby/issues/31)
-
 - Add exceptions when data attribute for messages/presence is not String, Binary or JSON data [\#4](https://github.com/ably/ably-ruby/issues/4)
-
 - Auth Callback and Auth URL should support tokens as well as token requests [\#2](https://github.com/ably/ably-ruby/issues/2)
 
 **Closed issues:**
 
 - Realtime Presence\#get does not wait by default [\#47](https://github.com/ably/ably-ruby/issues/47)
-
 - No implicit attach when accessing channel.presence [\#45](https://github.com/ably/ably-ruby/issues/45)
 
 **Merged pull requests:**
@@ -75,11 +92,9 @@
 - Reject invalid payload type [\#48](https://github.com/ably/ably-ruby/pull/48) ([mattheworiordan](https://github.com/mattheworiordan))
 
 ## [v0.8.1](https://github.com/ably/ably-ruby/tree/v0.8.1) (2015-04-23)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.8.0...v0.8.1)
 
 ## [v0.8.0](https://github.com/ably/ably-ruby/tree/v0.8.0) (2015-04-23)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.7.6...v0.8.0)
 
 **Merged pull requests:**
@@ -87,18 +102,15 @@
 - Token naming refactor [\#29](https://github.com/ably/ably-ruby/pull/29) ([mattheworiordan](https://github.com/mattheworiordan))
 
 ## [v0.7.6](https://github.com/ably/ably-ruby/tree/v0.7.6) (2015-04-17)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.7.5...v0.7.6)
 
 **Implemented enhancements:**
 
 - Rename Stat to Stats for consistency [\#32](https://github.com/ably/ably-ruby/issues/32)
-
 - Stats objects [\#24](https://github.com/ably/ably-ruby/issues/24)
-
 - Need a test to handle errors in callbacks [\#13](https://github.com/ably/ably-ruby/issues/13)
-
 - Allow token ID or API key in the client constructor [\#5](https://github.com/ably/ably-ruby/issues/5)
+- Typed stats similar to Java library + zero default for empty stats [\#25](https://github.com/ably/ably-ruby/pull/25) ([mattheworiordan](https://github.com/mattheworiordan))
 
 **Fixed bugs:**
 
@@ -111,19 +123,14 @@
 **Merged pull requests:**
 
 - Test encoded presence fixture data for \#get & \#history [\#28](https://github.com/ably/ably-ruby/pull/28) ([mattheworiordan](https://github.com/mattheworiordan))
-
 - Add coveralls.io coverage reporting [\#27](https://github.com/ably/ably-ruby/pull/27) ([mattheworiordan](https://github.com/mattheworiordan))
-
 - New paginated resource [\#26](https://github.com/ably/ably-ruby/pull/26) ([mattheworiordan](https://github.com/mattheworiordan))
-
-- Typed stats similar to Java library + zero default for empty stats [\#25](https://github.com/ably/ably-ruby/pull/25) ([mattheworiordan](https://github.com/mattheworiordan))
+- History since attach [\#22](https://github.com/ably/ably-ruby/pull/22) ([mattheworiordan](https://github.com/mattheworiordan))
 
 ## [v0.7.5](https://github.com/ably/ably-ruby/tree/v0.7.5) (2015-03-21)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.7.4...v0.7.5)
 
 ## [v0.7.4](https://github.com/ably/ably-ruby/tree/v0.7.4) (2015-03-21)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.7.2...v0.7.4)
 
 **Merged pull requests:**
@@ -131,7 +138,6 @@
 - Presence Member Map [\#14](https://github.com/ably/ably-ruby/pull/14) ([mattheworiordan](https://github.com/mattheworiordan))
 
 ## [v0.7.2](https://github.com/ably/ably-ruby/tree/v0.7.2) (2015-02-10)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.7.1...v0.7.2)
 
 **Implemented enhancements:**
@@ -141,15 +147,12 @@
 **Merged pull requests:**
 
 - Update README to include various missing snippets for core features [\#9](https://github.com/ably/ably-ruby/pull/9) ([kouno](https://github.com/kouno))
-
 - Fix connection retry frequency [\#7](https://github.com/ably/ably-ruby/pull/7) ([kouno](https://github.com/kouno))
 
 ## [v0.7.1](https://github.com/ably/ably-ruby/tree/v0.7.1) (2015-01-18)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.7.0...v0.7.1)
 
 ## [v0.7.0](https://github.com/ably/ably-ruby/tree/v0.7.0) (2015-01-12)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.6.2...v0.7.0)
 
 **Closed issues:**
@@ -157,39 +160,30 @@
 - JSON encoder should only append utf-8 before a cipher encoder is applied [\#1](https://github.com/ably/ably-ruby/issues/1)
 
 ## [v0.6.2](https://github.com/ably/ably-ruby/tree/v0.6.2) (2014-12-10)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.2.0...v0.6.2)
 
 ## [v0.2.0](https://github.com/ably/ably-ruby/tree/v0.2.0) (2014-12-09)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.1.6...v0.2.0)
 
 ## [v0.1.6](https://github.com/ably/ably-ruby/tree/v0.1.6) (2014-10-31)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.1.5...v0.1.6)
 
 ## [v0.1.5](https://github.com/ably/ably-ruby/tree/v0.1.5) (2014-10-23)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.1.4...v0.1.5)
 
 ## [v0.1.4](https://github.com/ably/ably-ruby/tree/v0.1.4) (2014-09-27)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.1.3...v0.1.4)
 
 ## [v0.1.3](https://github.com/ably/ably-ruby/tree/v0.1.3) (2014-09-26)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.1.2...v0.1.3)
 
 ## [v0.1.2](https://github.com/ably/ably-ruby/tree/v0.1.2) (2014-09-25)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.1.1...v0.1.2)
 
 ## [v0.1.1](https://github.com/ably/ably-ruby/tree/v0.1.1) (2014-09-23)
-
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v0.1.0...v0.1.1)
 
 ## [v0.1.0](https://github.com/ably/ably-ruby/tree/v0.1.0) (2014-09-23)
 
 
-
 \* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

data/lib/submodules/ably-ruby/ably.gemspec

@@ -25,14 +25,20 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'json'
   spec.add_runtime_dependency 'websocket-driver', '~> 0.3'
   spec.add_runtime_dependency 'msgpack', '>= 0.6.2'
+  spec.add_runtime_dependency 'addressable', '>= 2.0.0'
 
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'redcarpet'
-  spec.add_development_dependency 'rspec', '~> 3.1.0' # version lock, see config.around(:example, :event_machine) in event_machine_helper.rb
+  spec.add_development_dependency 'rspec', '~> 3.2.0' # version lock, see config.around(:example, :event_machine) in event_machine_helper.rb
   spec.add_development_dependency 'rspec-retry'
   spec.add_development_dependency 'yard'
   spec.add_development_dependency 'webmock'
 
   spec.add_development_dependency 'coveralls'
+
+  if RUBY_VERSION.match(/^2/)
+    spec.add_development_dependency 'pry'
+    spec.add_development_dependency 'pry-byebug'
+  end
 end

data/lib/submodules/ably-ruby/lib/ably.rb

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

data/lib/submodules/ably-ruby/lib/ably/auth.rb

@@ -13,8 +13,6 @@ module Ably
   #   @return [String] The provided client ID, used for identifying this client for presence purposes
   # @!attribute [r] current_token_details
   #   @return [Ably::Models::TokenDetails] Current {Ably::Models::TokenDetails} issued by this library or one of the provided callbacks used to authenticate requests
-  # @!attribute [r] token
-  #   @return [String] Token string provided to the {Ably::Client} constructor that is used to authenticate all requests
   # @!attribute [r] key
   #   @return [String] Complete API key containing both the key name and key secret, if present
   # @!attribute [r] key_name
@@ -61,6 +59,7 @@ module Ably
       @client              = client
       @options             = auth_options.dup
       @token_params        = token_params.dup
+      @token_option        = options[:token] || options[:token_details]
 
       @options.delete :force # Forcing token auth for every request is not a valid default
 
@@ -74,11 +73,25 @@ module Ably
         raise ArgumentError, 'key is missing. Either an API key, token, or token auth method must be provided'
       end
 
-      if has_client_id? && !token_creatable_externally?
-        raise ArgumentError, 'client_id cannot be provided without a complete API key. Key name & Secret is needed to authenticate with Ably and obtain a token' unless api_key_present?
+      if options[:client_id] == '*'
+        raise ArgumentError, 'A client cannot be configured with a wildcard client_id'
+      end
+
+      if has_client_id? && !token_creatable_externally? && !token_option
+        raise ArgumentError, 'client_id cannot be provided without a complete API key or means to authenticate. An API key is needed to automatically authenticate with Ably and obtain a token' unless api_key_present?
         ensure_utf_8 :client_id, client_id
       end
 
+      # If a token details object or token string is provided in the initializer
+      # then the client can be authorised immediately using this token
+      if token_option
+        token_details = convert_to_token_details(token_option)
+        if token_details
+          token_details = authorise_with_token(token_details)
+          logger.debug "Auth: new token passed in to the initializer: #{token_details}"
+        end
+      end
+
       @options.freeze
       @token_params.freeze
     end
@@ -120,7 +133,9 @@ module Ably
       token_params = (auth_options.delete(:token_params) || {}).merge(token_params)
       @token_params = @token_params.merge(token_params) # update defaults
 
-      @current_token_details = request_token(token_params, auth_options)
+      authorise_with_token(request_token(token_params, auth_options)).tap do |new_token_details|
+        logger.debug "Auth: new token following authorisation: #{new_token_details}"
+      end
     end
 
     # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
@@ -154,34 +169,29 @@ module Ably
     def request_token(token_params = {}, auth_options = {})
       ensure_valid_auth_attributes auth_options
 
-      token_params = (auth_options[:token_params] || {}).merge(token_params)
-      token_params = self.token_params.merge(token_params)
+      # Token param precedence (lowest to highest):
+      #   Auth default => client_id => auth_options[:token_params] arg => token_params arg
+      token_params = self.token_params.merge(
+        (client_id ? { client_id: client_id } : {}).
+          merge(auth_options[:token_params] || {}).
+          merge(token_params)
+      )
+
       auth_options = self.options.merge(auth_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)
+        token_request_from_auth_url(auth_url, auth_options, token_params)
       else
         create_token_request(token_params, auth_options)
       end
 
-      case token_request
-        when Ably::Models::TokenDetails
-          return token_request
-        when Hash
-          return Ably::Models::TokenDetails.new(token_request) if IdiomaticRubyWrapper(token_request).has_key?(:issued)
-        when String
-          return Ably::Models::TokenDetails.new(token: token_request)
+      convert_to_token_details(token_request).tap do |token_details|
+        return token_details if token_details
       end
 
-      token_request = Ably::Models::TokenRequest(token_request)
-
-      response = client.post("/keys/#{token_request.key_name}/requestToken",
-                             token_request.hash, send_auth_header: false,
-                             disable_automatic_reauthorise: true)
-
-      Ably::Models::TokenDetails.new(response.body)
+      send_token_request(token_request)
     end
 
     # Creates and signs a token request that can then subsequently be used by any client to request a token
@@ -277,21 +287,23 @@ 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_option || current_token_details || has_client_id? || token_creatable_externally?)
     end
 
     def client_id
-      options[:client_id]
+      @client_id || options[:client_id]
     end
 
-    def token
-      token_object = options[:token] || options[:token_details]
-
-      if token_object.kind_of?(Ably::Models::TokenDetails)
-        token_object.token
-      else
-        token_object
-      end
+    # When a client has authenticated with Ably and the client is either anonymous (cannot assume a +client_id+)
+    # or has an assigned +client_id+ (implicit in all operations), then this client has a validated +client_id+, even
+    # if that client_id is +nil+ (anonymous)
+    #
+    # Once validated by Ably, the client library will enforce the use of the +client_id+ identity provided by Ably, rejecting
+    # messages with an invalid +client_id+ immediately
+    #
+    # @return [Boolean]
+    def client_id_validated?
+      !!@client_id_validated
     end
 
     # Auth header string used in HTTP requests to Ably
@@ -327,7 +339,7 @@ module Ably
     #
     # @return [Boolean]
     def token_renewable?
-      token_creatable_externally? || (api_key_present? && !token)
+      token_creatable_externally? || (api_key_present? && !token_option)
     end
 
     # Returns false when attempting to send an API Key over a non-secure connection
@@ -338,8 +350,59 @@ module Ably
       client.use_tls? || using_token_auth?
     end
 
+    # True if token provided client_id is compatible with the client's configured +client_id+, when applicable
+    #
+    # @return [Boolean]
+    # @api private
+    def token_client_id_allowed?(token_client_id)
+      return true if client_id.nil? # no explicit client_id specified for this client
+      return true if client_id == '*' || token_client_id == '*' # wildcard supported always
+      token_client_id == client_id
+    end
+
+    # True if assumed_client_id is compatible with the client's configured or Ably assigned +client_id+
+    #
+    # @return [Boolean]
+    # @api private
+    def can_assume_client_id?(assumed_client_id)
+      if client_id_validated?
+        client_id == '*' || (client_id == assumed_client_id)
+      elsif !options[:client_id] || options[:client_id] == '*'
+        true # client ID is unknown
+      else
+        options[:client_id] == assumed_client_id
+      end
+    end
+
+    # Configures the client ID for this client
+    # Typically this occurs following an Auth or receiving a {Ably::Models::ProtocolMessage} with a +client_id+ in the {Ably::Models::ConnectionDetails}
+    #
+    # @api private
+    def configure_client_id(new_client_id)
+      # If new client ID from Ably is a wildcard, but preconfigured clientId is set, then keep the existing clientId
+      if has_client_id? && new_client_id == '*'
+        @client_id_validated = true
+        return
+      end
+
+      # If client_id is defined and not a wildcard, prevent it changing, this is not supported
+      if client_id && client_id != '*' &&  new_client_id != client_id
+        raise Ably::Exceptions::IncompatibleClientId.new("Client ID is immutable once configured for a client. Client ID cannot be changed to '#{new_client_id}'", 400, 40012)
+      end
+      @client_id_validated = true
+      @client_id = new_client_id
+    end
+
+    # True when a client_id other than a wildcard is configured for Auth
+    #
+    # @api private
+    def has_client_id?
+      client_id && (client_id != '*')
+    end
+
     private
     attr_reader :client
+    attr_reader :token_option
 
     def ensure_valid_auth_attributes(attributes)
       if attributes[:timestamp]
@@ -401,17 +464,21 @@ module Ably
 
     # Returns the current token if it exists or authorises and retrieves a token
     def token_auth_string
-      # If a TokenDetails object has been issued by this library
-      # then that Token will take precedence
-      if @current_token_details
-        authorise.token
-      elsif token # token string was configured in the options
-        token
+      if !current_token_details && token_option
+        # A TokenRequest was configured in the ClientOptions +:token field+ and no current token exists
+        # Note: If a Token or TokenDetails is provided in the initializer, the token is stored in +current_token_details+
+        authorise_with_token send_token_request(token_option)
+        current_token_details.token
       else
+        # Authorise will use the current token if one exists and is not expired, otherwise a new token will be issued
         authorise.token
       end
     end
 
+    def configure_current_token_details(token_details)
+      @current_token_details = token_details
+    end
+
     # Token Auth HTTP Authorization header value
     def token_auth_header
       "Bearer #{encode64(token_auth_string)}"
@@ -455,15 +522,20 @@ module Ably
     # Retrieve a token request from a specified URL, expects a JSON response
     #
     # @return [Hash]
-    def token_request_from_auth_url(auth_url, auth_options)
+    def token_request_from_auth_url(auth_url, auth_options, token_params)
       uri = URI.parse(auth_url)
       connection = Faraday.new("#{uri.scheme}://#{uri.host}", connection_options)
-      method = auth_options[:auth_method] || :get
+      method = auth_options[:auth_method] || options[:auth_method] || :get
+      params = (auth_options[:auth_params] || options[:auth_method] || {}).merge(token_params)
 
       response = connection.send(method) do |request|
         request.url uri.path
-        request.params = CGI.parse(uri.query || '').merge(auth_options[:auth_params] || {})
         request.headers = auth_options[:auth_headers] || {}
+        if method.to_s.downcase == 'post'
+          request.body = params
+        else
+          request.params = (Addressable::URI.parse(uri.to_s).query_values || {}).merge(params)
+        end
       end
 
       if !response.body.kind_of?(Hash) && !response.headers['Content-Type'].to_s.match(%r{text/plain}i)
@@ -474,6 +546,42 @@ module Ably
       response.body
     end
 
+    # Use the provided token to authenticate immediately and store the token details in +current_token_details+
+    def authorise_with_token(new_token_details)
+      if new_token_details && !new_token_details.from_token_string?
+        if !token_client_id_allowed?(new_token_details.client_id)
+          raise Ably::Exceptions::IncompatibleClientId.new("Client ID '#{new_token_details.client_id}' in the token is incompatible with the current client ID '#{client_id}'", 400, 40012)
+        end
+        configure_client_id new_token_details.client_id
+      end
+      configure_current_token_details new_token_details
+    end
+
+    # Returns a TokenDetails object if the provided token_details_obj argument is a TokenDetails object, Token String
+    # or TokenDetails JSON object.
+    # If the token_details_obj is not a Token or TokenDetails +nil+ is returned
+    def convert_to_token_details(token_details_obj)
+      case token_details_obj
+        when Ably::Models::TokenDetails
+          return token_details_obj
+        when Hash
+          return Ably::Models::TokenDetails.new(token_details_obj) if IdiomaticRubyWrapper(token_details_obj).has_key?(:issued)
+        when String
+          return Ably::Models::TokenDetails.new(token: token_details_obj)
+      end
+    end
+
+    # @return [Ably::Models::TokenDetails]
+    def send_token_request(token_request)
+      token_request = Ably::Models::TokenRequest(token_request)
+
+      response = client.post("/keys/#{token_request.key_name}/requestToken",
+                             token_request.hash, send_auth_header: false,
+                             disable_automatic_reauthorise: true)
+
+      Ably::Models::TokenDetails.new(response.body)
+    end
+
     # Return a Hash of connection options to initiate the Faraday::Connection with
     #
     # @return [Hash]
@@ -501,7 +609,7 @@ module Ably
         # Raise exceptions if response code is invalid
         builder.use Ably::Rest::Middleware::ExternalExceptions
 
-        setup_incoming_middleware builder, client.logger
+        setup_incoming_middleware builder, logger
 
         # Set Faraday's HTTP adapter
         builder.adapter Faraday.default_adapter
@@ -520,12 +628,12 @@ module Ably
       auth_callback_present? || token_url_present?
     end
 
-    def has_client_id?
-      !!client_id
-    end
-
     def api_key_present?
       key_name && key_secret
     end
+
+    def logger
+      client.logger
+    end
   end
 end