Skip to content

Latest commit

 

History

History
192 lines (150 loc) · 7.03 KB

README.md

File metadata and controls

192 lines (150 loc) · 7.03 KB
Raw

bui-backend

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

Version Status Doc

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

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