{"id":7482,"library":"oslo-middleware","title":"Oslo Middleware Library","description":"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.","status":"active","version":"8.0.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/oslo.middleware","tags":["OpenStack","WSGI","middleware","web development","HTTP","CORS","error handling"],"install":[{"cmd":"pip install oslo-middleware","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for WSGI request/response objects and decorators.","package":"WebOb","optional":false},{"reason":"Used for configuration management within OpenStack projects.","package":"oslo.config","optional":true},{"reason":"Provides context management, often used for request IDs and user context.","package":"oslo.context","optional":true},{"reason":"For internationalization support.","package":"oslo.i18n","optional":true},{"reason":"Collection of utility functions used across Oslo projects.","package":"oslo.utils","optional":true}],"imports":[{"note":"Top-level `oslo_middleware` package uses underscores, not dots, for direct imports.","wrong":"from oslo.middleware import cors","symbol":"CORS","correct":"from oslo_middleware import cors"},{"note":"Middleware components are typically imported from their respective snake_case modules within `oslo_middleware`.","wrong":"from oslo.middleware import catch_errors","symbol":"CatchErrors","correct":"from oslo_middleware import catch_errors"},{"note":"Older OpenStack projects might have used `openstack.common.middleware`. All new code should use `oslo_middleware`.","wrong":"from openstack.common.middleware import request_id","symbol":"RequestId","correct":"from oslo_middleware import request_id"}],"quickstart":{"code":"import webob.dec\nimport webob.exc\nfrom oslo_middleware import catch_errors\nfrom oslo_middleware import request_id\n\n@webob.dec.wsgify\ndef simple_app(req):\n    if req.path_info == '/hello':\n        return f\"Hello, Request ID: {req.environ.get('openstack.request_id', 'N/A')}\"\n    elif req.path_info == '/error':\n        raise ValueError('Something went wrong!')\n    return webob.exc.HTTPNotFound()\n\n# Order matters: RequestId first to ensure ID is generated,\n# then CatchErrors to handle subsequent exceptions.\napp = request_id.RequestId(simple_app)\napp = catch_errors.CatchErrors(app)\n\n# To run this with a WSGI server (e.g., Gunicorn or uWSGI):\n# Save as app.py and run 'gunicorn app:app'\n# Test with curl:\n# curl http://127.0.0.1:8000/hello\n# curl http://127.0.0.1:8000/error\n","lang":"python","description":"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."},"warnings":[{"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`).","message":"Import paths for middleware components were standardized under the `oslo_middleware` namespace. Older projects might still reference `openstack.common.middleware`.","severity":"breaking","affected_versions":"< 1.0.0 (pre-Oslo graduation)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"< 3.23.1, < 4.4.1 (specific to Red Hat OpenStack Platform Newton, but general warning applies)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement to `from oslo_middleware import ...`.","cause":"The package name is `oslo-middleware` (with a hyphen) for installation, but the Python import path uses an underscore: `oslo_middleware`.","error":"ModuleNotFoundError: No module named 'oslo.middleware'"},{"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.","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.","error":"TypeError: 'module' object is not callable (when trying to use `oslo_middleware.CORS` directly)"},{"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.","cause":"Attempting to access a request environment variable (like `openstack.request_id`) that has not been set by its corresponding middleware.","error":"KeyError: 'openstack.request_id' (or similar env var not found)"}]}