DEV Community: itsuki

How Reading a Design Patterns Book Led Me to Audit My Rust Framework with UML and Merise

itsuki — Wed, 22 Jul 2026 23:20:33 +0000

I was reading a design patterns book. I got to the UML class diagrams — and I stopped.

Because the diagram on the page was describing something Rust already says in its own syntax. A struct is a class. Option<T> is a 0..1 association. Vec<T> is 1..N. Ownership is composition. The formalism I was looking at, drawn as boxes and diamonds, was the same information the compiler already had — just in a different notation.

Which led to an uncomfortable thought. If the type system already encodes what UML draws, then translating my code into UML shouldn't tell me anything new. It should be redundant. Unless the translation didn't line up — and everywhere it failed to line up, there would be a bug hiding in the gap.

So I tried it. I took Runique — my Rust web framework, v2.1.21 — and I modeled the framework itself, module by module, in UML for structure and Merise for the data. The intuition was mine; I used Claude to help verify each translation against the actual code, line by line. We found twenty-plus latent bugs. Three of them were security-relevant. None of them had shown up in cargo test, in tracing, or in the compiler.

This is what the gaps looked like.

What I couldn't see in my own code

Runique is a Django-inspired framework: Axum, SeaORM, Tera, edition 2024. It works. It's powered a real restaurant's booking site and runique.io itself in production for months — that's my dogfooding. But the audit I'm describing was on the framework, not on those sites. And that's exactly the problem — "it works" is the state in which bugs are hardest to see. The compiler is happy. The tests are green. tracing shows nothing because nothing is throwing.

The tools I reach for every day are all local. cargo check sees one function. A unit test sees one path. tracing sees one request. None of them step back and show you the shape of the whole thing at once — and some bugs only exist in the shape. A field that's pub when it should be pub(crate). A file written one step too early in a sequence. A type that diverges from the type it's supposed to match, three files away, behind a feature flag.

I needed an outside view of the code — without leaving the code. Not a rewrite, not a new tool, not a linter. A different representation of the same thing, precise enough that the discrepancies would be mechanical to spot.

Three notations, one structure

Here's the idea the book handed me, made explicit.

Rust's type system, UML class diagrams, and Merise data models are three notations for the same underlying facts: entities, their relationships, their cardinalities, their invariants. The GoF patterns are just the recurring shapes that show up across all three. Rust encodes them in the type system, where the compiler enforces them. UML and Merise encode them in a separate graphical formalism, where a human reads them. The translation between the two is almost mechanical:

Concept	Rust	UML / Merise
Entity	`struct`	Class / Entity
Mandatory 1..1	field by value: `T`	cardinality `1..1`
Optional 0..1	`Option<T>`	cardinality `0..1`
1..N	`Vec<T>` / `HashMap<K,V>`	cardinality `1..N`
Composition (owned)	`struct A { b: B }` or `Box<B>`	filled diamond
Aggregation (shared)	`&B` / `Arc<B>` / `Rc<B>`	hollow diamond
Refinement	AST → HIR → MIR	MCD → MLD → MPD

One caveat, because Rustaceans will (rightly) pounce otherwise: the ownership-to-composition mapping isn't perfect. Box<B> still owns, so it's composition, not aggregation; aggregation — a shared reference with an independent lifetime — is &B, Arc<B>, Rc<B>. The analogy is a lens, not a law. But it's a sharp enough lens that when the code and the diagram disagree, the disagreement is worth investigating.

That's the whole method in one sentence: model the code in a formalism the type system doesn't natively speak, and audit the places where the two representations refuse to agree.

Merise deserves a note here, because it's the unfamiliar one for most English-speaking readers. It's a French systems-modeling method from the 1970s, still taught in French CS programs today. It splits a data model into conceptual (MCD), logical (MLD), and physical (MPD) levels — and crucially, at the logical level it forces you to write down both the cardinality and the concrete type of every association. That second demand is what caught one of the bugs below.

The method: three lenses, no sampling

I didn't spot-check. The point of an audit is coverage, so I went module by module across the whole framework, with three lenses, each matched to what it's good at:

Merise for the data — an MCD and an MLD of every eihwaz_* framework table, with cardinalities, foreign keys, and physical types.
UML class diagrams for the structure — one per layer: engine, forms, admin, auth, middleware, migration, config.
Sequence diagrams for the dynamics — the request/CSRF/upload flow, login/session, admin CRUD. This is the lens that shows you order, which neither the code nor a class diagram makes visible.

Everything is Mermaid in Markdown, versioned next to the code. No binary tool, no separate app — the diagrams render on GitHub and travel with the repo. Each one ends with an "anomalies" section, consolidated into a single anomalies.md with severity and a file:line for every finding.

Now the interesting part.

Bug 1 — UML: a `pub` field that quietly bypassed CSRF

I'll open with the most interesting one — not the most severe, the most interesting, because it's the bug that best shows what this whole exercise is really about.

I was drawing the UML class diagram for Prisme, the type that holds a request's parsed-and-CSRF-checked body. The diagram made me write down, for each field, its visibility. And there it was:

Prisme
  + data: StrMap        ← public
  + csrf_valid: bool
  + checked_data() -> Option<&StrMap>   ← fail-closed accessor

data was pub. checked_data() — the accessor that returns the body only if CSRF passed — was right next to it. The moment those two sat in the same box on the diagram, the problem was obvious: why build a fail-closed gate and then leave the raw field public next to it?

The CSRF enforcement in Runique doesn't live in the middleware for HTML forms — it lives at the point of access. req.form() checks csrf_valid and refuses to hand you validated data if the token is bad. But if Prisme::data is pub, any handler — or, more to the point, any third-party code built on Runique — can read the raw body directly and skip the gate entirely, without ever knowing it did.

I want to be exact about the severity, because the honest version is more interesting than the scary one. My own code was clean: admin, login, and form() all check CSRF before touching the body. This was never an exploited hole in Runique itself. It was a footgun in the public API — a shape that let someone building on the framework bypass CSRF by accident. That's a framework-author's bug, not a break-in.

The fix is one keyword, and it's the whole point of the article:

pub struct Prisme {
    /// Parsed body/query data. **Crate-private**: user code cannot read the raw
    /// body without going through the CSRF gate (anomaly C2). External access only
    /// via checked_data() (fail-closed) or req.form().
    pub(crate) data: StrMap,
    pub csrf_valid: bool,
}

impl Prisme {
    /// Fail-closed accessor: returns body data only if CSRF is valid.
    pub fn checked_data(&self) -> Option<&StrMap> {
        if self.csrf_valid { Some(&self.data) } else { None }
    }
}

pub → pub(crate). The Rust visibility system now structurally guarantees that the only doors to the request body are the two that check CSRF first. It's not a convention, not a lint, not a code-review rule someone has to remember. The compiler will reject the bypass. Visibility as a security mechanism — that's what the UML diagram surfaced, because a class diagram forces you to write down the one property (pub vs pub(crate)) that the code lets you skim past.

Bug 2 — Sequence diagram: a file written before it was allowed to be

The second lens is the one that shows time. Here's the sequence diagram for a multipart form POST, as I drew it from the real pipeline:

sequenceDiagram
    participant C as Client
    participant MW as csrf_middleware
    participant P as prisme_pipeline
    participant AG as parse_multipart
    participant H as Handler

    C->>MW: POST multipart (csrf_token as a field, no header)
    Note over MW: mutating method, no X-CSRF-Token,<br/>form content-type → LET THROUGH<br/>("Prisme will validate")
    MW->>P: next.run()
    P->>AG: parse_multipart(req)
    AG->>AG: stream file → tmp (size cap, NO extension check)
    AG->>AG: rename tmp → MEDIA_ROOT/uuid.ext (COMMIT)
    Note over AG: file committed to its final,<br/>servable location BEFORE CSRF,<br/>validation, and the handler
    AG-->>P: final paths
    P->>P: check_csrf() → csrf_valid (flag only)
    P-->>H: Request
    H->>H: if form.is_valid() { ... } else { reject }
    Note over H: file already on disk in MEDIA_ROOT,<br/>never removed on rejection

Read top to bottom and the bug reads itself. The file gets renamed into MEDIA_ROOT — its final, potentially publicly-served location — before CSRF is checked, before the form validates, and before the extension filter (which lives later, in FileField::validate) ever runs. On any public endpoint that extracts a Request and accepts multipart, that meant:

Unauthenticated file writes. The file lands in MEDIA_ROOT no matter what happens next.
No extension filter at that stage — only a size cap. An .html, .svg, or .js could land in a served directory. If MEDIA_ROOT is served statically, that's a path to stored XSS.
Orphans on rejection. CSRF fails, validation fails, honeypot trips — the file is already written, and nothing cleans it up.

No unit test caught this because no unit test is shaped like the request lifecycle. The class diagram didn't catch it either — every individual method is correct in isolation. Only the temporal view, the one that lays out order, made "written before validated" visible as a single glance.

The fix moves the commit to the end. parse_multipart now writes to a non-served staging directory, and FileField::finalize — running after CSRF and validation — is the only thing allowed to commit:

// No commit here: files stay in staging. FileField::finalize (the only committer)
// moves them to their served destination after CSRF + validation. On rejection,
// staging is purged by sweep_stale_staging (best-effort, TTL). Errors are logged,
// never swallowed.
Ok(data)

One committer, one gate, running in the right order — and a TTL sweep for staging that never got promoted, with every failure logged rather than dropped on the floor.

Bug 3 — Merise: a foreign key that didn't match its target

The last one is the bug Merise's "write down the type" discipline caught, and it's a clean demonstration of why a separate formalism earns its keep.

Here's the MLD fragment — the logical model — for the junction table between users and groups:

erDiagram
    USER ||--o{ USER_GROUPE : "belongs to"
    GROUPE ||--o{ USER_GROUPE : "groups"
    USER {
        pk id "int OR bigint under big-pk"
    }
    USER_GROUPE {
        pk user_id FK "→ users.id"
        int groupe_id FK
    }

Merise made me write two things next to user_id: its cardinality (a mandatory FK into users.id) and its physical type. And users.id has a footnote — it's integer normally, but bigint under the big-pk feature flag. So I went to check that the FK column followed the same rule. It didn't:

// user_id was hardcoded .integer() — it must follow eihwaz_users.id, which becomes
// BIGINT under the big-pk feature, or the FK is a type mismatch and fails to create.
let mut user_id_col = ColumnDef::new(Alias::new("user_id"));
user_id_col.integer();   // ← always integer, even when users.id is bigint

sessions, history, and reset_tokens all propagated the feature flag to their user_id columns. This one junction table didn't. Under big-pk, on a strict database like Postgres, the foreign key is a type mismatch and fails to create — a broken migration that only shows up for the subset of users who flip that flag. The fix is mechanical once you've seen it:

let mut user_id_col = ColumnDef::new(Alias::new("user_id"));
#[cfg(feature = "big-pk")]
user_id_col.big_integer();
#[cfg(not(feature = "big-pk"))]
user_id_col.integer();
user_id_col.not_null();

The compiler could never have caught this — both branches compile fine; they're just describing a database that won't build. Merise caught it because it made the type an explicit thing I had to write down and compare, instead of something buried in a ColumnDef builder call three files away from its counterpart.

The real discovery wasn't the bugs

Here's the twist I didn't expect. The bugs were the goal of the exercise. But they weren't the most valuable thing it produced.

The most valuable thing was the map.

By the end I had an architectural understanding of Runique that I — its author — did not have when I started. Not a vague "I know my codebase" feeling, but a precise, drawn, versioned model of every layer and every data flow. The bugs were a byproduct of building that map. The map is the asset.

Two things convinced me of that. The first was the verified false positives. I didn't just log the real bugs; I logged every hypothesis I was sure of that turned out to be wrong. I was convinced makemigrations couldn't handle ALTER COLUMN — false, it uses a full schema diff I'd forgotten I wrote. I was convinced two session-write paths produced a divergent session_id — false, the on_conflict clause makes it deterministic. Documenting the things you were wrong about is what separates an audit from a victory lap, and it's the part most people would quietly delete.

The second was the transverse themes. Once the bugs were on one page, they stopped looking like twenty separate bugs and started looking like four repeated anti-patterns: errors swallowed in silence; two sources of truth for one fact; security operations in the wrong order; a feature flag that didn't propagate everywhere it needed to. That's the jump from "fix the bug" to "extract the rule" — and you can only make it when you can see all the instances at once. The map is what let me see them at once.

How to do this to your own project

If you want to try it, the method compresses to a few rules:

Start with one module, one layer. Don't model the whole thing on day one; model the part you've started to distrust.
Match the lens to the question. Data integrity → Merise. Structure and visibility → UML class diagrams. Ordering and lifecycle → sequence diagrams. Most bugs live in exactly one of those three views and are invisible in the other two.
Keep the tooling trivial. Mermaid in Markdown, committed with the code. It renders on GitHub and it diffs like source, which means the diagrams stay honest instead of rotting in a wiki.
Log your false positives as carefully as your bugs. The discipline is the whole value. An audit that only records wins is marketing.

And one honest warning: this takes real time. It is not worth it on a weekend project. It's worth it on a production codebase you've started to distrust — the one that works, that passes its tests, and that you've nonetheless got a quiet feeling about. That feeling is usually right, and this is how you find out what it's pointing at.

Closing

The loop back to the book that started it is this. When I modeled Runique, I found patterns already in it — Builder, Template Method, Composite, Strategy — that I had never deliberately placed. They'd emerged on their own, because they're the shapes a problem like this pushes you toward. The book didn't teach me to add them. It gave me the vocabulary to see the ones that were already there, and the modeling gave me the visual proof they existed.

The full set of diagrams — every UML class diagram, the Merise data model, and the sequence flows, each with its own anomalies section — lives in the diagramme/ folder on GitHub. Runique itself is on crates.io and GitHub, docs at runique.io. More of this audit is becoming its own series: security-through-visibility, a sweep of every swallowed error, and the full list of verified false positives.

One question for the comments, because I genuinely want to know: have you ever used a modeling formalism to audit code you'd already written — and what did it reveal that the code itself was hiding?

I Built a Django-Inspired Web Framework in Rust — Here's What I Learned

itsuki — Sun, 14 Jun 2026 14:18:48 +0000

If you've ever used Django, you know the feeling: one command, and you have an admin panel, an ORM, form validation, middleware, session handling — everything just works. Then you try Rust web development, and you're back to assembling pieces yourself.

That's why I built Runique: a batteries-included web framework for Rust, inspired by Django's philosophy, built on top of Axum and Tokio.

Why "Django for Rust"?

Existing Rust frameworks are excellent at what they do — Axum is fast and composable, Actix-Web is a performance beast — but they're low-level by design. You bring your own ORM, your own session store, your own CSRF protection, your own admin interface. For many projects, that's the right tradeoff.

Runique takes the opposite bet: convention over configuration, with a structured, opinionated setup that gets you from zero to a production-ready app fast, without sacrificing Rust's safety and performance.

The Builder: A Validated Construction Pipeline

The part I'm most proud of is the application builder. You declare your components with a fluent API — in any order — and then a single .build() call runs a fixed, validated construction pipeline at startup:

Validation → DB connection → Templates → Engine → Admin → Middleware → Static files

Here's what a typical app setup looks like:

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    password_init(PasswordConfig::auto_with(Manual::Argon2));
    set_lang(Lang::En);

    let config: RuniqueConfig = RuniqueConfig::from_env();

    let db_config = DatabaseConfig::from_env()?.build();
    let db: DatabaseConnection = db_config.connect().await?;

    builder::new(config)
        .with_log(|l| {
            l.dev()
                .host_validation(tracing::Level::WARN)
                .acme(tracing::Level::INFO)
        })
        .routes(url::routes())
        .with_database(db)
        .with_mailer_from_env()
        .with_password_reset::<BuiltinUserEntity>(|pr| {
            pr.forgot_template("auth/forgot_password.html")
                .reset_template("auth/reset_password.html")
        })
        .statics()
        .middleware(|m| {
            m.with_session_memory_limit(5 * 1024 * 1024, 10 * 1024 * 1024)
                .with_session_cleanup_interval(5)
                .with_allowed_hosts(|h| {
                    h.enabled(!is_debug())
                        .host("runique.io")
                        .host("www.runique.io")
                        .host("localhost:3000")
                        .host("127.0.0.1:3000")
                })
                .with_csp(|c| {
                    c.policy(SecurityPolicy::strict())
                        .with_header_security(true)
                        .with_upgrade_insecure(!is_debug())
                        .scripts(vec!["'self'", "'strict-dynamic'"])
                })
        })
        .with_admin(|a| {
            a.site_title("Administration")
                .sitemap("https://runique.io/sitemap.xml")
                .auth(RuniqueAdminAuth::new())
                .routes(admins::routes("/admin-runique/"))
                .templates(|t| t.with_dashboard("admin/test_dashboard.html"))
                .with_state(admins::admin_state())
                .with_rate_limiter(RateLimiter::new().max_requests(20).retry_after(3600))
                .with_login_guard(LoginGuard::new().max_attempts(20).lockout_secs(300))
                .page_size(15)
        })
        .build()
        .await
        .map_err(|e| -> Box<dyn std::error::Error> { Box::new(e) })?
        .run()
        .await?;

    Ok(())
}

The .build() call validates every component — including cross-dependencies — before constructing anything. If your SECRET_KEY is still the default insecure value in production, the build fails with a clear error and a fix suggestion, before a single request is served:

[Security] SECRET_KEY is using the default insecure value
  → Set SECRET_KEY to a random 32+ character string in your .env file

This is the Django check framework equivalent, but enforced at startup — not discovered in production.

Security Included by Default

Security in Runique isn't a plugin you add later. It's part of the construction pipeline itself:

CSP (Content Security Policy) — configurable profiles, per-request nonce, HTMX hash merging when the admin panel is enabled
CSRF protection — built into the middleware stack, with per-route exemptions
Host validation — allowed hosts checked before routing
Trusted proxies — explicit configuration, not implicit trust
Security headers on static files — X-Content-Type-Options, Strict-Transport-Security, X-Frame-Options, Referrer-Policy applied automatically

// You don't wire ServeDir yourself — `.statics()` does it,
// already wrapping every static/media route with security headers:
{% static "path" %}
// → X-Content-Type-Options: nosniff
//   Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
//   X-Frame-Options: DENY
//   Referrer-Policy: strict-origin-when-cross-origin
//   + cache-control

The middleware stack uses numbered slots to guarantee application order — you can't accidentally apply CSRF before sessions, because the slots enforce the correct sequence.

What's Included

ORM (via SeaORM, optional feature flag)
Template engine (Tera, with custom filters and a URL registry for named routes)
Admin panel (auto-generated from your models, merged before the middleware stack so it always has session/auth context)
Form engine (typed structs with validation, v2 in progress)
Session handling (memory-first store with database fallback, built on tower-sessions, with periodic cleanup)
i18n (the FR/EN bilingual doc site is itself built with Runique)
Middleware system with ordered slots
Password reset (pluggable, routes registered automatically during build)
Debug error page — a styled page with collapsible sections and copy-to-clipboard for stack traces

One Concrete Example: Admin Merge Order

Here's a subtle design decision that illustrates Runique's philosophy. In Axum, .layer() only applies to routes present at call time. This means if you merge your admin router after applying middleware, the admin routes run without session, CSRF, or extension context — a silent, hard-to-debug failure.

Runique handles this in the builder:

// Step 4b: admin + password reset — merged BEFORE the middleware stack.
// `.layer()` in Axum only covers routes present at call time;
// merging after means admin routes run without Session/CSRF/Extensions.
let router = if self.admin.enabled {
    router.merge(admin_router)
} else {
    router
};

// Step 5: middleware applied AFTER, covering everything including admin
let (router, session_store) = middleware.apply_to_router(router, config, engine, tera);

You don't have to think about this. The pipeline handles it.

Current Status

Runique is at v2.1.x, MIT licensed, with bilingual documentation (EN/FR) at runique.io.

The framework is used in production for a restaurant management system — dogfooding at its most direct.

What's missing (being honest here, Django-style):

No async task queue yet (background jobs run on bare tokio::spawn)
Email sending is partial
OAuth is planned but not yet implemented
Test coverage is at ~61% (growing)

Try It

Add the dependency to your Cargo.toml:

[dependencies]
runique = "2.1"

Read the Getting Started Guide

Links & Resources

seb-alliot / runique

A framework web base on Django/python

Runique — the Django developer experience, in type-safe Rust

Declare a model once — get the database table, the migration, a type-safe form and a full admin panel. Runique is a batteries-included web framework that brings Django's productivity to Rust, without giving up Rust's safety and performance. Built on Axum, SeaORM and Tera.

Status — honest: active development. The framework crate (runique) is the source of truth; demo-app is a real validation app exercised against it. The admin is in beta. Nothing below is overstated — see Project status.

🌍 Languages: English | Français

Declarative macros, not boilerplate

model! {
    Article,
    table: "articles",
    pk: id => Pk,
    enums: { Status: [Draft="Draft", Published="Published"], },
    {
        title:  text [required],
        slug:   text [unique],

…

View on GitHub

Documentation: runique.io
Crates.io: crates.io/crates/runique

What do you think?

I'm particularly curious to hear from:

Django developers — Does this structure feel familiar, or "too much" for the Rust ecosystem?
Rust experts — How would you handle the middleware ordering differently?

Let's discuss in the comments!