feat: restricted runs allowed

Supports a new top-level key in content filters: restricted_runs_allowed.
The value will be a mapping of course key (str) to a list of course run key (str).
Updates the customer-based contains_content_items API endpoint
(`/api/v1/enterprise-customer/{enterprise_uuid}/contains_content_items/`)
to serialize an additional key in the response body containing a mapping of
restricted runs to catalog UUIDs for requested course keys.
Fundamentally, this becomes a transposition of the reverse mapping encoded in the content filter.
ENT-9358

docker-compose.yml

@@ -1,4 +1,3 @@
-version: "2.1"
 services:
   mysql:
     image: mysql:8.0.28-oracle

enterprise_catalog/apps/api/v1/views/enterprise_customer.py

@@ -1,5 +1,6 @@
 import logging
 import uuid
+from collections import defaultdict
 
 from django.utils.decorators import method_decorator
 from edx_rbac.utils import get_decoded_jwt
@@ -14,6 +15,10 @@
 from enterprise_catalog.apps.api.v1.serializers import ContentMetadataSerializer
 from enterprise_catalog.apps.api.v1.utils import unquote_course_keys
 from enterprise_catalog.apps.api.v1.views.base import BaseViewSet
+from enterprise_catalog.apps.catalog.constants import (
+    COURSE_RUN_KEY_PREFIX,
+    RESTRICTED_RUNS_ALLOWED_KEY,
+)
 from enterprise_catalog.apps.catalog.models import EnterpriseCatalog
 
 
@@ -101,7 +106,7 @@ def contains_content_items(self, request, enterprise_uuid, course_run_ids, progr
                 f'Error: invalid enterprice customer uuid: "{enterprise_uuid}" provided.',
                 status=HTTP_400_BAD_REQUEST
             )
-        customer_catalogs = EnterpriseCatalog.objects.filter(enterprise_uuid=enterprise_uuid)
+        customer_catalogs = list(EnterpriseCatalog.objects.filter(enterprise_uuid=enterprise_uuid))
 
         any_catalog_contains_content_items = False
         catalogs_that_contain_course = []
@@ -119,8 +124,32 @@ def contains_content_items(self, request, enterprise_uuid, course_run_ids, progr
         }
         if (get_catalogs_containing_specified_content_ids or get_catalog_list):
             response_data['catalog_list'] = catalogs_that_contain_course
+
+        response_data[RESTRICTED_RUNS_ALLOWED_KEY] = self._get_restricted_runs_allowed_for_query(
+            course_run_ids, customer_catalogs,
+        )
         return Response(response_data)
 
+    def _get_restricted_runs_allowed_for_query(self, course_run_ids, customer_catalogs):
+        # filter the set of restricted course keys down to only
+        # those requested by the client, and only if those requested keys
+        # are top-level course keys (NOT course run keys).
+        requested_course_keys = {
+            key for key in course_run_ids if not key.startswith(COURSE_RUN_KEY_PREFIX)
+        }
+        serialized_data = defaultdict(lambda: defaultdict(lambda: {'catalog_uuids': set()}))
+        for catalog in customer_catalogs:
+            if not catalog.restricted_runs_allowed:
+                continue
+            for restricted_course_key, restricted_runs in catalog.restricted_runs_allowed.items():
+                if restricted_course_key not in requested_course_keys:
+                    continue
+                course_dict = serialized_data[restricted_course_key]
+                for course_run_key in restricted_runs:
+                    run_dict = course_dict[course_run_key]
+                    run_dict['catalog_uuids'].add(str(catalog.uuid))
+        return serialized_data or None
+
     @action(detail=True, methods=['post'])
     def filter_content_items(self, request, enterprise_uuid, **kwargs):
         """

enterprise_catalog/apps/catalog/constants.py

@@ -108,6 +108,12 @@
 
 FORCE_INCLUSION_METADATA_TAG_KEY = 'enterprise_force_included'
 
+RESTRICTED_RUNS_ALLOWED_KEY = 'restricted_runs_allowed'
+
+AGGREGATION_KEY_PREFIX = 'course:'
+
+COURSE_RUN_KEY_PREFIX = 'course-v1:'
+
 
 def json_serialized_course_modes():
     """

enterprise_catalog/apps/catalog/models.py

@@ -26,6 +26,7 @@
 )
 from enterprise_catalog.apps.catalog.constants import (
     ACCESS_TO_ALL_ENTERPRISES_TOKEN,
+    AGGREGATION_KEY_PREFIX,
     CONTENT_COURSE_TYPE_ALLOW_LIST,
     CONTENT_PRODUCT_SOURCE_ALLOW_LIST,
     CONTENT_TYPE_CHOICES,
@@ -34,6 +35,7 @@
     EXEC_ED_2U_COURSE_TYPE,
     EXEC_ED_2U_ENTITLEMENT_MODE,
     PROGRAM,
+    RESTRICTED_RUNS_ALLOWED_KEY,
     json_serialized_course_modes,
 )
 from enterprise_catalog.apps.catalog.utils import (
@@ -116,6 +118,28 @@ def pretty_print_content_filter(self):
         """
         return json.dumps(self.content_filter, indent=4)
 
+    @cached_property
+    def restricted_runs_allowed(self):
+        """
+        Return a dict of restricted course <-> run mappings by
+        course key, e.g.
+        ```
+        "edX+FUN": [
+            "course-v1:edX+FUN+3T2024"
+        ]
+        ```
+        """
+        mapping = self.content_filter.get(RESTRICTED_RUNS_ALLOWED_KEY)  # pylint: disable=no-member
+        if not mapping:
+            return None
+        if not isinstance(mapping, dict):
+            LOGGER.error('%s restricted runs value is not a dict', self)
+            return None
+        return {
+            course_key.removeprefix(AGGREGATION_KEY_PREFIX): course_run_list
+            for course_key, course_run_list in mapping.items()
+        }
+
     @classmethod
     def get_by_uuid(cls, uuid):
         try:
@@ -211,6 +235,10 @@ def content_metadata(self):
             return ContentMetadata.objects.none()
         return self.catalog_query.contentmetadata_set.all()
 
+    @cached_property
+    def restricted_runs_allowed(self):
+        return self.catalog_query.restricted_runs_allowed
+
     @cached_property
     def enterprise_customer(self):
         """

enterprise_catalog/apps/catalog/tests/test_models.py

@@ -17,6 +17,7 @@
     EXEC_ED_2U_COURSE_TYPE,
     EXEC_ED_2U_ENTITLEMENT_MODE,
     PROGRAM,
+    RESTRICTED_RUNS_ALLOWED_KEY,
 )
 from enterprise_catalog.apps.catalog.models import (
     ContentMetadata,
@@ -590,3 +591,68 @@ def test_bulk_update_changes_modified_time(self):
         for record in records:
             record.refresh_from_db()
             self.assertGreater(record.modified, original_modified_time)
+
+    def test_restricted_runs_allowed_happy_path(self):
+        """
+        Test the happy path for computing a CatalogQuery's `restricted_runs_allowed`.
+        """
+        restricted_runs_dict = {
+            "course:edX+FUN": [
+                "course-v1:edX+FUN+3T2024",
+                "course-v1:edX+FUN+4T2024",
+            ],
+            "course:edX+GAMES": [
+                "course-v1:edX+GAMES+3T2024",
+                "course-v1:edX+GAMES+4T2024",
+            ]
+        }
+        content_filter = {
+            'other': 'stuff',
+            RESTRICTED_RUNS_ALLOWED_KEY: restricted_runs_dict
+        }
+        catalog_query = factories.CatalogQueryFactory(content_filter=content_filter)
+        catalog = factories.EnterpriseCatalogFactory(
+            catalog_query=catalog_query,
+        )
+
+        expected_restricted_runs_dict = {
+            "edX+FUN": [
+                "course-v1:edX+FUN+3T2024",
+                "course-v1:edX+FUN+4T2024",
+            ],
+            "edX+GAMES": [
+                "course-v1:edX+GAMES+3T2024",
+                "course-v1:edX+GAMES+4T2024",
+            ]
+        }
+        self.assertEqual(
+            expected_restricted_runs_dict,
+            catalog_query.restricted_runs_allowed,
+        )
+        self.assertEqual(
+            expected_restricted_runs_dict,
+            catalog.restricted_runs_allowed,
+        )
+
+    @ddt.data(
+        ['some+course+run'],
+        'some+course+run',
+        {},
+        [],
+        '',
+    )
+    def test_restricted_runs_are_none(self, restricted_runs_dict):
+        """
+        Tests all the cases that should result in a restricted_runs_allowed of None.
+        """
+        content_filter = {
+            'other': 'stuff',
+            RESTRICTED_RUNS_ALLOWED_KEY: restricted_runs_dict
+        }
+        catalog_query = factories.CatalogQueryFactory(content_filter=content_filter)
+        catalog = factories.EnterpriseCatalogFactory(
+            catalog_query=catalog_query,
+        )
+
+        self.assertIsNone(catalog_query.restricted_runs_allowed)
+        self.assertIsNone(catalog.restricted_runs_allowed)