Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Clivern/Beaver
💨 A real time messaging system to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps.
https://github.com/Clivern/Beaver
beaver hacktoberfest messaging messaging-service pubsub pusher realtime socket-io socketjs websocket
Last synced: 10 days ago
JSON representation
💨 A real time messaging system to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps.
- Host: GitHub
- URL: https://github.com/Clivern/Beaver
- Owner: Clivern
- License: mit
- Created: 2018-10-20T21:10:43.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-10-16T07:09:31.000Z (20 days ago)
- Last Synced: 2024-10-16T19:01:33.053Z (19 days ago)
- Topics: beaver, hacktoberfest, messaging, messaging-service, pubsub, pusher, realtime, socket-io, socketjs, websocket
- Language: Go
- Homepage: https://clivern.github.io/Beaver/
- Size: 3.11 MB
- Stars: 1,544
- Watchers: 32
- Forks: 82
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-go - Beaver - A real time messaging server to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps. (Messaging / Search and Analytic Databases)
- zero-alloc-awesome-go - Beaver - A real time messaging server to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps. (Messaging / Search and Analytic Databases)
- awesome-ccamel - Clivern/Beaver - 💨 A real time messaging system to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps. (Go)
- awesome - Clivern/Beaver - 💨 A real time messaging system to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps. (Go)
- awesome-go - Beaver - A real time messaging server to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps. Stars:`1.5K`. (Messaging / Search and Analytic Databases)
- awesome-go-extra - Beaver - app notifications, multiplayer games, chat apps in web and mobile apps.|1368|73|7|2018-10-20T21:10:43Z|2022-08-08T07:13:38Z| (Messaging / Advanced Console UIs)
- awesome-repositories - Clivern/Beaver - 💨 A real time messaging system to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps. (Go)
README
Beaver
A Real Time Messaging Server.
Beaver is a real-time messaging server. With beaver you can easily build scalable in-app notifications, realtime graphs, multiplayer games, chat applications, geotracking and more in web applications and mobile apps.
## Documentation
#### Run Beaver on Ubuntu
Download [the latest beaver binary](https://github.com/Clivern/Beaver/releases). Make it executable from everywhere.
```zsh
$ export BEAVER_LATEST_VERSION=$(curl --silent "https://api.github.com/repos/Clivern/Beaver/releases/latest" | jq '.tag_name' | sed -E 's/.*"([^"]+)".*/\1/' | tr -d v)
$ curl -sL https://github.com/Clivern/Beaver/releases/download/v{$BEAVER_LATEST_VERSION}/beaver_{$BEAVER_LATEST_VERSION}_Linux_x86_64.tar.gz | tar xz
```
Then install `redis` cluster or a single node. Update the following config file with redis configs.
Create the configs file `config.yml` from `config.dist.yml`. Something like the following:
```yaml
# App configs
app:
# Env mode (dev or prod)
mode: ${BEAVER_APP_MODE:-prod}
# HTTP port
port: ${BEAVER_API_PORT:-8080}
# Hostname
hostname: ${BEAVER_API_HOSTNAME:-127.0.0.1}
# TLS configs
tls:
status: ${BEAVER_API_TLS_STATUS:-off}
pemPath: ${BEAVER_API_TLS_PEMPATH:-cert/server.pem}
keyPath: ${BEAVER_API_TLS_KEYPATH:-cert/server.key}
# API Configs
api:
key: ${BEAVER_API_KEY:-6c68b836-6f8e-465e-b59f-89c1db53afca}
# Beaver Secret
secret: ${BEAVER_SECRET:-sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD}
# Runtime, Requests/Response and Beaver Metrics
metrics:
prometheus:
# Route for the metrics endpoint
endpoint: ${BEAVER_METRICS_PROM_ENDPOINT:-/metrics}
# Application Database
database:
# Database driver
driver: ${BEAVER_DB_DRIVER:-redis}
# Redis Configs
redis:
# Redis address
address: ${BEAVER_DB_REDIS_ADDR:-localhost:6379}
# Redis password
password: ${BEAVER_DB_REDIS_PASSWORD:- }
# Redis database
db: ${BEAVER_DB_REDIS_DB:-0}
# Log configs
log:
# Log level, it can be debug, info, warn, error, panic, fatal
level: ${BEAVER_LOG_LEVEL:-info}
# Output can be stdout or abs path to log file /var/logs/beaver.log
output: ${BEAVER_LOG_OUTPUT:-stdout}
# Format can be json
format: ${BEAVER_LOG_FORMAT:-json}
```
The run the `beaver` with `systemd`
```zsh
$ beaver api -c /path/to/config.yml
```
### API Endpoints
Create a Config `app_name`:
```bash
$ curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca" \
-d '{"key":"app_name","value":"Beaver"}' \
"http://localhost:8080/api/config"
```
Get a Config `app_name`:
```bash
$ curl -X GET \
-H "Content-Type: application/json" \
-H "X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca" \
"http://localhost:8080/api/config/app_name"
{"key":"app_name","value":"Beaver"}
```
Update a Config `app_name`:
```bash
$ curl -X PUT \
-H "Content-Type: application/json" \
-H "X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca" \
-d '{"value":"Beaver"}' \
"http://localhost:8080/api/config/app_name"
```
Delete a Config `app_name`:
```bash
$ curl -X DELETE \
-H "Content-Type: application/json" \
-H "X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca" \
"http://localhost:8080/api/config/app_name"
```
Create a Channel:
```bash
# Private Channel
$ curl -X POST \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"name": "app_x_chatroom_1", "type": "private"}' \
'http://localhost:8080/api/channel'
# Public Channel
$ curl -X POST \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"name": "app_y_chatroom_1", "type": "public"}' \
'http://localhost:8080/api/channel'
# Presence Channel
$ curl -X POST \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"name": "app_z_chatroom_5", "type": "presence"}' \
'http://localhost:8080/api/channel'
```
Get a Channel:
```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '' \
'http://localhost:8080/api/channel/app_x_chatroom_1'
{
"created_at":1545573214,
"listeners_count":0,
"name":"app_x_chatroom_1",
"subscribers_count":0,
"type":"private",
"updated_at":1545573214
}
$ curl -X GET \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '' \
'http://localhost:8080/api/channel/app_y_chatroom_1'
{
"created_at":1545573219,
"listeners_count":0,
"name":"app_y_chatroom_1",
"subscribers_count":0,
"type":"public",
"updated_at":1545573219
}
$ curl -X GET \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '' \
'http://localhost:8080/api/channel/app_z_chatroom_5'
{
"created_at": 1545573225,
"listeners": null,
"listeners_count": 0,
"name": "app_z_chatroom_5",
"subscribers": null,
"subscribers_count": 0,
"type": "presence",
"updated_at": 1545573225
}
```
Update a Channel `app_y_chatroom_1`:
```bash
$ curl -X PUT \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"type": "private"}' \
'http://localhost:8080/api/channel/app_y_chatroom_1'
```
Delete a Channel `app_y_chatroom_1`:
```bash
$ curl -X DELETE \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '' \
'http://localhost:8080/api/channel/app_y_chatroom_1'
```
Create a Client and add to `app_x_chatroom_1` Channel:
```bash
$ curl -X POST \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"channels": ["app_x_chatroom_1"]}' \
'http://localhost:8080/api/client'
{
"channels": [
"app_x_chatroom_1"
],
"created_at": 1545575142,
"id": "69775af3-5f68-4725-8162-09cab63e8427",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiNjk3NzVhZjMtNWY2OC00NzI1LTgxNjItMDljYWI2M2U4NDI3QDE1NDU1NzUxNDIiLCJ0aW1lc3RhbXAiOjE1NDU1NzUxNDJ9.EqL-nWwu5p7hJXWrKdZN3Ds2cxWVjNYmeP1mbl562nU",
"updated_at": 1545575142
}
```
Get a Client `69775af3-5f68-4725-8162-09cab63e8427`:
```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '' \
'http://localhost:8080/api/client/69775af3-5f68-4725-8162-09cab63e8427'
{
"channels": [
"app_x_chatroom_1"
],
"created_at": 1545575142,
"id": "69775af3-5f68-4725-8162-09cab63e8427",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiNjk3NzVhZjMtNWY2OC00NzI1LTgxNjItMDljYWI2M2U4NDI3QDE1NDU1NzUxNDIiLCJ0aW1lc3RhbXAiOjE1NDU1NzUxNDJ9.EqL-nWwu5p7hJXWrKdZN3Ds2cxWVjNYmeP1mbl562nU",
"updated_at": 1545575142
}
```
Subscribe a Client `69775af3-5f68-4725-8162-09cab63e8427` to a Channel `app_z_chatroom_5`:
```bash
$ curl -X PUT \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"channels": ["app_z_chatroom_5"]}' \
'http://localhost:8080/api/client/69775af3-5f68-4725-8162-09cab63e8427/subscribe'
```
Unsubscribe a Client `69775af3-5f68-4725-8162-09cab63e8427` from a Channel `app_z_chatroom_5`:
```bash
$ curl -X PUT \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"channels": ["app_z_chatroom_5"]}' \
'http://localhost:8080/api/client/69775af3-5f68-4725-8162-09cab63e8427/unsubscribe'
```
Delete a Client:
```bash
$ curl -X DELETE \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '' \
'http://localhost:8080/api/client/69775af3-5f68-4725-8162-09cab63e8427'
```
Publish to a Channel `app_x_chatroom_1`:
```bash
$ curl -X POST \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"channel": "app_x_chatroom_1", "data": "{\"message\": \"Hello World\"}"}' \
'http://localhost:8080/api/publish'
```
Broadcast to Channels `["app_x_chatroom_1"]`:
```bash
$ curl -X POST \
-H 'Content-Type: application/json' \
-H 'X-API-Key: 6c68b836-6f8e-465e-b59f-89c1db53afca' \
-d '{"channels": ["app_x_chatroom_1"], "data": "{\"message\": \"Hello World\"}"}' \
'http://localhost:8080/api/broadcast'
```
Sample Frontend Client
```js
function Socket(url){
ws = new WebSocket(url);
ws.onmessage = function(e) { console.log(e); };
ws.onclose = function(){
// Try to reconnect in 5 seconds
setTimeout(function(){Socket(url)}, 5000);
};
}
Socket("ws://localhost:8080/ws/$ID/$TOKEN");
```
## Client:
- [Go Client](https://github.com/domgolonka/beavergo) Thanks [@domgolonka](https://github.com/domgolonka)
## Versioning
For transparency into our release cycle and in striving to maintain backward compatibility, Beaver is maintained under the [Semantic Versioning guidelines](https://semver.org/) and release process is predictable and business-friendly.
See the [Releases section of our GitHub project](https://github.com/clivern/beaver/releases) for changelogs for each release version of Beaver. It contains summaries of the most noteworthy changes made in each release.
## Bug tracker
If you have any suggestions, bug reports, or annoyances please report them to our issue tracker at https://github.com/clivern/beaver/issues
## Security Issues
If you discover a security vulnerability within Beaver, please send an email to [[email protected]](mailto:[email protected])
## Contributing
We are an open source, community-driven project so please feel free to join us. see the [contributing guidelines](CONTRIBUTING.md) for more details.
## License
© 2018, Clivern. Released under [MIT License](https://opensource.org/licenses/mit-license.php).
**Beaver** is authored and maintained by [@Clivern](http://github.com/clivern).