anza 0.6.0

Ultra-lightweight, zero-copy, cryptographically verified Server-Templated UI (STUI) engine
Documentation

A server-side template and dynamic fragment rendering library for Rust web applications.

What It Does

  1. Full-Page Rendering: Renders complete HTML documents configured with <template shadowrootmode="open"> Declarative Shadow DOM shells.
  2. Dynamic Fragment Envelopes: Renders targeted HTML partials inside JSON Envelope payloads for partial UI updates.
  3. Payload Verification: Signs dynamic payloads using HMAC-SHA256 or Ed25519, and checks received envelopes with anza::verify_envelope (version, freshness, slot, signature).
  4. Streaming: Helpers for Server-Sent Events (SSE) and WebSocket message formats.

Installation

Add anza to your Cargo.toml:

[dependencies]
anza = "0.6.0"

To enable Axum framework response helpers:

[dependencies]
anza = { version = "0.6.0", features = ["axum"] }

Usage

1. Initialize Engine

use std::sync::Arc;
use anza::Setup;

let mut setup = Setup::new("./templates");
setup.signing = Setup::hmac(b"your-secret-key-at-least-32-bytes");
let engine = Arc::new(setup.run().expect("Failed to load templates"));

setup.signing = Setup::ed25519("keys/origin.key", "keys/origin.pub")?; signs with Ed25519 instead (raw 32-byte key files; a missing file is an error). The default is no signature. Keys are checked in run(): an HMAC secret shorter than 32 bytes, a private key that is not a 32-byte seed, or a public key that doesn't match is a CRYPTO error at setup.

Other Setup fields: watch (reload on change, feature watch), fragments (allowlist of template names and dir/ prefixes for fragments), escape (HTML-escape {{x}} values) and max_template_bytes (default 1 MiB).

2. Render Full Pages

use anza::Page;

// templates/pages/home.html inside templates/layout/shell.html ({{content}})
let doc = Page::new("/")
    .param("title", "My Web App")
    .run(&engine)
    .expect("Failed to render page");

println!("{}", doc.html);

3. Render Signed JSON Fragments

use anza::Fragment;

let envelope = Fragment::new("card.html", "feed")
    .param("title", "New Article")
    .run(&engine)
    .expect("Failed to render fragment");

// {"v":2,"slot":"feed","ts":...,"html":"...","sig":"..."}
let json = serde_json::to_string(&envelope).unwrap();

4. Axum Integration Example (features = ["axum"])

use std::sync::Arc;
use anza::{Fragment, Page, Setup};
use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let mut setup = Setup::new("./templates");
    setup.signing = Setup::hmac(b"your-secret-key-at-least-32-bytes");
    let engine = Arc::new(setup.run().unwrap());

    let app = Router::new()
        .route("/", get({
            let engine = engine.clone();
            move || async move { Page::new("/").param("title", "Home").run(&engine).unwrap() }
        }))
        .route("/api/card", get({
            let engine = engine.clone();
            move || async move { Fragment::new("card.html", "feed").run(&engine).unwrap() }
        }));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Document and Envelope implement IntoResponse (Axum) and Responder (Actix-web) when the matching feature is on.

Templates

Templates use {{name}} and {{{name}}} placeholders and are parsed once at startup. By default both insert values as-is, so escape user input first with anza::escape_html. With setup.escape = true, {{name}} is HTML-escaped and {{{name}}} stays raw (use {{{content}}} in the shell). Errors display as [Anza:CODE] message; Error::code() returns the code. Template layout, rendering rules and signing are in the documentation.

Documentation

  • Guide and API reference: https://anzaui.github.io/rust/
  • Engine Contract: the behaviour shared by the Rust, TypeScript and Python engines (envelope format, signature v2, page resolution, escaping, error codes). tests/fixtures/ holds vendored copies of its golden fixtures.
  • Changelog

The docs are markdown in docs/ (pages and sidebar in docs/config.toml), built with anza docs and deployed to GitHub Pages by .github/workflows/docs.yml. To build them locally you need the Anza CLI and the anza repo's theme in .anza/:

git clone --depth 1 --branch v0.6.0 https://github.com/anzaui/anza .anza
ANZA=/path/to/anza docs/build.sh     # writes _site/, served under /rust/

Releasing

Versions are independent of the other engines and of the Anza CLI. release-please keeps a release PR open from the conventional commits on main (version bump in Cargo.toml and this README, plus a CHANGELOG entry).

  1. Merge the release PR. release-please tags the commit v<version> and creates the GitHub release.

  2. Publish to crates.io from that tag:

    git checkout v<version>
    cargo test --features watch
    cargo publish
    

License

MIT © 2026 aduki, Labs