sufast 1.0.0
A blazing-fast Python web framework powered by Rust 🚀
License: MIT
Requires Python: >=3.8

# 🚀 Sufast – Ultra-Fast Python Web Framework Powered by Rust

**Sufast** is a revolutionary hybrid web framework that marries the developer-friendly elegance of **Python 🐍** with the raw computational power of **Rust 🦀**.

[![PyPI version](https://badge.fury.io/py/sufast.svg)](https://badge.fury.io/py/sufast)
[![Python Support](https://img.shields.io/pypi/pyversions/sufast.svg)](https://pypi.org/project/sufast/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI/CD](https://github.com/shohan-dev/sufast/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/shohan-dev/sufast/actions)
[![codecov](https://codecov.io/gh/shohan-dev/sufast/branch/main/graph/badge.svg)](https://codecov.io/gh/shohan-dev/sufast)
[![Downloads](https://pepy.tech/badge/sufast)](https://pepy.tech/project/sufast)

Built for high-performance APIs, enterprise microservices, and AI-powered backends that demand both speed and developer productivity.

> **🎯 Performance First**: Achieve **70,000+ RPS** with our revolutionary three-tier architecture while maintaining the simplicity of FastAPI-style development.

## 🆕 What's New

### 🏗️ Advanced API Organization
- **RouteGroup System**: Organize related endpoints with logical grouping and prefix support
- **Smart Tagging**: Auto-tagging based on patterns plus manual tag assignment for enhanced discovery
- **Enhanced HTTP Methods**: Complete REST support (GET, POST, PUT, DELETE, PATCH) with intelligent defaults

### 📖 Interactive Documentation Revolution
- **Three View Modes**: Performance Tiers, Groups, and Tags for different perspectives
- **Real-time Filtering**: Search and filter endpoints by tags, groups, or functionality
- **Live API Testing**: Execute requests directly from documentation interface
- **Rich Metadata**: Summaries, descriptions, examples, and comprehensive route information

### 🎯 Developer Experience Enhancements
- **API Introspection**: `get_all_tags()`, `get_routes_by_group()`, `get_routes_by_tag()` methods
- **Visual Organization**: Color-coded performance tiers and intuitive grouping
- **Enhanced Decorators**: Extended `@app.get()`, `@app.post()` etc. with tags, groups, summaries
- **Smart Auto-Documentation**: Automatic documentation generation with OpenAPI-style interface

## ⚡ Why Choose Sufast?

### 🚀 ** Performance**
- **70,000+ RPS** for static routes (pre-compiled responses)
- **60,000+ RPS** for cached routes (intelligent caching with TTL)
- **5,000+ RPS** for dynamic routes (real-time parameter processing)
- **Sub-millisecond latency** for optimized endpoints

### 🎯 **Three-Tier Architecture**
- **Tier 1 - Static Routes**: Pre-compiled responses for maximum speed
- **Tier 2 - Cached Routes**: Intelligent caching with configurable TTL
- **Tier 3 - Dynamic Routes**: Real-time processing with parameter extraction

### 🐍 **Developer Experience**
- FastAPI-style decorator syntax (`@app.route`, `@app.get`, `@app.post`)
- **Advanced Route Organization** with groups and tags
- **Interactive API Documentation** with filtering and search
- **Enhanced HTTP Methods** (GET, POST, PUT, DELETE, PATCH)
- **Smart Auto-Documentation** with OpenAPI-style interface
- Type hints and automatic validation support
- Hot reload for development
- Comprehensive error handling and debugging

### 🔧 **Production Ready**
- Zero-configuration deployment
- Built-in middleware support
- **Advanced Route Groups** for API organization
- **Tag-based Filtering** and discovery
- **Interactive Documentation** at `/docs`
- Request/response lifecycle hooks
- Comprehensive logging and monitoring
- Docker and Kubernetes ready



### 🎯 Performance Tiers

| **Tier** | **Type** | **Performance** | **Use Case** | **Example** |
|----------|----------|-----------------|--------------|-------------|
| 🔥 **Tier 1** | Static | **70,000+ RPS** | Fixed content, health checks | `@app.route('/', static=True)` |
| 🧠 **Tier 2** | Cached | **60,000+ RPS** | Semi-static data with TTL | `@app.route('/stats', cache_ttl=300)` |
| ⚡ **Tier 3** | Dynamic | **5,000+ RPS** | Parameter processing | `@app.route('/user/{id}')` |

## 📦 Installation

### Quick Install
```bash
pip install sufast
```

### Development Install
```bash
# Clone the repository
git clone https://github.com/shohan-dev/sufast.git
cd sufast

# Install in development mode
pip install -e .

# Run tests to verify installation
python -m pytest tests/
```

### System Requirements
- **Python**: 3.8+ (3.11+ recommended for optimal performance)
- **Platform**: Linux, macOS, Windows (x64)
- **Memory**: Minimum 512MB RAM
- **Dependencies**: Automatically bundled Rust binary

> **⚠️ Note**: First-time installation may take a moment to compile platform-specific binaries.

# 🚀 Quick Start

## Basic Application

```python
from sufast import Sufast

app = Sufast()

@app.route("/", static=True)
def hello():
    return {"message": "Hello from Sufast! �", "performance": "70K+ RPS"}

if __name__ == "__main__":
    app.run(port=8080)
```

Run your app:
```bash
python app.py
```

Visit → **[http://localhost:8080/](http://localhost:8080/)** 🌟

## Three-Tier Performance Demo

```python
from sufast import Sufast

app = Sufast()

# TIER 1: Static Route (70K+ RPS)
@app.route("/health", static=True)
def health_check():
    return {"status": "healthy", "tier": 1, "performance": "70,000+ RPS"}

# TIER 2: Cached Route (60K+ RPS)  
@app.route("/stats", cache_ttl=300)  # 5-minute cache
def get_statistics():
    return {
        "active_users": 1547,
        "requests_today": 892456,
        "tier": 2,
        "performance": "60,000+ RPS (cached)"
    }

# TIER 3: Dynamic Route (5K+ RPS)
@app.route("/user/{user_id}")
def get_user(user_id):
    return {
        "user_id": int(user_id),
        "name": f"User {user_id}",
        "tier": 3,
        "performance": "5,000+ RPS (dynamic)"
    }

app.run()
```

# 🎯 Enhanced Developer Features (v2.0+)

## 🏷️ Advanced Route Organization with Tags & Groups

### Route Groups for API Organization
```python
from sufast import Sufast

app = Sufast()

# Create organized route groups
users_group = app.group("User Management", prefix="/api/v1", tags=["api", "users"])
products_group = app.group("Product Catalog", prefix="/api/v1", tags=["api", "products"])

# Use groups for clean organization
@users_group.get("/users", 
                 tags=["list", "pagination"], 
                 summary="List all users",
                 description="Get paginated list of users with filtering")
def list_users():
    return {"users": [...], "total": 100}

@users_group.get("/users/{user_id}", 
                 tags=["profile", "details"])
def get_user(user_id):
    return {"id": user_id, "name": "User Name"}

@products_group.post("/products", 
                     tags=["create", "inventory"])
def create_product():
    return {"message": "Product created", "id": 123}
```

### Enhanced HTTP Method Decorators
```python
# Full REST API support with intelligent defaults
@app.get("/items", cache_ttl=300, tags=["read", "catalog"])
def list_items():
    return {"items": [...]}

@app.post("/items", tags=["create", "inventory"], group="Item Management")
def create_item():
    return {"created": True}

@app.put("/items/{item_id}", tags=["update", "modify"])
def update_item(item_id):
    return {"updated": item_id}

@app.delete("/items/{item_id}", tags=["delete", "cleanup"])
def delete_item(item_id):
    return {"deleted": item_id}

@app.patch("/items/{item_id}", tags=["patch", "partial"])
def patch_item(item_id):
    return {"patched": item_id}
```

### Smart Tag-Based Organization
```python
# Use decorators for advanced tagging
@app.tag("admin", "system", "monitoring")
@app.summary("System health check")
@app.description("Comprehensive health monitoring with detailed metrics")
@app.get("/health", static=True, group="System Monitoring")
def health_check():
    return {"status": "healthy", "metrics": {...}}

@app.tag("search", "discovery", "ai")
@app.get("/search/{query}", group="Search & Discovery")
def smart_search(query):
    return {"query": query, "results": [...]}
```

## 📖 Interactive API Documentation

### Auto-Generated Documentation at `/docs`
- **Three View Modes**: Performance Tiers, Groups, and Tags
- **Interactive Filtering**: Real-time tag-based filtering
- **Advanced Search**: Search across endpoints, descriptions, and tags
- **Live Testing**: Execute requests directly from documentation
- **Rich Metadata**: Summaries, descriptions, examples, and response schemas

### Query Your API Structure
```python
# Powerful introspection methods
all_tags = app.get_all_tags()
# Returns: ['admin', 'api', 'create', 'delete', 'read', 'system', ...]

all_groups = app.get_all_groups()
# Returns: ['User Management', 'Product Catalog', 'System Monitoring', ...]

admin_routes = app.get_routes_by_tag("admin")
user_routes = app.get_routes_by_group("User Management")

# Get comprehensive route information
print(f"📊 Total Routes: {len(app.route_metadata)}")
print(f"🏷️ Total Tags: {len(app.get_all_tags())}")
print(f"📁 Total Groups: {len(app.get_all_groups())}")
```

## 🎨 Enhanced Documentation Features

### Rich Route Metadata
```python
@app.get("/products/{product_id}", 
         tags=["products", "details", "e-commerce"],
         group="Product Catalog",
         summary="Get detailed product information",
         description="Retrieve comprehensive product details including pricing, inventory, and related items")
def get_product_details(product_id):
    """Get detailed product with dynamic pricing and recommendations."""
    return {
        "product": {...},
        "pricing": {...},
        "recommendations": [...]
    }
```

### Visual Organization Benefits
- **Color-coded Performance Tiers**: Static (🔥), Cached (🧠), Dynamic (⚡)
- **Group-based Navigation**: Logical API organization
- **Tag-based Discovery**: Find related endpoints instantly
- **Interactive Examples**: Pre-filled parameter examples
- **Real-time Testing**: Execute API calls from documentation


# 📚 Production-Ready API Example

```python
from sufast import Sufast
import json

app = Sufast()

# Sample database
USERS_DB = {
    1: {"id": 1, "name": "Alice Johnson", "email": "alice@example.com", "role": "admin"},
    2: {"id": 2, "name": "Bob Smith", "email": "bob@example.com", "role": "user"},
    3: {"id": 3, "name": "Charlie Brown", "email": "charlie@example.com", "role": "user"},
}

PRODUCTS_DB = {
    1: {"id": 1, "name": "UltraBook Pro", "price": 1299.99, "stock": 15},
    2: {"id": 2, "name": "Precision Mouse X1", "price": 29.99, "stock": 100},
}

# Helper function for JSON responses
def json_response(data, status=200):
    return {
        "body": json.dumps(data) if not isinstance(data, str) else data,
        "status": status,
        "headers": {"Content-Type": "application/json"}
    }

# STATIC ENDPOINTS (70K+ RPS)
@app.route("/", static=True)
def home():
    return {
        "message": "🚀 Welcome to Sufast Production API!",
        "version": "2.0",
        "performance": "70,000+ RPS",
        "endpoints": {
            "users": "/users",
            "products": "/products", 
            "health": "/health"
        }
    }

@app.route("/health", static=True)
def health():
    return {
        "status": "healthy",
        "service": "Sufast API v2.0",
        "performance": "70,000+ RPS",
        "uptime": "99.9%"
    }

# CACHED ENDPOINTS (60K+ RPS)
@app.route("/users", cache_ttl=300)  # 5-minute cache
def list_users():
    return {
        "users": list(USERS_DB.values()),
        "total": len(USERS_DB),
        "performance": "60,000+ RPS (cached)",
        "cache_ttl": 300
    }

@app.route("/products", cache_ttl=600)  # 10-minute cache
def list_products():
    return {
        "products": list(PRODUCTS_DB.values()),
        "total": len(PRODUCTS_DB),
        "performance": "60,000+ RPS (cached)",
        "cache_ttl": 600
    }

# DYNAMIC ENDPOINTS (5K+ RPS)
@app.route("/user/{user_id}")
def get_user(user_id):
    try:
        user_id = int(user_id)
        user = USERS_DB.get(user_id)
        
        if user:
            return {
                "user": user,
                "performance": "5,000+ RPS (dynamic)",
                "extracted_param": {"user_id": user_id}
            }
        else:
            return json_response({
                "error": "User not found",
                "user_id": user_id,
                "available_users": list(USERS_DB.keys())
            }, status=404)
    except ValueError:
        return json_response({
            "error": "Invalid user ID format",
            "expected": "Integer"
        }, status=400)

@app.route("/product/{product_id}")
def get_product(product_id):
    try:
        product_id = int(product_id)
        product = PRODUCTS_DB.get(product_id)
        
        if product:
            # Calculate dynamic pricing
            discount = 0.1 if product['stock'] > 50 else 0.05
            discounted_price = product['price'] * (1 - discount)
            
            return {
                "product": product,
                "pricing": {
                    "original": product['price'],
                    "discount": f"{discount*100}%",
                    "final": round(discounted_price, 2)
                },
                "performance": "5,000+ RPS (dynamic)"
            }
        else:
            return json_response({
                "error": "Product not found",
                "product_id": product_id
            }, status=404)
    except ValueError:
        return json_response({
            "error": "Invalid product ID format"
        }, status=400)

# Multi-parameter dynamic route
@app.route("/user/{user_id}/orders/{order_id}")
def get_user_order(user_id, order_id):
    return {
        "user_id": int(user_id),
        "order_id": int(order_id),
        "order": {
            "id": int(order_id),
            "user_id": int(user_id),
            "status": "shipped",
            "total": 299.99
        },
        "performance": "5,000+ RPS (multi-param dynamic)"
    }

if __name__ == "__main__":
    print("🚀 Starting Sufast Production API...")
    print("📊 Performance Tiers:")
    print("   🔥 Static routes: 70,000+ RPS")
    print("   🧠 Cached routes: 60,000+ RPS") 
    print("   ⚡ Dynamic routes: 5,000+ RPS")
    app.run(host="0.0.0.0", port=8080)
```

## 🏗️ Architecture

Sufast employs a sophisticated three-tier hybrid architecture that automatically optimizes your routes for maximum performance:

```
📁 Project Structure
├── 🐍 python/sufast/          # Python package and bindings
│   ├── core_ultimate.py       # Ultimate optimization engine
│   ├── routing.py             # Route management system
│   ├── middleware.py          # Request/response middleware
│   ├── database.py            # Database integration layer
│   └── templates.py           # Template rendering engine
├── 🦀 rust-core/              # High-performance Rust engine
│   ├── src/lib.rs             # Core Rust library
│   ├── src/server.rs          # HTTP server implementation
│   ├── src/routing.rs         # Ultra-fast route matching
│   └── src/middleware.rs      # Performance middleware
├── 📚 docs/                   # Comprehensive documentation
│   ├── quickstart.md          # Getting started guide
│   └── architecture.md       # Technical deep dive
├── 🧪 tests/                  # Multi-language test suites
│   ├── test_core.py           # Core functionality tests
│   ├── test_integration.py    # Integration test suite
│   └── test_v2_features.py    # Latest features validation
└── 🔧 scripts/               # Development and build tools
    ├── build.py               # Cross-platform build script
    ├── test.py                # Automated testing pipeline
    └── lint.py                # Code quality enforcement
```

### API Endpoints

| **Endpoint** | **Type** | **Performance** | **Description** |
|-------------|----------|-----------------|-----------------|
| `GET /` | Static | 70K+ RPS | API information |
| `GET /health` | Static | 70K+ RPS | Health check |
| `GET /users` | Cached | 60K+ RPS | List all users |
| `GET /products` | Cached | 60K+ RPS | List all products |
| `GET /user/{id}` | Dynamic | 5K+ RPS | Get user by ID |
| `GET /product/{id}` | Dynamic | 5K+ RPS | Get product with dynamic pricing |
| `GET /user/{id}/orders/{order_id}` | Dynamic | 5K+ RPS | Multi-parameter route |

## 📊 Performance Benchmarks

### Real-World Load Testing Results

| **Framework** | **Language** | **RPS** | **Latency (P95)** | **Memory** | **CPU Usage** | **Concurrent Users** |
|--------------|-------------|---------|------------------|------------|---------------|-------------------|
| 🚀 **Sufast ** | Rust + Python | **52,000-70,000** | **~2.1ms** | **~25MB** | **15%** | **1,000** |
| 🦀 **Actix-Web** | Pure Rust | 56,000 | ~1.7ms | ~20MB | 12% | 1,000 |
| 🐍 **FastAPI** | Python + Uvicorn | ~25,000 | ~5.6ms | ~60MB | 45% | 500 |
| 🌐 **Express.js** | Node.js | ~35,000 | ~4.2ms | ~50MB | 35% | 750 |
| 🌸 **Gin** | Go | ~45,000 | ~3.1ms | ~30MB | 20% | 900 |
| ☕ **Spring Boot** | Java | ~15,000 | ~8.4ms | ~120MB | 55% | 300 |

### Sufast Three-Tier Performance Breakdown

| **Route Type** | **Technology** | **RPS Range** | **Latency** | **Use Case** | **Memory Impact** |
|---------------|----------------|---------------|-------------|--------------|------------------|
| 🔥 **Static** | Pre-compiled Rust | **70,000+** | **<0.02ms** | Health checks, fixed content | Minimal |
| 🧠 **Cached** | DashMap + TTL | **60,000+** | **<0.05ms** | Semi-static data, API responses | Low |
| ⚡ **Dynamic** | Rust + Python FFI | **5,000+** | **1-5ms** | Parameter processing, business logic | Moderate |

### Test Environment
- **Hardware**: AWS c5.2xlarge (8 vCPU, 16GB RAM)
- **OS**: Ubuntu 22.04 LTS
- **Load Testing**: k6 with 1,000 virtual users
- **Duration**: 60 seconds sustained load
- **Network**: Local VPC (sub-1ms network latency)


# 🔬 Load Testing & Benchmarking

## k6 Performance Tests

### Basic Load Test
```javascript
// basic-load-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export let options = {
  stages: [
    { duration: '2m', target: 100 },   // Ramp up
    { duration: '5m', target: 1000 },  // Stay at 1000 users
    { duration: '2m', target: 0 },     // Ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<10'],   // 95% of requests under 10ms
    http_req_failed: ['rate<0.1'],     // Error rate under 10%
  },
};

export default function () {
  let res = http.get('http://localhost:8080/health');
  
  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time < 10ms': (r) => r.timings.duration < 10,
  });
  
  sleep(0.001);
}
```

### Three-Tier Performance Test
```javascript
// three-tier-test.js
import http from 'k6/http';
import { check } from 'k6';

export let options = {
  vus: 1000,
  duration: '60s',
};

export default function () {
  // Test all three tiers
  let scenarios = [
    { url: '/health', expected_rps: 70000, tier: 'static' },
    { url: '/users', expected_rps: 60000, tier: 'cached' },
    { url: `/user/${Math.floor(Math.random() * 5) + 1}`, expected_rps: 5000, tier: 'dynamic' }
  ];
  
  let scenario = scenarios[Math.floor(Math.random() * scenarios.length)];
  let res = http.get(`http://localhost:8080${scenario.url}`);
  
  check(res, {
    [`${scenario.tier} tier status is 200`]: (r) => r.status === 200,
    [`${scenario.tier} tier has tier info`]: (r) => r.json().performance !== undefined,
  });
}
```

### Run Tests
```bash
# Install k6
# macOS
brew install k6

# Ubuntu/Debian
sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install k6

# Windows (via Chocolatey)
choco install k6

# Run the tests
k6 run basic-load-test.js
k6 run three-tier-test.js
```

## Performance Monitoring

### Built-in Performance Metrics
```python
from sufast import Sufast

app = Sufast()

@app.route("/metrics", cache_ttl=10)
def get_metrics():
    # Get real-time performance statistics
    stats = app.get_ultimate_performance_stats()
    return {
        "performance_stats": stats,
        "tier_breakdown": {
            "static_routes": "70,000+ RPS",
            "cached_routes": "60,000+ RPS", 
            "dynamic_routes": "5,000+ RPS"
        },
        "current_load": stats.get("current_requests_per_second", 0),
        "memory_usage": stats.get("memory_usage_mb", 0),
        "uptime_seconds": stats.get("uptime_seconds", 0)
    }
```

# ✨ Features & Capabilities

## 🚀 Core Features

### Performance Optimization
- ✅ **Three-tier architecture** with automatic route optimization
- ✅ **Pre-compiled static responses** for maximum throughput
- ✅ **Intelligent caching system** with configurable TTL
- ✅ **Parameter extraction** with zero-copy deserialization
- ✅ **Memory-efficient routing** using Rust's DashMap
- ✅ **Sub-millisecond response times** for optimized routes

### Developer Experience
- ✅ **Advanced Route Organization** with groups and tags for better API structure
- ✅ **Interactive API Documentation** with filtering, search, and live testing at `/docs`
- ✅ **Enhanced HTTP Methods** with intelligent defaults (GET, POST, PUT, DELETE, PATCH)
- ✅ **Smart Auto-Documentation** with rich metadata and visual organization
- ✅ **FastAPI-style decorators** with extended capabilities (`@app.route`, `@app.get`, `@app.post`)
- ✅ **Route Groups** for logical endpoint organization with prefix support
- ✅ **Tag-based Discovery** for finding related endpoints instantly
- ✅ **Real-time API Introspection** with `get_all_tags()`, `get_routes_by_group()` methods
- ✅ **Type hints support** with automatic validation
- ✅ **Hot reload** for development workflow
- ✅ **Comprehensive error handling** with detailed debugging
- ✅ **Zero-configuration setup** for immediate productivity
- ✅ **Rich middleware ecosystem** for custom functionality

### Production Ready
- ✅ **Advanced Route Groups** for large-scale API organization and maintenance
- ✅ **Tag-based Filtering** for efficient endpoint discovery and documentation
- ✅ **Interactive Documentation** at `/docs` with three view modes and live testing
- ✅ **Comprehensive Metadata** with summaries, descriptions, and examples
- ✅ **Built-in health checks** and monitoring endpoints
- ✅ **Structured logging** with configurable levels
- ✅ **Request/response lifecycle hooks** for custom processing
- ✅ **CORS support** for cross-origin requests
- ✅ **Rate limiting** to prevent abuse
- ✅ **Graceful shutdown** handling

## 🔧 Advanced Features

### Route Organization & Documentation
```python
# Advanced route groups with organization
users_group = app.group("User Management", prefix="/api/v1", tags=["api", "users"])
@users_group.get("/users", summary="List users", tags=["pagination"])
def list_users(): ...

# Rich metadata for enhanced documentation
@app.get("/products/{id}", 
         tags=["products", "details"], 
         group="Product Catalog",
         summary="Get product details",
         description="Retrieve comprehensive product information")
def get_product(id): ...

# Tag-based organization and discovery
@app.tag("admin", "monitoring")
@app.get("/system/health", static=True)
def health_check(): ...
```

### Enhanced HTTP Method Support
```python
# Complete REST API with intelligent defaults
@app.get("/items", cache_ttl=300, tags=["read"])  # Auto-cached reads
@app.post("/items", tags=["create"])              # Validated creates
@app.put("/items/{id}", tags=["update"])          # Full updates
@app.patch("/items/{id}", tags=["modify"])        # Partial updates
@app.delete("/items/{id}", tags=["cleanup"])      # Safe deletes
```

### Interactive Documentation System
```python
# Three powerful view modes at /docs:
# 1. Performance Tiers: Static (🔥) / Cached (🧠) / Dynamic (⚡)
# 2. Groups: Organized by RouteGroup classifications
# 3. Tags: Filter and discover by functionality

# Real-time API introspection
all_tags = app.get_all_tags()
user_routes = app.get_routes_by_group("User Management")
admin_endpoints = app.get_routes_by_tag("admin")
```

### Route Types & Performance
```python
# Static routes (70K+ RPS)
@app.route("/health", static=True)
def health(): ...

# Cached routes (60K+ RPS)  
@app.route("/data", cache_ttl=300)
def get_data(): ...

# Dynamic routes (5K+ RPS)
@app.route("/user/{id}")
def get_user(id): ...

# Multi-parameter routes
@app.route("/user/{user_id}/post/{post_id}")
def get_user_post(user_id, post_id): ...
```

### Middleware Support
```python
# Custom middleware
@app.middleware("request")
async def log_requests(request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    print(f"Request processed in {process_time:.4f}s")
    return response

# Built-in CORS middleware
@app.middleware("cors")
def setup_cors():
    return {
        "allow_origins": ["*"],
        "allow_methods": ["GET", "POST", "PUT", "DELETE"],
        "allow_headers": ["*"]
    }
```

### Error Handling
```python
# Custom error handlers
@app.exception_handler(404)
def not_found_handler(request, exc):
    return {"error": "Not found", "path": request.url.path}

@app.exception_handler(500)  
def server_error_handler(request, exc):
    return {"error": "Internal server error", "details": str(exc)}
```

## 🎯 Use Cases

### High-Performance APIs
- ✅ Microservices with extreme throughput requirements
- ✅ Real-time data streaming endpoints
- ✅ Health check and monitoring systems
- ✅ Static content delivery with dynamic fallbacks

### AI/ML Applications  
- ✅ Model inference endpoints with low latency
- ✅ Feature serving for recommendation systems
- ✅ Real-time prediction APIs
- ✅ High-throughput data preprocessing pipelines

### Enterprise Systems
- ✅ Internal service meshes requiring high RPS
- ✅ API gateways and proxy services
- ✅ Caching layers for database-heavy applications
- ✅ Event streaming and webhook handlers



# � Deployment Guide

## 🐳 Docker Deployment

### Dockerfile
```dockerfile
FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Expose port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

# Run the application
CMD ["python", "app.py"]
```

### docker-compose.yml
```yaml
version: '3.8'

services:
  sufast-api:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SUFAST_ENV=production
      - SUFAST_LOG_LEVEL=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped
    
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - sufast-api
    restart: unless-stopped
```

## ☸️ Kubernetes Deployment

### deployment.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sufast-api
  labels:
    app: sufast-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: sufast-api
  template:
    metadata:
      labels:
        app: sufast-api
    spec:
      containers:
      - name: sufast-api
        image: your-registry/sufast-api:latest
        ports:
        - containerPort: 8080
        env:
        - name: SUFAST_ENV
          value: "production"
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: sufast-service
spec:
  selector:
    app: sufast-api
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: LoadBalancer
```

## 🌐 Production Configuration

### Environment Variables
```bash
# Production settings
export SUFAST_ENV=production
export SUFAST_HOST=0.0.0.0
export SUFAST_PORT=8080
export SUFAST_WORKERS=4

# Performance tuning
export SUFAST_CACHE_SIZE=1000000
export SUFAST_MAX_CONNECTIONS=10000
export SUFAST_TIMEOUT=30

# Logging
export SUFAST_LOG_LEVEL=info
export SUFAST_LOG_FORMAT=json

# Security
export SUFAST_CORS_ORIGINS="https://yourdomain.com"
export SUFAST_RATE_LIMIT=1000
```

### Production App Structure
```python
# production_app.py
import os
from sufast import Sufast

# Initialize with production settings
app = Sufast(
    debug=False,
    cors_origins=os.getenv("SUFAST_CORS_ORIGINS", "*").split(","),
    rate_limit=int(os.getenv("SUFAST_RATE_LIMIT", "1000")),
    cache_size=int(os.getenv("SUFAST_CACHE_SIZE", "1000000"))
)

# Production middleware
@app.middleware("request")
async def security_headers(request, call_next):
    response = await call_next(request)
    response.headers.update({
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "DENY",
        "X-XSS-Protection": "1; mode=block",
        "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
    })
    return response

# Your routes here...

if __name__ == "__main__":
    app.run(
        host=os.getenv("SUFAST_HOST", "0.0.0.0"),
        port=int(os.getenv("SUFAST_PORT", "8080")),
        workers=int(os.getenv("SUFAST_WORKERS", "4"))
    )
```

# 🔭 Roadmap & Future Plans

## 🎯 Version 2.1 (Q3 2025)
- 🔐 **Authentication & Authorization**
  - JWT token support with RS256/HS256
  - OAuth 2.0 integration (Google, GitHub, etc.)
  - Role-based access control (RBAC)
  - API key authentication

- 🗄️ **Database Integration**
  - Built-in PostgreSQL adapter
  - MongoDB async driver
  - Redis caching layer
  - SQLAlchemy ORM support

- ✅ **Request Validation**
  - Pydantic model integration
  - Automatic OpenAPI schema generation
  - Input sanitization and validation
  - Custom validation decorators

## 🚀 Version 2.2 (Q4 2025)
- 📁 **Static File Serving**
  - High-performance static file handler
  - CDN integration support
  - Asset compression and caching
  - SPA routing support

- 🔧 **Advanced Middleware**
  - Rate limiting with Redis backend
  - Request/response compression
  - Custom authentication handlers
  - Metrics collection middleware

- 🐳 **Enhanced DevOps**
  - Official Docker images
  - Helm charts for Kubernetes
  - CI/CD pipeline templates
  - Health check endpoints

## 🌟 Version 3.0 (Q1 2026)
- 🔄 **WebSocket Support**
  - Real-time bidirectional communication
  - WebSocket routing and middleware
  - Server-sent events (SSE)
  - Socket.IO compatibility layer

- 🧠 **AI/ML Features**
  - Built-in model serving endpoints
  - Automatic batching for inference
  - GPU acceleration support
  - Model versioning and A/B testing

- 🌐 **Microservices Tools**
  - Service discovery integration
  - Circuit breaker patterns
  - Distributed tracing
  - API gateway features

## 📈 Performance Goals
- **Version 2.1**: Target 80,000+ RPS for static routes
- **Version 2.2**: Sub-millisecond P99 latency for cached routes
- **Version 3.0**: 100,000+ RPS with WebSocket support

## 🤝 Community Roadmap
Vote on features and contribute ideas:
- 📊 [GitHub Discussions](https://github.com/shohan-dev/sufast/discussions)
- 🎯 [Feature Requests](https://github.com/shohan-dev/sufast/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
- �️ [Public Roadmap](https://github.com/shohan-dev/sufast/projects)

# ⚠️ Development Status & Production Readiness

## 🎯 Current Status: **ACTIVE DEVELOPMENT**

Sufast is currently in **active development** with impressive performance characteristics but requires additional features for full production deployment.

### ✅ **Production-Ready Components**
- ✅ **High-performance routing** (70K+ RPS demonstrated)
- ✅ **Three-tier optimization** architecture
- ✅ **Parameter extraction** and route matching
- ✅ **Basic middleware** support
- ✅ **Error handling** and debugging
- ✅ **Load testing** validation with k6

### ⚠️ **Development Components** (Coming Soon)
- 🔐 **Authentication & Authorization** (v2.1)
- 🗄️ **Database integration** (PostgreSQL, MongoDB)
- ✅ **Request validation** with Pydantic
- 🔒 **Security headers** and CORS
- 📝 **Structured logging** and monitoring
- 🐳 **Production deployment** guides

### 🎯 **Recommended Usage**

#### ✅ **Great For:**
- **High-performance prototypes** and proof of concepts
- **Microservices** with simple routing needs
- **Performance testing** and benchmarking
- **Learning** hybrid Rust-Python architectures
- **Contributing** to open source projects

#### ⚠️ **Not Ready For:**
- **Production applications** requiring authentication
- **Enterprise systems** needing comprehensive security
- **Database-heavy applications** without custom integration
- **Mission-critical services** requiring 99.9% uptime

### 💰 **Production Budget Considerations**

For projects with **$10K+ backend budgets**, we recommend:

1. **Hybrid Approach** (Recommended):
   - Use **FastAPI** for complex business logic (70% of routes)
   - Use **Sufast** for high-performance endpoints (30% of routes)
   - Best of both worlds: production features + performance

2. **Wait for v2.1** (Q3 2025):
   - Full authentication and database support
   - Production-ready security features
   - Comprehensive documentation and examples

3. **Custom Development**:
   - Contribute to Sufast development
   - Add missing production features
   - $6K-8K development investment

### 🚀 **Getting Production-Ready**

Join our development community:
- 📧 **Early Access**: Get notified of production-ready releases
- 🤝 **Contributing**: Help build missing features
- 💬 **Discord**: Join our developer community
- 🎯 **Roadmap**: Vote on priority features

**Bottom Line**: Sufast delivers exceptional performance but needs v2.1 for full production deployment. Consider hybrid approaches for immediate production needs.


# 🤝 Contributing & Community

## 🌟 Join the Sufast Community

We're building the fastest Python web framework together! Join our growing community of developers, contributors, and performance enthusiasts.

### � **Community Channels**
- 💬 **[Discord Server](https://discord.gg/sufast)** - Real-time chat and support
- 📊 **[GitHub Discussions](https://github.com/shohan-dev/sufast/discussions)** - Feature requests and ideas
- 🐛 **[GitHub Issues](https://github.com/shohan-dev/sufast/issues)** - Bug reports and tracking
- 📧 **[Newsletter](https://sufast.dev/newsletter)** - Development updates and releases

### 🚀 **How to Contribute**

#### 🐛 **Bug Reports**
Found a bug? Help us improve!
```bash
# 1. Check existing issues first
# 2. Create a minimal reproduction case
# 3. Include system information:
#    - OS and version
#    - Python version  
#    - Sufast version
#    - Error logs and stack traces
```

#### ✨ **Feature Development**
```bash
# 1. Fork the repository
git clone https://github.com/your-username/sufast.git
cd sufast

# 2. Create a feature branch
git checkout -b feature/amazing-feature

# 3. Set up development environment
pip install -e .[dev]
python scripts/setup_dev.py

# 4. Make your changes
# 5. Run tests
python scripts/test.py

# 6. Commit and push
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature

# 7. Open a Pull Request
```

#### 📚 **Documentation**
Help improve our documentation:
- API reference and examples
- Performance optimization guides
- Deployment and production guides
- Tutorial content for beginners

#### 🔧 **Development Priorities**

**High Priority (v2.1)**:
- 🔐 Authentication systems (JWT, OAuth)
- 🗄️ Database integration (PostgreSQL, MongoDB)
- ✅ Request validation with Pydantic
- 🔒 Security middleware and headers

**Medium Priority (v2.2)**:
- 📁 Static file serving optimization
- 📊 Metrics and monitoring integration
- 🐳 Docker and Kubernetes support
- 🧪 Advanced testing utilities

**Future Vision (v3.0)**:
- 🔄 WebSocket and real-time features
- 🧠 AI/ML model serving integration
- 🌐 Microservices and service mesh tools

### 🏆 **Contributor Recognition**

#### 🌟 **Hall of Fame**
- **Core Contributors**: Direct commit access and decision-making
- **Feature Champions**: Lead specific feature development
- **Community Heroes**: Help others and improve documentation
- **Performance Wizards**: Optimize and benchmark the framework

#### 🎁 **Contributor Perks**
- 🏷️ **Exclusive swag** for major contributions
- 🎯 **Early access** to new features and releases
- 💼 **LinkedIn recommendations** for significant contributions
- 🗣️ **Speaking opportunities** at conferences and meetups

### 📋 **Contribution Guidelines**

#### **Code Quality Standards**
```bash
# Before submitting:
1. Run the full test suite: `python scripts/test.py`
2. Check code formatting: `python scripts/lint.py`
3. Verify performance benchmarks: `python scripts/benchmark.py`
4. Update documentation if needed
5. Add tests for new features
```

#### **Commit Message Format**
```
type(scope): brief description

- feat: new features
- fix: bug fixes  
- docs: documentation changes
- perf: performance improvements
- test: test additions/modifications
- refactor: code restructuring

Example: feat(routing): add multi-parameter route support
```

### 🎯 **Getting Started**

#### **First-Time Contributors**
1. ⭐ **Star the repository** to show support
2. 🍴 **Fork the project** to your GitHub accou