Repository navigation
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.
| 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 |
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.
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, ¶ms).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
}- The server-side statement timeout is the primary stop.
- After a client-side cancel, the connection is never reused unless the query's error arrived within the grace period.
- 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.
- 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().awaitreturns 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.
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.
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.
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.
- cargo-nextest; testcontainers with PostGIS; insta JSON snapshots per feature; tower
oneshothandler 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.
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.
| 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 |
Estimated roughly a fifth more than the Go design, mostly from compile cycles, the cancellation guard and async ergonomics. See Stack Comparison.
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
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference