h5i-app
The Axum-based application framework for h5i. Write application logic in Rust and prove its properties in Lean 4.
h5i-app was developed as i5h and moved into the h5i workspace, where it sits next to h5i's red-teaming tools: they test the running application for what you did not anticipate, and h5i-app proves the properties you can state. The i5h repository now hosts the benchmark.
[]
= { = "0.1", = ["http", "postgres"] }
| Crate | Role |
|---|---|
h5i-app |
the entry point: re-exports the crates below behind features |
h5i-app-core |
the Kernel contract and an in-memory reference engine |
h5i-app-http |
axum integration: Actor, H5iApp::respond, rpc_router |
h5i-app-pg |
the PostgreSQL engine |
h5i-app-schema |
schema!: row types, table mappings, generated Lean |
h5i-app-sql |
write sets to keyed SQL statements (extracted, proven) |
h5i-app-pgsql |
statements to PostgreSQL text (extracted, proven) |
h5i-app-json |
the reply JSON writer (extracted, proven) |
h5i-app-token |
bearer-token encoding and parsing (extracted, proven) |
h5i-app-std |
byte strings, sets, maps, reachability and expiry checks for kernels (extracted, proven) |
A kernel crate depends on h5i-app-sql, h5i-app-schema and, for text,
sets or maps, h5i-app-std directly, so that extraction sees only the code
it translates.
High level features
- Write the logic as pure Rust functions and prove it in Lean 4 via Aeneas.
- Serve it with axum; handlers never touch the database.
- Run each request in a SERIALIZABLE PostgreSQL transaction, with retries and idempotency keys.
- Declare tables once with
schema!and get Rust mappings and Lean proofs. - Prove that invariants hold for the rows loaded back from the database.
- Prove properties across requests, for every order in which clients' requests commit.
flowchart LR
H["HTTP transport: axum, hyper (trusted)"] --> K["kernel (extracted)"]
K --> S["storage: plan, SQL compiler (extracted)"]
S --> DB["engine, PostgreSQL (trusted)"]
K -. Aeneas .-> A["kernel proofs"]
S -. Aeneas .-> B["storage proofs"]
DB -. "SQL model" .-> B
SP["Spec (reviewed)"] --> A
A --> D["db_inv"]
B --> D
Usage example
The kernel is one function that decides what a command does. This one, from the calculator tutorial, keeps one number per user:
The server around it is an ordinary axum application:
let engine = new;
engine.install_schema.await?;
let app = new;
let router = new.route.merge;
serve.await?;
pool connects over plain TCP. With the tls feature, pool_tls(&url, 8, &Roots::PemFile(ca)) encrypts every connection and verifies the server's
certificate chain and host name (libpq's verify-full); a server without TLS
is refused, never used in the clear. Use Roots::WebPki for a publicly
trusted certificate, or the provider's CA bundle (e.g. Amazon RDS's) as a PEM
file. lockdown_tls does the same for lockdown. SCRAM channel binding
(SCRAM-SHA-256-PLUS) is offered for RSA (PKCS#1 v1.5) and ECDSA server
certificates; add channel_binding=require to the URL to insist on it.
After the kernel is translated to Lean, you can prove properties of it, for
example that after any successful command a get by the same user returns its
result:
theorem get_after (a : Principal) (s s' : Snapshot) (c : Command) (w : Option Memory) (v : U64)
(hroom : s.memories.length < Usize.max)
(ht : transition a s c = ok (.Ok (w, .Value v))) (hs : apply s w = ok s') :
transition a s' .Get = ok (.Ok (none, .Value v))
License
This project is licensed under the Apache-2.0 license.