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
Что это такое?websocketd — это небольшая утилита командной строки, которая оборачивает уже существующую консольную программу и превращает её в WebSocket-сервер — что-то вроде inetd, только для WebSocket. Любой скрипт, который читает из STDIN и пишет в STDOUT, становится живым эндпоинтом, доступным из браузера.
Как он превращает мой скрипт в WebSocket-сервер?При запуске он открывает WebSocket-сервер на указанном вами порту; с каждым входящим соединением он запускает новый экземпляр вашей программы, передаёт сообщения клиента в её STDIN, а каждую строку из STDOUT, завершённую переводом строки, отправляет обратно как WebSocket-сообщение. Когда соединение закрывается, процесс завершается.
На каком языке можно написать мою серверную программу?Подойдёт любой исполняемый файл, который читает из STDIN и пишет в STDOUT — в README перечислены Bash, Python, Ruby, Perl, PHP, Java, Go, PowerShell, Haskell, Awk и другие. Сетевые библиотеки вообще не нужны: всей работой с сокетами занимается websocketd.
Как попробовать его, не написав ни строчки кода для фронтенда?Сначала запустите свой скрипт прямо из командной строки — в терминале и в виде WebSocket-эндпоинта он работает одинаково. Кроме того, в websocketd встроена консоль разработчика (--devconsole): с её помощью можно подключаться, отправлять фреймы и читать ответы без какого-либо JavaScript.
Что на нём вообще можно сделать?Среди примеров из README: вывод статистики Linux по CPU, вводу-выводу и памяти в реальном времени на HTML5-дашборд через vmstat, произвольный REPL прямо в браузере, получение SQL-данных с помощью LiveCode, список файлов из папки и слушатель событий геймпада, который вместе с Android превращается в эмулятор геймпада.
Можно ли спрятать его от публичного сетевого интерфейса?Да — он может слушать на Unix-сокете (--unixsocket) вместо TCP-адреса или вместе с ним, а права доступа задаются флагом --socketmode (например, 0700). В таком случае доступ получают только процессы на той же машине — например, если сокет проброшен через SSH или проксируется reverse-прокси.
При отладке ошибки из моего скрипта попадут в браузер?По желанию: с флагом --passstderr поток STDERR передаётся WebSocket-клиентам в виде JSON-помеченных сообщений наряду с STDOUT, так что клиент может отличить один поток от другого.
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