django-hostroute 0.1.1

django-hostroute is a high-performance host-header routing middleware for Django.

django-hostroute treats host-routing as a single, isolated Mechanism:

1. Zero-Dependency: Pure Python and Django standard library. No database migrations, extra system dependencies, or thread-blocking logic.
2. Instant Routing: Swaps Django urlconf routing paths via dictionary lookups.
3. Strict Isolation: Separates routing (the middleware engine) from routing (the dictionary mappings configured in settings.py).

Installation

pip install django-hostroute

Quick Start

1. Register the Middleware

Register django_hostroute.HostRouteMiddleware at the very top of your MIDDLEWARE list in settings.py. This ensures routing is resolved before security, session, or CSRF layers execute.

# settings.py

MIDDLEWARE = [
    # Must execute before Security and WhiteNoise
    'django_hostroute.HostRouteMiddleware',
    
    'django.middleware.security.SecurityMiddleware',
    # ...
]

2. Configure the Routing Policy

Define your domain-to-URLconf mappings in settings.py.

# settings.py

# 1. Authorize your hosts
ALLOWED_HOSTS = [
    'example.com',
    'api.example.com',
    'docs.example.com',
]

# 2. Add Routing
HOSTROUTE_MAP = {
    'example.com': 'myproject.core.urls',
    'api.example.com': 'myproject.api.urls',
    'docs.example.com': 'myproject.docs.urls',
}

# 3. Define the fallback URLconf for unmapped hosts (Optional)
HOSTROUTE_DEFAULT = 'myproject.core.urls'

# 4. Define short-circuit status code used (Optional)
HOSTROUTE_DISALLOWED_STATUS = 403

Local Development & Testing

When testing locally, Nginx and Django read the HTTP Host header. You can test your local subdomain matrix easily using one of two methods:

Option A: The .localhost Standard (Zero-Config)

Modern browsers natively resolve any domain ending in .localhost to your local machine (127.0.0.1). Simply add these hosts to your ALLOWED_HOSTS and HOSTROUTE_MAP in your local settings:

HOSTROUTE_MAP = {
    'api.localhost': 'myproject.api.urls',
    'docs.localhost': 'myproject.docs.urls',
}

Run python manage.py runserver and navigate to http://api.localhost:8000 in your browser. The middleware automatically strips the port and routes the request.

Option B: Raw Header Injection (CI/CD / Curl)

When testing inside headless containers or CI/CD pipelines, bypass DNS altogether by connecting to 127.0.0.1 but explicitly spoofing the Host header:

curl -H "Host: api.local" [http://127.0.0.1:8000/](http://127.0.0.1:8000/)

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

https://github.com/mesotron-dev/django-hostroute.git