Merge "graduate-oslo-middleware"

specs/juno/graduate-oslo-middleware.rst

@@ -0,0 +1,122 @@
+===========================
+ Graduating Oslo Middleware
+===========================
+
+https://blueprints.launchpad.net/oslo/+spec/graduate-oslo-middleware
+
+The new oslo.middleware library will provide a common library for wsgi
+middleware currently contained in oslo-incubator.
+
+Library Name
+============
+
+oslo.middleware
+
+Contents
+========
+
+* openstack/common/middleware/base.py
+* openstack/common/middleware/catch_errors.py
+* openstack/common/middleware/correlation_id.py
+* openstack/common/middleware/debug.py
+* openstack/common/middleware/request_id.py
+* openstack/common/middleware/sizelimit.py
+* tests/unit/middleware/test_catch_errors.py
+* tests/unit/middleware/test_correlation_id.py
+* tests/unit/middleware/test_request_id.py
+* tests/unit/middleware/test_sizelimit.py
+
+
+Early Adopters
+==============
+
+None
+
+Public API
+==========
+
+oslo.middleware library provides access to the following middleware
+('middleware' suffix will be dropped from original naming)::
+
+    * CatchErrors
+    * CorrelationId
+    * Debug
+    * RequestId
+    * RequestBodySizeLimiter
+
+To utilise the new middleware, after including oslo.middleware library,
+projects can declare the new middleware in wsgi pipeline as such::
+
+    [filter:<middleware>]
+    paste.filter_factory = oslo.middleware:<ClassName>.factory
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  chungg
+
+Other contributors:
+  None
+
+Primary Maintainer
+------------------
+
+Primary Maintainer:
+  dims
+
+Other Contributors:
+  chungg
+
+Security Contact
+----------------
+
+Security Contact:
+  dims
+
+Milestones
+----------
+
+Target Milestone for completion: Juno-3
+
+Work Items
+----------
+
+* https://wiki.openstack.org/wiki/Oslo/CreatingANewLibrary#Checklist
+* add deprecated decorator to current incubator classes
+* drop middleware suffix from class names
+* import middleware classes into middleware/__init__.py
+* audit middleware will not be included. it will be included in
+  keystonemiddleware as part of keystone's adoption of audit
+* notifier middleware will not be included. it will be included in
+  oslo.messaging to minimise dependencies in oslo.middleware.
+
+Adoption Notes
+==============
+
+General use of middleware remains the same. The only change in usage would be
+to reference middlware in oslo.middleware library rather than openstack/common.
+
+A deprecated decorator will be added to existing incubator classes so when
+the incubator version is used, log will notify of current oslo.middleware
+version.
+
+Dependencies
+============
+
+None
+
+References
+==========
+
+https://etherpad.openstack.org/p/oslo-middleware-dependency
+
+.. note::
+
+  This work is licensed under a Creative Commons Attribution 3.0
+  Unported License.
+  http://creativecommons.org/licenses/by/3.0/legalcode
+