notiflux is a pub/sub server where clients subscribe over a WebSocket and messages are broadcast over a POST request
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.
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:<campaign_id> 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 <topic> <token>
clients can then unsubscribe with
/unsubscribe <topic> # From one topic
/unsubscribe-all # From all topics
To make a broadcast to a topic, a POST request must be made to /broadcast, which includes the topic, message and token
curl \
-XPOST \
-H "Content-Type: application/json" \
-d '{"topic": "<topic>", "message": "<message>", "token": "<token>"}' \
localhost:8080/broadcast
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.
The JWT token needs to have the following payload:
{
"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
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.1PORT: Defaults to 8080JWT_PUBLIC_KEY_B64: Required, the base64 encoded public key
Generating a private key can be done with
openssl ecparam -genkey -name prime256v1 -out es256_private.pem
and then the public key
openssl ec -in es256_private.pem -pubout -out es256_public.pem
which can be base64 encoded with
cat es256_public.pem | base64
then running with docker is as simple as
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
1.3k Jan 8, 2023
5k Jan 4, 2023
12 Oct 3, 2022
344 Dec 31, 2022
55 Dec 30, 2022
20 Dec 2, 2022
12 Nov 12, 2022
158 Mar 9, 2023
10 Nov 11, 2022
5 Oct 4, 2022
191 Dec 20, 2022
11 Oct 17, 2022
5 Sep 28, 2024
1 Oct 31, 2021
2 Feb 20, 2022
10 Dec 20, 2022
102 Dec 24, 2022
1.2k Dec 30, 2022
1 Feb 4, 2022
3 Nov 16, 2022