beta: https better server support, client-server port config (#85)

* feat: client-server port config, better server support

* chore: beta

* docs: add https note about firefox

* test: fix tests

Author: shellscape

README.md

@@ -147,7 +147,8 @@ Default: `'localhost'`
 
 Sets the host that the `WebSocket` server will listen on. If this doesn't match
 the host of the server the module is used with, the module may not function
-properly. If the `server` option is defined, this option is ignored.
+properly. If the `server` option is defined, and the server has been instructed
+to listen, this option is ignored.
 
 If using the module in a specialized environment, you may choose to specify an
 `object` to define `client` and `server` host separately. The `object` value
@@ -181,6 +182,10 @@ module won't function properly. The module will examine the `server` instance
 passed and if `server` _is an instance of `https.Server`, and `https` is not
 already set_, will set `https` to `true`.
 
+_Note: When using a self-signed certificate on Firefox, you must add a "Server
+Exception" for `localhost:{port}` where `{port}` is either the `port` or the
+`port.server` option for secure `WebSocket` to work correctly._
+
 ##### logLevel
 
 Type: `String`  
@@ -198,12 +203,21 @@ If true, instructs the internal logger to prepend log output with a timestamp.
 
 ##### port
 
-Type: `Number`  
+Type: `Number|Object`  
 Default: `0`
 
 The port the `WebSocket` server should listen on. By default, the socket server
 will allocate a port. If a different port is chosen, the consumer of the module
-must ensure that the port is free before hand.
+must ensure that the port is free before hand. If the `server` option is defined,
+and the server has been instructed to listen, this option is ignored.
+
+If using the module in a specialized environment, you may choose to specify an
+`object` to define `client` and `server` port separately. The `object` value
+should match `{ client: <Number>, server: <Number> }`. Be aware that the `client`
+port will be used _in the browser_ by `WebSockets`. You should not use this
+option in this way unless _you know what you're doing._ Using a mismatched
+`client` and `server` port will be **unsupported by the project** as the behavior
+in the browser can be unpredictable and is specific to a particular environment.
 
 ##### reload
 

lib/options.js

@@ -46,8 +46,8 @@ module.exports = (opts = {}) => {
 
   if (typeof options.host === 'string') {
     options.host = {
-      server: options.host,
       client: options.host,
+      server: options.host,
     };
   } else if (!options.host.server) {
     throw new HotClientError(
@@ -59,23 +59,41 @@ module.exports = (opts = {}) => {
     );
   }
 
-  const { server } = options;
-
-  if (server && !server.listening) {
+  if (typeof options.port === 'number') {
+    options.port = {
+      client: options.port,
+      server: options.port,
+    };
+  } else if (!options.port.server) {
+    throw new HotClientError(
+      '`port.server` must be defined when setting host to an Object'
+    );
+  } else if (!options.port.client) {
     throw new HotClientError(
-      '`options.server` must be a running/listening net.Server instance'
+      '`port.client` must be defined when setting host to an Object'
     );
-  } else if (server) {
+  }
+
+  const { server } = options;
+
+  if (
+    server &&
+    server instanceof HttpsServer &&
+    typeof options.https === 'undefined'
+  ) {
+    options.https = true;
+  }
+
+  if (server && server.listening) {
     options.webSocket = {
       host: server.address().address,
       port: server.address().port,
     };
-
-    if (server instanceof HttpsServer && typeof options.https === 'undefined') {
-      options.https = true;
-    }
   } else {
-    options.webSocket = { host: options.host.client, port: options.port };
+    options.webSocket = {
+      host: options.host.client,
+      port: options.port.client,
+    };
   }
 
   return options;

lib/socket-server.js

@@ -4,7 +4,14 @@ const WebSocket = require('ws');
 
 function getServer(options) {
   const { host, log, port, server } = options;
-  const wssOptions = server ? { server } : { host: host.server, port };
+  const wssOptions = server
+    ? { server }
+    : { host: host.server, port: port.server };
+
+  if (server && !server.listening) {
+    server.listen(port.server, host.server);
+  }
+
   const wss = new WebSocket.Server(wssOptions);
 
   onConnection(wss, options);
@@ -87,7 +94,7 @@ function onListening(server, options) {
   /* eslint-disable no-underscore-dangle, no-param-reassign */
   const { host, log } = options;
 
-  if (options.server) {
+  if (options.server && options.server.listening) {
     const addr = options.server.address();
     server.host = addr.address;
     server.port = addr.port;

package.json

@@ -1,6 +1,9 @@
 {
   "name": "webpack-hot-client",
-  "version": "4.0.4",
+  "version": "4.1.0-beta.1",
+  "publishConfig": {
+    "tag": "beta"
+  },
   "description": "A client for enabling, and interacting with, webpack Hot Module Replacement",
   "license": "MIT",
   "repository": "webpack-contrib/webpack-hot-client",

schemas/options.json

@@ -41,7 +41,22 @@
       "type": "boolean"
     },
     "port": {
-      "type": "integer"
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "properties": {
+            "client": {
+              "type": "integer"
+            },
+            "server": {
+              "type": "integer"
+            }
+          },
+          "type": "object"
+        }
+      ]
     },
     "reload": {
       "type": "boolean"

test/__snapshots__/options.test.js.snap

@@ -51,7 +51,10 @@ Object {
   },
   "logLevel": "trace",
   "logTime": true,
-  "port": 0,
+  "port": Object {
+    "client": 0,
+    "server": 0,
+  },
   "reload": false,
   "send": Object {
     "errors": false,
@@ -124,7 +127,10 @@ Object {
   },
   "logLevel": "info",
   "logTime": false,
-  "port": 0,
+  "port": Object {
+    "client": 0,
+    "server": 0,
+  },
   "reload": true,
   "send": Object {
     "errors": true,
@@ -196,7 +202,10 @@ Object {
   },
   "logLevel": "info",
   "logTime": false,
-  "port": 0,
+  "port": Object {
+    "client": 0,
+    "server": 0,
+  },
   "reload": true,
   "send": Object {
     "errors": true,
@@ -268,7 +277,10 @@ Object {
   },
   "logLevel": "info",
   "logTime": false,
-  "port": 0,
+  "port": Object {
+    "client": 0,
+    "server": 0,
+  },
   "reload": true,
   "send": Object {
     "errors": true,

test/fixtures/app.js

@@ -17,3 +17,7 @@ console.log('dirty');
 console.log('dirty');
 
 console.log('dirty');
+
+console.log('dirty');
+console.log('dirty');
+console.log('dirty');

test/options.test.js

@@ -1,6 +1,5 @@
 const { readFileSync: read } = require('fs');
 const { resolve } = require('path');
-const { createServer } = require('http');
 const https = require('https');
 
 const killable = require('killable');
@@ -102,16 +101,4 @@ describe('options', () => {
     const t = () => getOptions({ host: { client: 'localhost' } });
     expect(t).toThrow();
   });
-
-  test('reject non-http.Server server', () => {
-    const server = {};
-    const t = () => getOptions({ server });
-    expect(t).toThrow();
-  });
-
-  test('reject non-running server', () => {
-    const server = createServer();
-    const t = () => getOptions({ server });
-    expect(t).toThrow();
-  });
 });