feat(system/roles): add Deprecation header on old path

GET /auth/system/roles is superseded by GET /auth/resource/system/roles,
which has been live since the system Blueprint was registered under the
resources Blueprint.  Add Deprecation: true and a Link successor-version
header when the endpoint is reached via the old path, so callers can
discover the new URL.

The old registration in auth/views.py already carries a TODO noting it
should be removed once consumers are updated.  Callers to migrate:
- GN2: wqflask/views.py, metadata_edits.py (×3), flask_extensions.py,
        oauth2/ui.py, oauth2/request_utils.py, oauth2/resources.py (×2)
- GN3: gn3/api/metadata.py, gn3/api/case_attributes.py
- gn-integration-tests: tests/test_gn_auth_smoke.py

Reviewed-By: Frederick M. Muriithi <fredmanglis@gmail.com>

1 files changed, 21 insertions, 7 deletions

diff --git a/gn_auth/auth/authorisation/resources/system/views.py b/gn_auth/auth/authorisation/resources/system/views.py
index d7a57a9..23ea6e9 100644
--- a/gn_auth/auth/authorisation/resources/system/views.py
+++ b/gn_auth/auth/authorisation/resources/system/views.py
@@ -1,7 +1,8 @@
 """Views relating to `System` resource(s)."""
 import logging
+import warnings
 from dataclasses import asdict
-from flask import request, jsonify, Blueprint, current_app as app
+from flask import request, jsonify, Blueprint, make_response, current_app as app
 
 from gn_libs import sqlite3 as authdb
 
@@ -13,6 +14,8 @@ from .models import user_roles_on_system
 logger = logging.getLogger(__name__)
 system = Blueprint("system", __name__)
 
+_SUCCESSOR = "/auth/resource/system/roles"
+
 
 @system.route("/roles")
 def system_roles():
@@ -25,10 +28,21 @@ def system_roles():
                 "INNER JOIN role_privileges AS rp ON r.role_id=rp.role_id "
                 "INNER JOIN privileges AS p ON rp.privilege_id=p.privilege_id "
                 "WHERE r.role_name='public-view'")
-            return jsonify(tuple(
-                asdict(role) for role in db_rows_to_roles(cursor.fetchall())))
+            roles_data = tuple(
+                asdict(role) for role in db_rows_to_roles(cursor.fetchall()))
+        else:
+            with require_oauth.acquire("profile group") as the_token:
+                roles_data = tuple(
+                    asdict(role) for role in
+                    user_roles_on_system(conn, the_token.user))
 
-        with require_oauth.acquire("profile group") as the_token:
-            return jsonify(tuple(
-                asdict(role) for role in
-                user_roles_on_system(conn, the_token.user)))
+    resp = make_response(jsonify(roles_data))
+    if "/resource/" not in request.path:
+        resp.headers["Deprecation"] = "true"
+        resp.headers["Link"] = f'<{_SUCCESSOR}>; rel="successor-version"'
+        warnings.warn(
+            ("The endpoint `/auth/system/roles` is deprecated -- please use "
+             "`/auth/resource/system/roles` instead."),
+            category=DeprecationWarning,
+            stacklevel=2)
+    return resp