websocketd README

The project's README from github.com/joewalnes/websocketd. As one markdown file: README.md.

websocketd

websocketd is a small command-line tool that will wrap an existing command-line interface program, and allow it to be accessed via a WebSocket.

WebSocket-capable applications can now be built very easily. As long as you can write an executable program that reads STDIN and writes to STDOUT, you can build a WebSocket server. Do it in Python, Ruby, Perl, Bash, .NET, C, Go, PHP, Java, Clojure, Scala, Groovy, Expect, Awk, VBScript, PowerShell, Haskell, Lua, R, whatever! No networking libraries necessary.

-@joewalnes

Details

Upon startup, websocketd will start a WebSocket server on a specified port, and listen for connections.

Upon a connection, it will fork the appropriate process, and disconnect the process when the WebSocket connection closes (and vice-versa).

Any message sent from the WebSocket client will be piped to the process's STDIN stream, followed by a \n newline.

Any text printed by the process to STDOUT shall be sent as a WebSocket message whenever a \n newline is encountered.

Download

If you're on a Mac, you can install websocketd using Homebrew. Just run brew install websocketd. For other operating systems, or if you don't want to use Homebrew, check out the link below.

Download for Linux, macOS and Windows

Quickstart

To get started, we'll create a WebSocket endpoint that will accept connections, then send back messages, counting to 10 with 1 second pause between each one, before disconnecting.

To show how simple it is, let's do it in Bash!

count.sh:

#!/bin/bash
for ((COUNT = 1; COUNT <= 10; COUNT++)); do
  echo $COUNT
  sleep 1
done

Before turning it into a WebSocket server, let's test it from the command line. The beauty of websocketd is that servers work equally well in the command line, or in shell scripts, as they do in the server - with no modifications required.

$ chmod +x count.sh
$ ./count.sh
1
2
3
4
5
6
7
8
9
10

Now let's turn it into a WebSocket server:

$ websocketd --port=8080 ./count.sh

Finally, let's create a web-page to test it.

count.html:

<!DOCTYPE html>
<pre id="log"></pre>
<script>
  // helper function: log message to screen
  function log(msg) {
    document.getElementById('log').textContent += msg + '\n';
  }

  // setup websocket with callbacks
  const ws = new WebSocket('ws://localhost:8080/');
  ws.onopen = () => {
    log('CONNECT');
  };
  ws.onclose = () => {
    log('DISCONNECT');
  };
  ws.onmessage = (event) => {
    log(`MESSAGE: ${event.data}`);
  };
</script>

Open this page in your web-browser. It will even work if you open it directly from disk using a file:// URL.

More Features

Documentation

More documentation

Example Projects

Got more examples? Open a pull request.

My Other Projects

And follow @joewalnes!

websocketd (joewalnes/websocketd)

Searching Database…

17.5K ·GitHub
Websocketd
What is this?websocketd is a small command-line tool that wraps an existing command-line program and exposes it as a WebSocket server — like inetd, but for WebSockets. Any script that reads STDIN and writes STDOUT becomes a live, browser-reachable endpoint.
How does it turn my script into a WebSocket server?On startup it opens a WebSocket server on a port you specify; each incoming connection forks your program, pipes client messages into its STDIN, and sends every newline-terminated STDOUT line back as a WebSocket message. The process dies when the connection closes.
What languages can my server program be written in?Any executable that reads STDIN and writes STDOUT — the README lists Bash, Python, Ruby, Perl, PHP, Java, Go, PowerShell, Haskell, Awk and more. You need no networking libraries at all; websocketd handles the socket side.
How do I try it before writing any frontend code?Run your script straight from the command line first — servers work identically in a terminal and as a WebSocket endpoint. websocketd also ships a built-in developer console (--devconsole) to connect, send frames and read responses with no JavaScript.
What can I actually build with it?The README's example projects include plotting real-time Linux CPU/IO/memory stats to an HTML5 dashboard via vmstat, an arbitrary REPL in the browser, retrieving SQL data with LiveCode, listing files from a folder, and a gamepad event listener that pairs with Android into a gamepad emulator.
Can I keep it off the public network interface?Yes — it can listen on a Unix domain socket (--unixsocket) instead of, or alongside, a TCP address, pinning permissions with --socketmode (e.g. 0700). That exposes it only to same-host processes, e.g. behind an SSH-forwarded or reverse-proxied socket.
Can my script's error output reach the browser while debugging?Optionally: with --passstderr, STDERR is forwarded to WebSocket clients tagged as JSON alongside STDOUT, so the client can tell the two streams apart.
What are similar projects?ttyd, tailcat, dufs, websocket, uvicorn, miller, fq, http-server
Which topics is it in?websockets, websocket, real-time, bsd, proxy, command-line, networking, go, command-line-tool, free, terminal, tool
Creator
joewalnes
Size
2.1 MB
Stars
17.5K
Updated
CommitSep 07Releasev0.4.1Jan 25
Age
13y
Commits · 90 Days