Built on Rust's Async Ecosystem
A deep dive into the technology stack, operating modes, request lifecycle, and the lock-free concurrency model that makes Ferrum Edge fast.
Core Dependencies
Every dependency was chosen for performance, correctness, and Rust-native design.
Multi-threaded async runtime. Work-stealing scheduler maximizes CPU utilization across all cores.
Production-grade HTTP/1.1 and HTTP/2 implementation. Powers most of Rust's web ecosystem.
Pure-Rust TLS. No OpenSSL dependency, no C FFI, memory-safe TLS for all connections.
gRPC over HTTP/2. Used for both gRPC proxying and the CP→DP control channel.
IETF QUIC and HTTP/3 over UDP. 0-RTT connection establishment for repeat clients.
Compile-time checked SQL queries. Async connection pooling for PostgreSQL, MySQL, and SQLite.
Zero-copy deserialization of config, plugin configs, and API payloads. JSON and YAML support.
Structured, contextual logging with per-request spans. OpenTelemetry-compatible.
Atomic reference-counted pointer swaps. Config reads are wait-free. Updates are atomic. The key to zero-downtime reloads.
Sharded concurrent hash maps. O(1) lookups with no global lock. Routes, consumers, rate limiters — all DashMap.
High-performance allocator on Linux and macOS. Better multi-threaded allocation performance vs. system malloc.
Operating Mode Diagrams
:8000 / :8443
:8000 / :9000
:9000 / :50051
:8000/:8443
:8000/:8443
:8000/:8443
ferrum-edge migrate
Request Lifecycle
Connection Accept
tokio accepts the TCP/UDP connection on the configured port. TLS handshake (rustls) if applicable. Protocol detection via ALPN for HTTP/1.1 vs HTTP/2.
Config Load (Lock-Free)
Atomic ArcSwap load. O(1), no blocking. Returns Arc pointer to current config. All concurrent requests share the same config Arc without copying.
Route Matching
DashMap lookup by host → sorted route list. Longest prefix match. O(1) average, no linear scans. If no route matches, 404 is returned immediately.
Plugin Chain Execution
Plugins execute in priority order: IP restriction → authentication → authorization → transformation → before_proxy. Any plugin can short-circuit by returning a response directly.
Upstream Selection
Load balancing algorithm selects a healthy upstream from the pool. Health state checked via atomic bool. Connection acquired from per-host pool.
Proxy & Response
Request forwarded via hyper to upstream. Response streamed back through after_proxy plugin hooks. Response body buffered only if a plugin requires it (opt-in).
Logging Phase
log() hook called on all plugins. Async, non-blocking. Access logs, metrics, traces emitted. Arc to config dropped — if config was swapped, old version is freed here.
Atomic Config Swap
Data Structure Complexity Table
| Operation | Structure | Read | Write | Notes |
|---|---|---|---|---|
| Config access | ArcSwap | O(1) atomic | O(1) atomic swap | Wait-free reads |
| Route lookup | DashMap | O(1) | O(1) shard-lock | num_cpus × 4 shards by default |
| Consumer lookup | DashMap | O(1) | O(1) shard-lock | By API key or consumer ID |
| Rate limit check | DashMap + AtomicU64 | O(1) | O(1) CAS | Lock-free token bucket |
| Health state | AtomicBool per target | O(1) atomic | O(1) atomic | Per upstream target |
| Plugin lookup | DashMap | O(1) | Build-time only | Plugins registered once at startup |
| Load balancing (RR) | AtomicUsize | O(1) | O(1) fetch_add | Atomic counter mod N |
| Load balancing (hash) | Consistent hash ring | O(log V) | O(N log V) | V = virtual nodes (150) |
| Connection pool | DashMap + AtomicU64 | O(1) | O(1) shard-lock | Lock-free epoch cleanup |