From 8d70e6c65cc764edeb4a20df4c22fbee24a57823 Mon Sep 17 00:00:00 2001
From: Sean Dague <sean@dague.net>
Date: Thu, 21 Jan 2016 08:29:20 -0500
Subject: [PATCH] cleanup: add comments about the pre/post extension processing

In doing the cleanup of the rest of the wsgi stack I finally figured
out what really was going on here. This can't come out today because
of the legacyv2 code stack, however it can be largely removed when
that drops.

Change-Id: Ie7489b9eb1eb42ba3c4ea2d7ea973eb8d875f0ea
---
 nova/api/openstack/wsgi.py | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/nova/api/openstack/wsgi.py b/nova/api/openstack/wsgi.py
index 7dc6df81487f..c26147ede255 100644
--- a/nova/api/openstack/wsgi.py
+++ b/nova/api/openstack/wsgi.py
@@ -542,6 +542,29 @@ class Resource(wsgi.Application):
     def deserialize(self, body):
         return JSONDeserializer().deserialize(body)
 
+    # NOTE(sdague): I didn't start the fire, however here is what all
+    # of this is about.
+    #
+    # In the legacy v2 code stack, extensions could extend actions
+    # with a generator that let 1 method be split into a top and
+    # bottom half. The top half gets executed before the main
+    # processing of the request (so effectively gets to modify the
+    # request before it gets to the main method).
+    #
+    # Returning a response triggers a shortcut to fail out. The
+    # response will nearly always be a failure condition, as it ends
+    # up skipping further processing one level up from here.
+    #
+    # This then passes on the list of extensions, in reverse order,
+    # on. post_process will run through all those, again with same
+    # basic logic.
+    #
+    # In tree this is only used in the legacy v2 stack, and only in
+    # the DiskConfig and SchedulerHints from what I can see.
+    #
+    # pre_process_extensions can be removed when the legacyv2 code
+    # goes away. post_proccess_extensions can be massively simplified
+    # at that point.
     def pre_process_extensions(self, extensions, request, action_args):
         # List of callables for post-processing extensions
         post = []
@@ -569,7 +592,8 @@ class Resource(wsgi.Application):
                 # Regular functions only perform post-processing
                 post.append(ext)
 
-        # Run post-processing in the reverse order
+        # None is response, it means we keep going. We reverse the
+        # extension list for post-processing.
         return None, reversed(post)
 
     def post_process_extensions(self, extensions, resp_obj, request,