Merge lp:~leonardr/lazr.restful/version-specific-request-interface into lp:lazr.restful

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch changes the way an incoming web service request is associated with a specific version of the web service. Previously, the version number was stuffed into a Zope annotation on the request object. Versioned lookups were done as named lookups using the version number as the name.

Now, the web service is expected to define a marker interface for every version it publishes, eg. IWebServiceRequestBeta. Once the traversal code knows which version of the web service the client is requesting, it calls alsoProvides on the request object to mark it with the appropriate marker interface.

The idea here is to get rid of named lookups. Instead of this:

getAdapter(data_model_object, IEntry, name="1.0")

We can now do this:

getMultiAdapter([data_model_object, request], IEntry)

Unfortunately, the benefits of this are mostly in the future. The two named lookups we do right now cannot be turned into multiadapter lookups. The first is the lookup that gets us the version-specific request interface in the first place. The second is a utility lookup:

root = getUtility(IWebServiceRootResource, name="1.0")

There's no such thing as a multi-value utility lookup. However, I'm considering writing a wrapper class that lets the utility lookup look like a simple adaptation:

root = IWebServiceRootResource(request)

But I'm not sure if that's valuable to the programmer.

To avoid a million test failures, I preserved the behavior of the unversioned code (where the incoming request does not have any special interface applied to it). I'll almost certainly remove this code once I make the service generation code support multi-versioning, but that's a way in the future.

[Leonard Richardson (leonardr)]

Because this branch is complicated and I'm not yet certain it will pay off, I don't plan to land it immediately. Instead, I'll be merging other branches into it and landing the whole thing once I have something useful.

[Francis J. Lacoste (flacoste)]

Hi Leonard,

Nice to see this coming along.

This is good to go once you fix the conflit marker and handle my few other
comments.

Cheers

> === modified file 'src/lazr/restful/docs/multiversion.txt'
> --- src/lazr/restful/docs/multiversion.txt 2009-11-19 16:43:08 +0000
> +++ src/lazr/restful/docs/multiversion.txt 2010-01-06 17:40:25 +0000
> @@ -5,10 +5,99 @@
> services. Typically these different services represent successive
> versions of a single web service, improved over time.
>
> +Setup
> +=====
> +
> +First, let's set up the web service infrastructure. Doing this first
> +will let us create HTTP requests for different versions of the web
> +service. The first step is to make all component lookups use the
> +global site manager.
> +
> + >>> from zope.component import getSiteManager
> + >>> sm = getSiteManager()
> +
> + >>> from zope.component import adapter
> + >>> from zope.component.interfaces import IComponentLookup
> + >>> from zope.interface import implementer, Interface
> + >>> @implementer(IComponentLookup)
> + ... @adapter(Interface)
> + ... def everything_uses_the_global_site_manager(context):
> + ... return sm
> + >>> sm.registerAdapter(everything_uses_the_global_site_manager)

Like discussed on IRC, the waving of this dead chicken isn't needed :-)

> +
> +Defining the request interfaces
> +-------------------------------
> +
> +Every version must have a corresponding subclass of
> +IWebServiceClientRequest. These marker interfaces let lazr.restful
> +keep track of which version of the web service a particular client
> +wants to use. In a real application, these interfaces will be
> +generated and registered automatically.
> +
> + >>> from lazr.restful.interfaces import (
> + ... IVersionedClientRequestImplementation, IWebServiceClientRequest)
> + >>> class IWebServiceRequestBeta(IWebServiceClientRequest):
> + ... pass
> +
> + >>> class IWebServiceRequest10(IWebServiceClientRequest):
> + ... pass
> +
> + >>> class IWebServiceRequestDev(IWebServiceClientRequest):
> + ... pass
> +
> + >>> request_classes = [IWebServiceRequestBeta,
> + ... IWebServiceRequest10, IWebServiceRequestDev]
> +
> + >>> from zope.interface import alsoProvides
> + >>> for cls, version in ((IWebServiceRequestBeta, 'beta'),
> + ... (IWebServiceRequest10, '1.0'),
> + ... (IWebServiceRequestDev, 'dev')):
> + ... alsoProvides(cls, IVersionedClientRequestImplementation)
> + ... sm.registerUtility(cls, IVersionedClientRequestImplementation,
> + ... name=version)
> +

Can you explain the use of IVersionedClientRequestImplementation? You
explained on IRC that it to make it easy to retrieve the interface related to
a version string.

Would IVersionedWebClientRequestFactory be a better name?

> +<<<<<<< TREE
> >>> for version in ['beta', 'dev', '1.0']:
> ... sm.registerAdapter(
> ... ContactCollection, provided=ICollection, name=version)
> @@ -397,3 +495,105 @@
> >>> print absoluteURL(dev_app, dev_request)
> http://api.multiversion.dev/d...

review: Approve (code)

[lp:~leonardr/lazr.restful/version-specific-request-interface]

95. By Leonard Richardson on 2010-01-06

Merged from original branch to get rid of conflict markers.

[Leonard Richardson (leonardr)]

I removed the rubber chicken and changed the text in the section on named utilities to make it more clear. I did this in the second branch because this branch has a lot of test failures (which the job of the second branch is to fix). The second branch already included a doctest of request.version, in the "Request lifecycle" section of multiversion.txt.

Unmerged revisions

95. By Leonard Richardson on 2010-01-06

Merged from original branch to get rid of conflict markers.

=== modified file 'src/lazr/restful/docs/multiversion.txt'
--- src/lazr/restful/docs/multiversion.txt	2009-11-19 16:43:08 +0000
+++ src/lazr/restful/docs/multiversion.txt	2010-01-06 21:06:12 +0000
@@ -5,10 +5,96 @@
 services. Typically these different services represent successive
 versions of a single web service, improved over time.
 
+Setup
+=====
+
+First, let's set up the web service infrastructure. Doing this first
+will let us create HTTP requests for different versions of the web
+service. The first step is to make all component lookups use the
+global site manager.
+
+    >>> from zope.component import getSiteManager
+    >>> sm = getSiteManager()
+
+    >>> from zope.component import adapter
+    >>> from zope.component.interfaces import IComponentLookup
+    >>> from zope.interface import implementer, Interface
+    >>> @implementer(IComponentLookup)
+    ... @adapter(Interface)
+    ... def everything_uses_the_global_site_manager(context):
+    ...     return sm
+    >>> sm.registerAdapter(everything_uses_the_global_site_manager)
+
+Then, let's install the common ZCML used by all lazr.restful web services.
+
+    >>> from zope.configuration import xmlconfig
+    >>> zcmlcontext = xmlconfig.string("""
+    ... <configure xmlns="http://namespaces.zope.org/zope">
+    ...   <include package="lazr.restful" file="basic-site.zcml"/>
+    ...   <utility
+    ...       factory="lazr.restful.example.base.filemanager.FileManager" />
+    ... </configure>
+    ... """)
+
+Web service configuration object
+--------------------------------
+
+Here's the web service configuration, which defines the three
+versions: 'beta', '1.0', and 'dev'.
+
+    >>> from lazr.restful import directives
+    >>> from lazr.restful.interfaces import IWebServiceConfiguration
+    >>> from lazr.restful.simple import BaseWebServiceConfiguration
+    >>> from lazr.restful.testing.webservice import WebServiceTestPublication
+
+    >>> class WebServiceConfiguration(BaseWebServiceConfiguration):
+    ...     hostname = 'api.multiversion.dev'
+    ...     use_https = False
+    ...     active_versions = ['beta', '1.0']
+    ...     latest_version_uri_prefix = 'dev'
+    ...     code_revision = 'test'
+    ...     max_batch_size = 100
+    ...     directives.publication_class(WebServiceTestPublication)
+
+    >>> from grokcore.component.testing import grok_component
+    >>> ignore = grok_component(
+    ...     'WebServiceConfiguration', WebServiceConfiguration)
+
+    >>> from zope.component import getUtility
+    >>> config = getUtility(IWebServiceConfiguration)
+
+Defining the request interfaces
+-------------------------------
+
+Every version must have a corresponding subclass of
+IWebServiceClientRequest. These marker interfaces let lazr.restful
+keep track of which version of the web service a particular client
+wants to use. In a real application, these interfaces will be
+generated and registered automatically.
+
+    >>> from lazr.restful.interfaces import (
+    ...     IVersionedClientRequestImplementation, IWebServiceClientRequest)
+    >>> class IWebServiceRequestBeta(IWebServiceClientRequest):
+    ...     pass
+
+    >>> class IWebServiceRequest10(IWebServiceClientRequest):
+    ...     pass
+
+    >>> class IWebServiceRequestDev(IWebServiceClientRequest):
+    ...     pass
+
+    >>> from zope.interface import alsoProvides
+    >>> for cls, version in ((IWebServiceRequestBeta, 'beta'),
+    ...                      (IWebServiceRequest10, '1.0'),
+    ...                      (IWebServiceRequestDev, 'dev')):
+    ...     alsoProvides(cls, IVersionedClientRequestImplementation)
+    ...     sm.registerUtility(cls, IVersionedClientRequestImplementation,
+    ...                        name=version)
+
 Example model objects
 =====================
 
-First let's define the data model. The model in webservice.txt is
+Now let's define the data model. The model in webservice.txt is
 pretty complicated; this model will be just complicated enough to
 illustrate how to publish multiple versions of a web service.
 
@@ -38,21 +124,6 @@
     ...     def get(self, name):
     ...         "Retrieve a single contact by name."
 
-Before we can define any classes, a bit of web service setup. Let's
-make all component lookups use the global site manager.
-
-    >>> from zope.component import getSiteManager
-    >>> sm = getSiteManager()
-
-    >>> from zope.component import adapter
-    >>> from zope.component.interfaces import IComponentLookup
-    >>> from zope.interface import implementer, Interface
-    >>> @implementer(IComponentLookup)
-    ... @adapter(Interface)
-    ... def everything_uses_the_global_site_manager(context):
-    ...     return sm
-    >>> sm.registerAdapter(everything_uses_the_global_site_manager)
-
 Here's a simple implementation of IContact.
 
     >>> from urllib import quote
@@ -169,14 +240,18 @@
     ...     implements(IContactEntryBeta)
     ...     delegates(IContactEntryBeta)
     ...     schema = IContactEntryBeta
+    ...     def __init__(self, context, request):
+    ...         self.context = context
+
     >>> sm.registerAdapter(
-    ...     ContactEntryBeta, provided=IContactEntry, name="beta")
+    ...     ContactEntryBeta, [IContact, IWebServiceRequestBeta],
+    ...     provided=IContactEntry)
 
 By wrapping one of our predefined Contacts in a ContactEntryBeta
 object, we can verify that it implements IContactEntryBeta and
 IContactEntry.
 
-    >>> entry = ContactEntryBeta(C1)
+    >>> entry = ContactEntryBeta(C1, None)
     >>> IContactEntry.validateInvariants(entry)
     >>> IContactEntryBeta.validateInvariants(entry)
 
@@ -188,7 +263,7 @@
     ...    implements(IContactEntry10)
     ...    schema = IContactEntry10
     ...
-    ...    def __init__(self, contact):
+    ...    def __init__(self, contact, request):
     ...        self.contact = contact
     ...
     ...    @property
@@ -199,9 +274,10 @@
     ...    def fax_number(self):
     ...        return self.contact.fax
     >>> sm.registerAdapter(
-    ...     ContactEntry10, provided=IContactEntry, name="1.0")
+    ...     ContactEntry10, [IContact, IWebServiceRequest10],
+    ...     provided=IContactEntry)
 
-    >>> entry = ContactEntry10(C1)
+    >>> entry = ContactEntry10(C1, None)
     >>> IContactEntry.validateInvariants(entry)
     >>> IContactEntry10.validateInvariants(entry)
 
@@ -213,16 +289,17 @@
     ...    implements(IContactEntryDev)
     ...    schema = IContactEntryDev
     ...
-    ...    def __init__(self, contact):
+    ...    def __init__(self, contact, request):
     ...        self.contact = contact
     ...
     ...    @property
     ...    def phone_number(self):
     ...        return self.contact.phone
     >>> sm.registerAdapter(
-    ...     ContactEntryDev, provided=IContactEntry, name="dev")
+    ...     ContactEntryDev, [IContact, IWebServiceRequestDev],
+    ...     provided=IContactEntry)
 
-    >>> entry = ContactEntryDev(C1)
+    >>> entry = ContactEntryDev(C1, None)
     >>> IContactEntry.validateInvariants(entry)
     >>> IContactEntryDev.validateInvariants(entry)
 
@@ -239,19 +316,35 @@
     ...
     ComponentLookupError: ...
 
-When adapting Contact to IEntry you must specify a version number as
-the name of the adapter. The object you get back will implement the
-appropriate version of the web service.
-
-    >>> beta_entry = getAdapter(C1, IEntry, name="beta")
+When adapting Contact to IEntry you must provide a versioned request
+object. The IEntry object you get back will implement the appropriate
+version of the web service.
+
+To test this we'll need to manually create some versioned request
+objects. The traversal process would take care of this for us (see
+"Request lifecycle" below), but it won't work yet because we have yet
+to define a service root resource.
+
+    >>> from lazr.restful.testing.webservice import (
+    ...     create_web_service_request)
+    >>> from zope.interface import alsoProvides
+
+    >>> from zope.component import getMultiAdapter
+    >>> request_beta = create_web_service_request('/beta/')
+    >>> alsoProvides(request_beta, IWebServiceRequestBeta)
+    >>> beta_entry = getMultiAdapter((C1, request_beta), IEntry)
     >>> print beta_entry.fax
     111-2121
 
-    >>> one_oh_entry = getAdapter(C1, IEntry, name="1.0")
+    >>> request_10 = create_web_service_request('/1.0/')
+    >>> alsoProvides(request_10, IWebServiceRequest10)
+    >>> one_oh_entry = getMultiAdapter((C1, request_10), IEntry)
     >>> print one_oh_entry.fax_number
     111-2121
 
-    >>> dev_entry = getAdapter(C1, IEntry, name="dev")
+    >>> request_dev = create_web_service_request('/dev/')
+    >>> alsoProvides(request_dev, IWebServiceRequestDev)
+    >>> dev_entry = getMultiAdapter((C1, request_dev), IEntry)
     >>> print dev_entry.fax
     Traceback (most recent call last):
     ...
@@ -299,46 +392,6 @@
     >>> len(dev_collection.find())
     2
 
-Web service infrastructure initialization
-=========================================
-
-Now that we've defined the data model, it's time to set up the web
-service infrastructure.
-
-    >>> from zope.configuration import xmlconfig
-    >>> zcmlcontext = xmlconfig.string("""
-    ... <configure xmlns="http://namespaces.zope.org/zope">
-    ...   <include package="lazr.restful" file="basic-site.zcml"/>
-    ...   <utility
-    ...       factory="lazr.restful.example.base.filemanager.FileManager" />
-    ... </configure>
-    ... """)
-
-Here's the configuration, which defines the three versions: 'beta',
-'1.0', and 'dev'.
-
-    >>> from lazr.restful import directives
-    >>> from lazr.restful.interfaces import IWebServiceConfiguration
-    >>> from lazr.restful.simple import BaseWebServiceConfiguration
-    >>> from lazr.restful.testing.webservice import WebServiceTestPublication
-
-    >>> class WebServiceConfiguration(BaseWebServiceConfiguration):
-    ...     hostname = 'api.multiversion.dev'
-    ...     use_https = False
-    ...     active_versions = ['beta', '1.0']
-    ...     latest_version_uri_prefix = 'dev'
-    ...     code_revision = 'test'
-    ...     max_batch_size = 100
-    ...     directives.publication_class(WebServiceTestPublication)
-
-    >>> from grokcore.component.testing import grok_component
-    >>> ignore = grok_component(
-    ...     'WebServiceConfiguration', WebServiceConfiguration)
-
-    >>> from zope.component import getUtility
-    >>> config = getUtility(IWebServiceConfiguration)
-
-
 The service root resource
 =========================
 
@@ -384,8 +437,6 @@
     ...         RootResourceAbsoluteURL, [cls, IBrowserRequest])
 
     >>> from zope.traversing.browser import absoluteURL
-    >>> from lazr.restful.testing.webservice import (
-    ...     create_web_service_request)
 
     >>> beta_request = create_web_service_request('/beta/')
     >>> ignore = beta_request.traverse(None)
@@ -397,3 +448,25 @@
     >>> print absoluteURL(dev_app, dev_request)
     http://api.multiversion.dev/dev/
 
+
+Request lifecycle
+=================
+
+When a request first comes in, there's no way to tell which version
+it's associated with.
+
+    >>> from lazr.restful.testing.webservice import (
+    ...     create_web_service_request)
+
+    >>> request_beta = create_web_service_request('/beta/')
+    >>> IWebServiceRequestBeta.providedBy(request_beta)
+    False
+
+The traversal process associates the request with a particular version.
+
+    >>> request_beta.traverse(None)
+    <BetaServiceRootResource object ...>
+    >>> IWebServiceRequestBeta.providedBy(request_beta)
+    True
+    >>> print request_beta.version
+    beta

=== modified file 'src/lazr/restful/interfaces/_rest.py'
--- src/lazr/restful/interfaces/_rest.py	2009-11-18 17:33:20 +0000
+++ src/lazr/restful/interfaces/_rest.py	2010-01-06 21:06:12 +0000
@@ -48,6 +48,7 @@
     'LAZR_WEBSERVICE_NAME',
     'LAZR_WEBSERVICE_NS',
     'IWebServiceClientRequest',
+    'IVersionedClientRequestImplementation',
     'IWebServiceLayer',
     ]
 
@@ -251,13 +252,28 @@
 
 
 class IWebServiceClientRequest(IBrowserRequest):
-    """Marker interface requests to the web service."""
+    """Interface for requests to the web service."""
+    version = Attribute("The version of the web service that the client "
+                        "requested.")
 
 
 class IWebServiceLayer(IWebServiceClientRequest, IDefaultBrowserLayer):
     """Marker interface for registering views on the web service."""
 
 
+class IVersionedClientRequestImplementation(Interface):
+    """Used to register IWebServiceClientRequest subclasses as utilities.
+
+    Every version of a web service must register a subclass of
+    IWebServiceClientRequest as an
+    IVersionedClientRequestImplementation utility, with a name that's
+    the web service version name. For instance:
+
+    registerUtility(IWebServiceClientRequestBeta,
+                    IVersionedClientRequestImplementation, name="beta")
+    """
+    pass
+
 class IJSONRequestCache(Interface):
     """A cache of objects exposed as URLs or JSON representations."""
 

=== modified file 'src/lazr/restful/publisher.py'
--- src/lazr/restful/publisher.py	2009-11-19 15:53:26 +0000
+++ src/lazr/restful/publisher.py	2010-01-06 21:06:12 +0000
@@ -34,7 +34,8 @@
     EntryResource, ScopedCollection, ServiceRootResource)
 from lazr.restful.interfaces import (
     IByteStorage, ICollection, ICollectionField, IEntry, IEntryField,
-    IHTTPResource, IServiceRootResource, IWebBrowserInitiatedRequest,
+    IHTTPResource, IServiceRootResource,
+    IVersionedClientRequestImplementation, IWebBrowserInitiatedRequest,
     IWebServiceClientRequest, IWebServiceConfiguration)
 
 
@@ -255,11 +256,25 @@
             raise NotFound(self, '', self)
         self.annotations[self.VERSION_ANNOTATION] = version
 
+        # Find the version-specific interface this request should
+        # provide, and provide it.
+        try:
+            to_provide = getUtility(IVersionedClientRequestImplementation,
+                                    name=version)
+            alsoProvides(self, to_provide)
+        except ComponentLookupError:
+            # XXX leonardr 2009-11-23 This stops single-version tests
+            # from breaking. I'll probably remove it once the
+            # necessary version-specific interfaces are automatically
+            # generated.
+            pass
+        self.version = version
+
         # Find the appropriate service root for this version and set
         # the publication's application appropriately.
         try:
             # First, try to find a version-specific service root.
-            service_root = getUtility(IServiceRootResource, name=version)
+            service_root = getUtility(IServiceRootResource, name=self.version)
         except ComponentLookupError:
             # Next, try a version-independent service root.
             service_root = getUtility(IServiceRootResource)