Ultimate WS

The Ultimate WebSocket server. Ultimate WS is an extremely fast, drop-in replacement for ws module, with support for Ultimate Express http upgrades. It uses uWebSockets.js under the hood.

It's useful when:
- You want same API as ws module, but the speed of uWebSockets.js
- You want to convert your Express app with ws to use Ultimate Express instead


Installation

1.
``bash
npm install ultimate-ws
`
2. Replace ws with ultimate-ws in your code
3. Check compatibility and differences below

Performance

Echo test using artillery (duration: 20, arrivalRate: 10000):

| Module | Send rate | Mean Session length | Median Session length |
|-------------------|---------------|---------------------|-----------------------|
| ws | 2709/sec | 2535ms | 127ms |
| ultimate-ws | 10046/sec | 45ms | 12ms |

Usage

$3

Since you don't create http server for ws or express, you can't really use server.on("upgrade", ...) to upgrade to Ultimate WS. Instead, you can pass Ultimate Express or uWS app to WebSocketServer as option. So instead of doing this:
`js
const http = require("http");
const express = require("express");
const ws = require("ws");

const app = express();
const wsServer = new ws.WebSocketServer({ noServer: true });

app.get("/", (_, res) => res.send("Hello, world!"));

const server = http.createServer(app);
server.on("upgrade", (request, socket, head) => {
const { pathname } = url.parse(request.url);
if(pathname !== "/wspath") return request.socket.destroy();

wsServer.handleUpgrade(request, socket, head, (ws) => {
wsServer.emit("connection", ws, request);
});
});

server.listen(3000);
`
You need to do this:
`js
const express = require("ultimate-express");
const app = express();
const { WebSocketServer } = require("ultimate-ws");

app.get("/", (_, res) => res.send("Hello, world!"));

const wsServer = new WebSocketServer({ server: app, path: "/wspath" }); // path is optional

// your usual ws server code ...

app.listen(3000);
`

Ultimate Express is fully compatible, much faster express implementation.

$3

If you want to use Ultimate WS without any existing http server, you can do this:
`js
const { WebSocketServer } = require("ultimate-ws");

const wsServer = new WebSocketServer({ port: 3000 });

// your usual ws server code ...
wsServer.on("connection", (ws) => {
ws.on("message", (message) => {
ws.send(message);
});
});
`

$3

You can also pass existing uWS server to WebSocketServer:
`js
const { WebSocketServer } = require("ultimate-ws");
const uws = require("uWebSockets.js");

const server = uws.App();
const wsServer = new WebSocketServer({ server: server });

// your usual ws server code ...

server.listen(3000);
`

HTTPS

Ultimate WS supports HTTPS. You can pass uwsOptions to WebSocketServer to configure it:
`js
const { WebSocketServer } = require("ultimate-ws");

const wsServer = new WebSocketServer({
port: 3000,
uwsOptions: {
// https://unetworking.github.io/uWebSockets.js/generated/interfaces/AppOptions.html
key_file_name: "path/to/key.pem",
cert_file_name: "path/to/cert.pem",
}
});
`

Handling requests before connection

Instead of this:

`js
const http = require("http");
const express = require("express");
const ws = require("ws");

const app = express();
const wsServer = new ws.WebSocketServer({ noServer: true, path: "/wspath" });

app.get("/", (_, res) => res.send("Hello, world!"));

const server = http.createServer(app);
server.on("upgrade", async (request, socket, head) => {
// your auth logic
const user = await getUserFromDatabase(request.headers['authorization']);
if(!user) return socket.destroy();

wsServer.handleUpgrade(request, socket, head, (ws) => {
ws.user = user;
wsServer.emit("connection", ws, request);
});
});

server.listen(3000);
`

You should do this:
`js
const { WebSocketServer } = require("ultimate-ws");
const express = require("ultimate-express");

const app = express();

const wsServer = new WebSocketServer({
server: app,
path: "/wspath",
handleUpgrade: async (request) => {
// your auth logic
const user = await getUserFromDatabase(request.headers['authorization']);
if(!user) {
// request has req and res properties
// which are instances of uws.HttpRequest and uws.HttpResponse
request.res.cork(() => {
request.res.writeStatus("401 Unauthorized");
request.res.end();
});
return false;
}

return (ws, request) => {
ws.user = user;
wsServer.emit("connection", ws, request);
}
}
});

app.get("/", (_, res) => res.send("Hello, world!"));

app.listen(3000);
`

- if handleUpgrade returns a function, it will be called with the new WebSocket instance and original request. "connection" will not be emitted automatically.
- if it returns false, the connection will not be upgraded. It's your responsibility to destroy the socket.
- if it returns nothing or anything else, the connection will be handled as usual, and "connection" event will be emitted.
- By default (handleUpgrade: undefined), the connection will be handled as usual, and "connection" event will be emitted.



Compatibility

All commonly used ws features are supported. Almost all ws servers should work, as it's built with maximum compatibility in mind.
Please refer to ws module documentation for API reference.
Below is the list of supported features and their compatibility:

✅ - Full support (all features and options are supported)
🚧 - Partial support (some features are not supported)
❌ - Not supported

#### WebSocket

- ✅ WebSocket
- ✅ WebSocket.Server
- ✅ WebSocket.WebSocket
- ✅ WebSocket.WebSocketServer
- ✅ WebSocket.CONNECTING
- ✅ WebSocket.OPEN
- ✅ WebSocket.CLOSING
- ✅ WebSocket.CLOSED
- ✅ WebSocket.createWebSocketStream

$3

#### Server options

ws options:

- ✅ autoPong (maps to uWS sendPingsAutomatically, default true)
- ✅ allowSynchronousEvents (may lower performance when false, default true)
- ✅ clientTracking
- ✅ handleProtocols
- ✅ host
- ✅ maxPayload (default 100mb)
- ✅ path
- 🚧 perMessageDeflate - pass true for DEDICATED_COMPRESSOR_4KB | DEDICATED_DECOMPRESSOR or your own CompressOptions number. Options are not supported and if this is an object it will be treated as true.
- ✅ port
- ✅ server
- ✅ verifyClient
- ✅ WebSocket
- ✅ callback
- ❌ noServer - see examples above for alternatives
- ❌ skipUTF8Validation - uWS always validates UTF-8 when message is a string
- ❌ backlog

uWS options (additional options that ws doesn't have):

- ✅ maxBackpressure (default maxPayload)
- ✅ idleTimeout (default 120)
- ✅ maxLifetime (default 0)
- ✅ closeOnBackpressureLimit (default false)

#### Server events

- ✅ close
- ✅ connection
- ✅ headers
- ✅ listening
- ✅ error - µWS never throws errors
- ✅ wsClientError - µWS never throws errors

#### Server properties

- ✅ server.address()
- ✅ server.clients
- ✅ server.close(callback)
- ✅ server.shouldHandle(request)
- ❌ server.handleUpgrade(request, socket, head, callback) - see examples above for alternatives

$3

This category only describes server clients. Client-side (new ws.WebSocket()) just uses original ws` module, and therefore supports everything.

#### Client events

- ✅ close
- ✅ message
- ✅ ping
- ✅ pong
- ✅ dropped - this event only exists in Ultimate WS for handling dropped messages
- ✅ drain - this event only exists in Ultimate WS for handling backpressure draining
- ✅ error - µWS never throws errors

#### Client properties

- ✅ client.addEventListener(type, listener, options)
- ✅ client.binaryType
- ✅ client.bufferedAmount
- ✅ client.close(code, reason)
- ✅ client.isPaused
- ✅ client.extensions
- ✅ client.onclose
- ✅ client.onerror
- ✅ client.onmessage
- ✅ client.onopen
- ✅ client.pause()
- 🚧 client.ping()
- ❌ client.pong(data, mask, callback) - pongs are handled automatically, method does nothing
- ✅ client.protocol
- ✅ client.resume()
- ✅ client.readyState
- ✅ client.removeEventListener(type, listener)
- 🚧 client.send(data, options, callback) - returns 1 for success, 2 for dropped due to backpressure limit, 0 for built up backpressure that will drain over time. Callback will only get error if it returns 2.
- - ✅ options.binary
- - ✅ options.compress
- - ❌ options.fin
- - ❌ options.mask
- ✅ client.terminate()