websocat v1.1.0

Node Websocat (websocat)

Netcat, curl and socat for WebSockets.

Use websocat as an npm module for tighter integration with node apps. Automatically downloads websocat.

Usage

npm install websocat

const websocat = require("websocat")

// Web service to proxy (on client)
const webService = micro((req, res) => res.end("Hello world!"))
webService.listen(3000)

// Start websocat that ingests a tcp/http request and hosts a websocket
const httpInWebSocketOut = await websocat.create({
  listen: "tcp-l:127.0.0.1:3001",
  host: "ws://127.0.0.1:3002",
  exitOnEOF: true,
  binary: true,
})

// Start a websocat that ingests messages from a websocket and forwards
// to our hello world server
const websocketIn = await websocat.create({
  listen: "ws-l:127.0.0.1:3002",
  host: "tcp:127.0.0.1:5000",
  exitOnEOF: true,
  binary: true,
})

const response = await request(`http://127.0.0.1:2000`)
// response === "Hello world!"

await httpInWebSocketOut.stop()
await websocketIn.stop()

Options

await websocat.create({
  // Alias: listen
  addr1: "tcp-l:127.0.0.1:3000",

  // Alias: host
  addr2: "ws://127.0.0.1:4000",

  // Close a data transfer direction if the other one reached EOF
  exitOnEOF: false,

  // strict line/message mode: drop too long messages instead of
  // splitting them, drop incomplete lines.
  strict: false,

  // Use \0 instead of \n for linemode
  nullTerminated: false,

  // Serve only once. Not to be confused with -1 (--one-message)
  oneshot: false,

  // Send and/or receive only one message. Use with --no-close and/or -u/-U.
  oneMessage: false,

  // Send message to WebSockets as binary messages
  binary: false,

  // Don't send Close message to websocket on EOF
  noClose: false,

  // Send message to WebSockets as text messages
  text: false,

  // Accept invalid certificates and hostnames while connecting to TLS
  insecure: false,

  // Inhibit copying data in one direction
  unidirectional: false,

  // Inhibit copying data in the other direction (or maybe in
  // both directions if combined with -u)
  unidirectionalReverse: false,

  // Add custom HTTP headers to websocket client request.
  headers: {
    Authorization: "Bearer SomeToken",
  },

  // Add custom HTTP header to websocket upgrade reply.
  serverHeaders: {
    Authorization: "Bearer SomeToken",
  },
})