ws is a simple to use, blazing fast, and thoroughly tested WebSocket client andserver implementation.
Passes the quite extensive Autobahn test suite: server,client.
Note: This module does not work in the browser. The client in the docs is areference to a back end with the role of a client in the WebSocketcommunication. Browser clients must use the nativeWebSocket
object. To make the same code work seamlessly on Node.js and the browser, youcan use one of the many wrappers available on npm, likeisomorphic-ws.
SE7ENKILLS Strasbourg #10 5x5, 1/10, demiragedusk. SE7ENKILLS London #11 PUB, 1/20. (csgo13.se7en.ws:27023), N/A, N/A. Querying Server Data.
Table of Contents
- Installing
- Usage examples
- FAQ
Protocol support
- HyBi drafts 07-12 (Use the option
protocolVersion: 8
) - HyBi drafts 13-17 (Current default, alternatively option
protocolVersion: 13
)
Installing
Opt-in for performance and spec compliance
There are 2 optional modules that can be installed along side with the wsmodule. These modules are binary addons which improve certain operations.Prebuilt binaries are available for the most popular platforms so you don'tnecessarily need to have a C++ compiler installed on your machine.
npm install --save-optional bufferutil
: Allows to efficiently performoperations such as masking and unmasking the data payload of the WebSocketframes.npm install --save-optional utf-8-validate
: Allows to efficiently check if amessage contains valid UTF-8 as required by the spec.
API docs
See /doc/ws.md
for Node.js-like docs for the ws classes.
WebSocket compression
ws supports the permessage-deflate extension which enablesthe client and server to negotiate a compression algorithm and its parameters,and then selectively apply it to the data payloads of each WebSocket message.
The extension is disabled by default on the server and enabled by default on theclient. It adds a significant overhead in terms of performance and memoryconsumption so we suggest to enable it only if it is really needed.
Note that Node.js has a variety of issues with high-performance compression,where increased concurrency, especially on Linux, can lead to catastrophicmemory fragmentation and slow performance. If you intend to usepermessage-deflate in production, it is worthwhile to set up a testrepresentative of your workload and ensure Node.js/zlib will handle it withacceptable performance and memory usage.
Tuning of permessage-deflate can be done via the options defined below. You canalso use zlibDeflateOptions
and zlibInflateOptions
, which is passed directlyinto the creation of raw deflate/inflate streams.
See the docs for more options.
The client will only use the extension if it is supported and enabled on theserver. To always disable the extension on the client set theperMessageDeflate
option to false
.
Usage examples
Sending and receiving text data
Sending binary data
Simple server
External HTTP/S server
Multiple servers sharing a single HTTP/S server
Server broadcast
echo.websocket.org demo
Other examples
For a full example with a browser client communicating with a ws server, see theexamples folder.
Otherwise, see the test cases.
FAQ
How to get the IP address of the client?
The remote IP address can be obtained from the raw socket.
When the server runs behind a proxy like NGINX, the de-facto standard is to usethe X-Forwarded-For
header.
How to detect and close broken connections?
Sometimes the link between the server and the client can be interrupted in a waythat keeps both the server and the client unaware of the broken state of theconnection (e.g. when pulling the cord).
In these cases ping messages can be used as a means to verify that the remoteendpoint is still responsive.
Pong messages are automatically sent in response to ping messages as required bythe spec.
Just like the server example above your clients might as well lose connectionwithout knowing it. You might want to add a ping listener on your clients toprevent that. A simple implementation would be:
![Server 5x5 wsop Server 5x5 wsop](https://1.bp.blogspot.com/-PQrGs5Dlgbo/V6hIK2WWeVI/AAAAAAAAAXA/9aiikqtyf0otriZC7E_N1CVBpJpaE82KwCLcB/s640/Bild2.jpg)
How to connect via a proxy?
Use a custom http.Agent
implementation like https-proxy-agent orsocks-proxy-agent.
Changelog
We're using the GitHub releases for changelog entries.