# WarpDrive vs Aralez: Comprehensive Feature Comparison

## Executive Summary

Both WarpDrive and Aralez are Rust-based reverse proxies built on Cloudflare's Pingora framework, delivering high-performance HTTP proxying. However, they have distinct architectural philosophies and feature sets:

- **WarpDrive**: Application-focused proxy with built-in process supervision, multi-process orchestration, ACME integration, and WASM plugin support
- **Aralez**: Edge proxy with dynamic config reloading, service discovery (Consul/Kubernetes), and built-in authentication mechanisms

---

## Feature Comparison Matrix

### Core Proxy Capabilities

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Framework** | Pingora 0.6 | Pingora 0.6 | Both use Cloudflare's framework |
| **Language** | Rust | Rust | Memory safe, high performance |
| **HTTP/1.1** | ✅ Yes | ✅ Yes | |
| **HTTP/2** | ✅ Yes (ALPN) | ✅ Yes (automatic) | |
| **HTTP/3/QUIC** | ❌ Tracked (blocked on Pingora support) | ❌ Not mentioned | Not available in either |
| **WebSocket** | ✅ Yes (Protocol.Ws/Wss) | ✅ Yes (automatic) | WarpDrive: explicit in protocol config; Aralez: zero config |
| **gRPC** | ✅ Yes (Protocol.Grpc over HTTP/2) | ✅ Yes (automatic) | WarpDrive: explicit; Aralez: automatic detection |

---

### Load Balancing & Routing

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Load Balancing** | ✅ Round-robin (Pingora's LoadBalancer) | ✅ Round-robin, Failover, Sticky sessions | WarpDrive uses single strategy; Aralez: multiple strategies |
| **Multi-upstream Routing** | ✅ Path, host, method, header matching | ✅ Path, virtual host based | WarpDrive more flexible |
| **Path Transformation** | ✅ strip_prefix, rewrite | ✅ Path-based routing | |
| **Sticky Sessions** | ❌ No | ✅ Yes (cookie-based) | Aralez only feature |
| **Host-based Routing** | ✅ Yes | ✅ Yes | Both support |
| **Method-based Routing** | ✅ Yes | ⚠️ Limited | WarpDrive more explicit |
| **Header-based Routing** | ✅ Yes | ⚠️ Limited | WarpDrive supports header matching in routes |
| **Dynamic Route Updates** | ❌ No (config-based only) | ✅ Yes (hot reload, API) | **MAJOR DIFFERENCE**: Aralez reloads config live |

---

### TLS/SSL & Certificates

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **TLS Termination** | ✅ Yes (rustls + OpenSSL) | ✅ Yes (OpenSSL) | WarpDrive: dual support; Aralez: OpenSSL only |
| **HTTPS Support** | ✅ Protocol.Https | ✅ Yes | |
| **Manual Certificates** | ✅ Yes (WARPDRIVE_TLS_CERT_PATH) | ✅ Yes (proxy_certificates dir) | |
| **ACME/Let's Encrypt** | ✅ Yes (instant-acme, automatic provisioning) | ❌ No | **MAJOR DIFFERENCE**: WarpDrive only feature |
| **Auto Certificate Loading** | ✅ Startup provisioning | ✅ Directory watch (hot reload) | Aralez watches folder, WarpDrive provisions at startup |
| **Upstream TLS Detection** | ❌ Manual config required | ✅ Yes (automatic) | **MAJOR DIFFERENCE**: Aralez auto-detects backend TLS |
| **TLS Upstream (Protocol.Https)** | ✅ Explicit in config | ✅ Auto-detected | Different approaches |
| **TLS Grade Configuration** | ❌ No | ✅ Yes (high/medium/unsafe) | Aralez simplifies cipher selection |

---

### Authentication & Authorization

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Basic Auth** | ❌ No | ✅ Yes | **MAJOR DIFFERENCE** |
| **API Key (x-api-key)** | ❌ No | ✅ Yes | **MAJOR DIFFERENCE** |
| **JWT** | ❌ No | ✅ Yes (built-in JWT generation + validation) | **MAJOR DIFFERENCE** |
| **JWT Generation API** | ❌ No | ✅ Yes (/jwt endpoint with master_key) | Aralez specific |
| **JWT Token Methods** | ❌ N/A | ✅ URL param (araleztoken=TOKEN) or Bearer header | Aralez specific |
| **Custom Authentication** | ⚠️ Via WASM plugins | ❌ No plugin system | WarpDrive offers extensibility |

---

### Caching

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **L1 Memory Cache** | ✅ Yes (LRU, 64MB default, probabilistic eviction) | ❌ No | WarpDrive only |
| **L2 Redis Cache** | ✅ Yes (optional, auto-fallback) | ❌ No | WarpDrive only |
| **Cache Coordination** | ✅ L1 + L2 coordinator | ❌ No caching layer | **MAJOR DIFFERENCE** |
| **Distributed Cache** | ✅ Redis (vendor-agnostic backend architecture) | ❌ No | WarpDrive only |

---

### Rate Limiting & Resilience

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Rate Limiting (GCRA)** | ✅ Yes (per-IP, governor crate, GCRA token bucket) | ✅ Yes (per-IP per-virtualhost) | Both have per-IP limiting |
| **Global Rate Limit** | ⚠️ Env var configuration | ✅ Yes (per-virtualhost) | Aralez: per-path override |
| **Per-Path Rate Limit** | ❌ No | ✅ Yes (path-specific limits override global) | **MAJOR DIFFERENCE**: Aralez has granular control |
| **Circuit Breaker** | ✅ Yes (3-state: Closed/Open/Half-Open) | ❌ No | WarpDrive only |
| **Circuit Breaker States** | ✅ Closed → Open → Half-Open → Closed | ❌ N/A | WarpDrive only feature |
| **Failure Threshold Config** | ✅ Yes (configurable) | ❌ N/A | |
| **Concurrency Limiting** | ✅ Yes (max concurrent requests) | ❌ No | WarpDrive only |
| **Failover** | ⚠️ Via circuit breaker + load balancer | ✅ Yes (explicit failover strategy) | Different approaches |

---

### Observability & Metrics

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Prometheus Metrics** | ✅ Yes (HTTP requests, cache, circuit breaker, rate limit metrics) | ✅ Yes | Both supported |
| **Metrics Endpoint** | ✅ Yes (/metrics on port 9090) | ✅ Yes | |
| **Structured Logging** | ✅ Yes (tracing-based with request context) | ✅ Yes (log levels: info/warn/error/debug/trace/off) | |
| **Health Endpoints** | ✅ Yes (/health, /healthz, /ready, /up) | ❌ No | WarpDrive only |
| **TUI/Dashboard** | ✅ Yes (interactive TUI for monitoring) | ❌ No | **MAJOR DIFFERENCE** - WarpDrive specific |
| **Process Monitoring** | ✅ Yes (process state, health, metrics in TUI) | ❌ No | WarpDrive only |

---

### Process Management & Supervision

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Process Supervision** | ✅ Yes (multi-process manager + single supervisor) | ❌ No | **MAJOR DIFFERENCE** |
| **Single Process** | ✅ ProcessSupervisor | ❌ N/A | WarpDrive only |
| **Multi-Process** | ✅ ProcessManager with dependency tracking | ❌ N/A | WarpDrive only |
| **Process Restart Policies** | ✅ Yes (always, on_failure, exponential backoff, linear backoff) | ❌ No | WarpDrive only |
| **Health Checks (upstreams)** | ⚠️ Basic monitoring | ✅ Yes (HEAD, GET, POST; configurable interval) | Aralez more explicit |
| **Process Event Bus** | ✅ Yes (real-time process events) | ❌ No | WarpDrive only |
| **Process Lifecycle Hooks** | ✅ Yes (pre_start, cluster_ready, pre_shutdown, post_shutdown) | ❌ No | WarpDrive only |

---

### Clustering & Coordination

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Cluster Mode** | ✅ Yes (with leader election) | ❌ No | WarpDrive only |
| **Leader Election** | ✅ Yes (via Redis) | ❌ No | WarpDrive only |
| **Hook Coordination** | ✅ Yes (leader-only hooks via Redis) | ❌ No | WarpDrive only |
| **Multi-instance Support** | ✅ Yes (cluster name, instance ID) | ❌ No | WarpDrive only |
| **Service Discovery** | ❌ No (static config only) | ✅ Yes (Consul, Kubernetes) | **MAJOR DIFFERENCE**: Aralez dynamic |

---

### Configuration Management

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Environment Variables** | ✅ Yes (extensive env var support) | ⚠️ Minimal | WarpDrive: comprehensive env support |
| **TOML Configuration** | ✅ Yes (advanced routing, hooks, processes) | ❌ No | WarpDrive specific |
| **YAML Configuration** | ❌ No | ✅ Yes (main.yaml, upstreams.yaml) | Aralez only |
| **Config Validation** | ✅ Yes (CLI: warpdrive validate) | ❌ No | WarpDrive only |
| **Runtime Checks** | ✅ Yes (CLI: warpdrive check) | ❌ No | WarpDrive only |
| **Hot Reload Config** | ❌ No (requires restart) | ✅ Yes (file watch, API push) | **MAJOR DIFFERENCE** |
| **Remote Config Push API** | ❌ No | ✅ Yes (HTTP API with master_key) | Aralez only |
| **Daemon Mode** | ✅ Yes (-d flag, daemonize) | ✅ Yes (daemon: true) | |
| **PID File Management** | ✅ Yes (with lock file) | ✅ Yes | Both supported |

---

### Middleware & Request Processing

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Static File Serving** | ✅ Yes (direct, bypasses backend; 600+ req/s) | ✅ Yes (built-in minimalistic file server) | WarpDrive: higher performance; Aralez: simpler |
| **X-Sendfile** | ✅ Yes (backend-controlled file serving) | ❌ No | WarpDrive only |
| **X-Forwarded Headers** | ✅ Yes (configurable) | ✅ Yes (automatic) | |
| **Gzip Compression** | ✅ Yes (automatic, pre-compressed .gz support) | ❌ No | WarpDrive only |
| **Brotli Compression** | ✅ Yes (preferred over gzip) | ❌ No | WarpDrive only |
| **ZStd Compression** | ✅ Yes (async-compression support) | ❌ No | WarpDrive only |
| **Compression Streaming** | ✅ Yes (SSE, X-Accel-Buffering detection) | ❌ No | WarpDrive only |
| **Custom Headers (global)** | ✅ Yes (per-route, per-upstream) | ✅ Yes (global headers in config) | |
| **Custom Headers (per-route)** | ✅ Yes (add_headers in route config) | ✅ Yes (per-path headers) | Both supported |

---

### Extensibility & Plugins

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **WASM Plugins** | ✅ Yes (Wasmtime runtime, component model) | ❌ No | **MAJOR DIFFERENCE**: WarpDrive only |
| **Plugin Types** | ✅ HTTP, WebSocket, gRPC | ❌ N/A | WarpDrive only |
| **Plugin Metrics** | ✅ Yes (per-plugin instrumentation) | ❌ N/A | WarpDrive only |
| **Plugin Manager** | ✅ Yes (load/unload dynamically) | ❌ No | WarpDrive only |
| **Middleware Chain** | ✅ Yes (extensible architecture) | ❌ No | WarpDrive only |

---

### Protocol Support

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **HTTP** | ✅ Yes | ✅ Yes | |
| **HTTPS** | ✅ Yes | ✅ Yes | |
| **WebSocket (ws/wss)** | ✅ Yes | ✅ Yes | |
| **gRPC** | ✅ Yes | ✅ Yes | |
| **Unix Domain Sockets** | ✅ Yes (~30% faster than TCP) | ❌ No | WarpDrive only |

---

### Deployment & Operations

| Feature | WarpDrive | Aralez | Notes |
|---------|-----------|--------|-------|
| **Docker Support** | ✅ Yes (Dockerfile provided, Ruby 3.4 Alpine) | ✅ Yes (Debian 13 slim image) | Both supported |
| **Binary Distribution** | ✅ cargo install wrap-drive | ✅ musl & glibc static/dynamic builds | Aralez: more distribution options |
| **Binary Portability** | ✅ musl & glibc (forked Pingora) | ✅ musl & glibc + pre-built arm64 | Both support portability |
| **Performance (glibc)** | N/A | 129,777 req/s (Oha benchmark) | Aralez published benchmarks |
| **Performance (musl)** | N/A | 123,870 req/s (Oha benchmark) | ~5% slower than glibc |
| **Graceful Shutdown** | ✅ Yes (configurable timeout) | ✅ Yes (SIGTERM/SIGQUIT) | |
| **Live Upgrade** | ❌ Not mentioned | ✅ Yes (socket-based upgrade mechanism) | Aralez specific |

---

### Unique Features

#### WarpDrive Exclusive Features
1. **ACME/Let's Encrypt Automatic Provisioning** - Full ACME support with HTTP-01 challenges
2. **Process Supervision & Multi-Process Orchestration** - Run/manage application servers alongside proxy
3. **Caching Layer (L1+L2)** - Redis distributed cache with memory fallback
4. **WASM Plugin System** - Secure sandboxed plugins via Wasmtime
5. **Circuit Breaker** - Full 3-state circuit breaker implementation
6. **Concurrency Limiting** - Max concurrent request controls
7. **Interactive TUI Dashboard** - Real-time monitoring and management
8. **Lifecycle Hooks** - Pre/post startup/shutdown orchestration with leader election
9. **Unix Domain Socket Support** - ~30% performance improvement over TCP
10. **Compression (Gzip/Brotli/ZStd)** - Multi-algorithm support with streaming detection
11. **X-Sendfile Support** - Backend-controlled file serving
12. **Health Endpoints** - /health, /healthz, /ready, /up

#### Aralez Exclusive Features
1. **Hot Reload Configuration** - Live config updates without restart via file watch or API
2. **Service Discovery** - Consul and Kubernetes provider integration
3. **Automatic TLS Detection** - Upstreams transparently detected as TLS or plain
4. **Built-in Authentication** - Basic Auth, API Key, JWT generation and validation
5. **Sticky Sessions** - Cookie-based session stickiness
6. **Per-Path Rate Limiting** - Granular rate limit control per-path (overrides global)
7. **Remote Config Push API** - Push config updates from CI/CD or external systems
8. **Live Process Upgrade** - Socket-based graceful process upgrade capability
9. **Multiple TLS Grade Presets** - Simplified cipher/protocol selection (high/medium/unsafe)
10. **Systemd Integration Guide** - Pre-configured systemd service template

---

## Architectural Differences

### WarpDrive Architecture
- **Focus**: Application-centric reverse proxy with embedded process management
- **Deployment Model**: Standalone proxy that can spawn and manage upstream processes
- **Configuration**: Environment variables (simple) + TOML (advanced)
- **State Management**: In-memory L1 cache + optional Redis L2
- **Extensibility**: WASM plugin system for custom middleware
- **Use Case**: Development/staging with embedded app servers; self-contained deployments

### Aralez Architecture
- **Focus**: Edge proxy with dynamic service discovery
- **Deployment Model**: Standalone proxy that routes to external services
- **Configuration**: YAML with hot-reload capability
- **State Management**: No caching layer (upstream responsibility)
- **Extensibility**: Limited; no plugin system
- **Use Case**: High-performance edge routing; service mesh integration; dynamic infrastructure

---

## Performance Characteristics

### WarpDrive
- **Static File Serving**: 600+ req/s (concurrent)
- **Backend**: Emphasis on feature richness over raw throughput
- **Memory**: LRU cache with probabilistic eviction (won't kill Raspberry Pi)
- **Compression**: Multi-algorithm support (may add slight overhead)

### Aralez
- **Raw Throughput**: 129,777 req/s (glibc), 123,870 req/s (musl)
- **Focus**: High-performance edge routing
- **Memory**: Minimal overhead (no caching layer)
- **Simplicity**: Fewer features = lower overhead

---

## Use Case Recommendations

### Use WarpDrive When:
- You need **automatic TLS provisioning** (ACME/Let's Encrypt)
- Running **embedded application servers** (Rails, Node, Python, etc.)
- Requiring **in-transit caching** with Redis backing
- Need **WASM plugin extensibility**
- Want **circuit breaker protection** for upstream failures
- Require **interactive operational dashboard** (TUI)
- Static file serving with **ETag/caching support**
- Multi-instance deployments with **leader election**

### Use Aralez When:
- Need **hot-reload configuration** without restart
- Integrating with **Consul** or **Kubernetes** for service discovery
- Requiring **built-in authentication** (Basic, API Key, JWT)
- Need **automatic upstream TLS detection**
- Want **maximum raw throughput** (edge proxy focus)
- Require **sticky sessions** for stateful backends
- Need **fine-grained per-path rate limiting**
- Deploying to high-volume edge infrastructure

---

## Configuration Complexity

### WarpDrive Configuration
```toml
[upstreams.app]
protocol = "http"
host = "127.0.0.1"
port = 3000

[[routes]]
path_prefix = "/"
upstream = "app"

[middleware.rate_limit]
enabled = true
requests_per_second = 100
```

### Aralez Configuration
```yaml
myhost.example.com:
  paths:
    "/":
      rate_limit: 100
      headers:
        - "X-Proxy-From:Aralez"
      servers:
        - "127.0.0.1:3000"
```

---

## Maturity & Status

| Aspect | WarpDrive | Aralez |
|--------|-----------|--------|
| **Version** | 0.3.0 (early) | 0.9.2 (stable) |
| **Stability** | Experimental (ACME/crash recovery noted as experimental) | Stable, production-ready |
| **Limitations** | See LIMITATIONS.md | Fewer known limitations |
| **Community** | Growing | Established |

---

## Summary Table: Quick Reference

| Dimension | Winner | Details |
|-----------|--------|---------|
| **Raw Performance** | Aralez | 129K+ req/s vs feature-rich focus |
| **Features** | WarpDrive | ACME, caching, WASM, circuit breaker, TUI |
| **Authentication** | Aralez | Built-in Basic/API Key/JWT |
| **Service Discovery** | Aralez | Consul, Kubernetes providers |
| **Hot Reload** | Aralez | Live config updates without restart |
| **Process Management** | WarpDrive | Multi-process orchestration |
| **Caching** | WarpDrive | L1+L2 Redis distributed cache |
| **Extensibility** | WarpDrive | WASM plugin system |
| **Operational Visibility** | WarpDrive | Interactive TUI dashboard |
| **Configuration Maturity** | Aralez | Stable YAML with hot-reload |
| **TLS Provisioning** | WarpDrive | ACME/Let's Encrypt automatic |
| **Edge Proxy** | Aralez | Optimized for high-volume routing |

