bare-ws

bare-ws is a WebSocket client and server for Bare. Sockets are bare-stream duplex streams that perform the WebSocket handshake over an HTTP or HTTPS request. It's pure JavaScript.

npm i bare-ws

Usage

const ws = require('bare-ws')

const server = new ws.Server({ port: 8080 }, (socket) => {
  socket.on('data', (data) => {
    console.log(data.toString())
  })
})

server.on('listening', () => {
  const socket = new ws.Socket({ port: 8080 })

  socket.write('Hello WebSocket')
})

API

Socket

const socket = new ws.Socket(url[, options])

Open a WebSocket connection to url, or wrap an already-connected socket when acting as the server side of a handshake.

Overloads:

new ws.Socket(url, options)
new ws.Socket(options)

options = {
  host: null,
  hostname: null, // Alias for `host`, for Node.js compatibility
  path: null,
  port: null,
  secure: false, // Use TLS (`wss:`) for the underlying connection
  socket: null // An already-connected TCP socket to wrap instead of opening a new one
}

socket.ping(data) · socket.pong(data)

Send a ping or pong frame with data as its payload. A string data is converted to a Buffer. Throws a WebSocketError with code NOT_CONNECTED if the socket hasn't finished connecting.

ws.Socket.handshake(req, cb)

Perform the client side of the WebSocket opening handshake over the HTTP request req, calling cb(error) with a WebSocketError if the server's response is invalid.

Sockets emit ping and pong (in addition to the usual stream events).

Server

const server = new ws.Server([options][, onconnection])

Create a WebSocket server, optionally backed by options.server. onconnection is added as a connection listener, called for each successful WebSocket upgrade with (socket, req).

options = {
  secure: false // Create an HTTPS-backed server, accepting `wss:` connections
}

server.address() · server.listening

server.address() returns the bound address of the underlying TCP server. server.listening is true once the server is bound and accepting connections.

server.close([cb]) · server.ref() · server.unref()

Stop the server from accepting new connections, calling cb once closed; ref/unref the underlying server.

ws.Server.handshake(req, [socket[, head]], cb)

Perform the server side of the WebSocket opening handshake for the request req, writing the 101 upgrade response and calling cb(error) with a WebSocketError on failure.

Servers emit connection and listening.

Constants

ws.opcode holds the WebSocket frame opcodes (CONTINUATION, TEXT, BINARY, CLOSE, PING, PONG) defined by RFC 6455. ws.status holds close status codes for protocol errors (PROTOCOL_ERROR) and oversized messages (MESSAGE_TOO_LARGE).

Errors

Protocol violations throw a WebSocketError carrying a code and a close status:

Related modules

Builds on bare-crypto, bare-events, bare-http1, bare-https, and bare-stream (see Bare modules).

See also

• Bare modules—the full bare-* catalog.
• bare-tcp—the socket layer WebSocket connections run over.
• bare-fetch—a request/response HTTP client for the non-persistent case.