# Django Hurricane

> The High-Performance, Django-Native Application Server for Docker, Cloud, and Kubernetes.

Django Hurricane is a production-ready application server built specifically for Django. Powered by Granian's high-performance Rust core (Hyper / Tokio), Hurricane replaces Gunicorn, Uvicorn, Nginx sidecars, and WhiteNoise with a unified, zero-configuration runtime.

## Core Features

- **Granian Core Engine:** High-performance HTTP 1.1/2 handling powered by Rust's Hyper and Tokio, delivering zero-copy asynchronous networking and 2x higher throughput than Gunicorn or Tornado.
- **Zero-Config WSGI & ASGI Auto-Detection:** Automatically executes WSGI (`WSGI_APPLICATION`) or ASGI (`ASGI_APPLICATION`) from Django settings.
- **Three-Tier Static & Media Asset Serving:** Nginx-grade static asset streaming via kernel sendfile and HTTP 304 caching, plus zero-setup live development finders fallback (`--static`, `--media`).
- **First-Line Defense Shields:**
  - **Fast-404:** Intercepts bot/scanner dictionary attacks (`.php`, `/.env`, `/wp-admin/`) at the gateway in &lt;0.35µs with zero Django overhead and silent drop logging.
  - **Token-Bucket Rate Limiter:** Enforces traffic quotas (default: 10 req/s, burst 30) with proxy header client IP extraction (`X-Forwarded-For`, `CF-Connecting-IP`, `X-Real-IP`).
- **Deep Health & Observability:** Out-of-the-box `/startup`, `/alive`, `/ready`, and `/metrics` (Prometheus) endpoints compatible with Docker healthchecks, AWS ALBs, and Kubernetes probes.
- **Traffic Shedding Under Congestion:** Saturated worker backlogs automatically trigger HTTP 400 on `/ready` to shed Ingress traffic before containers crash.

## Quickstart

Install via `uv` or `pip`:
```bash
uv add django-hurricane
# or
pip install django-hurricane
```

Add to `settings.py`:
```python
INSTALLED_APPS = [
    # ...
    "hurricane",
]
```

Run server:
```bash
python manage.py serve --port=8000 --static --media
```

## CLI Reference (`manage.py serve`)

- `--port`: Application HTTP port (default: 8000).
- `--probe-port`: Probe/metrics port (default: port + 1, e.g. 8001). Set equal to `--port` for single-port integrated routing.
- `--static`: Enable static files serving (auto-detects `STATIC_ROOT` and `STATIC_URL`).
- `--media`: Enable user-uploaded media files serving (auto-detects `MEDIA_ROOT` and `MEDIA_URL`).
- `--collectstatic`: Run `collectstatic --noinput` automatically on server startup.
- `--workers`: Number of worker threads / max concurrency ceiling (default: container CPUs + 4).
- `--runtime-threads`: Rust/Tokio runtime worker threads (default: detected container CPUs, capped at 4).
- `--req-queue-len`: Saturated queue threshold for readiness failure (default: workers * 2).
- `--fast-404`: Fast-404 mode (`auto`, `prefix`, `signature`, `off`).
- `--rate-limit`: Rate limit frequency (e.g. `10/s`, `off`).
- `--rate-limit-burst`: Token-bucket burst allowance (default: 30).
- `--rate-limit-proxy-header`: Header for client IP extraction (`X-Forwarded-For`, `CF-Connecting-IP`, `X-Real-IP`).

## Key Documentation Links

- **Getting Started:** https://django-hurricane.io/guides/getting-started
- **Standalone, Docker & Cloud Deployments:** https://django-hurricane.io/guides/standalone-and-cloud-deployments
- **Static & Media Serving Architecture:** https://django-hurricane.io/guides/static-and-media-files
- **Kubernetes Production Guide:** https://django-hurricane.io/guides/kubernetes-deployment
- **Benchmark Suite & Results:** https://django-hurricane.io/performance/benchmark-suite
- **Kubernetes Sizing & Architecture Recommendations:** https://django-hurricane.io/performance/architecture-recommendations
- **Product Roadmap:** https://django-hurricane.io/roadmap/feature-roadmap
