Hurricane

The Kubernetes-Native Application Server for Django.
Now powered by Granian (Hyper / Tokio / Rust 🦀) with zero-config WSGI & ASGI support.

Website & Documentation · Getting Started · Configuration Reference

"Did somebody say Rewrite It In Rust?" 🦀

As is required by Internet Law™, we felt the moral imperative to bring Rust into the Python ecosystem.

Previous versions of Hurricane relied on Tornado to bridge asynchronous networking with Django's synchronous WSGI layer. While pioneering, Tornado's Python event loop occasionally threw tantrums under heavy concurrency-choking on WSGI thread transitions and flapping Kubernetes readiness probes with false queue-saturation warnings.

We ripped that out.

Hurricane is now powered by Granian, a lightning-fast HTTP server built directly on Rust’s Hyper and Tokio runtimes. You get:

• 🚀 Blazingly fast HTTP handling with zero-copy I/O.
• 🦀 Rust concurrency managing TCP connection pools and worker dispatch.
• 🧘 True peace of mind: Kubernetes probes that reflect actual server capacity rather than asyncio event loop panic.

⚡ Benchmarks: Tornado vs. Granian

We pit the classic Tornado-based Hurricane against the new Granian-powered engine using Locust under identical high-concurrency conditions:

Under heavy traffic, Tornado mistook pending asyncio task counts for saturated request backlogs, triggering 160 false unready events that pulled pods out of service endpoints. Granian completely eliminates false unready flaps while doubling throughput.

📊 Reproduce & Explore: The complete benchmark suite, load scenarios, and raw result datasets are available at django-hurricane/django-hurricane-bench on GitHub.

✨ Highlights & Features

🔌 Zero-Config WSGI & ASGI Auto-Detection

Whether you are running a classic synchronous Django app or a bleeding-edge async setup with Channels or streaming views, Hurricane just works:

• Got WSGI_APPLICATION in your settings? Hurricane boots with Granian's multithreaded WSGI runner.
• Configured ASGI_APPLICATION? Hurricane automatically switches to Granian's ASGI asynchronous engine.
• No manual --mode flags. No extra configuration files.

🛡️ First Line of Defense: Fast-404 Protection

Automated vulnerability scanners love hammering Django with .php, /.env, and /wp-admin/ dictionary attacks. Normally, each attack request forces Django to execute its entire middleware stack, run session DB queries, and compile 404 templates.

Hurricane's Fast-404 Engine intercepts malicious and non-existent routes at the gateway edge:

• Zero Django Overhead: Serves your project's pre-rendered 404 HTML in < 50 microseconds, sparing Python worker threads and DB connection pools.
• Anti-Django Signatures: Immediately blocks scanner probes (.php, /.env, /.git, wp-*, xmlrpc, etc.).
• CMS / Catch-All Aware: Automatically detects root catch-alls (e.g. Wagtail, django-cms) and switches to signature-only matching so legitimate dynamic pages are never blocked.
• Silent Drop: Drops attacks without log pollution, preventing disk and stdout exhaustion during scanning waves.
• Configurable: Enabled by default (auto); easily disabled via --no-fast-404 or HURRICANE_FAST_404 = False.

🛑 DoS & Flood Protection: Request Rate Limiting

Prevent your Django workloads from getting overwhelmed by floods and Denial-of-Service attacks. Hurricane features an in-memory token bucket rate limiter enabled by default:

• Default Baseline: 10 requests / second with a burst allowance of 30 requests per IP (protecting legitimate browser asset storms and multi-tab browsing).
• Forwarded IP Resolution: Safely resolves the true client IP from X-Forwarded-For (leftmost IP) or X-Real-IP, bypassing intermediate Kubernetes ingresses and reverse proxies.
• Silent Protection: Drops rate-limited requests (HTTP 429 Too Many Requests) in < 5 microseconds with zero log spam, preventing disk and stdout saturation during DDoS attacks.
• Configurable: Easily customize rate, burst, or disable via --no-rate-limit or HURRICANE_RATE_LIMIT = False.

☸️ Native Kubernetes Probes

Kubernetes requires three probes to reliably manage container lifecycles. Hurricane implements all three out of the box without polluting your Django urls.py:

• /startup: Checks preflight tasks (like DB migrations) before Kubernetes allows traffic.
• /alive: Liveness probe ensuring the server process and worker threads aren't deadlocked.
• /ready: Verifies database connectivity and real request backlog capacity before routing traffic.

🛡️ Port Isolation with --probe-port

Running health checks on the same port as application traffic is a recipe for probe timeouts during traffic spikes. Hurricane allows isolating cluster probes on a separate port:

python manage.py serve --port 8000 --probe-port 8001

All probe requests run isolated on port 8001, synchronized with worker metrics via process-safe Shared Memory. Kubelet never times out waiting behind bulky user file downloads.

📊 Prometheus Metrics Built-In

Scrape /metrics out of the box! Hurricane exposes:

• Request counts, error rates, and average response times.
• Real-time worker thread saturation and backlog queue lengths.
• Standard Python runtime and GC allocation metrics.

📦 Static & Media File Serving

Don't want to run an Nginx sidecar just to serve media uploads and CSS?

python manage.py serve --static --media

Hurricane serves your collected statics and media assets directly with streaming responses.

🚀 Pre-Flight Migrations

Never serve traffic against an un-migrated database schema again:

python manage.py serve --check-migrations-apply

Hurricane runs pending migrations during startup while holding the /startup probe in a waiting state. Traffic is only allowed once the database schema is complete.

🚀 Quickstart

1. Installation

Install via uv (recommended) or pip:

# Using astral uv:
uv add django-hurricane

# Or using pip:
pip install django-hurricane

2. Configure Django

Add "hurricane" to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    # ...
    "hurricane",
]

3. Start the Server

python manage.py serve

Watch Hurricane spin up with Granian:

2026-10-20 12:00:00,102 INFO     hurricane.server.general Granian-powered Django web server. Version: 2.0.0rc2
2026-10-20 12:00:00,103 INFO     hurricane.server.general Starting probe application running on port 8001 with route liveness-probe: /alive, readiness-probe: /ready, startup-probe: /startup
2026-10-20 12:00:00,103 INFO     hurricane.server.general Starting Prometheus metrics exporter on port 8001 with route /metrics
2026-10-20 12:00:00,215 INFO     hurricane.server.general Starting HTTP Server on port 8000
2026-10-20 12:00:00,216 INFO     hurricane.server.general Startup time is 0.113 seconds

☸️ Kubernetes Pod Example

apiVersion: v1
kind: Pod
metadata:
  name: my-django-app
spec:
  containers:
  - name: web
    image: my-django-image:latest
    command: ["python", "manage.py", "serve", "--port=8000", "--probe-port=8001", "--check-migrations-apply"]
    ports:
    - containerPort: 8000
      name: http
    - containerPort: 8001
      name: probes
    startupProbe:
      httpGet:
        path: /startup
        port: 8001
      failureThreshold: 30
      periodSeconds: 2
    livenessProbe:
      httpGet:
        path: /alive
        port: 8001
      periodSeconds: 5
    readinessProbe:
      httpGet:
        path: /ready
        port: 8001
      periodSeconds: 2

🛠️ Development & Testing

This project uses modern Python development tooling powered by uv and ruff.

# Install dependencies
uv sync --all-groups --all-extras

# Run linting & formatting checks
uv run poe lint

# Run Django unit tests
uv run coverage run manage.py test

# Run Kubernetes End-to-End tests on k3d
uv run poe test-k8s

# Run performance benchmark suite
uv run poe benchmark

🏢 Commercial Support & Community

Hurricane is developed and maintained with ❤️ by Blueshoe.

• 💬 Discord: Join the discussion on our Blueshoe Discord Server
• 💼 LinkedIn: Connect with Blueshoe on LinkedIn
• ✉️ Contact: Need help optimizing your cloud-native Django deployment or Kubernetes architecture? Reach out to us at hurricane@blueshoe.de.