Skip to content
💨A real time messaging server to build a scalable in-app notifications, multiplayer games, chat apps in web and mobile apps.
Branch: master
Clone or download
Latest commit 873ea01 Apr 3, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE update readme & docker files Nov 7, 2018
assets Update docker files & add single node chart Feb 10, 2019
internal switch to spf13/viper Mar 14, 2019
var/logs Init beaver Oct 22, 2018
web add simple connect js func Dec 7, 2018
.gitignore switch to micro/go-config for yml configs Dec 22, 2018
.goreleaser.yml
.travis.yml
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Oct 20, 2018
CONTRIBUTING.md Update CONTRIBUTING.md Apr 3, 2019
Dockerfile Update docker files & add single node chart Feb 10, 2019
LICENSE
Makefile switch from dep to go modules Jan 8, 2019
PULL_REQUEST_TEMPLATE.md Update docs & add channel api package Nov 19, 2018
README.md Update README.md Apr 3, 2019
beaver.go switch to spf13/viper Mar 14, 2019
config.toml Fix some linting issues Oct 29, 2018
config.travis.yml support TLS Mar 12, 2019
config.yml support TLS Mar 12, 2019
docker-compose.yml Update docker files & add single node chart Feb 10, 2019
go.mod switch to spf13/viper Mar 14, 2019
go.sum switch to spf13/viper Mar 14, 2019

README.md

Beaver Logo

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.

Beaver Single Node

Documentation

Config & Run The Application

Beaver uses Go Modules to manage dependencies. First Create a dist config file.

$ cp config.yml config.dist.yml

Then add your app.*, log.*, redis_*, api.* ...etc.

app:
    mode: dev
    port: 8080
    domain: example.com
    secret: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD
    tls:
        status: off
        pemPath: cert/server.pem
        keyPath: cert/server.key

log:
    level: info
    path: var/logs

redis:
    addr: localhost:6379
    password:
    db: 0

api:
    token: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD

And then run the application.

$ go build beaver.go
$ ./beaver

// OR

$ go run beaver.go

// To Provide a custom config file
$ ./beaver -config=/custom/path/config.dist.yml
$ go run beaver.go -config=/custom/path/config.dist.yml

Or download a pre-built Beaver binary for your operating system.

$ curl -sL https://github.com/Clivern/Beaver/releases/download/x.x.x/beaver_x.x.x_OS.tar.gz | tar xz
$ ./beaver -config=config.dist.yml

Also running beaver with docker still an option.

$ mkdir -p $HOME/srv/beaver
$ mkdir -p $HOME/srv/beaver/configs
$ mkdir -p $HOME/srv/beaver/logs

$ cd $HOME/srv/beaver

$ curl -OL https://raw.githubusercontent.com/Clivern/Beaver/master/Dockerfile
$ curl -OL https://raw.githubusercontent.com/Clivern/Beaver/master/docker-compose.yml
$ curl -OL https://raw.githubusercontent.com/Clivern/Beaver/master/config.yml

$ cp config.yml ./configs/config.dist.yml
$ rm config.yml
# Update log.path to be the absolute path to config file on host machine ($HOME/srv/beaver/logs)
$ sed -i "s|var/logs|${HOME}/srv/beaver/logs|g" ./configs/config.dist.yml
$ sed -i "s|localhost:6379|redis:6379|g" ./configs/config.dist.yml

# Build and run containers
$ cd $HOME/srv/beaver/
$ docker-compose build
$ docker-compose up -d

API Endpoints

Create a Config app_name:

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD" \
    -d '{"key":"app_name","value":"Beaver"}' \
    "http://localhost:8080/api/config"

Get a Config app_name:

$ curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD" \
    "http://localhost:8080/api/config/app_name"

{"key":"app_name","value":"Beaver"}

Update a Config app_name:

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD" \
    -d '{"value":"Beaver"}' \
    "http://localhost:8080/api/config/app_name"

Delete a Config app_name:

$ curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD" \
    "http://localhost:8080/api/config/app_name"

Create a Channel:

# Private Channel
$ curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -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-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -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-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -d '{"name": "app_z_chatroom_5", "type": "presence"}' \
    'http://localhost:8080/api/channel'

Get a Channel:

$ curl -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -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-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -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-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -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:

$ curl -X PUT \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -d '{"type": "private"}' \
    'http://localhost:8080/api/channel/app_y_chatroom_1'

Delete a Channel app_y_chatroom_1:

$ curl -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -d '' \
    'http://localhost:8080/api/channel/app_y_chatroom_1'

Create a Client and add to app_x_chatroom_1 Channel:

$ curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -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:

$ curl -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -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:

$ curl -X PUT \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -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:

$ curl -X PUT \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -d '{"channels": ["app_z_chatroom_5"]}' \
    'http://localhost:8080/api/client/69775af3-5f68-4725-8162-09cab63e8427/unsubscribe'

Delete a Client:

$ curl -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -d '' \
    'http://localhost:8080/api/client/69775af3-5f68-4725-8162-09cab63e8427'

Publish to a Channel app_x_chatroom_1:

$ curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -d '{"channel": "app_x_chatroom_1", "data": "{\"message\": \"Hello World\"}"}' \
    'http://localhost:8080/api/publish'

Broadcast to Channels ["app_x_chatroom_1"]:

$ curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-TOKEN: sWUhHRcs4Aqa0MEnYwbuQln3EW8CZ0oD' \
    -d '{"channels": ["app_x_chatroom_1"], "data": "{\"message\": \"Hello World\"}"}' \
    'http://localhost:8080/api/broadcast'

Sample Frontend Client

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");

Versioning

For transparency into our release cycle and in striving to maintain backward compatibility, Beaver is maintained under the Semantic Versioning guidelines and release process is predictable and business-friendly.

See the Releases section of our GitHub project 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 hello@clivern.com

Contributing

We are an open source, community-driven project so please feel free to join us. see the contributing guidelines for more details.

License

© 2018, Clivern. Released under MIT License.

Beaver is authored and maintained by @Clivern.

You can’t perform that action at this time.