eui-rust
EUI applications, written in Rust.
EUI delivers an application interface over
HTTPS without HTML, CSS or JavaScript. The server sends a tree that is
already resolved, in a compact binary encoding; a native client applies
it, lays it out and draws it on the GPU. There is no tolerant parse at the
other end, no cascade to resolve, no script to run.
This crate is the server half: the wire format, the view encoder and its
diff, the session, the content-addressed asset store, the signed manifest,
and a component model in which a view is a value and a handler changes
state.
No dependencies, and the dependency list is the whole of it. Rust's
standard library has no BLAKE3 — and an asset is named by the hash of its
content — no SHA-1 for the WebSocket handshake, and no Ed25519 for the
manifest signature. All four are in src/, checked against the published
vectors, because the six sibling libraries answer with the same bytes and a
disagreement has to be findable. It also has no TLS, and that one is not
written out: see Running it.
use std::sync::Arc;
use eui::dsl::{button, column, text};
use eui::{nodes, style, App, Component, Ctx, Listen, Node, Params, ViewResult};
#[derive(Default)]
struct Counter { count: i64 }
impl Component for Counter {
fn handle(&mut self, name: &str, _: &Params, _: &Ctx) -> ViewResult<()> {
if name == "increment" { self.count += 1; }
Ok(())
}
fn render(&mut self, _: &Ctx) -> ViewResult<Node> {
Ok(column(nodes![
text(self.count.to_string(), style! { "size" => "4xl", "weight" => "bold" }),
button("Increment", "increment", style! {}),
], style! { "gap" => 5, "align" => "center", "justify" => "center",
"width" => "100%", "height" => "100%", "bg" => "surface.base" }))
}
}
fn main() -> std::io::Result<()> {
let mut app = App::new("Counter", "counter.example");
app.mount("counter", || Box::new(Counter::default()));
Arc::new(app).run(Listen { port: 5098, ..Listen::default() })
}
EUI_ALLOW_INSECURE_LOOPBACK=1 eui ws://127.0.0.1:5098/_eui/session/counter
Pressing the button sends one SetText. Not a page, not a diffed DOM,
not a frame of JSON: the style records went once, at mount, and every later
render names them by id.
What a view is
A value, and a pure function of the state. dsl builds them, but there is
nothing behind the helpers: print one and you have the whole document.
Node::new("box")
.style(style! { "display" => "column", "gap" => 4 })
.child(text("Hi", style! { "size" => "lg" }))
k one of the seventeen primitive kinds. Everything a person would
call a widget — button, dialog, table, date picker — is composed from these
on the server, which is why the catalogue grows without shipping a new
client.
s a flat style list in the spec's own vocabulary, written with
style!. An unknown key is an error, not a key that does nothing.
c children, t text, p props, on handlers, key
identity for reconciliation.
eui.solisoft.net/components is the
reference for all of it — every node key, all seventeen kinds, every style
key and all thirty-three colour roles, the event names, and the catalogue of
composed widgets, each shown with the hash it returns. It is written against
Soli, and the vocabulary is the protocol's, so a style hash on that page is
the same style here. Also worth the visit:
the running demo,
the controls every widget is built from,
and what is not there yet.
Colour is a role — surface.raised, text.muted, danger.base — never
a literal. The client resolves it against the viewer's theme, so the page is
right in dark mode without this server ever learning which mode they are
in. Sizes are scale indices, by index or by name: "size" => "lg",
"gap" => 4, "radius" => "md".
This crate ships the primitives plus a few composed widgets — button,
card, field, divider, spacer. Anything else in the catalogue is a
function that returns a node, so it ports by writing the same node.
What a handler is
One method, and the name is the view's rather than the event kind's: a
node saying ("wake", "tick") arrives as "tick".
fn handle(&mut self, name: &str, params: &Params, _: &Ctx) -> ViewResult<()> {
if name == "pick" { self.selected = params.string("id"); }
Ok(())
}
Params carries node, kind, payload and props — the node's props as
the server last rendered them. That last one is what lets one handler serve
ten thousand rows: put the identifying value on the node, not in the
handler's name.
A handler that returns an error leaves the state unchanged and the screen
right; it is a line in the log, not the end of somebody's session. A view
that cannot be encoded is the other way round: it fails identically on every
later render, so the session ends with Error 400 and the reason.
Ctx is the session as a component may speak to it: the viewport, what the
person granted, and ctx.handle() — a Send handle a timer or another
session can hold and wake this one with.
Running it
Arc::new(app).run(Listen { host: "0.0.0.0".into(), port: 5098 })
TLS is the one thing this crate hands to something else. The protocol's
floor is TLS 1.3 and the standard library has no TLS at all, so a
dependency-free server answers ws:// and belongs behind a terminator —
Caddy, nginx, a load balancer — that speaks wss:// to the window. The other
six libraries terminate it themselves. A release client refuses plain ws://
outright; a debug one takes EUI_ALLOW_INSECURE_LOOPBACK=1.
EUI_TRACE=1 on the server prints every frame and every event a session
sees, which is the first thing to reach for when a click does nothing.
Three endpoints and nothing else: /.well-known/eui (the signed manifest),
/_eui/asset/<blake3-hex> (content-addressed, immutable, served to anyone),
and the session itself.
let mut app = App::new("Books", "books.example");
app.key_path = Some("config/eui_publisher.pem".into());
app.capabilities = vec!["net.open"];
app.font("Space Grotesk", &["public/fonts/space-grotesk-400.ttf",
"public/fonts/space-grotesk-700.ttf"])?;
The publisher key is a PKCS#8 PEM — the same file the Ruby, Python, PHP, Node
and Go libraries read, so an application that changes language keeps its
identity and nobody's pin breaks. It is generated on first use and kept: a
client pins it against app_id on first run and refuses a different one
later.
The Ed25519 in here is TweetNaCl's arithmetic, and its scalar multiplication
adds on every bit and selects the result rather than branching on the nonce.
It is not fast, and it is not asked to be: a server signs its manifest once,
at boot.
What is here, and what is not
Implemented: the whole wire format of spec/02 (checked against the byte
vectors that document pins, the §8 example at exactly 150 bytes included,
both of its style records byte for byte), the session frames of spec/01,
the view encoder with its append-only tables, a keyed diff that reorders
through a Fenwick tree, assets, fonts, notifications, scroll_to and
focus_to, and the manifest.
Not yet:
- TLS, as above.
- Local handlers (
spec/07). A handler is a server round trip; the
bytecode a client runs for itself — the hover that answers without a
packet — is the next milestone.
- File transfers (
spec/01 §6): Upload and Blob are decoded and
dropped.
- Session resume (
spec/01 §4.1): a socket that breaks gets a fresh
session and a fresh Mount, which is a conforming answer and a worse one.
- The windowed
list's window event, and scene uniforms.
Against the other six
The same application, written seven times — in Soli, Ruby, Python, PHP,
JavaScript, Go and Rust, node for node. At 500 rows, one number changed:
9 bytes out of every one of them, and 2.4 ms out of this one against 26
for the slowest.
bench/README.md
has the tables, the method and the caveats; the applications and the one
driver that measures all seven live in clients/eui-ruby/bench of the
EUI repository.
Tests
cargo test
102 of them, and the ones worth reading are tests/proto.rs — the spec's own
§8 example, 150 bytes, byte for byte, both style records included, which is
what caught a u16 written the wrong way round — tests/apply.rs, which is a
client in forty lines that applies the server's ops and compares the tree it
ends up holding with the server's own, over every permutation of five keyed
rows and four hundred and eighty random edits, tests/ed25519_vectors.rs,
which is RFC 8032 §7.1, and tests/session.rs, which runs a real application
on a real socket and counts the ops a click costs.
Licence
MIT.