Merge branch 'requestToken-arity-fix' into source

content/client-lib-development-guide/features.textile

@@ -101,27 +101,37 @@ h3(#rest-auth). Auth
 *** @(RSA7b2)@ Token authentication is being used, and the @TokenRequest@ or @TokenDetails@ object, used for authentication, has a @clientId@ value
 *** @(RSA7b3)@ Following a realtime connection being established, if the @CONNECTED@ @ProtocolMessages@ contains a @clientId@ in the @ConnectionDetails@ object, which is optionally present in @ProtocolMessage#connectionDetails@
 * @(RSA8)@ @Auth#requestToken@ function:
+** @(RSA8e)@ Method signature is @requestToken(TokenParams, AuthOptions)@. @TokenParams@ and @AuthOptions@ are optional. When provided, the values supersede matching client library configured params and options.
 ** @(RSA8a)@ Implicitly creates a @TokenRequest@ if required, and requests a token from Ably if required. Returns a @TokenDetails@ object
 ** @(RSA8b)@ Supports all @TokenParams@ in the function arguments, which override defaults for @Client@ @Auth@.
-** @(RSA8c)@ When @authUrl@ option is set, it will retrieve the token from the provided URL using the HTTP @authHeaders@, query string @authParams@ and @authMethod@ (@GET@ or @POST@) HTTP verb.  The token retrieved is assumed by the library to be a token string if the response has @Content-Type@ @"text/plain"@, or taken to be a @TokenRequest@ or @TokenDetails@ object if the response has @Content-Type@ @"application/json"@. It can be quite difficult to add test coverage for these scenarios - as such, we have developed a simple echo server that can be used in your tests, see the "ably-js authUrl echo tests":https://github.com/ably/ably-js/commit/e77b2c6c197bc71f3d27084fe54524724a00bc92
-** @(RSA8d)@ When @authCallback@ option is set, it will execute the callback and will expect either a token string, a @TokenDetails@ object or a @TokenRequest@ object which will in turn be used to request a token from Ably.
+** @(RSA8c)@ When @authUrl@ option is set, it will query the provided URL to obtain a @TokenRequest@ or the token itself (either a token string or a @TokenDetails@). The query is performed using the given URL using the HTTP method in @authMethod@, headers (from @authHeaders@) and supplementary params (from @authParams@). The token retrieved is assumed by the library to be a token string if the response has @Content-Type@ @"text/plain"@, or taken to be a @TokenRequest@ or @TokenDetails@ object if the response has @Content-Type@ @"application/json"@. @authMethod@ can be either @GET@ or @POST@, or if not specified, will default to @GET@. It can be quite difficult to add test coverage for these scenarios - as such, we have developed a simple echo server that can be used in your tests, see the "ably-js authUrl echo tests":https://github.com/ably/ably-js/commit/e77b2c6c197bc71f3d27084fe54524724a00bc92
+*** @(RSA8c1)@ @TokenParams@ and any configured @authParams@ are always sent to the @authUrl@ as follows:
+**** @(RSA8c1a)@ When the @authMethod@ is @GET@ or unspecified, the combined params are appened to the URL as query string params
+**** @(RSA8c1b)@ When the @authMethod@ is @POST@, the combined params are sent in the body of the @POST@ request
+*** @(RSA8c2)@ @TokenParams@ take precedence over any configured @authParams@ when a name conflict occurs
+*** @(RSA8c3)@ Specifying @authParams@ as part of @AuthOptions@ replaces any configured @authParams@ specified in @ClientOptions@. As the key/value pairs are not merged, this enables a developer to delete @authParams@ where necessary by providing an entire new set of @authParams@
+** @(RSA8d)@ When @authCallback@ option is set, it will invoke the callback, passing in the @TokenParams@, and expects either a token string, a @TokenDetails@ object or a @TokenRequest@ object to be returned, which will in turn be used to request a token from Ably
 * @(RSA9)@ @Auth#createTokenRequest@ function:
+** @(RSA9h)@ Method signature is @createTokenRequest(TokenParams, AuthOptions)@. @TokenParams@ and @AuthOptions@ are optional. When provided, the values supersede any client library configured params and options.
 ** @(RSA9a)@ Returns a signed @TokenRequest@ object that can be used to obtain a token from Ably. This is useful for servers that can create a @TokenRequest@ signed with the API key without communicating with Ably directly. The @TokenRequest@ can then be passed to a designated client that is then responsible for communicating with Ably and requesting a token for authentication from that @TokenRequest@
 ** @(RSA9b)@ Supports all @AuthOptions@
 ** @(RSA9c)@ Generates a unique 16+ character @nonce@ if none is provided; the nonce is used to protect against replay attacks
 ** @(RSA9d)@ Generates a @timestamp@ from current time if not provided, will retrieve the server time if @queryTime@ is true
 ** @(RSA9e)@ TTL is optional and specified in milliseconds
 ** @(RSA9f)@ Capability JSON text can be provided that specifies the rights of the token in terms of the channel(s) authorised and the permitted operations on each
 ** @(RSA9g)@ A valid HMAC is created using the key secret  to sign the @TokenRequest@ so that it can be used by any client to request a token without having or exchanging any secrets
+** @(RSA9i)@ Adheres to all requirements in @RSA8@ relating to @TokenParams@, @authCallback@ and @authUrl@
 * @(RSA10)@ @Auth#authorise@ function:
 ** @(RSA10a)@ Instructs the library to create a token if needed and uses Token Auth for all future requests
+** @(RSA10j)@ Method signature is @authorise(TokenParams, AuthOptions)@. @TokenParams@ and @AuthOptions@ are optional. When provided, the values supersede any client library configured params and options.
 ** @(RSA10b)@ Supports all @AuthOptions@ and @TokenParams@ in the function arguments
 ** @(RSA10c)@ Will not create a new token unless no previous token exists or current token has expired. Please note that a buffer of 15s for token expiry is recommended to avoid race conditions where the token is valid at the time of the request, but invalid when it reaches the server. Therefore, we recommend that a token is considered expired 15s before the time field `expires`
 ** @(RSA10d)@ Providing the option @force@ set to true will force @authorise@ to issue a new token even if an existing token exists.
 ** @(RSA10e)@ Adheres to the implementation of @requestToken@ when issuing new tokens
 ** @(RSA10f)@ Returns a @TokenDetails@ object that contains the token string + token metadata
 ** @(RSA10g)@ Stores the @AuthOptions@ and @TokenParams@ arguments as defaults for subsequent authorisations
 ** @(RSA10h)@ Will use the configured @Auth#clientId@ by default, if not @null@
+** @(RSA10i)@ Adheres to all requirements in @RSA8@ relating to @TokenParams@, @authCallback@ and @authUrl@
 
 h3(#rest-channels). Channels
 
@@ -584,9 +594,9 @@ h4. ClientOptions
 *** @(TO3j4)@ @useTokenAuth@ boolean - When true, token authentication will always be used by the client
 *** @(TO3j5)@ @authCallback@ - A callback to call to obtain a signed @TokenRequest@, @TokenDetails@ or a token string. This enables a client to obtain token requests or tokens from another entity, so tokens can be renewed without the client requiring a key
 *** @(TO3j6)@ @authUrl@ string - A URL to query to obtain a signed @TokenRequest@, @TokenDetails@ or a token string. This enables a client to obtain token request or token from another entity, so tokens can be renewed without the client requiring a key
-*** @(TO3j7)@ @authMethod@ - The HTTP verb to be used when a request is made by the library to the @authUrl@. Defaults to @GET@
+*** @(TO3j7)@ @authMethod@ - The HTTP verb to be used when a request is made by the library to the @authUrl@. Defaults to @GET@, supports @GET@ and @POST@
 *** @(TO3j8)@ @authHeaders@ - Headers to be included in any request made by the library to the @authUrl@
-*** @(TO3j9)@ @authParams@ - Query params to be included in any request made by the library to the @authUrl@
+*** @(TO3j9)@ @authParams@ - Additional params to be included in any request made by the library to the @authUrl@, either as query params added to the URL in the case of @GET@, or form-encoded in the body in the case of @POST@
 *** @(TO3j10)@ @queryTime@ - If true, the library will query the Ably system for the current time instead of relying on a locally-available time of day
 ** @(TO3k)@ Development environment attributes:
 *** @(TO3k1)@ @environment@ string - for development environments only; allows a non-default Ably environment to be used such as @sandbox@
@@ -603,6 +613,17 @@ h4. TokenParams
 * @(TK2c)@ @clientId@ string -  A @clientId@ to associate with this token
 * @(TK2d)@ @timestamp@ long - The timestamp (in millis since the epoch) of this request. Timestamps, in conjunction with the @nonce@, are used to prevent n requests from being replayed
 
+h4. AuthOptions
+* @(AO1)@ A class providing configurable authentication options used when authenticating or issuing tokens explicitly. These options are used when invoking @Auth#authorise@, @Auth#requestToken@ and @Auth#createTokenRequest@
+* @(AO2)@ The attributes of @AuthOptions@ consist of:
+** @(AO2a)@ @key@ string - Full Ably key string, as obtained from dashboard, used when signing token requests locally
+** @(AO2b)@ @authCallback@ - A callback to call to obtain a signed @TokenRequest@, @TokenDetails@ or a token string. This enables a client to obtain token requests or tokens from another entity, so tokens can be renewed without the client requiring a key
+** @(AO2c)@ @authUrl@ string - A URL to query to obtain a signed @TokenRequest@, @TokenDetails@ or a token string. This enables a client to obtain token request or token from another entity, so tokens can be renewed without the client requiring a key
+** @(AO2d)@ @authMethod@ - The HTTP verb to be used when a request is made by the library to the @authUrl@. Defaults to @GET@, supports @GET@ and @POST@
+** @(AO2e)@ @authHeaders@ - Headers to be included in any request made by the library to the @authUrl@
+** @(AO2f)@ @authParams@ - Additional params to be included in any request made by the library to the @authUrl@, either as query params in the case of @GET@ or in the body in the case of @POST@
+** @(AO2g)@ @queryTime@ - If true, the library will query the Ably system for the current time instead of relying on a locally-available time of day
+
 h4. ChannelOptions
 * @(TB1)@ options provided when instancing a channel, see "Java ChannelOptions":https://github.com/ably/ably-java/blob/master/src/io/ably/types/ChannelOptions.java as a reference
 * @(TB2)@ The attributes of @ChannelOptions@ consist of: