API

class oslo_middleware.CatchErrors(application, conf=None)

Middleware that provides high-level error handling.

It catches all exceptions from subsequent applications in WSGI pipeline to hide internal errors from API response.

class oslo_middleware.CorrelationId(application, conf=None)

Middleware that attaches a correlation id to WSGI request

class oslo_middleware.CORS(application, *args, **kwargs)

CORS Middleware.

This middleware allows a WSGI app to serve CORS headers for multiple configured domains.

For more information, see http://www.w3.org/TR/cors/

add_origin(allowed_origin, allow_credentials=True, expose_headers=None, max_age=None, allow_methods=None, allow_headers=None)

Add another origin to this filter.

Parameters:
  • allowed_origin – Protocol, host, and port for the allowed origin.
  • allow_credentials – Whether to permit credentials.
  • expose_headers – A list of headers to expose.
  • max_age – Maximum cache duration.
  • allow_methods – List of HTTP methods to permit.
  • allow_headers – List of HTTP headers to permit from the client.
Returns:

classmethod factory(global_conf, **local_conf)

factory method for paste.deploy

allowed_origin: Protocol, host, and port for the allowed origin. allow_credentials: Whether to permit credentials. expose_headers: A list of headers to expose. max_age: Maximum cache duration. allow_methods: List of HTTP methods to permit. allow_headers: List of HTTP headers to permit from the client.

process_response(response, request=None)

Check for CORS headers, and decorate if necessary.

Perform two checks. First, if an OPTIONS request was issued, let the application handle it, and (if necessary) decorate the response with preflight headers. In this case, if a 404 is thrown by the underlying application (i.e. if the underlying application does not handle OPTIONS requests, the response code is overridden.

In the case of all other requests, regular request headers are applied.

set_latent(allow_headers=None, allow_methods=None, expose_headers=None)

Add a new latent property for this middleware.

Latent properties are those values which a system requires for operation. API-specific headers, for example, may be added by an engineer so that they ship with the codebase, and thus do not require extra documentation or passing of institutional knowledge.

Parameters:
  • allow_headers – HTTP headers permitted in client requests.
  • allow_methods – HTTP methods permitted in client requests.
  • expose_headers – HTTP Headers exposed to clients.
class oslo_middleware.Debug(application, conf=None)

Helper class that returns debug information.

Can be inserted into any WSGI application chain to get information about the request and response.

static print_generator(app_iter)

Prints the contents of a wrapper string iterator when iterated.

class oslo_middleware.Healthcheck(application, conf)

Healthcheck middleware used for monitoring.

If the path is /healthcheck, it will respond 200 with “OK” as the body. Or 503 with the reason as the body if one of the backend report an application issue.

This is useful for the following reasons:

  1. Load balancers can ‘ping’ this url to determine service availability.
  2. Provides an endpoint that is similar to ‘mod_status’ in apache which can provide details (or no details, depending on if configured) about the activity of the server.

Example requests/responses:

$ curl -i -X HEAD “http://0.0.0.0:8775/healthcheck” HTTP/1.1 204 No Content Content-Type: text/plain; charset=UTF-8 Content-Length: 0 Date: Fri, 11 Sep 2015 18:55:08 GMT

$ curl -i “http://0.0.0.0:8775/healthcheck” HTTP/1.1 200 OK Content-Type: text/plain; charset=UTF-8 Content-Length: 2 Date: Fri, 11 Sep 2015 18:55:43 GMT

OK

Example of paste configuration:

[filter:healthcheck]
paste.filter_factory = oslo_middleware:Healthcheck.factory
path = /healthcheck
backends = disable_by_file
disable_by_file_path = /var/run/nova/healthcheck_disable

[pipeline:public_api]
pipeline = healthcheck sizelimit [...] public_service

Multiple filter sections can be defined if it desired to have pipelines with different healthcheck configuration, example:

[pipeline:public_api]
pipeline = healthcheck_public sizelimit [...] public_service

[pipeline:admin_api]
pipeline = healthcheck_admin sizelimit [...] admin_service

[filter:healthcheck_public]
paste.filter_factory = oslo_middleware:Healthcheck.factory
path = /healthcheck_public
backends = disable_by_file
disable_by_file_path = /var/run/nova/healthcheck_public_disable

[filter:healthcheck_admin]
paste.filter_factory = oslo_middleware:Healthcheck.factory
path = /healthcheck_admin
backends = disable_by_file
disable_by_file_path = /var/run/nova/healthcheck_admin_disable

More details on available backends and their configuration can be found on this page: Healthcheck middleware plugins.

class oslo_middleware.HTTPProxyToWSGI(application, *args, **kwargs)

HTTP proxy to WSGI termination middleware.

This middleware overloads WSGI environment variables with the one provided by the remote HTTP reverse proxy.

class oslo_middleware.RequestId(application, conf=None)

Middleware that ensures request ID.

It ensures to assign request ID for each API request and set it to request environment. The request ID is also added to API response.

class oslo_middleware.RequestBodySizeLimiter(application, conf=None)

Limit the size of incoming requests.

class oslo_middleware.SSLMiddleware(application, *args, **kwargs)

SSL termination proxies middleware.

This middleware overloads wsgi.url_scheme with the one provided in secure_proxy_ssl_header header. This is useful when behind a SSL termination proxy.

Configuration Options

RequestBodySizeLimiter

oslo_middleware

max_request_body_size
Type:integer
Default:114688

The maximum body size for each request, in bytes.

Deprecated Variations
Group Name
DEFAULT osapi_max_request_body_size
DEFAULT max_request_body_size

SSLMiddleware

oslo_middleware

secure_proxy_ssl_header
Type:string
Default:X-Forwarded-Proto

The HTTP Header that will be used to determine what the original request protocol scheme was, even if it was hidden by a SSL termination proxy.

Warning

This option is deprecated for removal. Its value may be silently ignored in the future.