astraw / bui-backend

backend server for Browser User Interface (BUI)

bui-backend

bui-backend - Brower User Interfaces (BUIs) with Tokio

This library enables an application to serve a Browser User Interface (BUI). The browser becomes your GUI. The API is based on futures and reactively pushes state to the browser. Assets can be served from the filesystem or bundled in the executable. The server provides an "escape hatch" to allow server-client communication outside of bui-backend. The demo includes a Rust web assembly (wasm) frontend using the seed framework and a plain Javascript frontend. Together, this lets you ship an application written in Rust as a single file with a browser-based UI.

The operating principle is that the server runs an HTTP server (based on hyper) to which the browser connects. The initial page tells the browser to open a connection to a Server Sent Events endpoint and the server can subsequently push updates to the browser. Additionally, the server listens for POST callbacks on another endpoint. All data is encoded as JSON.

Features

• Uses async-change-tracker type to ensure that server state changes are reactively sent to all connected frontends.
• To keep things simple, server state is shared with all connected clients.
• Session keys (per browser) and connection keys (per tab) are maintained and allow taking control of communication using pre-established event stream. (This is an "escape hatch" to break out of the bui-backend abstractions as required by some use cases.)
• Written in asyncronous rust using async/await.
• Uses Serde JSON.
• Compile-time choice between bundling served files into executable (with bundle_files feature) or reading files from disk (serve_files).

Demo

A demo is available with frontends written in Rust web assembly using the seed framework and plain Javascript. (Use bui-demo with frontend_seed, or frontend_js feature.)

Potential improvements

• Add example with user login.
• Send minimal differences when state changes, likely by improving async-change-tracker.
• Implement more sophisticated state-sharing allowing partial views and minimal updates.
• Use ReadableStream instead of Server Sent Events.
• Add a websocket transport option as an alternative to Server Sent Events.
• Your idea here.

Security warning

Due to its nature, the program listens and responds to client connections from the network. If you expose your program to untrusted network connections, ensure that code within any callback handlers you write is safe when handling malicious input.

Other crates in this repository

• codegen - Buildtime codegen support for bui-backend.
• bui-demo - Example program with Rust and Javascript frontends.

License

Licensed under either of

• Apache License, Version 2.0, (./LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (./LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Code of conduct

Anyone who interacts with bui-backend in any space including but not limited to this GitHub repository is expected to follow our code of conduct.

Operational overview

                      HTTP responses
                      & event stream
+--server----------+ +--------------> +--web-browser-------------------------+
|app binary written|                  | frontend, optionally in written      |
|with bui_backend  | <--------------+ | in rust with support from bui_backend|
+------------------+  HTTP requests   +--------------------------------------+

Example

For a full example, see the demo.

Usage

This example assumes you have the following filesystem layout in the crate for the application binary that will run the webserver:

.
├── build.rs        # Bundles frontend files or specifies serving from disk.
├── Cargo.toml      # Normal Cargo.toml manifest file.
├── frontend_js     # Your frontend files are in this directory. bui_backend
│   ├── index.html  #   also includes some assistance for writing frontends
│   └── js          #   in rust, such as automatic serialization.
│       └── main.js
└── src             # The source for your application binary is here.
    └── main.rs

In this example, we assume you have files to serve for a frontend (e.g. index.html) in the directory frontend_js. You must create a file build.rs which will:

• compile the files in this directory into your application's binary if you use the default compilation features or specified the bundle_files cargo feature (recommended for deployment),
• attempt to access the files in this directory at runtime if you use the serve_files cargo feature (recommended for frontend development),
• or throw a compile time error if you do not specify exactly one of bundle_files and serve_files.

In the Cargo.toml file for your backend application, add the following lines:

[dependencies]
bui-backend = "0.7"
bui-backend-types = "0.7"

[build-dependencies]
bui-backend-codegen = "0.1.4"

Now, here is the example build.rs file:

extern crate bui_backend_codegen;

fn main() {
    bui_backend_codegen::codegen("frontend_js", "public.rs").expect("codegen failed");
}

Finally, in your main.rs file:

// Include the files to be served and define `fn get_default_config()`.
include!(concat!(env!("OUT_DIR"), "/public.rs")); // Despite slash, this works on Windows.

Building the documentation

RUSTDOCFLAGS='--cfg=docsrs -Dwarnings' cargo +nightly doc --open --features "bui-backend-types/uuid-v4"

Testing

cargo +nightly test --features "bui-backend-types/uuid-v4"

Regnerate README.md

cargo readme > README.md

License: MIT/Apache-2.0

bui-backend's Issues

Disallow failures on nightly

FYI, cargo-web 0.4.2 is building again on the newest nightly, so you can revert commit d2ca064. (:

Some questions before I decide if I port my frontend to bui

This project looks very interesting, but before I switch my existing frontend over to bui I have some questions:

1. Why does it use server-sent events instead of websockets? When will it be possible to use websockets instead?
2. How flexible is it, does it impose any restrictions on what the frontend can do? Or can it be a full featured web app that uses webgl, canvas, svg, localstorage etc.?
3. When to use bui instead of just writing a frontend in yew and backend with (rocket|rouille|hyper) + ws-rs (and then injecting the ws port into the page before serving, if the port is dynamic) or actix (to serve websockets on the same port)?
4. Will it ever support something like browser-sync, to reload all clients when the source changes (maybe using the notify crate like cargo-watch)?

My current project uses a frontend written in polymer, I'm using browser-sync to auto-reload the app when the files change on disk, but I want to rewrite the frontend in Rust with yew (for wasm) so that I can re-use code and types from my backend and get static type safety.
My server side uses ws-rs and I want to keep using websockets because somewhere I've read that they have lower latency than server-sent events, is that true?
Btw, this project is a DJing/VJing application and needs the lowest possible latency.