Chapter 1

A high-performance, concurrent, dual-engine (L4/L7) reverse proxy and load balancer engineered in Rust.

Iron-Proxy is designed for modern enterprise infrastructure, featuring mathematical latency-aware routing, automatic request resilience, and zero-downtime operations. Built on top of tokio and hyper, it safely multiplexes raw TCP streams alongside HTTP traffic without blocking the main event loop.

✨ Enterprise Features

• Dual-Engine Multiplexing: Run raw Layer 4 (TCP) and Layer 7 (HTTP) proxies side-by-side from a single binary.
• Advanced Load Balancing: Lock-free, highly concurrent routing using Peak EWMA (Exponentially Weighted Moving Average) for HTTP, Least Connections for TCP, and IP Hashing for stateful Sticky Sessions.
• Zero-Downtime Hot Reloading: Modify your iron-proxy.toml on the fly. The proxy watches for file system events and safely swaps configuration states without dropping active client connections.
• Self-Healing Resilience: Features asynchronous background health checks and automatic L7 request retries with in-memory body buffering for 5xx backend errors.
• First-Class Observability: Native Prometheus /metrics endpoint and strict, structured JSON telemetry for seamless Datadog/Grafana integration.
• Unix Daemonization: Production-ready CLI with native background process management.

⚙️ Architecture & Internals

Iron-Proxy is architected for maximum throughput and minimal tail latency.

🔒 Lock-Free State Management

The internal ConnectionTracker uses:

• DashMap for concurrent shared state
• Raw 64-bit atomic floating-point math via AtomicU64 bit-casting

This enables latency metrics to be updated in sub-microsecond time without traditional Mutex thread locking.

Atomic updates → zero lock contention → lower tail latency

💻 Command Line Interface

🚀 Quick Start

Installation

Pre-compiled binaries for Linux, macOS (Apple Silicon/Intel), and Windows are available.

1. Download the latest binary from the Releases tab.
2. Extract the executable and add it to your system $PATH.

(Alternatively, build from source: cargo install --path .)

Running the Proxy

Generate the default configuration file in your current directory:

iron-proxy init

Start the proxy in the background (Daemon mode):

iron-proxy start

Check the real-time cluster status:

iron-proxy status

Quick Start

Getting Iron-Proxy running in your environment takes less than a minute. The proxy is distributed as a single, statically compiled binary with no external dependencies.

Installation

Download the latest release for your operating system from the GitHub Releases page.

# Example for Linux x86_64
wget [https://github.com/thecoderbee/iron-proxy/releases/download/v4.0.3/iron-proxy-linux-amd64](https://github.com/thecoderbee/iron-proxy/releases/download/v4.0.3/iron-proxy-linux-amd64)
chmod +x iron-proxy-linux-amd64
sudo mv iron-proxy-linux-amd64 /usr/local/bin/iron-proxy

Initialization

Generate the default configuration file in your current directory:

iron-proxy init

This will create an iron-proxy.toml file containing a standard Layer 4 and Layer 7 cluster setup.

Running the Proxy

Validate your configuration syntax before starting:

iron-proxy check -c iron-proxy.toml

Start the proxy in the foreground (ideal for Docker/systemd):

iron-proxy run -c iron-proxy.toml

(Unix Only) Start the proxy as a detached background daemon:

iron-proxy start

Configuration Reference

Iron-Proxy uses a strictly typed TOML configuration schema (iron-proxy.toml). The configuration is hot-reloadable; saving changes to this file on disk will seamlessly update the routing rules without dropping active TCP or HTTP connections.

Global Settings

[admin]
bind_addr = "127.0.0.1"
port = 9090

[rate_limit]
capacity = 1000.0      # Maximum burst allowance per IP
refill_rate = 50.0     # Tokens regenerated per second

Layer & (HTTP) Clusters

The [[clusters]] array defines HTTP/HTTPS reverse proxy targets.

[[clusters]]
name = "api_gateway"
mode = "http"
sticky_sessions = false
max_retries = 3 
targets = [
    "10.0.0.1:8080",
    "10.0.0.2:8080"
]

• max-retries: Enables in-memory body buffering to automatically retry requests against healthy nodes if a target returns a 5xx error.

• sticky-session: Override Peak EWMA routing to deterministically pin client IPs to specific backend nodes.

Layer 4 (TCP) Servers

The [[tcp_servers]] array defines raw byte-streaming proxies.

[[tcp_servers]]
name = "redis_cluster"
bind_addr = "127.0.0.1"
port = 6379
targets = [
    "10.0.1.1:6379",
    "10.0.1.2:6379"
]

The Dual-Engine Design

Iron-Proxy operates on a dual-engine architecture, completely isolating Layer 4 (Transport) and Layer 7 (Application) logic. Both engines share a highly concurrent, lock-free global state (via DashMap) for routing decisions, but they handle network I/O fundamentally differently.

Layer 4: Raw TCP Streaming

The L4 engine acts as a blind byte-shoveler.

• It intercepts the incoming TCP connection.
• Selects the upstream backend with the lowest active connection count.
• Establishes an outbound TCP socket.
• Uses tokio::io::copy_bidirectional to achieve maximum throughput with near-zero memory overhead.

Layer 7: HTTP/HTTPS Proxy

The L7 engine is protocol-aware and computationally heavier.

• Manages TLS termination via rustls.
• Parses HTTP headers and strips hop-by-hop metadata.
• Implements token-bucket rate limiting per IP address.
• Buffers request bodies in memory to facilitate zero-downtime automated retries on backend failure.

Mathematical Routing (Peak EWMA)

To prevent the “thundering herd” problem and avoid routing traffic to slow but technically healthy nodes, Iron-Proxy utilizes advanced mathematical heuristics.

Peak EWMA (Exponentially Weighted Moving Average)

For Layer 7 HTTP traffic, round-robin or simple least-connections is insufficient. Iron-Proxy tracks the latency of every request using atomic bitwise operations to update an EWMA score without thread-blocking mutexes.

The routing engine calculates a real-time penalty cost for each backend: Cost = (Active Connections + 1) * Peak Latency EWMA

This ensures that a server experiencing a sudden latency spike will be temporarily bypassed until its historical latency average cools down, preventing localized cascading failures.

Deterministic IP Hashing

If sticky_sessions are enabled for legacy stateful applications, Peak EWMA is bypassed. The client’s IP address is cryptographically hashed, and the modulo of the hash against the alphabetically sorted list of healthy backends ensures the client always hits the exact same server.

Resilience & Health Checks

Iron-Proxy is designed to assume that upstream networks are hostile and backend servers will inevitably fail.

Active Background Probing

A dedicated Tokio task runs outside the proxy engines, firing HTTP GET requests or TCP pings at the configured interval.

• If a backend fails to respond within the strict 2-second timeout, the DashMap registry instantly marks the node as Dead.
• The routing engine will immediately cease sending new connections to that node.
• The probe continues pinging; once the node returns a successful response, it is automatically reintroduced to the cluster.

Passive L7 Circuit Breaking

If the active probe hasn’t detected a failure yet, but the L7 proxy engine encounters an unexpected socket drop or 502 Bad Gateway from a backend, the L7 proxy acts defensively. It automatically retries the buffered request on another node, and proactively flags the failing node as Dead in the shared registry.

Command Line Interface

The Iron-Proxy binary provides a robust CLI for operational lifecycle management.

Daemonization Logs

When using the start command on Unix systems, standard output and errors are detached from the TTY and piped directly to iron-proxy.out and iron-proxy.err in the working directory.