🗄️ Caching Proxy Server (Spring Boot CLI)

Table of Contents

• 1. ✨ Features
• 2. 🔧 Tech Stack
• 3. 🚀 Quick Start
  • 3.1. Prerequisites
  • 3.2. Build
  • 3.3. Run
  • 3.4. Test It
• 4. ⚙️ CLI Options
• 5. 🐳 Docker
  • 5.1. Build
  • 5.2. Run
• 6. 📐 How It Works
• 7. 📊 Benchmark (optional)
• 8. 🧭 Roadmap
• 9. 🤝 Contributing
• 10. 🔐 Security
• 11. 📜 License

A lightweight caching reverse proxy built with Spring Boot. It forwards requests to an origin server, caches responses in-memory, and returns X-Cache: HIT|MISS headers.

1. ✨ Features

• Forward requests to a configurable origin (e.g., http://dummyjson.com)

• In-memory caching with ConcurrentHashMap

• Adds X-Cache response header: HIT (served from cache) / MISS (fetched and stored)

• CLI flags: --port, --origin, --clear-cache

• Minimal dependencies, fast startup, easy to extend

2. 🔧 Tech Stack

• Java 17+

• Spring Boot 3.x

• RestTemplate / WebClient

• ConcurrentHashMap for cache

3. 🚀 Quick Start

3.1. Prerequisites

• Java 17+

• Maven 3.9+

3.2. Build

mvn clean package

3.3. Run

1. Start proxy

java -jar target/caching-proxy.jar --port=3000 --origin=http://dummyjson.com

1. Clear cache

java -jar target/caching-proxy.jar --clear-cache

3.4. Test It

# First run → MISS
curl -i http://localhost:3000/products | grep X-Cache

# Second run → HIT
curl -i http://localhost:3000/products | grep X-Cache

Output:

X-Cache: MISS
X-Cache: HIT

4. ⚙️ CLI Options

Flag	Type	Default	Description
--port	int	3000	Port for the proxy server
--origin	url	—	Origin base URL (e.g., http://dummyjson.com)
--clear-cache	bool	false	Clears in-memory cache and exits

Tip	You can also use environment variables (optional) like PROXY_PORT and PROXY_ORIGIN.

5. 🐳 Docker

5.1. Build

docker build -t caching-proxy:latest .

5.2. Run

docker run --rm -p 3000:3000 caching-proxy:latest \
  --port=3000 --origin=http://dummyjson.com

6. 📐 How It Works

1. On startup, CLI flags set port & origin.

2. On request:

   • If cached → return cached body with X-Cache: HIT

   • If not cached → forward to origin, store response, return with X-Cache: MISS

3. --clear-cache empties cache and exits.

Client → Proxy(Server:3000) → Origin
        ↑          |
        └── Cache ─┘

7. 📊 Benchmark (optional)

ab -n 200 -c 20 http://localhost:3000/products

Compare first run (MISS heavy) vs repeated run (HIT heavy).

8. 🧭 Roadmap

• ❏ TTL / max-size eviction (LRU)

• ❏ Cache policies by method/headers

• ❏ Invalidation endpoint

• ❏ Metrics (Micrometer/Prometheus)

• ❏ Redis as optional persistent backend

9. 🤝 Contributing

Pull requests welcome!

1. Fork repo

2. Create branch

3. Add tests

4. Update docs

10. 🔐 Security

Report vulnerabilities via Issues or email.

11. 📜 License

Licensed under the MIT License.