https://github.com/zooniverse/sugar
Event system
https://github.com/zooniverse/sugar
utility
Last synced: 4 months ago
JSON representation
Event system
- Host: GitHub
- URL: https://github.com/zooniverse/sugar
- Owner: zooniverse
- Created: 2014-10-06T14:47:27.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2025-09-25T01:54:57.000Z (8 months ago)
- Last Synced: 2025-09-25T03:44:13.865Z (8 months ago)
- Topics: utility
- Language: JavaScript
- Homepage:
- Size: 728 KB
- Stars: 1
- Watchers: 16
- Forks: 1
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://pullreminders.com?ref=badge)
# What is Sugar?
Sugar is a server side event notification system to deliver event data payloads to subscribed clients.
By default it will attempt to connect the client to the server using websockets and will fall back to long polling.
See https://github.com/zooniverse/Sugar-Client for the client implementation details.
## How it works
The server is a wrapper around Redis pub/sub (https://redis.io/topics/pubsub) and real time events (https://github.com/primus/primus#engineio) connections all via a HTTP API.
The HTTP end points are:
1. `get '/presence'`
+ list the subscribed user counts for all channels
0. `get '/active_users?channel=zooniverse'`
+ list the subscribed users for a specific channel
0. `post '/notify'`
+ send a 'notification' message to a specific private user channel
0. `post '/announce'`
+ broadcast an 'announcement' message to a specific section channel, e.g. (project-1 || zooniverse)
0. `post '/experiment'`
+ send a 'experiment' message to a specific private user channel
All requests to the post end points must include a formatted message body for the matching event type as described below.
The 3 types of messages the system accepts are:
1. Notifications
``` JSON
{"notifications": [{"user_id": "1", "message": "Hiya", "url": "test", "delivered": "false"}]}
```
0. Announcements
``` JSON
{"announcements": [{"message": "announcment message", "url": "test", "section": "zooniverse", "delivered": "false"}]}
```
0. Experiments
``` JSON
{"experiments": [{"user_id": "1", "message": "would you like to participate?", "url": "test", "delivered": "false"}]}
```
## Manual testing of notifications
Construct per user notification payloads in JSON and use something like cURL to POST the payload to the notifications server.
E.g.
``` bash
curl -vv \
-X "POST" "https://notifications-staging.zooniverse.org/notify" \
-H 'Content-Type: application/json' \
-u 'username:password' \
-d $'{
"notifications": [{
"message": "A message from curl to user 1",
"user_id": "1",
"url": "http://test.net",
"delivered": false
}]
}'
```
The `examples` directory has some example scripts. Replace `USER` and `PASSWORD` with the username and password for the staging service:
sugar-announce.sh- Send an announcement to a Zooniverse project.
sugar-messages.sh- Send a message to a user ID
sugar-notify.sh- Send a notification to a user ID
sugar-subjects.sh- Inject specific subjects into the classification queue for a user ID (PFE only.)
## Debugging
Visit https://notifications-staging.zooniverse.org/ for debug user & testing section announcements and user notifications.
## Development via docker & docker-compose
To Run a local version of the sugar system
+ `docker-compose build`
+ `docker-compose up`
Run run the tests (you may need to rebuild the docker image if the src changes)
+ `docker-compose run -T --rm sugar npm test`
Get a bash container via docker to run tests, etc
`docker-compose run --service-ports --rm sugar bash`