uWebSockets.js
The uWebSockets.js generally performs better than the default WebSockets implementation, and is capable of handling more connections while using less resources. This transport is recommended for production environments.
The underlying library uNetworking/uWebSockets.js is a C++ implementation of WebSockets. It benchmarks at least 10x Socket.IO and 8.5x Fastify. It also forms the core of Bun, and is the fastest standards-compliant web server in the TechEmpower (not endorsed) benchmarks.
Installation
npm install --save @colyseus/uwebsockets-transport@^0.18.0To use the express: option with this transport, also install the optional uwebsockets-express compatibility layer (^2.0.1 for Express v5, ^1.4.1 for Express v4):
npm install --save uwebsockets-expressUsage
import { uWebSocketsTransport } from "@colyseus/uwebsockets-transport"
import { defineServer } from "colyseus";
const server = defineServer({
// ...
transport: new uWebSocketsTransport({
/* transport options */
}, {
/* ssl options */
}),
//
// bind express routes
//
express: (app) => {
app.get("/hello", (req, res) => {
res.json({ hello: "world!" });
});
},
// ...
});Transport options
options.maxPayloadLength
Maximum length of received message. If a client tries to send you a message larger than this, the connection is immediately closed.
Default: 4096
options.idleTimeout
Maximum amount of seconds that may pass without sending or getting a message. Connection is closed if this timeout passes. Resolution (granularity) for timeouts are typically 4 seconds, rounded to closest. Disable by using 0.
Default: 120
options.sendPingsAutomatically
Whether or not we should automatically send pings to uphold a stable connection given idleTimeout.
Default: true
options.compression
What permessage-deflate compression to use. uWS.DISABLED, uWS.SHARED_COMPRESSOR or any of the uWS.DEDICATED_COMPRESSOR_xxxKB.
Default: uWS.DISABLED
options.maxBackpressure
Maximum length of allowed backpressure per socket when publishing or sending messages. Slow receivers with too high backpressure will be skipped until they catch up or timeout.
Default: 1024 * 1024
options.beforeUpgrade
Runs before the WebSocket handshake, while the connection is still a plain HTTP request.
beforeUpgrade?: (request: Request, context: AuthContext) => Response | void | Promise<Response | void>;The callback receives the upgrade request as a standard
Request, and the
same context object onAuth receives: token,
headers, and ip. The context is read-only here, and changes to it do not
carry over to onAuth.
Return a
Response to answer
the request without upgrading, or nothing to accept the handshake. The callback
may be async, and the handshake waits for it to resolve.
A callback that throws answers 500 Internal Server Error, and the connection is
not upgraded.
SSL options
options.key_file_name
Path to the SSL key file. (for SSL termination through the Node.js application.)
options.cert_file_name
Path to the SSL certificate file. (for SSL termination through the Node.js application.)
options.passphrase
Password for the SSL file. (for SSL termination through the Node.js application.)
Overriding the uWebSockets.js version
The @colyseus/uwebsockets-transport package ships with a specific version of uWebSockets.js as a dependency. You may need a different version, for example to pick up a bug fix or to match a specific platform requirement. In that case, override it directly from your project’s package.json.
Use the overrides field:
{
"overrides": {
"uWebSockets.js": "uNetworking/uWebSockets.js#v20.51.0"
}
}After updating package.json, remove your node_modules directory and reinstall dependencies for the override to take effect.
Check the uWebSockets.js releases for available versions.
Troubleshooting
431 Request Header Fields Too Large
The maximum header size is 4 KiB by default. If you need to increase the maximum header size, you can use the UWS_HTTP_MAX_HEADERS_SIZE environment variable:
UWS_HTTP_MAX_HEADERS_SIZE=32768