🦀 Request Coalescing with Rust and SurrealDB

This project demonstrates the implementation of the Request Coalescing pattern in Rust using the axum web framework and a remote SurrealDB database hosted in an Azure virtual machine.

---

🧠 What is Request Coalescing?

Request Coalescing is an optimization technique that consolidates multiple identical concurrent requests into a single one. This avoids redundant work, especially in I/O-bound operations like querying a database, thereby improving performance, reducing latency, and minimizing database load.

---

🔧 Technologies Used

• 🦀 Rust 1.88 — Primary programming language
• 🧱 Axum — Async web framework used for the HTTP server
• ⚙️ Tokio — Asynchronous runtime used by Axum
• 📦 DashMap — Thread-safe concurrent cache for deduplication
• ☁️ SurrealDB — Cloud-native database (running in an Azure Virtual Machine)
• 🐚 PowerShell — Used to insert initial data into SurrealDB
• 📄 .env — Configuration file for environment variables
• 📦 serde_json, reqwest, tracing — Supporting libraries
• 🧪 hey — Load testing tool for benchmarking the API

---

🏗️ Architecture

Two endpoints expose the same business logic:

• http://ip:3000/producto/:id → With Request Coalescing
• http://ip:3001/producto/:id → Without Request Coalescing

Both query the remote SurrealDB, but the coalescing version reduces redundant requests.

                        ┌────────────────────┐
                        │ Incoming HTTP GET  │
                        │ /producto/{id}     │
                        └────────┬───────────┘
                                 │
                         ┌───────▼────────┐
                         │ Request Router │
                         └───────┬────────┘
                                 │
               ┌────────────────▼────────────────┐
               │ With Request Coalescing (Port 3000) │
               │ - Uses cache + async task deduplication │
               └────────────────┬────────────────┘
                                │
                       ┌────────▼────────┐
                       │   SurrealDB     │
                       └─────────────────┘

               ┌──────────────────────────────┐
               │ Without Request Coalescing   │
               │ (Port 3001)                  │
               └──────────────────────────────┘

---

📂 Project Structure

src/
├── main.rs                 # Application entry point and routing
├── state.rs                # Shared application state and cache setup
├── domain/
│   ├── mod.rs
│   └── models.rs           # Domain models like Producto
├── handlers/
│   ├── mod.rs
│   └── producto.rs         # HTTP handlers for endpoints
├── infra/
│   ├── mod.rs
│   └── db.rs               # SurrealDB connection and query logic
└── services/
    ├── mod.rs
    └── producto_service.rs # Business logic and request coalescing

---

🚀 Benchmark Results

The performance test was run locally using hey from a Windows 10 machine, while the SurrealDB server ran remotely on an Azure VM.

Metric	With Coalescing (Port 3000)	Without Coalescing (Port 3001)
Total Time (1000 reqs)	⚡ 0.2015 s	🐢 4.3504 s
Average per request	0.0090 s	0.1932 s
Requests/sec	4962.7	229.8
95th Percentile Latency	0.1349 s	0.2538 s
Fastest request	0.0001 s	0.1277 s
Slowest request	0.1875 s	0.3810 s
HTTP 200 OK responses	1000	1000

---

🧪 How to Run Locally

1. Clone the repo:

   git clone <repo-url>
   cd rust_surrealdb_request_coalescing

2. Launch SurrealDB (already set on an Azure VM):

   No local DB required. Uses remote SurrealDB instance at <IP-VM>:8000

3. Run the Rust server:

   cargo run --release

4. Benchmark the endpoints:

   # With coalescing
   hey -n 1000 -c 50 http://ip:3000/producto/1001
   
   # Without coalescing
   hey -n 1000 -c 50 http://ip:3001/producto/1001

---

📌 Conclusion

This project demonstrates how applying the Request Coalescing pattern in a concurrent Rust web application leads to massive improvements in throughput and latency, especially when interacting with remote databases.

🌐 Author

Victor Aguayo — Technology Architect & Rust Enthusiast