include/websock.js

   1 /*
   2  * Websock: high-performance binary WebSockets
   3  * Copyright (C) 2012 Joel Martin
   4  * Licensed under LGPL-3 (see LICENSE.txt)
   5  *
   6  * Websock is similar to the standard WebSocket object but Websock
   7  * enables communication with raw TCP sockets (i.e. the binary stream)
   8  * via websockify. This is accomplished by base64 encoding the data
   9  * stream between Websock and websockify.
  10  *
  11  * Websock has built-in receive queue buffering; the message event
  12  * does not contain actual data but is simply a notification that
  13  * there is new data available. Several rQ* methods are available to
  14  * read binary data off of the receive queue.
  15  */
  16
  17 /*jslint browser: true, bitwise: false, plusplus: false */
  18 /*global Util, Base64 */
  19
  20
  21 // Load Flash WebSocket emulator if needed
  22
  23 // To force WebSocket emulator even when native WebSocket available
  24 //window.WEB_SOCKET_FORCE_FLASH = true;
  25 // To enable WebSocket emulator debug:
  26 //window.WEB_SOCKET_DEBUG=1;
  27
  28 if (window.WebSocket && !window.WEB_SOCKET_FORCE_FLASH) {
  29     Websock_native = true;
  30 } else if (window.MozWebSocket && !window.WEB_SOCKET_FORCE_FLASH) {
  31     Websock_native = true;
  32     window.WebSocket = window.MozWebSocket;
  33 } else {
  34     /* no builtin WebSocket so load web_socket.js */
  35
  36     Websock_native = false;
  37     (function () {
  38         function get_INCLUDE_URI() {
  39             return (typeof INCLUDE_URI !== "undefined") ?
  40                 INCLUDE_URI : "include/";
  41         }
  42
  43         var start = "<script src='" + get_INCLUDE_URI(),
  44             end = "'><\/script>", extra = "";
  45
  46         window.WEB_SOCKET_SWF_LOCATION = get_INCLUDE_URI() +
  47                     "web-socket-js/WebSocketMain.swf";
  48         if (Util.Engine.trident) {
  49             Util.Debug("Forcing uncached load of WebSocketMain.swf");
  50             window.WEB_SOCKET_SWF_LOCATION += "?" + Math.random();
  51         }
  52         extra += start + "web-socket-js/swfobject.js" + end;
  53         extra += start + "web-socket-js/web_socket.js" + end;
  54         document.write(extra);
  55     }());
  56 }
  57
  58
  59 function Websock() {
  60 "use strict";
  61
  62 var api = {},         // Public API
  63     websocket = null, // WebSocket object
  64     rQ = [],          // Receive queue
  65     rQi = 0,          // Receive queue index
  66     rQmax = 10000,    // Max receive queue size before compacting
  67     sQ = [],          // Send queue
  68
  69     eventHandlers = {
  70         'message' : function() {},
  71         'open'    : function() {},
  72         'close'   : function() {},
  73         'error'   : function() {}
  74     },
  75
  76     test_mode = false;
  77
  78
  79 //
  80 // Queue public functions
  81 //
  82
  83 function get_sQ() {
  84     return sQ;
  85 }
  86
  87 function get_rQ() {
  88     return rQ;
  89 }
  90 function get_rQi() {
  91     return rQi;
  92 }
  93 function set_rQi(val) {
  94     rQi = val;
  95 }
  96
  97 function rQlen() {
  98     return rQ.length - rQi;
  99 }
 100
 101 function rQpeek8() {
 102     return (rQ[rQi]      );
 103 }
 104 function rQshift8() {
 105     return (rQ[rQi++]      );
 106 }
 107 function rQunshift8(num) {
 108     if (rQi === 0) {
 109         rQ.unshift(num);
 110     } else {
 111         rQi -= 1;
 112         rQ[rQi] = num;
 113     }
 114
 115 }
 116 function rQshift16() {
 117     return (rQ[rQi++] <<  8) +
 118            (rQ[rQi++]      );
 119 }
 120 function rQshift32() {
 121     return (rQ[rQi++] << 24) +
 122            (rQ[rQi++] << 16) +
 123            (rQ[rQi++] <<  8) +
 124            (rQ[rQi++]      );
 125 }
 126 function rQshiftStr(len) {
 127     if (typeof(len) === 'undefined') { len = rQlen(); }
 128     var arr = rQ.slice(rQi, rQi + len);
 129     rQi += len;
 130     return arr.map(function (num) {
 131             return String.fromCharCode(num); } ).join('');
 132
 133 }
 134 function rQshiftBytes(len) {
 135     if (typeof(len) === 'undefined') { len = rQlen(); }
 136     rQi += len;
 137     return rQ.slice(rQi-len, rQi);
 138 }
 139
 140 function rQslice(start, end) {
 141     if (end) {
 142         return rQ.slice(rQi + start, rQi + end);
 143     } else {
 144         return rQ.slice(rQi + start);
 145     }
 146 }
 147
 148 // Check to see if we must wait for 'num' bytes (default to FBU.bytes)
 149 // to be available in the receive queue. Return true if we need to
 150 // wait (and possibly print a debug message), otherwise false.
 151 function rQwait(msg, num, goback) {
 152     var rQlen = rQ.length - rQi; // Skip rQlen() function call
 153     if (rQlen < num) {
 154         if (goback) {
 155             if (rQi < goback) {
 156                 throw("rQwait cannot backup " + goback + " bytes");
 157             }
 158             rQi -= goback;
 159         }
 160         //Util.Debug("   waiting for " + (num-rQlen) +
 161         //           " " + msg + " byte(s)");
 162         return true;  // true means need more data
 163     }
 164     return false;
 165 }
 166
 167 //
 168 // Private utility routines
 169 //
 170
 171 function encode_message() {
 172     /* base64 encode */
 173     return Base64.encode(sQ);
 174 }
 175
 176 function decode_message(data) {
 177     //Util.Debug(">> decode_message: " + data);
 178     /* base64 decode */
 179     rQ = rQ.concat(Base64.decode(data, 0));
 180     //Util.Debug(">> decode_message, rQ: " + rQ);
 181 }
 182
 183
 184 //
 185 // Public Send functions
 186 //
 187
 188 function flush() {
 189     if (websocket.bufferedAmount !== 0) {
 190         Util.Debug("bufferedAmount: " + websocket.bufferedAmount);
 191     }
 192     if (websocket.bufferedAmount < api.maxBufferedAmount) {
 193         //Util.Debug("arr: " + arr);
 194         //Util.Debug("sQ: " + sQ);
 195         if (sQ.length > 0) {
 196             websocket.send(encode_message(sQ));
 197             sQ = [];
 198         }
 199         return true;
 200     } else {
 201         Util.Info("Delaying send, bufferedAmount: " +
 202                 websocket.bufferedAmount);
 203         return false;
 204     }
 205 }
 206
 207 // overridable for testing
 208 function send(arr) {
 209     //Util.Debug(">> send_array: " + arr);
 210     sQ = sQ.concat(arr);
 211     return flush();
 212 }
 213
 214 function send_string(str) {
 215     //Util.Debug(">> send_string: " + str);
 216     api.send(str.split('').map(
 217         function (chr) { return chr.charCodeAt(0); } ) );
 218 }
 219
 220 //
 221 // Other public functions
 222
 223 function recv_message(e) {
 224     //Util.Debug(">> recv_message: " + e.data.length);
 225
 226     try {
 227         decode_message(e.data);
 228         if (rQlen() > 0) {
 229             eventHandlers.message();
 230             // Compact the receive queue
 231             if (rQ.length > rQmax) {
 232                 //Util.Debug("Compacting receive queue");
 233                 rQ = rQ.slice(rQi);
 234                 rQi = 0;
 235             }
 236         } else {
 237             Util.Debug("Ignoring empty message");
 238         }
 239     } catch (exc) {
 240         if (typeof exc.stack !== 'undefined') {
 241             Util.Warn("recv_message, caught exception: " + exc.stack);
 242         } else if (typeof exc.description !== 'undefined') {
 243             Util.Warn("recv_message, caught exception: " + exc.description);
 244         } else {
 245             Util.Warn("recv_message, caught exception:" + exc);
 246         }
 247         if (typeof exc.name !== 'undefined') {
 248             eventHandlers.error(exc.name + ": " + exc.message);
 249         } else {
 250             eventHandlers.error(exc);
 251         }
 252     }
 253     //Util.Debug("<< recv_message");
 254 }
 255
 256
 257 // Set event handlers
 258 function on(evt, handler) {
 259     eventHandlers[evt] = handler;
 260 }
 261
 262 function init() {
 263     rQ         = [];
 264     rQi        = 0;
 265     sQ         = [];
 266     websocket  = null;
 267 }
 268
 269 function open(uri) {
 270     init();
 271
 272     if (test_mode) {
 273         websocket = {};
 274     } else {
 275         websocket = new WebSocket(uri, 'base64');
 276         // TODO: future native binary support
 277         //websocket = new WebSocket(uri, ['binary', 'base64']);
 278     }
 279
 280     websocket.onmessage = recv_message;
 281     websocket.onopen = function() {
 282         Util.Debug(">> WebSock.onopen");
 283         if (websocket.protocol) {
 284             Util.Info("Server chose sub-protocol: " + websocket.protocol);
 285         } else {
 286             Util.Error("Server select no sub-protocol!: " + websocket.protocol);
 287         }
 288         eventHandlers.open();
 289         Util.Debug("<< WebSock.onopen");
 290     };
 291     websocket.onclose = function(e) {
 292         Util.Debug(">> WebSock.onclose");
 293         eventHandlers.close(e);
 294         Util.Debug("<< WebSock.onclose");
 295     };
 296     websocket.onerror = function(e) {
 297         Util.Debug(">> WebSock.onerror: " + e);
 298         eventHandlers.error(e);
 299         Util.Debug("<< WebSock.onerror");
 300     };
 301 }
 302
 303 function close() {
 304     if (websocket) {
 305         if ((websocket.readyState === WebSocket.OPEN) ||
 306             (websocket.readyState === WebSocket.CONNECTING)) {
 307             Util.Info("Closing WebSocket connection");
 308             websocket.close();
 309         }
 310         websocket.onmessage = function (e) { return; };
 311     }
 312 }
 313
 314 // Override internal functions for testing
 315 // Takes a send function, returns reference to recv function
 316 function testMode(override_send) {
 317     test_mode = true;
 318     api.send = override_send;
 319     api.close = function () {};
 320     return recv_message;
 321 }
 322
 323 function constructor() {
 324     // Configuration settings
 325     api.maxBufferedAmount = 200;
 326
 327     // Direct access to send and receive queues
 328     api.get_sQ       = get_sQ;
 329     api.get_rQ       = get_rQ;
 330     api.get_rQi      = get_rQi;
 331     api.set_rQi      = set_rQi;
 332
 333     // Routines to read from the receive queue
 334     api.rQlen        = rQlen;
 335     api.rQpeek8      = rQpeek8;
 336     api.rQshift8     = rQshift8;
 337     api.rQunshift8   = rQunshift8;
 338     api.rQshift16    = rQshift16;
 339     api.rQshift32    = rQshift32;
 340     api.rQshiftStr   = rQshiftStr;
 341     api.rQshiftBytes = rQshiftBytes;
 342     api.rQslice      = rQslice;
 343     api.rQwait       = rQwait;
 344
 345     api.flush        = flush;
 346     api.send         = send;
 347     api.send_string  = send_string;
 348
 349     api.on           = on;
 350     api.init         = init;
 351     api.open         = open;
 352     api.close        = close;
 353     api.testMode     = testMode;
 354
 355     return api;
 356 }
 357
 358 return constructor();
 359
 360 }