Package: openlabs_nereid_chat
Browser based Chat 1.0======================This document describes the protocol behind the chat system used bynereid. We looked around for a possible standard based on which we couldwrite a chat application which works within the browser. The search wasfutile and this is an attempt to write a generic implementation inspiredby XMPP to address browser based chat.1. Introduction---------------1.1 Overview~~~~~~~~~~~~This protocol is a protocol fr streaming JSON in order to exchange messagesand presence information in close to realtime.1.2 Requirements~~~~~~~~~~~~~~~~1. Compatible with most browsers.2. Compatible with proxies3. Fully compatible with HTTP/1.0.4. Fault Tolerant5. Extensible6. MUC rooms2. Concepts-----------2.1 Authentication~~~~~~~~~~~~~~~~~~This protocol does not define any authentication mechanism of its own, butleaves it to the underlying HTTP layer.2.2 Thread~~~~~~~~~~Thread an identifier that is used for tracking a conversation thread(sometimes referred to as an "instant messaging session") between twoentities.Every conversation in the system, to an individual user or to a group ofusers (MUC) happens in a thread. When a new message is initiated to anindividual or a group of users, a thread is created if one does notalready exist with the given users. The thread id need not be humanreadable.3. Syntax of Stanzas--------------------The basic semantics and common attributes of JSON objects specific to theimplementation are outlined below.Example of a complete stanza~~~~~~~~~~~~~~~~~~~~~~~~~~~~.. code:: js{"timestamp": "2011-02-10T15:04:55Z","stanzas": [{"type": "message""message": {"subject": "Optional topic of conversation","text": "The message body""type": "plain","language": "en_US","attachments": [],"id": "","thread": "thread-id","sender": {"url": "http://example.org/martin","objectType": "person","id": "tag:example.org,2011:martin","foo2": "some other extension property","image": {"url": "http://example.org/martin/image","width": 250,"height": 250},"displayName": "Martin Smith"},},},{"type": "presence""presence": [{"entity": "nereid.user,123","show": "chat","status": "A happy day","available": true,}, {"entity": "nereid.user,13","show": "dnd","status": "Busy in a meeting","available": true,}],}]3.1 Message~~~~~~~~~~~Message stanzas are used to push information to another entity. Messagessent in the context of a chat conversation are sent in a message stanza tothe recipients.3.1.1 Subject.............The `subject` attribute contains human-readable data that specifies the topicof the message. The attribute is optional3.1.2 Text...........The `text` attribute contains human-readable data that specifies thetextual contents of the message; this attribute is normally includedbut is OPTIONAL.3.1.3 Type...........The `type` attribute contains the Content-Type minor for the textualcontents of the message. The attribute is OPTIONAL and the default valueof the type is assumed to be `plain`. Possible values are:* `plain`* `html`* `rst`3.1.4 Language..............The `language` attribute is used to help identify the human language inwhich the textual contents of the message are composed. The language isspecified in accordance with the IETF best practice, specified by `RFC5646` and `RFC 4647` for easy parsing by a computer. An example oflanguage is `en-US` (English as used in the United States (US is theISO 3166‑1 country code for the United States)3.1.5 Attachments.................TODO3.1.6 ID........This is meant to be a RFC 4122 compliant GUID for the message generated onthe client side. An UUID v4 generated should be sufficient.3.1.7 Thread............The thread attribute contains non-human-readable character data specifying anidentifier that is used for tracking a conversation thread (sometimes referredto as an "instant messaging session") between two entities. The value of thethread attribute is generated by the sender and SHOULD be copied back in anyreplies.If left empty, the server implementation could decide if the message is acontinuation of an existing conversation or a new conversation could becreated for the purpose.If used, it MUST be unique to that conversation thread within the stream andMUST be consistent throughout that conversation (a client that receives amessage from the same sender but with a different thread ID MUST assume thatthe message in question exists outside the context of the existing conversationthread).3.1.8 Sender............Inspired from the actor in activity stream specification.TODO: Elaborate in detail3.1.9 Example Message....................... code:: js{"timestamp": "2011-02-10T15:04:55Z","type": "message""message": {"subject": "Optional topic of conversation","text": "The message body""type": "plain","language": "en_US","attachments": [],"id": "","thread": "thread-id","sender": {"url": "http://example.org/martin","objectType": "person","id": "tag:example.org,2011:martin","foo2": "some other extension property","image": {"url": "http://example.org/martin/image","width": 250,"height": 250},"displayName": "Martin Smith"},},}3.2 Presence~~~~~~~~~~~~Presence stanzas are used to express an entity's current network availability(offline or online, along with various sub-states of the latter and optionaluser-defined descriptive text), and to notify other entities of thatavailability. Unlike XMPP Presence stanzas are **not** used to negotiateand manage subscriptions to the presence of other entities. Webapplications are assumed to have their own unique ways of handlingsubscriptions.3.2.1 Available...............A boolean value to indicate if the user is available for communication.3.2.2 Show..........The OPTIONAL attribute contains non-human-readable character data thatspecifies the particular availability status of an entity or specificresource.* away -- The entity or resource is temporarily away.* chat -- The entity or resource is actively interested in chatting.* dnd -- The entity or resource is busy (dnd = "Do Not Disturb").* xa -- The entity or resource is away for an extended period(xa = "eXtended Away").3.2.3 Status............The OPTIONAL status element contains character data specifying anatural-language description of availability status. It is normallyused in conjunction with the show element to provide a detaileddescription of an availability state (e.g., "In a meeting").3.2.4 Entity............The unique identifier of the entity of which the presence stanza hasinformation about.3.2.5 Example Presence....................... code:: js{"type": "presence""presence": [{"entity": "nereid.user,123","show": "chat","status": "A happy day","available": true,}, {"entity": "nereid.user,13","show": "dnd","status": "Busy in a meeting","available": true,}],}4. Chat Token-------------4.1 Overview~~~~~~~~~~~~Authorized token to fetch chat stream without nereid cookies based login.4.2 Usage with Session-less tokens~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Quiet often chat is a part of a larger application and given the newtrends of single page applications, you may want to use the chatfunctionality without sessions. To implement the same this moduleprovides an API where an access token is initially generated by alogged in user which can then be used exclusively to subscribe tochat messages, notifications and send new messages.This token cannot be used for any other requests... note::For scalability reasons the chat tokens are stored in rediswith TTL of 1 hour.4.2.1 Generate chat token.........................Chat token can be generated by sending a POST request to the followingURL... code::POST /nereid-chat/tokenResponse:.. code::HTTP/1.1 200 OK{'token': '550e8400-e29b-41d4-a716-446655440000'}4.2.2 Subscribing to stream using token........................................Once a token is received with the above mentioned method call,it can then be used to subscribe to the event stream using thespecial handler shown below. Unlike the regular stream handler,this one expects a token... code::GET /nereid-chat/stream/<token>