[api] Add WebSocketServer.prototype.address() (#1294)

doc/ws.md

@@ -124,6 +124,14 @@ Emitted when the underlying server has been bound.
 A set that stores all connected clients. Please note that this property is only
 added when the `clientTracking` is truthy.
 
+### server.address()
+
+Returns an object with `port`, `family`, and `address` properties specifying
+the bound address, the address family name, and port of the server as reported
+by the operating system if listening on an IP socket.
+If the server is listening on a pipe or UNIX domain socket, the name is
+returned as a string.
+
 ### server.close([callback])
 
 Close the server and terminate all clients, calls callback when done.

lib/websocket-server.js

@@ -90,6 +90,24 @@ class WebSocketServer extends EventEmitter {
     this.options = options;
   }
 
+  /**
+   * Returns the bound address, the address family name, and port of the server
+   * as reported by the operating system if listening on an IP socket.
+   * If the server is listening on a pipe or UNIX domain socket, the name is
+   * returned as a string.
+   *
+   * @return {(Object|String|null)} The address of the server
+   * @public
+   */
+  address () {
+    if (this.options.noServer) {
+      throw new Error('The server is operating in "noServer" mode');
+    }
+
+    if (!this._server) return null;
+    return this._server.address();
+  }
+
   /**
    * Close the server.
    *

test/websocket-server.test.js

@@ -137,6 +137,34 @@ describe('WebSocketServer', function () {
     });
   });
 
+  describe('#address', function () {
+    it('returns the address of the server', function (done) {
+      const wss = new WebSocket.Server({ port: 0 }, () => {
+        const addr = wss.address();
+
+        assert.deepStrictEqual(addr, wss._server.address());
+        wss.close(done);
+      });
+    });
+
+    it('throws an error when operating in "noServer" mode', function () {
+      const wss = new WebSocket.Server({ noServer: true });
+
+      assert.throws(() => {
+        wss.address();
+      }, /^Error: The server is operating in "noServer" mode$/);
+    });
+
+    it('returns `null` if called after close', function (done) {
+      const wss = new WebSocket.Server({ port: 0 }, () => {
+        wss.close(() => {
+          assert.strictEqual(wss.address(), null);
+          done();
+        });
+      });
+    });
+  });
+
   describe('#close', function () {
     it('does not thrown when called twice', function (done) {
       const wss = new WebSocket.Server({ port: 0 }, () => {