Go to file
Bevan Hunt dfdee36486 wip 2020-01-06 21:48:29 -08:00
example fix user system and add ownership 2020-01-06 16:22:22 -08:00
src wip 2020-01-06 21:48:29 -08:00
.gitignore delete tmp 2019-12-31 00:41:16 -08:00
Cargo.lock wip 2020-01-06 21:48:29 -08:00
Cargo.toml wip 2020-01-06 21:48:29 -08:00
LICENSE move files 2019-12-31 00:46:48 -08:00
Makefile update readme 2020-01-05 23:24:24 -08:00
Procfile make library 2019-12-31 12:29:09 -08:00
README.md wip 2020-01-06 21:48:29 -08:00

README.md

Broker - Real-time Zero-Code API Server

crates.io

Purpose

The purpose of this library is to be your real-time zero-code API server.

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.

How it works

In Broker you create a user, login, then insert an event and its data with a timestamp. Broker publishes the event when the timestamp is reached to the event stream via SSE. Broker keeps all event versions in its database that can be viewed. Broker can also cancel future events.

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. Old events are saved in the database and are not changed but the latest event is the schema for the front-end. This is pure NoSQL as the backend is agnostic to the event data.

API

/users 
  • public endpoint
  • POST JSON to create a user
{"username":{...}, "password":{...}, "info":{...}}
  • where {...} is for username and string, password a string, and info any JSON you want

will return

{"id":{...}}
  • where {...} is the uuid (string) of the user
/login 
  • public endpoint
  • POST JSON to login
{"username":{...}, "password":{...}}
  • where {...} is for username a string and password a string

will return

{"jwt":{...}}
  • where {...} is a JWT (string)
/events 
  • public endpoint
  • connect your sse-client to this endpoint
/insert 
  • authenticated endpoint
  • POST JSON to insert an event
{"event":{...}, "id":{...}, "timestamp":{...}, "data":{...}}
  • where {...} is for the event a string, id is a uuid v4 you provide, timestamp is the epoch unix timestamp when you want the event to become the current event, and data is any JSON you want

will return

{"id":{...}}
  • where {...} is the uuid (string) of the event
/events/{id}/cancel
  • authenticated endpoint
  • do a GET request where id is the uuid of the event to cancel a future event

Features

  • Very performant with a low memory footprint
  • Real-time Event Stream via SSE
  • CORS support
  • Handles SSE client timeouts
  • Provides user authentication with JWTs and Bcrypt(ed) passwords
  • Handles future events via Epoch UNIX timestamp
  • Stateful immutable event persistence
  • Insert event via JSON POST request
  • Sync latest events with audit trail on SSE client connection
  • Event cancellation via GET request

Use

use broker::{broker_run};

#[actix_rt::main]
async fn main() -> std::result::Result<(), std::io::Error> {
    broker_run("http://localhost:3000".to_owned()).await
}
  • the only param is the origin you want to allow - wildcard is not supported
  • the PORT needs to be passed in as an environment variable
  • the ORIGIN needs to be passed in as an environment variable
  • the EXPIRY (for jwts) needs to be passed in as an environment variable
  • the SECRET (for jwts) needs to be passed in as an environment variable
  • the file database saves to ./tmp of the project root

Run Example

  • make

Under the Hood

Inspiration