Skip to content

Architecture Rust

mavrovde edited this page Nov 1, 2026 · 2 revisions

Architecture: Rust

The alternative candidate. This page describes how the language-neutral design on Architecture Overview would be built in Rust. It is a design; nothing is implemented yet. Versions are those current at the time of evaluation.

In short: one static musl binary built from axum 0.8 on tokio with tower / tower-http, tokio-postgres + deadpool-postgres, utoipa for OpenAPI 3.1, and clorinde generating typed queries from the read contract. A cargo workspace whose crate boundaries enforce the hexagon. The 2 second deadline uses the statement timeout as the primary stop plus an explicit cancel guard. Estimated 10–30 MB resident memory; image target 15 MB or less.

Stack

Concern Choice Why Alternatives rejected
Runtime tokio (multi-thread, worker count configurable) ecosystem default; timeouts; cancellation tokens async-std (discontinued), smol (small ecosystem)
HTTP axum 0.8 on hyper 1 tower-native middleware, extractors, typed state actix-web (own model), poem, warp (slow-compiling filter types)
Middleware tower and tower-http (request id, trace, sensitive headers, CORS, compression, limits, panic catching) composable layers; the API's gates are layers too hand-written services
OpenAPI 3.1 utoipa + utoipa-axum code-first from derives and attributes; routes and docs registered together aide (fewer users), dropshot (own server)
Driver tokio-postgres + deadpool-postgres explicit cancel token (wrapped, see below); binary protocol; prepared-statement cache sqlx (dropping a future does not cancel the server query), Diesel (synchronous core)
Queries clorinde typed Rust from .sql, checked against the contract stub in a throwaway database at generate time hand-written row access (no check), sea-query (a builder, no check)
Access-store migrations refinery plain embedded SQL sqlx-based migrators
Configuration figment + a declaration table; TOML file layering; errors name the key path and the provider config-rs (fallback behind the same loader trait)
Rate limiting governor (GCRA) per key exact; "not until" gives Retry-After per-IP-shaped wrappers
Admission own module priority, reserved shares, aging, estimate; permit released on drop the FIFO semaphore
Cache moka (future cache) weigher, per-entry expiry, single-flight quick_cache, mini-moka
Crypto RustCrypto hmac + sha2; OS randomness audited, pure Rust, constant-time verify ring (fine; not needed)
Errors thiserror + a project Problem type RFC 9457 in a few dozen lines small third-party crates
Logs, traces, metrics tracing (JSON), tracing-opentelemetry, OTLP; metrics + Prometheus exporter standard log + env_logger
Allocator mimalloc musl's allocator is slow under concurrency jemalloc (larger resident memory)
Geometry geo-types + polyline route decoding only geo (algorithms not needed)
Tests cargo-nextest, testcontainers (PostGIS), insta snapshots, proptest, cargo-fuzz, cargo-llvm-cov, jsonschema — —
Quality clippy (warnings as errors), rustfmt, cargo-deny, cargo-audit, oasdiff, Spectral — —
Documentation Scalar + Astro Starlight — Redoc

Workspace layout (planned)

The cargo workspace is the hexagon: a crate cannot import what its manifest does not list.

viafrei-api/
├── crates/
│   ├── domain/         # pure: geometry types, errors, time; no tokio, no serde
│   ├── app/            # use cases, one module per feature
│   ├── store/          # the ONLY crate that knows the read contract (clorinde output, mapping tables, deadline execution)
│   ├── access-store/   # keys, plans, audit, usage + migrations
│   ├── http/           # axum routers, DTOs with schemas, problems, GeoJSON, tower layers
│   ├── runtime/        # config, admission, rate limit, metering, telemetry, cache
│   └── bin/            # serve | migrate | keys | usage | config {check,show,docs} | openapi | version
├── xtask/              # scope lint, config lint, docs lint, contract-stub generation
├── contract/  api/openapi.json  docs/  bench/  test-data/  fuzz/
└── Dockerfile  deny.toml  rust-toolchain.toml

Dependency direction: bin → http, store crates, runtime → app → domain. domain and app never depend on the driver, axum or serde; a cargo-deny ban rule and a metadata test assert the graph.

#[async_trait::async_trait]
pub trait SituationReader: Send + Sync {
    async fn in_corridor(&self, s: &RequestScope, c: &Corridor, w: TimeWindow, f: &Filter)
        -> Result<(Vec<RoadSituation>, ProvenanceSet), PortError>;
}

RequestScope carries the deadline, the allowed families, the language, the key id and the tier as plain data. Ports use dyn traits to keep compile times and readability reasonable; the allocation per call is negligible.

Deadline and cancellation: the cancel guard

tokio-postgres documents cancellation as racy: a cancel can reach the server after the query finished and hit the next statement. The design handles that explicitly:

let token = client.cancel_token();
let guard = CancelGuard::new(token);   // on drop, unless disarmed: spawn token.cancel_query(...)
let tx = client.build_transaction().read_only(true).start().await?;
tx.batch_execute(&format!("set local statement_timeout = {}", remaining.as_millis())).await?; // a number from a Duration only
let rows = tokio::time::timeout(remaining, query.bind(&tx, &params).all()).await;
match rows {
    Ok(r)  => { tx.commit().await?; guard.disarm(); Ok(r?) }
    Err(_) => { guard.cancel_now().await; Err(PortError::Deadline) } // connection discarded unless it answered within the grace period
}
  1. The server-side statement timeout is the primary stop.
  2. After a client-side cancel, the connection is never reused unless the query's error arrived within the grace period.
  3. The guard also fires when the request future is dropped (the client went away).

The cancellation test covers both the timeout path and the dropped-future path, and a stress test of a thousand iterations must never reuse a poisoned connection.

Keys, limits and admission

  • HMAC-SHA-256 with constant-time verification; secrets wrapped in a newtype that prints <redacted> and cannot be serialised.
  • Key cache in moka with single-flight loading; revocations arrive through a PostgreSQL notification stream.
  • Rate limit: a governor limiter per key, held in moka with idle expiry; "not until" becomes Retry-After.
  • Admission: a mutex-guarded state with three queues of waiters, each holding a one-shot sender. acquire().await returns a permit whose drop runs dispatch, so a cancelled request structurally cannot leak a permit. A waiter dropped while queued is skipped. Tested with tokio's paused clock (deterministic), and with loom on the core state machine if the benchmark shows contention.
  • Composed features: a buffered stream with bounded parallelism and a per-part deadline.
  • Metering: a mutex-protected map swapped at each flush, then one batched upsert.

Caching

moka future cache with a byte weigher, per-entry expiry and single-flight; xxh3 ETags; compression via tower-http.

Memory item (estimate) Size
Binary and runtime ~5–8 MB idle
Result cache 16 MiB (configurable)
Key cache a few MB
Connections about 0.5 MB each

Estimated steady state 10–30 MB; container limit 64 MiB possible, 96 MiB as the safe default; two worker threads by default.

OpenAPI and errors

OpenApiRouter registers each handler together with its documentation, so routes and docs cannot diverge. Path attributes declare parameters, both JSON and GeoJSON content types, problem responses and the scope and MCP-counterpart extensions. Problem implements IntoResponse. The openapi subcommand writes the same document that /openapi.json serves.

Configuration

A constant declaration table (path, type, default, bounds, description, secret flag) is checked one-to-one against the configuration struct, which denies unknown fields. Defaults, then a TOML file (YAML is avoided because the common Rust YAML crate is unmaintained), then environment variables with __ for nesting. All violations are collected; figment's metadata names whether the file or the environment supplied the bad value. See Configuration.

Testing and CI specifics

  • cargo-nextest; testcontainers with PostGIS; insta JSON snapshots per feature; tower oneshot handler tests; every recorded response validated against the OpenAPI document; Schemathesis against the booted container.
  • proptest for corridor arithmetic, area bounds, cursor round-trips and the licence gate; cargo-fuzz (nightly toolchain only for fuzzing).
  • clippy with warnings as errors, cargo-deny (licences, bans, advisories), daily cargo-audit, CodeQL for Rust.
  • release-please with the Rust release type.

Container image

Static musl build with thin LTO and stripped symbols, copied into a scratch image as a non-root user. Image target 15 MB or less compressed. CA certificates are added when a TLS connection needs them.

Risks

Risk Mitigation
AI-agent fluency: slower convergence on async lifetimes, Send bounds, trait objects and generic tower layers; longer compile-and-fix cycles async-trait and dyn ports, no custom generic service stacks, strict clippy, small crates, build caches
Compile times thin LTO only in release; nextest; caches
Racy cancel in the driver statement timeout first; discard on doubt; stress test
clorinde and figment are smaller or slower-moving projects both behind the project's own traits; fallbacks are hand-mapped queries with a prepare test, and config-rs
Macro-heavy OpenAPI annotations drifting from handlers routes and docs registered together; response validation and Schemathesis
A second toolchain beside the platform self-contained repository; the contract file is the only coupling

Relative effort

Estimated roughly a fifth more than the Go design, mostly from compile cycles, the cancellation guard and async ergonomics. See Stack Comparison.

Sources

axum https://docs.rs/axum · tower-http https://docs.rs/tower-http · utoipa https://github.com/juhaku/utoipa · tokio-postgres https://docs.rs/tokio-postgres · deadpool-postgres https://docs.rs/deadpool-postgres · clorinde https://crates.io/crates/clorinde · refinery https://docs.rs/refinery · figment https://docs.rs/figment · governor https://docs.rs/governor · moka https://github.com/moka-rs/moka · tracing https://docs.rs/tracing · cargo-deny https://github.com/EmbarkStudios/cargo-deny · cargo-fuzz https://github.com/rust-fuzz/cargo-fuzz · proptest https://docs.rs/proptest · insta https://insta.rs · PostgreSQL cancel protocol https://www.postgresql.org/docs/16/protocol-flow.html#PROTOCOL-FLOW-CANCELING-REQUESTS

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally