Philote: plug-and-play websockets server

Philote is a minimal solution to the websockets server problem, it implements Publish/Subscribe and has a simple authentication mechanism that accomodates browser clients securely as well as server-side or desktop applications.

Simplicity is one of the design goals for Philote, ease of deployment is another: you should be able to drop the binary in any internet-accessible server and have it operational.

For a short demonstration, check out the sample command line Philote client called Jane

Basics

Philote implements a basic topic-based Publish-subscribe pattern, messages sent over the websocket connection are classified into channels, and each connection is given read/write access to a given list of channels at authentication time.

Messages sent over a connection for a given channel (to which it has write permission) will be received by all other connections (that have read permission to the channel in question).

Deploy your own instance

You can play around with Philote by deploying it on Heroku for free, keep in mind that Heroku's free tier dynos are not suited for production Philote usage, however, as sleeping dynos will mean websocket connections are closed.

Configuration options

Philote takes configuration options from your environment and attempts to provide sensible defaults, these are the environment variables you can set to change its behaviour:

If the defaults work for you, simply running philote will start the server with the default values, or you can just manipulate the environment and run with whatever settings you need.

$ PORT=9424 philote

CLI

There is a trivial implementation of basic Philote interaction called Jane that you can run locally, it can subscribe to a channel on a Philote server, receive and publish messages. It's useful for debugging purposes.

Clients

• JavaScript (browser)
• Go
• Python

Authentication

Clients authenticate in Philote using JSON Web Tokens, which consist on a JSON payload detailing the read/write permissions a given connection will have. The payload is hashed with a secret known to Philote so that incoming connections can be verified, this way you can generate tokens in your application backend and use them from the browser client without fear.

Clients in different language will provide methods to generate these tokens, for now, the Go client should be the reference implementation, although you'll notice that it's an extremely simple one so ports to other languages should be trivial to implement provided with a decent JWT library.

For incoming websockets connections, Philote will look to find the authentication token in the Authorization header, but since the native browser JavaScript WebSocket API does not provide a way to manipulate the request headers Philote will also look for the auth query parameter in case it fails to authenticate using the header option.

Install

You can install Philote (and Jane) easily with homebrew.

brew install pote/philote/philote

brew install pote/philote/jane

You can also manually get the binaries from latest release or install from source

Local development

Bootstrap it

You'll need gpm for dependency management.

Set it up

$ source .env.sample # you might want to copy it to .env and source that instead if you plan on changing the settings.
$ make

Run a Philote server

$ make server

Run the test suite

$ make test

Install from source

$ make install

History

The first versions of Philote were powered by Redis, it was initially thought of as a websocket bridge to a Redis instance.

After a while, that design was considered inpractical: redis is a big dependency to have, publish/subscribe was easy to implement in Philote itself and the authentication mechanism was changed to use JSON Web Tokens, making Redis unnecessary.

The result should be a more robust tool that anyone can drop in any operating system and get working trivially, without external dependencies.

License

Released under MIT License, check LICENSE file for details.