GateKeeper — High-Throughput Request Gateway with Circuit Breaker 🚦🛡️

GateKeeper is a lightweight Python-based gateway built using FastAPI. It acts as a proxy to route requests to multiple backend services, with built-in support for round-robin load balancing 🔁 and a circuit breaker mechanism 🔌 to prevent cascading failures in a microservices environment.

---

✨ Features

• 🔁 Round-robin request distribution across service replicas
• 🔌 In-memory circuit breaker (per backend URL)
• ⚡ FastAPI-based async HTTP routing with httpx
• 🔧 Configurable services via config.yaml
• 🛡️ Designed for high availability in microservice-based systems

---

🧰 Tech Stack

• 🐍 Python 3.10+
• ⚡ FastAPI
• 🌐 httpx
• 🧾 PyYAML

---

🚀 Setup Instructions

📥 Clone the repository

git clone <your-repo-url>
cd GateKeeper

🔒 Create and activate virtual environment

python -m venv gkvenv
source gkvenv/bin/activate  # On Windows: gkvenv\Scripts\activate

📦 Install dependencies

pip install -r requirements.txt

▶️ Run the gateway server

uvicorn main:app --reload --port 8000

🧪 (Optional) Start mock backend services

You can start the mock backend services (e.g., mock_user_service.py, mock_order_service.py) or create your own services running on ports 8001, 8002, 8003, etc.

🌐 API Usage

🛣️ Proxy Endpoint

GET /v1/proxy/{service_name}/{path}

📦 Example:

GET http://localhost:8000/v1/proxy/user-service/profile

✅ Description:

Forwards the incoming request to one of the configured replicas of the given service using round-robin logic.
Handles circuit breaker states internally to block failing backends.

⚙️ Configuration (config.yaml)

services:
  user-service:
    - http://localhost:8001
    - http://localhost:8002
  order-service:
    - http://localhost:8003

Define each microservice and its replicas in config.yaml.
The gateway will load this mapping on startup.

🧠 Design Decisions

• ⚡ FastAPI chosen for performance and async support

• 🌐 httpx.AsyncClient used for efficient non-blocking proxy calls

• 🧠 Circuit breaker state maintained in-memory for simplicity

• 🔁 RoundRobinManager class ensures even distribution across service replicas

• 🧼 Clean modular structure (router, circuit_breaker, utils)

🔐 Circuit Breaker Logic

Each backend URL maintains its own circuit state:

• ✅ CLOSED: Normal. Requests are sent.

• 🚫 OPEN: After 5 failures, requests are blocked for 60 seconds.

• 🔄 HALF-OPEN: After cooldown, a single test request is allowed:

  • If it succeeds → the circuit resets to CLOSED

  • If it fails → the circuit returns to OPEN

🖥️ Logs

Logs are printed to the console when state transitions happen:

[FAILURE], [CIRCUIT OPENED], [CIRCUIT HALF-OPEN], [CIRCUIT CLOSED]

📁 Folder Structure

GateKeeper/
├── main.py
├── config.yaml
├── requirements.txt
├── mock_user_service.py
├── mock_user_service2.py
├── mock_order_service3.py
├── README.md
├── gateway/
│   ├── router.py
│   ├── utils.py
│   └── circuit_breaker.py
└── .gitignore

🚧 Future Improvements

• 💾 Add persistent circuit breaker state (Redis, database, etc.)

• 📊 Add a /status endpoint to monitor circuit health

• ✅ Write unit and integration tests

• 🐳 Dockerize gateway and backend services for production-ready deployment