[feature] Support Windows named pipes (websockets#2079)

Document how to connect to a named pipe endpoint and the limitations.

Refs: websockets#1808
Refs: websockets#2075

doc/ws.md

@@ -18,7 +18,7 @@
 - [Class: WebSocket](#class-websocket)
  - [Ready state constants](#ready-state-constants)
  - [new WebSocket(address[, protocols][, options])](#new-websocketaddress-protocols-options)
- - [UNIX Domain Sockets](#unix-domain-sockets)
+ - [IPC connections](#ipc-connections)
  - [Event: 'close'](#event-close-1)
  - [Event: 'error'](#event-error-1)
  - [Event: 'message'](#event-message)
@@ -323,17 +323,27 @@ context takeover.
 
 Create a new WebSocket instance.
 
-#### UNIX Domain Sockets
+#### IPC connections
 
-`ws` supports making requests to UNIX domain sockets. To make one, use the
-following URL form:
+`ws` supports IPC connections. To connect to an IPC endpoint, use the following
+URL form:
 
-```
-ws+unix:/absolute/path/to/uds_socket:/pathname?search_params
-```
+- On Unices
+
+ ```
+ ws+unix:/absolute/path/to/uds_socket:/pathname?search_params
+ ```
+
+- On Windows
+
+ ```
+ ws+unix:\\.\pipe\pipe_name:/pathname?search_params
+ ```
 
-The character `:` is the separator between the socket path and the URL path. If
-the URL path is omitted
+The character `:` is the separator between the IPC path (the Unix domain socket
+path or the Windows named pipe) and the URL path. The IPC path must not include
+the characters `:` and `?`, otherwise the URL is incorrectly parsed. If the URL
+path is omitted
 
 ```
 ws+unix:/absolute/path/to/uds_socket

lib/websocket.js

@@ -677,13 +677,13 @@ function initAsClient(websocket, address, protocols, options) {
  }
 
  const isSecure = parsedUrl.protocol === 'wss:';
- const isUnixSocket = parsedUrl.protocol === 'ws+unix:';
+ const isIpcUrl = parsedUrl.protocol === 'ws+unix:';
  let invalidUrlMessage;
 
- if (parsedUrl.protocol !== 'ws:' && !isSecure && !isUnixSocket) {
+ if (parsedUrl.protocol !== 'ws:' && !isSecure && !isIpcUrl) {
  invalidUrlMessage =
  'The URL\'s protocol must be one of "ws:", "wss:", or "ws+unix:"';
- } else if (isUnixSocket && !parsedUrl.pathname) {
+ } else if (isIpcUrl && !parsedUrl.pathname) {
  invalidUrlMessage = "The URL's pathname is empty";
  } else if (parsedUrl.hash) {
  invalidUrlMessage = 'The URL contains a fragment identifier';
@@ -760,7 +760,7 @@ function initAsClient(websocket, address, protocols, options) {
  opts.auth = `${parsedUrl.username}:${parsedUrl.password}`;
  }
 
- if (isUnixSocket) {
+ if (isIpcUrl) {
  const parts = opts.path.split(':');
 
  opts.socketPath = parts[0];
@@ -771,9 +771,9 @@ function initAsClient(websocket, address, protocols, options) {
 
  if (opts.followRedirects) {
  if (websocket._redirects === 0) {
- websocket._originalUnixSocket = isUnixSocket;
+ websocket._originalIpc = isIpcUrl;
  websocket._originalSecure = isSecure;
- websocket._originalHostOrSocketPath = isUnixSocket
+ websocket._originalHostOrSocketPath = isIpcUrl
  ? opts.socketPath
  : parsedUrl.host;
 
@@ -791,11 +791,11 @@ function initAsClient(websocket, address, protocols, options) {
  }
  }
  } else if (websocket.listenerCount('redirect') === 0) {
- const isSameHost = isUnixSocket
- ? websocket._originalUnixSocket
+ const isSameHost = isIpcUrl
+ ? websocket._originalIpc
  ? opts.socketPath === websocket._originalHostOrSocketPath
  : false
- : websocket._originalUnixSocket
+ : websocket._originalIpc
  ? false
  : parsedUrl.host === websocket._originalHostOrSocketPath;
 

test/websocket-server.test.js

@@ -178,22 +178,16 @@ describe('WebSocketServer', () => {
  });
  });
 
- it('uses a precreated http server listening on unix socket', function (done) {
- //
- // Skip this test on Windows. The URL parser:
- //
- // - Throws an error if the named pipe uses backward slashes.
- // - Incorrectly parses the path if the named pipe uses forward slashes.
- //
- if (process.platform === 'win32') return this.skip();
+ it('uses a precreated http server listening on IPC', (done) => {
+ const randomString = crypto.randomBytes(16).toString('hex');
+ const ipcPath =
+ process.platform === 'win32'
+ ? `\\\\.\\pipe\\ws-pipe-${randomString}`
+ : path.join(os.tmpdir(), `ws-${randomString}.sock`);
 
  const server = http.createServer();
- const sockPath = path.join(
- os.tmpdir(),
- `ws.${crypto.randomBytes(16).toString('hex')}.sock`
- );
 
- server.listen(sockPath, () => {
+ server.listen(ipcPath, () => {
  const wss = new WebSocket.Server({ server });
 
  wss.on('connection', (ws, req) => {
@@ -210,8 +204,8 @@ describe('WebSocketServer', () => {
  }
  });
 
- const ws = new WebSocket(`ws+unix:${sockPath}:/foo?bar=bar`);
- ws.on('open', () => new WebSocket(`ws+unix:${sockPath}`));
+ const ws = new WebSocket(`ws+unix:${ipcPath}:/foo?bar=bar`);
+ ws.on('open', () => new WebSocket(`ws+unix:${ipcPath}`));
  });
  });
  });

test/websocket.test.js

@@ -1536,19 +1536,18 @@ describe('WebSocket', () => {
  });
  });
 
- it('drops the Authorization, Cookie and Host headers (2/4)', function (done) {
- if (process.platform === 'win32') return this.skip();
-
+ it('drops the Authorization, Cookie and Host headers (2/4)', (done) => {
  // Test the `ws:` to `ws+unix:` case.
 
- const socketPath = path.join(
- os.tmpdir(),
- `ws.${crypto.randomBytes(16).toString('hex')}.sock`
- );
+ const randomString = crypto.randomBytes(16).toString('hex');
+ const ipcPath =
+ process.platform === 'win32'
+ ? `\\\\.\\pipe\\ws-pipe-${randomString}`
+ : path.join(os.tmpdir(), `ws-${randomString}.sock`);
 
  server.once('upgrade', (req, socket) => {
  socket.end(
- `HTTP/1.1 302 Found\r\nLocation: ws+unix:${socketPath}\r\n\r\n`
+ `HTTP/1.1 302 Found\r\nLocation: ws+unix:${ipcPath}\r\n\r\n`
  );
  });
 
@@ -1563,7 +1562,7 @@ describe('WebSocket', () => {
  ws.close();
  });
 
- redirectedServer.listen(socketPath, () => {
+ redirectedServer.listen(ipcPath, () => {
  const headers = {
  authorization: 'Basic Zm9vOmJhcg==',
  cookie: 'foo=bar',
@@ -1589,34 +1588,42 @@ describe('WebSocket', () => {
 
  ws.on('close', (code) => {
  assert.strictEqual(code, 1005);
- assert.strictEqual(ws.url, `ws+unix:${socketPath}`);
+ assert.strictEqual(ws.url, `ws+unix:${ipcPath}`);
  assert.strictEqual(ws._redirects, 1);
 
  redirectedServer.close(done);
  });
  });
  });
 
- it('drops the Authorization, Cookie and Host headers (3/4)', function (done) {
- if (process.platform === 'win32') return this.skip();
-
+ it('drops the Authorization, Cookie and Host headers (3/4)', (done) => {
  // Test the `ws+unix:` to `ws+unix:` case.
 
- const redirectingServerSocketPath = path.join(
- os.tmpdir(),
- `ws.${crypto.randomBytes(16).toString('hex')}.sock`
- );
- const redirectedServerSocketPath = path.join(
- os.tmpdir(),
- `ws.${crypto.randomBytes(16).toString('hex')}.sock`
- );
+ const randomString1 = crypto.randomBytes(16).toString('hex');
+ const randomString2 = crypto.randomBytes(16).toString('hex');
+ let redirectingServerIpcPath;
+ let redirectedServerIpcPath;
+
+ if (process.platform === 'win32') {
+ redirectingServerIpcPath = `\\\\.\\pipe\\ws-pipe-${randomString1}`;
+ redirectedServerIpcPath = `\\\\.\\pipe\\ws-pipe-${randomString2}`;
+ } else {
+ redirectingServerIpcPath = path.join(
+ os.tmpdir(),
+ `ws-${randomString1}.sock`
+ );
+ redirectedServerIpcPath = path.join(
+ os.tmpdir(),
+ `ws-${randomString2}.sock`
+ );
+ }
 
  const redirectingServer = http.createServer();
 
  redirectingServer.on('upgrade', (req, socket) => {
  socket.end(
  'HTTP/1.1 302 Found\r\n' +
- `Location: ws+unix:${redirectedServerSocketPath}\r\n\r\n`
+ `Location: ws+unix:${redirectedServerIpcPath}\r\n\r\n`
  );
  });
 
@@ -1631,8 +1638,8 @@ describe('WebSocket', () => {
  ws.close();
  });
 
- redirectingServer.listen(redirectingServerSocketPath, listening);
- redirectedServer.listen(redirectedServerSocketPath, listening);
+ redirectingServer.listen(redirectingServerIpcPath, listening);
+ redirectedServer.listen(redirectedServerIpcPath, listening);
 
  let callCount = 0;
 
@@ -1645,7 +1652,7 @@ describe('WebSocket', () => {
  host: 'foo'
  };
 
- const ws = new WebSocket(`ws+unix:${redirectingServerSocketPath}`, {
+ const ws = new WebSocket(`ws+unix:${redirectingServerIpcPath}`, {
  followRedirects: true,
  headers
  });
@@ -1664,10 +1671,7 @@ describe('WebSocket', () => {
 
  ws.on('close', (code) => {
  assert.strictEqual(code, 1005);
- assert.strictEqual(
- ws.url,
- `ws+unix:${redirectedServerSocketPath}`
- );
+ assert.strictEqual(ws.url, `ws+unix:${redirectedServerIpcPath}`);
  assert.strictEqual(ws._redirects, 1);
 
  redirectingServer.close();
@@ -1676,9 +1680,7 @@ describe('WebSocket', () => {
  }
  });
 
- it('drops the Authorization, Cookie and Host headers (4/4)', function (done) {
- if (process.platform === 'win32') return this.skip();
-
+ it('drops the Authorization, Cookie and Host headers (4/4)', (done) => {
  // Test the `ws+unix:` to `ws:` case.
 
  const redirectingServer = http.createServer();
@@ -1696,12 +1698,13 @@ describe('WebSocket', () => {
  ws.close();
  });
 
- const socketPath = path.join(
- os.tmpdir(),
- `ws.${crypto.randomBytes(16).toString('hex')}.sock`
- );
+ const randomString = crypto.randomBytes(16).toString('hex');
+ const ipcPath =
+ process.platform === 'win32'
+ ? `\\\\.\\pipe\\ws-pipe-${randomString}`
+ : path.join(os.tmpdir(), `ws-${randomString}.sock`);
 
- redirectingServer.listen(socketPath, listening);
+ redirectingServer.listen(ipcPath, listening);
  redirectedServer.listen(0, listening);
 
  let callCount = 0;
@@ -1723,7 +1726,7 @@ describe('WebSocket', () => {
  host: 'foo'
  };
 
- const ws = new WebSocket(`ws+unix:${socketPath}`, {
+ const ws = new WebSocket(`ws+unix:${ipcPath}`, {
  followRedirects: true,
  headers
  });