\n\n\n## Important Notes\n\n* This repository is a fork of [uWebSockets v0.14](https://github.com/uNetworking/uWebSockets/tree/v0.14) therefore has two licence [MIT](https://github.com/ClusterWS/uWS/blob/master/LICENSE) and [ZLIB](https://github.com/ClusterWS/uWS/blob/master/src/LICENSE)\n* Consider using latest [uWebSockets](https://github.com/uNetworking/uWebSockets.js) version instead\n* You can support me through [Patreon](https://www.patreon.com/clusterws) and [PayPal](https://www.paypal.me/goriunov)\n\n## Supported Node Versions\n\n| CWS Version | Node 10 | Node 11 | Node 12 | Node 13 | Node 14 |\n|--------------|----------|---------|------------------|-----------|---------|\n| 3.0.0 | >=10.0 | X | >=12.16 | >=13.9 | >=14.5 |\n| 2.0.0 | >=10.0 | X | >=12.16 | >=13.9 | X |\n| 1.6.0 | >=10.0 | >=11.0 | >=12.0 & <12.16 | >=13.9 | X |\n\n## Documentation\n\n#### Useful links\n\n* [Examples](./examples)\n* [Changelog](./CHANGELOG.md)\n\n#### Table of Contents\n\n* [Installation](#user-content-installation)\n* [Websocket Client](#user-content-websocket-client)\n* [Websocket Server](#user-content-websocket-server)\n* [Secure WebSocket](#user-content-secure-websocket)\n* [Handle App Level Ping In Browser (example)](#user-content-handle-app-level-ping-in-browser-example)\n\n### Installation\n\n```js\nnpm i @clusterws/cws\n```\n\n### Websocket Client\n\nTypings: [dist/client.d.ts](https://github.com/ClusterWS/cWS/blob/master/dist/client.d.ts)\n\nImport cws WebSocket:\n```js\nconst { WebSocket } = require('@clusterws/cws');\n```\n\nConnect to WebSocket server:\n```js\nconst socket = new WebSocket(/* ws server endpoint **/);\n```\n\nEvent on `open` is triggered when server accepts connection and this connection is ready to perform other actions:\n```js\nsocket.on('open', () => { });\n// or like browser interface\nsocket.onopen = () => { };\n```\n\nEvent on `error` is triggered if there is an error with the connection:\n```js\nsocket.on('error', (err) => { });\n// or like browser interface\nsocket.onerror = (err) => { };\n```\n\nEvent on `close` is triggered when connection has been closed:\n```js\n// code: number and reason: string are optional\nsocket.on('close', (code, reason) => { });\n// or like browser interface\nsocket.onclose = (code, reason) => { };\n```\n\nEvent on `message` is triggered when client receives message(s):\n```js\n// receives string or binary\n\nsocket.on('message', (message) => { });\n// or like browser interface\nsocket.onmessage = (message) => { };\n```\n\nEvent `ping` is triggered when other side sends ping to check if connection still active:\n```js\nsocket.on('ping', () => { });\n```\n\nEvent `pong` is triggered after `ping` has been sent and it received back conformation:\n```js\nsocket.on('pong', () => { })\n```\n\nTo send message use `send` function:\n```js\n// send accepts string or binary\n// will automatically identify type\nsocket.send(msg);\n\n// will overwrite/specify message type to string (does not transform data to specified type)\nsocket.send(msg, { binary: false });\n\n// will overwrite/specify message type to binary (does not transform data to specified type)\nsocket.send(msg, { binary: true });\n\n// will call callback after message sent or errored\nsocket.send(msg, null, (err) => { });\n```\n\nTo close connection you can use `close` or `terminate` methods:\n```js\n// clean close code and reason are optional\nsocket.close(code, reason);\n// destroy socket \nsocket.terminate()\n```\n\nUse `ping` function to manually send ping:\n```js\nsocket.ping();\n// now just wait for `pong` event\n```\n\nTo get current socket ready state can use `readyState` getter:\n```js\nsocket.readyState; // -> OPEN (1) or CLOSED (3)\n\n// check if socket open can be done by\nif(socket.readyState === socket.OPEN) {}\n\n// check if socket closed can be done by\nif(socket.readyState === socket.CLOSED) {}\n```\n\nTo get addresses use `_socket` getter:\n```js\nsocket._socket;\n\n// Returns some thing like (all fields could be undefined):\n// {\n// remotePort,\n// remoteAddress,\n// remoteFamily\n// }\n```\n\n**For more information check typings (`*.d.ts`) files in [dist](https://github.com/ClusterWS/cWS/blob/master/dist) folder**\n\n### Websocket Server\n\nTypings: [dist/server.d.ts](https://github.com/ClusterWS/cWS/blob/master/dist/server.d.ts)\n\nImport cws WebSocket:\n```js\nconst { WebSocket } = require('@clusterws/cws');\n```\n\nCreate WebSocket server:\n```js\nconst wsServer = new WebSocket.Server({ \n /**\n * port?: number (creates server and listens on provided port)\n * host?: string (provide host if necessary with port)\n * path?: string (url at which accept ws connections)\n * server?: server (provide already existing server)\n * noDelay?: boolean (set socket no delay)\n * noServer?: boolean (use this when upgrade done outside of cws)\n * maxPayload?: number \n * perMessageDeflate?: boolean | { serverNoContextTakeover: boolean;}\n * verifyClient?: (info: ConnectionInfo, next: VerifyClientNext) => void (use to allow or decline connections)\n **/ \n }, () => {\n // callback called when server is ready\n // is not called when `noServer: true` or `server` is provided\n // from outside\n});\n```\n\nEvent on `connection` is triggered when new client is connected to the server:\n```js\n// `ws` is websocket client all available options \n// can be found in `Websocket Client` section above\n// `req` is http upgrade request\nwsServer.on('connection', (ws, req) => {})\n```\n\nEvent on `error` is triggered when server has some issues and `noServer` is `false:`\n```js\n// on error event will NOT include httpServer errors IF\n// server was passed under server parameter { server: httpServer },\n// you can register on 'error' listener directly on passed server\nwsServer.on('error', (err) => { })\n```\n\nEvent on `close` is triggered after you call `wsServer.close()` function, if `cb` is provided both `cb` and on `close` listener will be triggered:\n```js\nwsServer.on('close', () => { })\n```\n\nTo get all connected clients use `clients` getter:\n```js\nwsServer.clients;\n\n// loop thought all clients:\nwsServer.clients.forEach((ws) => { });\n\n// get number of clients:\nwsServer.clients.length;\n```\n\nTo send message to all connected clients use `broadcast` method:\n```js\n// broadcast string\nwsServer.broadcast(message);\n\n// broadcast binary\nwsServer.broadcast(message, { binary: true });\n```\n\ncWS supports auto ping with `startAutoPing` function:\n```js\nwsServer.startAutoPing(interval, appLevel);\n\n// send ping to each client every 10s and destroy client if no pong received \nwsServer.startAutoPing(10000);\n\n// pass true as second parameter to run app level ping\n// this is mainly used for browser to track pings at client level\n// as they do not expose on ping listener \n// look for browser client side implementation at the bottom\n// `Handle App Level Ping In Browser (example)`\nwsServer.startAutoPing(10000, true);\n```\n\nTo stop server use `close` function:\n```js\nwsServer.close(() => {\n // triggered after server has been stopped\n})\n```\n\n`handleUpgrade` is function which is commonly used together with `noServer` (same as `ws` module)\n```js\nconst wss = new WebSocket.Server({ noServer: true });\nconst server = http.createServer();\n\nwss.on('connection', (ws, req) => { })\n\nserver.on('upgrade', (request, socket, head) => {\n wss.handleUpgrade(request, socket, head, (ws) => {\n wss.emit('connection', ws, request);\n });\n});\n```\n\n**For more information check typings (`*.d.ts`) files in [dist](https://github.com/ClusterWS/cWS/blob/master/dist) folder**\n\n### Secure WebSocket\nYou can use `wss://` with `cws` by providing `https` server to `cws` and setting `secureProtocol` on https options:\n\n```js\nconst { readFileSync } = require('fs');\nconst { createServer } = require('https');\nconst { WebSocket, secureProtocol } = require('@clusterws/cws');\n\nconst options = {\n key: readFileSync(/** path to key */),\n cert: readFileSync(/** path to certificate */),\n secureProtocol\n // ...other Node HTTPS options\n};\n\nconst server = createServer(options);\nconst wsServer = new WebSocket.Server({ server });\n// your secure ws is ready (do your usual things)\n\nserver.listen(port, () => {\n console.log('Server is running');\n})\n```\n\n**For more detail example check [examples](https://github.com/ClusterWS/cWS/blob/master/examples) folder**\n\n### Handle App Level Ping In Browser (example)\nHandling custom App level `ping`, `pong` from the client side which does not have `onping` and `onpong` listeners available such as browsers.\n\n**Note** if all your clients have `onping` and `onpong` listeners do not send `appLevelPing` ping from the server. If you enable appLevelPing you will need to implement similar handler for every client library which connects to the server.\n\n```js\nconst PING = 57;\nconst PONG = new Uint8Array(['A'.charCodeAt()]);\n\nsocket.binaryType = 'arraybuffer';\n\nsocket.onmessage = function (message) {\n // note actually sent message in\n // browser default WebSocket is under `message.data`\n\n // check if message is not string \n if (typeof message.data !== 'string') {\n // transform it to Uint8Array\n let buffer = new Uint8Array(message.data);\n\n // Check if it is actually ping from the server\n if (buffer.length === 1 && buffer[0] === PING) {\n // this is definitely `ping` event you can call custom on ping handler \n // also must send back immediately pong to the server \n // otherwise server will disconnect this client\n return socket.send(PONG);\n }\n }\n\n // process with your logic\n}\n```\n","readmeFilename":"README.md","homepage":"https://github.com/ClusterWS/cWS#readme","repository":{"type":"git","url":"git+https://github.com/ClusterWS/cWS.git"},"bugs":{"url":"https://github.com/ClusterWS/cWS/issues"}}
![\"npm](\"https://badge.fury.io/js/%40clusterws%2Fcws.svg\"){kind=icon}
\n ![\"travis](\"https://travis-ci.org/ClusterWS/cWS.svg?branch=master\")
\n