PollDance
---------
Date: January 28th, 2013
Authors: Justin Karneges <justin@fanout.io>
         Katsuyuki Ohmuro <harmony7@pex2.jp>

PollDance is a general-purpose AJAX library, implementing multiple transports
to ensure cross-domain access works in all major browsers. It also provides
conveniences for long-polling applications such as retries, exponential
backoff between requests, randomized request delaying, and workarounds for
browser "busy" indications.

Dependencies:

  json2.js

Available Transports:

  XmlHttpRequest - for all modern CORS browsers
  JSON-P - for IE7, IE8, IE9, and older versions of other browsers

Limitations:

  - If the JSON-P transport is used, the request headers and body are subject
    to URI length limitations of the browser and server.
  - If the JSON-P transport is used, it may not be possible to inspect all of
    the response headers. At most, the server may provide "noteworthy" headers
    within the JSON-P encoding.

Usage:

  var req = new PollDance.Request();
  req.on('finished', function(code, result, headers) { ... });
  req.on('error', function(reason) { ... });
  var headers = { ... };
  var body = 'some data';
  req.maxTries = 2; // try twice
  req.start('POST', 'http://example.com/path', headers, body);

Non-JSON Results:

  By default, this library will parse response body data as JSON and return an
  object to the application. Set the rawResponse property to true to disable
  this behavior and have a string returned instead.

Polling and Retries:

  Set the maxTries property to enable multiple request attempts, with
  exponential backoff. Set maxTries to -1 to indicate infinite attempts.
  Transport errors or HTTP responses in the 5xx range will cause a retry to
  occur. Any other error will be returned to the application. Request objects
  may be reused. If reused, a random delay is inserted before starting the
  next request. By default this is a value between 0-1000ms. Set the maxDelay
  property to change the upper bound.

JSON-P Protocol:

  This library supports JSON-P by supplying the following query string
  parameters in the request:

  _callback: the JavaScript function to call in the response script
  _method: the method name (default GET)
  _headers: additional headers encoded as JSON (default none)
  _body: request body (default empty)

  This protocol dictates that the presence of the "callback" parameter
  signifies the request as a JSON-P request. The remaining parameters are
  optional.

  The server is expected to reply with a JSON object with fields:

  code: the HTTP response code
  status: the HTTP response status
  headers: any noteworthy HTTP response headers (default none)
  body: response body

  All fields are required except for "headers". Example response:

  {
    "code": 200,
    "status": "OK",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{ \"foo\": \"bar\" }"
  }