presidium-websocket

Presidium WebSocket

WebSocket client and server for Node.js. Implements RFC 6455.

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

Constructs a Presidium WebSocket client.

new WebSocket(url string) -> websocket WebSocket

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

Options:

• rejectUnauthorized - if true, the client verifies the server's certificate against a list of pre-approved certificate authorities (CAs). An error event is emitted if verification fails; err.code contains the OpenSSL error code. Defaults to true.
• autoConnect - if true, establishes the underlying TCP connection automatically upon construction. Defaults to true.
• maxMessageLength - the maximum length in bytes of sent messages. If a message is longer than maxMessageLength, it is split into fragmented messages that are reassembled by the receiver.

Events:

• open
• message
• ping
• pong
• error
• close

websocket 'open' event

Emitted when the WebSocket protocol handshake is complete.

websocket.on('open', ()=>()) -> ()

websocket 'message' event

Emitted upon receipt and successful decoding (and reassembly, if applicable) of an incoming message.

websocket.on('message', (message Buffer)=>()) -> ()

websocket 'ping' event

Emitted upon receipt and successful decoding of an incoming "ping" message.

websocket.on('ping', (payload Buffer)=>()) -> ()

websocket 'pong' event

Emitted upon receipt and successful decoding of an incoming "pong" message.

websocket.on('pong', (payload Buffer)=>()) -> ()

websocket 'error' event

Emitted if any errors occur during construction, in any method calls, or on the underlying socket.

websocket.on('error', (error Error)=>()) -> ()

websocket 'close' event

Emitted when the underlying socket is destroyed. The 'close' event can be emitted after a call to the websocket.close method.

websocket.on('close', ()=>()) -> ()

websocket.connect

Initiates a new connection to the WebSocket server.

websocket.connect() -> ()

websocket.send

Sends a payload to the WebSocket server.

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

websocket.sendClose

Sends a close frame to the WebSocket server.

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

websocket.sendPing

Sends a ping frame to the server.

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

websocket.sendPong

Sends a pong frame to the server.

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

websocket.close

Closes the connection to the WebSocket server.

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

websocket.destroy

Destroys the underlying socket.

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

WebSocket.Server

Constructs a Presidium WebSocket server.

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

type WebSocketHandler = (websocket WebSocket)=>()
type HTTPHandler = (request http.ClientRequest, response http.ServerResponse)=>()
type UpgradeHandler = (request http.ClientRequest, socket net.Socket, head Buffer)=>()

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

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

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

server.on('connection', websocketHandler WebSocketHandler) -> ()
server.on('request', httpHandler HTTPHandler) -> ()
server.on('upgrade', upgradeHandler 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', (payload Buffer)=>()) -> ()
  websocket.on('pong', (payload Buffer)=>()) -> ()
  websocket.on('error', (error Error)=>()) -> ()
  websocket.on('close', ()=>()) -> ()
})

WebSocket.SecureServer

Constructs a Presidium WebSocket Secure (WSS) server.

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

type WebSocketHandler = (websocket WebSocket)=>()
type HTTPHandler = (request http.ClientRequest, response http.ServerResponse)=>()
type UpgradeHandler = (request http.ClientRequest, socket net.Socket, head Buffer)=>()

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

new WebSocket.SecureServer(websocketHandler WebSocketHandler, options {
  httpHandler: HTTPHandler,
  key: string,
  cert: string,
  perMessageDeflate: boolean,
  maxMessageLength: number
}) -> server WebSocket.SecureServer

new WebSocket.SecureServer(options {
  websocketHandler: WebSocketHandler,
  httpHandler: HTTPHandler,
  key: string,
  cert: string,
  perMessageDeflate: boolean,
  maxMessageLength: number
}) -> server WebSocket.SecureServer

server.on('connection', websocketHandler WebSocketHandler) -> ()
server.on('request', httpHandler HTTPHandler) -> ()
server.on('upgrade', upgradeHandler 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', (payload Buffer)=>()) -> ()
  websocket.on('pong', (payload Buffer)=>()) -> ()
  websocket.on('error', (error Error)=>()) -> ()
  websocket.on('close', ()=>()) -> ()
})

Benchmarks

Stats for 30 individual 30s runs of bench-presidium and bench-ws:

OS 6.15.4-arch2-1
Node.js v22.12.0
presidium-websocket@0.1.2
ws@8.18.3

Presidium Max Throughput: 773.9204074888052
Presidium Min Throughput: 663.717446247961
Presidium Avg Throughput: 740.4098268048717

ws Max Throughput:        734.9618854401924
ws Min Throughput:        699.1601014862653
ws Avg Throughput:        721.359269165629

Please find all of the published benchmark output inside the benchmark-output folder.

Running benchmarks on your own system

Run benchmarks for ws:

./bench-ws

Run benchmarks for presidium-websocket:

./bench-presidium

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