#format rst

===========================
LongPoll JavaScript library
===========================

The `long-poll JavaScript library`_ is responsible for connecting to
`txlongpoll`_ and firing JavaScript events to reflect the state
of this connection and make RabbitMQ events available to the
JavaScript layer.

.. _`long-poll JavaScript library`: http://bazaar.launchpad.net/~launchpad-pqm/launchpad/devel/view/head:/lib/lp/app/longpoll/javascript/longpoll.js

.. _txlongpoll: https://launchpad.net/txlongpoll

Connection
----------

The long-poll library will issue a connection to the long-poll server
iff LP.cache.longpoll.uri and LP.cache.longpoll.key are populated in
the JSON cache.  After each successful or failed connection, the long-poll library reconnects to the long-poll server to be able to handle
new events.

`Request Timeout errors`_ are expected and are ignored by the long-poll JavaScript code (i.e. a new request is started when such an error happens).

.. _`Request Timeout errors`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9

Events
------

Two kind of events are fired by the long-poll JavaScript
library. Events deriving from LongPollEvents and "system" events
indicating the state of the long-polling connection. Here is a list of
all the possible events fired by the JavaScript long-poll library:

*event_key*
  fired each time RabbitMQ passes an event created using the
  LongPollEvent adapter (event_key being the name of the RabbitMQ
  event).

  For instance, this in LP python code::

   # subscription code omitted.
   class FakeEvent(LongPollEvent):

       implements(ILongPollEvent)

       @property
       def event_key(self):
          return "event-key-test"

   event = FakeEvent("source")
   event_data = {"hello": 1234}
   event.emit(**event_data)

  ... will result in an event being fired on the JavaScript side::

   Y.fire("event-key-test", {"hello": 1234});

*'lp.app.longpoll.failure'*
  fired each time a long-poll transaction fails. This might be because
  of connection problems or because the library failed to parse the
  event payload.

  To avoid hammering the server in case of an outage, the long-poll
  JavaScript library waits for 1 second before reconnecting.  Also,
  after 5 failed connections, the library will wait 3 minutes before
  trying to reconnect. The following events can be used to make the
  end user aware of the connection status:


*'lp.app.longpoll.longdelay'*
  fired each time the library switches in 'longdelay' mode (i.e. after
  5 failed connections).


*'lp.app.longpoll.shortdelay'*
  fired each time the library switches back in 'shortdelay' mode
  (i.e. after at least 5 failed connections and then after a
  successful connection).

Testing
-------

Since all the long-poll JavaScript library will be doing is firing
JavaScript events, testing a JavaScript application that interacts
with this library is pretty straightforward. Simply fire the events
and make sure the application reacts appropriately::

 // Fire "event-key-test".
 Y.fire("event-key-test", {"hello": 1234});

 // Simulate a failure.
 Y.fire("lp.app.longpoll.failure");

 // Simulate the library going into 'longdelay' mode.
 Y.fire("lp.app.longpoll.longdelay");