Launchpad Entry: wsgi-mapper
Created:
Contributors:
Summary
paste.urlmap is used for compositing some of the api server structure now. It has limitations on route matching (see launchpad bug lp:705314) that should be addressed. Also, the openstack api is still using a router internally because urlmap doesn't take into account http verbs for member actions.
Release Note
Use a new mapping mechanism to replace paste.urlmap to have more control in specifying how the api server runs.
Rationale
More control by people deploying is a good thing. As we get closer to allowing API extensions, we will need to have a mechanism in place for letting service provider build custom API stacks. paste.deploy is a good start, and having a good mapper can take us a lot farther.
User stories
If I want to run a middleware debugging only certain controllers API (/servers, for example), currently I don't have that capability. With a new mapper, it will be possible. If I want to replace a standard controller (for example, backup_schedules) with one of my own design, this will pave the way for that capability.
Assumptions
Bowties are cool.
Design
This will add a new class nova.wsgi.AppMapper that will be called in the 'use' directive of the paste configuration for the API server. Configuration for paste.deploy will be nearly identical, with two exceptions.
Firstly, the url definition should be compilable to a regular expression. This will allow better partial matching for routes. Hostnames are already matched by regular expression. Lastly, we need to specify proper verbs that should be accepted for members of certain controllers. While this could be done in the controller itself, it is currently configured by the ApiMapper, so I'm choosing to keep the logic in the routing mechanism instead of punting that information back to the controller. This also needs to take into account the parent_controller attribute of the mapper currently in use.
After implementing these changes we can revert the patch for ec2 metadata urls (referenced by bug above), as well as move more controller configuration to paste config files.
Implementation
Steal paste.urlmap. Change how route matching works to allow partial route matches that are more flexible and regular expressions for routes. Add verb checking for member actions with new configuration directives. Remove nova.api.openstack.APIRouter and configure it via the new AppMapper. Refactor nova.wsgi.Controller to do work for routing default actions (index, show, etc) that used to be handled by checking state from the routes python package, which we will have no more need of.
UI Changes
Instead of mappging like:
- /2007-10-10: ec2metadata
we can go to the shorter way of using:
- /20*: ec2metadata
When removing the openstack urlmapper we will have a configuration like:
- /servers: osapiservers /server/(\d+)? as servers_controller: osapiservers /server/(\d+)/backup_schedules: osapibackups /server/(\d+)/backkup_schedule/(\d+)?: servers_controller: post:pause,unpause get:diagnostics,actions
Code Changes
Described above.
Migration
The paste config file changes will be bundled with the source. Configuration will maintain backwards compatibility, but the section in any deployed apps that references the openstack api router will have to be updated. In most cases people will not have made changes to the defaults, so we can just copy in the new file.
Test/Demo Plan
Add unit tests to check that AppRouter:
- handles explicit path matches correctly
- handles regular expression path matches correctly
- handles the "as NAME" configuration directive
- handles any NAME: extra_params configuration correctly
- doesn't think NAME directives are explicit paths
- routes requests to the proper controllers
ensures the proper method is used for non-standard (index, show, &c) methods causes them to pass to the controller
- ensures when incorrect verb is used an exception/fault is raised
- modifies PATH_INFO and SCRIPT_NAME variables when appropriate (see paste.urlmap)
Add unit tests for Controller:
- handle standard actions appropriately
- handle nonstandard actions appropriately
Unresolved issues
I don't know if I'll just be pushing the action and verb info down into the controller and handling it in the base Controller class, or actually handling it in the AppRouter
BoF agenda and discussion
TODO: Use this section to take notes during the BoF; if you keep it in the approved spec, use it for summarising what was discussed and note any options that were rejected.