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
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).
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.
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:
| Environment Variable | Default | Description |
|---|---|---|
SECRET |
|
Secret salt used to sign authentication tokens |
PORT |
6380 |
Port in which to serve websocket connections |
LOGLEVEL |
info |
Verbosity of log output, valid options are [debug,info,warning,error,fatal,panic] |
MAX_CONNECTIONS |
255 |
Maximum amount of concurrent websocket connections allowed |
READ_BUFFER_SIZE |
1024 |
Size of the websocket read buffer, for most cases the default should be okay. |
WRITE_BUFFER_SIZE |
1024 |
Size of the websocket write buffer, for most cases the default should be okay. |
CHECK_ORIGIN |
false |
Check Origin headers during WebSocket upgrade handshake. |
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 philoteThere 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 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.
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
You'll need gpm for dependency management.
$ source .env.sample # you might want to copy it to .env and source that instead if you plan on changing the settings.
$ make$ make server$ make test$ make installThe 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.
Released under MIT License, check LICENSE file for details.