https://github.com/ikornaselur/notiflux
notiflux - subscribe over WebSockets, publish over REST
https://github.com/ikornaselur/notiflux
jwt pubsub rust websocket
Last synced: 4 months ago
JSON representation
notiflux - subscribe over WebSockets, publish over REST
- Host: GitHub
- URL: https://github.com/ikornaselur/notiflux
- Owner: ikornaselur
- Created: 2024-03-20T22:20:34.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-07T18:40:10.000Z (over 1 year ago)
- Last Synced: 2025-11-11T13:28:02.872Z (7 months ago)
- Topics: jwt, pubsub, rust, websocket
- Language: Rust
- Homepage:
- Size: 178 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# notiflux
notiflux is a pub/sub server where clients subscribe over a WebSocket and
messages are broadcast over a POST request
## How does it work?
Client connect via WebSocket and subscribe to topics. A publishing source
will make POST requests to the broadcast endpoint, with a message and a topic,
which will then publish the message to all connected clients.
### Usage
#### Subscribing to topics
Clients connect over WebSocket and subscribe to the topics, which can be any
string. The idea is that they could subscribe to something like
`campaign:` for notifications about a specific campaign, or even
just `campaigns` for all campaign updates.
This is by calling the subscribe command with the topic and a token (see next
section for token info)
```
/subscribe
```
clients can then unsubscribe with
```
/unsubscribe # From one topic
/unsubscribe-all # From all topics
```
#### Broadcasting messages
To make a broadcast to a topic, a POST request must be made to `/broadcast`,
which includes the topic, message and token
```bash
curl \
-XPOST \
-H "Content-Type: application/json" \
-d '{"topic": "", "message": "", "token": ""}' \
localhost:8080/broadcast
```
### Auth token
Notiflux uses an EC256 public/private key pair JWT for authentication. Notiflux
is deployed with the public key, while the broadcaster has the private key as a
secret.
When clients connect, they need to provide a JWT with the topics and scope,
signed by the private key. This token should be provided be the broadcasting
source.
To make a broadcast, the broadcaster makes a POST request with a JWT as well,
using the broadcast scope.
### JWT structure
The JWT token needs to have the following payload:
```js
{
"sub": "notiflux", // Can be any value
"exp": 123, // Expiry just needs to be valid for the broadcast
// or subscribe event, so just few seconds is enough
"topics": ["topic"], // The topics to validate against
"scope": "subscribe|broadcast", // Needs to be either 'subscribe' for clients
// or 'broadcast' for broadcaster
}
```
Note that the topics can be a list of just one topic or multiple topics, which
means the same JWT can be used to subscribe or broadcast to multiple topics.
See ./scripts folder for examples in Python
## Deployment
notiflux is published as a docker container as ghcr.io/ikornaselur/notiflux:latest
The configuration is done through environment variables:
* `HOST`: Defaults to 127.0.0.1
* `PORT`: Defaults to 8080
* `JWT_PUBLIC_KEY_B64`: Required, the base64 encoded public key
Generating a private key can be done with
```bash
openssl ecparam -genkey -name prime256v1 -out es256_private.pem
```
and then the public key
```bash
openssl ec -in es256_private.pem -pubout -out es256_public.pem
```
which can be base64 encoded with
```bash
cat es256_public.pem | base64
```
then running with docker is as simple as
```bash
docker run \
-e JWT_PUBLIC_KEY_B64=... \
-e HOST=0.0.0.0 \
-p 127.0.0.1:8080:8080 \
ghcr.io/ikornaselur/notiflux:latest
```