aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 340037fd5e62c404b893902722db043a1fbd1034 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
Pollymer
--------
Date: April 28th, 2014
Authors: Justin Karneges <justin@fanout.io>
         Katsuyuki Ohmuro <harmony7@pex2.jp>
Mailing List: http://lists.fanout.io/listinfo.cgi/fanout-users-fanout.io

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

Dependencies:

  json2.js

Available Transports:

  XmlHttpRequest - for same-origin requests on all browsers, and cross-origin
    requests on modern CORS browsers
  JSON-P - for cross-origin requests on older non-CORS browsers such as IE7,
    IE8, IE9, and Opera < 12.00

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 Pollymer.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);

Methods of Request Object:

  on(event_name, callback) - Add callback for event:
    event_name: name of event
    callback:   method to call when event occurs

    available events:
      'finished': function(code, result, headers)
        code:    HTTP status code
        result:  JSON object or string
        headers: hash of key/value strings
      'error': function(reason)
        reason: Pollymer.errorType

  off(event_name) - Remove callback for event

  start(method, url, headers, body) - start request
    method:  name of method (e.g. 'GET')
    url:     string url, or function that returns a string url if called
    headers: hash of key/value strings (optional)
    body:    string body data (optional)

    Sometime after the request has been started, a finished or error event
    will be raised and the object will return to inactive state (unless the
    recurring flag is set, see below).

    The start method may be called again once the request has completed
    (unless the recurring flag is set, see below). If called again on the same
    object, a short random delay will be added before performing the request.

  retry() - Attempt the exact same request again. Normally, Pollymer will
    automatically retry a request that it considers to be a failure, but this
    method may be used if the application needs to retry the request for any
    another reason. Retries have an exponentially increasing delay between
    them. Do not use retry() if the previous request attempt was considered to
    be successful, as it will add penalizing delays that you probably don't
    want in that case.

  abort() - Stop any current request and return the object to inactive state.

Properties of Request Object:

  Properties are simple members of the object. They can be set directly:
    req.rawResponse = true;
  or passed in a hash during construction:
    var req = new Pollymer.Request({rawResponse: true});

  rawResponse: boolean
    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.

  maxTries: int
    The number of tries a request should be attempted with temporary failure
    before raising an error event. Set to -1 to indicate infinite attempts.
    Default is 1.

  maxDelay: int
    The maximum amount of random milliseconds to delay between requests.
    Default 1000.

  recurring: boolean
    If set to true, then after a request finishes with a code between 200 and
    299, and the finished event has been raised, the same request will be
    started again. This allows Pollymer to automatically poll a resource
    endlessly. Pass a function as the url argument in order to be able to
    change the url between polls.

  transport: Pollymer.transportType
    Explicitly set the transport to use. Default is transportType.Auto, which
    automatically chooses the best transport when the request is started.

  withCredentials: boolean
    If set to true, and the request will be a cross-origin request performed
    over an XmlHttpRequest transport using CORS, then the withCredentials flag
    will be set on the XmlHttpRequest object to be used.  Use this flag if the
    CORS request needs to have HTTP Cookies and/or HTTP Authentication
    information sent along with it.

  timeout: integer
    Request wait timeout in milliseconds.
    Default 60000.

  errorCodes: string
    The error codes and/or ranges that should cause automatic retrying. For
    example, to have all error codes in the 500-599 range cause an automatic
    retry except for code 501, you could set errorCodes to '500,502-599'.
    Default is '500-599'.

Retries:

  When a request fails at the transport level, or the request succeeds with an
  error code between 500 and 599, and maxTries has not been reached, then
  Pollymer will retry the request silently, with an exponentially increasing
  delay between attempts. In any other case, the request will succeed and
  the finished event will be raised. If the application determines that the
  response indicates a temporary error and should be retried with the same
  backoff delay that Pollymer normally uses, the retry() method may be used.

Request Reuse:

  If start() is called on an object that has completed a request and is now
  inactive, then a random delay will be added before performing the next
  request. This is ideal behavior when repeatedly polling a resource, so do
  try to reuse the request object rather than throwing it away and creating a
  new one every time. When the recurring flag is used, the effect is the same
  as if you had called start() again yourself after a request finished.

  Be sure to recognize the difference between a retry and a reuse of the
  object. A retry implies that the previous request attempt was a failure,
  whereas reusing the object means the previous request attempt was
  successful. This distinction is important because it changes the way the
  delaying works.

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 status code
  reason: the HTTP response reason phrase
  headers: any noteworthy HTTP response headers (default none)
  body: response body

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

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