🚀 Leaky Tokens

Enterprise-Grade Token Management & Rate Limiting System

📖 Documentation • 🚀 Quick Start • 📊 Architecture • 🔧 API

---

WHY?

This is an auto-generated project by AI agents. I already have experience with all of these technologies, but nobody cares if you don't have a GitHub repo with a pet project—so here it is.

Why do I use AI agents to generate projects? Because it's fun and I'm bored. Do I really work with all of these technologies? Yep. Ten years in, that's the answer.

• But you still have to write code yourself, because AI agents are not perfect and can't write everything for you. And this project doesn't show your skills.
• Well, that's the new world. I worked hard before. I wrote code day and night, but times have changed.

---

✨ Features

🎯 Core Capabilities 🪣 Leaky Bucket Rate Limiting - Smooth traffic flow 💰 Token Quotas - Per-user & org-level management ⚡ SAGA Orchestration - Distributed transactions 🔑 Multi-Auth - JWT + API Key support	🏗️ Architecture ☁️ Cloud-Native - 12-Factor App ready 🔍 Service Discovery - Eureka registry ⚖️ Load Balancing - Gateway routing 🛡️ Circuit Breaker - Resilience4j
📊 Observability 📈 Prometheus Metrics - Real-time monitoring 📉 Grafana Dashboards - Visual insights 🔎 Distributed Tracing - Jaeger integration 📝 Centralized Logs - Full audit trail	🗄️ Data Layer 🐘 PostgreSQL - Primary persistence ⚡ Redis - Caching & rate limits 📨 Kafka - Event streaming 📦 Cassandra - Time-series analytics

---

🏛️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        🌐 API Gateway                           │
│                    (Port 8080 - Entry Point)                    │
└─────────────┬───────────────────────────────────────────────────┘
              │
    ┌─────────┼─────────┬─────────────┐
    │         │         │             │
    ▼         ▼         ▼             ▼
┌───────┐ ┌───────┐ ┌────────┐  ┌──────────┐
│  🔐   │ │  🪙    │ │  📊    │  │  📝      │
│ Auth  │ │ Token │ │Analytics│ │ Config   │
│ 8081  │ │ 8082  │ │  8083  │  │  8888    │
└───────┘ └───────┘ └────────┘  └──────────┘
                                              
🗄️ PostgreSQL  ⚡ Redis  📨 Kafka  📦 Cassandra

🎯 Service Registry

Service	Port	Purpose	Status
🌐 API Gateway	8080	Entry point, routing, rate limiting	✅ Ready
🔐 Auth Server	8081	JWT & API Key authentication	✅ Ready
🪙 Token Service	8082	Core business logic	✅ Ready
📊 Analytics	8083	Usage tracking & reports	✅ Ready
📍 Eureka	8761	Service discovery	✅ Ready
⚙️ Config	8888	Centralized configuration	✅ Ready

---

🚀 Quick Start

Prerequisites

• ☕ Java 25
• 🐳 Docker & Docker Compose
• 📦 Gradle (wrapper included)

⚡ One-Command Start

# Clone repository
git clone <repository-url> && cd leaky-tokens

# Start infrastructure
docker-compose -f docker-compose.infra.yml up -d

# Run all services
./gradlew bootRun --parallel

🧪 Test It Works

# Check service health
curl http://localhost:8082/api/v1/tokens/status | jq

# Register a user
curl -X POST http://localhost:8081/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","email":"[email protected]","password":"password"}' | jq

# Test token consumption
curl -X POST http://localhost:8082/api/v1/tokens/consume \
  -H "Content-Type: application/json" \
  -d '{"userId":"YOUR_USER_ID","provider":"openai","tokens":50}' | jq

---

🧪 Postman

1. Import the collection docs/postman/leaky-tokens.postman_collection.json.
2. Import the environment docs/postman/leaky-tokens.postman_environment.json.
3. Select the Leaky Tokens Local environment.
4. Run Auth/Login to auto-populate accessToken and userId, then exercise the other requests.

---

📖 Documentation

📚 Guide	📝 Description
📘 Overview	Project purpose & architecture
🚀 Getting Started	Installation & setup
👤 User Guide	How to use the API
🏗️ Architecture	Technical deep-dive
🎯 Use Cases	Business scenarios
⚙️ Configuration	All config options
📊 Monitoring	Metrics, logs, tracing
📋 API Reference	Complete API docs
🔧 Troubleshooting	Common issues
💻 Development	Contributing guide

---

📊 Key Capabilities

🪣 Rate Limiting Strategies

Leaky Bucket (Default)

Tokens leak at a constant rate, smoothing out traffic bursts:

token:
  bucket:
    capacity: 1000
    leakRatePerSecond: 10.0
    strategy: LEAKY_BUCKET

Token Bucket

Allows short bursts while maintaining average rate:

token:
  bucket:
    capacity: 1000
    leakRatePerSecond: 10.0
    strategy: TOKEN_BUCKET

Fixed Window

Simple counter-based limiting:

token:
  bucket:
    capacity: 1000
    windowSeconds: 60
    strategy: FIXED_WINDOW

💰 Quota Management

# Check quota
curl "http://localhost:8082/api/v1/tokens/quota?userId=...&provider=openai"

# Consume tokens
curl -X POST http://localhost:8082/api/v1/tokens/consume \
  -d '{"userId":"...","provider":"openai","tokens":100}'

# Purchase more tokens
curl -X POST http://localhost:8082/api/v1/tokens/purchase \
  -H "Idempotency-Key: purchase-001" \
  -d '{"userId":"...","provider":"openai","tokens":1000}'

---

🔍 Observability

📈 Monitoring URLs

Tool	URL	Description
📊 Grafana	http://localhost:3000	Dashboards (admin/admin)
📈 Prometheus	http://localhost:9090	Metrics collection
🔎 Jaeger	http://localhost:16686	Distributed tracing
📍 Eureka	http://localhost:8761	Service registry

🕵️ Distributed Tracing

View end-to-end request flows across microservices:

# Start with full tracing stack (includes Jaeger)
docker-compose -f docker-compose.full.yml up -d

# Access Jaeger UI
open http://localhost:16686

# Make some requests and watch traces appear
curl -X POST http://localhost:8080/api/v1/tokens/consume \
  -H "Content-Type: application/json" \
  -d '{"userId":"...","provider":"openai","tokens":50}'

Trace Analysis:

• See request paths through all services
• Identify latency bottlenecks
• Debug distributed issues
• 100% sampling in development mode

📚 Full Tracing Guide

📝 Quick Log Check

# Service logs
./gradlew :token-service:bootRun 2>&1 | tee service.log

# Docker logs
docker-compose logs -f token-service

# Search for errors
grep "ERROR" service.log

---

🎯 API Reference

Authentication Methods

# JWT Token
curl -H "Authorization: Bearer $JWT_TOKEN" ...

# API Key
curl -H "X-Api-Key: leaky_userid_xxxx" ...

Core Endpoints

Method	Endpoint	Description	Auth
POST	/api/v1/auth/register	Create user account	Public
POST	/api/v1/auth/login	Authenticate	Public
GET	/api/v1/tokens/quota	Check user quota	JWT
POST	/api/v1/tokens/consume	Consume tokens	JWT
POST	/api/v1/tokens/purchase	Buy tokens	JWT
GET	/api/v1/analytics/report	Usage report	JWT

📚 Full API Documentation →

---

🧪 Testing

# Run all tests
./gradlew test

# Run with coverage
./gradlew jacocoTestReport

# Performance tests
./gradlew :performance-tests:gatlingRun

---

🤝 Contributing

We welcome contributions! Please see our Development Guide for:

• 🏗️ Project structure
• 📝 Code style guidelines
• 🧪 Testing best practices
• 🔧 Development setup

---

⭐ Star this repo if you find it helpful!

Made with ❤️ and 🤖 AI assistance