From df1542686349a97ab1527f80c81861d89aaf4f78 Mon Sep 17 00:00:00 2001
From: Chris Dent <cdent@anticdent.org>
Date: Wed, 13 Jun 2018 14:38:23 +0100
Subject: [PATCH] [placement] Add status and links fields to version document
 at /

According to the spec [1] the version discovery doc must have a status
and links for each version. For the primary version the status value
should be 'CURRENT'. For placement the version discovery doc and "self"
are the same thing, so the provided "self" href looks redundant, but it
makes keystoneauth1 happy when doing version discovery.

In placement, since there is only one version at the moment, set status
to CURRENT.

Add a gabbi test that verifies the presence of both fields and values.

Without these fields, use of placement with a client that follows the
documented version discovery process will fail to work.

As the version doc is not considered microversioned[2] and in any case
this is making version discovery work where it didn't before, this is
not a candidate for a microversion and can be backported to the
beginning of placement's history if we like.

I've updated the api-ref docs. In the process I made the max
microversion in the sample discovery doc a bit more realistic and
in alignment with these modern times.

Changes:
  placement-api-ref/source/get-root.json

NOTE(stephenfin): Modified the root API sample to reflect the max
placement API version in Queens.

[1] http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html#version-discovery
[2] http://eavesdrop.openstack.org/irclogs/%23openstack-sdks/%23openstack-sdks.2018-06-13.log.html#t2018-06-13T13:40:12

Change-Id: Ie602ab1768efbf103563d8f6b9d28965fc81021a
Closes-Bug: #1776668
(cherry picked from commit 1a5a3a9bc8409349ab817b4858ee54bf2a036dab)
---
 nova/api/openstack/placement/handlers/root.py       | 12 ++++++++++++
 .../openstack/placement/gabbits/microversion.yaml   |  2 ++
 placement-api-ref/source/get-root.json              |  9 ++++++++-
 placement-api-ref/source/parameters.yaml            | 13 +++++++++++++
 placement-api-ref/source/root.inc                   |  2 ++
 5 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/nova/api/openstack/placement/handlers/root.py b/nova/api/openstack/placement/handlers/root.py
index 2f9c6861f2bc..298dab3816e0 100644
--- a/nova/api/openstack/placement/handlers/root.py
+++ b/nova/api/openstack/placement/handlers/root.py
@@ -32,6 +32,18 @@ def home(req):
         'id': 'v%s' % min_version,
         'max_version': max_version,
         'min_version': min_version,
+        # for now there is only ever one version, so it must be CURRENT
+        'status': 'CURRENT',
+        'links': [{
+            # Point back to this same URL as the root of this version.
+            # NOTE(cdent): We explicitly want this to be a relative-URL
+            # representation of "this same URL", otherwise placement needs
+            # to keep track of proxy addresses and the like, which we have
+            # avoided thus far, in order to construct full URLs. Placement
+            # is much easier to scale if we never track that stuff.
+            'rel': 'self',
+            'href': '',
+        }],
     }
     version_json = jsonutils.dumps({'versions': [version_data]})
     req.response.body = encodeutils.to_utf8(version_json)
diff --git a/nova/tests/functional/api/openstack/placement/gabbits/microversion.yaml b/nova/tests/functional/api/openstack/placement/gabbits/microversion.yaml
index 2a40d4f5cc17..27f81ca8c01c 100644
--- a/nova/tests/functional/api/openstack/placement/gabbits/microversion.yaml
+++ b/nova/tests/functional/api/openstack/placement/gabbits/microversion.yaml
@@ -22,6 +22,8 @@ tests:
       $.versions[0].max_version: /^\d+\.\d+$/
       $.versions[0].min_version: /^\d+\.\d+$/
       $.versions[0].id: v1.0
+      $.versions[0].status: CURRENT
+      $.versions[0].links[?rel = 'self'].href: ''
 
 - name: unavailable microversion raises 406
   GET: /
diff --git a/placement-api-ref/source/get-root.json b/placement-api-ref/source/get-root.json
index bdb92c3decea..e825006d71e4 100644
--- a/placement-api-ref/source/get-root.json
+++ b/placement-api-ref/source/get-root.json
@@ -3,7 +3,14 @@
         {
             "min_version" : "1.0",
             "id" : "v1.0",
-            "max_version" : "1.2"
+            "max_version" : "1.17",
+            "status": "CURRENT",
+            "links": [
+                {
+                    "href": "",
+                    "rel": "self"
+                }
+            ]
         }
     ]
 }
diff --git a/placement-api-ref/source/parameters.yaml b/placement-api-ref/source/parameters.yaml
index 6c1e87bdd99a..187881798fff 100644
--- a/placement-api-ref/source/parameters.yaml
+++ b/placement-api-ref/source/parameters.yaml
@@ -416,6 +416,12 @@ version_id:
   required: true
   description: >
     A common name for the version being described. Informative only.
+version_links:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of links related to and describing this version.
 version_max:
   type: string
   in: body
@@ -428,6 +434,13 @@ version_min:
   required: true
   description: >
     The minimum microversion that is supported.
+version_status:
+  type: string
+  in: body
+  required: true
+  description: >
+    The status of the version being described. With placement this is
+    "CURRENT".
 versions:
   type: array
   in: body
diff --git a/placement-api-ref/source/root.inc b/placement-api-ref/source/root.inc
index d6c498c05218..b92b37aaa288 100644
--- a/placement-api-ref/source/root.inc
+++ b/placement-api-ref/source/root.inc
@@ -41,6 +41,8 @@ Response
   - id: version_id
   - min_version: version_min
   - max_version: version_max
+  - status: version_status
+  - links: version_links
 
 Response Example
 ----------------