Improve web-app type safety.

remoting/webapp/me2mom/remoting.js

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /** @suppress {duplicate} */
 var remoting = remoting || {};
 
-(function() {
-'use strict';
+/**
+ * Whether or not the plugin should scale itself.
+ * @type {boolean}
+ */
+remoting.scaleToFit = false;
 
-window.addEventListener('blur', pluginLostFocus_, false);
+/** @type {remoting.ClientSession} */
+remoting.session = null;
 
-function pluginLostFocus_() {
-  // If the plug loses input focus, release all keys as a precaution against
-  // leaving them 'stuck down' on the host.
-  if (remoting.session && remoting.session.plugin) {
-    remoting.session.plugin.releaseAllKeys();
-  }
-}
+/** @type {string} */ remoting.accessCode = '';
+/** @type {number} */ remoting.accessCodeTimerId = 0;
+/** @type {number} */ remoting.accessCodeExpiresIn = 0;
+/** @type {remoting.AppMode} */ remoting.currentMode;
+/** @type {string} */ remoting.hostJid = '';
+/** @type {string} */ remoting.hostPublicKey = '';
+/** @type {boolean} */ remoting.lastShareWasCancelled = false;
+/** @type {boolean} */ remoting.timerRunning = false;
+/** @type {string} */ remoting.username = '';

[Jamie, 2011/10/18 00:19:27]

This while file needs refactoring, but for now just pre-declaring these globals
make the intent more explicit that having them created at first use.

 
 /** @enum {string} */
 remoting.AppMode = {
   HOME: 'home',
   UNAUTHENTICATED: 'auth',
   CLIENT: 'client',
     CLIENT_UNCONNECTED: 'client.unconnected',
     CLIENT_CONNECTING: 'client.connecting',
     CLIENT_CONNECT_FAILED: 'client.connect-failed',
     CLIENT_SESSION_FINISHED: 'client.session-finished',
   HOST: 'host',
     HOST_WAITING_FOR_CODE: 'host.waiting-for-code',
     HOST_WAITING_FOR_CONNECTION: 'host.waiting-for-connection',
     HOST_SHARED: 'host.shared',
     HOST_SHARE_FAILED: 'host.share-failed',
     HOST_SHARE_FINISHED: 'host.share-finished',
   IN_SESSION: 'in-session'
 };
 
-remoting.EMAIL = 'email';

[Jamie, 2011/10/18 00:19:27]

This is no longer used.

+(function() {
+'use strict';

[simonmorris, 2011/10/18 00:55:36]

Is it better to have 'use strict' at the top of the file?

[Jamie, 2011/10/18 01:42:01]

It doesn't matter, but yes, probably. Done.

+
+window.addEventListener('blur', pluginLostFocus_, false);
+
+function pluginLostFocus_() {
+  // If the plug loses input focus, release all keys as a precaution against
+  // leaving them 'stuck down' on the host.
+  if (remoting.session && remoting.session.plugin) {
+    remoting.session.plugin.releaseAllKeys();
+  }
+}
+
+/** @type {string} */
 remoting.HOST_PLUGIN_ID = 'host-plugin-id';
 
 /** @enum {string} */
 remoting.ClientError = {
   NO_RESPONSE: /*i18n-content*/'ERROR_NO_RESPONSE',
   INVALID_ACCESS_CODE: /*i18n-content*/'ERROR_INVALID_ACCESS_CODE',
   MISSING_PLUGIN: /*i18n-content*/'ERROR_MISSING_PLUGIN',
   OAUTH_FETCH_FAILED: /*i18n-content*/'ERROR_AUTHENTICATION_FAILED',
   HOST_IS_OFFLINE: /*i18n-content*/'ERROR_HOST_IS_OFFLINE',
   INCOMPATIBLE_PROTOCOL: /*i18n-content*/'ERROR_INCOMPATIBLE_PROTOCOL',
   OTHER_ERROR: /*i18n-content*/'ERROR_GENERIC'
 };
 
-/**
- * Whether or not the plugin should scale itself.
- * @type {boolean}
- */
-remoting.scaleToFit = false;
-
 // Constants representing keys used for storing persistent application state.
 var KEY_APP_MODE_ = 'remoting-app-mode';
 var KEY_EMAIL_ = 'remoting-email';
 var KEY_USE_P2P_API_ = 'remoting-use-p2p-api';
 
 // Some constants for pretty-printing the access code.
-var kSupportIdLen = 7;
-var kHostSecretLen = 5;
-var kAccessCodeLen = kSupportIdLen + kHostSecretLen;
-var kDigitsPerGroup = 4;
+/** @type {number} */ var kSupportIdLen = 7;
+/** @type {number} */ var kHostSecretLen = 5;
+/** @type {number} */ var kAccessCodeLen = kSupportIdLen + kHostSecretLen;
+/** @type {number} */ var kDigitsPerGroup = 4;
 
+/**
+ * @param {string} classes A space-separated list of classes.
+ * @param {string} cls The class to check for.
+ * @return {boolean} True if |cls| is found within |classes|.
+ */
 function hasClass(classes, cls) {
-  return classes.match(new RegExp('(\\s|^)' + cls + '(\\s|$)'));
+  return classes.match(new RegExp('(\\s|^)' + cls + '(\\s|$)')) != null;
 }
 
+/**
+ * @param {Element} element The element to which to add the class.
+ * @param {string} cls The new class.
+ * @return {void} Nothing.
+ */
 function addClass(element, cls) {
   if (!hasClass(element.className, cls)) {
     var padded = element.className == '' ? '' : element.className + ' ';
     element.className = padded + cls;
   }
 }
 
+/**
+ * @param {Element} element The element from which to remove the class.
+ * @param {string} cls The new class.
+ * @return {void} Nothing.
+ */
 function removeClass(element, cls) {
   element.className =
       element.className.replace(new RegExp('\\b' + cls + '\\b', 'g'), '')
                        .replace('  ', ' ');
 }
 
 function retrieveEmail_(access_token) {
   var headers = {
     'Authorization': 'OAuth ' + remoting.oauth2.getAccessToken()
   };
 
+  /** @param {XMLHttpRequest} xhr The XHR response. */
   var onResponse = function(xhr) {
     if (xhr.status != 200) {
       // TODO(ajwong): Have a better way of showing an error.
       remoting.debug.log('Unable to get email');
       document.getElementById('current-email').innerText = '???';
       return;
     }
 
     // TODO(ajwong): See if we can't find a JSON endpoint.
     setEmail(xhr.responseText.split('&')[0].split('=')[1]);
   };
 
   // TODO(ajwong): Update to new v2 API.
   remoting.xhr.get('https://www.googleapis.com/userinfo/email',
                    onResponse, '', headers);
 }
 
 function refreshEmail_() {
   if (!getEmail() && remoting.oauth2.isAuthenticated()) {
     remoting.oauth2.callWithToken(retrieveEmail_);
   }
 }
 
+/**
+ * @param {string} value The email address to place in local storage.
+ * @return {void} Nothing.
+ */
 function setEmail(value) {
   window.localStorage.setItem(KEY_EMAIL_, value);
   document.getElementById('current-email').innerText = value;
 }
 
 /**
  * @return {?string} The email address associated with the auth credentials.
  */
 function getEmail() {
   var result = window.localStorage.getItem(KEY_EMAIL_);
   return typeof result == 'string' ? result : null;
 }
 
 function exchangedCodeForToken_() {
   if (!remoting.oauth2.isAuthenticated()) {
     alert('Your OAuth2 token was invalid. Please try again.');
   }
-  remoting.oauth2.callWithToken(function(token) {
-      retrieveEmail_(token);
-  });
+  /** @param {string} token The auth token. */
+  var retrieveEmail = function(token) { retrieveEmail_(token); }
+  remoting.oauth2.callWithToken(retrieveEmail);
 }
 
 remoting.clearOAuth2 = function() {
   remoting.oauth2.clear();
   window.localStorage.removeItem(KEY_EMAIL_);
   remoting.setMode(remoting.AppMode.UNAUTHENTICATED);
 }
 
 remoting.toggleDebugLog = function() {
   var debugLog = document.getElementById('debug-log');
@@ skipping 41 matching lines @@
  *
  * @param {remoting.AppMode} mode The new modal state, expressed as a dotted
  * hiearchy.
  */
 remoting.setMode = function(mode) {
   var modes = mode.split('.');
   for (var i = 1; i < modes.length; ++i)
     modes[i] = modes[i - 1] + '.' + modes[i];
   var elements = document.querySelectorAll('[data-ui-mode]');
   for (var i = 0; i < elements.length; ++i) {
-    var element = elements[i];
+    /** @type {Element} */ var element = elements[i];
     var hidden = true;
     for (var m = 0; m < modes.length; ++m) {
       if (hasClass(element.getAttribute('data-ui-mode'), modes[m])) {
         hidden = false;
         break;
       }
     }
     element.hidden = hidden;
   }
   remoting.debug.log('App mode: ' + mode);
   remoting.currentMode = mode;
   if (mode == remoting.AppMode.IN_SESSION) {
     document.removeEventListener('keydown', remoting.checkHotkeys, false);
   } else {
     document.addEventListener('keydown', remoting.checkHotkeys, false);
   }
 }
 
 /**
  * Get the major mode that the app is running in.
- * @return {remoting.AppMode} The app's current major mode.
+ * @return {string} The app's current major mode.
  */
 remoting.getMajorMode = function() {
   return remoting.currentMode.split('.')[0];
 }
 
 remoting.tryShare = function() {
   remoting.debug.log('Attempting to share...');
   remoting.lastShareWasCancelled = false;
   if (remoting.oauth2.needsNewAccessToken()) {
     remoting.debug.log('Refreshing token...');
@@ skipping 73 matching lines @@
 
 remoting.updateAccessCodeTimeoutElement_ = function() {
   var pad = (remoting.accessCodeExpiresIn < 10) ? '0:0' : '0:';
   l10n.localizeElement(document.getElementById('seconds-remaining'),
                        pad + remoting.accessCodeExpiresIn);
   if (!updateTimeoutStyles_()) {
     disableTimeoutCountdown_();
   }
 }
 
+/**
+ * Callback to show or hide the NAT traversal warning when the policy changes.
+ * @param {boolean} enabled True if NAT traversal is enabled.
+ * @return {void} Nothing.
+ */
 function onNatTraversalPolicyChanged_(enabled) {
   var container = document.getElementById('nat-box-container');
   container.hidden = enabled;
 }
 
 function onStateChanged_() {
   var plugin = /** @type {remoting.HostPlugin} */
       document.getElementById(remoting.HOST_PLUGIN_ID);
   var state = plugin.state;
   if (state == plugin.STARTING) {
@@ skipping 86 matching lines @@
  * @return {void} Nothing.
  */
 remoting.cancelShare = function() {
   remoting.debug.log('Canceling share...');
   remoting.lastShareWasCancelled = true;
   var plugin = /** @type {remoting.HostPlugin} */
       document.getElementById(remoting.HOST_PLUGIN_ID);
   try {
     plugin.disconnect();
   } catch (error) {
-    remoting.debug.log('Error disconnecting: ' + error.description +
+    var tmp = /** @type {{description: string}} */ error;

[Jamie, 2011/10/18 00:19:27]

This is horrible, but I couldn't find any other way of adding type annotations
to an exception.

[simonmorris, 2011/10/18 00:55:36]

It's OK - maybe rename tmp to errorTyped, to make your
intention clearer?

[Jamie, 2011/10/18 01:42:01]

Done.

+    remoting.debug.log('Error disconnecting: ' + tmp.description +
                        '. The host plugin probably crashed.');
     // TODO(jamiewalch): Clean this up. We should have a class representing
     // the host plugin, like we do for the client, which should handle crash
     // reporting and it should use a more detailed error message than the
     // default 'generic' one. See crbug.com/94624
     showShareError_(/*i18n-content*/'ERROR_GENERIC');
   }
   disableTimeoutCountdown_();
 }
 
@@ skipping 48 matching lines @@
   // Update the stats once per second.
   window.setTimeout(updateStatistics, 1000);
 }
 
 function showToolbarPreview_() {
   var toolbar = document.getElementById('session-toolbar');
   addClass(toolbar, 'toolbar-preview');
   window.setTimeout(removeClass, 3000, toolbar, 'toolbar-preview');
 }
 
+/** @param {number} oldState The previous state of the plugin. */
 function onClientStateChange_(oldState) {
   if (!remoting.session) {
     // If the connection has been cancelled, then we no longer have a reference
     // to the session object and should ignore any state changes.
     return;
   }
   var state = remoting.session.state;
   if (state == remoting.ClientSession.State.CREATED) {
     remoting.debug.log('Created plugin');
   } else if (state == remoting.ClientSession.State.BAD_PLUGIN_VERSION) {
@@ skipping 49 matching lines @@
 function startSession_() {
   remoting.debug.log('Starting session...');
   var accessCode = document.getElementById('access-code-entry');
   accessCode.value = '';  // The code has been validated and won't work again.
   remoting.username =
       /** @type {string} email must be non-NULL to get here */ getEmail();
   remoting.session =
       new remoting.ClientSession(remoting.hostJid, remoting.hostPublicKey,
                                  remoting.accessCode, remoting.username,
                                  onClientStateChange_);
-  remoting.oauth2.callWithToken(function(token) {
+  /** @param {string} token The auth token. */
+  var createPluginAndConnect = function(token) {
     remoting.session.createPluginAndConnect(
         document.getElementById('session-mode'),
         token);
-  });
+  };
+  remoting.oauth2.callWithToken(createPluginAndConnect);
 }
 
 /**
  * Show a client-side error message.
  *
  * @param {remoting.ClientError} errorTag The error to be localized and
  * displayed.
  * @return {void} Nothing.
  */
 function showConnectError_(errorTag) {
   remoting.debug.log('Connection failed: ' + errorTag);
   var errorDiv = document.getElementById('connect-error-message');
   l10n.localizeElementFromTag(errorDiv, /** @type {string} */ (errorTag));
   remoting.accessCode = '';
   if (remoting.session) {
     remoting.session.disconnect();
     remoting.session = null;
   }
   remoting.setMode(remoting.AppMode.CLIENT_CONNECT_FAILED);
 }
 
 /**
  * @param {XMLHttpRequest} xhr The XMLHttpRequest object.
  * @return {void} Nothing.
  */
 function parseServerResponse_(xhr) {
   remoting.supportHostsXhr = null;
   remoting.debug.log('parseServerResponse: status = ' + xhr.status);
   if (xhr.status == 200) {
-    var host = JSON.parse(xhr.responseText);
-    if (host.data && host.data.jabberId) {
+    var host = /** @type {{data: {jabberId: string, publicKey: string}}} */
+        JSON.parse(xhr.responseText);
+    if (host.data && host.data.jabberId && host.data.publicKey) {

[Jamie, 2011/10/18 00:19:27]

I've updated the test to match the type cast above so that it's safe.

[simonmorris, 2011/10/18 00:55:36]

OK.

       remoting.hostJid = host.data.jabberId;
       remoting.hostPublicKey = host.data.publicKey;
       var split = remoting.hostJid.split('/');
       document.getElementById('connected-to').innerText = split[0];
       startSession_();
       return;
     }
   }
   var errorMsg = remoting.ClientError.OTHER_ERROR;
   if (xhr.status == 404) {
     errorMsg = remoting.ClientError.INVALID_ACCESS_CODE;
   } else if (xhr.status == 0) {
     errorMsg = remoting.ClientError.NO_RESPONSE;
   } else {
     remoting.debug.log('The server responded: ' + xhr.responseText);
   }
   showConnectError_(errorMsg);
 }
 
+/** @param {string} accessCode The access code, as entered by the user.
+ *  @return {string} The normalized form of the code (whitespace removed). */
 function normalizeAccessCode_(accessCode) {
   // Trim whitespace.
   // TODO(sergeyu): Do we need to do any other normalization here?
   return accessCode.replace(/\s/g, '');
 }
 
+/** @param {string} supportId The canonicalized support ID. */
 function resolveSupportId(supportId) {
   var headers = {
     'Authorization': 'OAuth ' + remoting.oauth2.getAccessToken()
   };
 
   remoting.supportHostsXhr = remoting.xhr.get(
       'https://www.googleapis.com/chromoting/v1/support-hosts/' +
           encodeURIComponent(supportId),
       parseServerResponse_,
       '',
@@ skipping 14 matching lines @@
     });
   } else {
     remoting.tryConnectWithAccessToken();
   }
 }
 
 remoting.tryConnectWithAccessToken = function() {
   if (!remoting.wcsLoader) {
     remoting.wcsLoader = new remoting.WcsLoader();
   }
+  /** @param {function(string):void} setToken The callback function. */
+  var callWithToken = function(setToken) {
+    remoting.oauth2.callWithToken(setToken);
+  };
   remoting.wcsLoader.start(
       remoting.oauth2.getAccessToken(),
-      function(setToken) {
-        remoting.oauth2.callWithToken(setToken);
-      },
+      callWithToken,
       remoting.tryConnectWithWcs);
 }
 
 remoting.tryConnectWithWcs = function() {
   var accessCode = document.getElementById('access-code-entry').value;
   remoting.accessCode = normalizeAccessCode_(accessCode);
   // At present, only 12-digit access codes are supported, of which the first
   // 7 characters are the supportId.
   if (remoting.accessCode.length != kAccessCodeLen) {
     remoting.debug.log('Bad access code length');
@@ skipping 97 matching lines @@
     case remoting.AppMode.HOST_WAITING_FOR_CONNECTION:
     case remoting.AppMode.HOST_SHARED:
     case remoting.AppMode.IN_SESSION:
       var result = chrome.i18n.getMessage(/*i18n-content*/'CLOSE_PROMPT');
       return result;
     default:
       return null;
   }
 }
 
+/**
+ * @param {Event} event The keyboard event.
+ * @return {void} Nothing.
+ */
 remoting.checkHotkeys = function(event) {
   if (String.fromCharCode(event.which) == 'D') {
     remoting.toggleDebugLog();
   }
 }
 
 function recenterToolbar_() {
   var toolbar = document.getElementById('session-toolbar');
   var toolbarX = (window.innerWidth - toolbar.clientWidth) / 2;
   toolbar.style['left'] = toolbarX + 'px';
 }
 
 }());