|
| 1 | +# websocketd |
| 2 | + |
| 3 | +`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. |
| 4 | + |
| 5 | +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, Haskell, Lua, R, whatever! No networking libraries necessary. |
| 6 | + |
| 7 | +-[@joewalnes](https://twitter.com/joewalnes) |
| 8 | + |
| 9 | +## Details |
| 10 | + |
| 11 | +Upon startup, `websocketd` will start a WebSocket server on a specified port, and listen for connections. |
| 12 | + |
| 13 | +Upon a connection, it will fork the appropriate process, and disconnect the process when the WebSocket connection closes (and vice-versa). |
| 14 | + |
| 15 | +Any message sent from the WebSocket client will be piped to the process's `STDIN` stream, followed by a `\n` newline. |
| 16 | + |
| 17 | +Any text printed by the process to `STDOUT` shall be sent as a WebSocket message whenever a `\n` newline is encountered. |
| 18 | + |
| 19 | +## Download |
| 20 | + |
| 21 | +If you're on a Mac, you can install `websocketd` using [Homebrew](http://brew.sh/). Just run `brew install websocketd`. For other operating systems, or if you don't want to use Homebrew, check out the link below. |
| 22 | + |
| 23 | +**[Download for Linux, OS X and Windows](https://github.com/app-fast/websocketd/wiki/Download-and-install)** |
| 24 | + |
| 25 | +## Quickstart |
| 26 | + |
| 27 | +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. |
| 28 | + |
| 29 | +To show how simple it is, let's do it in Bash! |
| 30 | + |
| 31 | +**count.sh**: |
| 32 | + |
| 33 | +```sh |
| 34 | +#!/bin/bash |
| 35 | +for ((COUNT = 1; COUNT <= 10; COUNT++)); do |
| 36 | + echo $COUNT |
| 37 | + sleep 1 |
| 38 | +done |
| 39 | +``` |
| 40 | + |
| 41 | +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. |
| 42 | + |
| 43 | +```sh |
| 44 | +$ chmod +x count.sh |
| 45 | +$ ./count.sh |
| 46 | +1 |
| 47 | +2 |
| 48 | +3 |
| 49 | +4 |
| 50 | +5 |
| 51 | +6 |
| 52 | +7 |
| 53 | +8 |
| 54 | +9 |
| 55 | +10 |
| 56 | +``` |
| 57 | + |
| 58 | +Now let's turn it into a WebSocket server: |
| 59 | + |
| 60 | +```sh |
| 61 | +$ websocketd --port=8080 ./count.sh |
| 62 | +``` |
| 63 | + |
| 64 | +Finally, let's create a web-page to test it. |
| 65 | + |
| 66 | +**count.html**: |
| 67 | + |
| 68 | +```html |
| 69 | +<!DOCTYPE html> |
| 70 | +<pre id="log"></pre> |
| 71 | +<script> |
| 72 | + // helper function: log message to screen |
| 73 | + function log(msg) { |
| 74 | + document.getElementById("log").textContent += msg + "\n"; |
| 75 | + } |
| 76 | +
|
| 77 | + // setup websocket with callbacks |
| 78 | + var ws = new WebSocket("ws://localhost:8080/"); |
| 79 | + ws.onopen = function () { |
| 80 | + log("CONNECT"); |
| 81 | + }; |
| 82 | + ws.onclose = function () { |
| 83 | + log("DISCONNECT"); |
| 84 | + }; |
| 85 | + ws.onmessage = function (event) { |
| 86 | + log("MESSAGE: " + event.data); |
| 87 | + }; |
| 88 | +</script> |
| 89 | +``` |
| 90 | + |
| 91 | +Open this page in your web-browser. It will even work if you open it directly |
| 92 | +from disk using a `file://` URL. |
| 93 | + |
| 94 | +## More Features |
| 95 | + |
| 96 | +- Very simple install. Just [download](https://github.com/app-fast/websocketd/wiki/Download-and-install) the single executable for Linux, Mac or Windows and run it. Minimal dependencies, no installers, no package managers, no external libraries. Suitable for development and production servers. |
| 97 | +- Server side scripts can access details about the WebSocket HTTP request (e.g. remote host, query parameters, cookies, path, etc) via standard [CGI environment variables](https://github.com/app-fast/websocketd/wiki/Environment-variables). |
| 98 | +- As well as serving websocket daemons it also includes a static file server and classic CGI server for convenience. |
| 99 | +- Command line help available via `websocketd --help`. |
| 100 | +- Includes [WebSocket developer console](https://github.com/app-fast/websocketd/wiki/Developer-console) to make it easy to test your scripts before you've built a JavaScript frontend. |
| 101 | +- [Examples in many programming languages](https://github.com/app-fast/websocketd/tree/master/examples) are available to help you getting started. |
| 102 | + |
| 103 | +## User Manual |
| 104 | + |
| 105 | +**[More documentation in the user manual](https://github.com/app-fast/websocketd/wiki)** |
| 106 | + |
| 107 | +## Example Projects |
| 108 | + |
| 109 | +- [Plot real time Linux CPU/IO/Mem stats to a HTML5 dashboard using websocketd and vmstat](https://github.com/app-fast/web-vmstats) _(for Linux)_ |
| 110 | +- [Arbitrary REPL in the browser using websocketd](https://github.com/rowanthorpe/ws-repl) |
| 111 | +- [Retrieve SQL data from server with LiveCode and webSocketd](https://github.com/samansjukur/wslc) |
| 112 | +- [List files from a configured folder](https://github.com/dbalakirev/directator) _(for Linux)_ |
| 113 | +- [Listen for gamepad events and report them to the system](https://github.com/experiment322/controlloid-server) _(this + android = gamepad emulator)_ |
| 114 | + |
| 115 | +Got more examples? Open a pull request. |
| 116 | + |
| 117 | +## My Other Projects |
| 118 | + |
| 119 | +- [ReconnectingWebSocket](https://github.com/app-fast/reconnecting-websocket) - Simplest way to add some robustness to your WebSocket connections. |
| 120 | +- [Smoothie Charts](http://smoothiecharts.org/) - JavaScript charts for streaming data. |
| 121 | +- Visit [The Igloo Lab](http://theigloolab.com/) to see and subscribe to other thingies I make. |
| 122 | + |
| 123 | +And [follow @joewalnes](https://twitter.com/joewalnes)! |
0 commit comments