Simple library for parsing OpenStack microversion headers.
Go to file
Chris Dent 6a379d9783 Correct docstring on Version(0, 0) test
If no max or min is set, no Version should match, including
0.0. The test was already correct, but the associated
docstring was a pasto.

Change-Id: I925a9df3b044b1f581b2c62db1bda9ace0a5cc47
2018-03-21 15:18:23 +00:00
doc/source Include README.rst content on doc index 2016-03-31 18:07:23 +01:00
microversion_parse Correct docstring on Version(0, 0) test 2018-03-21 15:18:23 +00:00
.gitignore Add MicroversionMiddleware 2018-03-20 17:24:56 +00:00
.gitreview Enable gerrit, gitreview and gate testing 2016-03-31 12:31:20 +01:00
.stestr.conf Add MicroversionMiddleware 2018-03-20 17:24:56 +00:00
LICENSE Initial commit 2016-03-22 15:29:38 +00:00
Makefile allow tox to skip missing interpreters 2016-03-24 13:28:08 +00:00
README.rst Allow passing a json_error_formatter to the middleware 2018-03-20 17:24:56 +00:00
requirements.txt Add MicroversionMiddleware 2018-03-20 17:24:56 +00:00
setup.cfg Clean up package version and python version support 2018-03-20 17:24:56 +00:00
setup.py Initial proof of concept of microversion_parse 2016-03-22 17:48:42 +00:00
test-requirements.txt Add MicroversionMiddleware 2018-03-20 17:24:56 +00:00
tox.ini Add MicroversionMiddleware 2018-03-20 17:24:56 +00:00

README.rst

microversion_parse

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.

get_version

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.

parse_version_string

A function to turn a version string into a Version, a comparable namedtuple:

version_tuple = microversion_parse.parse_version_string('2.1')

If the provided string is not a valid microversion string, TypeError is raised.

extract_version

Combines get_version and 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.

Note that extract_version does not support legacy_headers.

MicroversionMiddleware

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:

app

The next WSGI middleware or application in the stack.

service_type

The service type of the application, used to identify microversion headers.

versions_list

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:

json_error_formatter

A Webob error formatter that can be used to structure the response when JSON is expected.

For example:

def app():
    app = middleware.MicroversionMiddleware(
        MyWSGIApp(), 'cats', ['1.0', '1.1', '1.2'])
    return app