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
MicroversionMiddleware 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 headers include:
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,
TypeError is raised.
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