Debian Codegraph @

closure-library/closure/goog/net/jsonp.js

raw
1 // Copyright 2006 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 // The original file lives here: http://go/cross_domain_channel.js
16
17 /**
18 * @fileoverview Implements a cross-domain communication channel. A
19 * typical web page is prevented by browser security from sending
20 * request, such as a XMLHttpRequest, to other servers than the ones
21 * from which it came. The Jsonp class provides a workaround by
22 * using dynamically generated script tags. Typical usage:.
23 *
24 * var trustedUri = goog.html.TrustedResourceUrl.fromConstant(
25 * goog.string.Const.from('https://example.com/servlet'));
26 * var jsonp = new goog.net.Jsonp(trustedUri);
27 * var payload = {'foo': 1, 'bar': true};
28 * jsonp.send(payload, function(reply) { alert(reply) });
29 *
30 * This script works in all browsers that are currently supported by
31 * the Google Maps API, which is IE 6.0+, Firefox 0.8+, Safari 1.2.4+,
32 * Netscape 7.1+, Mozilla 1.4+, Opera 8.02+.
33 *
34 */
35
36 goog.provide('goog.net.Jsonp');
37
38 goog.require('goog.html.TrustedResourceUrl');
39 goog.require('goog.net.jsloader');
40 goog.require('goog.object');
41
42 // WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
43 //
44 // This class allows us (Google) to send data from non-Google and thus
45 // UNTRUSTED pages to our servers. Under NO CIRCUMSTANCES return
46 // anything sensitive, such as session or cookie specific data. Return
47 // only data that you want parties external to Google to have. Also
48 // NEVER use this method to send data from web pages to untrusted
49 // servers, or redirects to unknown servers (www.google.com/cache,
50 // /q=xx&btnl, /url, www.googlepages.com, etc.)
51 //
52 // WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
53
54
55
56 /**
57 * Creates a new cross domain channel that sends data to the specified
58 * host URL. By default, if no reply arrives within 5s, the channel
59 * assumes the call failed to complete successfully.
60 *
61 * @param {!goog.html.TrustedResourceUrl} uri The Uri of the server side code
62 * that receives data posted through this channel (e.g.,
63 * "http://maps.google.com/maps/geo").
64 *
65 * @param {string=} opt_callbackParamName The parameter name that is used to
66 * specify the callback. Defaults to "callback".
67 *
68 * @constructor
69 * @final
70 */
71 goog.net.Jsonp = function(uri, opt_callbackParamName) {
72 /**
73 * The uri_ object will be used to encode the payload that is sent to the
74 * server.
75 * @type {!goog.html.TrustedResourceUrl}
76 * @private
77 */
78 this.uri_ = uri;
79
80 /**
81 * This is the callback parameter name that is added to the uri.
82 * @type {string}
83 * @private
84 */
85 this.callbackParamName_ =
86 opt_callbackParamName ? opt_callbackParamName : 'callback';
87
88 /**
89 * The length of time, in milliseconds, this channel is prepared
90 * to wait for for a request to complete. The default value is 5 seconds.
91 * @type {number}
92 * @private
93 */
94 this.timeout_ = 5000;
95
96 /**
97 * The nonce to use in the dynamically generated script tags. This is used for
98 * allowing the script callbacks to execute when the page has an enforced
99 * Content Security Policy.
100 * @type {string}
101 * @private
102 */
103 this.nonce_ = '';
104 };
105
106
107 /**
108 * The prefix for the callback name which will be stored on goog.global.
109 */
110 goog.net.Jsonp.CALLBACKS = '_callbacks_';
111
112
113 /**
114 * Used to generate unique callback IDs. The counter must be global because
115 * all channels share a common callback object.
116 * @private
117 */
118 goog.net.Jsonp.scriptCounter_ = 0;
119
120
121 /**
122 * Static private method which returns the global unique callback id.
123 *
124 * @param {string} id The id of the script node.
125 * @return {string} A global unique id used to store callback on goog.global
126 * object.
127 * @private
128 */
129 goog.net.Jsonp.getCallbackId_ = function(id) {
130 return goog.net.Jsonp.CALLBACKS + '__' + id;
131 };
132
133
134 /**
135 * Sets the length of time, in milliseconds, this channel is prepared
136 * to wait for for a request to complete. If the call is not competed
137 * within the set time span, it is assumed to have failed. To wait
138 * indefinitely for a request to complete set the timout to a negative
139 * number.
140 *
141 * @param {number} timeout The length of time before calls are
142 * interrupted.
143 */
144 goog.net.Jsonp.prototype.setRequestTimeout = function(timeout) {
145 this.timeout_ = timeout;
146 };
147
148
149 /**
150 * Returns the current timeout value, in milliseconds.
151 *
152 * @return {number} The timeout value.
153 */
154 goog.net.Jsonp.prototype.getRequestTimeout = function() {
155 return this.timeout_;
156 };
157
158
159 /**
160 * Sets the nonce value for CSP. This nonce value will be added to any created
161 * script elements and must match the nonce provided in the
162 * Content-Security-Policy header sent by the server for the callback to pass
163 * CSP enforcement.
164 *
165 * @param {string} nonce The CSP nonce value.
166 */
167 goog.net.Jsonp.prototype.setNonce = function(nonce) {
168 this.nonce_ = nonce;
169 };
170
171
172 /**
173 * Sends the given payload to the URL specified at the construction
174 * time. The reply is delivered to the given replyCallback. If the
175 * errorCallback is specified and the reply does not arrive within the
176 * timeout period set on this channel, the errorCallback is invoked
177 * with the original payload.
178 *
179 * If no reply callback is specified, then the response is expected to
180 * consist of calls to globally registered functions. No &callback=
181 * URL parameter will be sent in the request, and the script element
182 * will be cleaned up after the timeout.
183 *
184 * @param {Object=} opt_payload Name-value pairs. If given, these will be
185 * added as parameters to the supplied URI as GET parameters to the
186 * given server URI.
187 *
188 * @param {Function=} opt_replyCallback A function expecting one
189 * argument, called when the reply arrives, with the response data.
190 *
191 * @param {Function=} opt_errorCallback A function expecting one
192 * argument, called on timeout, with the payload (if given), otherwise
193 * null.
194 *
195 * @param {string=} opt_callbackParamValue Value to be used as the
196 * parameter value for the callback parameter (callbackParamName).
197 * To be used when the value needs to be fixed by the client for a
198 * particular request, to make use of the cached responses for the request.
199 * NOTE: If multiple requests are made with the same
200 * opt_callbackParamValue, only the last call will work whenever the
201 * response comes back.
202 *
203 * @return {!Object} A request descriptor that may be used to cancel this
204 * transmission, or null, if the message may not be cancelled.
205 */
206 goog.net.Jsonp.prototype.send = function(
207 opt_payload, opt_replyCallback, opt_errorCallback, opt_callbackParamValue) {
208
209 var payload = opt_payload ? goog.object.clone(opt_payload) : {};
210
211 var id = opt_callbackParamValue ||
212 '_' + (goog.net.Jsonp.scriptCounter_++).toString(36) +
213 goog.now().toString(36);
214 var callbackId = goog.net.Jsonp.getCallbackId_(id);
215
216 if (opt_replyCallback) {
217 var reply = goog.net.Jsonp.newReplyHandler_(id, opt_replyCallback);
218 // Register the callback on goog.global to make it discoverable
219 // by jsonp response.
220 goog.global[callbackId] = reply;
221 payload[this.callbackParamName_] = callbackId;
222 }
223
224 var options = {timeout: this.timeout_, cleanupWhenDone: true};
225 if (this.nonce_) {
226 options.attributes = {'nonce': this.nonce_};
227 }
228
229 var uri = this.uri_.cloneWithParams(payload);
230
231 var deferred = goog.net.jsloader.safeLoad(uri, options);
232 var error = goog.net.Jsonp.newErrorHandler_(id, payload, opt_errorCallback);
233 deferred.addErrback(error);
234
235 return {id_: id, deferred_: deferred};
236 };
237
238
239 /**
240 * Cancels a given request. The request must be exactly the object returned by
241 * the send method.
242 *
243 * @param {Object} request The request object returned by the send method.
244 */
245 goog.net.Jsonp.prototype.cancel = function(request) {
246 if (request) {
247 if (request.deferred_) {
248 request.deferred_.cancel();
249 }
250 if (request.id_) {
251 goog.net.Jsonp.cleanup_(request.id_, false);
252 }
253 }
254 };
255
256
257 /**
258 * Creates a timeout callback that calls the given timeoutCallback with the
259 * original payload.
260 *
261 * @param {string} id The id of the script node.
262 * @param {Object} payload The payload that was sent to the server.
263 * @param {Function=} opt_errorCallback The function called on timeout.
264 * @return {!Function} A zero argument function that handles callback duties.
265 * @private
266 */
267 goog.net.Jsonp.newErrorHandler_ = function(id, payload, opt_errorCallback) {
268 /**
269 * When we call across domains with a request, this function is the
270 * timeout handler. Once it's done executing the user-specified
271 * error-handler, it removes the script node and original function.
272 */
273 return function() {
274 goog.net.Jsonp.cleanup_(id, false);
275 if (opt_errorCallback) {
276 opt_errorCallback(payload);
277 }
278 };
279 };
280
281
282 /**
283 * Creates a reply callback that calls the given replyCallback with data
284 * returned by the server.
285 *
286 * @param {string} id The id of the script node.
287 * @param {Function} replyCallback The function called on reply.
288 * @return {!Function} A reply callback function.
289 * @private
290 */
291 goog.net.Jsonp.newReplyHandler_ = function(id, replyCallback) {
292 /**
293 * This function is the handler for the all-is-well response. It
294 * clears the error timeout handler, calls the user's handler, then
295 * removes the script node and itself.
296 *
297 * @param {...Object} var_args The response data sent from the server.
298 */
299 var handler = function(var_args) {
300 goog.net.Jsonp.cleanup_(id, true);
301 replyCallback.apply(undefined, arguments);
302 };
303 return handler;
304 };
305
306
307 /**
308 * Removes the reply handler registered on goog.global object.
309 *
310 * @param {string} id The id of the script node to be removed.
311 * @param {boolean} deleteReplyHandler If true, delete the reply handler
312 * instead of setting it to nullFunction (if we know the callback could
313 * never be called again).
314 * @private
315 */
316 goog.net.Jsonp.cleanup_ = function(id, deleteReplyHandler) {
317 var callbackId = goog.net.Jsonp.getCallbackId_(id);
318 if (goog.global[callbackId]) {
319 if (deleteReplyHandler) {
320 try {
321 delete goog.global[callbackId];
322 } catch (e) {
323 // NOTE: Workaround to delete property on 'window' in IE <= 8, see:
324 // http://stackoverflow.com/questions/1073414/deleting-a-window-property-in-ie
325 goog.global[callbackId] = undefined;
326 }
327 } else {
328 // Removing the script tag doesn't necessarily prevent the script
329 // from firing, so we make the callback a noop.
330 goog.global[callbackId] = goog.nullFunction;
331 }
332 }
333 };
334
335
336 // WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
337 //
338 // This class allows us (Google) to send data from non-Google and thus
339 // UNTRUSTED pages to our servers. Under NO CIRCUMSTANCES return
340 // anything sensitive, such as session or cookie specific data. Return
341 // only data that you want parties external to Google to have. Also
342 // NEVER use this method to send data from web pages to untrusted
343 // servers, or redirects to unknown servers (www.google.com/cache,
344 // /q=xx&btnl, /url, www.googlepages.com, etc.)
345 //
346 // WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING