API 1.1 ongoing review PR

Gemfile.lock

@@ -8,7 +8,7 @@ GEM
     clipboard (1.1.1)
     coderay (1.1.1)
     colored (1.2)
-    cri (2.9.1)
+    cri (2.10.1)
       colored (~> 1.2)
     domain_name (0.5.20170404)
       unf (>= 0.0.5, < 1.0.0)
@@ -58,7 +58,7 @@ GEM
       byebug (~> 9.0)
       pry (~> 0.10)
     rack (2.0.3)
-    rake (12.0.0)
+    rake (12.3.0)
     rb-fsevent (0.10.2)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)
@@ -103,4 +103,4 @@ RUBY VERSION
    ruby 2.4.1p111
 
 BUNDLED WITH
-   1.15.3
+   1.16.0

README.md

@@ -46,12 +46,13 @@ If you would prefer to use Docker, then you can set up the env as follows:
 Running on Heroku
 ----
 
-This repo will automatically run on Heroku, but relies on the following buildpacks:
+This repo will automatically run on Heroku, but relies on the following buildpacks (see https://github.com/ably-forks/heroku-buildpack-nanoc):
 
     $ heroku buildpacks
     === ably-docs Buildpack URLs
-    1. heroku/ruby
-    2. https://github.com/ably-forks/heroku-buildpack-nanoc.git
+    1. https://github.com/heroku/heroku-buildpack-ruby
+    2. https://github.com/ably-forks/heroku-buildpack-nanoc
+    3. https://github.com/heroku/heroku-buildpack-static
 
 Pull requests
 ----

app/assets/javascripts/application.js

@@ -39,7 +39,7 @@ $(function() {
     if (!idTag.length) {
       if (console.error) { console.error('Hash tag target #' + aid + ' is missing.  Could not scroll'); }
     } else {
-      $('body').animate({ scrollTop: idTag.offset().top - stickNavHeight }, 'fast', function() {
+      $('html, body').animate({ scrollTop: (Math.round(idTag.offset().top) - stickNavHeight) + "px" }, 'fast', function() {
         setTimeout(function() { navIsScrolling = false; }, 750);
       });
       var newUrl = document.location.href.replace(/#[^#]*$/,'') + '#' + aid;

content/rest-api/index.textile

@@ -1019,10 +1019,10 @@ bc[sh]. curl -X POST https://rest.ably.io/push/publish \
  -H "Content-Type: application/json" \
  --data \
  '
- {
+{
   "recipient": {
     "clientId": "myClientId"
-  }
+  },
   "notification": {
     "title": "Hello from Ably!",
     "body": "Example push notification from Ably."
@@ -1031,8 +1031,7 @@ bc[sh]. curl -X POST https://rest.ably.io/push/publish \
     "foo": "bar",
     "baz": "qux"
   }
-}
-'
+}'
 
 The @recipient@ field supports delivering either to devices "registered to Ably":#post-device-registration by device ID, by their associated client ID, or directly to devices using the underlying notifications service (GCM, APNs, etc.), thus bypassing registrations to Ably altogether.
 

content/root/how-ably-works.textile

@@ -149,7 +149,7 @@ Most of our client libraries use a WebSocket to establish a realtime connection
 
 However, client libraries such as our "Javascript browser library":https://github.com/ably/ably-js are designed to choose the best transport available based on the browser and connection available. By supporting additional transports with the ability to fallback to the lowest common denominator, Ably ensures that practically every browser in use today is able to establish a realtime connection to Ably. The following transports are currently supported by our "Javascript browser library":https://github.com/ably/ably-js in order of best to worst performing:
 
-* "WebSockets":https://en.wikipedia.org/wiki/WebSocket ("supported by 88% of browsers globally as of Nov 2015":http://caniuse.com/#feat=websockets)
+* "WebSockets":https://en.wikipedia.org/wiki/WebSocket ("supported by 94% of browsers globally as of Dec 2017":http://caniuse.com/#feat=websockets)
 * XHR streaming
 * XDR streaming
 * XHR polling

content/tutorials/publish-subscribe.textile

@@ -6,7 +6,7 @@ index: 10
 
 The Ably Realtime service organizes the message traffic within applications into named channels. Channels are the “unit” of message distribution; clients attach to any number of channels to subscribe to messages, and every message published to a channel is broadcasted to all subscribers. This scalable and resilient messaging pattern is commonly called pub/sub.
 
-As you can publish a message to any channel, channels provide a means for you to filter data by topic or enforce access control for your subscribers. Only subscribers for those channesl will receive those messages.
+As you can publish a message to any channel, channels provide a means for you to filter data by topic or enforce access control for your subscribers. Only subscribers for those channels will receive those messages.
 
 Messages published can contain string, JSON object, JSON array or binary data payloads.
 
@@ -119,7 +119,7 @@ blang[javascript].
     </script>
   ```
 
-  "See this step in Github":https://github.com/ably/tutorials/commit/843128d
+  "See this step in Github":https://github.com/ably/tutorials/commit/publish-subscribe-javascript-install-ably
 
 blang[nodejs].
   To start using Ably you first need to install the NPM module. The NPM module can be installed as follows:
@@ -379,7 +379,7 @@ blang[javascript].
     });
   ```
 
-  "See this step in Github":https://github.com/ably/tutorials/commit/de53537
+  "See this step in Github":https://github.com/ably/tutorials/commit/publish-subscribe-javascript-subscribe
 
 blang[nodejs].
   ```[nodejs]
@@ -499,7 +499,7 @@ blang[javascript].
     channel.publish("update", { "team": "Man United" });
   ```
 
-  "See this step in Github":https://github.com/ably/tutorials/commit/140583e
+  "See this step in Github":https://github.com/ably/tutorials/commit/publish-subscribe-javascript
 
 blang[nodejs].
   ```[nodejs]

content/types/_auth_options.textile

@@ -19,9 +19,9 @@ h4.
   ruby:    Attributes
   Python:  Attributes
 
-- <span lang="default">authCallback</span><span lang="csharp">AuthCallback</span><span lang="python">auth_callback</span><span lang="ruby">:auth_callback</span> := A <span lang="default">function</span><span lang="javascript,nodejs">function with the form @function(tokenParams, callback(err, tokenOrTokenRequest))@</span><span lang="java">@TokenCallback@ instance</span><span lang="python">callable (eg a lambda)</span><span lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</span> which is called when a new token is required. The role of the callback is to either generate a signed "@TokenRequest@":/realtime/types#token-request which may then be submitted automatically by the library to the "Ably REST API @requestToken@":/rest-api#request-token; or to provide a valid token in as a "@TokenDetails@":/realtime/types#token-details object. See "an authentication callback example":<%= JsBins.url_for('authentication/auth-callback') %> or "our authentication documentation":/rest/authentication for details of the token request format and associated API calls.<br>__Type: <span lang="default">@Callable@</span><span lang="java">@TokenCallback@</span><span lang="ruby">@Proc@</span><span lang="csharp">@Func<TokenParams, Task<TokenDetails>>@</span>__
+- <span lang="default">authCallback</span><span lang="csharp">AuthCallback</span><span lang="python">auth_callback</span><span lang="ruby">:auth_callback</span> := A <span lang="default">function</span><span lang="javascript,nodejs">function with the form @function(tokenParams, callback(err, tokenOrTokenRequest))@</span><span lang="java">@TokenCallback@ instance</span><span lang="python">callable (eg a lambda)</span><span lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</span> which is called when a new token is required. The role of the callback is to either generate a signed "@TokenRequest@":/realtime/types#token-request which may then be submitted automatically by the library to the "Ably REST API @requestToken@":/rest-api#request-token; or to provide a valid token in as a "@TokenDetails@":/realtime/types#token-details object. See "an authentication callback example":<%= JsBins.url_for('authentication/auth-callback') %> or "our authentication documentation":/rest/authentication for details of the token request format and associated API calls. Please note that the JSON stringified version of @TokenDetails@ or @TokenRequest@ must be less than 128kb.<br>__Type: <span lang="default">@Callable@</span><span lang="java">@TokenCallback@</span><span lang="ruby">@Proc@</span><span lang="csharp">@Func<TokenParams, Task<TokenDetails>>@</span>__
 
-- <span lang="default">authUrl</span><span lang="csharp">AuthUrl</span><span lang="ruby">:auth_url</span><span lang="python">auth_url</span> := A URL that the library may use to obtain a token string (in plain text format), or a signed "@TokenRequest@":/realtime/types#token-request or "@TokenDetails@":/realtime/types#token-details (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server.<br>__Type: <span lang="default">@String@</span><span lang="csharp">@Uri@</span><span lang="swift,objc">@NSURL@</span>__
+- <span lang="default">authUrl</span><span lang="csharp">AuthUrl</span><span lang="ruby">:auth_url</span><span lang="python">auth_url</span> := A URL that the library may use to obtain a token string (in plain text format), or a signed "@TokenRequest@":/realtime/types#token-request or "@TokenDetails@":/realtime/types#token-details (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server. Please note that the JSON stringified version of @TokenDetails@ or @TokenRequest@ must be less than 128kb.<br>__Type: <span lang="default">@String@</span><span lang="csharp">@Uri@</span><span lang="swift,objc">@NSURL@</span>__
 
 - <span lang="default">authMethod</span><span lang="csharp">AuthMethod</span><span lang="ruby">:auth_method</span><span lang="python">auth_method</span> := _<span lang="default">@GET@</span><span lang="ruby">@:get@</span>_ The HTTP verb to use for the request, either <span lang="default">@GET@</span><span lang="ruby">@:get@</span> or <span lang="default">@POST@</span><span lang="ruby">@:post@</span><br>__Type: <span lang="default">@String@</span><span lang="ruby">@Symbol@</span><span lang="csharp">@HttpMethod@</span>__
 

content/types/_client_options.textile

@@ -18,17 +18,17 @@ h4.
 
 - <span lang="default">key</span><span lang="csharp">Key</span><span lang="ruby">:key</span> := The full key string, as obtained from the "application dashboard":http://support.ably.io/solution/articles/3000030053-how-do-i-access-my-app-dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue tokens without needing to defer to a separate entity to sign token requests. Read more about "Basic authentication":/general/authentication#basic-authentication<br>__Type: @String@__
 
-- <span lang="default">token</span><span lang="csharp">Token</span><span lang="ruby">:token</span> := An authenticated token string that is most commonly obtained from the <span lang="default">@token@</span><span lang="csharp">@Token@</span> property of a "@TokenDetails@":/realtime/types#token-details component of a token request response. Use this option if you wish to use Token authentication. Read more about "Token authentication":/general/authentication#token-authentication<br>__Type: @String@__
+- <span lang="default">token</span><span lang="csharp">Token</span><span lang="ruby">:token</span> := An authenticated token. This can either be a "@TokenDetails@":/realtime/types#token-details object, a "@TokenRequest@":/realtime/types#token-request object, or token string obtained from the <span lang="default">@token@></span><span lang="csharp">@Token@</span> property of a "@TokenDetails@":/realtime/types#token-details component of a token request response. Use this option if you wish to use Token authentication. Read more about "Token authentication":/general/authentication#token-authentication<br>__Type: @String@, @TokenDetails@ or @TokenRequest@__
 
 - <span lang="default">tokenDetails</span><span lang="csharp">TokenDetails</span><span lang="python">token_details</span><span lang="ruby">:token_details</span> := An authenticated "@TokenDetails@":/realtime/types/#token-details object that is most commonly obtained from of a token request response. Use this option if you wish to use Token authentication. Read more about "Token authentication":/general/authentication#token-authentication<br>__Type: @TokenDetails@__
 
 - <span lang="default">tls</span><span lang="csharp">Tls</span><span lang="ruby">:tls</span> := _true_ A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication ensuring private keys are compromised in transit. "Find out more about TLS":https://support.ably.io/solution/articles/3000045208-are-messages-sent-to-and-received-from-ably-sent-security-using-tls<br>__Type: @Boolean@__
 
 - <span lang="default">clientId</span><span lang="csharp">ClientId</span><span lang="python">client_id</span><span lang="ruby">:client_id</span> := A client ID, used for identifying this client when publishing messages or for presence purposes. The <span lang="default">@clientId@</span><span lang="ruby,python">@client_id@</span><span lang="csharp">@ClientId@</span> can be any non-empty string. This option is primarily intended to be used in situations where the library is instanced with a key; note that a <span lang="default">@clientId@</span><span lang="ruby,python">@client_id@</span><span lang="csharp">@ClientId@</span> may also be implicit in a token used to instance the library; an error will be raised if a <span lang="default">@clientId@</span><span lang="ruby,python">@client_id@</span> specified here conflicts with the <span lang="default">@clientId@</span><span lang="ruby,python">@client_id@</span><span lang="csharp">@ClientId@</span> implicit in the token. "Find out more about client identities":/how-ably-works#client-identity<br>__Type: @String@__
 
-- <span lang="default">authCallback</span><span lang="csharp">AuthCallback</span><span lang="python">auth_callback</span><span lang="ruby">:auth_callback</span> := A <span lang="default">function</span><span lang="javascript,nodejs">function with the form @function(tokenParams, callback(err, tokenOrTokenRequest))@</span><span lang="java">@TokenCallback@ instance</span><span lang="python">callable (eg a lambda)</span><span lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</span> which is called when a new token is required. The role of the callback is to either generate a signed "@TokenRequest@":/realtime/types#token-request which may then be submitted automatically by the library to the "Ably REST API @requestToken@":/rest-api#request-token; or to provide a valid token in as a "@TokenDetails@":/realtime/types#token-details object. See "an authentication callback example":<%= JsBins.url_for('authentication/auth-callback') %> or "our authentication documentation":/rest/authentication for details of the token request format and associated API calls.<br>__Type: <span lang="default">@Callable@</span><span lang="java">@TokenCallback@</span><span lang="ruby">@Proc@</span><span lang="csharp">@Func<TokenParams, Task<TokenDetails>>@</span>__
+- <span lang="default">authCallback</span><span lang="csharp">AuthCallback</span><span lang="python">auth_callback</span><span lang="ruby">:auth_callback</span> := A <span lang="default">function</span><span lang="javascript,nodejs">function with the form @function(tokenParams, callback(err, tokenOrTokenRequest))@</span><span lang="java">@TokenCallback@ instance</span><span lang="python">callable (eg a lambda)</span><span lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</span> which is called when a new token is required. The role of the callback is to either generate a signed "@TokenRequest@":/realtime/types#token-request which may then be submitted automatically by the library to the "Ably REST API @requestToken@":/rest-api#request-token; or to provide a valid token in as a "@TokenDetails@":/realtime/types#token-details object. See "an authentication callback example":<%= JsBins.url_for('authentication/auth-callback') %> or "our authentication documentation":/rest/authentication for details of the token request format and associated API calls. Please note that the JSON stringified version of @TokenDetails@ or @TokenRequest@ must be less than 128kb.<br>__Type: <span lang="default">@Callable@</span><span lang="java">@TokenCallback@</span><span lang="ruby">@Proc@</span><span lang="csharp">@Func<TokenParams, Task<TokenDetails>>@</span>__
 
-- <span lang="default">authUrl</span><span lang="csharp">AuthUrl</span><span lang="python">auth_url</span><span lang="ruby">:auth_url</span> := A URL that the library may use to obtain a token string (in plain text format), or a signed "@TokenRequest@":/realtime/types#token-request or "@TokenDetails@":/realtime/types#token-details (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server.<br>__Type: <span lang="default">@String@</span><span lang="csharp">@Uri@</span>__
+- <span lang="default">authUrl</span><span lang="csharp">AuthUrl</span><span lang="python">auth_url</span><span lang="ruby">:auth_url</span> := A URL that the library may use to obtain a token string (in plain text format), or a signed "@TokenRequest@":/realtime/types#token-request or "@TokenDetails@":/realtime/types#token-details (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server. Please note that the JSON stringified version of @TokenDetails@ or @TokenRequest@ must be less than 128kb.<br>__Type: <span lang="default">@String@</span><span lang="csharp">@Uri@</span>__
 
 - <span lang="default">authMethod</span><span lang="csharp">AuthMethod</span><span lang="python">auth_method</span><span lang="ruby">:auth_method</span> := _<span lang="default">@GET@</span><span lang="ruby">@:get@</span>_ The HTTP verb to use for the request, either <span lang="default">@GET@</span><span lang="ruby">@:get@</span> or <span lang="default">@POST@</span><span lang="ruby">@:post@</span><br>__Type: <span lang="default">@String@</span><span lang="ruby">@Symbol@</span><span lang="csharp">@HttpMethod@</span>__