diff --git a/cms/djangoapps/contentstore/rest_api/v2/authoring_urls.py b/cms/djangoapps/contentstore/rest_api/v2/authoring_urls.py index 1c0d693dec4f..336da798fa94 100644 --- a/cms/djangoapps/contentstore/rest_api/v2/authoring_urls.py +++ b/cms/djangoapps/contentstore/rest_api/v2/authoring_urls.py @@ -1,10 +1,14 @@ """Contentstore API v2 authoring URLs.""" -from django.urls import path +from django.urls import path, register_converter +from edx_rest_framework_extensions.url_converters import UsageKeyConverter +from cms.djangoapps.contentstore.rest_api.v2.views.container_children import CourseContainerChildrenViewSet from cms.djangoapps.contentstore.rest_api.v2.views.textbooks import CourseTextbooksViewSet from cms.djangoapps.contentstore.rest_api.v2.views.video_settings import CourseVideoSettingsViewSet +register_converter(UsageKeyConverter, "usage_key") + app_name = "authoring_v2" urlpatterns = [ @@ -18,4 +22,9 @@ CourseVideoSettingsViewSet.as_view({"get": "retrieve"}), name="course_video_settings", ), + path( + "containers//children/", + CourseContainerChildrenViewSet.as_view({"get": "list"}), + name="container_child_list", + ), ] diff --git a/cms/djangoapps/contentstore/rest_api/v2/container_children_service.py b/cms/djangoapps/contentstore/rest_api/v2/container_children_service.py new file mode 100644 index 000000000000..03f7f0e0fe37 --- /dev/null +++ b/cms/djangoapps/contentstore/rest_api/v2/container_children_service.py @@ -0,0 +1,130 @@ +"""Service layer for the v2 container children endpoint.""" + +import logging + +from rest_framework.exceptions import NotFound + +from cms.djangoapps.contentstore.helpers import xblock_studio_url, xblock_type_display_name +from cms.djangoapps.contentstore.utils import ( + get_user_partition_info, + get_visibility_partition_info, + get_xblock_render_error, + get_xblock_validation_messages, +) +from cms.lib.xblock.upstream_sync import UpstreamLink +from openedx.core.djangoapps.content_tagging.toggles import is_tagging_feature_disabled +from xmodule.modulestore.django import modulestore # pylint: disable=wrong-import-order +from xmodule.modulestore.exceptions import ItemNotFoundError # pylint: disable=wrong-import-order + +log = logging.getLogger(__name__) + +CONTAINER_NOT_FOUND_MESSAGE = "No container in this course has this key." +RENDER_ERROR_MESSAGE = "This block could not be rendered. The cause is in the server log." + + +def _load_container(store, usage_key): + """ + Return the container ``usage_key`` names, with its children loaded, or raise ``NotFound``. + + A container is a block that can hold children and is not the course + itself. The course's own children are served by the course outline. + """ + try: + block = store.get_item(usage_key, depth=1) + except ItemNotFoundError as error: + log.info("Children of %s requested, which does not exist: %s", usage_key, error) + raise NotFound(CONTAINER_NOT_FOUND_MESSAGE) from error + if not block.has_children or block.category == "course": + log.info("Children of %s requested, which is a %s.", usage_key, block.category) + raise NotFound(CONTAINER_NOT_FOUND_MESSAGE) + return block + + +def _summary(child): + """The short description of a child.""" + return { + "id": str(child.location), + "category": child.category, + "display_name": child.display_name_with_default, + "display_type": xblock_type_display_name(child), + "has_children": child.has_children, + } + + +def _actions(container, child, can_manage_tags): + """What the Studio unit page lets an author do with ``child``.""" + is_course = child.scope_ids.usage_id.context_key.is_course + # A child that holds children and has no page of its own is edited inline, + # where copying, moving and the other whole-block actions do not apply. + show_inline = child.has_children and not xblock_studio_url(child, parent_xblock=container) + show_other_action = not show_inline and is_course + return { + "can_copy": show_other_action, + "can_duplicate": show_other_action, + "can_move": show_other_action, + "can_manage_access": show_other_action, + "can_delete": is_course, + "can_manage_tags": can_manage_tags, + } + + +def _render_error(request, child): + """ + The message to show for a child that fails to render, or an empty string. + + The cause comes from the block's own code and may expose internals, so it + is logged with the child's key rather than returned. + """ + cause = get_xblock_render_error(request, child) + if not cause: + return "" + log.warning("Rendering %s for the children list failed: %s", child.location, cause) + return RENDER_ERROR_MESSAGE + + +def _detail(request, container, child, course, can_manage_tags): + """Everything the Studio unit page shows about ``child``.""" + upstream_link = UpstreamLink.try_get_for_block(child, log_error=False) + return { + "name": child.display_name_with_default, + "block_id": str(child.location), + "block_type": child.location.block_type, + "user_partition_info": get_visibility_partition_info(child, course=course), + "user_partitions": get_user_partition_info(child, course=course), + # A block with no upstream is by far the commonest case, so it is + # null rather than a record of empty fields. + "upstream_link": upstream_link.to_json(include_child_info=True) if upstream_link.upstream_ref else None, + "actions": _actions(container, child, can_manage_tags), + "validation_messages": get_xblock_validation_messages(child), + "render_error": _render_error(request, child), + } + + +def list_container_children(request, usage_key, full, paginate): + """ + Return the children of the container ``usage_key`` names, in the order the container stores them. + + ``paginate(children, build_page)`` receives every loadable child and a + function that describes one page of them; it returns the response. The + children that make up the answer are the ones that can be loaded, so a + dangling reference in the container is left out, and the fields that are + costly to work out (partitions, upstream link, validation, rendering) are + worked out for the requested page only. ``full`` selects them. + + Raises ``NotFound`` when no block has the key or the block is not a + container. Nothing is written. + """ + store = modulestore() + with store.bulk_operations(usage_key.course_key): + container = _load_container(store, usage_key) + children = container.get_children() + if not full: + return paginate(children, lambda page: [_summary(child) for child in page]) + # Loaded once and shared by every child, as the partitions are + # defined on the course. + course = store.get_course(usage_key.course_key) + can_manage_tags = not is_tagging_feature_disabled() + return paginate( + children, + lambda page: [_detail(request, container, child, course, can_manage_tags) for child in page], + ) diff --git a/cms/djangoapps/contentstore/rest_api/v2/permissions.py b/cms/djangoapps/contentstore/rest_api/v2/permissions.py new file mode 100644 index 000000000000..6f42297ce04f --- /dev/null +++ b/cms/djangoapps/contentstore/rest_api/v2/permissions.py @@ -0,0 +1,43 @@ +"""Permissions for the v2 authoring API.""" + +from opaque_keys.edx.locator import CourseLocator +from rest_framework.exceptions import NotFound +from rest_framework.permissions import BasePermission + +from openedx.core.djangoapps.authz.constants import LegacyAuthoringPermission +from openedx.core.djangoapps.authz.decorators import user_has_course_permission +from openedx.core.djangoapps.content.course_overviews.models import CourseOverview + +try: + from openedx_authz.constants.permissions import COURSES_VIEW_COURSE +except ImportError: + COURSES_VIEW_COURSE = None + +COURSE_NOT_FOUND_MESSAGE = "The requested course does not exist." + + +class CanViewCourse(BasePermission): + """ + Allow callers who may view the course in Studio. + + Reads the parsed ``course_key`` or ``usage_key`` URL argument. + Must follow ``IsAuthenticated`` in ``permission_classes``. + """ + + def has_permission(self, request, view): + course_key = view.kwargs.get("course_key") + if course_key is None: + usage_key = view.kwargs.get("usage_key") + if usage_key is None: + return False + course_key = usage_key.context_key + if not isinstance(course_key, CourseLocator): + raise NotFound(COURSE_NOT_FOUND_MESSAGE) + if course_key.org is None or not CourseOverview.course_exists(course_key): + raise NotFound(COURSE_NOT_FOUND_MESSAGE) + return user_has_course_permission( + request.user, + COURSES_VIEW_COURSE.identifier if COURSES_VIEW_COURSE else "courses.view_course", + course_key, + LegacyAuthoringPermission.READ, + ) diff --git a/cms/djangoapps/contentstore/rest_api/v2/serializers/container_children.py b/cms/djangoapps/contentstore/rest_api/v2/serializers/container_children.py new file mode 100644 index 000000000000..77d6df77fc59 --- /dev/null +++ b/cms/djangoapps/contentstore/rest_api/v2/serializers/container_children.py @@ -0,0 +1,170 @@ +"""Serializers for the children of a course container.""" + +from rest_framework import serializers + +CONTAINER_MINIMAL_VIEW = "minimal" +CONTAINER_FULL_VIEW = "full" + + +class CourseContainerChildSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A block placed directly in a container, as listed by default.""" + + id = serializers.CharField(help_text="Usage key of the block.") + category = serializers.CharField( + help_text="Block type, such as html, problem, video, vertical (unit) or split_test.", + ) + display_name = serializers.CharField(help_text="Name of the block shown to authors.") + display_type = serializers.CharField( + allow_null=True, + help_text=( + "Name of the block's type shown to authors, such as Unit, Problem or Text. Null for a block type " + "that declares no display name." + ), + ) + has_children = serializers.BooleanField( + help_text="Whether the block can hold children, as a unit or a split test does.", + ) + + class Meta: + ref_name = "CourseContainerChild" + + +class CourseContainerChildMessageSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A problem the block reports with its own settings.""" + + text = serializers.CharField(help_text="What is wrong, written for the author.") + type = serializers.CharField(help_text="Severity: warning or error.") + + class Meta: + ref_name = "CourseContainerChildMessage" + + +class CourseContainerChildActionsSerializer(serializers.Serializer): # pylint: disable=abstract-method + """What an author can do with a block placed in a container.""" + + can_copy = serializers.BooleanField(help_text="Whether the block can be copied to the clipboard.") + can_duplicate = serializers.BooleanField(help_text="Whether the block can be duplicated in place.") + can_move = serializers.BooleanField(help_text="Whether the block can be moved to another container.") + can_manage_access = serializers.BooleanField( + help_text="Whether the block's access restrictions can be edited.", + ) + can_delete = serializers.BooleanField(help_text="Whether the block can be deleted.") + can_manage_tags = serializers.BooleanField( + help_text="Whether the block can be tagged. False when tagging is turned off.", + ) + + class Meta: + ref_name = "CourseContainerChildActions" + + +class CourseContainerChildUpstreamChildSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A block inside a linked container that can be synced from its own upstream block.""" + + id = serializers.CharField(help_text="Usage key of the block in the course.") + name = serializers.CharField(allow_null=True, help_text="Name of the block. Null when it has none set.") + upstream = serializers.CharField(allow_null=True, help_text="Key of the library block the block is linked to.") + + class Meta: + ref_name = "CourseContainerChildUpstreamChild" + + +class CourseContainerChildUpstreamLinkSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A block's link to the library block it was created from, and whether the library has moved on.""" + + upstream_ref = serializers.CharField(help_text="Key of the library block or container the block is linked to.") + version_synced = serializers.IntegerField( + allow_null=True, + help_text="Version of the library content the block holds. Null when the link records none.", + ) + version_available = serializers.IntegerField( + allow_null=True, + help_text="Latest published version of the library content. Null when it cannot be determined.", + ) + version_declined = serializers.IntegerField( + allow_null=True, + help_text="Version an author chose not to sync, if any.", + ) + error_message = serializers.CharField( + allow_null=True, + help_text="Why the link cannot be followed, such as a library that no longer exists. Null for a working link.", + ) + ready_to_sync = serializers.BooleanField( + help_text="Whether a newer version is available and can be synced into the block.", + ) + downstream_customized = serializers.ListField( + child=serializers.CharField(), + help_text="Names of the fields the author has changed in the course, which a sync would overwrite.", + ) + top_level_parent_key = serializers.CharField( + allow_null=True, + help_text=( + "Usage key of the top-level linked container this block belongs to, when it was added with one. " + "Null otherwise." + ), + ) + ready_to_sync_children = CourseContainerChildUpstreamChildSerializer( + many=True, + required=False, + help_text=( + "The blocks inside a linked container that have a newer version available. Present only when the " + "block is linked to a library container." + ), + ) + + class Meta: + ref_name = "CourseContainerChildUpstreamLink" + + +class CourseContainerChildFullSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A block placed directly in a container, with everything the Studio unit page shows for it.""" + + name = serializers.CharField(help_text="Name of the block shown to authors.") + block_id = serializers.CharField(help_text="Usage key of the block.") + block_type = serializers.CharField(help_text="Block type, such as html, problem, video or split_test.") + user_partition_info = serializers.DictField( + help_text=( + "The groups the block's visibility can be restricted to: selectable_partitions, " + "selected_partition_index (-1 when unrestricted) and selected_groups_label." + ), + ) + user_partitions = serializers.ListField( + child=serializers.DictField(), + help_text="The course's content groups and enrollment tracks, and which of their groups the block uses.", + ) + upstream_link = CourseContainerChildUpstreamLinkSerializer( + allow_null=True, + help_text="The block's link to a library block. Null when the block is not linked to one.", + ) + actions = CourseContainerChildActionsSerializer(help_text="What the requesting user's Studio lets them do.") + validation_messages = CourseContainerChildMessageSerializer( + many=True, + help_text="Problems the block reports with its own settings. Empty when there are none.", + ) + render_error = serializers.CharField( + allow_blank=True, + help_text=( + "A fixed message when the block fails to render in Studio, empty when it renders. The cause is " + "recorded in the server log, not returned." + ), + ) + + class Meta: + ref_name = "CourseContainerChildFull" + + +class CourseContainerChildQuerySerializer(serializers.Serializer): # pylint: disable=abstract-method + """Query parameters of a container children read. A parameter sent with an empty value counts as omitted.""" + + view = serializers.ChoiceField( + choices=[CONTAINER_MINIMAL_VIEW, CONTAINER_FULL_VIEW], + default=CONTAINER_MINIMAL_VIEW, + error_messages={"invalid_choice": "Must be minimal or full."}, + help_text=( + "minimal (the default) describes each child briefly. full adds what the Studio unit page shows " + "for each: visibility groups, library link, available actions, validation messages and rendering " + "errors." + ), + ) + + class Meta: + ref_name = "CourseContainerChildQuery" diff --git a/cms/djangoapps/contentstore/rest_api/v2/views/container_children.py b/cms/djangoapps/contentstore/rest_api/v2/views/container_children.py new file mode 100644 index 000000000000..dd5ee4a37aed --- /dev/null +++ b/cms/djangoapps/contentstore/rest_api/v2/views/container_children.py @@ -0,0 +1,237 @@ +"""API views for the children of a course container.""" + +from drf_spectacular.utils import ( + OpenApiExample, + OpenApiParameter, + OpenApiResponse, + PolymorphicProxySerializer, + extend_schema, +) +from edx_rest_framework_extensions.errors import ErrorResponseSerializer +from edx_rest_framework_extensions.mixins import StandardizedErrorMixin +from edx_rest_framework_extensions.paginators import DefaultPagination, IterablePaginationMixin +from edx_rest_framework_extensions.url_converters import UsageKeyConverter +from rest_framework import viewsets +from rest_framework.permissions import IsAuthenticated + +from cms.djangoapps.contentstore.rest_api.v2.container_children_service import list_container_children +from cms.djangoapps.contentstore.rest_api.v2.permissions import CanViewCourse +from cms.djangoapps.contentstore.rest_api.v2.serializers.container_children import ( + CourseContainerChildFullSerializer, + CourseContainerChildQuerySerializer, + CourseContainerChildSerializer, +) + +CONTAINER_MINIMAL_VIEW = "minimal" +CONTAINER_FULL_VIEW = "full" + + +class CourseContainerChildPagination(DefaultPagination): + """ + The standard page envelope, with a schema that describes all seven of its keys. + + ``DefaultPagination`` returns seven keys but inherits a response schema + that documents only four, so generated clients would drop ``num_pages``, + ``current_page`` and ``start``. + + Delete this subclass and use ``DefaultPagination`` directly once + edx-drf-extensions documents all seven keys in + ``DefaultPagination.get_paginated_response_schema``. + """ + + def get_paginated_response_schema(self, schema): + return { + "type": "object", + "required": ["count", "num_pages", "current_page", "start", "next", "previous", "results"], + "properties": { + "count": {"type": "integer", "description": "Total number of children.", "example": 2}, + "num_pages": {"type": "integer", "description": "Total number of pages.", "example": 1}, + "current_page": {"type": "integer", "description": "Number of this page, starting at 1.", "example": 1}, + "start": { + "type": "integer", + "description": "Zero-based index of the first child on this page.", + "example": 0, + }, + "next": { + "type": "string", + "format": "uri", + "nullable": True, + "description": "Address of the next page, or null on the last page.", + "example": None, + }, + "previous": { + "type": "string", + "format": "uri", + "nullable": True, + "description": "Address of the previous page, or null on the first page.", + "example": None, + }, + "results": schema, + }, + } + + +_USAGE_KEY_PARAMETER = OpenApiParameter( + name="usage_key", + description=( + "Usage key of a section, subsection, unit or other container of a course, such as " + "block-v1:edX+DemoX+2026+type@vertical+block@welcome." + ), + location=OpenApiParameter.PATH, + type=str, + pattern=f"^{UsageKeyConverter.regex}$", +) + +_VIEW_PARAMETER = OpenApiParameter( + name="view", + description=str(CourseContainerChildQuerySerializer().fields["view"].help_text or ""), + required=False, + location=OpenApiParameter.QUERY, + type=str, + enum=[CONTAINER_MINIMAL_VIEW, CONTAINER_FULL_VIEW], + default=CONTAINER_MINIMAL_VIEW, +) + +MINIMAL_VIEW_EXAMPLE = OpenApiExample( + "Child", + summary="A child in the default view", + description="A unit holding a split test: the child holds children of its own.", + response_only=True, + status_codes=["200"], + value={ + "id": "block-v1:edX+DemoX+2026+type@split_test+block@experiment", + "category": "split_test", + "display_name": "Experiment", + "display_type": "Content Experiment", + "has_children": True, + }, +) + +FULL_VIEW_EXAMPLE = OpenApiExample( + "Child with unit page data", + summary="A child with view=full", + description="A block linked to a library block that has a newer version.", + response_only=True, + status_codes=["200"], + value={ + "name": "Introduction", + "block_id": "block-v1:edX+DemoX+2026+type@html+block@intro_text", + "block_type": "html", + "user_partition_info": { + "selectable_partitions": [], + "selected_partition_index": -1, + "selected_groups_label": "", + }, + "user_partitions": [ + { + "id": 50, + "name": "Enrollment Track Groups", + "scheme": "enrollment_track", + "groups": [{"id": 1, "name": "Audit", "selected": False, "deleted": False}], + }, + ], + "upstream_link": { + "upstream_ref": "lb:edX:demo_library:html:shared_text", + "version_synced": 1, + "version_available": 2, + "version_declined": None, + "error_message": None, + "ready_to_sync": True, + "downstream_customized": [], + "top_level_parent_key": None, + }, + "actions": { + "can_copy": True, + "can_duplicate": True, + "can_move": True, + "can_manage_access": True, + "can_delete": True, + "can_manage_tags": True, + }, + "validation_messages": [ + {"text": "This component's access settings contradict its parent's access settings.", "type": "error"}, + ], + "render_error": "", + }, +) + +_ITEM_SCHEMA = PolymorphicProxySerializer( + component_name="CourseContainerChildRead", + serializers=[CourseContainerChildSerializer, CourseContainerChildFullSerializer], + resource_type_field_name=None, +) + + +def _error(description): + return OpenApiResponse(response=ErrorResponseSerializer, description=description) + + +@extend_schema(tags=["openedx-platform-sdk"]) +class CourseContainerChildrenViewSet(StandardizedErrorMixin, IterablePaginationMixin, viewsets.ViewSet): + """ + The blocks placed directly in a container of a course, in the order the container stores them. + + One level only: a child that is itself a container is listed as one block, + and its own children are read from its address. Only the children on the + requested page are described in full, so the cost of a request follows the + page size, not the size of the container. + + Callable by anyone who may view the course in Studio. The course is looked + up first, so a signed-in caller learns that a course does not exist (404) + before being refused (403), and only a caller who may view the course + learns whether a block exists in it. Every child is listed for such a + caller, including children hidden from learners. + + A plain ``ViewSet``: the children are read from the modulestore, not from + database rows. Their order is the order of the container, so there is no + ordering parameter. + """ + + permission_classes = (IsAuthenticated, CanViewCourse) + serializer_class = CourseContainerChildSerializer + pagination_class = CourseContainerChildPagination + + def get_serializer(self, *args, **kwargs): + """Instantiate the child serializer declared on this viewset.""" + return self.serializer_class(*args, **kwargs) + + @extend_schema( + summary="List the children of a container", + description=( + "Returns one page of the blocks placed directly in a section, subsection, unit or other container of " + "the course, in the order the container stores them. By default each child is described briefly. " + "With view=full each child carries what the Studio unit page shows for it: the groups it is " + "visible to, its link to a library block, the actions available, its validation messages and " + "whether it renders. The course itself, components that cannot hold children, and blocks that " + "do not exist are not containers and are answered with 404." + ), + parameters=[_USAGE_KEY_PARAMETER, _VIEW_PARAMETER], + responses={ + 200: OpenApiResponse( + response=_ITEM_SCHEMA, + description="A page of the container's children.", + ), + 400: _error("view has an invalid value."), + 401: _error("The requester is not authenticated."), + 403: _error("The requester may not view this course in Studio."), + 404: _error( + "The course does not exist, the key does not name a block of a course, the block is not a " + "container, or the requested page is out of range." + ), + 406: _error("The Accept header admits no JSON media type."), + }, + examples=[MINIMAL_VIEW_EXAMPLE, FULL_VIEW_EXAMPLE], + ) + def list(self, request, usage_key): + """Return one page of the container's children.""" + query = CourseContainerChildQuerySerializer(data=request.query_params) + query.is_valid(raise_exception=True) + full = query.validated_data["view"] == CONTAINER_FULL_VIEW + serializer = CourseContainerChildFullSerializer if full else CourseContainerChildSerializer + + def paginate(children, describe_page): + return self.paginate_iterable( + request, children, serialize=lambda page: serializer(describe_page(page), many=True).data, + ) + + return list_container_children(request, usage_key, full, paginate) diff --git a/cms/djangoapps/contentstore/rest_api/v2/views/tests/helpers.py b/cms/djangoapps/contentstore/rest_api/v2/views/tests/helpers.py index e956150f300d..762cd6867fc0 100644 --- a/cms/djangoapps/contentstore/rest_api/v2/views/tests/helpers.py +++ b/cms/djangoapps/contentstore/rest_api/v2/views/tests/helpers.py @@ -1,16 +1,27 @@ """Shared helpers for the v2 authoring endpoint tests.""" +from contextlib import contextmanager from unittest.mock import patch +import pymongo from crum import signals as crum_signals from django.core import signals as core_signals +from django.db import connection from django.db.models import signals as model_signals +from django.db.models.signals import post_save from django.dispatch import Signal +from django.test.utils import CaptureQueriesContext from drf_spectacular.generators import SchemaGenerator from drf_spectacular.settings import patched_settings +from openedx_authz.models.engine import PolicyCacheControl +from openedx_events.content_authoring.signals import XBLOCK_UPDATED from openedx_events.tooling import OpenEdxPublicSignal from rest_framework.test import APIClient +from xmodule.modulestore.django import SignalHandler, modulestore # pylint: disable=wrong-import-order +from xmodule.modulestore.mixed import MixedModuleStore # pylint: disable=wrong-import-order +from xmodule.modulestore.tests.factories import BlockFactory, CourseFactory # pylint: disable=wrong-import-order + PASSWORD = "test" # The schema settings the CMS publishes its authoring schema with. The test @@ -95,3 +106,114 @@ def resolve_ref(schema, node): if ref is None: return node return schema["components"]["schemas"][ref.rsplit("/", 1)[1]] + + +def build_course(sections=2, subsections=2, units=2, **course_kwargs): + """ + Create a course holding ``sections`` sections of ``subsections`` subsections of + ``units`` units, each unit holding one problem. Return the course as stored. + """ + course = CourseFactory.create(**course_kwargs) + for s in range(sections): + section = BlockFactory.create( + parent_location=course.location, category="chapter", display_name=f"Section {s}", + ).location + for ss in range(subsections): + subsection = BlockFactory.create( + parent_location=section, category="sequential", display_name=f"Subsection {s}.{ss}", + ).location + for u in range(units): + unit = BlockFactory.create( + parent_location=subsection, category="vertical", display_name=f"Unit {s}.{ss}.{u}", + ).location + BlockFactory.create(parent_location=unit, category="problem", display_name=f"Problem {s}.{ss}.{u}") + return modulestore().get_course(course.id) + + +@contextmanager +def count_mongo_calls(): + """Count Mongo reads and writes made inside the block.""" + read_ops = ("find", "find_one", "count_documents", "aggregate") + write_ops = ("insert_one", "insert_many", "replace_one", "update_one", "update_many", "bulk_write", + "delete_one", "delete_many", "find_one_and_update", "find_one_and_replace", "find_one_and_delete") + counts = {"reads": 0, "writes": 0} + + def counting(kind, original): + def wrapper(self, *args, **kwargs): + counts[kind] += 1 + return original(self, *args, **kwargs) + return wrapper + + collection = pymongo.collection.Collection + with patch.multiple(collection, **{ + name: counting("reads" if name in read_ops else "writes", getattr(collection, name)) + for name in read_ops + write_ops + }): + yield counts + + +def sql_writes(queries): + """``(statement, table)`` for each INSERT, UPDATE and DELETE among the captured ``queries``.""" + result = [] + for query in queries.captured_queries: + words = query["sql"].split() + statement = words[0].upper() + if statement in ("INSERT", "DELETE"): + result.append((statement, words[2].strip('"`'))) + elif statement == "UPDATE": + result.append((statement, words[1].strip('"`'))) + return result + + +@contextmanager +def record_effects(test_case): + """ + Record, inside the block, SQL writes, Mongo writes, modulestore updates, + model saves, xblock-updated events and course-published signals. + """ + effects = {"saves": [], "xblock_updated": [], "published": [], "update_item": []} + update_item = MixedModuleStore.update_item + + def spy_update_item(store, xblock, *args, **kwargs): + effects["update_item"].append(str(xblock.location)) + return update_item(store, xblock, *args, **kwargs) + + def on_save(sender, **kwargs): # pylint: disable=unused-argument + effects["saves"].append(sender.__name__) + + def on_xblock_updated(**kwargs): + effects["xblock_updated"].append(str(kwargs["xblock_info"].usage_key)) + + def on_published(sender, **kwargs): # pylint: disable=unused-argument + effects["published"].append(kwargs) + + post_save.connect(on_save, weak=False) + XBLOCK_UPDATED.connect(on_xblock_updated, weak=False) + SignalHandler.course_published.connect(on_published, weak=False) + try: + with test_case.captureOnCommitCallbacks(execute=True), \ + CaptureQueriesContext(connection) as queries, \ + count_mongo_calls() as mongo, \ + patch.object(MixedModuleStore, "update_item", spy_update_item): + yield effects + effects["sql_writes"] = sql_writes(queries) + effects["mongo_writes"] = mongo["writes"] + finally: + post_save.disconnect(on_save) + XBLOCK_UPDATED.disconnect(on_xblock_updated) + SignalHandler.course_published.disconnect(on_published) + + +FIRST_LOOKUP_WRITES = [("INSERT", PolicyCacheControl._meta.db_table)] # pylint: disable=protected-access + + +def as_json_schema(node): + """An OpenAPI 3.0 schema as JSON Schema: ``nullable`` becomes a null alternative.""" + if isinstance(node, list): + return [as_json_schema(item) for item in node] + if not isinstance(node, dict): + return node + converted = {key: as_json_schema(value) for key, value in node.items() if key != "nullable"} + if node.get("nullable"): + return {"anyOf": [converted, {"type": "null"}]} + return converted diff --git a/cms/djangoapps/contentstore/rest_api/v2/views/tests/test_container_children.py b/cms/djangoapps/contentstore/rest_api/v2/views/tests/test_container_children.py new file mode 100644 index 000000000000..8a1b472ed35a --- /dev/null +++ b/cms/djangoapps/contentstore/rest_api/v2/views/tests/test_container_children.py @@ -0,0 +1,1497 @@ +"""Tests for the v2 container children API.""" + +import logging +import re +from collections import Counter +from functools import cache +from importlib import import_module +from unittest.mock import patch + +import ddt +import jsonschema +import pytest +from django.db import connection +from django.db.models.signals import post_save, pre_save +from django.test.signals import template_rendered +from django.test.utils import CaptureQueriesContext +from django.urls import Resolver404, resolve, reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from edx_toggles.toggles.testutils import override_waffle_flag +from opaque_keys.edx.keys import UsageKey +from openedx_authz.constants.roles import ( + COURSE_ADMIN, + COURSE_AUDITOR, + COURSE_BETA_TESTER, + COURSE_DATA_RESEARCHER, + COURSE_EDITOR, + COURSE_LIMITED_STAFF, + COURSE_STAFF, +) +from openedx_authz.models.engine import PolicyCacheControl +from rest_framework.test import APIClient +from xblock.core import XBlock + +from cms.djangoapps.contentstore.rest_api.v1.views.tests.test_vertical_block import BaseXBlockContainer +from cms.djangoapps.contentstore.rest_api.v2.container_children_service import RENDER_ERROR_MESSAGE +from cms.djangoapps.contentstore.rest_api.v2.views.tests.helpers import ( + FIRST_LOOKUP_WRITES, + PASSWORD, + SignalRecorder, + as_json_schema, + build_course, + count_mongo_calls, + generate_cms_schema, + logged_in_client, + record_effects, +) +from cms.djangoapps.contentstore.tests.utils import routed_actions +from common.djangoapps.student.models import CourseAccessRole, CourseEnrollment +from common.djangoapps.student.roles import ( + CourseInstructorRole, + CourseLimitedStaffRole, + CourseStaffRole, + OrgInstructorRole, + OrgStaffRole, +) +from common.djangoapps.student.tests.factories import UserFactory +from openedx.core.djangoapps.authz.tests.mixins import CourseAuthoringAuthzTestMixin +from openedx.core.djangoapps.content.course_overviews.models import CourseOverview +from openedx.core.djangoapps.content_tagging.toggles import DISABLE_TAGGING_FEATURE +from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user +from openedx.core.djangoapps.oauth_dispatch.tests.factories import AccessTokenFactory, ApplicationFactory +from xmodule.modulestore.django import modulestore # pylint: disable=wrong-import-order +from xmodule.modulestore.tests.django_utils import ModuleStoreTestCase, SharedModuleStoreTestCase # pylint: disable=wrong-import-order +from xmodule.modulestore.tests.factories import BlockFactory # pylint: disable=wrong-import-order +from xmodule.partitions.partitions import Group, UserPartition # pylint: disable=wrong-import-order + +UNKNOWN_COURSE_UNIT = "block-v1:NoSuchOrg+NoSuchCourse+NoSuchRun+type@vertical+block@unit" +VERSION_GUID = "0123456789abcdef01234567" +LIBRARY_KEYS = ( + "lb:Org:lib:problem:1", # a block of a content library + "lib-block-v1:Org+Lib+type@problem+block@x", # a block of a legacy library + f"lib-block-v1:version@{VERSION_GUID}+type@problem+block@x", # a legacy library key naming only a version +) +COURSE_NOT_FOUND = "The requested course does not exist." +CONTAINER_NOT_FOUND = "No container in this course has this key." +INVALID_VIEW = "Must be minimal or full." +VIEWS = ("default", "full") +ENVELOPE_KEYS = {"count", "next", "previous", "num_pages", "current_page", "start", "results"} +SUMMARY_KEYS = {"id", "category", "display_name", "display_type", "has_children"} +DETAIL_KEYS = { + "name", "block_id", "block_type", "user_partition_info", "user_partitions", "upstream_link", "actions", + "validation_messages", "render_error", +} + +PAGE = "PaginatedCourseContainerChildReadList" +SUMMARY_SHAPE = "CourseContainerChild" +DETAIL_SHAPE = "CourseContainerChildFull" +ITEM_SHAPE = "CourseContainerChildRead" + + +def children_url(usage_key): + """Return the address of the children of the container ``usage_key``.""" + return reverse("authoring_v2:container_child_list", kwargs={"usage_key": usage_key}) + + +def v1_url(usage_key): + """Return the deprecated address of the children of ``usage_key``.""" + return reverse("cms.djangoapps.contentstore:v1:container_children", kwargs={"usage_key_string": str(usage_key)}) + + +def _client(user=None): + """An API client that returns server errors as responses, authenticated as ``user`` if given.""" + client = APIClient() + client.raise_request_exception = False + if user is not None: + client.force_authenticate(user=user) + return client + + +def _session_client(user): + """A client signed in to a browser session as ``user``.""" + user.set_password(PASSWORD) + user.save() + return logged_in_client(user) + + +def _params(view): + return {"view": "full"} if view == "full" else {} + + +def units_of(course_key): + """Every unit of the course, in course order.""" + course = modulestore().get_course(course_key) + return [ + unit + for section in course.get_children() + for subsection in section.get_children() + for unit in subsection.get_children() + ] + + +def _ccx_key(usage_key): + """The key of ``usage_key``'s block in custom course (CCX) 1 of its course.""" + run = usage_key.course_key + return UsageKey.from_string( + f"ccx-block-v1:{run.org}+{run.course}+{run.run}+ccx@1+type@{usage_key.block_type}+block@{usage_key.block_id}" + ) + + +def _block(parent, category, display_name, **kwargs): + """Create a block under ``parent`` and return it as stored.""" + location = BlockFactory.create( + parent_location=parent.location, category=category, display_name=display_name, **kwargs, + ).location + return modulestore().get_item(location) + + +def _without_instance(envelope): + """An error envelope without ``instance``, the request path, which holds the key the caller sent.""" + return {name: value for name, value in envelope.items() if name != "instance"} + + +@cache +def _published_schema(): + """The CMS authoring schema, generated once.""" + return generate_cms_schema() + + +@cache +def _published_components(): + """The schema's components as JSON Schema.""" + return as_json_schema(_published_schema()["components"]["schemas"]) + + +def assert_matches_published_schema(body, component): + """Assert ``body`` is valid against the published schema component ``component``.""" + jsonschema.validate( + body, {"$ref": f"#/components/schemas/{component}", "components": {"schemas": _published_components()}}, + ) + + +def assert_matches_one_item_shape(item, shape): + """Assert ``item`` matches the published item type, and of its two shapes exactly ``shape``.""" + assert_matches_published_schema(item, ITEM_SHAPE) + assert_matches_published_schema(item, shape) + other = DETAIL_SHAPE if shape == SUMMARY_SHAPE else SUMMARY_SHAPE + with pytest.raises(jsonschema.ValidationError): + assert_matches_published_schema(item, other) + + +def assert_page(body, view): + """Assert ``body`` is a page as published, each of its results of the shape ``view`` selects.""" + assert set(body) == ENVELOPE_KEYS + assert_matches_published_schema(body, PAGE) + for item in body["results"]: + assert_matches_one_item_shape(item, DETAIL_SHAPE if view == "full" else SUMMARY_SHAPE) + + +# --------------------------------------------------------------------------- +# Who may call the endpoint +# --------------------------------------------------------------------------- + +def assert_inactive_jwt_reads(user, usage_key, view): + """Deactivate ``user``; assert a JWT for it reads the children.""" + user.is_active = False + user.save() + header = {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(user)}"} + response = APIClient().get(children_url(usage_key), _params(view), **header) + assert response.status_code == 200, response.content + assert_page(response.json(), view) + user.refresh_from_db() + assert user.is_active is False + + +class _AccessMatrixMixin: + """Checks a caller's status on both views, on GET and HEAD, against the expected one.""" + + def assert_access(self, user, view, expected, usage_key=None): + """Assert the status and, when refused, the error envelope.""" + usage_key = usage_key or self.unit.location + response = _client(user).get(children_url(usage_key), _params(view)) + head = _client(user).head(children_url(usage_key), _params(view)) + assert response.status_code == expected, response.content + assert head.status_code == expected + if expected != 200: + slug = {401: "authn", 403: "authz", 404: "not-found"}[expected] + assert_error_envelope(response, expected_status=expected, expected_type_slug=slug) + else: + assert_page(response.json(), view) + + +@ddt.ddt +class ContainerChildrenAccessLegacyPermissionsTest(_AccessMatrixMixin, SharedModuleStoreTestCase): + """Who may list a container's children when policy-based authoring permissions are off.""" + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.course = build_course(sections=1, subsections=1, units=1) + cls.other_course = build_course(sections=1, subsections=1, units=1) + cls.unit = units_of(cls.course.id)[0] + + def _user_with(self, role): + user = UserFactory() + role.add_users(user) + return user + + @ddt.data(*VIEWS) + def test_anonymous_caller_is_refused_with_401(self, view): + self.assert_access(None, view, 401) + response = _client().get(children_url(self.unit.location), _params(view)) + assert response["WWW-Authenticate"] == 'JWT realm="api"' + + @ddt.data(*VIEWS) + def test_user_without_a_role_is_refused_with_403(self, view): + self.assert_access(UserFactory(), view, 403) + + @ddt.data(*VIEWS) + def test_an_enrolled_learner_is_refused_with_403(self, view): + learner = UserFactory() + CourseEnrollment.enroll(learner, self.course.id) + self.assert_access(learner, view, 403) + + def test_v1_lists_the_children_for_a_user_without_a_role(self): + """v1 checks only that the caller is signed in; v2 also requires permission to view the course.""" + user = UserFactory() + assert _client(user).get(v1_url(self.unit.location)).status_code == 200 + assert _client(user).get(children_url(self.unit.location)).status_code == 403 + + @ddt.data(*VIEWS) + def test_unknown_course_is_404_before_permission_is_checked(self, view): + self.assert_access(UserFactory(), view, 404, usage_key=UNKNOWN_COURSE_UNIT) + self.assert_access(UserFactory(is_staff=True), view, 404, usage_key=UNKNOWN_COURSE_UNIT) + + @ddt.data(*VIEWS) + def test_anonymous_caller_of_an_unknown_course_is_refused_with_401(self, view): + self.assert_access(None, view, 401, usage_key=UNKNOWN_COURSE_UNIT) + + @ddt.data(*VIEWS) + def test_limited_staff_is_refused(self, view): + self.assert_access(self._user_with(CourseLimitedStaffRole(self.course.id)), view, 403) + + @ddt.data(*VIEWS) + def test_staff_of_another_course_is_refused(self, view): + """A role on course A does not open a container of course B.""" + user = self._user_with(CourseStaffRole(self.other_course.id)) + self.assert_access(user, view, 200, usage_key=units_of(self.other_course.id)[0].location) + self.assert_access(user, view, 403) + + @ddt.data(*VIEWS) + def test_course_staff_may_read(self, view): + self.assert_access(self._user_with(CourseStaffRole(self.course.id)), view, 200) + + @ddt.data(*VIEWS) + def test_course_instructor_may_read(self, view): + self.assert_access(self._user_with(CourseInstructorRole(self.course.id)), view, 200) + + @ddt.data(*VIEWS) + def test_org_staff_and_org_instructor_may_read(self, view): + self.assert_access(self._user_with(OrgStaffRole(self.course.id.org)), view, 200) + self.assert_access(self._user_with(OrgInstructorRole(self.course.id.org)), view, 200) + + @ddt.data(*VIEWS) + def test_global_staff_and_superuser_may_read(self, view): + self.assert_access(UserFactory(is_staff=True), view, 200) + self.assert_access(UserFactory(is_superuser=True), view, 200) + + @ddt.data(*VIEWS) + def test_a_missing_block_is_404_for_a_reader_and_403_for_anyone_else(self, view): + missing = self.unit.location.replace(block_id="missing") + self.assert_access(self._user_with(CourseStaffRole(self.course.id)), view, 404, usage_key=missing) + self.assert_access(UserFactory(), view, 403, usage_key=missing) + + @ddt.data(*VIEWS) + def test_an_inactive_session_is_not_authenticated(self, view): + """A session whose account is not activated is refused with 401, global staff included.""" + for user in (UserFactory(is_staff=True), self._user_with(CourseStaffRole(self.course.id))): + client = _session_client(user) + assert client.get(children_url(self.unit.location), _params(view)).status_code == 200, "active control" + user.is_active = False + user.save() + response = client.get(children_url(self.unit.location), _params(view)) + assert_error_envelope(response, expected_status=401, expected_type_slug="authn") + + @ddt.data(*VIEWS) + def test_jwt_caller_may_read(self, view): + user = self._user_with(CourseStaffRole(self.course.id)) + response = APIClient().get( + children_url(self.unit.location), _params(view), HTTP_AUTHORIZATION=f"JWT {create_jwt_for_user(user)}", + ) + assert response.status_code == 200, response.content + + @ddt.data(*VIEWS) + def test_an_inactive_jwt_caller_who_is_global_staff_may_read(self, view): + """A JWT is not checked for an activated account.""" + assert_inactive_jwt_reads(UserFactory(is_staff=True), self.unit.location, view) + + @ddt.data(*VIEWS) + def test_bearer_token_is_refused(self, view): + """Bearer tokens are not accepted here, though the v1 read takes them.""" + user = UserFactory(is_staff=True) + token = AccessTokenFactory(user=user, application=ApplicationFactory(user=user)).token + response = APIClient().get( + children_url(self.unit.location), _params(view), HTTP_AUTHORIZATION=f"Bearer {token}", + ) + assert_error_envelope(response, expected_status=401, expected_type_slug="authn") + assert APIClient().get(v1_url(self.unit.location), HTTP_AUTHORIZATION=f"Bearer {token}").status_code == 200 + + @ddt.data(*VIEWS) + def test_a_custom_course_is_refused_to_everyone(self, view): + """Studio read access is never granted on a custom course (CCX), global staff included.""" + key = _ccx_key(self.unit.location) + self.assert_access(UserFactory(is_staff=True), view, 403, usage_key=key) + self.assert_access(self._user_with(CourseStaffRole(self.course.id)), view, 403, usage_key=key) + + @ddt.data("post", "put", "patch", "delete") + def test_other_methods_are_refused_after_authentication(self, method): + """Anonymous callers are refused before the method is; signed-in readers learn it is not allowed.""" + url = children_url(self.unit.location) + anonymous = getattr(_client(), method)(url, {}, format="json") + assert_error_envelope(anonymous, expected_status=401, expected_type_slug="authn") + reader = self._user_with(CourseStaffRole(self.course.id)) + refused = getattr(_client(reader), method)(url, {}, format="json") + # The error library does not catalogue MethodNotAllowed, so it is typed + # internal. Change the expected type here once it does. + assert_error_envelope(refused, expected_status=405, expected_type_slug="internal") + + +@ddt.ddt +class ContainerChildrenAccessAuthzTest(CourseAuthoringAuthzTestMixin, _AccessMatrixMixin, SharedModuleStoreTestCase): + """Who may list a container's children when policy-based authoring permissions are on.""" + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.course = build_course(sections=1, subsections=1, units=1) + cls.other_course = build_course(sections=1, subsections=1, units=1) + cls.unit = units_of(cls.course.id)[0] + cls.other_unit = units_of(cls.other_course.id)[0] + + def _user_with(self, role, course_key=None): + user = UserFactory() + self.add_user_to_role_in_course(user, role, course_key or self.course.id) + return user + + @ddt.data(*VIEWS) + def test_anonymous_caller_is_refused_with_401(self, view): + self.assert_access(None, view, 401) + + @ddt.data(*VIEWS) + def test_user_without_a_role_is_refused_with_403(self, view): + self.assert_access(self.unauthorized_user, view, 403) + + @ddt.data(*[(view, role) for view in VIEWS for role in (COURSE_AUDITOR.external_key, COURSE_ADMIN.external_key)]) + @ddt.unpack + def test_a_role_on_another_course_is_refused(self, view, role): + user = self._user_with(role, self.other_course.id) + self.assert_access(user, view, 200, usage_key=self.other_unit.location) + self.assert_access(user, view, 403) + + @ddt.data(*VIEWS) + def test_unknown_course_is_404_before_permission_is_checked(self, view): + self.assert_access(self.unauthorized_user, view, 404, usage_key=UNKNOWN_COURSE_UNIT) + + @ddt.data(*[(view, role) for view in VIEWS for role in ( + COURSE_AUDITOR.external_key, COURSE_EDITOR.external_key, COURSE_STAFF.external_key, COURSE_ADMIN.external_key, + )]) + @ddt.unpack + def test_roles_that_may_view_the_course_may_read(self, view, role): + self.assert_access(self._user_with(role), view, 200) + + @ddt.data(*[(view, role) for view in VIEWS for role in ( + COURSE_LIMITED_STAFF.external_key, COURSE_DATA_RESEARCHER.external_key, COURSE_BETA_TESTER.external_key, + )]) + @ddt.unpack + def test_other_roles_are_refused(self, view, role): + self.assert_access(self._user_with(role), view, 403) + + @ddt.data(*VIEWS) + def test_legacy_course_staff_without_a_policy_role_is_refused(self, view): + user = UserFactory() + CourseAccessRole.objects.create(user=user, role="staff", course_id=self.course.id, org=self.course.id.org) + self.assert_access(user, view, 403) + + @ddt.data(*VIEWS) + def test_a_missing_block_is_404_for_a_reader_and_403_for_anyone_else(self, view): + missing = self.unit.location.replace(block_id="missing") + self.assert_access(self._user_with(COURSE_AUDITOR.external_key), view, 404, usage_key=missing) + self.assert_access(self.unauthorized_user, view, 403, usage_key=missing) + + @ddt.data(*VIEWS) + def test_an_inactive_session_with_a_role_is_not_authenticated(self, view): + user = self._user_with(COURSE_AUDITOR.external_key) + client = _session_client(user) + assert client.get(children_url(self.unit.location), _params(view)).status_code == 200, "active control" + user.is_active = False + user.save() + response = client.get(children_url(self.unit.location), _params(view)) + assert_error_envelope(response, expected_status=401, expected_type_slug="authn") + + @ddt.data(*VIEWS) + def test_an_inactive_jwt_caller_with_a_role_may_read(self, view): + """A JWT is not checked for an activated account.""" + assert_inactive_jwt_reads(self._user_with(COURSE_AUDITOR.external_key), self.unit.location, view) + + @ddt.data(*VIEWS) + def test_a_custom_course_is_refused_to_staff_and_course_staff(self, view): + """A custom course (CCX) is not a scope the permission policy grants to staff or to a course role.""" + key = _ccx_key(self.unit.location) + self.assert_access(self.staff_user, view, 403, usage_key=key) + self.assert_access(self._user_with(COURSE_STAFF.external_key), view, 403, usage_key=key) + + @ddt.data(*VIEWS) + def test_staff_and_superuser_without_a_role_are_admitted_by_the_policy(self, view): + self.assert_access(self.staff_user, view, 200) + self.assert_access(self.super_user, view, 200) + + +# --------------------------------------------------------------------------- +# What is a container +# --------------------------------------------------------------------------- + +class ContainerChildrenMembershipTest(ModuleStoreTestCase): + """ + A container is a block other than the course that can hold children. + Anything else is answered with 404 without naming the block. + """ + + def setUp(self): + super().setUp() + course = build_course(sections=1, subsections=1, units=1) + self.course_key = course.id + self.store = modulestore() + self.course = self.store.get_course(course.id) + self.section = self.course.get_children()[0] + self.subsection = self.section.get_children()[0] + self.unit = self.subsection.get_children()[0] + self.problem = self.unit.get_children()[0] + self.split = _block(self.unit, "split_test", "Split test") + self.group = _block(self.split, "vertical", "Group") + self.empty_unit = _block(self.subsection, "vertical", "Empty unit") + self.reader = UserFactory() + CourseStaffRole(course.id).add_users(self.reader) + self.client = _client(self.reader) + + def _assert_not_a_container(self, key): + """Assert both views answer 404 for ``key`` without naming it.""" + for params in ({}, {"view": "full"}): + response = self.client.get(children_url(key), params) + envelope = assert_error_envelope(response, expected_status=404, expected_type_slug="not-found") + assert envelope["detail"] == CONTAINER_NOT_FOUND + assert envelope["instance"] == children_url(key) + assert str(key) not in str(_without_instance(envelope)) + + def test_every_kind_of_container_lists_its_children_in_order(self): + for block in (self.section, self.subsection, self.unit, self.split, self.group, self.empty_unit): + expected = [str(child.location) for child in self.store.get_item(block.location).get_children()] + for view, key in (("default", "id"), ("full", "block_id")): + response = self.client.get(children_url(block.location), _params(view)) + assert response.status_code == 200, (block.location, response.content) + body = response.json() + assert_page(body, view) + assert [item[key] for item in body["results"]] == expected + assert body["count"] == len(expected) + + def test_a_container_without_children_is_an_empty_page(self): + """The unit holds nothing; it is a container all the same, so the answer is a page, not a 404.""" + body = self.client.get(children_url(self.empty_unit.location)).json() + assert body == {"count": 0, "next": None, "previous": None, "num_pages": 1, "current_page": 1, "start": 0, + "results": []} + + def test_the_course_is_not_a_container(self): + self._assert_not_a_container(self.course.location) + + def test_a_component_is_not_a_container(self): + """v1 answers a component's key with an empty list of children.""" + self._assert_not_a_container(self.problem.location) + legacy = self.client.get(v1_url(self.problem.location)) + assert (legacy.status_code, legacy.json()["children"]) == (200, []) + + def test_a_missing_block_is_not_a_container(self): + """v1 answers it with a server error.""" + missing = self.unit.location.replace(block_id="missing") + self._assert_not_a_container(missing) + assert self.client.get(v1_url(missing)).status_code == 500 + + def test_a_container_the_course_does_not_reach_is_listed(self): + """Only the key's course is looked at, not the path from the course down to the block.""" + orphan = self.store.create_item(self.user.id, self.course_key, "chapter", "orphan_section") + child = _block(orphan, "sequential", "Subsection of an orphan section") + body = self.client.get(children_url(orphan.location)).json() + assert [item["id"] for item in body["results"]] == [str(child.location)] + + def test_a_course_info_block_that_does_not_exist_is_not_created(self): + """v1 creates it, which makes its GET a write.""" + key = self.course_key.make_usage_key("course_info", "updates") + assert not self.store.has_item(key) + # The first permission lookup on a database stores the policy version row; it is not under test. + assert self.client.get(children_url(self.unit.location)).status_code == 200 + with record_effects(self) as effects: + self._assert_not_a_container(key) + assert (effects["sql_writes"], effects["mongo_writes"], effects["update_item"]) == ([], 0, []) + assert not self.store.has_item(key) + assert self.client.get(v1_url(key)).status_code == 200 + assert self.store.has_item(key) + + def test_keys_outside_any_course_are_not_found(self): + for key in (*LIBRARY_KEYS, f"block-v1:version@{VERSION_GUID}+type@vertical+block@x"): + for params in ({}, {"view": "full"}): + response = self.client.get(children_url(key), params) + envelope = assert_error_envelope(response, expected_status=404, expected_type_slug="not-found") + assert envelope["detail"] == COURSE_NOT_FOUND + assert VERSION_GUID not in str(_without_instance(envelope)) + assert_error_envelope(_client().get(children_url(key)), expected_status=401, expected_type_slug="authn") + + +# --------------------------------------------------------------------------- +# The default view and the page +# --------------------------------------------------------------------------- + +@ddt.ddt +class ContainerChildrenDefaultViewTest(ModuleStoreTestCase): + """A brief description of each child, in a page.""" + + def setUp(self): + super().setUp() + course = build_course(sections=1, subsections=1, units=1) + self.store = modulestore() + self.section = self.store.get_course(course.id).get_children()[0] + self.subsection = self.section.get_children()[0] + self.unit = self.subsection.get_children()[0] + self.reader = UserFactory() + CourseStaffRole(course.id).add_users(self.reader) + self.client = _client(self.reader) + + def _get(self, block, **params): + return self.client.get(children_url(block.location), params) + + def test_each_kind_of_child_is_described_by_its_type(self): + html = _block(self.unit, "html", "Introduction") + split = _block(self.unit, "split_test", "Experiment") + group = _block(split, "vertical", "Group") + problem = self.unit.get_children()[0] + assert self._get(self.unit).json()["results"] == [ + {"id": str(problem.location), "category": "problem", "display_name": "Problem 0.0.0", + "display_type": "Problem", "has_children": False}, + {"id": str(html.location), "category": "html", "display_name": "Introduction", + "display_type": "Text", "has_children": False}, + {"id": str(split.location), "category": "split_test", "display_name": "Experiment", + "display_type": "Content Experiment", "has_children": True}, + ] + assert self._get(split).json()["results"] == [ + {"id": str(group.location), "category": "vertical", "display_name": "Group", + "display_type": "Vertical", "has_children": True}, + ] + assert self._get(self.subsection).json()["results"] == [ + {"id": str(self.unit.location), "category": "vertical", "display_name": "Unit 0.0.0", + "display_type": "Unit", "has_children": True}, + ] + assert self._get(self.section).json()["results"] == [ + {"id": str(self.subsection.location), "category": "sequential", "display_name": "Subsection 0.0", + "display_type": "Subsection", "has_children": True}, + ] + + def test_a_block_type_that_declares_no_display_name_has_a_null_display_type(self): + """The published schema marks display_type nullable, so the nullable case has to be real.""" + with patch( + "cms.djangoapps.contentstore.rest_api.v2.container_children_service.xblock_type_display_name", + return_value=None, + ): + body = self._get(self.unit).json() + assert [item["display_type"] for item in body["results"]] == [None] + assert_page(body, "default") + + @ddt.data({}, {"view": "minimal"}, {"view": ""}) + def test_the_brief_description_is_the_default(self, params): + body = self._get(self.unit, **params).json() + assert set(body["results"][0]) == SUMMARY_KEYS + + def test_the_view_is_validated(self): + for value in ("bogus", "FULL", "full,minimal"): + response = self._get(self.unit, view=value) + envelope = assert_error_envelope(response, expected_status=400, expected_type_slug="validation") + assert envelope["errors"] == {"view": [INVALID_VIEW]} + + def test_the_order_is_the_order_the_container_stores(self): + first = _block(self.unit, "html", "First") + second = _block(self.unit, "html", "Second") + unit = self.store.get_item(self.unit.location) + unit.children = [second.location, unit.children[0], first.location] + self.store.update_item(unit, self.user.id) + expected = [str(second.location), str(unit.children[1]), str(first.location)] + assert [item["id"] for item in self._get(self.unit).json()["results"]] == expected + legacy = self.client.get(v1_url(self.unit.location)).json() + assert [item["block_id"] for item in legacy["children"]] == expected + + def test_a_reference_to_a_block_that_cannot_be_loaded_is_left_out(self): + """v1 fails on the whole container.""" + unit = self.store.get_item(self.unit.location) + unit.children.append(self.unit.location.replace(block_type="html", block_id="gone")) + self.store.update_item(unit, self.user.id) + for params in ({}, {"view": "full"}): + body = self._get(self.unit, **params).json() + assert body["count"] == 1 + assert len(body["results"]) == 1 + assert self.client.get(v1_url(self.unit.location)).status_code == 500 + + def test_a_page_holds_ten_children_by_default_and_links_to_the_next(self): + for index in range(11): + _block(self.unit, "html", f"Text {index}") + first = self._get(self.unit).json() + assert (first["count"], first["num_pages"], first["current_page"], first["start"]) == (12, 2, 1, 0) + assert len(first["results"]) == 10 + assert first["previous"] is None + assert first["next"] == f"http://testserver{children_url(self.unit.location)}?page=2" + second = self._get(self.unit, page=2).json() + assert (second["current_page"], second["start"], len(second["results"])) == (2, 10, 2) + assert second["next"] is None + assert second["previous"] == f"http://testserver{children_url(self.unit.location)}" + assert [item["display_name"] for item in first["results"] + second["results"]][1:] == [ + f"Text {index}" for index in range(11) + ] + + def test_the_page_links_keep_the_view_and_the_page_size(self): + for index in range(4): + _block(self.unit, "html", f"Text {index}") + body = self._get(self.unit, view="full", page_size=2, page=2).json() + assert (body["count"], body["num_pages"], body["start"]) == (5, 3, 2) + for link, page in ((body["previous"], None), (body["next"], "3")): + query = dict(part.split("=") for part in link.split("?")[1].split("&")) + assert query == {"view": "full", "page_size": "2", **({"page": page} if page else {})} + + def test_a_page_never_holds_more_than_a_hundred_children(self): + with self.store.bulk_operations(self.unit.location.course_key): + for index in range(100): + _block(self.unit, "html", f"Text {index}") + body = self._get(self.unit, page_size=101).json() + assert (body["count"], len(body["results"]), body["num_pages"]) == (101, 100, 2) + assert len(self._get(self.unit, page=2, page_size=101).json()["results"]) == 1 + + @ddt.data({"page": 2}, {"page": 0}, {"page": "x"}, {"page": -1}, {"page": 2, "view": "full"}) + def test_a_page_that_does_not_exist_is_404(self, params): + response = self._get(self.unit, **params) + envelope = assert_error_envelope(response, expected_status=404, expected_type_slug="not-found") + assert envelope["detail"] == "Invalid page." + + def test_the_details_are_worked_out_for_the_requested_page_only(self): + """The cost of view=full follows the page size, not the number of children.""" + for index in range(5): + _block(self.unit, "html", f"Text {index}") + service = "cms.djangoapps.contentstore.rest_api.v2.container_children_service" + with patch(f"{service}.get_xblock_render_error", return_value="") as render, \ + patch(f"{service}.get_user_partition_info", return_value=[]) as partitions, \ + patch(f"{service}.UpstreamLink.try_get_for_block") as upstream: + upstream.return_value.upstream_ref = None + body = self._get(self.unit, view="full", page_size=2, page=2).json() + assert (body["count"], len(body["results"])) == (6, 2) + assert render.call_count == partitions.call_count == upstream.call_count == 2 + + +# --------------------------------------------------------------------------- +# The full view +# --------------------------------------------------------------------------- + +RENDER_SECRET = "secret detail of /var/lib/studio/render.py" +SERVICE = "cms.djangoapps.contentstore.rest_api.v2.container_children_service" + + +class FailingRenderBlock(XBlock): + """A block whose rendering fails with a message that must not reach the caller.""" + + def student_view(self, context=None): # pylint: disable=unused-argument + raise RuntimeError(RENDER_SECRET) + + +@ddt.ddt +class ContainerChildrenFullViewTest(ModuleStoreTestCase): + """What view=full says about each child, for each way the data can vary.""" + + def setUp(self): + super().setUp() + course = build_course(sections=1, subsections=1, units=1) + self.store = modulestore() + self.subsection = self.store.get_course(course.id).get_children()[0].get_children()[0] + self.unit = self.subsection.get_children()[0] + self.reader = UserFactory() + CourseStaffRole(course.id).add_users(self.reader) + self.client = _client(self.reader) + + def _full(self, block): + """The full view of ``block``'s children by name.""" + response = self.client.get(children_url(block.location), {"view": "full"}) + assert response.status_code == 200, response.content + body = response.json() + assert_page(body, "full") + return {item["name"]: item for item in body["results"]} + + def test_a_child_that_is_not_linked_to_a_library_has_a_null_link(self): + child = self._full(self.unit)["Problem 0.0.0"] + assert set(child) == DETAIL_KEYS + assert child["upstream_link"] is None + assert child["validation_messages"] == [] + assert child["render_error"] == "" + + def test_a_link_to_a_library_that_cannot_be_followed_reports_why_and_nothing_else(self): + """Every field of the link that is null in practice is declared nullable.""" + _block(self.unit, "html", "Broken", upstream="lb:Org:nolib:html:missing", upstream_version=3) + _block(self.unit, "html", "Unversioned", upstream="lb:Org:nolib:html:other") + link = self._full(self.unit)["Broken"]["upstream_link"] + assert link["upstream_ref"] == "lb:Org:nolib:html:missing" + assert link["version_synced"] == 3 + assert link["version_available"] is None + assert link["version_declined"] is None + assert isinstance(link["error_message"], str) + assert link["error_message"] != "" + assert link["ready_to_sync"] is False + assert link["downstream_customized"] == [] + assert link["top_level_parent_key"] is None + assert "ready_to_sync_children" not in link + assert self._full(self.unit)["Unversioned"]["upstream_link"]["version_synced"] is None + + def test_the_actions_follow_where_the_child_sits(self): + """ + A child that holds children and has no page of its own is edited inline, + so whole-block actions do not apply to it; everything else can be copied. + """ + split = _block(self.unit, "split_test", "Split") + _block(split, "vertical", "Group") + everything = { + "can_copy": True, "can_duplicate": True, "can_move": True, "can_manage_access": True, + "can_delete": True, "can_manage_tags": True, + } + inline = {**everything, "can_copy": False, "can_duplicate": False, "can_move": False, + "can_manage_access": False} + assert self._full(self.unit)["Problem 0.0.0"]["actions"] == everything + assert self._full(self.unit)["Split"]["actions"] == everything + assert self._full(split)["Group"]["actions"] == inline + assert self._full(self.subsection)["Unit 0.0.0"]["actions"] == everything + + @ddt.data(True, False) + def test_tagging_can_be_turned_off(self, disabled): + with override_waffle_flag(DISABLE_TAGGING_FEATURE, disabled): + actions = self._full(self.unit)["Problem 0.0.0"]["actions"] + assert actions["can_manage_tags"] is (not disabled) + + def test_the_visibility_groups_and_what_contradicts_them_are_reported(self): + course = self.store.get_course(self.unit.location.course_key) + course.user_partitions = [ + UserPartition(0, "Cohorts", "Test partition", [Group("0", "alpha"), Group("1", "beta")]), + ] + self.store.update_item(course, self.user.id) + unit = self.store.get_item(self.unit.location) + unit.group_access = {0: [1]} + self.store.update_item(unit, self.user.id) + problem = self.store.get_item(self.unit.get_children()[0].location) + problem.group_access = {0: [0]} + self.store.update_item(problem, self.user.id) + child = self._full(self.unit)["Problem 0.0.0"] + assert [(message["type"], message["text"]) for message in child["validation_messages"]] == [ + ("error", "This component's access settings contradict its parent's access settings."), + ] + assert [ + (partition["name"], [(group["name"], group["selected"]) for group in partition["groups"]]) + for partition in child["user_partitions"] + ] == [("Cohorts", [("alpha", True), ("beta", False)]), ("Enrollment Track Groups", [("Audit", False)])] + assert child["user_partition_info"] == { + "selectable_partitions": [], "selected_partition_index": -1, "selected_groups_label": "", + } + + @XBlock.register_temp_plugin(FailingRenderBlock, "failing_render") + def test_a_child_that_fails_to_render_is_reported_without_the_cause(self): + """The cause comes from the block's own code, so it is logged with the child's key and not returned.""" + broken = _block(self.unit, "failing_render", "Broken") + with self.assertLogs(SERVICE, level="WARNING") as logs: + response = self.client.get(children_url(self.unit.location), {"view": "full"}) + body = response.json() + assert_page(body, "full") + by_name = {item["name"]: item for item in body["results"]} + assert by_name["Broken"]["render_error"] == RENDER_ERROR_MESSAGE + assert by_name["Problem 0.0.0"]["render_error"] == "" + assert RENDER_SECRET not in response.content.decode() + assert len(logs.records) == 1 + assert str(broken.location) in logs.records[0].getMessage() + assert RENDER_SECRET in logs.records[0].getMessage() + assert logs.records[0].levelno == logging.WARNING + legacy = self.client.get(v1_url(self.unit.location)).json() + assert {child["name"]: child["render_error"] for child in legacy["children"]}["Broken"] == RENDER_SECRET + + def test_the_default_view_neither_renders_nor_loads_the_course(self): + with patch(f"{SERVICE}.get_xblock_render_error") as render, patch.object( + self.store.__class__, "get_course", side_effect=AssertionError("the course is not needed") + ): + assert self.client.get(children_url(self.unit.location)).status_code == 200 + render.assert_not_called() + + +# --------------------------------------------------------------------------- +# Parity with the v1 read +# --------------------------------------------------------------------------- + +# Differences between the v1 read and view=full: (json path pattern, reason). +# The comparison asserts that each occurs and that nothing else differs. +INTENTIONAL_DIFFERENCES = [ + ( + r"is_published|can_paste_component|display_name|upstream_ready_to_sync_children_info(\[\d+\].*)?", + "v1 also describes the container itself; the page lists only its children", + ), + (r"count|next|previous|num_pages|current_page|start", "the page envelope"), + ( + r"results\[\d+\]\.render_error", + "the cause of a render failure is logged and a fixed message returned", + ), +] + +_ABSENT = object() + + +def _flatten(obj, prefix=""): + """ + A ``{json_path: value}`` map of every leaf of ``obj``. An empty object or + array is a leaf, so a container that empties or changes kind is seen. + """ + flat = {} + if isinstance(obj, dict) and obj: + for key in sorted(obj): + flat.update(_flatten(obj[key], f"{prefix}.{key}" if prefix else key)) + elif isinstance(obj, list) and obj: + for index, item in enumerate(obj): + flat.update(_flatten(item, f"{prefix}[{index}]")) + else: + flat[prefix] = obj + return flat + + +def _same(a, b): + """Whether two leaves are equal and of the same JSON type: true is not 1, 1.0 is not 1, {} is not [].""" + return type(a) is type(b) and a == b + + +def _differences(legacy, new): + """ + Compare two bodies. Return the json paths that differ, those among them no + declared difference explains, and the declared differences that did not occur. + """ + a, b = _flatten(legacy), _flatten(new) + changed = {key for key in set(a) | set(b) if not _same(a.get(key, _ABSENT), b.get(key, _ABSENT))} + declared = [pattern for pattern, _ in INTENTIONAL_DIFFERENCES] + unexpected = {key for key in changed if not any(re.fullmatch(pattern, key) for pattern in declared)} + missing = {pattern for pattern in declared if not any(re.fullmatch(pattern, key) for key in changed)} + return changed, unexpected, missing + + +def _as_page(legacy): + """The v1 body with its list of children where the page holds its results.""" + body = dict(legacy) + body["results"] = body.pop("children") + return body + + +def test_the_comparison_sees_types_and_empty_containers(): + assert _differences({"a": {"b": []}}, {"a": {}})[0] == {"a", "a.b"} + assert _differences({"x": True}, {"x": 1})[0] == {"x"} + assert _differences({"x": 1.0}, {"x": 1})[0] == {"x"} + assert _differences({"x": {}}, {"x": []})[0] == {"x"} + assert _differences({"x": None, "y": 1}, {"y": 1})[0] == {"x"} + assert _differences({"x": [1, {"y": False}]}, {"x": [1, {"y": False}]})[0] == set() + + +def test_each_declared_difference_must_occur_and_nothing_else_may(): + legacy = {"results": [{"render_error": "x", "name": "a"}], "is_published": False, "display_name": "u"} + new = {"results": [{"render_error": "fixed", "name": "a"}], "count": 1} + _, unexpected, missing = _differences(legacy, new) + assert unexpected == set() + assert missing == {pattern for pattern, _ in INTENTIONAL_DIFFERENCES} - { + INTENTIONAL_DIFFERENCES[0][0], INTENTIONAL_DIFFERENCES[1][0], INTENTIONAL_DIFFERENCES[2][0], + } + _, unexpected, missing = _differences(legacy, {**new, "results": [{"render_error": "fixed", "name": "b"}]}) + assert unexpected == {"results[0].name"} + _, unexpected, missing = _differences( + {"results": [{"render_error": ""}], "is_published": False, "display_name": "u"}, + {"results": [{"render_error": ""}], "count": 1}, + ) + assert (unexpected, missing) == (set(), {INTENTIONAL_DIFFERENCES[2][0]}) + + +class _ParityMixin: + """Compares view=full against the v1 read of the same container for the same caller.""" + + def pair(self, client, usage_key, **params): + """The v1 and view=full reads of ``usage_key`` as JSON; v2 is read first so nothing v1 stores reaches it.""" + new = client.get(children_url(usage_key), {"view": "full", **params}) + legacy = client.get(v1_url(usage_key)) + assert legacy.status_code == new.status_code == 200, (legacy.content, new.content) + return _as_page(legacy.json()), new.json() + + def compare(self, client, usage_key, **params): + """Return the paths that differ between the two reads of ``usage_key``; ``unexpected`` ones fail here.""" + legacy, new = self.pair(client, usage_key, **params) + changed, unexpected, _ = _differences(legacy, new) + assert unexpected == set(), (str(usage_key), sorted(unexpected)) + assert_page(new, "full") + assert [child["block_id"] for child in legacy["results"]] == [item["block_id"] for item in new["results"]] + # Where v1 reports a render failure the page carries the fixed message, and nowhere else. + for old, item in zip(legacy["results"], new["results"], strict=True): + assert item["render_error"] == (RENDER_ERROR_MESSAGE if old["render_error"] else ""), item["block_id"] + return changed + + +class ContainerChildrenParityTest(_ParityMixin, ModuleStoreTestCase): + """view=full returns what v1 returns for each child, except the declared differences.""" + + @XBlock.register_temp_plugin(FailingRenderBlock, "failing_render") + def test_every_kind_of_container_is_described_as_v1_describes_it(self): + course = build_course(sections=1, subsections=2, units=1) + store = modulestore() + course = store.get_course(course.id) + course.user_partitions = [ + UserPartition(0, "Cohorts", "Test partition", [Group("0", "alpha"), Group("1", "beta")]), + ] + store.update_item(course, self.user.id) + section = store.get_course(course.id).get_children()[0] + subsection = section.get_children()[0] + unit = subsection.get_children()[0] + _block(unit, "html", "Introduction") + _block(unit, "html", "Broken link", upstream="lb:Org:nolib:html:missing", upstream_version=2) + _block(unit, "failing_render", "Fails to render") + split = _block(unit, "split_test", "Split") + _block(split, "vertical", "Group A") + _block(split, "vertical", "Group B") + restricted_unit = store.get_item(unit.location) + restricted_unit.group_access = {0: [1]} + store.update_item(restricted_unit, self.user.id) + restricted_problem = store.get_item(unit.get_children()[0].location) + restricted_problem.group_access = {0: [0]} + store.update_item(restricted_problem, self.user.id) + reader = UserFactory() + CourseStaffRole(course.id).add_users(reader) + client = _client(reader) + + changed = set() + containers = [section, subsection, unit, split, store.get_item(unit.location).get_children()[-1]] + for container in containers + [section.get_children()[1].get_children()[0]]: + changed |= self.compare(client, container.location) + with override_waffle_flag(DISABLE_TAGGING_FEATURE, True): + changed |= self.compare(client, unit.location) + + declared = [pattern for pattern, _ in INTENTIONAL_DIFFERENCES] + for pattern in declared: + assert any(re.fullmatch(pattern, key) for key in changed), f"declared difference never occurred: {pattern}" + + def test_pagination_does_not_change_what_is_described(self): + course = build_course(sections=1, subsections=1, units=1) + unit = units_of(course.id)[0] + for index in range(4): + _block(unit, "html", f"Text {index}") + reader = UserFactory() + CourseStaffRole(course.id).add_users(reader) + client = _client(reader) + whole, _ = self.pair(client, unit.location)[0], None + pages = [ + client.get(children_url(unit.location), {"view": "full", "page_size": 2, "page": page}).json()["results"] + for page in (1, 2, 3) + ] + assert [item for page in pages for item in page] == whole["results"] + assert [len(page) for page in pages] == [2, 2, 1] + + +class ContainerChildrenLibraryLinkedParityTest(_ParityMixin, BaseXBlockContainer): + """Children linked to library blocks and to a library container are described as v1 describes them.""" + + view_name = "container_children" + + def test_a_linked_container_reports_which_of_its_blocks_are_ready_to_sync(self): + changed = self.compare(self.client, self.sequential.location) + body = self.client.get(children_url(self.sequential.location), {"view": "full"}).json() + link = body["results"][0]["upstream_link"] + assert body["results"][0]["block_id"] == str(self.vertical.location) + assert link["upstream_ref"] == self.unit["id"] + assert link["ready_to_sync_children"] == [{ + "id": str(self.html_unit_second.usage_key), + "name": "Html Content 2", + "upstream": self.html_block["id"], + }] + assert not any(key.startswith("results[0].upstream_link") for key in changed) + + def test_a_linked_block_reports_the_version_the_library_has_moved_to(self): + self.compare(self.client, self.vertical.location) + body = self.client.get(children_url(self.vertical.location), {"view": "full"}).json() + first, second = body["results"] + assert first["upstream_link"] is None + assert second["upstream_link"] == { + "upstream_ref": self.html_block["id"], + "version_synced": 1, + "version_available": 2, + "version_declined": None, + "error_message": None, + "ready_to_sync": True, + "downstream_customized": [], + "top_level_parent_key": None, + } + + +# --------------------------------------------------------------------------- +# Reads write nothing +# --------------------------------------------------------------------------- + +class _ReadIsSideEffectFreeMixin: + """ + Every read (both views, GET and HEAD, of a unit holding a block linked to + a library, a split test and a block that fails to render, of a subsection + and of a section) writes no domain row and no Mongo document, stores + nothing through the modulestore, and sends no openedx-event. + + Two things are written, and only these: + + * The reads start on a database that has never served a role or + permission lookup, and the first lookup stores the permission library's + policy version row (``PolicyCacheControl``). + * Rendering a child for the full view can store state for the previewing + user in the session, and the session is saved with the response. The + default view renders nothing and never touches the session. + + Each save sends the model's pre_save and post_save, and nothing else is + sent beyond the test client's own report of rendered templates. + """ + + SESSION_TABLE = "django_session" + + def reader_for(self, course): + """Return a user who may read ``course``.""" + raise NotImplementedError + + def _course(self): + """A course whose first unit holds children of each kind that reads differently.""" + course = build_course(sections=1, subsections=1, units=2) + unit = units_of(course.id)[0] + _block(unit, "html", "Linked", upstream="lb:Org:nolib:html:missing", upstream_version=1) + _block(_block(unit, "split_test", "Split"), "vertical", "Group") + _block(unit, "failing_render", "Fails to render") + return course, unit + + def _assert_reads_have_no_side_effects(self): + """Make every read of the course and check what each one wrote and sent.""" + course, unit = self._course() + subsection = unit.get_parent() + section = subsection.get_parent() + client = _client(self.reader_for(course)) + PolicyCacheControl.objects.all().delete() + full = {"view": "full"} + reads = [ + ("get", unit, {}), ("get", unit, full), ("head", unit, {}), ("head", unit, full), + ("get", subsection, {}), ("get", subsection, full), ("get", section, {}), ("head", section, full), + ] + assert not PolicyCacheControl.objects.exists() + for index, (method, block, params) in enumerate(reads): + # The signal recorder is outermost, so callbacks run on commit as + # the effects recorder exits are still seen. + with SignalRecorder() as signals, record_effects(self) as effects: + response = getattr(client, method)(children_url(block.location), params) + first = index == 0 + request = (index, method, block.location.block_type, params) + assert response.status_code == 200, (request, response.content) + session = [write for write in effects["sql_writes"] if write[1] == self.SESSION_TABLE] + others = [write for write in effects["sql_writes"] if write[1] != self.SESSION_TABLE] + assert others == (FIRST_LOOKUP_WRITES if first else []), request + assert len(session) <= 1, request + if not params: + assert session == [], request + saved = (["PolicyCacheControl"] if first else []) + ["Session"] * len(session) + assert sorted(effects["saves"]) == sorted(saved), request + expected_signals = ([pre_save, post_save] if first else []) + [pre_save, post_save] * len(session) + sent = [signal for _, signal in signals.unexpected()] + if params: + # The test instrumentation reports each template a rendered child uses; nothing else receives it. + sent = [signal for signal in sent if signal is not template_rendered] + assert Counter(sent) == Counter(expected_signals), request + assert effects["mongo_writes"] == 0, request + assert effects["update_item"] == [], request + assert effects["xblock_updated"] == [], request + assert effects["published"] == [], request + + @XBlock.register_temp_plugin(FailingRenderBlock, "failing_render") + def test_reads_have_no_side_effects(self): + self._assert_reads_have_no_side_effects() + + @XBlock.register_temp_plugin(FailingRenderBlock, "failing_render") + def test_a_signed_in_session_is_written_by_the_full_view_only(self): + """The session of a browser caller is the one thing a read stores, and only by rendering.""" + course, unit = self._course() + client = _session_client(self.reader_for(course)) + client.get(children_url(unit.location)) + with record_effects(self) as effects: + assert client.get(children_url(unit.location)).status_code == 200 + assert effects["sql_writes"] == [] + with record_effects(self) as effects: + assert client.get(children_url(unit.location), {"view": "full"}).status_code == 200 + assert {table for _, table in effects["sql_writes"]} == {self.SESSION_TABLE} + assert effects["mongo_writes"] == 0 + + +class ContainerChildrenSideEffectsLegacyPermissionsTest(_ReadIsSideEffectFreeMixin, ModuleStoreTestCase): + """ + Reads by course staff with policy-based authoring permissions off. Course + staff rather than global staff, whose access is decided without a role lookup. + """ + + def reader_for(self, course): + reader = UserFactory() + CourseStaffRole(course.id).add_users(reader) + return reader + + +class ContainerChildrenSideEffectsAuthzTest( + CourseAuthoringAuthzTestMixin, _ReadIsSideEffectFreeMixin, ModuleStoreTestCase, +): + """Reads by a course auditor with policy-based authoring permissions on.""" + + def reader_for(self, course): + reader = UserFactory() + self.add_user_to_role_in_course(reader, COURSE_AUDITOR.external_key, course.id) + return reader + + +# --------------------------------------------------------------------------- +# Query counts +# --------------------------------------------------------------------------- + +def _measure(request): + """SQL statements, Mongo reads and Mongo writes of the second of two identical requests.""" + request() + with CaptureQueriesContext(connection) as queries, count_mongo_calls() as mongo: + response = request() + assert response.status_code == 200, response.content + return [query["sql"] for query in queries.captured_queries], mongo["reads"], mongo["writes"] + + +def _statement_shape(sql): + """A SQL statement with its literal values and savepoint names blanked, so two requests compare.""" + return re.sub(r"'(?:[^']|'')*'|\bs\d+_x\d+\b|\b\d+(?:\.\d+)?\b", "?", sql) + + +def _is_permission_lookup(sql): + """A statement that checks the caller may view the course, which v1 does not do.""" + tables = ( # pylint: disable=protected-access + CourseOverview._meta.db_table, "waffle_utils_waffleflag", "openedx_authz", '"auth_user"', + "user_api_userretirementrequest", + ) + return sql.lstrip().upper().startswith("SELECT") and any(table in sql for table in tables) + + +CHILDREN = (1, 5, 20) + + +class _QueryCountMixin: + """ + Request costs of a unit holding 1, 5 and 20 children (and of a subsection + holding as many units), against the v1 read of it. The course has an + overview record, as every published course does. + """ + + def reader_for(self, course): + raise NotImplementedError + + def costs(self, count, category="html"): + """``{read: (sql statements, mongo reads, mongo writes)}`` for v1 and the views of ``count`` children.""" + course = build_course(1, 1, 1) + CourseOverview.get_from_id(course.id) + unit = units_of(course.id)[0] + container = unit if category == "html" else unit.get_parent() + for index in range(count - len(container.get_children())): + _block(container, category, f"Child {index}") + client = _client(self.reader_for(course)) + key = container.location + return { + "v1": _measure(lambda: client.get(v1_url(key))), + "default": _measure(lambda: client.get(children_url(key))), + "full": _measure(lambda: client.get(children_url(key), {"view": "full"})), + "full_page_of_5": _measure(lambda: client.get(children_url(key), {"view": "full", "page_size": 5})), + } + + def test_the_default_view_costs_the_same_for_every_number_of_children(self): + for category in ("html", "vertical"): + default = {} + for count in CHILDREN: + statements, reads, writes = self.costs(count, category)["default"] + default[count] = (len(statements), reads, writes) + assert len(set(default.values())) == 1, (category, default) + assert default[1][2] == 0 + + def test_the_full_view_costs_no_more_than_v1_beyond_the_permission_check(self): + for category in ("html", "vertical"): + for count in CHILDREN: + costs = self.costs(count, category) + full, v1 = (Counter(map(_statement_shape, costs[read][0])) for read in ("full", "v1")) + extra = full - v1 + assert all(_is_permission_lookup(sql) for sql in extra), (category, count, extra) + assert sum(extra.values()) <= 4, (category, count, extra) + assert costs["full"][1] <= costs["v1"][1], (category, count, costs) + assert costs["v1"][2] == costs["full"][2] == costs["full_page_of_5"][2] == 0, (category, count, costs) + + def test_the_full_view_costs_what_the_page_holds_not_what_the_container_holds(self): + """A page of five of twenty children costs as much as a container of five.""" + five = self.costs(5)["full"] + paged = self.costs(20)["full_page_of_5"] + assert (len(paged[0]), paged[1]) == (len(five[0]), five[1]) + + +class ContainerChildrenQueryCountTest(_QueryCountMixin, ModuleStoreTestCase): + """Request costs with policy-based authoring permissions off, read by course staff.""" + + def reader_for(self, course): + reader = UserFactory() + CourseStaffRole(course.id).add_users(reader) + return reader + + +class ContainerChildrenQueryCountAuthzTest(CourseAuthoringAuthzTestMixin, _QueryCountMixin, ModuleStoreTestCase): + """Request costs with policy-based authoring permissions on, read by a course auditor.""" + + def reader_for(self, course): + reader = UserFactory() + self.add_user_to_role_in_course(reader, COURSE_AUDITOR.external_key, course.id) + return reader + + +# --------------------------------------------------------------------------- +# Addresses, methods and the published schema +# --------------------------------------------------------------------------- + +UNIT_KEY = "block-v1:edX+ToyX+Toy_Course+type@vertical+block@unit" + + +@ddt.ddt +class ContainerChildrenRoutingTest(SharedModuleStoreTestCase): + """The address, the deprecated v1 addresses, and requests no route or method serves.""" + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.course = build_course(sections=1, subsections=1, units=1) + cls.unit = units_of(cls.course.id)[0] + + def test_the_address(self): + assert children_url(UNIT_KEY) == f"/api/authoring/v2/containers/{UNIT_KEY}/children/" + match = resolve(children_url(UNIT_KEY)) + assert match.view_name == "authoring_v2:container_child_list" + assert routed_actions(match.func) == {"get": "list"} + assert match.kwargs == {"usage_key": UsageKey.from_string(UNIT_KEY)} + + def test_the_container_detail_address_is_not_shadowed(self): + match = resolve(f"/api/authoring/v2/containers/{UNIT_KEY}/") + assert match.view_name == "authoring_v2:container_detail" + assert routed_actions(match.func) == {"get": "retrieve"} + + def test_the_v1_addresses_are_unchanged(self): + assert v1_url(UNIT_KEY) == f"/api/contentstore/v1/container/{UNIT_KEY}/children" + assert resolve(v1_url(UNIT_KEY)).view_name == "cms.djangoapps.contentstore:v1:container_children" + vertical = reverse("cms.djangoapps.contentstore:v1:container_vertical", kwargs={"usage_key_string": UNIT_KEY}) + assert vertical == f"/api/contentstore/v1/container/vertical/{UNIT_KEY}/children" + assert resolve(vertical).view_name == "cms.djangoapps.contentstore:v1:container_vertical" + + def test_the_v1_vertical_address_still_redirects_to_the_v1_children(self): + reader = UserFactory(is_staff=True) + vertical = reverse("cms.djangoapps.contentstore:v1:container_vertical", kwargs={"usage_key_string": UNIT_KEY}) + response = _client(reader).get(vertical) + assert response.status_code == 301 + assert response["Location"] == v1_url(UNIT_KEY) + + def test_v1_keeps_its_own_error_bodies(self): + response = _client().get(v1_url(self.unit.location)) + assert response.status_code == 401 + assert response.json() == {"detail": "Authentication credentials were not provided."} + response = _client(UserFactory()).get(v1_url("i4x://InvalidOrg/InvalidCourse/vertical/static/InvalidContent")) + assert response.status_code == 404 + + def test_the_url_name_is_unique_in_its_namespace(self): + # Imported here because it parses its converters at import time, which needs the URL conf loaded first. + authoring_urls = import_module("cms.djangoapps.contentstore.rest_api.v2.authoring_urls") + names = [pattern.name for pattern in authoring_urls.urlpatterns] + assert names.count("container_child_list") == 1 + assert len(names) == len(set(names)) + + def test_unsupported_accept_is_refused_with_406(self): + # The error library does not catalogue NotAcceptable, so it is typed + # internal. Change the expected type here once it does. + response = _client(UserFactory(is_staff=True)).get( + children_url(self.unit.location), HTTP_ACCEPT="application/xml", + ) + assert_error_envelope(response, expected_status=406, expected_type_slug="internal") + + def test_options_describes_the_endpoint(self): + response = _client(UserFactory(is_staff=True)).options(children_url(self.unit.location)) + assert response.status_code == 200 + assert response.json()["name"] == "Course Container Children" + + # These addresses match no route, so the service's HTML 404 page answers + # them. Change these to the error envelope once a catch-all route under the + # mount answers unknown addresses. + + @ddt.data("not-a-usage-key", "i4x://edX/ToyX/vertical/unit", "edX/ToyX/Toy_Course/vertical/unit") + def test_unparsable_or_deprecated_key_is_404(self, key): + response = _client(UserFactory(is_staff=True)).get(f"/api/authoring/v2/containers/{key}/children/") + assert response.status_code == 404 + assert response["Content-Type"].startswith("text/html") + + def test_the_address_without_its_trailing_slash_redirects_to_it(self): + """No route answers the address without its slash; the service redirects a read to the slashed one.""" + address = f"/api/authoring/v2/containers/{self.unit.location}/children" + response = _client(UserFactory(is_staff=True)).get(address) + assert response.status_code == 301 + assert response["Location"] == children_url(self.unit.location) + with pytest.raises(Resolver404): + resolve(f"/api/authoring/v2/containers/{self.unit.location}/children") + + +class ContainerChildrenSchemaTest(SharedModuleStoreTestCase): + """The read as published, generated from the real contentstore and authoring routes.""" + + PATH = "/api/authoring/v2/containers/{usage_key}/children/" + V1 = "/api/contentstore/v1/container/{usage_key_string}/children" + V1_VERTICAL = "/api/contentstore/v1/container/vertical/{usage_key_string}/children" + V1_HANDLER = "/api/contentstore/v1/container_handler/{usage_key_string}" + + @staticmethod + def _ref(node): + return node["$ref"].rsplit("/", 1)[-1] + + def _response_ref(self, response): + return self._ref(response["content"]["application/json"]["schema"]) + + @staticmethod + def _nullable(component): + return {name for name, field in component["properties"].items() if field.get("nullable")} + + @staticmethod + def _components(): + return _published_schema()["components"]["schemas"] + + def test_the_read_is_published_for_the_sdk(self): + schema = _published_schema() + assert list(schema["paths"][self.PATH]) == ["get"] + operation = schema["paths"][self.PATH]["get"] + assert operation["operationId"] == "v2_containers_children_list" + assert operation["tags"] == ["openedx-platform-sdk"] + assert "deprecated" not in operation + assert "x-internal" not in operation + parameters = {p["name"]: p for p in operation["parameters"]} + assert set(parameters) == {"usage_key", "view", "page", "page_size"} + assert parameters["usage_key"] == { + "in": "path", + "name": "usage_key", + "schema": {"type": "string", "pattern": "^[^/]+$"}, + "description": ( + "Usage key of a section, subsection, unit or other container of a course, such as " + "block-v1:edX+DemoX+2026+type@vertical+block@welcome." + ), + "required": True, + } + assert parameters["view"]["in"] == "query" + assert not parameters["view"].get("required") + assert parameters["view"]["schema"] == {"type": "string", "enum": ["full", "minimal"], "default": "minimal"} + assert [(name, parameters[name]["in"], parameters[name]["schema"]) for name in ("page", "page_size")] == [ + ("page", "query", {"type": "integer"}), ("page_size", "query", {"type": "integer"}), + ] + assert set(operation["responses"]) == {"200", "400", "401", "403", "404", "406"} + assert self._response_ref(operation["responses"]["200"]) == PAGE + for status in ("400", "401", "403", "404", "406"): + assert self._response_ref(operation["responses"][status]) == "ErrorResponse", status + + def test_the_page_has_all_seven_keys_around_the_two_item_shapes(self): + components = self._components() + page = components[PAGE] + assert set(page["required"]) == set(page["properties"]) == ENVELOPE_KEYS + item = {"$ref": f"#/components/schemas/{ITEM_SHAPE}"} + assert page["properties"]["results"] == {"type": "array", "items": item} + assert self._nullable(page) == {"next", "previous"} + assert {name: page["properties"][name]["type"] for name in ENVELOPE_KEYS - {"results"}} == { + "count": "integer", "num_pages": "integer", "current_page": "integer", "start": "integer", + "next": "string", "previous": "string", + } + assert components[ITEM_SHAPE] == {"oneOf": [ + {"$ref": f"#/components/schemas/{SUMMARY_SHAPE}"}, + {"$ref": f"#/components/schemas/{DETAIL_SHAPE}"}, + ]} + + def test_the_two_item_shapes(self): + components = self._components() + summary = components[SUMMARY_SHAPE] + assert set(summary["required"]) == set(summary["properties"]) == SUMMARY_KEYS + assert self._nullable(summary) == {"display_type"} + detail = components[DETAIL_SHAPE] + assert set(detail["required"]) == set(detail["properties"]) == DETAIL_KEYS + assert self._nullable(detail) == {"upstream_link"} + link = components["CourseContainerChildUpstreamLink"] + assert set(link["required"]) == set(link["properties"]) - {"ready_to_sync_children"} + assert self._nullable(link) == { + "version_synced", "version_available", "version_declined", "error_message", "top_level_parent_key", + } + actions = components["CourseContainerChildActions"] + assert set(actions["required"]) == set(actions["properties"]) == { + "can_copy", "can_duplicate", "can_move", "can_manage_access", "can_delete", "can_manage_tags", + } + assert {field["type"] for field in actions["properties"].values()} == {"boolean"} + assert self._nullable(components["CourseContainerChildUpstreamChild"]) == {"name", "upstream"} + + def test_every_field_of_the_read_is_described(self): + """Every property of every component the read references, however deep, has a description.""" + components = self._components() + reached, pending = set(), [PAGE] + while pending: + name = pending.pop() + if name not in reached: + reached.add(name) + refs = re.findall(r"'\$ref': '([^']+)'", str(components[name])) + pending.extend(ref.rsplit("/", 1)[-1] for ref in refs) + assert reached == { + PAGE, ITEM_SHAPE, SUMMARY_SHAPE, DETAIL_SHAPE, "CourseContainerChildActions", "CourseContainerChildMessage", + "CourseContainerChildUpstreamLink", "CourseContainerChildUpstreamChild", + } + # The generator swaps its own placeholder for the item type inside ``results``, so that + # one property cannot carry a description of its own. + undescribed = { + f"{name}.{field}" + for name in reached + for field, spec in components[name].get("properties", {}).items() + if not spec.get("description") + } + assert undescribed == {f"{PAGE}.results"} + + def test_the_examples_are_valid_bodies_of_their_view(self): + """Each example is one child, which the generator places in a page.""" + operation = _published_schema()["paths"][self.PATH]["get"] + examples = operation["responses"]["200"]["content"]["application/json"]["examples"] + assert set(examples) == {"Child", "ChildWithUnitPageData"} + brief = examples["Child"]["value"] + assert_page(brief, "default") + assert [item["has_children"] for item in brief["results"]] == [True] + full = examples["ChildWithUnitPageData"]["value"] + assert_page(full, "full") + assert [item["upstream_link"]["ready_to_sync"] for item in full["results"]] == [True] + assert full["results"][0]["validation_messages"][0]["type"] == "error" + + def test_the_v1_read_is_deprecated_and_the_replacement_is_not(self): + paths = _published_schema()["paths"] + operation = paths[self.V1]["get"] + assert operation["deprecated"] is True + assert operation["operationId"] == "v1_container_children_retrieve" + assert "deprecated" not in paths[self.PATH]["get"] + + def test_other_operations_are_left_as_they_were(self): + """The hook marks the exact superseded address only.""" + paths = _published_schema()["paths"] + assert paths[self.V1_HANDLER]["get"]["deprecated"] is True + assert self.V1_VERTICAL not in paths + for path in ( + "/api/authoring/v2/containers/{usage_key}/", + "/api/authoring/v2/courses/{course_key}/textbooks/", + "/api/contentstore/v0/advanced_settings/{course_id}", + ): + assert "deprecated" not in paths[path]["get"], path + + def test_the_names_the_v1_read_published_remain(self): + components = self._components() + assert {"ContainerChildren", "ContainerChild", "MessageValidation"} <= set(components) + assert { + "CourseContainerChild", "CourseContainerChildFull", "CourseContainerChildRead", PAGE, + } <= set(components) diff --git a/cms/lib/spectacular.py b/cms/lib/spectacular.py index 662cf80c65f0..ca7a248b6770 100644 --- a/cms/lib/spectacular.py +++ b/cms/lib/spectacular.py @@ -13,6 +13,8 @@ "/api/contentstore/v0/youtube_transcripts/{course_id}/check", "/api/contentstore/v0/youtube_transcripts/{course_id}/uploa", "/api/contentstore/v0/youtube_transcripts/{course_id}/upload", + # → /api/authoring/v2/containers/{usage_key}/children/ + "/api/contentstore/v1/container/{usage_key_string}/children", ) # Legacy addresses of APIs migrated to /api/authoring/, marked deprecated for diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py index 4581f23a6148..919a58057727 100644 --- a/cms/lib/tests/test_spectacular.py +++ b/cms/lib/tests/test_spectacular.py @@ -44,6 +44,10 @@ def test_the_contentstore_mount_is_still_admitted(self): assert self._admitted("/api/contentstore/v0/youtube_transcripts/course-v1:a+b+c/check") assert self._admitted("/api/contentstore/v4/home/courses/") + def test_the_container_children_mounts_are_admitted(self): + assert self._admitted("/api/authoring/v2/containers/block-v1:a+b+c+type@vertical+block@d/children/") + assert self._admitted("/api/contentstore/v1/container/block-v1:a+b+c+type@vertical+block@d/children") + def test_the_hand_listed_discussions_path_is_still_admitted(self): assert self._admitted("/api/courses/course-v1:a+b+c/bulk_enable_disable_discussions") @@ -76,12 +80,39 @@ def test_both_spellings_of_each_superseded_path_are_listed(self): "/api/contentstore/v0/youtube_transcripts/{course_id}/check", "/api/contentstore/v0/youtube_transcripts/{course_id}/uploa", "/api/contentstore/v0/youtube_transcripts/{course_id}/upload", + "/api/contentstore/v1/container/{usage_key_string}/children", } def test_the_conforming_paths_are_left_unmarked(self): - conforming = "/api/authoring/v1/courses/{course_key}/youtube_transcript_checks/" - result = self._run({"paths": {conforming: {"get": {"operationId": "x"}}}}) - assert result["paths"][conforming]["get"] == {"operationId": "x"} + for conforming in ( + "/api/authoring/v1/courses/{course_key}/youtube_transcript_checks/", + "/api/authoring/v2/containers/{usage_key}/children/", + ): + result = self._run({"paths": {conforming: {"get": {"operationId": "x"}}}}) + assert result["paths"][conforming]["get"] == {"operationId": "x"} + + def test_the_children_read_is_marked_and_the_redirect_is_not(self): + children = "/api/contentstore/v1/container/{usage_key_string}/children" + redirect = "/api/contentstore/v1/container/vertical/{usage_key_string}/children" + result = self._run({"paths": {children: {"get": {}}, redirect: {"get": {}}}}) + assert result["paths"][children]["get"] == {"deprecated": True} + assert result["paths"][redirect]["get"] == {} + + def test_the_children_read_is_marked_by_its_exact_path_and_its_replacement_is_not(self): + legacy = "/api/contentstore/v1/container/{usage_key_string}/children" + replacement = "/api/authoring/v2/containers/{usage_key}/children/" + lookalikes = ( + legacy + "/", + "/api/contentstore/v1/container/{usage_key_string}/children_summary", + "/api/contentstore/v2/container/{usage_key_string}/children", + "/api/authoring/v2/containers/{usage_key}/", + "/api/contentstore/v0/advanced_settings/{course_id}", + ) + result = self._run({"paths": {path: {"get": {}} for path in (legacy, replacement, *lookalikes)}}) + assert result["paths"][legacy]["get"] == {"deprecated": True} + assert result["paths"][replacement]["get"] == {} + for path in lookalikes: + assert result["paths"][path]["get"] == {}, path def test_an_unrelated_contentstore_path_is_left_unmarked(self): other = "/api/contentstore/v0/advanced_settings/{course_id}"