A small set of functions to manage OpenStack microversion headers that can be used in middleware, application handlers and decorators to effectively manage microversions.
Also included, in the
middleware module, is a
that will process incoming microversion headers.
A simple parser for OpenStack microversion headers:
import microversion_parse # headers is a dict of headers with folded (comma-separated # values) or a list of header, value tuples version = microversion_parse.get_version( headers, service_type='compute', legacy_headers=['x-openstack-nova-api-version']) # If headers are not already available, a dict of headers # can be extracted from the WSGI environ headers = microversion_parse.headers_from_wsgi_environ(environ) version = microversion_parse.get_version( headers, service_type='placement')
It processes microversion headers with the standard form:
OpenStack-API-Version: compute 2.1
In that case, the response will be '2.1'.
If provided with a
legacy_headers argument, this is treated as
a list of additional headers to check for microversions. Some examples of
OpenStack-telemetry-api-version: 2.1 OpenStack-nova-api-version: 2.1 X-OpenStack-nova-api-version: 2.1
If a version string cannot be found,
None will be returned. If
the input is incorrect usual Python exceptions (ValueError,
TypeError) are allowed to raise to the caller.
A function to turn a version string into a
Version, a comparable
version_tuple = microversion_parse.parse_version_string('2.1')
If the provided string is not a valid microversion string,
parse_version_string to find and validate
a microversion for a given service type in a collection of headers:
version_tuple = microversion_parse.extract_version( headers, # a representation of headers, as accepted by get_version service_type, # service type identify to match in headers versions_list, # an ordered list of strings of version numbers that # are the valid versions presented by this service )
latest will be translated to whatever the max version is in versions_list.
If the found version is not in versions_list a
ValueError is raised.
extract_version does not support
A WSGI middleware that can wrap an application that needs to be microversion aware. The application will get a WSGI environ with a 'SERVICE_TYPE.microversion' key that has a value of the microversion found at an 'openstack-api-version' header that matches SERVICE_TYPE. If no header is found, the minimum microversion will be set. If the special keyword 'latest' is used, the maximum microversion will be set.
If the requested microversion is not available a 406 response is returned.
If there is an error parsing a provided header, a 400 response is returned.
Otherwise the application is called.
The middleware is configured when it is created. Three parameters are required:
- The next WSGI middleware or application in the stack.
- The service type of the application, used to identify microversion headers.
- An ordered list of legitimate microversions (as strings) for the application. It's assumed that any application that is using microversions will have such a list for its own housekeeping and documentation.
One named parameter is optional:
- A Webob error formatter that can be used to structure the response when JSON is expected.
def app(): app = middleware.MicroversionMiddleware( MyWSGIApp(), 'cats', ['1.0', '1.1', '1.2']) return app