presidium-websocket

Presidium WebSocket

WebSocket client and server for Node.js.

const WebSocket = require('presidium-websocket')

const server = new WebSocket.Server(websocket => {
  websocket.on('message', message => {
    console.log('Message from client:', message)
    websocket.send('Hello from server!')
  })
  websocket.on('close', () => {
    console.log('websocket closed')
  })
})

server.listen(1337, () => {
  console.log('WebSocket server listening on port 1337')
})

const websocket = new WebSocket('ws://localhost:1337/')

websocket.on('open', () => {
  websocket.send('Hello from client!')
})
websocket.on('message', message => {
  console.log('Message from server:', message)
})

Serve WebSocket Secure (WSS) connections.

const WebSocket = require('presidium-websocket')
const fs = require('fs')

const server = new WebSocket.SecureServer({
  key: fs.readFileSync('/path/to/my-key'),
  cert: fs.readFileSync('/path/to/my-cert')
})

server.on('connection', websocket => {
  websocket.on('message', message => {
    console.log('Secure message from client:', message)
    websocket.send('Hello from server!')
  })
  websocket.on('close', () => {
    console.log('websocket closed')
  })
})

server.listen(4443, () => {
  console.log('WebSocket Secure server listening on port 4443')
})

const websocket = new WebSocket('wss://localhost:4443/')

websocket.on('open', () => {
  websocket.send('Hello from client!')
})
websocket.on('message', message => {
  console.log('Message from server:', message)
})

Supports compression with perMessageDeflate (uses zlib default options).

const server = new WebSocket.Server({ perMessageDeflate: true })

Initiate new connections on the same websocket instance.

const websocket = new WebSocket('ws://localhost:1337/')

// reconnect websocket on broken connections
while (true) {
  if (websocket.readyState === 1) {
    // websocket is open
  } else {
    // reconnect
    websocket.connect()
  }
  await sleep(10000)
}

Installation

with npm:

npm i presidium-websocket

Docs

WebSocket

Create a Presidium WebSocket client.

new WebSocket(url string) -> websocket WebSocket

new WebSocket(url string, options {
  rejectUnauthorized: boolean,
  autoConnect: boolean
}) -> websocket WebSocket

websocket.on('open', ()=>()) -> ()
websocket.on('message', (message Buffer)=>()) -> ()
websocket.on('ping', ()=>()) -> ()
websocket.on('pong', ()=>()) -> ()
websocket.on('error', (error Error)=>()) -> ()
websocket.on('close', ()=>()) -> ()

Initiate a new connection to the WebSocket server.

websocket.connect() -> ()

Send a payload to the WebSocket server.

websocket.send(payload Buffer|string) -> ()

Send a close frame to the WebSocket server.

websocket.sendClose() -> ()
websocket.sendClose(payload Buffer|string) -> ()

Send a ping frame to the server.

websocket.sendPing() -> ()
websocket.sendPing(payload Buffer|string) -> ()

Send a pong frame to the server.

websocket.sendPong() -> ()
websocket.sendPong(payload Buffer|string) -> ()

Close the connection to the WebSocket server.

websocket.close() -> ()
websocket.close(payload Buffer|string) -> ()

Destroy the underlying socket

websocket.destroy() -> ()
websocket.destroy(payload Buffer|string) -> ()

WebSocket.Server

Create a Presidium WebSocket server.

module http 'https://nodejs.org/api/http.html'
module net 'https://nodejs.org/api/net.html'

websocketHandler (websocket WebSocket)=>()
httpHandler (request http.ClientRequest, response http.ServerResponse)=>()
upgradeHandler (request http.ClientRequest, socket net.Socket, head Buffer)=>()

new WebSocket.Server() -> server WebSocket.Server
new WebSocket.Server(websocketHandler) -> server WebSocket.Server

new WebSocket.Server(websocketHandler, options {
  httpHandler: httpHandler,
  secure: boolean,
  key: string,
  cert: string
}) -> server WebSocket.Server

new WebSocket.Server(options {
  websocketHandler: websocketHandler,
  httpHandler: httpHandler,
  secure: boolean,
  key: string,
  cert: string
}) -> server WebSocket.Server

server.on('connection', websocketHandler) -> ()
server.on('request', httpHandler) -> ()
server.on('upgrade', upgradeHandler) -> ()
server.on('error', (error Error)=>()) -> ()
server.on('close', ()=>()) -> ()

server.on('connection', (websocket WebSocket) => {
  websocket.on('open', ()=>()) -> ()
  websocket.on('message', (message Buffer)=>()) -> ()
  websocket.on('ping', ()=>()) -> ()
  websocket.on('pong', ()=>()) -> ()
  websocket.on('error', (error Error)=>()) -> ()
  websocket.on('close', ()=>()) -> ()
})

WebSocket.SecureServer

Create a Presidium WebSocket Secure server.

module http 'https://nodejs.org/api/http.html'
module net 'https://nodejs.org/api/net.html'

websocketHandler (websocket WebSocket)=>()
httpHandler (request http.ClientRequest, response http.ServerResponse)=>()
upgradeHandler (request http.ClientRequest, socket net.Socket, head Buffer)=>()

new WebSocket.SecureServer(options {
  key: string,
  cert: string
}) -> server WebSocket.SecureServer

new WebSocket.SecureServer(websocketHandler, options {
  httpHandler: httpHandler,
  key: string,
  cert: string
}) -> server WebSocket.SecureServer

new WebSocket.SecureServer(options {
  websocketHandler: websocketHandler,
  httpHandler: httpHandler,
  key: string,
  cert: string
}) -> server WebSocket.SecureServer

server.on('connection', websocketHandler) -> ()
server.on('request', httpHandler) -> ()
server.on('upgrade', upgradeHandler) -> ()
server.on('error', (error Error)=>()) -> ()
server.on('close', ()=>()) -> ()

server.on('connection', (websocket WebSocket) => {
  websocket.on('open', ()=>()) -> ()
  websocket.on('message', (message Buffer)=>()) -> ()
  websocket.on('ping', ()=>()) -> ()
  websocket.on('pong', ()=>()) -> ()
  websocket.on('error', (error Error)=>()) -> ()
  websocket.on('close', ()=>()) -> ()
})

Benchmarks

Please find the published benchmark output inside the benchmark-output folder. You can run the benchmarks on your own system with the following command:

npm run bench

Contributing

Your feedback and contributions are welcome. If you have a suggestion, please raise an issue. Prior to that, please search through the issues first in case your suggestion has been made already. If you decide to work on an issue, please create a pull request.

Pull requests should provide some basic context and link the relevant issue. Here is an example pull request. If you are interested in contributing, the help wanted tag is a good place to start.

For more information please see CONTRIBUTING.md

License

Presidium WebSocket is MIT Licensed.

Support

• minimum Node.js version: 16