Difference between revisions of "Spec-wsgi-mapper"

Latest revision as of 23:31, 17 February 2013

• Launchpad Entry: NovaSpec: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.