[doc] Discourage use of verifyClient hook (#1613)

Author: adrianhopebailie

README.md

@@ -32,6 +32,7 @@ can use one of the many wrappers available on npm, like
   - [Simple server](#simple-server)
   - [External HTTP/S server](#external-https-server)
   - [Multiple servers sharing a single HTTP/S server](#multiple-servers-sharing-a-single-https-server)
+  - [Client authentication](#client-authentication)
   - [Server broadcast](#server-broadcast)
   - [echo.websocket.org demo](#echowebsocketorg-demo)
   - [Use the Node.js streams API](#use-the-nodejs-streams-api)
@@ -249,6 +250,40 @@ server.on('upgrade', function upgrade(request, socket, head) {
 server.listen(8080);
 ```
 
+### Client authentication
+
+```js
+const http = require('http');
+const WebSocket = require('ws');
+const url = require('url');
+
+const server = http.createServer();
+const wss = new WebSocket.Server({ noServer: true });
+
+wss.on('connection', function(ws, request, client) {
+  ws.on('message', function(message) {
+    console.log(`WS message ${message} from user ${client}`);
+  });
+});
+
+server.on('upgrade', function upgrade(request, socket, head) {
+  authenticate(request, (err, client) => {
+    if (err || !client) {
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(request, socket, head, function done(ws) {
+      wss.emit('connection', ws, request, client);
+    });
+  });
+});
+
+server.listen(8080);
+```
+
+Also see the provided [example](./examples/express-session-parse) using
+`express-session`.
+
 ### Server broadcast
 
 A client WebSocket broadcasting to all connected WebSocket clients, including

doc/ws.md

@@ -57,7 +57,8 @@ This class represents a WebSocket server. It extends the `EventEmitter`.
   - `backlog` {Number} The maximum length of the queue of pending connections.
   - `server` {http.Server|https.Server} A pre-created Node.js HTTP/S server.
   - `verifyClient` {Function} A function which can be used to validate incoming
-    connections. See description below.
+    connections. See description below. (Usage is discouraged: see
+    [Issue #337](https://github.com/websockets/ws/issues/377#issuecomment-462152231))
   - `handleProtocols` {Function} A function which can be used to handle the
     WebSocket subprotocols. See description below.
   - `path` {String} Accept only connections matching this path.
@@ -75,6 +76,10 @@ started manually. The "noServer" mode allows the WebSocket server to be
 completly detached from the HTTP/S server. This makes it possible, for example,
 to share a single HTTP/S server between multiple WebSocket servers.
 
+> **NOTE:** Use of `verifyClient` is discouraged. Rather handle client
+> authentication in the `upgrade` event of the HTTP server. See examples for
+> more details.
+
 If `verifyClient` is not set then the handshake is automatically accepted. If it
 is provided with a single argument then that is:
 

examples/express-session-parse/index.js

@@ -48,20 +48,20 @@ app.delete('/logout', function(request, response) {
 //
 const server = http.createServer(app);
 
-const wss = new WebSocket.Server({
-  verifyClient: function(info, done) {
-    console.log('Parsing session from request...');
-    sessionParser(info.req, {}, () => {
-      console.log('Session is parsed!');
+const wss = new WebSocket.Server({ noServer: true });
 
-      //
-      // We can reject the connection by returning false to done(). For example,
-      // reject here if user is unknown.
-      //
-      done(info.req.session.userId);
+server.on('upgrade', function upgrade(request, socket, head) {
+  console.log('Parsing session from request...');
+  sessionParser(request, {}, () => {
+    if (!request.session.userId) {
+      socket.destroy();
+      return;
+    }
+    console.log('Session is parsed!');
+    wss.handleUpgrade(request, socket, head, function done(ws) {
+      wss.emit('connection', ws, request);
     });
-  },
-  server
+  });
 });
 
 wss.on('connection', function(ws, request) {

examples/express-session-parse/public/app.js

@@ -1,6 +1,7 @@
 (function() {
   const messages = document.querySelector('#messages');
   const wsButton = document.querySelector('#wsButton');
+  const wsSendButton = document.querySelector('#wsSendButton');
   const logout = document.querySelector('#logout');
   const login = document.querySelector('#login');
 
@@ -50,6 +51,16 @@
     };
     ws.onclose = function() {
       showMessage('WebSocket connection closed');
+      ws = null;
     };
   };
+
+  wsSendButton.onclick = function() {
+    if (!ws) {
+      showMessage('No WebSocket connection');
+      return;
+    }
+    ws.send('Hello World!');
+    showMessage('Sent "Hello World!"');
+  };
 })();

examples/express-session-parse/public/index.html

@@ -15,6 +15,9 @@ <h1>Choose an action.</h1>
     <button id="wsButton" type="button" title="Open WebSocket connection">
       Open WebSocket connection
     </button>
+    <button id="wsSendButton" type="button" title="Send WebSocket message">
+      Send WebSocket message
+    </button>
     <pre id="messages" style="height: 400px; overflow: scroll"></pre>
     <script src="app.js"></script>
   </body>