djproxy 2.3.2

Why?

If an application depends on a proxy (to get around Same Origin Policy issues in JavaScript, perhaps), djproxy can be used to provide that functionality in a web server agnostic way. This allows developers to keep local development environments for proxy dependent applications fully functional without needing to run anything other than the django development server.

djproxy is also suitable for use in production environments and has been proven to be performant in large scale deployments. However, a web server’s proxy capabilities will be more performant in many cases. If one needs to use this in production, it should be fine as long as upstream responses aren’t large. Performance can be further increased by aggressively caching upstream responses.

Note that djproxy doesn’t currently support websockets because django doesn’t support them. I will investigate adding websocket support as soon as django has it.

Installation

pip install djproxy

djproxy requires requests >= 1.0.0, django >= 1.4.0 and python >= 2.6.

It’s currently tested against Django 1.4.x, 1.5.x, 1.6.x, 1.7.x, 1.9.x, and 1.10.x.

Usage

Start by defining a new proxy:

from djproxy.views import HttpProxy

class LocalProxy(HttpProxy):
    base_url = 'https://google.com/'

Add a url pattern that points at the proxy view. The url kwarg will be urljoined with base_url:

urlpatterns = [
    url(r'^local_proxy/(?P<url>.*)$', LocalProxy.as_view(), name='proxy')
]

/local_proxy/some/content will now proxy https://google.com/some/content/.

Additional examples can be found here: views, urls.

Adjusting location headers (ProxyPassReverse)

Apache has a directive called ProxyPassReverse that makes replacements to three location headers: URI, Location, and Content-Location. Without this functionality, proxying an endpoint that returns a redirect with a Location header of http://foo.bar/go/cats/ would cause a downstream requestor to be redirected away from the proxy. djproxy has a similar mechanism which is exposed via the reverse_urls class variable. The following proxies are equivalent:

Djproxy:

class ReverseProxy(HttpProxy):
    base_url = 'https://google.com/'
    reverse_urls = [
        ('/google/', 'https://google.com/')
    ]

urlpatterns = patterns[
    url(r'^google/(?P<url>.*)$', ReverseProxy.as_view(), name='gproxy')
]

Apache:

<Proxy https://google.com/*>
    Order deny,allow
    Allow from all
</Proxy>
ProxyPass /google/ https://google.com/
ProxyPassReverse /google/ https://google.com/

from djproxy.urls import generate_routes

configuration = {
    'test_proxy': {
        'base_url': 'https://google.com/',
        'prefix': '/test_prefix/',
    },
    'service_name': {
        'base_url': 'https://service.com/',
        'prefix': '/service_prefix/',
        'verify_ssl': False,
        'append_middlware': ['myapp.proxy_middleware.add_headers']
    }
}

urlpatterns += generate_routes(configuration)

<Proxy https://google.com/*>
    Order deny,allow
    Allow from all
</Proxy>
ProxyPass /test_prefix/ https://google.com/
ProxyPassReverse /test_prefix/ https://google.com/


<Proxy https://service.com/*>
    Order deny,allow
    Allow from all
</Proxy>
ProxyPass /service_prefix/ http://service.com/
ProxyPassReverse /service_prefix/ http://service.com/

Proxy middleware

HttpProxys support custom middleware for preprocessing data from downstream to be sent to upstream endpoints and for preprocessing response data before it is sent back downstream. X-Forwarded-Host, X-Forwarded-For, X-Forwarded-Proto and the ProxyPassRevere functionality area all implemented as middleware.

HttProxy views are configured to execute particular middleware by setting their proxy_middleware attribute. The following HttpProxy would attach XFF and XFH headers, but not preform the ProxyPassReverse header translation or attach an XFP header:

class ReverseProxy(HttpProxy):
    base_url = 'https://google.com/'
    reverse_urls = [
        ('/google/', 'https://google.com/')
    ]
    proxy_middleware = [
        'djproxy.proxy_middleware.AddXFF',
        'djproxy.proxy_middleware.AddXFH'
    ]

If a custom middleware is needed to modify content, headers, cookies, etc before the content is sent upstream of if one needs to make similar modifications before the content is sent back downstream, a custom middleware can be written and proxy views can be configured to use it. djproxy contains a middleware template to make this process easier.

Terminology

It is important to understand the meaning of these terms in the context of this project:

upstream: The destination that is being proxied.

downstream: The agent that initiated the request to djproxy.

Contributing

To run the tests, first install development dependencies:

pip install -r requirements.txt

To test this against a version of Django other than the latest supported on the test environment’s Python version, wipe out the requirements.txt installation by pip installing the desired version.

Run nosetests to execute the test suite.

To automatically run the test suite, flake8, and pep257 checks whenever python files change use testtube by executing stir in the top level djproxy directory.

To run a Django dev server that proxies itself, execute the following:

django-admin.py runserver --settings=tests.test_settings --pythonpath="./"

Similarly, to run a configure Django shell, execute the following:

django-admin.py shell --settings=tests.test_settings --pythonpath="./"

See tests/test_settings.py and tests/test_urls.py for configuration information.