paste.deploy.config -- Configuration and Environment middleware

Paste Configuration Middleware and Objects

Module Contents

class paste.deploy.config.DispatchingConfig

This is a configuration object that can be used globally, imported, have references held onto. The configuration may differ by thread (or may not).

Specific configurations are registered (and deregistered) either for the process or for threads.

class paste.deploy.config.ConfigMiddleware(application, config)

A WSGI middleware that adds a paste.config key to the request environment, as well as registering the configuration temporarily (for the length of the request) with paste.CONFIG.

class paste.deploy.config.PrefixMiddleware(app, global_conf=None, prefix='/', translate_forwarded_server=True, force_port=None, scheme=None)

Translate a given prefix into a SCRIPT_NAME for the filtered application.

PrefixMiddleware provides a way to manually override the root prefix (SCRIPT_NAME) of your application for certain, rare situations.

When running an application under a prefix (such as '/james') in FastCGI/apache, the SCRIPT_NAME environment variable is automatically set to to the appropriate value: '/james'. Pylons' URL generating functions, such as url_for, always take the SCRIPT_NAME value into account.

One situation where PrefixMiddleware is required is when an application is accessed via a reverse proxy with a prefix. The application is accessed through the reverse proxy via the the URL prefix '/james', whereas the reverse proxy forwards those requests to the application at the prefix '/'.

The reverse proxy, being an entirely separate web server, has no way of specifying the SCRIPT_NAME variable; it must be manually set by a PrefixMiddleware instance. Without setting SCRIPT_NAME, url_for will generate URLs such as: '/purchase_orders/1', when it should be generating: '/james/purchase_orders/1'.

To filter your application through a PrefixMiddleware instance, add the following to the '[app:main]' section of your .ini file:

filter-with = proxy-prefix

[filter:proxy-prefix]
use = egg:PasteDeploy#prefix
prefix = /james

The name proxy-prefix simply acts as an identifier of the filter section; feel free to rename it.

Also, unless disabled, the X-Forwarded-Server header will be translated to the Host header, for cases when that header is lost in the proxying. Also X-Forwarded-Host, X-Forwarded-Scheme, and X-Forwarded-Proto are translated.

If force_port is set, SERVER_PORT and HTTP_HOST will be rewritten with the given port. You can use a number, string (like '80') or the empty string (whatever is the default port for the scheme). This is useful in situations where there is port forwarding going on, and the server believes itself to be on a different port than what the outside world sees.

You can also use scheme to explicitly set the scheme (like scheme = https).