## Broker - Real-time BaaS (Backend as a Service)

[![crates.io](https://meritbadge.herokuapp.com/broker)](https://crates.io/crates/broker)

### Purpose

The purpose of this service is to be your real-time BaaS (Backend as a Service). 

Broker is a SSE message broker that requires you write no backend code to have a full real-time API.

Broker is born from the need that rather than building a complex REST API with web-sockets and a SQL database to provide reactive web forms (like for React) there must be a simpler way.

Broker follows an insert-only/publish/subscribe paradigm rather than a REST CRUD paradigm. 

### Features

* Very performant with almost no CPU and memory usage
* Under 500 lines of code
* Secure Real-time Event Stream via SSE - requires the use of [broker-client](https://www.npmjs.com/package/broker-client)
* Supports CORS
* Supports SSL - full end-to-end encryption
* Provides user authentication with JWTs with stored Argon2 passwords
* Uses Global NTP servers and doesn't rely on your local server time
* Insert event via JSON POST request 
* Sync latest events on SSE client connection

### How it works

In Broker you create a user, login, then insert an event with its data. Broker then publishes the event via SSE.

When the client first subscribes to the SSE connection all the latest events and data is sent to the client. Combined with sending the latest event via SSE when subscribed negates the necessity to do any GET API requests in the lifecycle of an event.

The side-effect of this system is that the latest event is the schema. This is pure NoSQL as the backend is agnostic to the event data.

### Recommeded Services/Libraries to use with Broker
* [broker-client](https://www.npmjs.com/package/broker-client) - the official front-end client for broker
* [broker-hook](https://www.npmjs.com/package/broker-hook) - the official react hook for broker
* [React Hook Form](https://react-hook-form.com/) - Best form library for React
* [React Debounce Input](https://www.npmjs.com/package/react-debounce-input) - React input for Real-time Submission (Edit in Place forms)

### Broker FAQ
* Why compete against Parse Server and Firebase?

[Firebase](https://firebase.google.com/) is not open-source, is not free, and has complicated pricing. [Parse Server](https://github.com/parse-community/parse-server) doesn't have real-time features and is about 30,000 LOC of JS.

* Will broker work with mobile apps?

Yes with React Native. There may be native 3rd party libraries for SSE that work. In the future official libraries may be made available for native platforms.

### Use

#### Step 1 - create a user

```html
POST /users 
```
- public endpoint
- POST JSON to create a user
```json
{"username":{...}, "password":{...}}
```
- where {...} is for username is a string and password is a string

will return `200` or `500` or `400`

#### For JWT Auth: Step 2 - login with the user

```html
POST /login 
```
- public endpoint
- POST JSON to login
```json
{"username":{...}, "password":{...}}
```
- where {...} is for username is a string and password is a string

will return 
```json
{"jwt":{...}}
```
- where {...} is a JWT (string)

#### Step 3 - connect to SSE

```html 
GET /sse
```
- authenticated endpoint (Authorization: Bearer {jwt})
- connect your sse-client to this endpoint using [broker-client](https://www.npmjs.com/package/broker-client)
- `note`: broker-client uses fetch as eventsource doesn't support headers

#### Step 4 - insert an event

```html
POST /insert 
```
- authenticated endpoint (Authorization: Bearer {jwt})
- POST JSON to insert an event
```json
{"event":{...}, "data":{...}}
```
- where {...} is for the event a string and data is any JSON you want

will return: `200` or `500` or `400` or `401`

### Install

``` cargo install broker ```

- the origin can be passed in as a flag - default *
- the port can be passed in as a flag - default 8080
- the jwt_expiry (for jwts) can be passed in as a flag - default 86400
- the jwt_secret (for jwts) should be passed in as a flag - default secret
- the secure can be passed in as a flag (true or false) - default false
- the key_path can be passed in as a flag if connection https - default ./broker.rsa
- the cert_path can be passed in as a flag if connection https - default ./broker.pem
- the db can be passed in as a flag where the embedded database will be saved - default tmp
- example: `./broker --db="tmp" --port="443" --secure="true" --origin="*" --jwt_expiry="86400" --jwt_secret="secret" --key_path="broker.rsa" --cert_path="broker.pem"`

### Service

There is an example `systemctl` service for Ubuntu called `broker.service` in the code

### TechStack

* [Tide](https://crates.io/crates/tide)
* [RocksDB](https://crates.io/crates/rocksdb)

### Inspiration

* [React Hooks](https://reactjs.org/docs/hooks-intro.html)
* [Meteor](https://meteor.com)
* [MongoDB](https://www.mongodb.com/)
* [Pusher](https://pusher.com)
* [Event Sourcing](https://microservices.io/patterns/data/event-sourcing.html)
* [Best in Place](https://github.com/bernat/best_in_place)
* [Brock Whitten](https://www.youtube.com/watch?v=qljYMEfVukU)

### Migrations

- from 5.0 to 6.0: is a full rewrite - there is no upgrade path from 5.0 to 6.0
- from 4.0 to 5.0: multi-tenancy has been added and sled has been upgraded - there is no upgrade path from 4.0 to 5.0
- from 3.0 to 4.0: the sse endpoint now returns all events with all collections with the latest collection event rather than just the latest event data for all event types
- from 2.0 to 3.0: the sse endpoint is now secure and requires the use of the [broker-client](https://www.npmjs.com/package/broker-client) library
- from 1.0 to 2.0: the optional API endpoints URLs have been changed but have the same functionality