Add CORS Middleware for Oslo.

This aims to provide a comprehensive middleware solution
for the CORS (Cross-Origin-Resource-Sharing) specification -
http://www.w3.org/TR/cors/.

Tests and documentation have been provided.

Change-Id: I3c0ff620f10bec2cbf7b748d48fff025aab44351

2 files changed, 63 insertions, 0 deletions

diff --git a/doc/source/cors.rst b/doc/source/cors.rst
new file mode 100644
index 0000000..00ed574
--- /dev/null
+++ b/doc/source/cors.rst
@@ -0,0 +1,62 @@
+===============
+CORS Middleware
+===============
+
+This middleware provides a comprehensive, configurable implementation of the
+CORS_ (Cross Origin Resource Sharing) specification as oslo-supported python
+wsgi middleware.
+
+Quickstart
+----------
+First, include the middleware in your application::
+
+    from oslo_middleware import cors
+    from oslo_config import cfg
+
+    app = cors.CORS(your_wsgi_application, cfg.CONF)
+
+Secondly, add a global [cors] configuration block to the configuration file
+read by oslo.config::
+
+    [cors]
+    allowed_origin=https://website.example.com:443
+    max_age=3600
+    allow_methods=GET,POST,PUT,DELETE
+    allow_headers=Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header
+    expose_headers=Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header
+
+Advanced Configuration
+----------------------
+CORS Middleware permits you to define multiple `allowed_origin`'s, and to
+selectively override the global configuration for each. To accomplish this,
+first follow the setup instructions in the Quickstart above.
+
+Then, create an new configuration group for each domain that you'd like to
+extend. Each of these configuration groups must be named `[cors.something]`,
+with each name being unique. The purpose of the suffix to `cors.` is
+legibility, we recommend using a reasonable human-readable string::
+
+    [cors.ironic_webclient]
+    # CORS Configuration for a hypothetical ironic webclient, which overrides
+    # authentication
+    allowed_origin=https://ironic.example.com:443
+    allow_credentials=True
+
+    [cors.horizon]
+    # CORS Configuration for horizon, which uses global options.
+    allowed_origin=https://horizon.example.com:443
+
+    [cors.dashboard]
+    # CORS Configuration for a hypothetical dashboard, which only permits
+    # HTTP GET requests.
+    allowed_origin=https://dashboard.example.com:443
+    allow_methods=GET
+
+
+Module Documentation
+--------------------
+
+.. automodule:: oslo_middleware.cors
+   :members:
+
+.. _CORS: http://www.w3.org/TR/cors/
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e2aed92..ebca9f6 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -9,4 +9,5 @@ Contents
    installation
    api
    healthcheck_plugins
+   cors
    contributing