1
// Copyright 2013 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 The API spec for the WebChannel messaging library.
17
 *
18
 * Similar to HTML5 WebSocket and Closure BrowserChannel, WebChannel
19
 * offers an abstraction for point-to-point socket-like communication between
20
 * a browser client and a remote origin.
21
 *
22
 * WebChannels are created via <code>WebChannel</code>. Multiple WebChannels
23
 * may be multiplexed over the same WebChannelTransport, which represents
24
 * the underlying physical connectivity over standard wire protocols
25
 * such as HTTP and SPDY.
26
 *
27
 * A WebChannels in turn represents a logical communication channel between
28
 * the client and server end point. A WebChannel remains open for
29
 * as long as the client or server end-point allows.
30
 *
31
 * Messages may be delivered in-order or out-of-order, reliably or unreliably
32
 * over the same WebChannel. Message delivery guarantees of a WebChannel is
33
 * to be specified by the application code; and the choice of the
34
 * underlying wire protocols is completely transparent to the API users.
35
 *
36
 * Client-to-client messaging via WebRTC based transport may also be support
37
 * via the same WebChannel API in future.
38
 *
39
 * Note that we have no immediate plan to move this API out of labs. While
40
 * the implementation is production ready, the API is subject to change
41
 * (addition only):
42
 * 1. Adopt new Web APIs (mainly whatwg streams) and goog.net.streams.
43
 * 2. New programming models for cloud (on the server-side) may require
44
 *    new APIs to be defined.
45
 * 3. WebRTC DataChannel alignment
46
 *
47
 */
48

49
goog.provide('goog.net.WebChannel');
50

51
goog.require('goog.events');
52
goog.require('goog.events.Event');
53

54

55

56
/**
57
 * A WebChannel represents a logical bi-directional channel over which the
58
 * client communicates with a remote server that holds the other endpoint
59
 * of the channel. A WebChannel is always created in the context of a shared
60
 * {@link WebChannelTransport} instance. It is up to the underlying client-side
61
 * and server-side implementations to decide how or when multiplexing is
62
 * to be enabled.
63
 *
64
 * @interface
65
 * @extends {EventTarget}
66
 */
67
goog.net.WebChannel = function() {};
68

69

70
/**
71
 * Configuration spec for newly created WebChannel instances.
72
 *
73
 * WebChannels are configured in the context of the containing
74
 * {@link WebChannelTransport}. The configuration parameters are specified
75
 * when a new instance of WebChannel is created via {@link WebChannelTransport}.
76
 *
77
 * messageHeaders: custom headers to be added to every message sent to the
78
 * server. This object is mutable, and custom headers may be changed, removed,
79
 * or added during the runtime after a channel has been opened.
80
 *
81
 * initMessageHeaders: similar to messageHeaders, but any custom headers will
82
 * be sent only once when the channel is opened. Typical usage is to send
83
 * an auth header to the server, which only checks the auth header at the time
84
 * when the channel is opened.
85
 *
86
 * messageUrlParams: custom url query parameters to be added to every message
87
 * sent to the server. This object is mutable, and custom parameters may be
88
 * changed, removed or added during the runtime after a channel has been opened.
89
 *
90
 * clientProtocolHeaderRequired: whether a special header should be added to
91
 * each message so that the server can dispatch webchannel messages without
92
 * knowing the URL path prefix. Defaults to false.
93
 *
94
 * concurrentRequestLimit: the maximum number of in-flight HTTP requests allowed
95
 * when SPDY is enabled. Currently we only detect SPDY in Chrome.
96
 * This parameter defaults to 10. When SPDY is not enabled, this parameter
97
 * will have no effect.
98
 *
99
 * supportsCrossDomainXhr: setting this to true to allow the use of sub-domains
100
 * (as configured by the server) to send XHRs with the CORS withCredentials
101
 * bit set to true.
102
 *
103
 * testUrl: the test URL for detecting connectivity during the initial
104
 * handshake. This parameter defaults to "/<channel_url>/test".
105
 *
106
 * sendRawJson: whether to bypass v8 encoding of client-sent messages. Will be
107
 * deprecated after v9 wire protocol is introduced. Only safe to set if the
108
 * server is known to support this feature.
109
 *
110
 * httpSessionIdParam: the URL parameter name that contains the session id (
111
 * for sticky routing of HTTP requests). When this param is specified, a server
112
 * that supports this option will respond with an opaque session id as part of
113
 * the initial handshake (via the X-HTTP-Session-Id header); and all the
114
 * subsequent requests will contain the httpSessionIdParam. This option will
115
 * take precedence over any duplicated parameter specified with
116
 * messageUrlParams, whose value will be ignored.
117
 *
118
 * httpHeadersOverwriteParam: the URL parameter name to allow custom HTTP
119
 * headers to be overwritten as a URL param to bypass CORS preflight.
120
 * goog.net.rpc.HttpCors is used to encode the HTTP headers.
121
 *
122
 * backgroundChannelTest: whether to run the channel test (detecting networking
123
 * conditions) as a background process so the OPEN event will be fired sooner
124
 * to reduce the initial handshake delay. This option defaults to false now.
125
 * Eventually we may turn this flag on by default.
126
 *
127
 * @typedef {{
128
 *   messageHeaders: (!Object<string, string>|undefined),
129
 *   initMessageHeaders: (!Object<string, string>|undefined),
130
 *   messageUrlParams: (!Object<string, string>|undefined),
131
 *   clientProtocolHeaderRequired: (boolean|undefined),
132
 *   concurrentRequestLimit: (number|undefined),
133
 *   supportsCrossDomainXhr: (boolean|undefined),
134
 *   testUrl: (string|undefined),
135
 *   sendRawJson: (boolean|undefined),
136
 *   httpSessionIdParam: (string|undefined),
137
 *   httpHeadersOverwriteParam: (string|undefined),
138
 *   backgroundChannelTest: (boolean|undefined)
139
 * }}
140
 */
141
goog.net.WebChannel.Options;
142

143

144
/**
145
 * Types that are allowed as message data.
146
 *
147
 * Note that JS objects (sent by the client) can only have string encoded
148
 * values due to the limitation of the current wire protocol.
149
 *
150
 * Unicode strings (sent by the server) may or may not need be escaped, as
151
 * decided by the server.
152
 *
153
 * @typedef {(ArrayBuffer|Blob|Object<string, string>|Array)}
154
 */
155
goog.net.WebChannel.MessageData;
156

157

158
/**
159
 * Open the WebChannel against the URI specified in the constructor.
160
 */
161
goog.net.WebChannel.prototype.open = goog.abstractMethod;
162

163

164
/**
165
 * Close the WebChannel.
166
 */
167
goog.net.WebChannel.prototype.close = goog.abstractMethod;
168

169

170
/**
171
 * Sends a message to the server that maintains the other end point of
172
 * the WebChannel.
173
 *
174
 * @param {!goog.net.WebChannel.MessageData} message The message to send.
175
 */
176
goog.net.WebChannel.prototype.send = goog.abstractMethod;
177

178

179
/**
180
 * Common events fired by WebChannels.
181
 * @enum {string}
182
 */
183
goog.net.WebChannel.EventType = {
184
  /** Dispatched when the channel is opened. */
185
  OPEN: goog.events.getUniqueId('open'),
186

187
  /** Dispatched when the channel is closed. */
188
  CLOSE: goog.events.getUniqueId('close'),
189

190
  /** Dispatched when the channel is aborted due to errors. */
191
  ERROR: goog.events.getUniqueId('error'),
192

193
  /** Dispatched when the channel has received a new message. */
194
  MESSAGE: goog.events.getUniqueId('message')
195
};
196

197

198

199
/**
200
 * The event interface for the MESSAGE event.
201
 *
202
 * @constructor
203
 * @extends {goog.events.Event}
204
 */
205
goog.net.WebChannel.MessageEvent = function() {
206
  goog.net.WebChannel.MessageEvent.base(
207
      this, 'constructor', goog.net.WebChannel.EventType.MESSAGE);
208
};
209
goog.inherits(goog.net.WebChannel.MessageEvent, goog.events.Event);
210

211

212
/**
213
 * The content of the message received from the server.
214
 *
215
 * @type {!goog.net.WebChannel.MessageData}
216
 */
217
goog.net.WebChannel.MessageEvent.prototype.data;
218

219

220
/**
221
 * WebChannel level error conditions.
222
 *
223
 * Summary of error debugging and reporting in WebChannel:
224
 *
225
 * Network Error
226
 * 1. By default the webchannel library will set the error status to
227
 *    NETWORK_ERROR when a channel has to be aborted or closed. NETWORK_ERROR
228
 *    may be recovered by the application by retrying and opening a new channel.
229
 * 2. There may be lost messages (not acked by the server) when a channel is
230
 *    aborted. Currently we don't have a public API to retrieve messages that
231
 *    are waiting to be acked on the client side. File a bug if you think it
232
 *    is useful to expose such an API.
233
 * 3. Details of why a channel fails are available via closure debug logs,
234
 *    and stats events (see webchannel/requeststats.js). Those are internal
235
 *    stats and are subject to change. File a bug if you think it's useful to
236
 *    version and expose such stats as part of the WebChannel API.
237
 *
238
 * Server Error
239
 * 1. SERVER_ERROR is intended to indicate a non-recoverable condition, e.g.
240
 *    when auth fails.
241
 * 2. We don't currently generate any such errors, because most of the time
242
 *    it's the responsibility of upper-layer frameworks or the application
243
 *    itself to indicate to the client why a webchannel has been failed
244
 *    by the server.
245
 * 3. When a channel is failed by the server explicitly, we still signal
246
 *    NETWORK_ERROR to the client. Explicit server failure may happen when the
247
 *    server does a fail-over, or becomes overloaded, or conducts a forced
248
 *    shutdown etc.
249
 * 4. We use some heuristic to decide if the network (aka cloud) is down
250
 *    v.s. the actual server is down.
251
 *
252
 *  RuntimeProperties.getLastStatusCode is a useful state that we expose to
253
 *  the client to indicate the HTTP response status code of the last HTTP
254
 *  request initiated by the WebChannel client library, for debugging
255
 *  purposes only.
256
 *
257
 * @enum {number}
258
 */
259
goog.net.WebChannel.ErrorStatus = {
260
  /** No error has occurred. */
261
  OK: 0,
262

263
  /** Communication to the server has failed. */
264
  NETWORK_ERROR: 1,
265

266
  /** The server fails to accept or process the WebChannel. */
267
  SERVER_ERROR: 2
268
};
269

270

271

272
/**
273
 * The event interface for the ERROR event.
274
 *
275
 * @constructor
276
 * @extends {goog.events.Event}
277
 */
278
goog.net.WebChannel.ErrorEvent = function() {
279
  goog.net.WebChannel.ErrorEvent.base(
280
      this, 'constructor', goog.net.WebChannel.EventType.ERROR);
281
};
282
goog.inherits(goog.net.WebChannel.ErrorEvent, goog.events.Event);
283

284

285
/**
286
 * The error status.
287
 *
288
 * @type {!goog.net.WebChannel.ErrorStatus}
289
 */
290
goog.net.WebChannel.ErrorEvent.prototype.status;
291

292

293
/**
294
 * @return {!goog.net.WebChannel.RuntimeProperties} The runtime properties
295
 * of the WebChannel instance.
296
 */
297
goog.net.WebChannel.prototype.getRuntimeProperties = goog.abstractMethod;
298

299

300

301
/**
302
 * The runtime properties of the WebChannel instance.
303
 *
304
 * This class is defined for debugging and monitoring purposes, as well as for
305
 * runtime functions that the application may choose to manage by itself.
306
 *
307
 * @interface
308
 */
309
goog.net.WebChannel.RuntimeProperties = function() {};
310

311

312
/**
313
 * @return {number} The effective limit for the number of concurrent HTTP
314
 * requests that are allowed to be made for sending messages from the client
315
 * to the server. When SPDY is not enabled, this limit will be one.
316
 */
317
goog.net.WebChannel.RuntimeProperties.prototype.getConcurrentRequestLimit =
318
    goog.abstractMethod;
319

320

321
/**
322
 * For applications that need support multiple channels (e.g. from
323
 * different tabs) to the same origin, use this method to decide if SPDY is
324
 * enabled and therefore it is safe to open multiple channels.
325
 *
326
 * If SPDY is disabled, the application may choose to limit the number of active
327
 * channels to one or use other means such as sub-domains to work around
328
 * the browser connection limit.
329
 *
330
 * @return {boolean} Whether SPDY is enabled for the origin against which
331
 * the channel is created.
332
 */
333
goog.net.WebChannel.RuntimeProperties.prototype.isSpdyEnabled =
334
    goog.abstractMethod;
335

336

337
/**
338
 * For applications to query the current HTTP session id, sent by the server
339
 * during the initial handshake.
340
 *
341
 * @return {?string} the HTTP session id or null if no HTTP session is in use.
342
 */
343
goog.net.WebChannel.RuntimeProperties.prototype.getHttpSessionId =
344
    goog.abstractMethod;
345

346

347
/**
348
 * This method generates an in-band commit request to the server, which will
349
 * ack the commit request as soon as all messages sent prior to this commit
350
 * request have been committed by the application.
351
 *
352
 * Committing a message has a stronger semantics than delivering a message
353
 * to the application. Detail spec:
354
 * https://github.com/bidiweb/webchannel/blob/master/commit.md
355
 *
356
 * Timeout or cancellation is not supported and the application may have to
357
 * abort the channel if the commit-ack fails to arrive in time.
358
 *
359
 * @param {function()} callback The callback will be invoked once an
360
 * ack has been received for the current commit or any newly issued commit.
361
 */
362
goog.net.WebChannel.RuntimeProperties.prototype.commit = goog.abstractMethod;
363

364

365
/**
366
 * This method may be used by the application to recover from a peer failure
367
 * or to enable sender-initiated flow-control.
368
 *
369
 * Detail spec: https://github.com/bidiweb/webchannel/blob/master/commit.md
370
 *
371
 * @return {number} The total number of messages that have not received
372
 * commit-ack from the server; or if no commit has been issued, the number
373
 * of messages that have not been delivered to the server application.
374
 */
375
goog.net.WebChannel.RuntimeProperties.prototype.getNonAckedMessageCount =
376
    goog.abstractMethod;
377

378

379
/**
380
 * A low water-mark message count to notify the application when the
381
 * flow-control condition is cleared, that is, when the application is
382
 * able to send more messages.
383
 *
384
 * We expect the application to configure a high water-mark message count,
385
 * which is checked via getNonAckedMessageCount(). When the high water-mark
386
 * is exceeded, the application should install a callback via this method
387
 * to be notified when to start to send new messages.
388
 *
389
 * @param {number} count The low water-mark count. It is an error to pass
390
 * a non-positive value.
391
 * @param {!function()} callback The call back to notify the application
392
 * when NonAckedMessageCount is below the specified low water-mark count.
393
 * Any previously registered callback is cleared. This new callback will
394
 * be cleared once it has been fired, or when the channel is closed or aborted.
395
 */
396
goog.net.WebChannel.RuntimeProperties.prototype.notifyNonAckedMessageCount =
397
    goog.abstractMethod;
398

399

400
/**
401
 * This method registers a callback to handle the commit request sent
402
 * by the server. Commit protocol spec:
403
 * https://github.com/bidiweb/webchannel/blob/master/commit.md
404
 *
405
 * @param {function(!Object)} callback The callback will take an opaque
406
 * commitId which needs be passed back to the server when an ack-commit
407
 * response is generated by the client application, via ackCommit().
408
 */
409
goog.net.WebChannel.RuntimeProperties.prototype.onCommit = goog.abstractMethod;
410

411

412
/**
413
 * This method is used by the application to generate an ack-commit response
414
 * for the given commitId. Commit protocol spec:
415
 * https://github.com/bidiweb/webchannel/blob/master/commit.md
416
 *
417
 * @param {!Object} commitId The commitId which denotes the commit request
418
 * from the server that needs be ack'ed.
419
 */
420
goog.net.WebChannel.RuntimeProperties.prototype.ackCommit = goog.abstractMethod;
421

422

423
/**
424
 * @return {number} The last HTTP status code received by the channel.
425
 */
426
goog.net.WebChannel.RuntimeProperties.prototype.getLastStatusCode =
427
    goog.abstractMethod;
428

429

430
/**
431
 * A request header to indicate to the server the messaging protocol
432
 * each HTTP message is speaking.
433
 *
434
 * @type {string}
435
 */
436
goog.net.WebChannel.X_CLIENT_PROTOCOL = 'X-Client-Protocol';
437

438

439
/**
440
 * The value for x-client-protocol when the messaging protocol is WebChannel.
441
 *
442
 * @type {string}
443
 */
444
goog.net.WebChannel.X_CLIENT_PROTOCOL_WEB_CHANNEL = 'webchannel';
445

446

447
/**
448
 * A response header for the server to signal the wire-protocol that
449
 * the browser establishes with the server (or proxy), e.g. "spdy" (aka http/2)
450
 * "quic". This information avoids the need to use private APIs to decide if
451
 * HTTP requests are multiplexed etc.
452
 *
453
 * @type {string}
454
 */
455
goog.net.WebChannel.X_CLIENT_WIRE_PROTOCOL = 'X-Client-Wire-Protocol';
456

457

458
/**
459
 * A response header for the server to send back the HTTP session id as part of
460
 * the initial handshake. The value of the HTTP session id is opaque to the
461
 * WebChannel protocol.
462
 *
463
 * @type {string}
464
 */
465
goog.net.WebChannel.X_HTTP_SESSION_ID = 'X-HTTP-Session-Id';
466

467