Oslo Middleware Library

8.0.0 · active · verified Thu Apr 16

Oslo.middleware is an OpenStack library that provides a collection of WSGI middleware components for web service development. It allows developers to inject functionality into WSGI pipelines to intercept and modify request/response flows, offering features like HTTP header manipulation, request body size limiting, CORS support, and error handling. It is an actively maintained project within the OpenStack ecosystem, with regular releases aligning with OpenStack development cycles.

Common errors

```
ModuleNotFoundError: No module named 'oslo.middleware'
```
cause The package name is `oslo-middleware` (with a hyphen) for installation, but the Python import path uses an underscore: `oslo_middleware`.

fix Change your import statement to `from oslo_middleware import ...`.
```
TypeError: 'module' object is not callable (when trying to use `oslo_middleware.CORS` directly)
```
cause Many `oslo_middleware` components are classes that need to be instantiated, or they provide a factory function (e.g., `CORS.factory()`) for `paste.deploy` integration, not directly callable as a module.

fix Instantiate the middleware class: `app = cors.CORS(your_app, ...)` or use its `factory` method if integrating with `paste.deploy`. Refer to specific middleware documentation for correct usage.
```
KeyError: 'openstack.request_id' (or similar env var not found)
```
cause Attempting to access a request environment variable (like `openstack.request_id`) that has not been set by its corresponding middleware.

fix Ensure the relevant middleware (e.g., `RequestId` for `openstack.request_id`) is properly included and ordered in your WSGI pipeline before your application attempts to access its values.

Warnings

breaking Import paths for middleware components were standardized under the `oslo_middleware` namespace. Older projects might still reference `openstack.common.middleware`.
Fix: Update import statements from `from openstack.common.middleware import X` to `from oslo_middleware import X` (or specific module, e.g., `from oslo_middleware import request_id`).
gotcha Incorrect middleware order can lead to unexpected behavior. For instance, `CatchErrors` should typically wrap your application and other middleware that might raise exceptions, while `RequestId` often comes early in the pipeline.
Fix: Carefully consider the order of middleware in your WSGI pipeline. Middleware applied earlier will process requests first and responses last. For example, `RequestId` usually precedes error handling or authentication middleware.
deprecated The `CatchErrors` middleware, in older versions, had an information-disclosure flaw (CVE-2017-2592) where sensitive values could be included in traceback error messages, potentially exposing tokens or other data.
Fix: Ensure you are using a patched version of `oslo.middleware` (newer than the affected versions). Review and sanitize error messages and logs if you are using custom error handling or older versions.

Install

pip install oslo-middleware Install stable version

Imports

CORS
wrong:
```
from oslo.middleware import cors
```
correct:
```
from oslo_middleware import cors
```
Top-level `oslo_middleware` package uses underscores, not dots, for direct imports.
CatchErrors
wrong:
```
from oslo.middleware import catch_errors
```
correct:
```
from oslo_middleware import catch_errors
```
Middleware components are typically imported from their respective snake_case modules within `oslo_middleware`.
RequestId
wrong:
```
from openstack.common.middleware import request_id
```
correct:
```
from oslo_middleware import request_id
```
Older OpenStack projects might have used `openstack.common.middleware`. All new code should use `oslo_middleware`.

Quickstart

This example demonstrates how to chain two `oslo_middleware` components, `RequestId` and `CatchErrors`, with a basic WSGI application. `RequestId` ensures a unique ID for each request, and `CatchErrors` provides high-level error handling, preventing raw tracebacks from being exposed to clients. This setup is typical in OpenStack services.

import webob.dec
import webob.exc
from oslo_middleware import catch_errors
from oslo_middleware import request_id

@webob.dec.wsgify
def simple_app(req):
    if req.path_info == '/hello':
        return f"Hello, Request ID: {req.environ.get('openstack.request_id', 'N/A')}"
    elif req.path_info == '/error':
        raise ValueError('Something went wrong!')
    return webob.exc.HTTPNotFound()

# Order matters: RequestId first to ensure ID is generated,
# then CatchErrors to handle subsequent exceptions.
app = request_id.RequestId(simple_app)
app = catch_errors.CatchErrors(app)

# To run this with a WSGI server (e.g., Gunicorn or uWSGI):
# Save as app.py and run 'gunicorn app:app'
# Test with curl:
# curl http://127.0.0.1:8000/hello
# curl http://127.0.0.1:8000/error

view raw JSON →