Debian Codegraph @

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

raw
1 // Copyright 2007 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 /**
16 * @fileoverview Provides the namesspace for client-side communication
17 * between pages originating from different domains (it works also
18 * with pages from the same domain, but doing that is kinda
19 * pointless).
20 *
21 * The only publicly visible class is goog.net.xpc.CrossPageChannel.
22 *
23 * Note: The preferred name for the main class would have been
24 * CrossDomainChannel. But as there already is a class named like
25 * that (which serves a different purpose) in the maps codebase,
26 * CrossPageChannel was chosen to avoid confusion.
27 *
28 * CrossPageChannel abstracts the underlying transport mechanism to
29 * provide a common interface in all browsers.
30 *
31 *
32 * @suppress {underscore}
33 */
34
35 /*
36 TODO(user)
37 - resolve fastback issues in Safari (IframeRelayTransport)
38 */
39
40
41 /**
42 * Namespace for CrossPageChannel
43 */
44 goog.provide('goog.net.xpc');
45 goog.provide('goog.net.xpc.CfgFields');
46 goog.provide('goog.net.xpc.ChannelStates');
47 goog.provide('goog.net.xpc.TransportNames');
48 goog.provide('goog.net.xpc.TransportTypes');
49 goog.provide('goog.net.xpc.UriCfgFields');
50 goog.require('goog.log');
51
52 goog.forwardDeclare('goog.net.xpc.CrossPageChannel'); // circular
53
54
55 /**
56 * Enum used to identify transport types.
57 * @enum {number}
58 */
59 goog.net.xpc.TransportTypes = {
60 NATIVE_MESSAGING: 1,
61 FRAME_ELEMENT_METHOD: 2,
62 IFRAME_RELAY: 3,
63 IFRAME_POLLING: 4,
64 FLASH: 5,
65 NIX: 6,
66 DIRECT: 7
67 };
68
69
70 /**
71 * Enum containing transport names. These need to correspond to the
72 * transport class names for createTransport_() to work.
73 * @const {!Object<string,string>}
74 */
75 goog.net.xpc.TransportNames = {
76 '1': 'NativeMessagingTransport',
77 '2': 'FrameElementMethodTransport',
78 '3': 'IframeRelayTransport',
79 '4': 'IframePollingTransport',
80 '5': 'FlashTransport',
81 '6': 'NixTransport',
82 '7': 'DirectTransport'
83 };
84
85
86 // TODO(user): Add auth token support to other methods.
87
88
89 /**
90 * Field names used on configuration object.
91 * @const
92 */
93 goog.net.xpc.CfgFields = {
94 /**
95 * Channel name identifier.
96 * Both peers have to be initialized with
97 * the same channel name. If not present, a channel name is
98 * generated (which then has to transferred to the peer somehow).
99 */
100 CHANNEL_NAME: 'cn',
101 /**
102 * Authorization token. If set, NIX will use this authorization token
103 * to validate the setup.
104 */
105 AUTH_TOKEN: 'at',
106 /**
107 * Remote party's authorization token. If set, NIX will validate this
108 * authorization token against that sent by the other party.
109 */
110 REMOTE_AUTH_TOKEN: 'rat',
111 /**
112 * The URI of the peer page.
113 */
114 PEER_URI: 'pu',
115 /**
116 * Ifame-ID identifier.
117 * The id of the iframe element the peer-document lives in.
118 */
119 IFRAME_ID: 'ifrid',
120 /**
121 * Transport type identifier.
122 * The transport type to use. Possible values are entries from
123 * goog.net.xpc.TransportTypes. If not present, the transport is
124 * determined automatically based on the useragent's capabilities.
125 */
126 TRANSPORT: 'tp',
127 /**
128 * Local relay URI identifier (IframeRelayTransport-specific).
129 * The URI (can't contain a fragment identifier) used by the peer to
130 * relay data through.
131 */
132 LOCAL_RELAY_URI: 'lru',
133 /**
134 * Peer relay URI identifier (IframeRelayTransport-specific).
135 * The URI (can't contain a fragment identifier) used to relay data
136 * to the peer.
137 */
138 PEER_RELAY_URI: 'pru',
139 /**
140 * Local poll URI identifier (IframePollingTransport-specific).
141 * The URI (can't contain a fragment identifier)which is polled
142 * to receive data from the peer.
143 */
144 LOCAL_POLL_URI: 'lpu',
145 /**
146 * Local poll URI identifier (IframePollingTransport-specific).
147 * The URI (can't contain a fragment identifier) used to send data
148 * to the peer.
149 */
150 PEER_POLL_URI: 'ppu',
151 /**
152 * The hostname of the peer window, including protocol, domain, and port
153 * (if specified). Used for security sensitive applications that make
154 * use of NativeMessagingTransport (i.e. most applications).
155 */
156 PEER_HOSTNAME: 'ph',
157 /**
158 * Usually both frames using a connection initially send a SETUP message to
159 * each other, and each responds with a SETUP_ACK. A frame marks itself
160 * connected when it receives that SETUP_ACK. If this parameter is true
161 * however, the channel it is passed to will not send a SETUP, but rather will
162 * wait for one from its peer and mark itself connected when that arrives.
163 * Peer iframes created using such a channel will send SETUP however, and will
164 * wait for SETUP_ACK before marking themselves connected. The goal is to
165 * cope with a situation where the availability of the URL for the peer frame
166 * cannot be relied on, eg when the application is offline. Without this
167 * setting, the primary frame will attempt to send its SETUP message every
168 * 100ms, forever. This floods the javascript console with uncatchable
169 * security warnings, and fruitlessly burns CPU. There is one scenario this
170 * mode will not support, and that is reconnection by the outer frame, ie the
171 * creation of a new channel object to connect to a peer iframe which was
172 * already communicating with a previous channel object of the same name. If
173 * that behavior is needed, this mode should not be used. Reconnection by
174 * inner frames is supported in this mode however.
175 */
176 ONE_SIDED_HANDSHAKE: 'osh',
177 /**
178 * The frame role (inner or outer). Used to explicitly indicate the role for
179 * each peer whenever the role cannot be reliably determined (e.g. the two
180 * peer windows are not parent/child frames). If unspecified, the role will
181 * be dynamically determined, assuming a parent/child frame setup.
182 */
183 ROLE: 'role',
184 /**
185 * Which version of the native transport startup protocol should be used, the
186 * default being '2'. Version 1 had various timing vulnerabilities, which
187 * had to be compensated for by introducing delays, and is deprecated. V1
188 * and V2 are broadly compatible, although the more robust timing and lack
189 * of delays is not gained unless both sides are using V2. The only
190 * unsupported case of cross-protocol interoperation is where a connection
191 * starts out with V2 at both ends, and one of the ends reconnects as a V1.
192 * All other initial startup and reconnection scenarios are supported.
193 */
194 NATIVE_TRANSPORT_PROTOCOL_VERSION: 'nativeProtocolVersion',
195 /**
196 * Whether the direct transport runs in synchronous mode. The default is to
197 * emulate the other transports and run asyncronously but there are some
198 * circumstances where syncronous calls are required. If this property is
199 * set to true, the transport will send the messages synchronously.
200 */
201 DIRECT_TRANSPORT_SYNC_MODE: 'directSyncMode'
202 };
203
204
205 /**
206 * Config properties that need to be URL sanitized.
207 * @type {Array<string>}
208 */
209 goog.net.xpc.UriCfgFields = [
210 goog.net.xpc.CfgFields.PEER_URI, goog.net.xpc.CfgFields.LOCAL_RELAY_URI,
211 goog.net.xpc.CfgFields.PEER_RELAY_URI, goog.net.xpc.CfgFields.LOCAL_POLL_URI,
212 goog.net.xpc.CfgFields.PEER_POLL_URI
213 ];
214
215
216 /**
217 * @enum {number}
218 */
219 goog.net.xpc.ChannelStates = {
220 NOT_CONNECTED: 1,
221 CONNECTED: 2,
222 CLOSED: 3
223 };
224
225
226 /**
227 * The name of the transport service (used for internal signalling).
228 * @type {string}
229 * @suppress {underscore|visibility}
230 */
231 goog.net.xpc.TRANSPORT_SERVICE_ = 'tp';
232
233
234 /**
235 * Transport signaling message: setup.
236 * @type {string}
237 */
238 goog.net.xpc.SETUP = 'SETUP';
239
240
241 /**
242 * Transport signaling message: setup for native transport protocol v2.
243 * @type {string}
244 */
245 goog.net.xpc.SETUP_NTPV2 = 'SETUP_NTPV2';
246
247
248 /**
249 * Transport signaling message: setup acknowledgement.
250 * @type {string}
251 * @suppress {underscore|visibility}
252 */
253 goog.net.xpc.SETUP_ACK_ = 'SETUP_ACK';
254
255
256 /**
257 * Transport signaling message: setup acknowledgement.
258 * @type {string}
259 */
260 goog.net.xpc.SETUP_ACK_NTPV2 = 'SETUP_ACK_NTPV2';
261
262
263 /**
264 * Object holding active channels.
265 *
266 * @package {Object<string, goog.net.xpc.CrossPageChannel>}
267 */
268 goog.net.xpc.channels = {};
269
270
271 /**
272 * Returns a random string.
273 * @param {number} length How many characters the string shall contain.
274 * @param {string=} opt_characters The characters used.
275 * @return {string} The random string.
276 */
277 goog.net.xpc.getRandomString = function(length, opt_characters) {
278 var chars = opt_characters || goog.net.xpc.randomStringCharacters_;
279 var charsLength = chars.length;
280 var s = '';
281 while (length-- > 0) {
282 s += chars.charAt(Math.floor(Math.random() * charsLength));
283 }
284 return s;
285 };
286
287
288 /**
289 * The default characters used for random string generation.
290 * @type {string}
291 * @private
292 */
293 goog.net.xpc.randomStringCharacters_ =
294 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
295
296
297 /**
298 * The logger.
299 * @type {goog.log.Logger}
300 */
301 goog.net.xpc.logger = goog.log.getLogger('goog.net.xpc');