WebSockets
the UNIX way

Full duplex messaging between web browsers and servers

websocketd is the WebSocket daemon

It takes care of handling the WebSocket connections,
launching your programs to handle the WebSockets,
and passing messages between programs and web-browser.

It's like CGI, twenty years later, for WebSockets

Language agnostic

If you can run your program from the command line, you can write WebSocket endpoints.

No libraries required

Just read incoming text from stdin and write outgoing text to stdout.
Messaging is simple.

Avoid threading headaches

Each inbound WebSocket connection runs your program in a dedicated process.
Connections are isolated by process.

Built for the UNIX philosophy

Write programs that do one thing and do it well.
Write programs to work together.
Write programs to handle text streams,
because that is a universal interface.

If you dig that, you'll dig websocketd.

10 second tutorial

Let's create a tiny WebSocket server that counts to ten, pausing between each iteration.

Create a program in your favorite language:

  • Bash
  • Java
  • Python
  • Ruby
  • PHP
  • Perl
  • C
  • C#
  • Swift
  • Dart
  • In fact... anything!
#!/bin/bash

# Count from 1 to 10 with a sleep
for ((COUNT = 1; COUNT <= 10; COUNT++)); do
  echo $COUNT
  sleep 0.5
done
class Counter {
  public static void main(String [] args) throws Exception {
    for (int i=0; i<10; i++) {
      System.out.println(i);
      Thread.sleep(500);
    }
  }
}
#!/usr/bin/python
from sys import stdout
from time import sleep

# Count from 1 to 10 with a sleep
for count in range(0, 10):
  print(count + 1)
  stdout.flush()
  sleep(0.5)
#!/usr/bin/ruby

# Count from 1 to 10 with a sleep
STDOUT.sync = true
(1..10).each do |count|
	puts count
	sleep(0.5)
end
#!/usr/bin/php
<?php

# Count from 1 to 10 with a sleep
for ($count = 1; $count <= 10; $count++) {
	echo $count . "\n";
	usleep(500000);
}
?>
#!/usr/bin/perl
use Time::HiRes qw(sleep);
# Autoflush
$|++;
# Count from 1 to 10 with a sleep
for my $count (1 .. 10) {
	print "$count\n";
	sleep 0.5;
}
#include <stdio.h>
#include <unistd.h>

int main() {
    int i;

    // Disable output buffering.
    setbuf(stdout, NULL);

    for (i = 1; i <= 10; i++) {
        printf("%d\n", i);
        usleep(500000);
    }

    return 0;
}
using System;
using System.Threading;

class Counter
{
  static void Main()
  {
    for (int i = 1; i <= 10; i++)
    {
      Console.WriteLine(i);
      Thread.Sleep(500);
    }
  }
}
#!/usr/bin/env xcrun swift
import AppKit

for index in 1...10 {
  print(index)
  fflush(__stdoutp)
  NSThread.sleepForTimeInterval(0.5)
}
import 'dart:io';

main() {
  for (int i = 0; i < 10; i++) {
    print(i);
    sleep(const Duration(milliseconds: 500));
  }
}
You get the idea!

If you can write a program that can be launched from
the command line, you can build a WebSocket server.

Read inbound messages from STDIN.
Write outbound messages to STDOUT.

Read HTTP and connection details from environment vars.
Use line breaks as message delimiters.

Start websocketd and tell it about your program:

$ websocketd --port=8080 my-program

Now connect to your program from JavaScript in a web-page using a WebSocket:

var ws = new WebSocket('ws://localhost:8080/');

ws.onmessage = function(event) {
  console.log('Count is: ' + event.data);
};

See... WebSocket servers are simple!

Whichever way inclined you are

I

Oh, and...

Static server

Serves your static HTML, JavaScript, etc

Program routing

Route different URLs to different programs

CGI server

Dynamic generate content over HTTP too

SSL

Out-of-the-box support for serving content using HTTPS and WSS

Origin checking

Restrict which pages can make WebSocket connections

Development console

Interact with your WebSocket programs before you've built your frontend

Get it

Available for Linux, OSX, Windows, FreeBSD, OpenBSD and Solaris

websocketd is a single executable program. Easy to copy to servers.

Current version: 0.3.0

Announcements, new features, security advisories

We won't share your email address with anyone else. Pinky swear.