Add documentation and JSON Schema validation

Author: zkayyali812

ansible_base/feature_flags/feature_flags.yaml renamed to ansible_base/feature_flags/definitions/feature_flags.yaml

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Flag Configuration Schema",
+  "description": "Validates a list of feature flag configurations.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "description": "The unique identifier for the feature flag. Must be in all capitals and start with 'FEATURE_' and end with '_ENABLED'",
+        "type": "string",
+        "pattern": "^FEATURE_[A-Z0-9_]+_ENABLED$"
+      },
+      "ui_name": {
+        "description": "The human-readable name for the feature flag displayed in the UI.",
+        "type": "string",
+        "minLength": 1
+      },
+      "visibility": {
+        "description": "Controls whether the feature is visible in the UI.",
+        "type": "string",
+        "enum": ["public", "private"]
+      },
+      "condition": {
+        "description": "The type of condition for the feature flag's value. Currently only boolean is supported.",
+        "type": "string",
+        "enum": ["boolean"]
+      },
+      "value": {
+        "description": "The default value of the feature flag, as a string.",
+        "type": "string",
+        "enum": ["True", "False"]
+      },
+      "support_level": {
+        "description": "The level of support provided for this feature.",
+        "type": "string",
+        "enum": [
+          "NOT_FOR_USE",
+          "NOT_FOR_PRODUCTION",
+          "READY_FOR_PRODUCTION"
+        ]
+      },
+      "description": {
+        "description": "A brief explanation of what the feature does.",
+        "type": "string"
+      },
+      "support_url": {
+        "description": "A URL to the relevant documentation for the feature.",
+        "type": "string",
+        "format": "uri"
+      },
+      "toggle_type": {
+        "description": "The actual value of the feature flag. Note: The YAML string 'False' or 'True' is parsed as a boolean.",
+        "type": "string",
+        "enum": ["install-time", "run-time"]
+      },
+      "labels": {
+        "description": "A list of labels to categorize the feature.",
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["controller", "eda", "gateway", "platform"]
+        },
+        "minItems": 1,
+        "uniqueItems": true
+      }
+    },
+    "required": [
+      "name",
+      "ui_name",
+      "visibility",
+      "condition",
+      "value",
+      "support_level",
+      "description",
+      "support_url"
+    ]
+  }
+}

ansible_base/feature_flags/definitions/schema.json

@@ -2,14 +2,6 @@
 from flags.sources import Condition
 
 
-class DatabaseCondition(Condition):
-    """Condition that includes the AAPFlags database object"""
-
-    def __init__(self, condition, value, required=False, obj=None):
-        super().__init__(condition, value, required=required)
-        self.obj = obj
-
-
 class AAPFlagSource(object):
 
     def get_queryset(self):
@@ -21,5 +13,5 @@ def get_flags(self):
         for o in self.get_queryset():
             if o.name not in flags:
                 flags[o.name] = []
-            flags[o.name].append(DatabaseCondition(o.condition, o.value, required=o.required, obj=o))
+            flags[o.name].append(Condition(o.condition, o.value, required=o.required))
         return flags

ansible_base/feature_flags/flag_source.py

@@ -1,11 +1,30 @@
 from flags.state import flag_state
+from rest_framework import serializers
 
 from ansible_base.feature_flags.models import AAPFlag
 from ansible_base.lib.serializers.common import NamedCommonModelSerializer
 
 from .utils import get_django_flags
 
 
+class FeatureFlagStatesSerializer(NamedCommonModelSerializer):
+    """Serialize list of feature flags"""
+
+    state = serializers.SerializerMethodField()
+
+    def get_state(self, instance):
+        return flag_state(instance.name)
+
+    class Meta:
+        model = AAPFlag
+        fields = ["name", "state"]
+
+    def to_representation(self, instance=None) -> dict:
+        instance.state = True
+        ret = super().to_representation(instance)
+        return ret
+
+
 # TODO: Remove once all components are migrated to the new endpont.
 class OldFeatureFlagSerializer(NamedCommonModelSerializer):
     """Serialize list of feature flags"""

ansible_base/feature_flags/serializers.py

@@ -16,7 +16,7 @@ def get_django_flags():
 
 def feature_flags_list():
     current_dir = Path(__file__).parent
-    flags_list_file = current_dir / 'feature_flags.yaml'
+    flags_list_file = current_dir / 'definitions/feature_flags.yaml'
     with open(flags_list_file, 'r') as file:
         try:
             return yaml.safe_load(file)

ansible_base/feature_flags/utils.py

@@ -1,16 +1,13 @@
 from django.conf import settings
 from django.utils.translation import gettext_lazy as _
-from flags.sources import get_flags
-from flags.state import flag_state
 from rest_framework.response import Response
 from rest_framework.viewsets import ModelViewSet
 
 from ansible_base.feature_flags.models import AAPFlag
-from ansible_base.feature_flags.serializers import OldFeatureFlagSerializer
+from ansible_base.feature_flags.serializers import FeatureFlagStatesSerializer, OldFeatureFlagSerializer
 from ansible_base.lib.utils.views.ansible_base import AnsibleBaseView
 from ansible_base.lib.utils.views.django_app_api import AnsibleBaseDjangoAppApiView
 from ansible_base.lib.utils.views.permissions import IsSuperuserOrAuditor, try_add_oauth2_scope_permission
-from ansible_base.rest_pagination import DefaultPaginator
 
 from .utils import get_django_flags
 
@@ -22,17 +19,9 @@ class FeatureFlagsStatesView(AnsibleBaseDjangoAppApiView, ModelViewSet):
 
     queryset = AAPFlag.objects.order_by('id')
     permission_classes = try_add_oauth2_scope_permission([IsSuperuserOrAuditor])
+    serializer_class = FeatureFlagStatesSerializer
     http_method_names = ['get', 'head', 'options']
 
-    def list(self, request):
-        paginator = DefaultPaginator()
-        flags = get_flags()
-        ret = []
-        for flag in flags:
-            ret.append({"flag_name": flag, "flag_state": flag_state(flag)})
-        result_page = paginator.paginate_queryset(ret, request)
-        return paginator.get_paginated_response(result_page)
-
 
 # TODO: This can be removed after functionality is migrated over to new class
 class OldFeatureFlagsStateListView(AnsibleBaseView):

ansible_base/feature_flags/views.py

@@ -5,55 +5,32 @@ Additional library documentation can be found at https://cfpb.github.io/django-f
 
 ## Settings
 
-Add `ansible_base.feature_flags` to your installed apps:
+Add `ansible_base.feature_flags` to your installed apps and ensure `ansible_base.resource_registry` as added to enable flag state to sync across the platform:
 
 ```python
 INSTALLED_APPS = [
     ...
     'ansible_base.feature_flags',
+    'ansible_base.resource_registry', # Must also be added
 ]
 ```
 
-### Additional Settings
+## Detail
 
-Additional settings are required to enable feature_flags.
-This will happen automatically if using [dynamic_settings](../Installation.md)
-
-First, you need to add `flags` to your `INSTALLED_APPS`:
+By adding the `ansible_base.feature_flags` app to your application, all Ansible Automation Platform feature flags will be loaded and available in your component.
+To receive flag state updates, ensure the following definition is available in your components `RESOURCE_LIST` - 
 
 ```python
-INSTALLED_APPS = [
-    ...
-    'flags',
-    ...
-]
-```
-
-Additionally, create a `FLAGS` entry:
-
-```python
-FLAGS = {}
-```
-
-Finally, add `django.template.context_processors.request` to your `TEMPLATES` `context_processors` setting:
+from ansible_base.feature_flags.models import AAPFlag
+from ansible_base.resource_registry.shared_types import FeatureFlagType
 
-```python
-TEMPLATES = [
-    {
-        'BEACKEND': 'django.template.backends.django.DjangoTemplates',
-        ...
-        'OPTIONS': {
-            ...
-            'context_processors': [
-                ...
-                'django.template.context_processors.request',
-                ...
-            ]
-            ...
-        }
-        ...
-    }
-]
+RESOURCE_LIST = (
+    ...
+    ResourceConfig(
+        AAPFlag,
+        shared_resource=SharedResource(serializer=FeatureFlagType, is_provider=False),
+    ),
+)
 ```
 
 ## URLS
@@ -70,3 +47,29 @@ urlpatterns = [
     ...
 ]
 ```
+
+## Adding Feature Flags
+
+To add a feature flag to the platform, specify it in the following [file](../../ansible_base/feature_flags/definitions/feature_flags.yaml)
+
+An example flag could resemble -
+
+```yaml
+- name: FEATURE_FOO_ENABLED
+  ui_name: Foo
+  visibility: public
+  condition: boolean
+  value: 'False'
+  support_level: NOT_FOR_PRODUCTION
+  description: TBD
+  support_url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/
+  labels:
+    - controller
+```
+
+Validate this file against the json schema by running `check-jsonschema` -
+
+```bash
+pip install check-jsonschema
+check-jsonschema --schemafile ansible_base/feature_flags/definitions/schema.json ansible_base/feature_flags/definitions/feature_flags.yaml
+```

docs/apps/feature_flags.md

@@ -9,6 +9,7 @@ flake8==7.1.1           # Linting tool, if changed update pyproject.toml as well
 Flake8-pyproject==1.2.3 # Linting tool, if changed update pyproject.toml as well
 ipython
 isort==6.0.0            # Linting tool, if changed update pyproject.toml as well
+jsonschema
 tox
 tox-docker
 typeguard

requirements/requirements_dev.txt

@@ -1,7 +1,10 @@
+import json
 from unittest.mock import MagicMock, call
 
 import pytest
+import yaml
 from django.core.exceptions import ValidationError
+from jsonschema import validate
 
 MODULE_PATH = "ansible_base.feature_flags.utils"
 
@@ -119,6 +122,23 @@ def test_get_django_flags(mocker):
     assert result == {"FLAG_X": True}
 
 
+def test_validate_flags_yaml_against_json_schema():
+    feature_flags_yaml = 'ansible_base/feature_flags/definitions/feature_flags.yaml'
+    feature_flags_schema = 'ansible_base/feature_flags/definitions/schema.json'
+    try:
+        with open(feature_flags_yaml, 'r') as file:
+            feature_flags_file = yaml.safe_load(file)
+        with open(feature_flags_schema, 'r') as file:
+            schema = json.load(file)
+        validate(instance=feature_flags_file, schema=schema)
+        assert True, "Validation succeeded as expected."
+    except FileNotFoundError as e:
+        pytest.fail(f"Could not find a necessary file: {e}. Make sure schema.json and valid_data.yaml exist.")
+    except Exception as e:
+        # If any other exception occurs (like a ValidationError), fail the test.
+        pytest.fail(f"Validation failed unexpectedly for a valid file: {e}")
+
+
 class TestCreateInitialData:
 
     @pytest.mark.django_db  # May not be strictly necessary with all the mocking, but good practice

test_app/tests/feature_flags/test_utils.py

@@ -37,11 +37,11 @@ def test_feature_flags_states_list(admin_api_client, flags_list):
 
     found_and_verified_flags_count = 0
     for flag_from_api in response.data['results']:
-        api_flag_name = flag_from_api.get('flag_name')
+        api_flag_name = flag_from_api.get('name')
         if api_flag_name in expected_flag_states:
             found_and_verified_flags_count += 1
             expected_value = expected_flag_states[api_flag_name]
-            actual_value = flag_from_api.get('flag_state')
+            actual_value = flag_from_api.get('state')
             assert actual_value == expected_value
 
     # Assert that all flags you intended to check were actually found in the API response and verified