ably / docs Goto Github PK

Ensure closing & reopening starts a new connection

Stats can be retrieved selectively, this should be documented.

See ably/ably-js#116

@paddybyers and @kouno, please can you review my changes in the docs repo over the last few days, see 8a62a69...source

The biggest chunks of work are:

• Reorganisation of the client library developer guide sections with lots of new content
• Support for wider variable interpolation within code examples
• Update of out of date documentation include Authentication, WebSocket & Comet transports, Encryption, Real-time Protocol, REST API etc. I am focussing on this now because I want to help client lib developers by having docs that are up to date. @paddybyers especially, please can you review my changes as it's quite likely there are still parts that are wrong. I am less worried about missing docs however quite worried if the docs are wrong.
• I set up the Quick Start Guide as a test to see if I could get the "Try it" live code editor working again properly with our JSBin. This all works now and the workflow is actually quite easy, you can either work in repo itself and the changes to JSBin are pushed up live when running guard, or you can edit in JSbin and then export back to docs by appending .textile to the URL in JSBin.

Please can you review these changes as soon as possible as I will be telling all client library developers that the documentation in those sections is now mostly up to date.

@kouno we are also now ready to get going with integrating our examples into the docs repo.

Update all REST API documentation to include up to date API specifications, intro guides, and simple examples for JS, Ruby, Java

See ably/ably-js#43 (comment)

For example, how long we retain messages when a connection is dropped, or how many messages can be retained by the connection state on a frontend, total messages per second, message size etc.

┆Issue is synchronized with this Jira Task by Unito

So RTP8g says that the client lib, for Presence#enter, Raises an exception if the channel is DETACHED or FAILED.

This seems inconsistent with other actions that trigger an implicit attach (eg channel#publish), for which the client lib triggers an implicit attach for a detached channel just as for an initialized one. Presence#enter is the only action that has both an Implicitly attaches to the channel if not attached and a Raises an exception if the channel is DETACHED or FAILED requirement (the only other action that has the latter is Presence#get, which does not have an implicit attach requirement).

Current client lib behaviour: ably-js treats detached and initialized channels the same for all of these, and implicitly attaches. Ably-ruby has all presence broadcast-type actions raising an exception if called on a detached channel.

Not obvious to me why implicit attaching should behave differently between presence actions and others.

(Also for realtime presence#get: if we don't want to make it an implicit-attach action, shouldn't it raise an exception if in any state other than attached, not just detached or failed?)

We don't currently support versioning in the documentation.

Once all libraries reach 0.8 compatibility, we will need to review how we can publish updates to the docs, but allow people to access older versions.

@paddybyers, @SimonWoolf and @kouno FYI, something to think about in the near future.

See ably/ably-js#45 (comment)

This needs to be brought in line with version 0.7 of our client libraries.

Various discussions relating to the clientId requires a spec change to ensure client libraries correctly set, enforce, and send the clientId to Ably.

Update documentation in line with issue 131 of Ably.

See https://github.com/ably/website/issues/164#issuecomment-90643915

See ably/ably-js#99 for more information.

If we know the underlying internet connection has gone away or come back, we can act on that immediately.

FYI @paddybyers

If the client has a valid token, and authorise is called with new token params, a new token is generated. Need to check if the spec states the new params should be used for subsequent requests or not

High level how does it work with threads / events / blocking etc.

#59 (comment)

For example:

JSON format

String payload -> encoding = ""
Binary payload -> encoding = "base64"
JSON payload -> encoding = "json"
Cipher JSON payload -> encoding = "json/utf-8/cipher+aes-128-cbc/base64"

MSGPACK format

String payload -> encoding = ""
Binary payload -> encoding = ""
JSON payload -> encoding = "json"
Cipher JSON payload -> encoding = "json/utf-8/cipher+aes-128-cbc"

@kouno can you please create an Angular version of either the Backbone.js or Ember.js examples at http://docs.ably.io/code-index/. The examples are in https://github.com/ably/docs/tree/source/content/code/website-examples.

Once done, please can you incorporate into the website, see https://github.com/ably/website/commit/7a59aca3e05241097306275d3b1a7226d390aca4 for an example.

Instead of

bc[lang]. # first line must be here
# second line

Line break above causes code block to end

We should be able to use

```lang
 # first line

 # line break above is allowed
```.

Probably slightly less important these days, but necessary. We need to get all the pages up to date for client library developers.

See http://docs.ably.io/client-lib-development-guide/, http://docs.ably.io/client-lib-development-guide/comet/, http://docs.ably.io/client-lib-development-guide/connection-manager/, http://docs.ably.io/client-lib-development-guide/encryption/, http://docs.ably.io/client-lib-development-guide/recovery/, http://docs.ably.io/client-lib-development-guide/websocket/. Lots to do, enjoy ;)

Also on the website

Whilst working through the documentation today, I found that referring to clients that have a clientId as authenticated clients could be very confusing for users. This is probably because being authenticated has no relation to your authentication with Ably via a token or API key, and the word authentication exists in Basic Authentication as well.

Having had a quick chat about this, @paddybyers and I came up with the following suggestion, which should not have any impact on the client libraries fortunately, but will simply be rolled out in our documentation.

@SimonWoolf and @lmars, do you have any objections or suggestions to improve this terminology?

Authentication

The process of providing credentials to Ably in the form of a token or API key, which in turn allows you to communicate with Ably if the credentials are valid.

Authorisation

Ably is responsible for authorising or refusing operations for the authenticated client based on the permissions specified within the API key and/or Token provided when the client authenticated.

Identified Client

Any client that has connected to Ably and has either explicitly provided a clientId when instancing the library, or implicitly been assigned a clientId following token authentication, will then assume and be restricted to that clientId for all operations. As our customers are responsible for issuing tokens or token requests themselves, and we recommend that they only use token authentication and never share their private keys with clients, an identified client publishing or present on a channel with the clientId given in their token can therefore be trusted by other clients.

There are other features of the rest API that I think are also not in the docs, eg
?fields= (see Using-the-Admin-API#fields)
?select= (see Using-the-Admin-API#select)
?flatten= (see Using-the-Admin-API#flatten)

In getting the java library to run on Android I've run into the issue that the base HTTP primitive (HttpURLConnection) doesn't give you access to the response body in the case that:

1. the statusCode is 401 or 407; and
2. there is a request body (usually POST).

The reason is that under these circumstances the request body upload is forcibly terminated by closing the connection, and that in turn means that the response body is not read.

Response headers are available (and really do have to be, because otherwise WWW-Authenticate challenges would not work) so I've added the following headers to all error responses:

X-Ably-ErrorCode
X-Ably-ErrorMessage

These (with the statusCode) mean that a full error object can be constructed even if the response body is lost. (These are present for all error responses irrespective of method, where the error comes from the realtime system; but obviously not for errors arising downstream such as the loadbalancer.)

@paddybyers, @kouno and @SimonWoolf, would you mind reviewing the latest update I have made to the "Realtime Connection documentation":http://docs.ably.io/realtime/connection/ with commit deee337. Note this is published to http://docs.ably.io/realtime/connection/, and the Types page is at http://docs.ably.io/realtime/types/

There have been various other fixes and tweaks to the docs repo, however I think this commit is the only one relevant to review.

See http://docs.ably.io/rest-api/#presence

@paddybyers can you review my comments on your last commit in regards to the feature spec please?

paddybyers@db991f0

Hopefully I can then circulate the spec to everyone.

See discussion at ably/ably-js#118

• Retry immediately if a connection disconnects from a connected state
• Retry every 15s whilst in the disconnected state
• Moves to suspended state within 2 minutes
• Retry every 30s whilst in the suspended state
• Review the fallback strategy when connection fails because of network or server issues
• Allow defaults to be reconfigured before instancing the library, with a defaults option.
• Add REST request timeout

See ably/ably-js#108

This was not in the spec previously

It will make life a lot easier if developers can issue simple curl commands from within the documentation

I noticed that the documentation is missing a page that describes how the test provisioning API works, see http://docs.ably.io/client-lib-development-guide/

It would be useful if this was documented.

In the overview section for each client library, we should provide an architecture overview so that developers understand the principles behind the design of the library. For example, in Java it is threaded, in Ruby it relies on EventMachine, and Go uses Mutexes, Go routines & Channels. This overview should be replicated in the client library READMEs as well.

@paddybyers please see ably/ably-ruby@23877d5#diff-5a92463d6ab8ad3fc8cf8aff5cfde6f8R573

I have implemented a new feature in the Ruby library following a discussion with Peter a few days ago as follows:

• Connection is opened
• Message is published over the transport
• The transport is disconnected
• The connection is resumed with a new transport
• The message ACK has not yet been received because the transport was disconnected beforehand, so the client library resends the message and gets an ACK

I would like your view on whether this is the correct behaviour. The alternative is to fail the message that was sent, but that does not feel right given it was actually sent successfully.

In the same way that Channel#publish throws an exception when publishing in a channel or connection state that is not acceptable (depending on the queueMessages client option), see RTN6c2 and RTN6c3 of http://docs.ably.io/client-lib-development-guide/features/, I propose we add the same expectation for all Presence events that publish messages such as enter, enterClient, update, leave etc.

@paddybyers thoughts?

Better to use the naming convention of {{KEY_NAME}} and {{KEY_SECRET}} for the two parts either side of the : of API keys. This will need to be updated on the website once rolled out.

Once #64 is finalise, update the spec spreadsheets with the recent batch of refinements to the spec. Also need confirmation on when ConnectionDetails wildcard is supported.

I think this is one for you. @kouno and I will tackle the client lib API docs.

@paddybyers and @kouno finally completed the spec for both realtime & REST, see http://docs.ably.io/client-lib-development-guide/features/

Please can you review and fixup any issues you foresee or add your comments here and I will amend. If you notice anything missing please add too.

I will be using this as a check list for all client library developers to confirm what amount of functionality exists and is tested in each client library, so it's important we get this right as it will into a Google Doc with a list to code to prove the feature is implemented.

Update all Real-time API documentation to include up to date API specifications, intro guides, and simple examples for JS, Ruby, Java

Scenario as follows:

1. Client connects
2. Client attaches to channel bacon
3. Client publishes 5 messages to bacon
4. Transport disconnects, and client automatically tries to reconnect
5. Whilst reconnecting the developer publishes 5 more messages to the bacon channel, and another client publishes 3 messages to the bacon channel.
6. Client reconnects, but is unable to resume, so detaches all channels

Question:

• Should the queued messages for the channel that is not attached fail those messages as the channel is now failed?
• Could we publish the messages anyway when we introduce the functionality to publish without being attached?

@paddybyers WDYT?