django-bolt 0.1.0__cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

django_bolt-0.1.0.dist-info/METADATA

@@ -0,0 +1,629 @@
+Metadata-Version: 2.4
+Name: django-bolt
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Programming Language :: Rust
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Dist: django>=4.2
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2
+Requires-Dist: msgspec>=0.18
+Requires-Dist: maturin>=1.9.4
+Requires-Dist: watchfiles>=0.24
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: multipart>=1.3
+Summary: High-performance API framework for Django with Rust-powered endpoints delivering 60k+ RPS
+Keywords: django,api,rust,performance,actix,pyo3,async
+Author-email: Farhan <farhanalirazaazeemi@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/FarhanAliRaza/django-bolt
+Project-URL: Repository, https://github.com/FarhanAliRaza/django-bolt
+Project-URL: Documentation, https://github.com/FarhanAliRaza/django-bolt#readme
+Project-URL: Bug Tracker, https://github.com/FarhanAliRaza/django-bolt/issues
+
+<div align="center">
+  <img src="docs/logo.png" alt="Django-Bolt Logo" width="400"/>
+
+  [![Seeking Remote Work](https://img.shields.io/badge/🌍-Actively%20Seeking%20Remote%20Work-success?style=for-the-badge)](mailto:farhanalirazaazeemi@gmail.com)
+</div>
+
+**High-Performance Fully Typed API Framework for Django**
+
+Django-Bolt is a high-performance API framework for Django that provides Rust-powered API endpoints capable of **60k+ RPS** performance. Similar to Django REST Framework or Django Ninja, it integrates seamlessly with existing Django projects while leveraging Actix Web for HTTP handling, PyO3 to bridge Python async handlers with Rust's async runtime, msgspec for fast serialization, and supports multi-process scaling with SO_REUSEPORT.
+
+**Key Features:**
+
+- 🚀 **High Performance** - Rust-powered HTTP server (Actix Web + Tokio + PYO3)
+- 🔐 **Authentication in Rust** - JWT/API Key validation without Python GIL
+- 📦 **msgspec Serialization** - 5-10x faster than standard JSON
+- 🎯 **Django Integration** - Use your existing Django models and other django features you love (django admin, django packages (All django packages will work except that use django middlware for now. I will work on some compatibilty layer to make them work but it is not a priority right now) )
+- 🔄 **Async/Await** - Full async support with Python coroutines
+- 🎛️ **Middleware System** - CORS, rate limiting, compression, custom middleware
+- 🔒 **Guards & Permissions** - DRF and litestar inspired route protection
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+COMING VERY SOON NEAR YOUR DJANGO PROJECTS
+
+For now you can build and use it locally if you want.
+
+### Run Your First API
+
+```python
+# myproject/api.py
+from django_bolt import BoltAPI
+from django.contrib.auth.models import User
+import msgspec
+
+api = BoltAPI()
+
+class UserSchema(msgspec.Struct):
+    id: str
+    username: str
+
+
+@api.get("/users/{user_id}")
+async def get_user(user_id: int) -> UserSchema: # 🎉 Reponse is type validated
+    user = await User.objects.aget(id=user_id) # 🤯 Yes and Django orm works without any setup
+    return {"id": user.id, "username": user.username} # or you could just return the queryset
+
+```
+
+```bash
+# Start the server
+python manage.py runbolt --host 0.0.0.0 --port 8000 --processes 4 --workers 1
+# processes are python processes that handle request 1 actix worker
+```
+
+---
+
+## 📊 Performance Benchmarks
+
+> **⚠️ Disclaimer:** Django-Bolt is a **feature-incomplete framework** currently in development. Benchmarks were run on a Ryzen 5600G with 16GB RAM (8 processes × 1 worker, C=100 N=10000) on localhost. Performance will vary significantly based on hardware, OS, configuration, and workload.
+>
+> **📁 Resources:** Example project available at [python/examples/testproject/](python/examples/testproject/). Run benchmarks with `make save-bench` or see [scripts/benchmark.sh](scripts/benchmark.sh).
+
+| Endpoint Type              | Requests/sec    |
+| -------------------------- | --------------- |
+| Root endpoint              | **~86,500 RPS** |
+| JSON parsing/validation    | **~81,000 RPS** |
+| Path + Query params        | **~62,500 RPS** |
+| HTML/Redirect responses    | **~88,000 RPS** |
+| Form data handling         | **~69,000 RPS** |
+| ORM reads (SQLite, 10 rec) | **~12,000 RPS** |
+
+**Why so fast?**
+
+- Authentication and guards run in Rust without the Python GIL
+- Request routing uses matchit (zero-copy path matching)
+- No middleware overhead if not required
+- JSON serialization with msgspec
+- Multi-process with SO_REUSEPORT (kernel-level load balancing)
+
+---
+
+## ✅ What's Complete
+
+### Core Framework ✅
+
+- ✅ **Rust HTTP Server** - Actix Web with tokio async runtime
+- ✅ **Fast Routing** - matchit-based routing with path parameters (`/items/{id}`)
+- ✅ **Async Handlers** - Full async/await support (enforced async handlers)
+- ✅ **Request/Response** - msgspec-based validation and serialization
+- ✅ **Multiple Response Types**:
+  - `JSON` - msgspec-serialized JSON responses
+  - `PlainText` - Plain text responses
+  - `HTML` - HTML responses
+  - `Redirect` - HTTP redirects
+  - `File` - File downloads (in-memory)
+  - `FileResponse` - Streaming file responses (handled in Rust)
+  - `StreamingResponse` - Async streaming for large payloads
+- ✅ **Parameter Injection**:
+  - Path parameters (`/items/{id}`)
+  - Query parameters (`?page=1&limit=10`)
+  - Headers (`Annotated[str, Header("x-api-key")]`)
+  - Cookies (`Annotated[str, Cookie("session")]`)
+  - Form data (`Annotated[str, Form("username")]`)
+  - File uploads (`Annotated[bytes, File("upload")]`)
+  - Request body (msgspec.Struct)
+- ✅ **Dependency Injection** - `Depends()` system for reusable dependencies
+- ✅ **Django ORM Integration** - Full access to Django models (async methods)
+- ✅ **Multi-Process Scaling** - SO_REUSEPORT for horizontal scaling
+- ✅ **Auto-Discovery** - Finds `api.py` in project root and all installed apps
+
+### Middleware System ✅
+
+- ✅ **Global Middleware** - Apply to all routes via `BoltAPI(middleware=[...])`
+- ✅ **Per-Route Middleware** - `@middleware`, `@rate_limit`, `@cors` decorators
+- ✅ **CORS Middleware** - Full CORS support with preflight
+- ✅ **Rate Limiting** - Token bucket algorithm (in Rust, no GIL)
+- ✅ **Compression** - Automatic gzip/brotli/zstd compression (client-negotiated)
+- ✅ **Skip Middleware** - `@skip_middleware("cors", "rate_limit", "compression")`
+- ✅ **Middleware Config** - Dictionary-based configuration
+
+### Authentication & Authorization ✅
+
+- ✅ **JWT Authentication** - **Complete** (runs in Rust without GIL)
+
+  - Algorithms: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512
+  - Token validation in Rust (zero Python overhead)
+  - Expiration validation
+  - Custom claims support
+  - Django User integration helpers
+  - Token revocation support (optional)
+
+- ✅ **API Key Authentication** - **Partial** (runs in Rust without GIL)
+
+  - Header-based API keys
+  - Per-key permissions
+  - Fast validation in Rust
+
+- ✅ **Permission Guards** (all run in Rust):
+
+  - `AllowAny()` - Public access
+  - `IsAuthenticated()` - Requires valid auth
+  - `IsAdminUser()` - Requires admin/superuser
+  - `IsStaff()` - Requires staff status
+  - `HasPermission("perm")` - Single permission check
+  - `HasAnyPermission("p1", "p2")` - OR logic
+  - `HasAllPermissions("p1", "p2")` - AND logic
+
+- ✅ **Auth Context** - Request-level auth context with user info
+- ✅ **Token Utilities**:
+
+  - `create_jwt_for_user(user)` - Generate JWT for Django User
+
+- ✅ **Token Revocation** (optional):
+  - `InMemoryRevocation` - In-memory token blacklist
+  - `DjangoCacheRevocation` - Cache-based revocation
+  - `DjangoORMRevocation` - Database-backed revocation
+
+### Developer Tools ✅
+
+- ✅ **CLI** - `python -m django_bolt init` for project setup
+- ✅ **Management Command** - `python manage.py runbolt`
+- ✅ **Auto-Discovery** - Finds APIs in all Django apps
+- ⚠️ **Error Messages** - Clear error messages (In Progress)
+- ✅ **Type Hints** - Full type hint support with msgspec
+
+---
+
+## 📋 TODO / Roadmap
+
+### Must Have (Blockers) 🚨
+
+- ✅ **Core API functionality** - DONE
+- ✅ **Authentication** - DONE (JWT complete)
+- ✅ **Tests passing** - DONE (142 passed)
+- ✅ **Better error messages** - DONE (Enhanced exception system with structured errors)
+- ✅ **Health check endpoints** - DONE (`/health`, `/ready` with custom checks)
+- ✅ **Request/Response logging** - DONE (Integrates with Django's logging)
+- ❌ **PyPI package** - Missing (currently manual install)
+
+### Should Have (Important) 🎯
+
+- ✅ **Error handling with Django DEBUG integration** - DONE
+- ✅ **Structured error responses** (FastAPI-compatible) - DONE
+- ✅ **Response compression** - DONE (gzip/brotli/zstd)
+- ✅ **OpenAPI/Swagger docs** - DONE (some parts remaining like grouping)
+- ✅ **Django admin integration** - DONE
+- ⚠️ **API Key auth** - Partial (only in-memory)
+- ⚠️ **Testing utilities** - Partial
+
+### Nice to Have (Can defer) 📝
+
+- [ ] **Static file serving** - Efficient static file serving from Rust
+- [ ] **Pagination helpers** - Built-in pagination utilities
+- [ ] **OAuth2/OpenID** - OAuth2 and OpenID Connect support
+- [ ] **API Versioning** - URL/header-based versioning
+- [ ] **Content Negotiation** - Accept header-based content negotiation
+- [ ] **ETags & Conditional Requests** - Caching optimization
+- [ ] **Filtering & Sorting** - Query parameter-based filtering
+
+---
+
+## 🏗️ Architecture
+
+### Core Components
+
+1. **[src/lib.rs](src/lib.rs)** - Main Rust entry point, exposes PyO3 module
+2. **[src/server.rs](src/server.rs)** - Actix Web server with multi-worker tokio runtime
+3. **[src/router.rs](src/router.rs)** - matchit-based routing
+4. **[src/middleware/](src/middleware/)** - Middleware pipeline
+   - `auth.rs` - JWT/API Key authentication (zero GIL overhead)
+   - `cors.rs` - CORS handling
+   - `rate_limit.rs` - Token bucket rate limiting
+5. **[src/permissions.rs](src/permissions.rs)** - Guard evaluation
+6. **[python/django_bolt/api.py](python/django_bolt/api.py)** - Python decorator-based API
+7. **[python/django_bolt/auth/](python/django_bolt/auth/)** - Authentication system
+   - `backends.py` - Auth backend classes (compile to Rust metadata)
+   - `guards.py` - Permission guard classes
+   - `jwt_utils.py` - JWT utilities for Django User integration
+   - `middleware.py` - Middleware decorators
+   - `token.py` - Token handling
+   - `revocation.py` - Token revocation stores
+
+### Request Flow
+
+```
+HTTP Request → Actix Web (Rust)
+           ↓
+    Route Matching (matchit)
+           ↓
+    Middleware Pipeline (Rust - no GIL)
+      - CORS
+      - Rate Limiting
+           ↓
+    Authentication (Rust - no GIL for most part may require in future)
+      - JWT validation
+      - API Key validation
+           ↓
+    Guards/Permissions (Rust - no GIL)
+      - IsAuthenticated
+      - IsAdminUser
+      - HasPermission
+           ↓
+    Python Handler (PyO3 bridge)
+           ↓
+    Parameter Extraction & Validation (msgspec)
+           ↓
+    Handler Execution (async Python)
+      - Django ORM access
+      - Business logic
+           ↓
+    Response Serialization (msgspec)
+           ↓
+    HTTP Response
+```
+
+---
+
+## 📖 Usage Examples
+
+### Basic Routes
+
+```python
+from django_bolt import BoltAPI
+import msgspec
+from typing import Optional
+
+api = BoltAPI()
+
+# Simple GET
+@api.get("/hello")
+async def hello():
+    return {"message": "Hello, World!"}
+
+# Path parameters
+@api.get("/users/{user_id}")
+async def get_user(user_id: int):
+    return {"user_id": user_id}
+
+# Query parameters
+@api.get("/search")
+async def search(q: str, limit: int = 10):
+    return {"query": q, "limit": limit}
+
+# Request body with validation
+class CreateUserRequest(msgspec.Struct):
+    username: str
+    email: str
+    age: int
+
+@api.post("/users", response_model=CreateUserRequest)
+async def create_user(user: CreateUserRequest):
+    # Validated automatically
+    return user
+```
+
+### Authentication & Guards
+
+```python
+from django_bolt import BoltAPI
+from django_bolt.auth import (
+    JWTAuthentication,
+    IsAuthenticated,
+    IsAdminUser,
+    HasPermission,
+)
+
+api = BoltAPI()
+
+# Require JWT authentication
+@api.get(
+    "/protected",
+    auth=[JWTAuthentication()],
+    guards=[IsAuthenticated()]
+)
+async def protected_route(request):
+    auth_context = request.get("auth", {})
+    user_id = auth_context.get("user_id")
+    return {"message": f"Hello, user {user_id}"}
+
+# Require admin access
+@api.get(
+    "/admin",
+    auth=[JWTAuthentication()],
+    guards=[IsAdminUser()]
+)
+async def admin_only(request):
+    return {"message": "Admin access"}
+
+# Permission-based access
+@api.post(
+    "/articles",
+    auth=[JWTAuthentication()],
+    guards=[HasPermission("articles.create")]
+)
+async def create_article(request):
+    return {"message": "Article created"}
+
+# Create JWT token for Django user
+from django_bolt.auth import create_jwt_for_user
+from django.contrib.auth.models import User
+
+@api.post("/login")
+async def login(username: str, password: str):
+    user = await User.objects.aget(username=username)
+    # Verify password...
+    token = create_jwt_for_user(user, exp_hours=24)
+    return {"access_token": token, "token_type": "bearer"}
+```
+
+### Middleware
+
+```python
+from django_bolt import BoltAPI
+from django_bolt.auth import cors, rate_limit, skip_middleware
+
+# Global middleware
+api = BoltAPI(
+    middleware_config={
+        "cors": {
+            "origins": ["http://localhost:3000"],
+            "methods": ["GET", "POST", "PUT", "DELETE"],
+        }
+    }
+)
+
+# Per-route rate limiting
+@api.get("/limited")
+@rate_limit(rps=10, burst=20)
+async def limited_endpoint():
+    return {"message": "Rate limited to 10 req/s"}
+
+# Custom CORS for specific route
+@api.get("/public")
+@cors(origins=["*"])
+async def public_endpoint():
+    return {"message": "Public endpoint with CORS"}
+
+# Skip global middleware
+@api.get("/no-cors")
+@skip_middleware("cors")
+async def no_cors():
+    return {"message": "CORS disabled for this route"}
+```
+
+### Django ORM Integration
+
+```python
+from django_bolt import BoltAPI
+from django.contrib.auth.models import User
+from myapp.models import Article
+
+api = BoltAPI()
+
+@api.get("/users/{user_id}")
+async def get_user(user_id: int):
+    # Use Django's async ORM methods
+    user = await User.objects.aget(id=user_id)
+    return {
+        "id": user.id,
+        "username": user.username,
+        "email": user.email,
+    }
+
+@api.get("/articles")
+async def list_articles(limit: int = 10):
+    # Async query with select_related
+    articles = await Article.objects.select_related("author").all()[:limit]
+    return [
+        {
+            "id": a.id,
+            "title": a.title,
+            "author": a.author.username,
+        }
+        async for a in articles
+    ]
+```
+
+### Response Types
+
+```python
+from django_bolt import BoltAPI
+from django_bolt.responses import PlainText, HTML, Redirect, FileResponse
+
+api = BoltAPI()
+
+@api.get("/text")
+async def text_response():
+    return PlainText("Hello, World!")
+
+@api.get("/html")
+async def html_response():
+    return HTML("<h1>Hello</h1>")
+
+@api.get("/redirect")
+async def redirect_response():
+    return Redirect("/new-location")
+
+@api.get("/download")
+async def download_file():
+    # Streams file from Rust (zero-copy)
+    return FileResponse("/path/to/file.pdf", filename="document.pdf")
+```
+
+### Streaming Responses
+
+```python
+from django_bolt import BoltAPI
+from django_bolt.responses import StreamingResponse
+import asyncio
+
+api = BoltAPI()
+
+@api.get("/stream")
+async def stream_data():
+    async def generate():
+        for i in range(100):
+            yield f"data: {i}\n\n"
+            await asyncio.sleep(0.1)
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream"
+    )
+```
+
+---
+
+## 🔧 Development
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/yourusername/django-bolt.git
+cd django-bolt
+
+# Install dependencies
+pip install -r requirements-dev.txt
+
+# Build Rust extension
+make build  # or: maturin develop --release
+
+# Run tests
+make test-py
+```
+
+### Commands
+
+```bash
+# Build
+make build          # Build Rust extension
+make rebuild        # Clean and rebuild
+
+# Testing
+make test-py        # Run Python tests
+make smoke          # Quick smoke tests
+make orm-smoke      # ORM-specific tests
+
+# Benchmarking
+make bench          # Run benchmarks
+make save-bench     # Run and save results
+make bench C=100 N=50000  # Custom benchmark
+
+# Server
+make run-bg HOST=127.0.0.1 PORT=8000 P=2 WORKERS=2
+```
+
+---
+
+## 📁 Project Structure
+
+```
+django-bolt/
+├── src/                              # Rust server code
+│   ├── lib.rs                        # PyO3 module entry point
+│   ├── server.rs                     # Actix Web server
+│   ├── router.rs                     # matchit routing
+│   ├── middleware/
+│   │   ├── mod.rs
+│   │   ├── auth.rs                   # JWT/API Key auth (no GIL)
+│   │   ├── cors.rs                   # CORS handling
+│   │   └── rate_limit.rs             # Token bucket rate limiting
+│   ├── permissions.rs                # Guard evaluation
+│   └── streaming.rs                  # Streaming response handling
+├── python/django_bolt/               # Python framework
+│   ├── api.py                        # BoltAPI class, decorators
+│   ├── responses.py                  # Response types
+│   ├── exceptions.py                 # HTTP exceptions
+│   ├── params.py                     # Parameter markers
+│   ├── auth/                         # Authentication system
+│   │   ├── __init__.py
+│   │   ├── backends.py               # Auth backends
+│   │   ├── guards.py                 # Permission guards
+│   │   ├── middleware.py             # Middleware decorators
+│   │   ├── jwt_utils.py              # JWT utilities
+│   │   ├── token.py                  # Token handling
+│   │   └── revocation.py             # Token revocation
+│   ├── management/commands/
+│   │   └── runbolt.py                # Django management command
+│   ├── cli.py                        # django-bolt CLI
+│   ├── tests/                        # Test suite
+│   │   ├── test_auth_secret_key.py
+│   │   ├── test_guards_auth.py
+│   │   ├── test_guards_integration.py
+│   │   ├── test_jwt_auth.py
+│   │   ├── test_jwt_token.py
+│   │   ├── test_middleware.py
+│   │   └── test_syntax.py
+│   └── bootstrap.py                  # Django setup helper
+└── python/examples/testproject/      # Example Django project
+    ├── manage.py
+    ├── testproject/
+    │   ├── settings.py
+    │   └── api.py                    # Example routes
+    └── users/                        # Example app
+        ├── models.py
+        └── api.py
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Here's how:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests (`make test-py`)
+5. Commit (`git commit -m 'Add amazing feature'`)
+6. Push (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+### Areas That Need Help
+
+- Authentication
+- OpenAPI/Swagger generation
+- More comprehensive tests and test utilities
+- Documentation improvements
+
+---
+
+**Built with ⚡ by developers who need speed without sacrificing Python's elegance**
+