From ed19b704cc36ceebc433aa3aa54b23517cacb50b Mon Sep 17 00:00:00 2001
From: Michael Jumper <mjumper@apache.org>
Date: Wed, 28 Sep 2022 10:50:25 -0700
Subject: [PATCH] GUACAMOLE-1687: Clean, document, and clarify usage of tunnel
 timer reset function.

---
 .../src/main/webapp/modules/Tunnel.js         | 42 +++++++++++--------
 1 file changed, 25 insertions(+), 17 deletions(-)

diff --git a/guacamole-common-js/src/main/webapp/modules/Tunnel.js b/guacamole-common-js/src/main/webapp/modules/Tunnel.js
index ec2d8259a..c698ee8ed 100644
--- a/guacamole-common-js/src/main/webapp/modules/Tunnel.js
+++ b/guacamole-common-js/src/main/webapp/modules/Tunnel.js
@@ -356,12 +356,16 @@ Guacamole.HTTPTunnel = function(tunnelURL, crossDomain, extraTunnelHeaders) {
     }
 
     /**
-     * Initiates a timeout which, if data is not received, causes the tunnel
-     * to close with an error.
-     * 
+     * Resets the state of timers tracking network activity and stability. If
+     * those timers are not yet started, invoking this function starts them.
+     * This function should be invoked when the tunnel is established and every
+     * time there is network activity on the tunnel, such that the timers can
+     * safely assume the network and/or server are not responding if this
+     * function has not been invoked for a significant period of time.
+     *
      * @private
      */
-    function reset_timeout() {
+    var resetTimers = function resetTimers() {
 
         // Get rid of old timeouts (if any)
         window.clearTimeout(receive_timeout);
@@ -381,7 +385,7 @@ Guacamole.HTTPTunnel = function(tunnelURL, crossDomain, extraTunnelHeaders) {
             tunnel.setState(Guacamole.Tunnel.State.UNSTABLE);
         }, tunnel.unstableThreshold);
 
-    }
+    };
 
     /**
      * Closes this tunnel, signaling the given status and corresponding
@@ -491,7 +495,7 @@ Guacamole.HTTPTunnel = function(tunnelURL, crossDomain, extraTunnelHeaders) {
             message_xmlhttprequest.onreadystatechange = function() {
                 if (message_xmlhttprequest.readyState === 4) {
 
-                    reset_timeout();
+                    resetTimers();
 
                     // If an error occurs during send, handle it
                     if (message_xmlhttprequest.status !== 200)
@@ -581,7 +585,7 @@ Guacamole.HTTPTunnel = function(tunnelURL, crossDomain, extraTunnelHeaders) {
             if (xmlhttprequest.readyState === 3 ||
                 xmlhttprequest.readyState === 4) {
 
-                reset_timeout();
+                resetTimers();
 
                 // Also poll every 30ms (some browsers don't repeatedly call onreadystatechange for new data)
                 if (pollingMode === POLLING_ENABLED) {
@@ -742,7 +746,7 @@ Guacamole.HTTPTunnel = function(tunnelURL, crossDomain, extraTunnelHeaders) {
     this.connect = function(data) {
 
         // Start waiting for connect
-        reset_timeout();
+        resetTimers();
 
         // Mark the tunnel as connecting
         tunnel.setState(Guacamole.Tunnel.State.CONNECTING);
@@ -760,7 +764,7 @@ Guacamole.HTTPTunnel = function(tunnelURL, crossDomain, extraTunnelHeaders) {
                 return;
             }
 
-            reset_timeout();
+            resetTimers();
 
             // Get UUID and HTTP-specific tunnel session token from response
             tunnel.setUUID(connect_xmlhttprequest.responseText);
@@ -932,12 +936,16 @@ Guacamole.WebSocketTunnel = function(tunnelURL) {
     };
 
     /**
-     * Initiates a timeout which, if data is not received, causes the tunnel
-     * to close with an error.
-     * 
+     * Resets the state of timers tracking network activity and stability. If
+     * those timers are not yet started, invoking this function starts them.
+     * This function should be invoked when the tunnel is established and every
+     * time there is network activity on the tunnel, such that the timers can
+     * safely assume the network and/or server are not responding if this
+     * function has not been invoked for a significant period of time.
+     *
      * @private
      */
-    function reset_timeout() {
+    var resetTimers = function resetTimers() {
 
         // Get rid of old timeouts (if any)
         window.clearTimeout(receive_timeout);
@@ -968,7 +976,7 @@ Guacamole.WebSocketTunnel = function(tunnelURL) {
         else
             sendPing();
 
-    }
+    };
 
     /**
      * Closes this tunnel, signaling the given status and corresponding
@@ -1043,7 +1051,7 @@ Guacamole.WebSocketTunnel = function(tunnelURL) {
 
     this.connect = function(data) {
 
-        reset_timeout();
+        resetTimers();
 
         // Mark the tunnel as connecting
         tunnel.setState(Guacamole.Tunnel.State.CONNECTING);
@@ -1052,7 +1060,7 @@ Guacamole.WebSocketTunnel = function(tunnelURL) {
         socket = new WebSocket(tunnelURL + "?" + data, "guacamole");
 
         socket.onopen = function(event) {
-            reset_timeout();
+            resetTimers();
         };
 
         socket.onclose = function(event) {
@@ -1074,7 +1082,7 @@ Guacamole.WebSocketTunnel = function(tunnelURL) {
         
         socket.onmessage = function(event) {
 
-            reset_timeout();
+            resetTimers();
 
             var message = event.data;
             var startIndex = 0;