feat: update content libraries API to use upstream collection events

bradenmacdonald · bradenmacdonald · commit 999c392800e8 · 2026-04-20T20:19:17.000-07:00
diff --git a/openedx/core/djangoapps/content_libraries/signal_handlers.py b/openedx/core/djangoapps/content_libraries/signal_handlers.py
@@ -4,179 +4,74 @@
 
 import logging
 
-from django.db.models.signals import m2m_changed, post_delete, post_save
 from django.dispatch import receiver
-from opaque_keys import OpaqueKey
-from opaque_keys.edx.locator import LibraryLocatorV2
-from openedx_content.api import get_components, get_containers
-from openedx_content.models_api import Collection, CollectionPublishableEntity, PublishableEntity
-from openedx_events.content_authoring.data import ContentObjectChangedData, LibraryCollectionData
+from openedx_content.api import signals as content_signals
+from openedx_events.content_authoring.data import LibraryCollectionData
 from openedx_events.content_authoring.signals import (
-    CONTENT_OBJECT_ASSOCIATIONS_CHANGED,
     LIBRARY_COLLECTION_CREATED,
     LIBRARY_COLLECTION_DELETED,
     LIBRARY_COLLECTION_UPDATED,
 )
 
-from .api import library_collection_locator, library_component_usage_key, library_container_locator
+from . import tasks
+from .api import library_collection_locator
 from .models import ContentLibrary
 
 log = logging.getLogger(__name__)
 
 
-@receiver(post_save, sender=Collection, dispatch_uid="library_collection_saved")
-def library_collection_saved(sender, instance, created, **kwargs):
+@receiver(content_signals.LEARNING_PACKAGE_COLLECTION_CHANGED)
+def collection_updated(
+    learning_package: content_signals.LearningPackageEventData,
+    change: content_signals.CollectionChangeData,
+    **kwargs,
+):
     """
-    Raises LIBRARY_COLLECTION_CREATED if the Collection is new,
-    or LIBRARY_COLLECTION_UPDATED if updated an existing Collection.
+    A Collection has been updated - handle that as needed.
+
+    We receive this low-level event from `openedx_content`, and check if it
+    happened in a library. If so, we emit more detailed library-specific events.
+
+    ⏳ This event is emitted synchronously and this handler is called
+       synchronously. If a lot of entities were changed, we need to dispatch an
+       asynchronous handler to deal with them to avoid slowdowns.
     """
     try:
-        library = ContentLibrary.objects.get(learning_package_id=instance.learning_package_id)
+        library = ContentLibrary.objects.get(learning_package_id=learning_package.id)
     except ContentLibrary.DoesNotExist:
-        log.error("{instance} is not associated with a content library.")
-        return
+        return  # We don't care about non-library events.
+
+    collection_key = library_collection_locator(library_key=library.library_key, collection_key=change.collection_code)
+    entities_changed = change.entities_added + change.entities_removed
 
-    if created:
+    if change.created:  # This is a newly-created collection, or was "un-deleted":
         # .. event_implemented_name: LIBRARY_COLLECTION_CREATED
         # .. event_type: org.openedx.content_authoring.content_library.collection.created.v1
-        LIBRARY_COLLECTION_CREATED.send_event(
-            library_collection=LibraryCollectionData(
-                collection_key=library_collection_locator(
-                    library_key=library.library_key,
-                    collection_key=instance.key,
-                ),
-            )
-        )
-    else:
+        LIBRARY_COLLECTION_CREATED.send_event(library_collection=LibraryCollectionData(collection_key=collection_key))
+        # As an example of what this event triggers,  Collections are listed in the Meilisearch index as items in the
+        # library. So the handler will add this Collection as an entry in the Meilisearch index.
+    elif change.metadata_modified or entities_changed:
+        # The collection was renamed or its items were changed.
+        # This event is ambiguous but because the search index of the colleciton itself may have something like
+        # "contains 15 items", we _do_ need to emit it even when only the items have changed and not the metadata.
         # .. event_implemented_name: LIBRARY_COLLECTION_UPDATED
         # .. event_type: org.openedx.content_authoring.content_library.collection.updated.v1
-        LIBRARY_COLLECTION_UPDATED.send_event(
-            library_collection=LibraryCollectionData(
-                collection_key=library_collection_locator(
-                    library_key=library.library_key,
-                    collection_key=instance.key,
-                ),
-            )
-        )
-
-
-@receiver(post_delete, sender=Collection, dispatch_uid="library_collection_deleted")
-def library_collection_deleted(sender, instance, **kwargs):
-    """
-    Raises LIBRARY_COLLECTION_DELETED for the deleted Collection.
-    """
-    try:
-        library = ContentLibrary.objects.get(learning_package_id=instance.learning_package_id)
-    except ContentLibrary.DoesNotExist:
-        log.error("{instance} is not associated with a content library.")
-        return
-
-    # .. event_implemented_name: LIBRARY_COLLECTION_DELETED
-    # .. event_type: org.openedx.content_authoring.content_library.collection.deleted.v1
-    LIBRARY_COLLECTION_DELETED.send_event(
-        library_collection=LibraryCollectionData(
-            collection_key=library_collection_locator(
-                library_key=library.library_key,
-                collection_key=instance.key,
-            ),
-        )
-    )
-
-
-def _library_collection_entity_changed(
-    publishable_entity: PublishableEntity,
-    library_key: LibraryLocatorV2 | None = None,
-) -> None:
-    """
-    Sends a CONTENT_OBJECT_ASSOCIATIONS_CHANGED event for the entity.
-    """
-    if not library_key:
-        try:
-            library = ContentLibrary.objects.get(
-                learning_package_id=publishable_entity.learning_package_id,
-            )
-        except ContentLibrary.DoesNotExist:
-            log.error("{publishable_entity} is not associated with a content library.")
-            return
-
-        library_key = library.library_key
-
-    assert library_key
-
-    opaque_key: OpaqueKey
-
-    if hasattr(publishable_entity, 'component'):
-        opaque_key = library_component_usage_key(
-            library_key,
-            publishable_entity.component,
+        LIBRARY_COLLECTION_UPDATED.send_event(library_collection=LibraryCollectionData(collection_key=collection_key))
+    elif change.deleted:
+        # .. event_implemented_name: LIBRARY_COLLECTION_DELETED
+        # .. event_type: org.openedx.content_authoring.content_library.collection.deleted.v1
+        LIBRARY_COLLECTION_DELETED.send_event(library_collection=LibraryCollectionData(collection_key=collection_key))
+
+    # Now, what about the actual entities (containers/components) in the collection?
+    if entities_changed:
+        if len(entities_changed) == 1:
+            # If there's only one changed entity, emit the event synchronously:
+            fn = tasks.send_collections_changed_events
+        else:
+            # If there are more than one changed entities, emit the events asynchronously:
+            fn = tasks.send_collections_changed_events.delay
+        fn(
+            publishable_entity_ids=entities_changed,
+            learning_package_id=learning_package.id,
+            library_key_str=str(library.library_key),
         )
-    elif hasattr(publishable_entity, 'container'):
-        opaque_key = library_container_locator(
-            library_key,
-            publishable_entity.container,
-        )
-    else:
-        log.error("Unknown publishable entity type: %s", publishable_entity)
-        return
-
-    # .. event_implemented_name: CONTENT_OBJECT_ASSOCIATIONS_CHANGED
-    # .. event_type: org.openedx.content_authoring.content.object.associations.changed.v1
-    CONTENT_OBJECT_ASSOCIATIONS_CHANGED.send_event(
-        content_object=ContentObjectChangedData(
-            object_id=str(opaque_key),
-            changes=["collections"],
-        ),
-    )
-
-
-@receiver(post_save, sender=CollectionPublishableEntity, dispatch_uid="library_collection_entity_saved")
-def library_collection_entity_saved(sender, instance, created, **kwargs):
-    """
-    Sends a CONTENT_OBJECT_ASSOCIATIONS_CHANGED event for components added to a collection.
-    """
-    if created:
-        _library_collection_entity_changed(instance.entity)
-
-
-@receiver(post_delete, sender=CollectionPublishableEntity, dispatch_uid="library_collection_entity_deleted")
-def library_collection_entity_deleted(sender, instance, **kwargs):
-    """
-    Sends a CONTENT_OBJECT_ASSOCIATIONS_CHANGED event for components removed from a collection.
-    """
-    # Only trigger component updates if CollectionPublishableEntity was cascade deleted due to deletion of a collection.
-    if isinstance(kwargs.get('origin'), Collection):
-        _library_collection_entity_changed(instance.entity)
-
-
-@receiver(m2m_changed, sender=CollectionPublishableEntity, dispatch_uid="library_collection_entities_changed")
-def library_collection_entities_changed(sender, instance, action, pk_set, **kwargs):
-    """
-    Sends a CONTENT_OBJECT_ASSOCIATIONS_CHANGED event for components added/removed/cleared from a collection.
-    """
-    if action not in ["post_add", "post_remove", "post_clear"]:
-        return
-
-    try:
-        library = ContentLibrary.objects.get(
-            learning_package_id=instance.learning_package_id,
-        )
-    except ContentLibrary.DoesNotExist:
-        log.error("{instance} is not associated with a content library.")
-        return
-
-    if isinstance(instance, PublishableEntity):
-        _library_collection_entity_changed(instance, library.library_key)
-        return
-
-    # When action=="post_clear", pk_set==None
-    # Since the collection instance now has an empty entities set,
-    # we don't know which ones were removed, so we need to update associations for all library
-    # components and containers.
-    components = get_components(instance.learning_package_id)
-    containers = get_containers(instance.learning_package_id)
-    if pk_set:
-        components = components.filter(pk__in=pk_set)
-        containers = containers.filter(pk__in=pk_set)
-
-    for entity in list(components.all()) + list(containers.all()):
-        _library_collection_entity_changed(entity.publishable_entity, library.library_key)
diff --git a/openedx/core/djangoapps/content_libraries/tasks.py b/openedx/core/djangoapps/content_libraries/tasks.py
@@ -14,6 +14,7 @@
     A longer-term solution to this issue would be to move the content_libraries app to cms:
     https://github.com/openedx/edx-platform/issues/33428
 """
+
 from __future__ import annotations
 
 import json
@@ -38,6 +39,7 @@
     set_code_owner_attribute_from_module,
     set_custom_attribute,
 )
+from opaque_keys import OpaqueKey
 from opaque_keys.edx.locator import (
     BlockUsageLocator,
     LibraryCollectionLocator,
@@ -46,9 +48,15 @@
 )
 from openedx_content import api as content_api
 from openedx_content.api import create_zip_file as create_lib_zip_file
-from openedx_content.models_api import DraftChangeLog, PublishLog
-from openedx_events.content_authoring.data import LibraryBlockData, LibraryCollectionData, LibraryContainerData
+from openedx_content.models_api import DraftChangeLog, LearningPackage, PublishableEntity, PublishLog
+from openedx_events.content_authoring.data import (
+    ContentObjectChangedData,
+    LibraryBlockData,
+    LibraryCollectionData,
+    LibraryContainerData,
+)
 from openedx_events.content_authoring.signals import (
+    CONTENT_OBJECT_ASSOCIATIONS_CHANGED,
     LIBRARY_BLOCK_CREATED,
     LIBRARY_BLOCK_DELETED,
     LIBRARY_BLOCK_PUBLISHED,
@@ -83,6 +91,48 @@
 DATETIME_FORMAT = '%Y-%m-%dT%H:%M:%SZ'  # Should match serializer format. Redefined to avoid circular import.
 
 
+@shared_task(base=LoggedTask)
+@set_code_owner_attribute
+def send_collections_changed_events(
+    publishable_entity_ids: list[PublishableEntity.ID],
+    learning_package_id: LearningPackage.ID,
+    library_key_str: str,
+):
+    """
+    Sends a CONTENT_OBJECT_ASSOCIATIONS_CHANGED event for each modified library
+    entity in the given list, because their associated collections have changed.
+
+    ⏳ This task is designed to be run asynchronously so it can handle many
+       entities, but you can also call it synchronously if you are only
+       processing a single entity. Handlers should be synchronous and fast, to
+       support the "update one item synchronously" use case, but can be async if
+       needed.
+    """
+    library_key = LibraryLocatorV2.from_string(library_key_str)
+    entities = (
+        content_api.get_publishable_entities(learning_package_id)
+        .filter(id__in=publishable_entity_ids)
+        .select_related("component", "container")
+    )
+
+    for entity in entities:
+        opaque_key: OpaqueKey
+
+        if hasattr(entity, "component"):
+            opaque_key = api.library_component_usage_key(library_key, entity.component)
+        elif hasattr(entity, "container"):
+            opaque_key = api.library_container_locator(library_key, entity.container)
+        else:
+            log.error("Unknown publishable entity type: %s", entity)
+            continue
+
+        # .. event_implemented_name: CONTENT_OBJECT_ASSOCIATIONS_CHANGED
+        # .. event_type: org.openedx.content_authoring.content.object.associations.changed.v1
+        CONTENT_OBJECT_ASSOCIATIONS_CHANGED.send_event(
+            content_object=ContentObjectChangedData(object_id=str(opaque_key), changes=["collections"]),
+        )
+
+
 @shared_task(base=LoggedTask)
 @set_code_owner_attribute
 def send_events_after_publish(publish_log_pk: int, library_key_str: str) -> None:
diff --git a/openedx/core/djangoapps/content_libraries/tests/test_api.py b/openedx/core/djangoapps/content_libraries/tests/test_api.py
@@ -30,6 +30,8 @@
     LIBRARY_CONTAINER_DELETED,
     LIBRARY_CONTAINER_UPDATED,
 )
+from openedx_events.testing import EventsIsolationMixin
+from openedx_events.tooling import OpenEdxPublicSignal
 from user_tasks.models import UserTaskStatus
 
 from common.djangoapps.student.tests.factories import UserFactory
@@ -39,13 +41,21 @@
 from .base import ContentLibrariesRestApiTest
 
 
-class ContentLibraryCollectionsTest(ContentLibrariesRestApiTest):
+class ContentLibraryCollectionsTest(ContentLibrariesRestApiTest, EventsIsolationMixin):
     """
     Tests for Content Library API collections methods.
 
     Same guidelines as ContentLibrariesTestCase.
     """
 
+    @classmethod
+    def setUpClass(cls):
+        """Test setup"""
+        super().setUpClass()
+        # By default, errors thrown in signal handlers get suppressed. We want to see them though!
+        # https://github.com/openedx/openedx-events/issues/569
+        cls.allow_send_events_failure(*(s.event_type for s in OpenEdxPublicSignal.all_events()))
+
     def setUp(self) -> None:
         super().setUp()
 
