[#3196] Add IMiddleware hooks to Flask stack

Clarify what app will you get on the interface docstrings

Conflicts:
	ckan/config/middleware/flask_app.py
	ckan/plugins/interfaces.py

ckan/config/middleware/flask_app.py

@@ -26,7 +26,7 @@
 from ckan.common import config, g, request, ungettext
 import ckan.lib.app_globals as app_globals
 from ckan.plugins import PluginImplementations
-from ckan.plugins.interfaces import IBlueprint
+from ckan.plugins.interfaces import IBlueprint, IMiddleware
 from ckan.views import (identify_user,
                         set_cors_headers_for_response,
                         check_session_cookie,
@@ -209,6 +209,9 @@ def hello_world_post():
 
     # Start other middleware
 
+    for plugin in PluginImplementations(IMiddleware):
+        app = plugin.make_middleware(app, config)
+
     # Fanstatic
     if debug:
         fanstatic_config = {
@@ -228,6 +231,14 @@ def hello_world_post():
         }
     app = Fanstatic(app, **fanstatic_config)
 
+    for plugin in PluginImplementations(IMiddleware):
+        try:
+            app = plugin.make_error_log_middleware(app, config)
+        except AttributeError:
+            log.critical('Middleware class {0} is missing the method'
+                         'make_error_log_middleware.'
+                         .format(plugin.__class__.__name__))
+
     # Update the main CKAN config object with the Flask specific keys
     # that were set here or autogenerated
     flask_config_keys = set(flask_app.config.keys()) - set(config.keys())

ckan/plugins/interfaces.py

@@ -57,15 +57,40 @@ def implemented_by(cls, other):
 
 
 class IMiddleware(Interface):
-    u'''Hook into Pylons middleware stack
+    u'''Hook into CKAN middleware stack
+
+    Note that methods on this interface will be called two times,
+    one for the Pylons stack and one for the Flask stack (eventually
+    there will be only the Flask stack).
     '''
     def make_middleware(self, app, config):
         u'''Return an app configured with this middleware
+
+        When called on the Flask stack, this method will get the actual Flask
+        app so plugins wanting to install Flask extensions can do it like
+        this::
+
+            import ckan.plugins as p
+            from flask_mail import Mail
+
+            class MyPlugin(p.SingletonPlugin):
+
+                p.implements(p.I18nMiddleware)
+
+                def make_middleware(app, config):
+
+                    mail = Mail(app)
+
+                    return app
         '''
         return app
 
     def make_error_log_middleware(self, app, config):
         u'''Return an app configured with this error log middleware
+
+        Note that both on the Flask and Pylons middleware stacks, this
+        method will receive a wrapped WSGI app, not the actual Flask or
+        Pylons app.
         '''
         return app