feat: add an option to use native timer functions (#672)

This allows to control the behavior of mocked timers (@sinonjs/fake-timers),
depending on the value of the "useNativeTimers" option:

- true: use native setTimeout function
- false (default): use classic timers, that may be mocked

The "installTimerFunctions" method will also be used in the
`socket.io-client` package:

```
import { installTimerFunctions } from "engine.io-client/lib/util";
```

Note: we could also have put the method in its own library, but that
sounded a bit overkill

Related: socketio/socket.io-client#1479

Author: vartan

README.md

@@ -263,6 +263,7 @@ Exposed as `eio` in the browser standalone build.
       - `forceNode` (`Boolean`): Uses NodeJS implementation for websockets - even if there is a native Browser-Websocket available, which is preferred by default over the NodeJS implementation. (This is useful when using hybrid platforms like nw.js or electron) (`false`, NodeJS only)
       - `localAddress` (`String`): the local IP address to connect to
       - `autoUnref` (`Boolean`): whether the transport should be `unref`'d upon creation. This calls `unref` on the underlying timers and sockets so that the program is allowed to exit if they are the only timers/sockets in the event system (Node.js only)
+      - `useNativeTimers` (`Boolean`): Whether to always use the native timeouts. This allows the client to reconnect when the native timeout functions are overridden, such as when mock clocks are installed with [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers).
     - **Polling-only options**
       - `requestTimeout` (`Number`): Timeout for xhr-polling requests in milliseconds (`0`)
     - **Websocket-only options**

lib/socket.js

@@ -4,6 +4,7 @@ const debug = require("debug")("engine.io-client:socket");
 const parser = require("engine.io-parser");
 const parseuri = require("parseuri");
 const parseqs = require("parseqs");
+const { installTimerFunctions } = require("./util");
 
 class Socket extends Emitter {
   /**
@@ -31,6 +32,8 @@ class Socket extends Emitter {
       opts.hostname = parseuri(opts.host).host;
     }
 
+    installTimerFunctions(this, opts);
+
     this.secure =
       null != opts.secure
         ? opts.secure
@@ -172,7 +175,7 @@ class Socket extends Emitter {
       transport = "websocket";
     } else if (0 === this.transports.length) {
       // Emit error on next tick so it can be listened to
-      setTimeout(() => {
+      this.setTimeoutFn(() => {
         this.emit("error", "No transports available");
       }, 0);
       return;
@@ -431,8 +434,8 @@ class Socket extends Emitter {
    * @api private
    */
   resetPingTimeout() {
-    clearTimeout(this.pingTimeoutTimer);
-    this.pingTimeoutTimer = setTimeout(() => {
+    this.clearTimeoutFn(this.pingTimeoutTimer);
+    this.pingTimeoutTimer = this.setTimeoutFn(() => {
       this.onClose("ping timeout");
     }, this.pingInterval + this.pingTimeout);
     if (this.opts.autoUnref) {
@@ -609,8 +612,8 @@ class Socket extends Emitter {
       debug('socket close with reason: "%s"', reason);
 
       // clear timers
-      clearTimeout(this.pingIntervalTimer);
-      clearTimeout(this.pingTimeoutTimer);
+      this.clearTimeoutFn(this.pingIntervalTimer);
+      this.clearTimeoutFn(this.pingTimeoutTimer);
 
       // stop event from firing again for transport
       this.transport.removeAllListeners("close");

lib/transport.js

@@ -1,5 +1,6 @@
 const parser = require("engine.io-parser");
 const Emitter = require("component-emitter");
+const { installTimerFunctions } = require("./util");
 const debug = require("debug")("engine.io-client:transport");
 
 class Transport extends Emitter {
@@ -11,6 +12,7 @@ class Transport extends Emitter {
    */
   constructor(opts) {
     super();
+    installTimerFunctions(this, opts);
 
     this.opts = opts;
     this.query = opts.query;

lib/transports/polling-jsonp.js

@@ -99,7 +99,7 @@ class JSONPPolling extends Polling {
       "undefined" !== typeof navigator && /gecko/i.test(navigator.userAgent);
 
     if (isUAgecko) {
-      setTimeout(function() {
+      this.setTimeoutFn(function() {
         const iframe = document.createElement("iframe");
         document.body.appendChild(iframe);
         document.body.removeChild(iframe);

lib/transports/polling-xhr.js

@@ -3,7 +3,7 @@
 const XMLHttpRequest = require("xmlhttprequest-ssl");
 const Polling = require("./polling");
 const Emitter = require("component-emitter");
-const { pick } = require("../util");
+const { pick, installTimerFunctions } = require("../util");
 const globalThis = require("../globalThis");
 
 const debug = require("debug")("engine.io-client:polling-xhr");
@@ -105,6 +105,7 @@ class Request extends Emitter {
    */
   constructor(uri, opts) {
     super();
+    installTimerFunctions(this, opts);
     this.opts = opts;
 
     this.method = opts.method || "GET";
@@ -187,7 +188,7 @@ class Request extends Emitter {
           } else {
             // make sure the `error` event handler that's user-set
             // does not throw in the same tick and gets caught here
-            setTimeout(() => {
+            this.setTimeoutFn(() => {
               this.onError(typeof xhr.status === "number" ? xhr.status : 0);
             }, 0);
           }
@@ -200,7 +201,7 @@ class Request extends Emitter {
       // Need to defer since .create() is called directly from the constructor
       // and thus the 'error' event can only be only bound *after* this exception
       // occurs.  Therefore, also, we cannot throw here at all.
-      setTimeout(() => {
+      this.setTimeoutFn(() => {
         this.onError(e);
       }, 0);
       return;

lib/transports/websocket-constructor.browser.js

@@ -5,7 +5,7 @@ const nextTick = (() => {
   if (isPromiseAvailable) {
     return cb => Promise.resolve().then(cb);
   } else {
-    return cb => setTimeout(cb, 0);
+    return (cb, setTimeoutFn) => setTimeoutFn(cb, 0);
   }
 })();
 

lib/transports/websocket.js

@@ -165,7 +165,7 @@ class WS extends Transport {
           nextTick(() => {
             this.writable = true;
             this.emit("drain");
-          });
+          }, this.setTimeoutFn);
         }
       });
     }

lib/util.js

@@ -1,3 +1,5 @@
+const globalThis = require("./globalThis");
+
 module.exports.pick = (obj, ...attr) => {
   return attr.reduce((acc, k) => {
     if (obj.hasOwnProperty(k)) {
@@ -6,3 +8,17 @@ module.exports.pick = (obj, ...attr) => {
     return acc;
   }, {});
 };
+
+// Keep a reference to the real timeout functions so they can be used when overridden
+const NATIVE_SET_TIMEOUT = setTimeout;
+const NATIVE_CLEAR_TIMEOUT = clearTimeout;
+
+module.exports.installTimerFunctions = (obj, opts) => {
+  if (opts.useNativeTimers) {
+    obj.setTimeoutFn = NATIVE_SET_TIMEOUT.bind(globalThis);
+    obj.clearTimeoutFn = NATIVE_CLEAR_TIMEOUT.bind(globalThis);
+  } else {
+    obj.setTimeoutFn = setTimeout.bind(globalThis);
+    obj.clearTimeoutFn = clearTimeout.bind(globalThis);
+  }
+};