From a7e307f204caf2f07285097b7ca9bd6260824432 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Thu, 15 Oct 2026 03:41:09 +0500 Subject: [PATCH 01/61] feat: add /api/user/v2/ users, user_preferences and time_zones The user directory, the stored-preference listings and the time-zone reference list were the least conforming endpoints of the User API: the only gate was the deprecated X-Edx-Api-Key header, which ignores request.user entirely, so any holder of the key could read every user's email address and full preference mapping. The listings were addressed by database id, two of them put the parent key in the path instead of the query string, the time-zone list returned an unbounded array, the stored preference row embedded its owner's entire record (one extra query per row), and the forum-role listing created the role it was asked about on every GET. Each of those is a contract change, so they land on a new version and /api/user/v1/ is untouched and keeps serving them. What callers get instead: GET /api/user/v2/users/ (also ?preference_key=, ?forum_role=&course_key=) GET /api/user/v2/users/{username}/ GET /api/user/v2/user_preferences/ GET /api/user/v2/user_preferences/{username},{key}/ GET /api/user/v2/time_zones/ Authenticated staff callers rather than an API key, the standard error envelope, the standard pagination envelope on all three lists, filter sets and a deterministic ordering, and the ?view= and ?fields= response presets. The forum-role filter no longer creates a role, and an unparsable course key is a validation error rather than a 500. Being refused is part of the contract, so the refusals are explicit. A deactivated staff account is turned away on both paths rather than only one: the session authenticator already rejected it, but IsAdminUser reads only is_staff and the JWT authenticator does not read is_active, so such an account could read the whole directory until its token expired. These addresses require an active user. An unrecognised query parameter is a 400 rather than silence. A client porting from a superseded address by changing the version segment alone would otherwise pass a filter this version does not define, have it ignored, and receive every row believing the page was filtered. The allowlist is derived from the paginator, the ordering backend, the filter set and the query serializer, so it cannot drift away from the filters it describes. Shared building blocks are used rather than rewritten: StandardizedErrorMixin, DefaultPagination, IterablePaginationMixin, ScopedQuerysetMixin with FullScopePolicy, MinimalViewMixin and project. The two local classes each supply one predicate the library does not, and each docstring says which. The tests pin behaviour rather than structure: every allowed and every refused caller with the error type asserted, value-level parity with each superseded address, query counts that stay constant across 1, 5 and 25 rows where the superseded listing pays per row, SQL captures proving no GET writes, and the URL literals each name reverses to. --- lms/urls.py | 1 + .../core/djangoapps/user_api/v2/__init__.py | 1 + openedx/core/djangoapps/user_api/v2/errors.py | 36 + .../core/djangoapps/user_api/v2/filters.py | 178 +++ .../core/djangoapps/user_api/v2/paginators.py | 57 + .../djangoapps/user_api/v2/permissions.py | 20 + openedx/core/djangoapps/user_api/v2/schema.py | 31 + .../djangoapps/user_api/v2/serializers.py | 206 +++ .../djangoapps/user_api/v2/tests/__init__.py | 1 + .../user_api/v2/tests/test_parity.py | 374 +++++ .../user_api/v2/tests/test_query_counts.py | 178 +++ .../user_api/v2/tests/test_schema.py | 531 +++++++ .../user_api/v2/tests/test_url_mount.py | 68 + .../djangoapps/user_api/v2/tests/test_urls.py | 296 ++++ .../user_api/v2/tests/test_views.py | 1401 +++++++++++++++++ openedx/core/djangoapps/user_api/v2/urls.py | 71 + openedx/core/djangoapps/user_api/v2/views.py | 593 +++++++ 17 files changed, 4043 insertions(+) create mode 100644 openedx/core/djangoapps/user_api/v2/__init__.py create mode 100644 openedx/core/djangoapps/user_api/v2/errors.py create mode 100644 openedx/core/djangoapps/user_api/v2/filters.py create mode 100644 openedx/core/djangoapps/user_api/v2/paginators.py create mode 100644 openedx/core/djangoapps/user_api/v2/permissions.py create mode 100644 openedx/core/djangoapps/user_api/v2/schema.py create mode 100644 openedx/core/djangoapps/user_api/v2/serializers.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/__init__.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_parity.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_schema.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_urls.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_views.py create mode 100644 openedx/core/djangoapps/user_api/v2/urls.py create mode 100644 openedx/core/djangoapps/user_api/v2/views.py diff --git a/lms/urls.py b/lms/urls.py index 0e624d44981a..8a4c1cc929ae 100644 --- a/lms/urls.py +++ b/lms/urls.py @@ -142,6 +142,7 @@ path('api/courses/', include('lms.djangoapps.course_api.urls')), # User API endpoints + path('api/user/v2/', include('openedx.core.djangoapps.user_api.v2.urls')), path('api/user/', include('openedx.core.djangoapps.user_api.urls')), # Note: these are older versions of the User API that will eventually be # subsumed by api/user listed above. diff --git a/openedx/core/djangoapps/user_api/v2/__init__.py b/openedx/core/djangoapps/user_api/v2/__init__.py new file mode 100644 index 000000000000..333c1a588afe --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/__init__.py @@ -0,0 +1 @@ +"""Version 2 of the User API.""" diff --git a/openedx/core/djangoapps/user_api/v2/errors.py b/openedx/core/djangoapps/user_api/v2/errors.py new file mode 100644 index 000000000000..223f7d59e69a --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/errors.py @@ -0,0 +1,36 @@ +"""Error types this version of the User API classifies for itself.""" + +from edx_rest_framework_extensions.errors import register_error_type +from rest_framework.exceptions import MethodNotAllowed, NotAcceptable + + +class RefusedMethod(MethodNotAllowed): + """A request method this API does not serve at the address it was sent to.""" + + +class UnsatisfiableAccept(NotAcceptable): + """An ``Accept`` header naming no representation this API can produce.""" + + +register_error_type(RefusedMethod, "method-not-allowed", "Method Not Allowed") +register_error_type(UnsatisfiableAccept, "not-acceptable", "Not Acceptable") + + +class CatalogedRequestErrorsMixin: + """ + Names the error type of a refused method and of an unanswerable ``Accept`` header. + + The shared catalog classifies neither, so both would reach the caller + described as a server fault at a 4xx status. Raising this API's own + subclasses of them names each error without changing how the same failure + is classified for any other API in the process; once the shared catalog + covers them, the subclasses can give way to it. + """ + + def handle_exception(self, exc): + """Classify the two request failures the shared catalog leaves unnamed.""" + if isinstance(exc, MethodNotAllowed) and not isinstance(exc, RefusedMethod): + exc = RefusedMethod(self.request.method, detail=exc.detail) + elif isinstance(exc, NotAcceptable) and not isinstance(exc, UnsatisfiableAccept): + exc = UnsatisfiableAccept(detail=exc.detail) + return super().handle_exception(exc) diff --git a/openedx/core/djangoapps/user_api/v2/filters.py b/openedx/core/djangoapps/user_api/v2/filters.py new file mode 100644 index 000000000000..741aaee5fc12 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/filters.py @@ -0,0 +1,178 @@ +"""Filter sets for version 2 of the User API.""" + +import logging + +from django import forms +from django.contrib.auth.models import User # pylint: disable=imported-auth-user +from django.core.exceptions import ValidationError as FormValidationError +from django_filters import rest_framework as filters +from opaque_keys import InvalidKeyError +from opaque_keys.edx.keys import CourseKey +from rest_framework.exceptions import ValidationError +from rest_framework.filters import OrderingFilter + +from openedx.core.djangoapps.user_api.models import UserPreference + +log = logging.getLogger(__name__) + + +class StrictOrderingFilter(OrderingFilter): + """ + Refuses a sort field the view does not offer, and completes the sort it accepts. + + The default backend drops an unusable field silently and answers 200 in + the default order, which a caller reads as a page sorted the way it asked. + It also replaces the view's own order rather than adding to it, so a sort + on a column several rows share leaves their relative order to the database + and the pages of one listing need not agree on it; the fields named by the + view's ``ordering_tiebreak`` are appended to settle those rows. + """ + + def get_ordering(self, request, queryset, view): + """Return the requested sort, followed by the fields that make it total.""" + ordering = super().get_ordering(request, queryset, view) + if not ordering: + return ordering + chosen = {field.lstrip("-") for field in ordering} + tiebreak = [field for field in getattr(view, "ordering_tiebreak", ()) if field not in chosen] + return [*ordering, *tiebreak] + + def remove_invalid_fields(self, queryset, fields, view, request): + """Return the requested sort fields, refusing the request when one is not offered.""" + allowed = super().remove_invalid_fields(queryset, fields, view, request) + rejected = [field for field in fields if field not in allowed] + if rejected: + log.info("Sort refused on %s: %r", type(view).__name__, rejected) + offered = sorted( + name for name, _label in self.get_valid_fields(queryset, view, {"request": request}) + ) + raise ValidationError({ + "ordering": [ + f"Sort by any of: {', '.join(offered)}, each optionally prefixed with '-'.", + ], + }) + return allowed + + +class _BooleanQueryField(forms.NullBooleanField): + """Reads a boolean out of the query string, refusing a value that names neither side.""" + + def to_python(self, value): + """Return the boolean this value names, or refuse the request.""" + if value in self.empty_values: + return None + parsed = super().to_python(value) + if parsed is None: + raise FormValidationError("Enter true or false.", code="invalid") + return parsed + + +class StrictBooleanFilter(filters.BooleanFilter): + """ + Refuses a value that names neither true nor false instead of ignoring it. + + The default field reads an unrecognised value as "no preference" and + answers 200 with the filter dropped, handing the caller the rows it asked + to leave out, which is the opposite of what it asked for. + """ + + field_class = _BooleanQueryField + + def __init__(self, *args, **kwargs): + """Pass the raw value through to the field, which is what judges it.""" + # The default widget maps anything it does not recognise to "no + # preference" before the field ever sees it; a text widget hands the + # value over untouched. + kwargs.setdefault("widget", forms.TextInput) + super().__init__(*args, **kwargs) + + +class UserFilterSet(filters.FilterSet): + """ + Narrows the user directory. + + ``forum_role`` and ``course_key`` name a role within one course and are + only meaningful together, so either on its own is rejected. A role that no + course has defined matches no users and is not created. + """ + + username = filters.CharFilter(help_text="Return the user with exactly this username.") + email = filters.CharFilter(help_text="Return the user with exactly this email address.") + is_active = StrictBooleanFilter( + help_text="Return only users whose account is active, or only inactive ones. true or false.", + ) + preference_key = filters.CharFilter( + method="filter_preference_key", + help_text="Return only users who have stored a preference with this key.", + ) + forum_role = filters.CharFilter( + method="filter_forum_role", + help_text="Return only users holding this course forum role. Requires course_key.", + ) + course_key = filters.CharFilter( + method="filter_course_key", + help_text=( + "Course the forum role belongs to, percent-encoded, for example " + "course-v1:edX%2BDemoX%2BDemo. A plus sign that is not encoded arrives as a " + "space and the key is refused. Requires forum_role." + ), + ) + + class Meta: + model = User + fields = ("username", "email", "is_active", "preference_key", "forum_role", "course_key") + + def filter_queryset(self, queryset): + """Reject a forum role without its course, or a course without its role, before filtering.""" + cleaned = self.form.cleaned_data + forum_role = cleaned.get("forum_role") + course_key = cleaned.get("course_key") + if forum_role and not course_key: + raise ValidationError({"course_key": ["This parameter is required when forum_role is supplied."]}) + if course_key and not forum_role: + raise ValidationError({"forum_role": ["This parameter is required when course_key is supplied."]}) + return super().filter_queryset(queryset) + + def filter_preference_key(self, queryset, name, value): # pylint: disable=unused-argument + """Keep users who have stored a preference under ``value``.""" + return queryset.filter(preferences__key=value) + + def filter_forum_role(self, queryset, name, value): # pylint: disable=unused-argument + """ + Keep users holding the role ``value`` in the course named by ``course_key``. + + Nothing stops a course from carrying the same role under several rows, + and a user may hold any number of them, so the join is collapsed to one + entry per user. + """ + raw_course_key = self.form.cleaned_data.get("course_key") + try: + course_key = CourseKey.from_string(raw_course_key) + except InvalidKeyError as exc: + log.info("User directory filtered with an unparsable course key: %r", raw_course_key) + raise ValidationError({"course_key": ["Enter a valid course key."]}) from exc + return queryset.filter(roles__name=value, roles__course_id=course_key).distinct() + + def filter_course_key(self, queryset, name, value): # pylint: disable=unused-argument + """Narrowing happens in ``filter_forum_role``, which needs both values at once.""" + return queryset + + +class UserPreferenceFilterSet(filters.FilterSet): + """ + Narrows the stored-preference list by preference name or by owner. + + An owner is named by username: the list is keyed the way the addresses of + its members are, and publishes no database identifier for a caller to + filter on. + """ + + key = filters.CharFilter(help_text="Return only preferences stored under exactly this key.") + username = filters.CharFilter( + field_name="user__username", + help_text="Return only preferences belonging to this user.", + ) + + class Meta: + model = UserPreference + fields = ("key", "username") diff --git a/openedx/core/djangoapps/user_api/v2/paginators.py b/openedx/core/djangoapps/user_api/v2/paginators.py new file mode 100644 index 000000000000..5e796180d3cb --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/paginators.py @@ -0,0 +1,57 @@ +"""Pagination for version 2 of the User API.""" + +from edx_rest_framework_extensions.paginators import DefaultPagination + + +class UserApiPagination(DefaultPagination): + """ + Page-number pagination whose published schema matches the body it returns. + + ``DefaultPagination`` answers with ``count``, ``num_pages``, + ``current_page``, ``start``, ``next``, ``previous`` and ``results`` but + inherits the four-member schema of DRF's ``PageNumberPagination``, so a + generated client would not know about the three page-position members. + This subclass only restates the response schema; the body is unchanged. + """ + + def get_paginated_response_schema(self, schema): + """Describe the full envelope the paginator returns.""" + return { + "type": "object", + "required": ["count", "num_pages", "current_page", "start", "results"], + "properties": { + "count": { + "type": "integer", + "example": 123, + "description": "Total number of items across every page.", + }, + "num_pages": { + "type": "integer", + "example": 13, + "description": "Total number of pages.", + }, + "current_page": { + "type": "integer", + "example": 2, + "description": "Number of the page in this response, counting from one.", + }, + "start": { + "type": "integer", + "example": 10, + "description": "Index of the first item of this page within the full result set.", + }, + "next": { + "type": "string", + "nullable": True, + "format": "uri", + "description": "URL of the next page, or null on the last page.", + }, + "previous": { + "type": "string", + "nullable": True, + "format": "uri", + "description": "URL of the previous page, or null on the first page.", + }, + "results": schema, + }, + } diff --git a/openedx/core/djangoapps/user_api/v2/permissions.py b/openedx/core/djangoapps/user_api/v2/permissions.py new file mode 100644 index 000000000000..80e78b269541 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/permissions.py @@ -0,0 +1,20 @@ +"""Permission classes for version 2 of the User API.""" + +from rest_framework.permissions import BasePermission + + +class IsActiveUser(BasePermission): + """ + Admits only a caller whose account is still active. + + The authenticated and administrator checks read ``is_authenticated`` and + ``is_staff``, and neither reads ``is_active``. A token stays valid until it + expires and is accepted without the account being re-read for it, so an + account deactivated after a token was issued keeps every access that token + carries unless the account's state is checked here. edx-drf-extensions + ships no equivalent class, so this one stands in for it. + """ + + def has_permission(self, request, view): + """Return whether the caller's account is still active.""" + return bool(request.user and request.user.is_active) diff --git a/openedx/core/djangoapps/user_api/v2/schema.py b/openedx/core/djangoapps/user_api/v2/schema.py new file mode 100644 index 000000000000..1db961213b16 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/schema.py @@ -0,0 +1,31 @@ +"""Schema helpers for version 2 of the User API.""" + +from drf_spectacular.serializers import PolymorphicProxySerializerExtension +from drf_spectacular.utils import PolymorphicProxySerializer + + +class ResponseShapes(PolymorphicProxySerializer): + """ + The set of bodies one operation returns for the same status code. + + An endpoint whose caller can reduce the response answers with the default + object, with a preset, or with a selection of properties. A reduced body + satisfies more than one of those descriptions, so they are published as + alternatives a body may match in any combination. + """ + + def __init__(self, component_name, serializers, **kwargs): + # The generator re-instantiates a declaration from the arguments it + # retained, so the discriminator is only supplied when it is missing. + kwargs.setdefault("resource_type_field_name", None) + super().__init__(component_name=component_name, serializers=serializers, **kwargs) + + +class ResponseShapesExtension(PolymorphicProxySerializerExtension): + """Publishes the alternatives of a ``ResponseShapes`` declaration.""" + + target_class = ResponseShapes + + def map_serializer(self, auto_schema, direction): + """Return the alternatives as a set a body may match more than one of.""" + return {"anyOf": super().map_serializer(auto_schema, direction)["oneOf"]} diff --git a/openedx/core/djangoapps/user_api/v2/serializers.py b/openedx/core/djangoapps/user_api/v2/serializers.py new file mode 100644 index 000000000000..8c418252640d --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/serializers.py @@ -0,0 +1,206 @@ +"""Serializers for version 2 of the User API.""" + +from django.contrib.auth.models import User # pylint: disable=imported-auth-user +from django.urls import reverse +from drf_spectacular.utils import extend_schema_field +from edx_rest_framework_extensions.errors import ErrorResponseSerializer +from rest_framework import serializers + +from openedx.core.djangoapps.user_api.models import UserPreference + +#: Value of the ``view`` query parameter that embeds the owning user in each preference. +FULL_VIEW = "full" + +#: Value of the ``view`` query parameter that reduces a user to its identifying fields. +MINIMAL_VIEW = "minimal" + +#: Properties the ``minimal`` preset keeps of a directory entry. +USER_MINIMAL_FIELDS = ("id", "username", "email") + +#: Properties the ``minimal`` preset keeps of a stored preference. +PREFERENCE_MINIMAL_FIELDS = ("username", "key", "value") + + +class ErrorResponse(ErrorResponseSerializer): # pylint: disable=abstract-method + """ + The body of every unsuccessful response. + + ``type`` is a URI naming the kind of failure, ``title`` names it in one + line, ``status`` repeats the HTTP status code and ``detail`` explains what + happened; ``errors`` lists the per-field messages of a rejected parameter. + """ + + +class _KeptFieldsMixin: + """ + Describes an object reduced to the properties named in ``kept_fields``. + + The response presets reduce an already serialized object, so a preset's + shape has a describing serializer of its own rather than a serializing one. + """ + + #: Names of the properties the preset returns. + kept_fields = () + + def get_fields(self): + """Return the declared fields narrowed to the ones the preset returns.""" + fields = super().get_fields() + return {name: field for name, field in fields.items() if name in self.kept_fields} + + +class _OptionalFieldsMixin: + """ + Describes an object whose every property is optional. + + A caller that selects properties with ``fields`` decides which ones come + back, so none of them is guaranteed to be present. + """ + + def get_fields(self): + """Return the declared fields, none of them mandatory.""" + fields = super().get_fields() + for field in fields.values(): + field.required = False + field.read_only = False + return fields + + +def full_view_requested(request): + """Return True when the caller asked for the embedded-user response preset.""" + if request is None: + return False + params = getattr(request, "query_params", None) + if params is None: + params = getattr(request, "GET", {}) + return params.get("view") == FULL_VIEW + + +class UserDirectorySerializer(serializers.ModelSerializer): + """A user of the platform directory, addressed by username.""" + + id = serializers.IntegerField( + read_only=True, + help_text="Database identifier of the user. Addresses in this API use the username instead.", + ) + url = serializers.HyperlinkedIdentityField( + view_name="user_v2:user_detail", + lookup_field="username", + help_text="Absolute URL of this user's directory entry.", + ) + email = serializers.EmailField(read_only=True, help_text="Registered email address of the user.") + username = serializers.CharField(read_only=True, help_text="Unique name the user is addressed by.") + name = serializers.SerializerMethodField( + help_text="Full name recorded on the user's profile, or null when the user has no profile.", + ) + preferences = serializers.SerializerMethodField( + help_text="The user's stored preferences, as a mapping of preference key to value.", + ) + + class Meta: + model = User + fields = ("id", "url", "email", "name", "username", "preferences") + read_only_fields = fields + + @extend_schema_field(serializers.CharField(allow_null=True)) + def get_name(self, user): + """Return the profile name, or None for a user who has no profile row.""" + profile = getattr(user, "profile", None) + return profile.name if profile is not None else None + + @extend_schema_field(serializers.DictField(child=serializers.CharField())) + def get_preferences(self, user): + """Return the user's preferences as a key-to-value mapping.""" + return UserPreference.get_all_preferences(user) + + +class UserDirectoryMinimalSerializer(_KeptFieldsMixin, UserDirectorySerializer): + """A directory entry reduced to the properties that identify the user.""" + + kept_fields = USER_MINIMAL_FIELDS + + +class UserDirectoryProjectionSerializer(_OptionalFieldsMixin, UserDirectorySerializer): + """A directory entry reduced to the properties the caller selected.""" + + +class UserPreferenceRecordSerializer(serializers.ModelSerializer): + """ + A stored preference, identified by the user that owns it and its key. + + ``user`` carries the owner's whole directory entry and is included only + when the caller asks for the ``full`` response preset; by default the + owner appears as the ``username`` string alone. + """ + + url = serializers.SerializerMethodField(help_text="Absolute URL of this preference.") + username = serializers.CharField( + source="user.username", + read_only=True, + help_text="Username of the user this preference belongs to.", + ) + key = serializers.CharField(read_only=True, help_text="Name of the preference.") + value = serializers.CharField(read_only=True, help_text="Stored value of the preference.") + user = serializers.SerializerMethodField( + help_text="Directory entry of the owning user; null unless the full response preset is asked for.", + ) + + class Meta: + model = UserPreference + fields = ("username", "key", "value", "url", "user") + read_only_fields = fields + + @extend_schema_field(serializers.URLField()) + def get_url(self, preference): + """Return the member address of this preference.""" + path = reverse( + "user_v2:user_preference_detail", + kwargs={"username": preference.user.username, "key": preference.key}, + ) + request = self.context.get("request") + return request.build_absolute_uri(path) if request is not None else path + + @extend_schema_field(UserDirectorySerializer(allow_null=True)) + def get_user(self, preference): + """Embed the owner only when the caller asked for the full preset.""" + if not full_view_requested(self.context.get("request")): + return None + return UserDirectorySerializer(preference.user, context=self.context).data + + +class UserPreferenceRecordMinimalSerializer(_KeptFieldsMixin, UserPreferenceRecordSerializer): + """A stored preference reduced to its owner, its name and its value.""" + + kept_fields = PREFERENCE_MINIMAL_FIELDS + + +class UserPreferenceRecordProjectionSerializer(_OptionalFieldsMixin, UserPreferenceRecordSerializer): + """A stored preference reduced to the properties the caller selected.""" + + +class TimeZoneSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A time zone and the way it is displayed to a learner.""" + + time_zone = serializers.CharField(help_text="Name of the time zone, for example ``US/Pacific``.") + description = serializers.CharField( + help_text="Display form of the time zone, for example ``US/Pacific (PST, UTC-0800)``.", + ) + + +class TimeZoneQuerySerializer(serializers.Serializer): # pylint: disable=abstract-method + """Query parameters accepted by the time-zone list.""" + + country_code = serializers.RegexField( + r"^[A-Za-z]{2}$", + required=False, + # An empty value narrows nothing, the way an empty value of any other + # parameter does, and is accepted rather than held to the pattern. + allow_blank=True, + error_messages={ + "invalid": "Enter a two-letter ISO 3166-1 alpha-2 country code, for example FR.", + }, + help_text=( + "Two-letter ISO 3166-1 alpha-2 country code, case-insensitive. " + "Every time zone is returned when it is omitted or left empty, and when " + "the code names a country with no time zones of its own." + ), + ) diff --git a/openedx/core/djangoapps/user_api/v2/tests/__init__.py b/openedx/core/djangoapps/user_api/v2/tests/__init__.py new file mode 100644 index 000000000000..61ab32b09c15 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/__init__.py @@ -0,0 +1 @@ +"""Tests for version 2 of the User API.""" diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_parity.py new file mode 100644 index 000000000000..38a75fe6bd13 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_parity.py @@ -0,0 +1,374 @@ +"""Behaviour parity between the version 1 and version 2 User API addresses.""" + +import json + +import pytest +from django.contrib.auth.models import User # pylint: disable=imported-auth-user +from django.core.exceptions import ObjectDoesNotExist +from django.test.utils import override_settings +from django.urls import reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from opaque_keys import InvalidKeyError +from opaque_keys.edx.keys import CourseKey +from rest_framework import status +from rest_framework.test import APITestCase + +from common.djangoapps.student.tests.factories import AdminFactory, UserFactory +from openedx.core.djangoapps.django_comment_common.models import Role +from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangolib.testing.utils import skip_unless_lms + +PASSWORD = "Password1234" +API_KEY = "parity-test-api-key" +COURSE_KEY = CourseKey.from_string("course-v1:edX+DemoX+Demo") + +#: Fields that legitimately differ per request and are ignored in the diff. +VOLATILE_FIELDS = {"instance", "next", "previous"} + +#: Differences the plan declares intentional, per case. Each entry is a +#: (json path, reason) pair and the diff must contain all of them and nothing else. +INTENTIONAL_DIFFERENCES = { + "user_list": [ + ("results[0].url", "the member address is keyed by username instead of database id"), + ("results[1].url", "the member address is keyed by username instead of database id"), + ], + "user_detail": [ + ("url", "the member address is keyed by username instead of database id"), + ], + "preference_list": [ + ( + "results[0].user", + "the embedded owner is a member of every row and is null unless the full preset is asked for", + ), + ("results[0].username", "the owner's username is carried in place of the embedded user object"), + ("results[0].url", "the member address is keyed by username and preference key"), + ( + "results[1].user", + "the embedded owner is a member of every row and is null unless the full preset is asked for", + ), + ("results[1].username", "the owner's username is carried in place of the embedded user object"), + ("results[1].url", "the member address is keyed by username and preference key"), + ], + "preference_detail": [ + ("user", "the embedded owner is a member of every row and is null unless the full preset is asked for"), + ("username", "the owner's username is carried in place of the embedded user object"), + ("url", "the member address is keyed by username and preference key"), + ], + "preference_key_filter": [ + ("results[0].url", "the member address is keyed by username instead of database id"), + ], + "forum_role_filter": [ + ("results[0].url", "the member address is keyed by username instead of database id"), + ], +} + + +def normalize(obj, path=""): + """Sort keys, drop volatile fields, and collect a {json path: value} map for diffing.""" + flat = {} + if isinstance(obj, dict): + for key in sorted(obj): + if key in VOLATILE_FIELDS: + continue + flat.update(normalize(obj[key], f"{path}.{key}" if path else key)) + elif isinstance(obj, list): + for index, item in enumerate(obj): + flat.update(normalize(item, f"{path}[{index}]")) + else: + flat[path] = obj + return flat + + +def diff(legacy, new): + """Return (every changed path, the changed paths no declared difference covers).""" + left, right = normalize(legacy), normalize(new) + return {key for key in set(left) | set(right) if left.get(key, "") != right.get(key, "")} + + +def unexpected(changed, intentional): + """Return the changed paths that no declared intentional difference covers.""" + declared = {path for path, _reason in intentional} + return { + key for key in changed + if not any(key == path or key.startswith(path + ".") or key.startswith(path + "[") for path in declared) + } + + +@skip_unless_lms +@override_settings(EDX_API_KEY=API_KEY) +class ParityTests(APITestCase): + """The same fixtures through the legacy and the conforming address.""" + + def setUp(self): + super().setUp() + self.admin = AdminFactory.create(username="parity-admin", password=PASSWORD) + self.user = UserFactory.create( + username="parity-user", email="parity-user@example.com", password=PASSWORD, + ) + self.preference = UserPreferenceFactory.create(user=self.user, key="pref-lang", value="en") + role = Role.objects.create(course_id=COURSE_KEY, name="Moderator") + role.users.add(self.user) + + def legacy(self, address, params=None): + """Call a version 1 address with the API key it is gated by.""" + return self.client.get(address, params or {}, HTTP_X_EDX_API_KEY=API_KEY) + + def conforming(self, address, params=None): + """Call a version 2 address as the administrator it is gated by.""" + assert self.client.login(username=self.admin.username, password=PASSWORD) + response = self.client.get(address, params or {}) + self.client.logout() + return response + + def assert_parity(self, legacy, new, case, expected_status=status.HTTP_200_OK): + """ + Assert the two bodies differ only where the case declares they do. + + Rows are compared where each version put them, so a page whose rows + move is a difference like any other and has to be declared. + """ + assert legacy.status_code == expected_status, legacy.content + assert new.status_code == expected_status, new.content + legacy_body = json.loads(legacy.content) + new_body = json.loads(new.content) + changed = diff(legacy_body, new_body) + intentional = INTENTIONAL_DIFFERENCES[case] + assert not unexpected(changed, intentional), ( + f"undeclared differences: {sorted(unexpected(changed, intentional))}\n" + f"legacy={legacy_body}\nnew={new_body}" + ) + for path, reason in intentional: + assert any( + key == path or key.startswith(path + ".") or key.startswith(path + "[") + for key in changed + ), f"declared difference did not occur: {path} ({reason})" + + def test_user_list_parity(self): + legacy = self.legacy("/api/user/v1/users/", {"page_size": 100}) + new = self.conforming(reverse("user_v2:user_list"), {"page_size": 100}) + self.assert_parity(legacy, new, "user_list") + + def test_the_conforming_page_is_ordered_by_username_whatever_the_creation_order(self): + """Version 1 applies no ordering, so only the conforming side can be pinned to a sequence.""" + for username in ("parity-zulu", "parity-alpha"): + UserFactory.create(username=username, email=f"{username}@example.com", password=PASSWORD) + + new = self.conforming(reverse("user_v2:user_list"), {"page_size": 100}) + usernames = [row["username"] for row in json.loads(new.content)["results"]] + assert usernames == ["parity-admin", "parity-alpha", "parity-user", "parity-zulu"] + + legacy = self.legacy("/api/user/v1/users/", {"page_size": 100}) + legacy_usernames = [row["username"] for row in json.loads(legacy.content)["results"]] + assert sorted(legacy_usernames) == usernames + + def test_the_api_key_admits_at_the_legacy_addresses_only(self): + """The header the version 1 addresses are gated by is not a credential at version 2.""" + legacy = self.legacy("/api/user/v1/users/", {"page_size": 100}) + assert legacy.status_code == status.HTTP_200_OK, legacy.content + assert sorted(row["username"] for row in json.loads(legacy.content)["results"]) == [ + "parity-admin", "parity-user", + ] + + for address in ( + reverse("user_v2:user_list"), + reverse("user_v2:user_detail", kwargs={"username": "parity-user"}), + reverse("user_v2:user_preference_list"), + reverse( + "user_v2:user_preference_detail", + kwargs={"username": "parity-user", "key": "pref-lang"}, + ), + ): + refused = self.client.get(address, HTTP_X_EDX_API_KEY=API_KEY) + envelope = assert_error_envelope( + refused, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + assert envelope["detail"] == "Authentication credentials were not provided.", address + + def test_user_detail_parity(self): + legacy = self.legacy(f"/api/user/v1/users/{self.user.id}/") + new = self.conforming(reverse("user_v2:user_detail", kwargs={"username": "parity-user"})) + self.assert_parity(legacy, new, "user_detail") + + def test_preference_list_parity(self): + """More than one row, so the comparison pairs rows rather than reading a single one.""" + UserPreferenceFactory.create(user=self.user, key="pref-time", value="UTC") + legacy = self.legacy("/api/user/v1/user_prefs/", {"page_size": 100}) + new = self.conforming(reverse("user_v2:user_preference_list"), {"page_size": 100}) + assert len(json.loads(new.content)["results"]) == 2 + self.assert_parity(legacy, new, "preference_list") + + def test_the_conforming_preference_page_is_ordered_by_owner_and_key(self): + """Version 1 applies no ordering, so only the conforming side can be pinned to a sequence.""" + UserPreferenceFactory.create(user=self.user, key="pref-time", value="UTC") + UserPreferenceFactory.create(user=self.admin, key="pref-zone", value="UTC") + + new = self.conforming(reverse("user_v2:user_preference_list"), {"page_size": 100}) + rows = [(row["username"], row["key"]) for row in json.loads(new.content)["results"]] + assert rows == [ + ("parity-admin", "pref-zone"), + ("parity-user", "pref-lang"), + ("parity-user", "pref-time"), + ] + + legacy = self.legacy("/api/user/v1/user_prefs/", {"page_size": 100}) + legacy_rows = [ + (row["user"]["username"], row["key"]) for row in json.loads(legacy.content)["results"] + ] + assert legacy_rows == [ + ("parity-user", "pref-lang"), + ("parity-user", "pref-time"), + ("parity-admin", "pref-zone"), + ] + assert sorted(legacy_rows) == rows + + def test_preference_detail_parity(self): + legacy = self.legacy(f"/api/user/v1/user_prefs/{self.preference.id}/") + new = self.conforming( + reverse( + "user_v2:user_preference_detail", + kwargs={"username": "parity-user", "key": "pref-lang"}, + ), + ) + self.assert_parity(legacy, new, "preference_detail") + + def test_preference_key_filter_parity(self): + legacy = self.legacy("/api/user/v1/preferences/pref-lang/users/", {"page_size": 100}) + new = self.conforming( + reverse("user_v2:user_list"), {"preference_key": "pref-lang", "page_size": 100}, + ) + self.assert_parity(legacy, new, "preference_key_filter") + + def test_forum_role_filter_parity(self): + legacy = self.legacy( + "/api/user/v1/forum_roles/Moderator/users/", + {"course_id": str(COURSE_KEY), "page_size": 100}, + ) + new = self.conforming( + reverse("user_v2:user_list"), + {"forum_role": "Moderator", "course_key": str(COURSE_KEY), "page_size": 100}, + ) + self.assert_parity(legacy, new, "forum_role_filter") + + def test_full_preset_reproduces_the_legacy_embedded_user(self): + legacy = self.legacy(f"/api/user/v1/user_prefs/{self.preference.id}/") + new = self.conforming( + reverse( + "user_v2:user_preference_detail", + kwargs={"username": "parity-user", "key": "pref-lang"}, + ), + {"view": "full"}, + ) + legacy_user = json.loads(legacy.content)["user"] + new_user = json.loads(new.content)["user"] + assert set(legacy_user) == set(new_user) + for field in ("id", "email", "name", "username", "preferences"): + assert legacy_user[field] == new_user[field], field + assert legacy_user["url"].endswith(f"/user_api/v1/users/{self.user.id}/") + assert new_user["url"].endswith("/api/user/v2/users/parity-user/") + + def test_a_user_without_a_profile_is_a_row_here_and_a_failure_at_version_one(self): + """Declared difference: the version 1 entry cannot render a user who has no profile row.""" + profileless = User.objects.create_user("parity-profileless", "pp@example.com", PASSWORD) + with pytest.raises(ObjectDoesNotExist): + self.legacy(f"/api/user/v1/users/{profileless.id}/") + + new = self.conforming( + reverse("user_v2:user_detail", kwargs={"username": "parity-profileless"}), + ) + assert new.status_code == status.HTTP_200_OK + body = json.loads(new.content) + assert body["name"] is None + assert body["username"] == "parity-profileless" + + def test_time_zone_rows_are_unchanged_inside_the_new_envelope(self): + legacy = json.loads(self.legacy("/api/user/v1/preferences/time_zones/").content) + new = json.loads(self.conforming(reverse("user_v2:time_zone_list"), {"page_size": 100}).content) + assert isinstance(legacy, list) + assert new["count"] == len(legacy) + assert new["results"] == legacy[:100] + + def test_country_filtered_time_zones_are_unchanged(self): + legacy = json.loads( + self.legacy("/api/user/v1/preferences/time_zones/", {"country_code": "FR"}).content, + ) + new = json.loads( + self.conforming(reverse("user_v2:time_zone_list"), {"country_code": "FR"}).content, + ) + assert new["results"] == legacy + + def test_unauthenticated_bodies_differ_as_declared(self): + legacy = self.client.get("/api/user/v1/users/") + assert legacy.status_code == status.HTTP_401_UNAUTHORIZED + assert json.loads(legacy.content) == { + "detail": "Authentication credentials were not provided.", + } + + new = self.client.get(reverse("user_v2:user_list")) + envelope = assert_error_envelope( + new, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + assert envelope["title"] == "Authentication Required" + assert envelope["detail"] == "Authentication credentials were not provided." + assert envelope["instance"] == "/api/user/v2/users/" + + def test_forbidden_bodies_differ_as_declared(self): + assert self.client.login(username=self.user.username, password=PASSWORD) + legacy = self.client.get("/api/user/v1/users/") + assert legacy.status_code == status.HTTP_403_FORBIDDEN + assert json.loads(legacy.content) == { + "detail": "You do not have permission to perform this action.", + } + + new = self.client.get(reverse("user_v2:user_list")) + envelope = assert_error_envelope( + new, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + assert envelope["title"] == "Permission Denied" + assert envelope["detail"] == "You do not have permission to perform this action." + + def test_a_missing_course_parameter_keeps_its_status_and_changes_its_body(self): + """The legacy address already refused this caller; only the shape of the refusal moves.""" + legacy = self.legacy("/api/user/v1/forum_roles/Moderator/users/") + assert legacy.status_code == status.HTTP_400_BAD_REQUEST + assert json.loads(legacy.content) == {"detail": "course_id must be specified"} + + new = self.conforming(reverse("user_v2:user_list"), {"forum_role": "Moderator"}) + envelope = assert_error_envelope( + new, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "course_key": ["This parameter is required when forum_role is supplied."], + } + + def test_an_unparsable_course_parameter_is_answered_rather_than_raised(self): + """Declared difference: the version 1 address lets the key error escape the handler.""" + with pytest.raises(InvalidKeyError): + self.legacy("/api/user/v1/forum_roles/Moderator/users/", {"course_id": "not a course"}) + + new = self.conforming( + reverse("user_v2:user_list"), {"forum_role": "Moderator", "course_key": "not a course"}, + ) + envelope = assert_error_envelope( + new, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"course_key": ["Enter a valid course key."]} + + def test_a_database_identifier_is_refused_instead_of_narrowing_nothing(self): + """The directory is keyed by username, and says so rather than answering an unfiltered page.""" + refused = self.conforming(reverse("user_v2:user_list"), {"id": self.user.id, "page_size": 100}) + envelope = assert_error_envelope( + refused, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert sorted(envelope["errors"]) == ["id"] + + def test_an_identifier_held_by_a_caller_resolves_to_the_username_the_entry_is_keyed_by(self): + """The step an integration holding identifiers takes before addressing an entry.""" + assert self.client.login(username=self.admin.username, password=PASSWORD) + resolved = self.client.get("/api/user/v1/accounts", {"lms_user_id": self.user.id}) + self.client.logout() + assert resolved.status_code == status.HTTP_200_OK + assert [account["username"] for account in json.loads(resolved.content)] == ["parity-user"] + + entry = self.conforming(reverse("user_v2:user_detail", kwargs={"username": "parity-user"})) + assert entry.status_code == status.HTTP_200_OK + assert json.loads(entry.content)["id"] == self.user.id diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py b/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py new file mode 100644 index 000000000000..e8cc522fa8f1 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py @@ -0,0 +1,178 @@ +"""Query-count guards for the version 2 User API list and member addresses.""" + +import pytest +from django.test.utils import override_settings +from django.urls import reverse + +from common.djangoapps.student.tests.factories import AdminFactory, UserFactory +from openedx.core.djangoapps.django_comment_common.models import Role +from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangolib.testing.utils import skip_unless_lms + +PASSWORD = "Password1234" +COURSE_KEY = "course-v1:edX+DemoX+Demo" + +#: Row counts a per-row query would show up at. +ROW_COUNTS = [1, 5, 25] + +#: Page sizes a per-item query would show up at, for the list whose rows are +#: not database rows and whose size is therefore set by the page alone. +PAGE_SIZES = [1, 10, 100] + +USER_LIST_QUERIES = 16 +USER_DETAIL_QUERIES = 15 +PREFERENCE_LIST_QUERIES = 15 +PREFERENCE_LIST_FULL_VIEW_QUERIES = 16 +PREFERENCE_DETAIL_QUERIES = 14 +TIME_ZONE_LIST_QUERIES = 13 + +#: Address of the stored-preference list this version replaces, and the key it +#: is gated by, so the cost of the two can be compared in one measurement. +EARLIER_PREFERENCE_LIST = "/api/user/v1/user_prefs/" +EARLIER_API_KEY = "query-count-api-key" + +#: What that list costs for a page holding two rows per user, measured the same +#: way as the counts above: a constant part plus five queries for every user on +#: the page, because each row fetches its owner, the owner's profile and the +#: owner's own preferences again. +EARLIER_PREFERENCE_LIST_QUERIES = {1: 15, 5: 35, 25: 135} + + +@pytest.fixture(name="directory") +@skip_unless_lms +def directory_fixture(request, client, django_user_model): # pylint: disable=unused-argument + """Sign an administrator in and populate the directory with ``request.param`` users.""" + admin = AdminFactory.create(username="count-admin", password=PASSWORD) + users = [UserFactory.create(username=f"counted{index}") for index in range(request.param)] + for user in users: + UserPreferenceFactory.create(user=user, key="pref-lang", value="en") + UserPreferenceFactory.create(user=user, key="time_zone", value="UTC") + role = Role.objects.create(course_id=COURSE_KEY, name="Moderator") + role.users.add(*users) + assert client.login(username=admin.username, password=PASSWORD) + # The first authenticated request of a session populates caches the rest + # of the session reuses; the counts below are the steady-state ones. + client.get(reverse("user_v2:user_list")) + return users + + +@pytest.mark.django_db +@pytest.mark.parametrize("directory", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_user_list_query_count_does_not_grow_with_rows(client, directory, django_assert_num_queries): + url = reverse("user_v2:user_list") + with django_assert_num_queries(USER_LIST_QUERIES): + response = client.get(url, {"page_size": 100}) + assert len(response.json()["results"]) == len(directory) + 1 + + +@pytest.mark.django_db +@pytest.mark.parametrize("directory", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_preference_key_filter_query_count_does_not_grow_with_rows( + client, directory, django_assert_num_queries, +): + url = reverse("user_v2:user_list") + with django_assert_num_queries(USER_LIST_QUERIES): + response = client.get(url, {"preference_key": "pref-lang", "page_size": 100}) + assert len(response.json()["results"]) == len(directory) + + +@pytest.mark.django_db +@pytest.mark.parametrize("directory", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_forum_role_filter_query_count_does_not_grow_with_rows( + client, directory, django_assert_num_queries, +): + url = reverse("user_v2:user_list") + with django_assert_num_queries(USER_LIST_QUERIES): + response = client.get( + url, {"forum_role": "Moderator", "course_key": COURSE_KEY, "page_size": 100}, + ) + assert len(response.json()["results"]) == len(directory) + + +@pytest.mark.django_db +@pytest.mark.parametrize("directory", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_preference_list_query_count_does_not_grow_with_rows( + client, directory, django_assert_num_queries, +): + url = reverse("user_v2:user_preference_list") + with django_assert_num_queries(PREFERENCE_LIST_QUERIES): + response = client.get(url, {"page_size": 100}) + assert len(response.json()["results"]) == 2 * len(directory) + + +@pytest.mark.django_db +@pytest.mark.parametrize("directory", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_preference_list_full_view_query_count_does_not_grow_with_rows( + client, directory, django_assert_num_queries, +): + url = reverse("user_v2:user_preference_list") + with django_assert_num_queries(PREFERENCE_LIST_FULL_VIEW_QUERIES): + response = client.get(url, {"page_size": 100, "view": "full"}) + rows = response.json()["results"] + assert len(rows) == 2 * len(directory) + assert rows[0]["user"]["preferences"] == {"pref-lang": "en", "time_zone": "UTC"} + + +@pytest.mark.django_db +@pytest.mark.parametrize("page_size", PAGE_SIZES) +@pytest.mark.parametrize("directory", [1], indirect=True) +@skip_unless_lms +def test_time_zone_list_query_count_does_not_grow_with_page_size( + client, directory, django_assert_num_queries, page_size, +): # pylint: disable=unused-argument + """The rows come from the time-zone database, so only the page size varies them.""" + url = reverse("user_v2:time_zone_list") + with django_assert_num_queries(TIME_ZONE_LIST_QUERIES): + response = client.get(url, {"page_size": page_size}) + assert len(response.json()["results"]) == page_size + + +@pytest.mark.django_db +@pytest.mark.parametrize("directory", [5], indirect=True) +@skip_unless_lms +def test_member_query_counts(client, directory, django_assert_num_queries): + with django_assert_num_queries(USER_DETAIL_QUERIES): + response = client.get(reverse("user_v2:user_detail", kwargs={"username": "counted0"})) + assert response.json()["username"] == "counted0" + + with django_assert_num_queries(PREFERENCE_DETAIL_QUERIES): + response = client.get( + reverse( + "user_v2:user_preference_detail", + kwargs={"username": "counted0", "key": "pref-lang"}, + ), + ) + assert response.json()["value"] == "en" + + +@pytest.mark.django_db +@pytest.mark.parametrize("directory", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_the_earlier_preference_list_pays_per_row_where_this_one_does_not( + client, directory, django_assert_num_queries, +): + """ + Both lists are measured over the same rows, so the saving cannot drift apart. + + The earlier row embeds its owner without a join and re-reads that owner's + own preferences, so a page of it costs five queries per user; this one + reads the same page at a count that does not move with it. + """ + with django_assert_num_queries(PREFERENCE_LIST_QUERIES): + current = client.get(reverse("user_v2:user_preference_list"), {"page_size": 100}) + assert len(current.json()["results"]) == 2 * len(directory) + + client.logout() + with override_settings(EDX_API_KEY=EARLIER_API_KEY): + with django_assert_num_queries(EARLIER_PREFERENCE_LIST_QUERIES[len(directory)]): + earlier = client.get( + EARLIER_PREFERENCE_LIST, + {"page_size": 100}, + HTTP_X_EDX_API_KEY=EARLIER_API_KEY, + ) + assert len(earlier.json()["results"]) == 2 * len(directory) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py new file mode 100644 index 000000000000..de29bdae413e --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -0,0 +1,531 @@ +"""Tests for what version 2 of the User API publishes in the OpenAPI schema.""" + +import json +from importlib import import_module + +import jsonschema +import pytest +from django.conf import settings +from django.urls import reverse +from drf_spectacular.generators import SchemaGenerator +from drf_spectacular.settings import patched_settings + +from common.djangoapps.student.tests.factories import AdminFactory +from lms.lib.spectacular import SUPERSEDED_USER_PATHS, lms_mark_legacy_paths_deprecated +from openedx.core.apidocs import get_api_docs_settings +from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangoapps.user_api.v2.serializers import TimeZoneQuerySerializer +from openedx.core.djangoapps.user_api.v2.views import PREFERENCE_KEY_PATTERN_PARTIAL +from openedx.core.djangolib.testing.utils import skip_unless_lms + +PASSWORD = "Password1234" + +USER_MEMBER_PATH = "/api/user/v2/users/{username}/" +PREFERENCE_MEMBER_PATH = "/api/user/v2/user_preferences/{username},{key}/" +TIME_ZONE_LIST_PATH = "/api/user/v2/time_zones/" + +#: The addresses that answer with a page of rows, and the ones that answer with +#: a single record. +LIST_PATHS = { + "/api/user/v2/users/", + "/api/user/v2/user_preferences/", + TIME_ZONE_LIST_PATH, +} +MEMBER_PATHS = {USER_MEMBER_PATH, PREFERENCE_MEMBER_PATH} + +VERSION_TWO_PATHS = LIST_PATHS | MEMBER_PATHS + +PAGINATION_MEMBERS = {"count", "num_pages", "current_page", "start", "next", "previous", "results"} + +#: Where this version is mounted in the service's URL configuration. +VERSION_TWO_MOUNT = "api/user/v2/" + +#: The components this version contributes to the document. +VERSION_TWO_COMPONENTS = ( + "ErrorResponse", + "PaginatedTimeZoneList", + "PaginatedUserDirectoryResponseList", + "PaginatedUserPreferenceRecordResponseList", + "TimeZone", + "UserDirectory", + "UserDirectoryMinimal", + "UserDirectoryProjection", + "UserDirectoryResponse", + "UserPreferenceRecord", + "UserPreferenceRecordMinimal", + "UserPreferenceRecordProjection", + "UserPreferenceRecordResponse", +) + +#: Every body these endpoints return: the address and parameters that produce +#: it, the published path it is documented under, and the rows it carries. +SHAPE_CASES = ( + ("/api/user/v2/users/", "/api/user/v2/users/", {}), + ("/api/user/v2/users/", "/api/user/v2/users/", {"view": "minimal"}), + ("/api/user/v2/users/", "/api/user/v2/users/", {"fields": "username,email"}), + ("/api/user/v2/users/", "/api/user/v2/users/", {"view": "minimal", "fields": "username"}), + ("/api/user/v2/users/{username}/", "/api/user/v2/users/shape-admin/", {}), + ("/api/user/v2/users/{username}/", "/api/user/v2/users/shape-admin/", {"view": "minimal"}), + ("/api/user/v2/users/{username}/", "/api/user/v2/users/shape-admin/", {"fields": "id,url"}), + ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {}), + ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {"view": "full"}), + ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {"view": "minimal"}), + ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {"fields": "key,value"}), + ( + "/api/user/v2/user_preferences/{username},{key}/", + "/api/user/v2/user_preferences/shape-admin,pref-lang/", + {}, + ), + ( + "/api/user/v2/user_preferences/{username},{key}/", + "/api/user/v2/user_preferences/shape-admin,pref-lang/", + {"view": "full"}, + ), + ( + "/api/user/v2/user_preferences/{username},{key}/", + "/api/user/v2/user_preferences/shape-admin,pref-lang/", + {"view": "minimal"}, + ), + ( + "/api/user/v2/user_preferences/{username},{key}/", + "/api/user/v2/user_preferences/shape-admin,pref-lang/", + {"fields": "value"}, + ), + ("/api/user/v2/time_zones/", "/api/user/v2/time_zones/", {"country_code": "FR"}), +) + + +def as_json_schema(node): + """ + Return a published schema node as a JSON Schema document. + + The document describes an absent value with ``nullable``, which JSON + Schema spells as an alternative type, so a validator reading the published + node verbatim would reject a member the API is documented to omit. + """ + 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 + + +def published_body_schema(schema, path): + """Return what a successful body of ``path`` must satisfy, components included.""" + body = schema["paths"][path]["get"]["responses"]["200"]["content"]["application/json"]["schema"] + return as_json_schema({**body, "components": schema["components"]}) + +#: The version 1 addresses this change supersedes, written out independently of +#: the constant the hook reads so that changing either one shows up here. +SUPERSEDED_USER_ADDRESSES = { + "/api/user/v1/users/": "/api/user/v2/users/", + "/api/user/v1/users/{id}/": "/api/user/v2/users/{username}/", + "/api/user/v1/user_prefs/": "/api/user/v2/user_preferences/", + "/api/user/v1/user_prefs/{id}/": "/api/user/v2/user_preferences/{username},{key}/", + "/api/user/v1/preferences/{pref_key}/users/": "/api/user/v2/users/", + "/api/user/v1/forum_roles/{name}/users/": "/api/user/v2/users/", + "/api/user/v1/preferences/time_zones/": "/api/user/v2/time_zones/", +} + +#: Legacy enrollment addresses this schema already marked before the user API joined it. +SUPERSEDED_ENROLLMENT_PATHS = { + "/api/enrollment/v2/course/{course_id}", + "/api/enrollment/v2/enrollment/{course_id}", + "/api/enrollment/v2/enrollment/{username},{course_id}", + "/api/enrollment/v2/enrollments", +} + +#: Enrollment operations whose ids must survive the widened path prefix. +ENROLLMENT_OPERATION_IDS = { + "v1_enrollments_list", + "v1_enrollment_create", + "v2_enrollments_list", + "v2_enrollments_list_legacy", + "v2_enrollment_,_retrieve", + "v2_roles_retrieve", +} + + +@pytest.fixture(name="schema") +@skip_unless_lms +def schema_fixture(db): # pylint: disable=invalid-name, unused-argument + """The schema published under the service's own drf-spectacular settings.""" + return SchemaGenerator().get_schema(request=None, public=True) + + +def service_wide_schema(patterns=None): + """Return the document the service publishes for browsing its whole surface.""" + with patched_settings(get_api_docs_settings()): + return SchemaGenerator(patterns=patterns).get_schema(request=None, public=True) + + +def patterns_without_this_version(): + """Return the service's URL configuration with this version's mount taken out.""" + configured = import_module(settings.ROOT_URLCONF).urlpatterns + remaining = [entry for entry in configured if str(entry.pattern) != VERSION_TWO_MOUNT] + assert len(remaining) == len(configured) - 1, "this version is not mounted where it is looked for" + return remaining + + +def published_names(schema): + """Return every component name and operation id a document carries.""" + return set(schema["components"]["schemas"]) | { + operation["operationId"] for _path, _method, operation in operations(schema) + } + + +def operations(schema): + """Yield every (path, method, operation) the schema documents.""" + for path, path_item in schema["paths"].items(): + for method, operation in path_item.items(): + if isinstance(operation, dict) and method in {"get", "post", "put", "patch", "delete"}: + yield path, method, operation + + +@skip_unless_lms +def test_version_two_addresses_are_published(schema): + assert VERSION_TWO_PATHS <= set(schema["paths"]) + + +@skip_unless_lms +def test_version_two_operations_carry_the_area_tag(schema): + tags = { + operation["operationId"]: operation.get("tags") + for path, _method, operation in operations(schema) + if path in VERSION_TWO_PATHS + } + assert tags == { + "v2_users_list": ["user"], + "v2_users_retrieve": ["user"], + "v2_user_preferences_list": ["user"], + "v2_user_preferences_retrieve": ["user"], + "v2_time_zones_list": ["user"], + } + + +@skip_unless_lms +def test_enrollment_operation_ids_survive_the_widened_prefix(schema): + published = {operation["operationId"] for _path, _method, operation in operations(schema)} + assert ENROLLMENT_OPERATION_IDS <= published + + +@skip_unless_lms +def test_only_superseded_addresses_are_marked_deprecated(schema): + deprecated = { + path for path, _method, operation in operations(schema) if operation.get("deprecated") + } + assert deprecated == SUPERSEDED_ENROLLMENT_PATHS | set(SUPERSEDED_USER_ADDRESSES) + + +@skip_unless_lms +def test_only_this_version_and_the_addresses_it_supersedes_are_published(schema): + """A user address this change neither serves nor replaces stays out of the document.""" + published = {path for path in schema["paths"] if path.startswith("/api/user/")} + assert published == VERSION_TWO_PATHS | set(SUPERSEDED_USER_ADDRESSES) + + +@skip_unless_lms +def test_addresses_owned_by_other_apps_are_not_published(schema): + """Neighbours of the mounts this change adds, including one under its own prefix.""" + for path in ( + "/api/user/v1/accounts", + "/api/user/v1/me", + "/api/user/v1/preferences/{username}", + "/api/user/v1/account/registration/", + "/api/user/v2/account/registration/", + ): + assert path not in schema["paths"], path + + +@skip_unless_lms +def test_pagination_envelope_is_published_in_full(schema): + for component in ( + "PaginatedUserDirectoryResponseList", + "PaginatedUserPreferenceRecordResponseList", + "PaginatedTimeZoneList", + ): + published = schema["components"]["schemas"][component] + assert set(published["properties"]) == PAGINATION_MEMBERS, component + + +@pytest.mark.django_db +@skip_unless_lms +def test_published_pagination_envelope_matches_the_response_body(client, schema): + admin = AdminFactory.create(username="schema-admin", password=PASSWORD) + UserPreferenceFactory.create(user=admin, key="pref-lang", value="en") + assert client.login(username=admin.username, password=PASSWORD) + body = client.get(reverse("user_v2:user_preference_list")).json() + published = schema["components"]["schemas"]["PaginatedUserPreferenceRecordResponseList"] + assert set(body) == set(published["properties"]) + + +@skip_unless_lms +def test_error_responses_reference_the_shared_envelope(schema): + for path, method, operation in operations(schema): + if path not in VERSION_TWO_PATHS: + continue + for code, response in operation["responses"].items(): + if not code.startswith("4"): + continue + schema_ref = response["content"]["application/json"]["schema"] + assert schema_ref == {"$ref": "#/components/schemas/ErrorResponse"}, (path, method, code) + + +@skip_unless_lms +def test_an_operation_that_takes_a_response_preset_publishes_the_refusal(schema): + """A preset the operation does not answer to is a 400, so each of them documents one.""" + takes_a_preset = [ + (path, method) + for path, method, operation in operations(schema) + if path in VERSION_TWO_PATHS + and any(parameter["name"] == "view" for parameter in operation.get("parameters", [])) + and "400" in operation["responses"] + ] + assert sorted(takes_a_preset) == [ + ("/api/user/v2/user_preferences/", "get"), + ("/api/user/v2/user_preferences/{username},{key}/", "get"), + ("/api/user/v2/users/", "get"), + ("/api/user/v2/users/{username}/", "get"), + ] + + +@skip_unless_lms +def test_user_list_publishes_its_filters(schema): + parameters = { + parameter["name"]: parameter + for parameter in schema["paths"]["/api/user/v2/users/"]["get"]["parameters"] + } + assert set(parameters) == { + "course_key", "email", "fields", "forum_role", "is_active", "ordering", + "page", "page_size", "preference_key", "username", "view", + } + # The filter that refuses an unparsable value is still published as a boolean. + assert parameters["is_active"]["schema"] == {"type": "boolean"} + + +@skip_unless_lms +def test_preference_list_publishes_its_filters(schema): + parameters = { + parameter["name"]: parameter + for parameter in schema["paths"]["/api/user/v2/user_preferences/"]["get"]["parameters"] + } + assert set(parameters) == {"fields", "key", "ordering", "page", "page_size", "username", "view"} + # Every published parameter is one the list reads, and one it keeps. + assert [name for name, parameter in parameters.items() if parameter.get("deprecated")] == [] + + +@skip_unless_lms +def test_enum_post_processing_runs_before_the_deprecation_hook(): + hooks = settings.SPECTACULAR_SETTINGS["POSTPROCESSING_HOOKS"] + assert hooks[0] == "drf_spectacular.hooks.postprocess_schema_enums" + assert "lms.lib.spectacular.lms_mark_legacy_paths_deprecated" in hooks[1:] + + +@skip_unless_lms +def test_hook_leaves_other_resources_alone(): + """The hook marks only the addresses it lists, even among their neighbours.""" + untouched = [ + "/api/user/v1/accounts", + "/api/user/v1/me", + "/api/user/v1/preferences/email_opt_in/", + "/api/user/v2/account/registration/", + "/user_api/v1/users/", + "/user_api/v1/preferences/time_zones/", + "/api/enrollment/v2/enrollments/", + "/api/courses/v1/courses/", + ] + marked = ["/api/user/v1/users/", "/api/enrollment/v2/enrollments"] + result = {"paths": {path: {"get": {"operationId": path}} for path in untouched + marked}} + + lms_mark_legacy_paths_deprecated(result, generator=None, request=None, public=True) + + for path in untouched: + assert "deprecated" not in result["paths"][path]["get"], path + for path in marked: + assert result["paths"][path]["get"]["deprecated"] is True, path + + +@skip_unless_lms +def test_every_superseded_address_has_a_published_replacement(schema): + assert set(SUPERSEDED_USER_ADDRESSES) == set(SUPERSEDED_USER_PATHS) + for superseded, replacement in SUPERSEDED_USER_ADDRESSES.items(): + assert superseded in schema["paths"] + assert replacement in schema["paths"] + + +@pytest.mark.django_db +@skip_unless_lms +def test_this_version_only_adds_to_the_service_wide_document(): + """ + Nothing published for browsing the whole service is lost when this version joins it. + + Enum post-processing runs over every operation the service publishes and + renames both sides of a name collision, so a component this version never + declared can be renamed out of the document, and a client generated from it + loses the matching model. The document is therefore read with this version + mounted and with its mount taken out, and the second has to be contained in + the first. + """ + without_this_version = published_names(service_wide_schema(patterns_without_this_version())) + whole = service_wide_schema() + missing = without_this_version - published_names(whole) + assert missing == set(), sorted(missing) + + components = whole["components"]["schemas"] + assert "user_api.User" in components + assert {"UserDirectory", "UserPreferenceRecord", "TimeZone"} <= set(components) + assert "CountryTimeZone" in components + + +@skip_unless_lms +def test_every_response_shape_is_published(schema): + """The reduced bodies the presets return are described, not only the full one.""" + components = schema["components"]["schemas"] + assert components["UserDirectoryResponse"]["anyOf"] == [ + {"$ref": "#/components/schemas/UserDirectory"}, + {"$ref": "#/components/schemas/UserDirectoryMinimal"}, + {"$ref": "#/components/schemas/UserDirectoryProjection"}, + ] + assert components["UserPreferenceRecordResponse"]["anyOf"] == [ + {"$ref": "#/components/schemas/UserPreferenceRecord"}, + {"$ref": "#/components/schemas/UserPreferenceRecordMinimal"}, + {"$ref": "#/components/schemas/UserPreferenceRecordProjection"}, + ] + assert sorted(components["UserDirectory"]["required"]) == [ + "email", "id", "name", "preferences", "url", "username", + ] + assert sorted(components["UserDirectoryMinimal"]["required"]) == ["email", "id", "username"] + assert sorted(components["UserPreferenceRecordMinimal"]["required"]) == ["key", "username", "value"] + for component in ("UserDirectoryProjection", "UserPreferenceRecordProjection"): + published = components[component] + assert "required" not in published, component + assert set(published["properties"]) == set( + components[component.replace("Projection", "")]["properties"] + ), component + + +@pytest.mark.django_db +@skip_unless_lms +def test_published_shapes_accept_every_body_the_endpoints_return(client, schema): + """Every preset and selection the parameters offer returns a body the document describes.""" + admin = AdminFactory.create(username="shape-admin", password=PASSWORD) + UserPreferenceFactory.create(user=admin, key="pref-lang", value="en") + assert client.login(username=admin.username, password=PASSWORD) + for published_path, address, params in SHAPE_CASES: + case = (address, params) + response = client.get(address, params) + assert response.status_code == 200, case + body = response.json() + if "results" in body: + assert body["count"] == 1, case + validator = jsonschema.Draft202012Validator(published_body_schema(schema, published_path)) + assert [error.message for error in validator.iter_errors(body)] == [], case + + +@skip_unless_lms +def test_sort_parameter_publishes_the_fields_it_accepts(schema): + """The sort allow-list and the order used when none is asked for are published.""" + for path, accepted, default in ( + ("/api/user/v2/users/", ["-date_joined", "-username", "date_joined", "username"], ["username"]), + ("/api/user/v2/user_preferences/", ["-key", "-username", "key", "username"], ["username", "key"]), + ): + parameter = next( + published for published in schema["paths"][path]["get"]["parameters"] + if published["name"] == "ordering" + ) + assert parameter["schema"]["items"]["enum"] == accepted, path + assert parameter["schema"]["default"] == default, path + + +@skip_unless_lms +def test_every_list_publishes_the_page_that_does_not_exist(schema): + """Asking for a page past the end of a list is answered 404, so each list documents it.""" + assert LIST_PATHS | MEMBER_PATHS == set(VERSION_TWO_PATHS) + documented = { + path: sorted(operation["responses"]) + for path, _method, operation in operations(schema) + if path in LIST_PATHS + } + assert documented == { + "/api/user/v2/users/": ["200", "400", "401", "403", "404"], + "/api/user/v2/user_preferences/": ["200", "400", "401", "403", "404"], + TIME_ZONE_LIST_PATH: ["200", "400", "404"], + } + + +@skip_unless_lms +def test_member_addresses_describe_the_parts_they_are_built_from(schema): + """Each part of a member address is published with its meaning and what its route matches.""" + username_schema = {"type": "string", "pattern": rf"^{settings.USERNAME_REGEX_PARTIAL}$"} + published = { + (path, parameter["name"]): parameter + for path, _method, operation in operations(schema) + if path in MEMBER_PATHS + for parameter in operation["parameters"] + if parameter["in"] == "path" + } + assert published == { + (USER_MEMBER_PATH, "username"): { + "in": "path", + "name": "username", + "required": True, + "schema": username_schema, + "description": "Unique name of the user whose directory entry is returned.", + }, + (PREFERENCE_MEMBER_PATH, "username"): { + "in": "path", + "name": "username", + "required": True, + "schema": username_schema, + "description": ( + "Username of the user the preference belongs to: the part of the address " + "before the comma." + ), + }, + (PREFERENCE_MEMBER_PATH, "key"): { + "in": "path", + "name": "key", + "required": True, + "schema": {"type": "string", "pattern": rf"^{PREFERENCE_KEY_PATTERN_PARTIAL}$"}, + "description": ( + "Name the preference is stored under: the part of the address after the comma." + ), + }, + } + + +@skip_unless_lms +def test_the_country_parameter_publishes_the_constraint_it_is_held_to(schema): + """The parameter comes from the serializer that validates it, so the two cannot disagree.""" + field = TimeZoneQuerySerializer().fields["country_code"] + enforced = next( + validator.regex.pattern for validator in field.validators if hasattr(validator, "regex") + ) + parameter = next( + published for published in schema["paths"][TIME_ZONE_LIST_PATH]["get"]["parameters"] + if published["name"] == "country_code" + ) + assert parameter["description"] == field.help_text + assert parameter["schema"] == { + "oneOf": [{"type": "string", "pattern": enforced}, {"type": "string", "maxLength": 0}], + } + assert "required" not in parameter + + +@skip_unless_lms +def test_published_text_is_written_for_the_clients_that_read_it(schema): + """Descriptions reach every consumer, so they carry no governance references.""" + published = json.dumps({ + "paths": {path: schema["paths"][path] for path in VERSION_TWO_PATHS}, + "components": { + name: schema["components"]["schemas"][name] for name in VERSION_TWO_COMPONENTS + }, + }) + for reference in ("ADR", "OEP-", "drf-spectacular", "extend_schema"): + assert reference not in published, reference + assert schema["components"]["schemas"]["ErrorResponse"]["description"].startswith( + "The body of every unsuccessful response." + ) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py b/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py new file mode 100644 index 000000000000..019d3c535434 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py @@ -0,0 +1,68 @@ +"""Addresses of other apps that share the prefix version 2 of the User API is mounted on.""" + +from django.test import SimpleTestCase +from django.urls import resolve, reverse + +from openedx.core.djangolib.testing.utils import skip_unless_lms + +AUTHN_LOGIN_VIEWS = "openedx.core.djangoapps.user_authn.views.login" +AUTHN_REGISTER_VIEWS = "openedx.core.djangoapps.user_authn.views.register" + + +@skip_unless_lms +class SharedPrefixTests(SimpleTestCase): + """ + The authentication app keeps the two addresses it serves under this prefix. + + The mount for this version is matched before the include that carries the + rest of the user surface and before the authentication app's own patterns, + so it is first in line for every address that begins with + ``/api/user/v2/``. Those two addresses reach the authentication app only + because no pattern here matches them first. + """ + + def assert_resolves_to(self, address, module, class_name, url_name, kwargs=None): + """Assert an address reaches the named view through the named route.""" + match = resolve(address) + view_class = match.func.view_class + assert (view_class.__module__, view_class.__name__) == (module, class_name), address + assert match.url_name == url_name, address + assert match.kwargs == (kwargs or {}), address + + def test_registration_still_reaches_the_authentication_app(self): + self.assert_resolves_to( + "/api/user/v2/account/registration/", + AUTHN_REGISTER_VIEWS, + "RegistrationView", + "user_api_registration_v2", + ) + + def test_login_session_still_reaches_the_authentication_app(self): + self.assert_resolves_to( + "/api/user/v2/account/login_session/", + AUTHN_LOGIN_VIEWS, + "LoginSessionView", + "user_api_login_session", + {"api_version": "v2"}, + ) + + def test_the_version_one_addresses_beside_them_are_unaffected(self): + self.assert_resolves_to( + "/api/user/v1/account/registration/", + AUTHN_REGISTER_VIEWS, + "RegistrationView", + "user_api_registration", + ) + self.assert_resolves_to( + "/api/user/v1/account/login_session/", + AUTHN_LOGIN_VIEWS, + "LoginSessionView", + "user_api_login_session", + {"api_version": "v1"}, + ) + + def test_both_shared_prefix_addresses_still_reverse_to_themselves(self): + assert reverse("user_api_registration_v2") == "/api/user/v2/account/registration/" + assert reverse( + "user_api_login_session", kwargs={"api_version": "v2"}, + ) == "/api/user/v2/account/login_session/" diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_urls.py b/openedx/core/djangoapps/user_api/v2/tests/test_urls.py new file mode 100644 index 000000000000..c51ceab78a13 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_urls.py @@ -0,0 +1,296 @@ +"""Tests for the version 2 User API URL surface.""" + +import re + +import pytest +from django.core.exceptions import ImproperlyConfigured +from django.urls import get_resolver, resolve, reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from rest_framework import status +from rest_framework.request import Request +from rest_framework.test import APIRequestFactory, APITestCase + +from common.djangoapps.student.tests.factories import AdminFactory +from openedx.core.djangoapps.user_api.v2 import urls as v2_urls +from openedx.core.djangoapps.user_api.v2.views import UserPreferenceViewSet, UserViewSet +from openedx.core.djangolib.testing.utils import skip_unless_lms + +PASSWORD = "Password1234" + +V2_VIEW_MODULE = "openedx.core.djangoapps.user_api.v2.views" +V1_VIEW_MODULE = "openedx.core.djangoapps.user_api.views" +V2_NAMESPACE = "user_v2" + +#: A route name is lower case, starts with a letter and separates words with +#: underscores; nothing else is accepted. +SNAKE_CASE_NAME = re.compile(r"[a-z][a-z0-9_]*\Z") +VERSION_IN_NAME = re.compile(r"v\d") + +EXPECTED_ADDRESSES = { + "user_v2:user_list": ({}, "/api/user/v2/users/"), + "user_v2:user_detail": ({"username": "alice"}, "/api/user/v2/users/alice/"), + "user_v2:user_preference_list": ({}, "/api/user/v2/user_preferences/"), + "user_v2:user_preference_detail": ( + {"username": "alice", "key": "time_zone"}, + "/api/user/v2/user_preferences/alice,time_zone/", + ), + "user_v2:time_zone_list": ({}, "/api/user/v2/time_zones/"), +} + + +def registered_route_names(): + """ + Return the route names the mounted URLconf registers under this namespace. + + These are the names ``reverse()`` accepts; they are read from the resolver + rather than from this module so that a route added or renamed in the + URLconf is seen here. + """ + _prefix, namespace_resolver = get_resolver().namespace_dict[V2_NAMESPACE] + return {key for key in namespace_resolver.reverse_dict if isinstance(key, str)} + + +def resolved_route_names(): + """Return the route names ``resolve()`` reports for the published addresses.""" + return {resolve(address).url_name for _kwargs, address in EXPECTED_ADDRESSES.values()} + + +def routed_actions(view_func): + """ + Return the method-to-action map a viewset mount was registered with. + + DRF adds a ``head`` entry to a mount's ``actions`` the first time it serves + a GET, so the raw attribute depends on what the test suite requested first. + """ + return {method: action for method, action in view_func.actions.items() if method != "head"} + + +def view_identity(view_func): + """ + Return the module and class name of the view a route is mounted on. + + A viewset mount carries the class name on the wrapper itself; Django's + plain class-based views record the class separately instead. + """ + view_class = getattr(view_func, "view_class", None) + name = view_class.__name__ if view_class is not None else view_func.__name__ + return (view_func.__module__, name) + + +@skip_unless_lms +class UrlLiteralTests(APITestCase): + """Every name reverses to the address the API publishes.""" + + def test_reverse_literals(self): + for name, (kwargs, expected) in EXPECTED_ADDRESSES.items(): + assert reverse(name, kwargs=kwargs) == expected, name + + def test_names_are_snake_case_and_carry_no_version(self): + registered = registered_route_names() + assert registered == {name.split(":")[1] for name in EXPECTED_ADDRESSES} + for name in registered: + assert SNAKE_CASE_NAME.match(name), name + assert not VERSION_IN_NAME.search(name), name + + def test_resolved_names_are_the_names_that_reverse(self): + resolved = resolved_route_names() + assert resolved == registered_route_names() + for address, name in ( + ("/api/user/v2/users/", "user_list"), + ("/api/user/v2/users/alice/", "user_detail"), + ("/api/user/v2/user_preferences/", "user_preference_list"), + ("/api/user/v2/user_preferences/alice,time_zone/", "user_preference_detail"), + ("/api/user/v2/time_zones/", "time_zone_list"), + ): + match = resolve(address) + assert match.url_name == name, address + assert match.view_name == f"{V2_NAMESPACE}:{name}", address + + def test_viewsets_build_action_addresses_under_this_mount(self): + assert UserViewSet(basename="user").reverse_action("list") == "/api/user/v2/users/" + assert UserViewSet(basename="user").reverse_action( + "detail", kwargs={"username": "alice"}, + ) == "/api/user/v2/users/alice/" + preferences = UserPreferenceViewSet(basename="user_preference") + assert preferences.reverse_action("list") == "/api/user/v2/user_preferences/" + assert preferences.reverse_action( + "detail", kwargs={"username": "alice", "key": "time_zone"}, + ) == "/api/user/v2/user_preferences/alice,time_zone/" + + def test_action_addresses_follow_the_namespace_the_request_arrived_on(self): + request = Request(APIRequestFactory().get("/api/user/v2/users/")) + request.resolver_match = resolve("/api/user/v2/users/") + view = UserViewSet(basename="user", request=request) + assert view.reverse_action("list") == "http://testserver/api/user/v2/users/" + + def test_addresses_resolve_to_the_version_two_viewsets(self): + expected = { + "/api/user/v2/users/": ("UserViewSet", {"get": "list"}), + "/api/user/v2/users/alice/": ("UserViewSet", {"get": "retrieve"}), + "/api/user/v2/user_preferences/": ("UserPreferenceViewSet", {"get": "list"}), + "/api/user/v2/user_preferences/alice,time_zone/": ( + "UserPreferenceViewSet", {"get": "retrieve"}, + ), + "/api/user/v2/time_zones/": ("CountryTimeZoneViewSet", {"get": "list"}), + } + for address, (class_name, actions) in expected.items(): + match = resolve(address) + assert view_identity(match.func) == (V2_VIEW_MODULE, class_name), address + assert routed_actions(match.func) == actions, address + + def test_username_with_a_dot_resolves_to_the_member_route(self): + match = resolve("/api/user/v2/users/ada.lovelace/") + assert view_identity(match.func) == (V2_VIEW_MODULE, "UserViewSet") + assert match.kwargs == {"username": "ada.lovelace"} + + def test_preference_member_address_splits_into_username_and_key(self): + match = resolve("/api/user/v2/user_preferences/ada.lovelace,pref-lang/") + assert match.kwargs == {"username": "ada.lovelace", "key": "pref-lang"} + + def test_a_key_containing_a_comma_belongs_to_the_key(self): + """A preference name is free-form text, and the username half cannot contain a comma.""" + match = resolve("/api/user/v2/user_preferences/ada.lovelace,a,b/") + assert match.kwargs == {"username": "ada.lovelace", "key": "a,b"} + assert reverse( + "user_v2:user_preference_detail", kwargs={"username": "ada.lovelace", "key": "a,b"}, + ) == "/api/user/v2/user_preferences/ada.lovelace,a,b/" + + def test_a_username_outside_the_allowed_pattern_does_not_reach_the_viewset(self): + match = resolve("/api/user/v2/user_preferences/al!ce,pref-lang/") + assert view_identity(match.func) == (V2_VIEW_MODULE, "UnknownAddressView") + + def test_no_database_id_member_address_is_served(self): + match = resolve("/api/user/v2/user_preferences/42/") + assert view_identity(match.func) == (V2_VIEW_MODULE, "UnknownAddressView") + + +@skip_unless_lms +class RouteShapeTests(APITestCase): + """ + Every address this version serves is named and ends in a slash. + + The mount also carries one pattern that is neither: the fallback matched + after all of them, which answers an address no route serves. It addresses + no resource and reverses to nothing, which is why it has no name, and + pinning it here keeps a second wildcard from being added quietly beside + it. + """ + + def test_every_address_is_named_and_ends_in_a_slash(self): + addresses = [pattern for pattern in v2_urls.urlpatterns if pattern.name] + assert sorted(pattern.name for pattern in addresses) == [ + "time_zone_list", + "user_detail", + "user_list", + "user_preference_detail", + "user_preference_list", + ] + for pattern in addresses: + assert SNAKE_CASE_NAME.match(pattern.name), pattern.name + assert str(pattern.pattern).endswith("/$"), pattern.name + + def test_the_router_route_that_is_replaced_has_to_exist(self): + """Dropping a route the router does not generate is refused instead of passing silently.""" + routes = v2_urls.router.urls + assert v2_urls.REPLACED_ROUTER_ROUTE in {route.name for route in routes} + kept = v2_urls.without_route(routes, v2_urls.REPLACED_ROUTER_ROUTE) + assert [route.name for route in kept] == [ + "user_list", + "user_detail", + "user_preference_list", + "time_zone_list", + ] + with pytest.raises(ImproperlyConfigured): + v2_urls.without_route(routes, "user_preference_detail_renamed") + + def test_the_one_unnamed_pattern_is_the_fallback_and_it_is_matched_last(self): + unnamed = [pattern for pattern in v2_urls.urlpatterns if not pattern.name] + assert len(unnamed) == 1 + assert unnamed[0] is v2_urls.urlpatterns[-1] + assert view_identity(unnamed[0].callback) == (V2_VIEW_MODULE, "UnknownAddressView") + + +@skip_unless_lms +class LegacyAddressTests(APITestCase): + """Mounting version 2 leaves the version 1 surface exactly where it was.""" + + def test_version_one_addresses_still_reach_the_version_one_views(self): + expected = { + "/api/user/v1/users/": "UserViewSet", + "/api/user/v1/users/42/": "UserViewSet", + "/api/user/v1/user_prefs/": "UserPreferenceViewSet", + "/api/user/v1/user_prefs/42/": "UserPreferenceViewSet", + "/api/user/v1/preferences/pref-lang/users/": "PreferenceUsersListView", + "/api/user/v1/forum_roles/Moderator/users/": "ForumRoleUsersListView", + "/api/user/v1/preferences/time_zones/": "CountryTimeZoneListView", + } + for address, class_name in expected.items(): + match = resolve(address) + assert view_identity(match.func) == (V1_VIEW_MODULE, class_name), address + + def test_version_one_url_names_still_reverse(self): + assert reverse("accounts_api", kwargs={"username": "alice"}) == "/api/user/v1/accounts/alice" + assert reverse("own_username_api") == "/api/user/v1/me" + assert reverse("preferences_api", kwargs={"username": "alice"}) == "/api/user/v1/preferences/alice" + + def test_unversioned_twins_still_resolve(self): + match = resolve("/user_api/v1/users/") + assert view_identity(match.func) == (V1_VIEW_MODULE, "UserViewSet") + + +@skip_unless_lms +class MalformedAddressTests(APITestCase): + """An address that matches no route is refused in the body shape this API answers with.""" + + def setUp(self): + super().setUp() + self.admin = AdminFactory.create(username="url-admin", password=PASSWORD) + assert self.client.login(username=self.admin.username, password=PASSWORD) + + def assert_refused_in_json(self, response): + """Assert the refusal is the standard error body and not a page meant for a browser.""" + assert response["Content-Type"].startswith("application/json"), response["Content-Type"] + assert "\w+)", + re.IGNORECASE, +) + +#: The platform's ``SafeSessionMiddleware`` puts the signed-in caller's e-mail +#: into the session the first time it finds it missing, which rewrites that one +#: row once per session; the deployed configuration keeps sessions in the cache +#: and only the test settings put them in a table at all. It is framework +#: bookkeeping rather than a change to the data this API serves, and it is the +#: only table left out of the captures below. +SESSION_TABLE = "django_session" + + +def write_target(sql): + """Return the table a statement writes to, or ``None`` if it cannot be read.""" + match = WRITE_TARGET.match(sql) + return match.group("table") if match else None + + +def write_queries(captured): + """ + Return the captured statements that would change the data this API serves. + + Only the statement's own target table decides: a write to a domain table is + reported however it mentions the session table elsewhere, and a write whose + target cannot be read is reported rather than assumed harmless. + """ + return [ + query["sql"] + for query in captured + if WRITE_VERB.match(query["sql"]) and write_target(query["sql"]) != SESSION_TABLE + ] + + +class WriteCaptureFilterTests(SimpleTestCase): + """The capture filter reports writes by their target table and nothing else.""" + + PREFERENCE_INSERT = ( + 'INSERT INTO "user_api_userpreference" ("user_id", "key", "value") ' + "VALUES (1, 'pref-lang', 'django_session')" + ) + PREFERENCE_DELETE = ( + 'DELETE FROM "user_api_userpreference" WHERE "user_id" IN ' + '(SELECT "user_id" FROM "django_session" WHERE "session_key" = \'abc\')' + ) + ROLE_INSERT = 'INSERT INTO "django_comment_common_role" ("name") VALUES (\'Moderator\')' + SESSION_UPDATE = 'UPDATE "django_session" SET "session_data" = \'x\' WHERE "session_key" = \'abc\'' + SESSION_INSERT = 'INSERT INTO "django_session" ("session_key", "session_data") VALUES (\'abc\', \'x\')' + SESSION_DELETE = 'DELETE FROM "django_session" WHERE "session_key" = \'abc\'' + USER_SELECT = 'SELECT "auth_user"."id" FROM "auth_user" ORDER BY "auth_user"."username" ASC' + UNREADABLE_WRITE = 'UPDATE /* hint */ "user_api_userpreference" SET "value" = \'en\'' + + def captured(self, *statements): + """Return the statements in the shape ``CaptureQueriesContext`` records them.""" + return [{"sql": statement, "time": "0.000"} for statement in statements] + + def test_domain_writes_are_reported_even_when_they_name_the_session_table(self): + reported = write_queries( + self.captured(self.PREFERENCE_INSERT, self.PREFERENCE_DELETE, self.ROLE_INSERT), + ) + assert reported == [self.PREFERENCE_INSERT, self.PREFERENCE_DELETE, self.ROLE_INSERT] + + def test_session_bookkeeping_is_the_only_statement_dropped(self): + reported = write_queries( + self.captured( + self.SESSION_INSERT, + self.SESSION_UPDATE, + self.SESSION_DELETE, + self.USER_SELECT, + self.ROLE_INSERT, + ), + ) + assert reported == [self.ROLE_INSERT] + + def test_reads_are_not_writes(self): + assert write_queries(self.captured(self.USER_SELECT)) == [] + + def test_a_write_whose_target_cannot_be_read_is_still_reported(self): + assert write_target(self.UNREADABLE_WRITE) is None + assert write_queries(self.captured(self.UNREADABLE_WRITE)) == [self.UNREADABLE_WRITE] + + def test_the_target_table_is_read_through_any_backend_quoting(self): + assert write_target(self.ROLE_INSERT) == "django_comment_common_role" + assert write_target("UPDATE `django_session` SET `session_data` = 'x'") == SESSION_TABLE + assert write_target(" insert into user_api_userpreference (value) values ('x')") == ( + "user_api_userpreference" + ) + assert write_target("INSERT OR IGNORE INTO `user_api_userpreference` (`value`) VALUES ('en')") == ( + "user_api_userpreference" + ) + assert write_target(self.USER_SELECT) is None + + +class UserApiV2TestCase(APITestCase): + """Fixtures shared by the version 2 User API tests.""" + + def setUp(self): + super().setUp() + self.admin = AdminFactory.create(username="admin-caller", password=PASSWORD) + self.learner = UserFactory.create(username="learner-caller", password=PASSWORD) + self.alice = UserFactory.create(username="alice", email="alice@example.com", password=PASSWORD) + self.bob = UserFactory.create(username="bob", email="bob@example.com", password=PASSWORD) + UserPreferenceFactory.create(user=self.alice, key="pref-lang", value="en") + UserPreferenceFactory.create(user=self.bob, key="time_zone", value="UTC") + + def login(self, user): + """Sign the given user in through the session the platform default accepts.""" + assert self.client.login(username=user.username, password=PASSWORD) + + def usernames_in(self, response): + """Return the usernames carried by a paginated directory page.""" + return [row["username"] for row in response.data["results"]] + + +@skip_unless_lms +class UserListViewTests(UserApiV2TestCase): + """GET /api/user/v2/users/""" + + def setUp(self): + super().setUp() + self.url = reverse("user_v2:user_list") + + def test_anonymous_caller_is_unauthenticated(self): + response = self.client.get(self.url) + assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") + + def test_non_admin_caller_is_forbidden(self): + self.login(self.learner) + response = self.client.get(self.url) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_non_admin_cannot_list_another_users_preference_holders(self): + self.login(self.learner) + response = self.client.get(self.url, {"preference_key": "pref-lang"}) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_admin_caller_receives_the_directory(self): + self.login(self.admin) + response = self.client.get(self.url, {"page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PAGINATION_KEYS + assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] + assert response.data["count"] == 4 + assert response.data["num_pages"] == 1 + assert response.data["current_page"] == 1 + assert response.data["start"] == 0 + + def test_row_shape_matches_the_declared_fields(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice"}) + row = response.data["results"][0] + assert set(row) == {"id", "url", "email", "name", "username", "preferences"} + assert row["id"] == self.alice.id + assert row["email"] == "alice@example.com" + assert row["name"] == self.alice.profile.name + assert row["preferences"] == {"pref-lang": "en"} + assert row["url"].endswith("/api/user/v2/users/alice/") + + def test_second_page_reports_its_position(self): + self.login(self.admin) + response = self.client.get(self.url, {"page_size": 2, "page": 2}) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["bob", "learner-caller"] + assert response.data["current_page"] == 2 + assert response.data["num_pages"] == 2 + assert response.data["start"] == 2 + assert response.data["previous"] is not None + assert response.data["next"] is None + + def test_a_page_beyond_the_last_one_is_not_found(self): + self.login(self.admin) + response = self.client.get(self.url, {"page": 9999}) + assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") + + def test_a_page_number_that_is_not_a_number_is_not_found(self): + self.login(self.admin) + response = self.client.get(self.url, {"page": "abc"}) + assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") + + def test_ordering_can_be_reversed(self): + self.login(self.admin) + response = self.client.get(self.url, {"ordering": "-username", "page_size": 100}) + assert self.usernames_in(response) == ["learner-caller", "bob", "alice", "admin-caller"] + + def test_ordering_by_join_date(self): + self.alice.date_joined = datetime(2020, 1, 1, tzinfo=UTC) + self.alice.save() + self.bob.date_joined = datetime(2019, 1, 1, tzinfo=UTC) + self.bob.save() + self.login(self.admin) + response = self.client.get(self.url, {"ordering": "date_joined", "page_size": 100}) + assert self.usernames_in(response)[-2:] == ["bob", "alice"] + + def test_unknown_ordering_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url, {"ordering": "password", "page_size": 100}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "ordering": ["Sort by any of: date_joined, username, each optionally prefixed with '-'."], + } + + def test_one_unknown_field_refuses_the_whole_sort(self): + self.login(self.admin) + response = self.client.get(self.url, {"ordering": "username,password", "page_size": 100}) + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + + def test_filter_by_email(self): + self.login(self.admin) + response = self.client.get(self.url, {"email": "bob@example.com"}) + assert self.usernames_in(response) == ["bob"] + + def test_filter_by_is_active(self): + self.alice.is_active = False + self.alice.save() + self.login(self.admin) + response = self.client.get(self.url, {"is_active": "false", "page_size": 100}) + assert self.usernames_in(response) == ["alice"] + + def test_filter_by_is_active_keeps_only_the_active_accounts(self): + self.alice.is_active = False + self.alice.save() + self.login(self.admin) + response = self.client.get(self.url, {"is_active": "true", "page_size": 100}) + assert self.usernames_in(response) == ["admin-caller", "bob", "learner-caller"] + + def test_an_is_active_value_that_names_no_side_is_refused(self): + """A mistyped value must be refused, not read as "no preference" and answered unfiltered.""" + self.alice.is_active = False + self.alice.save() + self.login(self.admin) + response = self.client.get(self.url, {"is_active": "maybe", "page_size": 100}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"is_active": ["Enter true or false."]} + + def test_an_empty_is_active_value_narrows_nothing(self): + self.alice.is_active = False + self.alice.save() + self.login(self.admin) + response = self.client.get(self.url, {"is_active": "", "page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] + + def test_filter_by_preference_key(self): + self.login(self.admin) + response = self.client.get(self.url, {"preference_key": "pref-lang", "page_size": 100}) + assert self.usernames_in(response) == ["alice"] + + def test_filter_by_unknown_preference_key_returns_no_rows(self): + self.login(self.admin) + response = self.client.get(self.url, {"preference_key": "nope", "page_size": 100}) + assert response.data["results"] == [] + assert response.data["count"] == 0 + + def give_alice_the_moderator_role(self): + """Make alice a moderator of the course the forum-role tests narrow by.""" + role = Role.objects.create(course_id=COURSE_KEY, name="Moderator") + role.users.add(self.alice) + return role + + def test_filter_by_forum_role_and_course(self): + self.give_alice_the_moderator_role() + other_role = Role.objects.create(course_id=OTHER_COURSE_KEY, name="Moderator") + other_role.users.add(self.bob) + self.login(self.admin) + response = self.client.get( + self.url, {"forum_role": "Moderator", "course_key": str(COURSE_KEY), "page_size": 100}, + ) + assert self.usernames_in(response) == ["alice"] + + def test_anonymous_caller_cannot_list_a_courses_forum_role_holders(self): + self.give_alice_the_moderator_role() + response = self.client.get( + self.url, {"forum_role": "Moderator", "course_key": str(COURSE_KEY)}, + ) + assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") + + def test_non_admin_cannot_list_a_courses_forum_role_holders(self): + self.give_alice_the_moderator_role() + self.login(self.learner) + response = self.client.get( + self.url, {"forum_role": "Moderator", "course_key": str(COURSE_KEY)}, + ) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_holding_the_role_does_not_let_a_learner_list_its_holders(self): + self.give_alice_the_moderator_role() + self.login(self.alice) + response = self.client.get( + self.url, {"forum_role": "Moderator", "course_key": str(COURSE_KEY)}, + ) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_the_published_course_key_example_can_be_pasted_into_a_query_string(self): + """A caller that copies the documented key into a query string reaches the role holders.""" + example = re.search( + r"for example (course-v1:[^\s.]+)", + UserFilterSet.base_filters["course_key"].extra["help_text"], + ).group(1) + role = Role.objects.create(course_id=COURSE_KEY, name="Moderator") + role.users.add(self.alice) + self.login(self.admin) + response = self.client.get(f"{self.url}?forum_role=Moderator&course_key={example}") + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["alice"] + + def test_a_course_key_whose_plus_signs_are_not_encoded_is_refused(self): + """An unencoded plus sign arrives as a space, which no course key may contain.""" + self.login(self.admin) + response = self.client.get( + f"{self.url}?forum_role=Moderator&course_key=course-v1:edX+DemoX+Demo", + ) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"course_key": ["Enter a valid course key."]} + + def test_a_user_holding_the_role_through_several_rows_is_listed_once(self): + """Nothing stops a course from carrying one role name under several rows.""" + for _ in range(2): + role = Role.objects.create(course_id=COURSE_KEY, name="Moderator") + role.users.add(self.alice) + self.login(self.admin) + response = self.client.get( + self.url, {"forum_role": "Moderator", "course_key": str(COURSE_KEY), "page_size": 100}, + ) + assert self.usernames_in(response) == ["alice"] + assert response.data["count"] == 1 + + def test_forum_role_without_course_key_is_rejected(self): + self.login(self.admin) + response = self.client.get(self.url, {"forum_role": "Moderator"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "course_key": ["This parameter is required when forum_role is supplied."], + } + + def test_course_key_without_forum_role_is_rejected(self): + self.login(self.admin) + response = self.client.get(self.url, {"course_key": str(COURSE_KEY)}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "forum_role": ["This parameter is required when course_key is supplied."], + } + + def test_malformed_course_key_is_rejected(self): + self.login(self.admin) + response = self.client.get(self.url, {"forum_role": "Moderator", "course_key": "not a course"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"course_key": ["Enter a valid course key."]} + + def test_unknown_forum_role_returns_no_rows_and_creates_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + response = self.client.get( + self.url, {"forum_role": "Inquisitor", "course_key": str(COURSE_KEY)}, + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [] + assert Role.objects.filter(name="Inquisitor").count() == 0 + assert write_queries(captured.captured_queries) == [] + + def test_minimal_view_returns_only_identifying_fields(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice", "view": "minimal"}) + row = response.data["results"][0] + assert set(row) == {"id", "username", "email"} + assert row["username"] == "alice" + + def test_fields_parameter_projects_the_row(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice", "fields": "username,email"}) + assert response.data["results"] == [{"username": "alice", "email": "alice@example.com"}] + + def test_fields_parameter_narrows_the_minimal_view(self): + self.login(self.admin) + response = self.client.get( + self.url, {"username": "alice", "view": "minimal", "fields": "username"}, + ) + assert response.data["results"] == [{"username": "alice"}] + + def test_a_field_name_the_row_does_not_carry_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url, {"fields": "user_name"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "fields": [ + "No such field: user_name. " + "Select any of: email, id, name, preferences, url, username.", + ], + } + + def test_a_field_the_minimal_preset_drops_is_refused(self): + """The preset decides what the row carries, so the selection is judged against it.""" + self.login(self.admin) + response = self.client.get(self.url, {"view": "minimal", "fields": "name"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "fields": ["No such field: name. Select any of: email, id, username."], + } + + def test_every_unknown_field_name_is_named_at_once(self): + self.login(self.admin) + response = self.client.get(self.url, {"fields": "username,e_mail,joined"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"][0].startswith("No such field: e_mail, joined.") + + def test_a_field_name_with_surrounding_space_is_accepted(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice", "fields": " username , email "}) + assert response.data["results"] == [{"username": "alice", "email": "alice@example.com"}] + + def test_an_unknown_field_does_not_answer_an_anonymous_caller(self): + response = self.client.get(self.url, {"fields": "user_name"}) + assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") + + def test_an_unknown_response_preset_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url, {"view": "nonsense"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "view": ["Ask for any of: minimal, or omit this parameter for the default response."], + } + + def test_the_preset_that_belongs_to_the_preference_list_is_refused_here(self): + self.login(self.admin) + response = self.client.get(self.url, {"view": "full"}) + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + + def test_an_empty_response_preset_returns_the_default_shape(self): + """A query string built from an empty variable narrows nothing rather than failing.""" + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice", "view": ""}) + assert response.status_code == status.HTTP_200_OK + assert set(response.data["results"][0]) == { + "id", "url", "email", "name", "username", "preferences", + } + + def test_an_unknown_preset_does_not_answer_an_anonymous_caller(self): + response = self.client.get(self.url, {"view": "nonsense"}) + assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") + + def test_listing_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + self.client.get(self.url, {"page_size": 100}) + assert write_queries(captured.captured_queries) == [] + + def test_head_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + response = self.client.head(self.url) + assert response.status_code == status.HTTP_200_OK + assert write_queries(captured.captured_queries) == [] + + +@skip_unless_lms +class UserDetailViewTests(UserApiV2TestCase): + """GET /api/user/v2/users/{username}/""" + + def url_for(self, username): + """Return the member address of the named user.""" + return reverse("user_v2:user_detail", kwargs={"username": username}) + + def test_anonymous_caller_is_unauthenticated(self): + response = self.client.get(self.url_for("alice")) + assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") + + def test_non_admin_caller_is_forbidden(self): + self.login(self.learner) + response = self.client.get(self.url_for("alice")) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_owner_who_is_not_an_admin_is_forbidden(self): + self.login(self.alice) + response = self.client.get(self.url_for("alice")) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_admin_caller_receives_the_entry(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice")) + assert response.status_code == status.HTTP_200_OK + assert response.data["username"] == "alice" + assert response.data["email"] == "alice@example.com" + assert response.data["preferences"] == {"pref-lang": "en"} + + def test_unknown_username_is_not_found(self): + self.login(self.admin) + response = self.client.get(self.url_for("nobody")) + assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") + + def test_username_containing_a_dot_resolves(self): + UserFactory.create(username="ada.lovelace", email="ada@example.com", password=PASSWORD) + self.login(self.admin) + response = self.client.get(self.url_for("ada.lovelace")) + assert response.status_code == status.HTTP_200_OK + assert response.data["username"] == "ada.lovelace" + + def test_minimal_view_returns_only_identifying_fields(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice"), {"view": "minimal"}) + assert set(response.data) == {"id", "username", "email"} + + def test_a_field_name_the_entry_does_not_carry_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice"), {"fields": "user_name"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "fields": [ + "No such field: user_name. " + "Select any of: email, id, name, preferences, url, username.", + ], + } + + def test_fields_parameter_projects_the_entry(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice"), {"fields": "username"}) + assert response.data == {"username": "alice"} + + def test_an_unknown_response_preset_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice"), {"view": "nonsense"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "view": ["Ask for any of: minimal, or omit this parameter for the default response."], + } + + def test_retrieval_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + self.client.get(self.url_for("alice")) + assert write_queries(captured.captured_queries) == [] + + def test_head_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + response = self.client.head(self.url_for("alice")) + assert response.status_code == status.HTTP_200_OK + assert write_queries(captured.captured_queries) == [] + + +@skip_unless_lms +class ProfilelessUserTests(UserApiV2TestCase): + """A user with no profile row is listed with a null name rather than failing.""" + + def test_user_without_a_profile_has_a_null_name(self): + User.objects.create_user("profileless", "profileless@example.com", PASSWORD) + self.login(self.admin) + response = self.client.get( + reverse("user_v2:user_detail", kwargs={"username": "profileless"}), + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["name"] is None + + +@skip_unless_lms +class UserPreferenceListViewTests(UserApiV2TestCase): + """GET /api/user/v2/user_preferences/""" + + def setUp(self): + super().setUp() + self.url = reverse("user_v2:user_preference_list") + + def keys_in(self, response): + """Return the (username, key) pairs carried by a page of preferences.""" + return [(row["username"], row["key"]) for row in response.data["results"]] + + def test_anonymous_caller_is_unauthenticated(self): + response = self.client.get(self.url) + assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") + + def test_non_admin_caller_is_forbidden(self): + self.login(self.learner) + response = self.client.get(self.url) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_owner_who_is_not_an_admin_is_forbidden(self): + self.login(self.alice) + response = self.client.get(self.url, {"username": "alice"}) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_admin_caller_receives_every_preference(self): + self.login(self.admin) + response = self.client.get(self.url, {"page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PAGINATION_KEYS + assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "time_zone")] + + def test_row_shape_is_flat_by_default(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice"}) + row = response.data["results"][0] + assert set(row) == {"username", "key", "value", "url", "user"} + assert row["username"] == "alice" + assert row["key"] == "pref-lang" + assert row["value"] == "en" + assert row["user"] is None + assert row["url"].endswith("/api/user/v2/user_preferences/alice,pref-lang/") + + def test_full_view_embeds_the_owning_user(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice", "view": "full"}) + row = response.data["results"][0] + assert set(row["user"]) == {"id", "url", "email", "name", "username", "preferences"} + assert row["user"]["username"] == "alice" + assert row["user"]["preferences"] == {"pref-lang": "en"} + + def test_minimal_view_drops_the_address_and_owner(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice", "view": "minimal"}) + assert response.data["results"] == [{"username": "alice", "key": "pref-lang", "value": "en"}] + + def test_a_field_name_the_row_does_not_carry_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url, {"fields": "preference_key"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "fields": [ + "No such field: preference_key. " + "Select any of: key, url, user, username, value.", + ], + } + + def test_a_page_beyond_the_last_one_is_not_found(self): + self.login(self.admin) + response = self.client.get(self.url, {"page": 9999}) + assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") + + def test_fields_parameter_projects_the_row(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice", "fields": "key,value"}) + assert response.data["results"] == [{"key": "pref-lang", "value": "en"}] + + def test_filter_by_key(self): + UserPreferenceFactory.create(user=self.bob, key="pref-lang", value="fr") + self.login(self.admin) + response = self.client.get(self.url, {"key": "pref-lang", "page_size": 100}) + assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "pref-lang")] + + def test_filter_by_username(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "bob", "page_size": 100}) + assert self.keys_in(response) == [("bob", "time_zone")] + + def test_the_owner_id_the_earlier_list_took_is_refused_rather_than_ignored(self): + """A caller that ported by changing the version segment is told, not quietly unfiltered.""" + self.login(self.admin) + response = self.client.get(self.url, {"user": self.alice.id, "page_size": 100}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "user": [f"No such query parameter. Send any of: {PREFERENCE_QUERY_PARAMS}."], + } + + def test_an_answered_page_announces_no_deprecated_parameter(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice"}) + assert response.status_code == status.HTTP_200_OK + assert "Deprecation" not in response + + def test_ordering_by_key_descending(self): + self.login(self.admin) + response = self.client.get(self.url, {"ordering": "-key", "page_size": 100}) + assert self.keys_in(response) == [("bob", "time_zone"), ("alice", "pref-lang")] + + def test_ordering_takes_the_fields_in_the_order_they_are_named(self): + UserPreferenceFactory.create(user=self.bob, key="pref-lang", value="fr") + self.login(self.admin) + response = self.client.get(self.url, {"ordering": "key,-username", "page_size": 100}) + assert self.keys_in(response) == [ + ("bob", "pref-lang"), ("alice", "pref-lang"), ("bob", "time_zone"), + ] + + def test_unknown_ordering_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url, {"ordering": "value", "page_size": 100}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "ordering": ["Sort by any of: key, username, each optionally prefixed with '-'."], + } + + def test_listing_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + self.client.get(self.url, {"page_size": 100}) + assert write_queries(captured.captured_queries) == [] + + def test_full_view_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + self.client.get(self.url, {"page_size": 100, "view": "full"}) + assert write_queries(captured.captured_queries) == [] + + def test_head_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + response = self.client.head(self.url) + assert response.status_code == status.HTTP_200_OK + assert write_queries(captured.captured_queries) == [] + + def test_an_unknown_response_preset_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url, {"view": "nonsense"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "view": [ + "Ask for any of: full, minimal, or omit this parameter for the default response.", + ], + } + + +@skip_unless_lms +class UserPreferenceDetailViewTests(UserApiV2TestCase): + """GET /api/user/v2/user_preferences/{username},{key}/""" + + def url_for(self, username, key): + """Return the member address of one stored preference.""" + return reverse("user_v2:user_preference_detail", kwargs={"username": username, "key": key}) + + def test_anonymous_caller_is_unauthenticated(self): + response = self.client.get(self.url_for("alice", "pref-lang")) + assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") + + def test_non_admin_caller_is_forbidden(self): + self.login(self.learner) + response = self.client.get(self.url_for("alice", "pref-lang")) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_owner_who_is_not_an_admin_is_forbidden(self): + self.login(self.alice) + response = self.client.get(self.url_for("alice", "pref-lang")) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + + def test_admin_caller_receives_the_preference(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice", "pref-lang")) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == {"username", "key", "value", "url", "user"} + assert response.data["username"] == "alice" + assert response.data["key"] == "pref-lang" + assert response.data["value"] == "en" + assert response.data["user"] is None + + def test_full_view_embeds_the_owning_user(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice", "pref-lang"), {"view": "full"}) + assert response.data["user"]["username"] == "alice" + + def test_a_field_name_the_preference_does_not_carry_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice", "pref-lang"), {"fields": "preference_key"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "fields": [ + "No such field: preference_key. " + "Select any of: key, url, user, username, value.", + ], + } + + def test_unknown_key_is_not_found(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice", "nope")) + assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") + + def test_key_belonging_to_another_user_is_not_found(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice", "time_zone")) + assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") + + def test_an_unknown_response_preset_is_refused(self): + self.login(self.admin) + response = self.client.get(self.url_for("alice", "pref-lang"), {"view": "nonsense"}) + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + + def test_retrieval_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + self.client.get(self.url_for("alice", "pref-lang")) + assert write_queries(captured.captured_queries) == [] + + def test_head_writes_nothing(self): + self.login(self.admin) + with CaptureQueriesContext(connection) as captured: + response = self.client.head(self.url_for("alice", "pref-lang")) + assert response.status_code == status.HTTP_200_OK + assert write_queries(captured.captured_queries) == [] + + +@skip_unless_lms +class TimeZoneListViewTests(UserApiV2TestCase): + """GET /api/user/v2/time_zones/""" + + def setUp(self): + super().setUp() + self.url = reverse("user_v2:time_zone_list") + + def test_anonymous_caller_receives_the_list(self): + response = self.client.get(self.url) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PAGINATION_KEYS + assert len(response.data["results"]) == 10 + assert set(response.data["results"][0]) == {"time_zone", "description"} + + def test_authenticated_caller_receives_the_same_count(self): + anonymous_count = self.client.get(self.url).data["count"] + self.login(self.learner) + response = self.client.get(self.url) + assert response.data["count"] == anonymous_count + + def test_country_code_narrows_the_list(self): + response = self.client.get(self.url, {"country_code": "FR", "page_size": 100}) + assert [row["time_zone"] for row in response.data["results"]] == ["Europe/Paris"] + + def test_country_code_is_case_insensitive(self): + upper = self.client.get(self.url, {"country_code": "FR", "page_size": 100}).data["results"] + lower = self.client.get(self.url, {"country_code": "fr", "page_size": 100}).data["results"] + assert upper == lower + + def test_country_without_time_zones_falls_back_to_every_zone(self): + every = self.client.get(self.url).data["count"] + response = self.client.get(self.url, {"country_code": "BV"}) + assert response.data["count"] == every + + def test_an_empty_country_code_returns_every_zone(self): + """A query string built from an empty variable narrows nothing rather than failing.""" + every = self.client.get(self.url).data["count"] + response = self.client.get(self.url, {"country_code": ""}) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == every + + def test_a_page_beyond_the_last_one_is_not_found(self): + """The list is public, so its most common failure is answered to anyone.""" + response = self.client.get(self.url, {"page": 9999}) + assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") + + def test_malformed_country_code_is_rejected(self): + response = self.client.get(self.url, {"country_code": "FRA"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "country_code": ["Enter a two-letter ISO 3166-1 alpha-2 country code, for example FR."], + } + + def test_listing_writes_nothing(self): + with CaptureQueriesContext(connection) as captured: + self.client.get(self.url, {"page_size": 100}) + assert write_queries(captured.captured_queries) == [] + + def test_head_writes_nothing(self): + with CaptureQueriesContext(connection) as captured: + response = self.client.head(self.url) + assert response.status_code == status.HTTP_200_OK + assert write_queries(captured.captured_queries) == [] + + +@skip_unless_lms +class PageSizeCapTests(UserApiV2TestCase): + """ + No caller can ask any of the lists for more rows than one maximum page. + + The time-zone list is the one a caller reaches without signing in, and it + is long enough to be worth asking for whole, so the cap is asserted against + live rows on every list rather than read off the paginator. + """ + + MAX_PAGE_SIZE = 100 + + def test_the_directory_page_is_capped(self): + User.objects.bulk_create( + User(username=f"extra-{index:03d}", email=f"extra-{index:03d}@example.com") + for index in range(self.MAX_PAGE_SIZE) + ) + self.login(self.admin) + response = self.client.get(reverse("user_v2:user_list"), {"page_size": 1000}) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == self.MAX_PAGE_SIZE + 4 + assert len(response.data["results"]) == self.MAX_PAGE_SIZE + assert response.data["num_pages"] == 2 + assert response.data["next"] is not None + + def test_the_stored_preference_page_is_capped(self): + UserPreference.objects.bulk_create( + UserPreference(user=self.alice, key=f"extra-{index:03d}", value="x") + for index in range(self.MAX_PAGE_SIZE) + ) + self.login(self.admin) + response = self.client.get(reverse("user_v2:user_preference_list"), {"page_size": 1000}) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == self.MAX_PAGE_SIZE + 2 + assert len(response.data["results"]) == self.MAX_PAGE_SIZE + assert response.data["num_pages"] == 2 + + def test_the_time_zone_page_is_capped_for_an_anonymous_caller(self): + every_zone = len(get_country_time_zones()) + assert every_zone > self.MAX_PAGE_SIZE, every_zone + response = self.client.get(reverse("user_v2:time_zone_list"), {"page_size": 1000}) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == every_zone + assert len(response.data["results"]) == self.MAX_PAGE_SIZE + assert response.data["num_pages"] == ceil(every_zone / self.MAX_PAGE_SIZE) + + +@skip_unless_lms +class RefusedRequestTests(UserApiV2TestCase): + """A method this API does not serve, and an Accept header it cannot answer.""" + + #: Public, standardized, and served by another API: what its refused method + #: is called must not change because this one names its own. + OTHER_API_URL = "/api/enrollment/v2/courses/course-v1:edX+DemoX+Demo/" + + def setUp(self): + super().setUp() + self.public_url = reverse("user_v2:time_zone_list") + + def test_a_refused_method_is_named_for_an_anonymous_caller(self): + response = self.client.post(self.public_url, {}, format="json") + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + assert envelope["title"] == "Method Not Allowed" + assert envelope["detail"] == 'Method "POST" not allowed.' + assert response["Content-Type"] == "application/json" + + def test_an_accept_header_this_api_cannot_answer_is_named(self): + response = self.client.get(self.public_url, HTTP_ACCEPT="application/xml") + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_406_NOT_ACCEPTABLE, + expected_type_slug="not-acceptable", + ) + assert envelope["title"] == "Not Acceptable" + assert envelope["detail"] == "Could not satisfy the request Accept header." + assert response["Content-Type"] == "application/json" + + def test_a_refused_method_is_named_on_the_gated_collections(self): + self.login(self.admin) + for url_name in ("user_v2:user_list", "user_v2:user_preference_list"): + response = self.client.delete(reverse(url_name)) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + assert envelope["detail"] == 'Method "DELETE" not allowed.' + + def test_a_refused_method_is_named_on_the_gated_members(self): + self.login(self.admin) + response = self.client.put(reverse("user_v2:user_detail", args=[self.alice.username])) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + assert envelope["detail"] == 'Method "PUT" not allowed.' + + def test_another_api_is_classified_exactly_as_the_shared_catalog_classifies_it(self): + """The catalog names no refused method, and nothing here changes that for anyone else.""" + response = self.client.post(self.OTHER_API_URL, {}, format="json") + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="internal", + ) + assert envelope["title"] == "Internal Server Error" + + +@skip_unless_lms +class UnknownQueryParameterTests(UserApiV2TestCase): + """Each endpoint refuses a query parameter it reads nothing from, and takes the rest.""" + + def setUp(self): + super().setUp() + self.user_list = reverse("user_v2:user_list") + self.user_detail = reverse("user_v2:user_detail", kwargs={"username": "alice"}) + self.preference_list = reverse("user_v2:user_preference_list") + self.preference_detail = reverse( + "user_v2:user_preference_detail", kwargs={"username": "alice", "key": "pref-lang"}, + ) + self.time_zone_list = reverse("user_v2:time_zone_list") + + def assert_refused(self, response, name, offered): + """Assert the response named the parameter it would not take, and the ones it takes.""" + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {name: [f"No such query parameter. Send any of: {offered}."]} + + def assert_each_is_answered(self, address, parameter_sets): + """Assert the endpoint answers each of these query strings.""" + for params in parameter_sets: + with self.subTest(params=params): + response = self.client.get(address, params) + assert response.status_code == status.HTTP_200_OK, response.content + + def test_the_directory_refuses_a_parameter_it_does_not_read(self): + self.login(self.admin) + response = self.client.get(self.user_list, {"lms_user_id": self.alice.id, "page_size": 100}) + self.assert_refused(response, "lms_user_id", USER_QUERY_PARAMS) + + def test_a_mistyped_filter_refuses_the_page_instead_of_returning_every_row(self): + self.login(self.admin) + response = self.client.get(self.user_list, {"usernme": "alice", "page_size": 100}) + self.assert_refused(response, "usernme", USER_QUERY_PARAMS) + + def test_every_unrecognised_parameter_is_named_at_once(self): + self.login(self.admin) + response = self.client.get(self.user_list, {"sort": "username", "limit": "10"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert sorted(envelope["errors"]) == ["limit", "sort"] + + def test_a_directory_entry_refuses_a_parameter_it_does_not_read(self): + self.login(self.admin) + response = self.client.get(self.user_detail, {"expand": "profile"}) + self.assert_refused(response, "expand", USER_QUERY_PARAMS) + + def test_the_preference_list_refuses_a_parameter_it_does_not_read(self): + self.login(self.admin) + response = self.client.get(self.preference_list, {"value": "en", "page_size": 100}) + self.assert_refused(response, "value", PREFERENCE_QUERY_PARAMS) + + def test_a_stored_preference_refuses_a_parameter_it_does_not_read(self): + self.login(self.admin) + response = self.client.get(self.preference_detail, {"value": "en"}) + self.assert_refused(response, "value", PREFERENCE_QUERY_PARAMS) + + def test_the_time_zone_list_refuses_a_parameter_it_does_not_read(self): + response = self.client.get(self.time_zone_list, {"country": "FR"}) + self.assert_refused(response, "country", TIME_ZONE_QUERY_PARAMS) + + def test_the_time_zone_list_refuses_a_sort_it_does_not_offer(self): + """This list is ordered by its display form and reads no sort parameter.""" + response = self.client.get(self.time_zone_list, {"ordering": "country_code"}) + self.assert_refused(response, "ordering", TIME_ZONE_QUERY_PARAMS) + + def test_an_unknown_parameter_does_not_answer_an_anonymous_caller(self): + response = self.client.get(self.user_list, {"lms_user_id": self.alice.id}) + assert_error_envelope( + response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + def test_an_unknown_parameter_does_not_answer_a_non_admin_caller(self): + self.login(self.learner) + response = self.client.get(self.preference_list, {"lms_user_id": self.alice.id}) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_the_directory_answers_every_parameter_it_reads(self): + self.login(self.admin) + self.assert_each_is_answered(self.user_list, [ + {"page": 1}, + {"page_size": 2}, + {"ordering": "-username"}, + {"view": "minimal"}, + {"fields": "username"}, + {"format": "json"}, + {"username": "alice"}, + {"email": "alice@example.com"}, + {"is_active": "true"}, + {"preference_key": "pref-lang"}, + {"forum_role": "Moderator", "course_key": str(COURSE_KEY)}, + ]) + + def test_a_directory_entry_answers_every_parameter_it_reads(self): + self.login(self.admin) + self.assert_each_is_answered(self.user_detail, [ + {"view": "minimal"}, {"fields": "username"}, {"format": "json"}, {"ordering": "username"}, + ]) + + def test_the_preference_list_answers_every_parameter_it_reads(self): + self.login(self.admin) + self.assert_each_is_answered(self.preference_list, [ + {"page": 1}, + {"page_size": 2}, + {"ordering": "-key"}, + {"view": "full"}, + {"fields": "key"}, + {"format": "json"}, + {"key": "pref-lang"}, + {"username": "alice"}, + ]) + + def test_a_stored_preference_answers_every_parameter_it_reads(self): + self.login(self.admin) + self.assert_each_is_answered(self.preference_detail, [ + {"view": "full"}, {"fields": "key"}, {"format": "json"}, + ]) + + def test_the_time_zone_list_answers_every_parameter_it_reads(self): + self.assert_each_is_answered(self.time_zone_list, [ + {"country_code": "FR"}, {"page": 1}, {"page_size": 5}, {"format": "json"}, + ]) + + def test_a_page_of_the_directory_is_still_narrowed_by_the_filters_it_takes(self): + """The refusal guards the parameters, not the filtering they ask for.""" + self.login(self.admin) + response = self.client.get(self.user_list, {"username": "alice", "page_size": 100}) + assert self.usernames_in(response) == ["alice"] + + +@skip_unless_lms +class TokenCallerTests(UserApiV2TestCase): + """The staff-gated endpoints answer a bearer of a staff token and refuse everyone else.""" + + def setUp(self): + super().setUp() + self.addresses = { + "user_list": reverse("user_v2:user_list"), + "user_detail": reverse("user_v2:user_detail", kwargs={"username": "alice"}), + "preference_list": reverse("user_v2:user_preference_list"), + "preference_detail": reverse( + "user_v2:user_preference_detail", kwargs={"username": "alice", "key": "pref-lang"}, + ), + } + + def token_headers(self, user): + """Return the request headers that carry a token identifying the given user.""" + return {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(user)}"} + + def test_a_staff_token_reaches_the_directory(self): + response = self.client.get( + self.addresses["user_list"], {"page_size": 100}, **self.token_headers(self.admin), + ) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] + assert response.data["count"] == 4 + + def test_a_staff_token_reaches_every_staff_gated_address(self): + headers = self.token_headers(self.admin) + detail = self.client.get(self.addresses["user_detail"], **headers) + assert detail.status_code == status.HTTP_200_OK + assert detail.data["username"] == "alice" + + preferences = self.client.get( + self.addresses["preference_list"], {"username": "alice"}, **headers, + ) + assert preferences.status_code == status.HTTP_200_OK + assert [(row["username"], row["key"]) for row in preferences.data["results"]] == [ + ("alice", "pref-lang"), + ] + + preference = self.client.get(self.addresses["preference_detail"], **headers) + assert preference.status_code == status.HTTP_200_OK + assert preference.data["value"] == "en" + + def test_the_token_and_not_a_session_identifies_the_caller(self): + token = create_jwt_for_user(self.admin) + response = self.client.get( + self.addresses["user_list"], {"username": "alice"}, HTTP_AUTHORIZATION=f"JWT {token}", + ) + assert response.status_code == status.HTTP_200_OK + assert response.wsgi_request.user == self.admin + assert response.wsgi_request.auth == token + assert "sessionid" not in response.wsgi_request.COOKIES + + def test_a_learners_token_is_forbidden_on_every_staff_gated_address(self): + headers = self.token_headers(self.learner) + for name, address in self.addresses.items(): + with self.subTest(address=name): + response = self.client.get(address, **headers) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_the_owner_of_the_record_is_still_not_staff(self): + response = self.client.get( + self.addresses["preference_detail"], **self.token_headers(self.alice), + ) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_a_token_that_does_not_decode_is_unauthenticated(self): + response = self.client.get( + self.addresses["user_list"], HTTP_AUTHORIZATION="JWT not.a.token", + ) + assert_error_envelope( + response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + +@skip_unless_lms +class SharedSortValueTests(UserApiV2TestCase): + """Users that compare equal on the sorted column are ordered the same way on every page.""" + + def setUp(self): + super().setUp() + self.url = reverse("user_v2:user_list") + joined = datetime(2024, 3, 1, tzinfo=UTC) + for username in ("zoe-shared", "mia-shared", "ada-shared"): + UserFactory.create(username=username, date_joined=joined) + self.login(self.admin) + + def test_users_sharing_a_join_date_are_ordered_by_username(self): + response = self.client.get(self.url, {"ordering": "date_joined", "page_size": 100}) + shared = [name for name in self.usernames_in(response) if name.endswith("-shared")] + assert shared == ["ada-shared", "mia-shared", "zoe-shared"] + + def test_the_sort_the_caller_asked_for_still_decides_the_order(self): + """The tie-break settles rows that compare equal; the requested sort places them.""" + response = self.client.get(self.url, {"ordering": "-date_joined", "page_size": 100}) + assert self.usernames_in(response)[:3] == ["ada-shared", "mia-shared", "zoe-shared"] + + def test_paging_through_a_shared_join_date_lists_each_user_once(self): + listed = [] + for page in (1, 2, 3): + response = self.client.get( + self.url, {"ordering": "date_joined", "page_size": 3, "page": page}, + ) + listed.extend(self.usernames_in(response)) + assert sorted(listed) == [ + "ada-shared", "admin-caller", "alice", "bob", "learner-caller", "mia-shared", "zoe-shared", + ] + + +@skip_unless_lms +class DeactivatedStaffCallerTests(UserApiV2TestCase): + """ + A staff account whose user record has been deactivated is refused by both halves of + the default authentication pair: the session half stops accepting it, and the active + account these views require refuses a token issued before the account was deactivated. + """ + + def setUp(self): + super().setUp() + self.url = reverse("user_v2:user_list") + self.staff = AdminFactory.create(username="deactivated-admin", password=PASSWORD) + self.staff_gated = { + "user_list": self.url, + "user_detail": reverse("user_v2:user_detail", kwargs={"username": "alice"}), + "preference_list": reverse("user_v2:user_preference_list"), + "preference_detail": reverse( + "user_v2:user_preference_detail", kwargs={"username": "alice", "key": "pref-lang"}, + ), + } + + def deactivate(self, user): + """Clear an account's active flag the way an operator does, leaving its staff flag.""" + user.is_active = False + user.save() + + def test_a_session_held_by_a_deactivated_staff_account_is_refused(self): + self.login(self.staff) + assert self.client.get(self.url).status_code == status.HTTP_200_OK + self.deactivate(self.staff) + response = self.client.get(self.url) + assert_error_envelope( + response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + def test_a_token_held_by_a_deactivated_staff_account_is_refused(self): + headers = {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(self.staff)}"} + assert self.client.get(self.url, **headers).status_code == status.HTTP_200_OK + self.deactivate(self.staff) + response = self.client.get(self.url, {"page_size": 100}, **headers) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_a_deactivated_staff_token_is_refused_at_every_staff_gated_address(self): + self.deactivate(self.staff) + headers = {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(self.staff)}"} + for name, address in self.staff_gated.items(): + with self.subTest(address=name): + response = self.client.get(address, **headers) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_a_deactivated_staff_session_is_refused_at_every_staff_gated_address(self): + self.login(self.staff) + self.deactivate(self.staff) + for name, address in self.staff_gated.items(): + with self.subTest(address=name): + response = self.client.get(address) + assert_error_envelope( + response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + def test_the_directory_does_not_list_the_account_that_was_refused(self): + """The refusal is the whole response: no row of the page leaks past it.""" + self.deactivate(self.staff) + response = self.client.get( + self.url, {"page_size": 100}, HTTP_AUTHORIZATION=f"JWT {create_jwt_for_user(self.staff)}", + ) + assert response.status_code == status.HTTP_403_FORBIDDEN + assert "results" not in response.data + + def test_an_active_staff_token_still_reaches_the_directory(self): + response = self.client.get( + self.url, {"page_size": 100}, HTTP_AUTHORIZATION=f"JWT {create_jwt_for_user(self.staff)}", + ) + assert response.status_code == status.HTTP_200_OK + assert "deactivated-admin" in self.usernames_in(response) + + def test_a_token_held_by_a_deactivated_learner_is_still_forbidden(self): + self.deactivate(self.learner) + response = self.client.get( + self.url, HTTP_AUTHORIZATION=f"JWT {create_jwt_for_user(self.learner)}", + ) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + +@skip_unless_lms +class PreferenceSerializerTests(UserApiV2TestCase): + """The preference address is built with or without a request to make it absolute.""" + + def test_url_is_relative_without_a_request(self): + preference = self.alice.preferences.get(key="pref-lang") + data = UserPreferenceRecordSerializer(preference).data + assert data["url"] == "/api/user/v2/user_preferences/alice,pref-lang/" + assert data["user"] is None diff --git a/openedx/core/djangoapps/user_api/v2/urls.py b/openedx/core/djangoapps/user_api/v2/urls.py new file mode 100644 index 000000000000..911fb321af69 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/urls.py @@ -0,0 +1,71 @@ +"""URLs for version 2 of the User API.""" + +from django.conf import settings +from django.core.exceptions import ImproperlyConfigured +from django.urls import re_path +from rest_framework.routers import SimpleRouter + +from .views import ( + PREFERENCE_KEY_PATTERN_PARTIAL, + CountryTimeZoneViewSet, + UnknownAddressView, + UserPreferenceViewSet, + UserViewSet, +) + +app_name = "user_v2" + +#: A preference is identified by its owner and its key, so the router's +#: database-id member route is dropped and replaced by the address declared +#: below under the same name. +REPLACED_ROUTER_ROUTE = "user_preference_detail" + + +def without_route(routes, name): + """ + Return ``routes`` without the one registered under ``name``. + + A name that matches nothing means the router stopped generating that route + under that name: the address it serves would then be published alongside + the one declared here instead of being replaced by it, so the mismatch is + refused here rather than discovered at the address. + """ + kept = [route for route in routes if route.name != name] + if len(kept) == len(routes): + raise ImproperlyConfigured(f"The router registers no route named {name!r} to replace.") + return kept + + +class SnakeCaseRouter(SimpleRouter): + """ + A router that names its routes ``_``. + + The names a route is registered under are the ones ``resolve()`` reports + and the ones ``reverse()`` accepts, so they are generated in the published + form rather than rewritten afterwards. + """ + + routes = [route._replace(name=route.name.replace("-", "_")) for route in SimpleRouter.routes] + + +router = SnakeCaseRouter() +router.register(r"users", UserViewSet, basename="user") +router.register(r"user_preferences", UserPreferenceViewSet, basename="user_preference") +router.register(r"time_zones", CountryTimeZoneViewSet, basename="time_zone") + + +urlpatterns = [ + *without_route(router.urls, REPLACED_ROUTER_ROUTE), + # The username half carries the pattern a username is allowed to match and + # the key half takes the rest of the segment. + re_path( + rf"^user_preferences/(?P{settings.USERNAME_REGEX_PARTIAL})" + rf",(?P{PREFERENCE_KEY_PATTERN_PARTIAL})/$", + UserPreferenceViewSet.as_view({"get": "retrieve"}), + name="user_preference_detail", + ), + # The authentication app serves two addresses under this prefix, which this + # mount is matched before; everything else under it belongs to this version. + # The route answers rather than reverses, so it carries no name. + re_path(r"^(?!account/).*$", UnknownAddressView.as_view()), +] diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py new file mode 100644 index 000000000000..6022c5dcec40 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -0,0 +1,593 @@ +"""Views for version 2 of the User API.""" + +import logging + +from django.conf import settings +from django.contrib.auth.models import User # pylint: disable=imported-auth-user +from django.db.models import F +from django.http import Http404 +from django_filters.rest_framework import DjangoFilterBackend +from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema, extend_schema_view +from edx_rest_framework_extensions.mixins import StandardizedErrorMixin +from edx_rest_framework_extensions.paginators import IterablePaginationMixin +from edx_rest_framework_extensions.scoping import FullScopePolicy, ScopedQuerysetMixin +from edx_rest_framework_extensions.shaping import MinimalViewMixin, project +from rest_framework import permissions, viewsets +from rest_framework.exceptions import NotFound, ValidationError +from rest_framework.reverse import reverse +from rest_framework.settings import api_settings +from rest_framework.views import APIView + +from openedx.core.djangoapps.user_api.models import UserPreference +from openedx.core.djangoapps.user_api.preferences.api import get_country_time_zones + +from .errors import CatalogedRequestErrorsMixin +from .filters import StrictOrderingFilter, UserFilterSet, UserPreferenceFilterSet +from .paginators import UserApiPagination +from .permissions import IsActiveUser +from .schema import ResponseShapes +from .serializers import ( + FULL_VIEW, + MINIMAL_VIEW, + PREFERENCE_MINIMAL_FIELDS, + USER_MINIMAL_FIELDS, + ErrorResponse, + TimeZoneQuerySerializer, + TimeZoneSerializer, + UserDirectoryMinimalSerializer, + UserDirectoryProjectionSerializer, + UserDirectorySerializer, + UserPreferenceRecordMinimalSerializer, + UserPreferenceRecordProjectionSerializer, + UserPreferenceRecordSerializer, + full_view_requested, +) + +log = logging.getLogger(__name__) + +USER_TAG = "user" + +#: Fields the user directory sorts on, and the order it uses when asked for none. +USER_SORT_FIELDS = ("username", "date_joined") +USER_DEFAULT_SORT = ("username",) + +#: Fields the stored-preference list sorts on, and the order it uses when asked for none. +PREFERENCE_SORT_FIELDS = ("key", "username") +PREFERENCE_DEFAULT_SORT = ("username", "key") + +#: The part of a preference's address that carries its key. The key is +#: free-form text that may itself contain a comma, so it takes the rest of the +#: segment; the route and the published address are built from this one pattern. +PREFERENCE_KEY_PATTERN_PARTIAL = "[^/]+" + + +def _query_param(name, description, **kwargs): + """Build an optional query parameter for the published schema.""" + return OpenApiParameter( + name=name, + description=description, + required=False, + location=OpenApiParameter.QUERY, + **kwargs, + ) + + +def _path_param(name, description, pattern): + """Build a path parameter for the published schema, carrying what its route matches.""" + return OpenApiParameter( + name=name, + description=description, + required=True, + location=OpenApiParameter.PATH, + type=str, + pattern=pattern, + ) + + +_USERNAME_PATTERN = rf"^{settings.USERNAME_REGEX_PARTIAL}$" + +_USER_PATH_PARAM = _path_param( + "username", + "Unique name of the user whose directory entry is returned.", + _USERNAME_PATTERN, +) +_PREFERENCE_USERNAME_PATH_PARAM = _path_param( + "username", + "Username of the user the preference belongs to: the part of the address before the comma.", + _USERNAME_PATTERN, +) +_PREFERENCE_KEY_PATH_PARAM = _path_param( + "key", + "Name the preference is stored under: the part of the address after the comma.", + rf"^{PREFERENCE_KEY_PATTERN_PARTIAL}$", +) + +#: Parameters that shape a response rather than select the rows in it. +VIEW_PARAM = "view" +FIELDS_PARAM = "fields" +RESPONSE_SHAPING_PARAMS = (VIEW_PARAM, FIELDS_PARAM) + +#: The framework's own representation selector. This deployment reads nothing +#: from it, since ``URL_FORMAT_OVERRIDE`` is unset and JSON is the only +#: renderer, and a caller that sends it anyway is answered rather than refused. +FORMAT_PARAM = "format" + +_FIELDS_PARAM = _query_param( + FIELDS_PARAM, + "Comma-separated list of top-level field names to keep in each returned object. " + "A name the response cannot carry is refused.", +) +#: The presets each list answers to, published as the parameter's enum and +#: accepted by the view from the same declaration. +USER_PRESETS = (MINIMAL_VIEW,) +PREFERENCE_PRESETS = (FULL_VIEW, MINIMAL_VIEW) + +_MINIMAL_VIEW_PARAM = _query_param( + VIEW_PARAM, + "Response preset. `minimal` reduces each user to its identifying fields " + "(`id`, `username`, `email`). Omit it to receive the full entry.", + enum=list(USER_PRESETS), +) +_PREFERENCE_VIEW_PARAM = _query_param( + VIEW_PARAM, + "Response preset. `full` embeds the owning user's whole directory entry in each " + "preference; `minimal` returns only `username`, `key` and `value`. Omit it to " + "receive the owner's username alongside the preference.", + enum=list(PREFERENCE_PRESETS), +) + + +def _ordering_param(sort_fields, default): + """Build the sort parameter of a list, naming the fields it accepts.""" + return _query_param( + "ordering", + "Fields to sort by, in order of precedence, each optionally prefixed with `-` to sort " + "descending. A field that is not listed here is refused.", + many=True, + enum=[*sort_fields, *(f"-{field}" for field in sort_fields)], + default=list(default), + style="form", + explode=False, + ) + + +_USER_ORDERING_PARAM = _ordering_param(USER_SORT_FIELDS, USER_DEFAULT_SORT) +_PREFERENCE_ORDERING_PARAM = _ordering_param(PREFERENCE_SORT_FIELDS, PREFERENCE_DEFAULT_SORT) + +_RESP_UNAUTHENTICATED = OpenApiResponse(ErrorResponse, description="The requester is not authenticated.") +_RESP_FORBIDDEN = OpenApiResponse(ErrorResponse, description="The requester may not use this endpoint.") +_RESP_NOT_FOUND = OpenApiResponse(ErrorResponse, description="No such resource.") +_RESP_NO_SUCH_PAGE = OpenApiResponse(ErrorResponse, description="There is no such page of results.") +_RESP_BAD_REQUEST = OpenApiResponse( + ErrorResponse, description="A query parameter is missing, invalid, or not one this endpoint reads.", +) + +#: A directory entry comes back whole, as the identifying fields the ``minimal`` +#: preset keeps, or as the properties ``fields`` selected. +_USER_SHAPES = ResponseShapes( + component_name="UserDirectoryResponse", + serializers=[ + UserDirectorySerializer, + UserDirectoryMinimalSerializer, + UserDirectoryProjectionSerializer, + ], +) + +#: A stored preference comes back whole, as the three fields the ``minimal`` +#: preset keeps, or as the properties ``fields`` selected. +_PREFERENCE_SHAPES = ResponseShapes( + component_name="UserPreferenceRecordResponse", + serializers=[ + UserPreferenceRecordSerializer, + UserPreferenceRecordMinimalSerializer, + UserPreferenceRecordProjectionSerializer, + ], +) + + +class _MemberLookupMixin: + """Report a missing member through the standard error envelope.""" + + def get_object(self): + try: + return super().get_object() + except Http404 as exc: + raise NotFound from exc + + +class _ActionAddressMixin: + """ + Builds the address of an action from the snake_case names these routes carry. + + A router names an action ``-`` by default, and that name + belongs to an earlier mount of the same resource, so the default lookup + would hand out the older address instead of this one. + """ + + #: The namespace these routes are mounted under, read when an address is + #: asked for outside a request and there is no resolver match to take it from. + url_namespace = "user_v2" + + def reverse_action(self, url_name, *args, **kwargs): + """Return the address of one of this viewset's actions.""" + request = getattr(self, "request", None) + namespace = self.url_namespace + if request is not None and request.resolver_match is not None: + namespace = request.resolver_match.namespace or namespace + kwargs.setdefault("request", request) + return reverse(f"{namespace}:{self.basename}_{url_name}", *args, **kwargs) + + +def _requested_field_names(raw): + """Return the top-level property names a ``fields`` value asks for.""" + if not raw: + return [] + return [name.strip().split(".", 1)[0] for name in raw.split(",") if name.strip()] + + +class _StrictQueryParametersMixin: + """ + Refuses a query parameter the view reads nothing from. + + An unknown parameter is otherwise dropped in silence: a caller that + mistyped a filter, or kept one an earlier version of the endpoint + answered, receives the whole collection and reads it as the narrowed page + it asked for. The names a view answers to are assembled from what it + declares (its paginator, its sort backend, its filter set, and the + serializer that validates its query string), so a parameter that is added + or renamed cannot fall out of step with this check. + """ + + #: Names the view reads that none of the declarations below account for. + extra_query_params = () + + def known_query_params(self): + """Return the names of the query parameters this view reads.""" + names = {FORMAT_PARAM, api_settings.URL_FORMAT_OVERRIDE, *self.extra_query_params} + pagination_class = getattr(self, "pagination_class", None) + if pagination_class is not None: + names.update({pagination_class.page_query_param, pagination_class.page_size_query_param}) + for backend in getattr(self, "filter_backends", ()): + names.add(getattr(backend, "ordering_param", None)) + filterset_class = getattr(self, "filterset_class", None) + if filterset_class is not None: + names.update(filterset_class.base_filters) + query_serializer_class = getattr(self, "query_serializer_class", None) + if query_serializer_class is not None: + names.update(query_serializer_class().fields) + return names - {None} + + def initial(self, request, *args, **kwargs): + """Check the query string once the caller has been admitted.""" + super().initial(request, *args, **kwargs) + known = self.known_query_params() + unknown = sorted(set(request.query_params) - known) + if unknown: + log.info("Query refused on %s: %r", type(self).__name__, unknown) + offered = ", ".join(sorted(known)) + raise ValidationError({ + name: [f"No such query parameter. Send any of: {offered}."] + for name in unknown + }) + + +class _ResponsePresetMixin(MinimalViewMixin): + """ + Applies the ``view`` and ``fields`` presets to an already serialized payload. + + A view lists the presets it answers to, and a ``view`` value outside that + list is refused: a caller that mistypes a preset asked for a smaller + payload and would otherwise be handed the full one without being told. + The same holds for a field name the response cannot carry, which would + otherwise select nothing and leave the caller with empty objects. + """ + + #: Presets this view answers to. An empty ``view`` narrows nothing, the way + #: an empty value of any other parameter does. + response_presets = () + + def initial(self, request, *args, **kwargs): + """Check the requested preset and fields once the caller has been admitted.""" + super().initial(request, *args, **kwargs) + preset = request.query_params.get(VIEW_PARAM) + if preset and preset not in self.response_presets: + raise ValidationError({ + VIEW_PARAM: [ + f"Ask for any of: {', '.join(self.response_presets)}, " + "or omit this parameter for the default response.", + ], + }) + self.check_requested_fields(request) + + def shapeable_fields(self): + """Return the names of the properties a response of this view can carry.""" + if self.is_minimal_view_requested(): + return set(self.minimal_fields) + return set(self.get_serializer_class()().fields) + + def check_requested_fields(self, request): + """Refuse a selected field the response cannot carry, naming the ones it can.""" + available = self.shapeable_fields() + unknown = sorted(set(_requested_field_names(request.query_params.get(FIELDS_PARAM))) - available) + if unknown: + raise ValidationError({ + FIELDS_PARAM: [ + f"No such field: {', '.join(unknown)}. " + f"Select any of: {', '.join(sorted(available))}.", + ], + }) + + def shape(self, data, request): + """Return ``data`` reduced to the preset and the fields the caller asked for.""" + data = self.shape_minimal(data, request) + requested_fields = request.query_params.get(FIELDS_PARAM) + if not requested_fields: + return data + if isinstance(data, list): + return [project(item, requested_fields) for item in data] + return project(data, requested_fields) + + def shape_page(self, response, request): + """Shape the items of a paginated response in place.""" + response.data["results"] = self.shape(response.data["results"], request) + return response + + +@extend_schema(tags=[USER_TAG]) +@extend_schema_view( + list=extend_schema( + summary="List users", + description=( + "Returns a page of the user directory. Supply `preference_key` to keep only the " + "users who have stored a preference under that key, or `forum_role` together with " + "`course_key` to keep only the holders of a course forum role." + ), + parameters=[_MINIMAL_VIEW_PARAM, _FIELDS_PARAM, _USER_ORDERING_PARAM], + responses={ + 200: _USER_SHAPES, + 400: _RESP_BAD_REQUEST, + 401: _RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_NO_SUCH_PAGE, + }, + ), + retrieve=extend_schema( + summary="Get one user", + description="Returns the directory entry of the user with this username.", + parameters=[_USER_PATH_PARAM, _MINIMAL_VIEW_PARAM, _FIELDS_PARAM], + responses={ + 200: _USER_SHAPES, + 400: _RESP_BAD_REQUEST, + 401: _RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_NOT_FOUND, + }, + ), +) +class UserViewSet( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + _ActionAddressMixin, + _MemberLookupMixin, + _ResponsePresetMixin, + _StrictQueryParametersMixin, + ScopedQuerysetMixin, + viewsets.ReadOnlyModelViewSet, +): + """ + Read-only directory of platform users, addressed by username. + + Access is layered: ``permission_classes`` admits only platform + administrators whose account is still active, the scoping policy decides + which rows such an administrator may see, and the filter set narrows those + rows further by the caller's query parameters. + """ + + permission_classes = (permissions.IsAuthenticated, IsActiveUser, permissions.IsAdminUser) + serializer_class = UserDirectorySerializer + pagination_class = UserApiPagination + queryset = User.objects.all().prefetch_related("preferences").select_related("profile") + # Platform administrators may read every entry, so the policy keeps the + # queryset whole; a narrower policy can replace it without touching the + # filtering below. + scoping_policy = FullScopePolicy() + lookup_field = "username" + # The router's default lookup pattern excludes dots, which usernames allow. + lookup_value_regex = settings.USERNAME_REGEX_PARTIAL + filter_backends = (DjangoFilterBackend, StrictOrderingFilter) + filterset_class = UserFilterSet + ordering_fields = USER_SORT_FIELDS + ordering = USER_DEFAULT_SORT + # A sort the caller asks for is completed with these so that it is total: + # rows that compare equal would otherwise be ordered differently from one + # page to the next, and a client reading the pages in turn would see some + # of them twice and miss others. + ordering_tiebreak = ("username",) + minimal_fields = USER_MINIMAL_FIELDS + response_presets = USER_PRESETS + extra_query_params = RESPONSE_SHAPING_PARAMS + + def list(self, request, *args, **kwargs): + """Return a page of directory entries, shaped as the caller asked.""" + return self.shape_page(super().list(request, *args, **kwargs), request) + + def retrieve(self, request, *args, **kwargs): + """Return one directory entry, shaped as the caller asked.""" + response = super().retrieve(request, *args, **kwargs) + response.data = self.shape(response.data, request) + return response + + +@extend_schema(tags=[USER_TAG]) +@extend_schema_view( + list=extend_schema( + summary="List stored preferences", + description=( + "Returns a page of stored user preferences. Supply `key` to keep only the " + "preferences stored under that name, or `username` to keep only one user's." + ), + parameters=[_PREFERENCE_VIEW_PARAM, _FIELDS_PARAM, _PREFERENCE_ORDERING_PARAM], + responses={ + 200: _PREFERENCE_SHAPES, + 400: _RESP_BAD_REQUEST, + 401: _RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_NO_SUCH_PAGE, + }, + ), + retrieve=extend_schema( + summary="Get one stored preference", + description=( + "Returns the preference stored under this key for this user. A preference is " + "identified by the pair, which the address carries as the username, a comma and " + "the key, for example `alice,time_zone`." + ), + operation_id="v2_user_preferences_retrieve", + parameters=[ + _PREFERENCE_USERNAME_PATH_PARAM, + _PREFERENCE_KEY_PATH_PARAM, + _PREFERENCE_VIEW_PARAM, + _FIELDS_PARAM, + ], + responses={ + 200: _PREFERENCE_SHAPES, + 400: _RESP_BAD_REQUEST, + 401: _RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_NOT_FOUND, + }, + ), +) +class UserPreferenceViewSet( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + _ActionAddressMixin, + _ResponsePresetMixin, + _StrictQueryParametersMixin, + ScopedQuerysetMixin, + viewsets.ReadOnlyModelViewSet, +): + """ + Read-only list of stored user preferences, each addressed by its owner and key. + + A preference is identified by the pair, so the member address is + ``{username},{key}`` rather than a database id. Access is layered the same + way as the user directory: permission classes, then the scoping policy, + then the filter set. + """ + + permission_classes = (permissions.IsAuthenticated, IsActiveUser, permissions.IsAdminUser) + serializer_class = UserPreferenceRecordSerializer + pagination_class = UserApiPagination + queryset = ( + UserPreference.objects.all() + .select_related("user", "user__profile") + .annotate(username=F("user__username")) + ) + scoping_policy = FullScopePolicy() + filter_backends = (DjangoFilterBackend, StrictOrderingFilter) + filterset_class = UserPreferenceFilterSet + ordering_fields = PREFERENCE_SORT_FIELDS + ordering = PREFERENCE_DEFAULT_SORT + # The owner and the key identify a row, so they complete any sort the + # caller asks for and keep the order of a page stable. + ordering_tiebreak = ("username", "key") + minimal_fields = PREFERENCE_MINIMAL_FIELDS + response_presets = PREFERENCE_PRESETS + extra_query_params = RESPONSE_SHAPING_PARAMS + + def filter_queryset(self, queryset): + """Fetch each owner's own preferences too when they are about to be embedded.""" + queryset = super().filter_queryset(queryset) + if full_view_requested(getattr(self, "request", None)): + queryset = queryset.prefetch_related("user__preferences") + return queryset + + def get_object(self): + """Look the preference up by the username and key that identify it.""" + try: + preference = self.get_queryset().get( + user__username=self.kwargs["username"], key=self.kwargs["key"], + ) + except UserPreference.DoesNotExist as exc: + raise NotFound from exc + self.check_object_permissions(self.request, preference) + return preference + + def list(self, request, *args, **kwargs): + """Return a page of stored preferences, shaped as the caller asked.""" + return self.shape_page(super().list(request, *args, **kwargs), request) + + def retrieve(self, request, *args, **kwargs): + """Return one stored preference, shaped as the caller asked.""" + response = super().retrieve(request, *args, **kwargs) + response.data = self.shape(response.data, request) + return response + + +@extend_schema(tags=[USER_TAG]) +class CountryTimeZoneViewSet( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + _ActionAddressMixin, + _StrictQueryParametersMixin, + IterablePaginationMixin, + viewsets.ViewSet, +): + """ + Time zones commonly used in a country, or every time zone when no country is named. + + The rows come from the time-zone database rather than from a queryset, so + this is a plain ViewSet whose one query parameter is validated by a + serializer. The reference data it returns is the same for every caller and + is public on purpose. + """ + + permission_classes = (permissions.AllowAny,) + serializer_class = TimeZoneSerializer + #: Validates the query string, and names the parameters this view reads. + query_serializer_class = TimeZoneQuerySerializer + pagination_class = UserApiPagination + + def get_serializer(self, *args, **kwargs): + """Build the output serializer; a plain ViewSet has no generic machinery to do it.""" + return self.serializer_class(*args, **kwargs) + + @extend_schema( + summary="List time zones", + description=( + "Returns a page of time zones, ordered by their display form. Supply " + "`country_code` to receive the time zones commonly used in one country." + ), + # The parameters are published from the serializer that validates them, + # so the constraint a caller is held to is the one it reads. + parameters=[TimeZoneQuerySerializer], + responses={ + 200: TimeZoneSerializer, + 400: _RESP_BAD_REQUEST, + 404: _RESP_NO_SUCH_PAGE, + }, + ) + def list(self, request): + """Return a page of time zones, for one country or for the world.""" + query = self.query_serializer_class(data=request.query_params) + query.is_valid(raise_exception=True) + time_zones = get_country_time_zones(query.validated_data.get("country_code")) + return self.paginate_iterable(request, time_zones) + + +@extend_schema(exclude=True) +class UnknownAddressView(StandardizedErrorMixin, APIView): + """ + Refuses every address under this version of the API that no route serves. + + It serves no resource: it exists so that a mistyped address is answered + with the same JSON body as every other failure instead of the service's + HTML error page, which a client that asked for JSON cannot read. + """ + + permission_classes = (permissions.AllowAny,) + + def initial(self, request, *args, **kwargs): + """Refuse the address before a handler is chosen, whatever the method.""" + raise NotFound From 149e8c82a9fcf28604d7c1607d193e090a3590c0 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Thu, 15 Oct 2026 03:41:09 +0500 Subject: [PATCH 02/61] feat: publish the user API in the LMS schema The LMS drf-spectacular pre-processing hook is an allowlist and admitted only /api/enrollment/vN/, so everything under /api/user/ generated, routed and tested while being invisible in the published document. The new v2 addresses would have shipped undocumented and the schema gate would have reported the prefix missing with no clue as to why. The filter now admits exactly what this change owns: the v2 addresses, matched by their view package rather than by path prefix, plus the seven legacy paths they supersede, so each superseded address appears beside its replacement. It is deliberately not a /api/user/vN/ prefix. Admitting the whole prefix pulled thirty-eight further v1 operations into the document -- undocumented request bodies and internal docstrings published as client-facing text -- none of which this change owns or documents. SCHEMA_PATH_PREFIX becomes a two-branch pattern, stripped only to derive tags and operationIds. Every existing enrollment operationId was compared before and after and is unchanged, and so is every operationId, path and component of the service-wide /api-docs document: a generated client derives a module per operationId and a model per component, so a rename there deletes a module as surely as a removal does. The title follows the contents, and the three comments that named the old title follow it. Deprecation is marked where it belongs, outside the frozen modules: the existing post-processing hook gains a tuple of the seven exact legacy paths this change supersedes. Exact paths, not a prefix, so an address whose replacement nobody has written yet can never be marked -- the hook test includes neighbouring user addresses, the unversioned twins and another area's paths and asserts they are left alone. POSTPROCESSING_HOOKS is unchanged: setting it replaces drf-spectacular's defaults, so the enum hook stays restated and stays first. --- lms/envs/common.py | 11 +- lms/envs/devstack.py | 2 +- lms/envs/production.py | 2 +- lms/lib/spectacular.py | 84 +++++++++++-- lms/lib/tests/test_spectacular.py | 193 ++++++++++++++++++++++++++++-- openedx/core/apidocs.py | 2 +- 6 files changed, 264 insertions(+), 30 deletions(-) diff --git a/lms/envs/common.py b/lms/envs/common.py index 7ce78ae83ae0..6f27f270965f 100644 --- a/lms/envs/common.py +++ b/lms/envs/common.py @@ -2179,15 +2179,14 @@ add_optional_apps(OPTIONAL_APPS, INSTALLED_APPS) # noqa: F405 -###################### drf-spectacular (LMS enrollment schema) ###################### +###################### drf-spectacular (LMS API schema) ###################### SPECTACULAR_SETTINGS = { - 'TITLE': 'LMS Enrollment API', + 'TITLE': 'LMS API', 'VERSION': '0.1.0', 'SERVE_INCLUDE_SCHEMA': False, 'PREPROCESSING_HOOKS': ['lms.lib.spectacular.lms_api_filter'], - # Mark legacy slashless enrollment addresses deprecated. The enum hook is - # drf-spectacular's default, restated because setting this key replaces - # the default list. + # Mark superseded addresses deprecated. The enum hook is drf-spectacular's + # default, restated because setting this key replaces the default list. 'POSTPROCESSING_HOOKS': [ 'drf_spectacular.hooks.postprocess_schema_enums', 'lms.lib.spectacular.lms_mark_legacy_paths_deprecated', @@ -2195,7 +2194,7 @@ ], # Stripped from each path to derive its tags and operationId, so changing # it renames every operationId. Paths themselves are emitted in full. - 'SCHEMA_PATH_PREFIX': '/api/enrollment', + 'SCHEMA_PATH_PREFIX': r'/api/(enrollment|user)', # Serve the Swagger UI and ReDoc assets from drf-spectacular-sidecar rather # than drf-spectacular's default unpinned jsdelivr CDN URLs, keeping them # self-hosted and version-pinned as the drf-yasg bundles were. diff --git a/lms/envs/devstack.py b/lms/envs/devstack.py index 789945a32c40..e74a18aaf8ce 100644 --- a/lms/envs/devstack.py +++ b/lms/envs/devstack.py @@ -583,7 +583,7 @@ def should_show_debug_toolbar(request): # pylint: disable=missing-function-docs 'COMPLETE', ] -###################### drf-spectacular (LMS enrollment schema) ###################### +###################### drf-spectacular (LMS API schema) ###################### SPECTACULAR_SETTINGS['SERVERS'] = [ # noqa: F405 {'url': LMS_ROOT_URL, 'description': 'Local'}, # noqa: F405 ] diff --git a/lms/envs/production.py b/lms/envs/production.py index 24350824c391..1defebe32992 100644 --- a/lms/envs/production.py +++ b/lms/envs/production.py @@ -398,7 +398,7 @@ def get_env_setting(setting): MIDDLEWARE.extend(_YAML_TOKENS.get('EXTRA_MIDDLEWARE_CLASSES', [])) # noqa: F405 -###################### drf-spectacular (LMS enrollment schema) ###################### +###################### drf-spectacular (LMS API schema) ###################### SPECTACULAR_SETTINGS['SERVERS'] = [ # noqa: F405 {'url': LMS_ROOT_URL, 'description': 'Local'}, # noqa: F405 ] diff --git a/lms/lib/spectacular.py b/lms/lib/spectacular.py index 942199deac69..cfd310de404a 100644 --- a/lms/lib/spectacular.py +++ b/lms/lib/spectacular.py @@ -11,21 +11,70 @@ # addresses already have distinct ids and keep them. COLLIDING_LEGACY_PATH = "/api/enrollment/v2/enrollments" +# Addresses listed here are superseded by a conforming address this schema also +# publishes. Each entry is spelled out rather than matched by prefix, so an +# address whose replacement has not been written yet is never marked. +SUPERSEDED_USER_PATHS = ( + "/api/user/v1/users/", + "/api/user/v1/users/{id}/", + "/api/user/v1/user_prefs/", + "/api/user/v1/user_prefs/{id}/", + "/api/user/v1/preferences/{pref_key}/users/", + "/api/user/v1/forum_roles/{name}/users/", + "/api/user/v1/preferences/time_zones/", +) + +PUBLISHED_PATH_PATTERN = re.compile(r"^/api/enrollment/v\d+/") + +# The user addresses this schema documents are the ones the version below +# serves, and beside each of those the address it supersedes. Apps older than +# that version are mounted under the same ``/api/user/v2/`` prefix, so matching +# the prefix alone would publish endpoints described nowhere here; the package +# a view comes from decides instead. +PUBLISHED_USER_PREFIX = "/api/user/v2/" +PUBLISHED_USER_VIEW_MODULE = "openedx.core.djangoapps.user_api.v2." + +# Every user address, whatever its version, belongs to one tag group. A tag is +# the first path segment left once the configured prefix is removed, which in a +# document that trims ``/api/user`` is the version, so user operations would be +# grouped with the enrollment operations that carry the same version. A document +# that trims nothing already derives a tag naming an area, and regrouping its +# operations would move them in every client generated from it. +USER_PATH_PREFIX = "/api/user/" +USER_TAG = "user" + +_PATH_PARAMETER = re.compile(r"\{([\w-]+)\}") +_VERSION_TAG = re.compile(r"v\d+") + +# The superseded addresses with their parameter names removed. The generator +# renames a ``{pk}`` parameter to ``{id}`` only after this filter has run, so +# the comparison cannot depend on how a parameter is spelled. +_SUPERSEDED_USER_SHAPES = frozenset(_PATH_PARAMETER.sub("{}", path) for path in SUPERSEDED_USER_PATHS) + def _is_legacy_path(path): """Conforming routes always end in a slash, so a slashless v2 path is a legacy address.""" return path.startswith(LEGACY_V2_PREFIX) and not path.endswith("/") +def _is_published_user_path(path, callback): + """A user address is documented when this version serves it, or when this version replaces it.""" + if _PATH_PARAMETER.sub("{}", path) in _SUPERSEDED_USER_SHAPES: + return True + if not path.startswith(PUBLISHED_USER_PREFIX): + return False + view = getattr(callback, "cls", None) + return getattr(view, "__module__", "").startswith(PUBLISHED_USER_VIEW_MODULE) + + def lms_api_filter(endpoints): """ - Pre-processing hook: keep only enrollment v2 endpoints tagged for the SDK. + Pre-processing hook: keep only the endpoints this schema documents. """ filtered = [] - ENROLLMENT_PATH_PATTERN = re.compile(r"^/api/enrollment/v\d+/") for path, path_regex, method, callback in endpoints: - if ENROLLMENT_PATH_PATTERN.match(path): + if PUBLISHED_PATH_PATTERN.match(path) or _is_published_user_path(path, callback): filtered.append((path, path_regex, method, callback)) return filtered @@ -33,26 +82,37 @@ def lms_api_filter(endpoints): class LmsAutoSchema(AutoSchema): """ - Give the colliding legacy Enrollment v2 address a distinct operationId. - - It and its conforming twin tokenize to the same operationId, so - drf-spectacular would otherwise break the tie with a numeral suffix in - registration order. The conforming address keeps the clean id; the - deprecated one is suffixed ``_legacy``. + Keep the one colliding address distinct, and group each operation under its own area. + + The slashless Enrollment v2 address tokenizes to the id of its conforming + twin, so the two would be told apart only by a numeral suffix handed out + in registration order, which says nothing about the operation and moves + when the routes move; it is suffixed ``_legacy`` instead, leaving the + conforming address the clean id. Every other address keeps the id and the + tag the generator derives for it, because a client generated from a + document takes a module from each operationId and groups it by tag, so + renaming either drops what a consumer already imports. """ def get_operation_id(self): - """Suffix the colliding legacy address so the pair never shares an operationId.""" + """Suffix the one colliding address so the pair never shares an operationId.""" operation_id = super().get_operation_id() if self.path == COLLIDING_LEGACY_PATH: return f"{operation_id}_legacy" return operation_id + def get_tags(self): + """Name the area whenever the tag derived for a user address would name a version.""" + tags = super().get_tags() + if self.path.startswith(USER_PATH_PREFIX) and tags and _VERSION_TAG.fullmatch(tags[0]): + return [USER_TAG] + return tags + def lms_mark_legacy_paths_deprecated(result, generator, request, public): # pylint: disable=unused-argument - """Mark the legacy slashless Enrollment v2 addresses ``deprecated: true``.""" + """Mark every superseded address ``deprecated: true``.""" for path, path_item in result.get("paths", {}).items(): - if not _is_legacy_path(path): + if not (_is_legacy_path(path) or path in SUPERSEDED_USER_PATHS): continue for operation in path_item.values(): if isinstance(operation, dict): diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index b611c8ad7776..66c193901f33 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -1,20 +1,33 @@ """Tests for the LMS drf-spectacular hooks and schema class.""" +import re +from collections import defaultdict +from types import SimpleNamespace from unittest import mock -from django.test import SimpleTestCase +from django.test import SimpleTestCase, TestCase from django.urls import path from drf_spectacular.generators import SchemaGenerator -from drf_spectacular.settings import spectacular_settings +from drf_spectacular.settings import patched_settings, spectacular_settings from rest_framework import serializers, viewsets +from rest_framework.permissions import AllowAny from rest_framework.response import Response from rest_framework.settings import api_settings from lms.lib.spectacular import LmsAutoSchema, lms_api_filter, lms_mark_legacy_paths_deprecated +from openedx.core.apidocs import get_api_docs_settings +ENROLLMENT_VIEWS = "openedx.core.djangoapps.enrollments.views" +USER_API_V1_VIEWS = "openedx.core.djangoapps.user_api.views" +USER_API_V2_VIEWS = "openedx.core.djangoapps.user_api.v2.views" +USER_AUTHN_VIEWS = "openedx.core.djangoapps.user_authn.views.register" +COURSE_VIEWS = "lms.djangoapps.course_api.views" -def _endpoint(route): - return (route, route, "GET", None) + +def _endpoint(route, view_module=COURSE_VIEWS): + """An endpoint tuple as the generator hands it to the hook, served from ``view_module``.""" + callback = SimpleNamespace(cls=type("_View", (), {"__module__": view_module})) + return (route, route, "GET", callback) def _schema(*routes): @@ -22,19 +35,45 @@ def _schema(*routes): class LmsApiFilterTest(SimpleTestCase): - """The pre-processing hook keeps only enrollment endpoints.""" + """The hook keeps the enrollment mounts, this version of the user mounts, and what they supersede.""" - def test_keeps_enrollment_drops_the_rest(self): + def test_keeps_enrollment_this_version_and_the_addresses_it_supersedes(self): kept = lms_api_filter([ - _endpoint("/api/enrollment/v2/enrollments/"), - _endpoint("/api/enrollment/v1/enrollment"), - _endpoint("/api/user/v1/accounts/"), + _endpoint("/api/enrollment/v2/enrollments/", ENROLLMENT_VIEWS), + _endpoint("/api/enrollment/v1/enrollment", ENROLLMENT_VIEWS), + _endpoint("/api/user/v2/users/", USER_API_V2_VIEWS), + _endpoint("/api/user/v2/user_preferences/{username},{key}/", USER_API_V2_VIEWS), + # Superseded, and spelled with the parameter name the generator has + # not renamed to ``{id}`` yet. + _endpoint("/api/user/v1/users/{pk}/", USER_API_V1_VIEWS), + _endpoint("/api/user/v1/preferences/time_zones/", USER_API_V1_VIEWS), + # Neither served nor superseded by this version. + _endpoint("/api/user/v2/account/registration/", USER_AUTHN_VIEWS), + _endpoint("/api/user/v1/accounts", USER_API_V1_VIEWS), + _endpoint("/api/user/v1/me", USER_API_V1_VIEWS), + _endpoint("/api/user/v1/preferences/{username}", USER_API_V1_VIEWS), + _endpoint("/api/courses/v1/courses/", COURSE_VIEWS), + _endpoint("/api/user_tours/v1/tours/"), + _endpoint("/user_api/v1/users/", USER_API_V1_VIEWS), ]) assert [path for path, *_ in kept] == [ "/api/enrollment/v2/enrollments/", "/api/enrollment/v1/enrollment", + "/api/user/v2/users/", + "/api/user/v2/user_preferences/{username},{key}/", + "/api/user/v1/users/{pk}/", + "/api/user/v1/preferences/time_zones/", ] + def test_under_the_version_prefix_the_view_package_decides(self): + """Other apps are mounted under the same prefix, so the path alone cannot admit an address.""" + route = "/api/user/v2/account/registration/" + admitted = { + view_module: [path for path, *_ in lms_api_filter([_endpoint(route, view_module)])] + for view_module in (USER_AUTHN_VIEWS, USER_API_V2_VIEWS) + } + assert admitted == {USER_AUTHN_VIEWS: [], USER_API_V2_VIEWS: [route]} + class LmsMarkLegacyPathsDeprecatedTest(SimpleTestCase): """Slashless v2 paths are legacy and deprecated; slashed ones are conforming.""" @@ -54,6 +93,25 @@ def test_only_slashless_v2_paths_are_deprecated(self): assert "deprecated" not in paths["/api/enrollment/v2/courses/{course_key}/"]["get"] assert "deprecated" not in paths["/api/enrollment/v1/enrollment"]["get"] + def test_only_the_listed_user_addresses_are_deprecated(self): + result = lms_mark_legacy_paths_deprecated(_schema( + "/api/user/v1/users/", + "/api/user/v1/users/{id}/", + "/api/user/v1/preferences/time_zones/", + "/api/user/v1/accounts", + "/api/user/v1/preferences/{username}", + "/api/user/v2/users/", + "/user_api/v1/users/", + ), None, None, False) + paths = result["paths"] + assert paths["/api/user/v1/users/"]["get"]["deprecated"] is True + assert paths["/api/user/v1/users/{id}/"]["get"]["deprecated"] is True + assert paths["/api/user/v1/preferences/time_zones/"]["get"]["deprecated"] is True + assert "deprecated" not in paths["/api/user/v1/accounts"]["get"] + assert "deprecated" not in paths["/api/user/v1/preferences/{username}"]["get"] + assert "deprecated" not in paths["/api/user/v2/users/"]["get"] + assert "deprecated" not in paths["/user_api/v1/users/"]["get"] + def test_paths_are_left_as_full_urls(self): """Paths are not trimmed, so every key resolves against LMS_ROOT_URL.""" result = lms_mark_legacy_paths_deprecated(_schema("/api/enrollment/v2/enrollments/"), None, None, False) @@ -99,3 +157,120 @@ def test_only_the_colliding_legacy_address_is_suffixed(self): assert ids["/api/enrollment/v2/courses/{id}/"] == "v2_courses_retrieve" # Already distinct from every conforming id, so it keeps its name. assert ids["/api/enrollment/v2/enrollment/{id}"] == "v2_enrollment_retrieve" + + +class _UserApiViewSet(viewsets.GenericViewSet): + """Stand-in for a user view read both as a collection and as a member.""" + + serializer_class = _EmptySerializer + permission_classes = (AllowAny,) + + def list(self, request): + return Response([]) + + def retrieve(self, request, **kwargs): + return Response({}) + + +def _user_routes(schema_class): + """User, enrollment and non-``/api/`` addresses, inspected by ``schema_class``.""" + view = type("_InspectedViewSet", (_UserApiViewSet,), {"schema": schema_class()}) + return [ + path("api/user/v1/accounts", view.as_view({"get": "retrieve"})), + path("api/user/v1/accounts/", view.as_view({"get": "retrieve"})), + path("api/user/v1/preferences/", view.as_view({"get": "retrieve"})), + path( + "api/user/v1/preferences//", + view.as_view({"get": "retrieve"}), + ), + path("api/user/v1/users/", view.as_view({"get": "list"})), + path("api/user/v2/users/", view.as_view({"get": "list"})), + path("api/enrollment/v1/enrollments/", view.as_view({"get": "list"})), + # Outside ``/api/``, so a document that derives its prefix from the + # routes it covers derives the one the service-wide document has. + path("user_api/v1/preferences/", view.as_view({"get": "retrieve"})), + ] + + +def _named_operations(schema_class, patches): + """The ``{address: (operationId, tags)}`` ``schema_class`` produces under ``patches``.""" + with patched_settings({"PREPROCESSING_HOOKS": [], **patches}): + schema = SchemaGenerator(patterns=_user_routes(schema_class)).get_schema(request=None, public=True) + return { + route: (operation["operationId"], tuple(operation["tags"])) + for route, path_item in schema["paths"].items() + for operation in path_item.values() + } + + +class UserOperationIdTest(SimpleTestCase): + """User addresses keep the names the generator derives; only their tag group is chosen here.""" + + def test_the_service_wide_document_keeps_every_name_the_generator_derives(self): + """Each of these is the name that document already published, and a client imports it by name.""" + assert _named_operations(LmsAutoSchema, get_api_docs_settings()) == { + "/api/user/v1/accounts": ("api_user_v1_accounts_retrieve", ("api",)), + "/api/user/v1/accounts/{username}": ("api_user_v1_accounts_retrieve_2", ("api",)), + "/api/user/v1/preferences/{username}": ("api_user_v1_preferences_retrieve", ("api",)), + "/api/user/v1/preferences/{username}/{preference_key}": + ("api_user_v1_preferences_retrieve_2", ("api",)), + "/api/user/v1/users/": ("api_user_v1_users_list", ("api",)), + "/api/user/v2/users/": ("api_user_v2_users_list", ("api",)), + "/api/enrollment/v1/enrollments/": ("api_enrollment_v1_enrollments_list", ("api",)), + "/user_api/v1/preferences/{username}": ("user_api_v1_preferences_retrieve", ("user_api",)), + } + + def test_a_user_address_is_grouped_by_area_where_the_derived_tag_would_name_a_version(self): + """In the document that trims the area off, the derived tag is the version, and ids are untouched.""" + assert _named_operations(LmsAutoSchema, {}) == { + "/api/user/v1/accounts": ("v1_accounts_retrieve", ("user",)), + "/api/user/v1/accounts/{username}": ("v1_accounts_retrieve_2", ("user",)), + "/api/user/v1/preferences/{username}": ("v1_preferences_retrieve", ("user",)), + "/api/user/v1/preferences/{username}/{preference_key}": ("v1_preferences_retrieve_2", ("user",)), + "/api/user/v1/users/": ("v1_users_list", ("user",)), + "/api/user/v2/users/": ("v2_users_list", ("user",)), + "/api/enrollment/v1/enrollments/": ("v1_enrollments_list", ("v1",)), + "/user_api/v1/preferences/{username}": ("user_api_v1_preferences_retrieve", ("user_api",)), + } + + +class PublishedDocumentTest(TestCase): + """What the service actually publishes: distinct ids, and one area per tag group.""" + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.schema = SchemaGenerator().get_schema(request=None, public=True) + + @classmethod + def operations(cls): + """Yield every (path, operation) the published document carries.""" + for route, path_item in cls.schema["paths"].items(): + for operation in path_item.values(): + if isinstance(operation, dict) and "operationId" in operation: + yield route, operation + + def test_every_operation_id_is_unique(self): + ids = [operation["operationId"] for _route, operation in self.operations()] + assert sorted(ids) == sorted(set(ids)) + + def test_only_the_one_enrollment_pair_is_told_apart_by_a_numeral_suffix(self): + """A numeral suffix is assigned in route order, so it is not a stable name.""" + suffixed = { + route: operation["operationId"] + for route, operation in self.operations() + if re.fullmatch(r".+_\d+", operation["operationId"]) + } + # Renaming this one would change an id the document already published, so it stays. + assert suffixed == {"/api/enrollment/v1/enrollment/{course_id}": "v1_enrollment_retrieve_2"} + + def test_no_tag_group_holds_two_areas(self): + areas = defaultdict(set) + for route, operation in self.operations(): + for tag in operation.get("tags", []): + areas[tag].add(route.split("/")[2]) + assert {tag: sorted(members) for tag, members in areas.items()} == { + "v1": ["enrollment"], + "openedx-platform-sdk": ["enrollment"], + "user": ["user"], + } diff --git a/openedx/core/apidocs.py b/openedx/core/apidocs.py index 838c61b6bb56..05f8f59888f0 100644 --- a/openedx/core/apidocs.py +++ b/openedx/core/apidocs.py @@ -21,7 +21,7 @@ # These are passed as ``custom_settings`` to SpectacularAPIView rather than # living in ``SPECTACULAR_SETTINGS``, because that global is already claimed by # a deliberately narrow schema in each service -- the Authoring API -# (``/authoring-api/``) in CMS and the Enrollment API (``/lms-api/``) in LMS. +# (``/authoring-api/``) in CMS and the LMS API (``/lms-api/``) in LMS. # Both filter the surface down via ``PREPROCESSING_HOOKS`` and trim a path # prefix, so ``/api-docs`` must switch that filtering off explicitly to cover # the whole service. From e487de76c21e1f44823abe9f805019c0e897abc8 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Fri, 23 Oct 2026 11:37:22 +0500 Subject: [PATCH 03/61] feat: standardize the account, name-change, verification and profile image APIs as /api/user/v2/ The account surface was the largest non-conforming part of the User API and the one most callers depend on: frontend-platform's account fetch, the account and profile MFEs, and both mobile apps all read it. Ten of its operations answered in shapes nothing documented, refused malformed input with server faults, and addressed one account's records through a permission that read a username from somewhere other than the address. Every change here is a contract change, so they land on a new version: /api/user/v1/ is untouched and keeps serving every one of its callers. What this version answers: GET /api/user/v2/accounts/ (?username=, ?email=, ?lms_user_id=, ?view=, ?fields=, ?ordering=) GET /api/user/v2/accounts/me/ GET /api/user/v2/accounts/{username}/ PATCH /api/user/v2/accounts/{username}/ POST /api/user/v2/accounts/{username}/deactivation/ POST /api/user/v2/email_searches/ POST /api/user/v2/name_changes/ POST /api/user/v2/name_changes/{username}/confirmations/ GET /api/user/v2/accounts/{username}/verification_status/ GET /api/user/v2/accounts/{username}/verifications/ POST /api/user/v2/accounts/{username}/profile_image/ DELETE /api/user/v2/accounts/{username}/profile_image/ A refusal is part of the contract, so the refusals are explicit. The request body is measured against a serializer before the account service reads it, so a wrongly typed property is a validation envelope rather than a server fault; a failure inside the service is a server fault rather than a validation envelope. A permission reads the username from the address and from nowhere else, and compares it exactly, because the handler behind it selects the record by that same value. An account that is no longer active is refused on both halves of the default authentication pair rather than only one. Lists answer in the standard envelope, bounded and ordered by username; a filter that matches nothing answers an empty page rather than reporting the address as missing, and a status that has never been established answers "none" rather than reporting the account as missing. An email search is bounded at a hundred addresses, which bounds its answer. The schema describes what the code does: the superseded addresses publish the media types they actually read, every operation publishes the codes it really answers, and the response components carry the properties the bodies really hold, with presets modelled rather than implied. The tests pin behaviour rather than structure. Every allowed and every refused caller is named with the error type asserted; value-level parity is checked against each superseded address; query counts are measured on the earlier endpoint first and asserted not to grow with the collection; SQL captures prove no read writes, including writes deferred to commit; and each guard was checked by breaking what it covers and watching the right tests fail. The profile-image endpoints are addressed under the User API but served by a view that belongs to the profile_images app, so the conforming version lives in that app's own new version package and is mounted into the user version two URLconf exactly as the earlier view is imported today. The app's existing modules are untouched, and the image validation they own is called rather than copied. An upload is read before anything is stored, so a truncated file, metadata that cannot be parsed, or a header declaring more pixels than the site will ever draw are answered as the caller's error rather than as a server fault, while a failure to store a well-formed image stays a server fault. The media types the address reads are published, and the body is published as required. A caller may set and clear the image on the account the address names and on no other, staff included, since clearing an image is a change to an account rather than a moderation tool. The permission reads the username from the address and compares it exactly, because that is the value the stored names are built from, so the account a caller is admitted for is always the account written to. The tests drive real uploads: each refusal with its error type, parity against the earlier address for the bodies both answer, and a check that a caller holding another spelling of the owner's name is refused and stores nothing. --- lms/lib/spectacular.py | 164 +- lms/lib/tests/test_spectacular.py | 181 +- .../djangoapps/profile_images/v2/__init__.py | 1 + .../profile_images/v2/serializers.py | 43 + .../profile_images/v2/tests/__init__.py | 1 + .../profile_images/v2/tests/test_views.py | 905 ++++++ .../djangoapps/profile_images/v2/views.py | 255 ++ openedx/core/djangoapps/user_api/v2/errors.py | 68 +- .../djangoapps/user_api/v2/permissions.py | 71 +- .../core/djangoapps/user_api/v2/selectors.py | 70 + .../djangoapps/user_api/v2/serializers.py | 582 ++++ .../user_api/v2/tests/test_account_parity.py | 574 ++++ .../v2/tests/test_account_query_counts.py | 410 +++ .../user_api/v2/tests/test_account_views.py | 2579 +++++++++++++++++ .../v2/tests/test_name_change_views.py | 567 ++++ .../user_api/v2/tests/test_schema.py | 1267 +++++++- .../user_api/v2/tests/test_selectors.py | 106 + .../djangoapps/user_api/v2/tests/test_urls.py | 271 +- .../v2/tests/test_verification_views.py | 1047 +++++++ openedx/core/djangoapps/user_api/v2/urls.py | 64 +- .../core/djangoapps/user_api/v2/view_utils.py | 73 + openedx/core/djangoapps/user_api/v2/views.py | 1105 ++++++- 22 files changed, 10264 insertions(+), 140 deletions(-) create mode 100644 openedx/core/djangoapps/profile_images/v2/__init__.py create mode 100644 openedx/core/djangoapps/profile_images/v2/serializers.py create mode 100644 openedx/core/djangoapps/profile_images/v2/tests/__init__.py create mode 100644 openedx/core/djangoapps/profile_images/v2/tests/test_views.py create mode 100644 openedx/core/djangoapps/profile_images/v2/views.py create mode 100644 openedx/core/djangoapps/user_api/v2/selectors.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_account_query_counts.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_account_views.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_selectors.py create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py create mode 100644 openedx/core/djangoapps/user_api/v2/view_utils.py diff --git a/lms/lib/spectacular.py b/lms/lib/spectacular.py index cfd310de404a..4ac182ea1bb7 100644 --- a/lms/lib/spectacular.py +++ b/lms/lib/spectacular.py @@ -1,8 +1,11 @@ """Helper functions for drf-spectacular (LMS schema).""" import re +from collections import namedtuple +from functools import cache from drf_spectacular.openapi import AutoSchema +from drf_spectacular.utils import OpenApiResponse LEGACY_V2_PREFIX = "/api/enrollment/v2/" @@ -15,6 +18,16 @@ # publishes. Each entry is spelled out rather than matched by prefix, so an # address whose replacement has not been written yet is never marked. SUPERSEDED_USER_PATHS = ( + "/api/user/v1/me", + "/api/user/v1/accounts", + "/api/user/v1/accounts/search_emails", + "/api/user/v1/accounts/{username}", + "/api/user/v1/accounts/{username}/deactivate/", + "/api/user/v1/accounts/{username}/image", + "/api/user/v1/accounts/{username}/verification_status/", + "/api/user/v1/accounts/{username}/verifications/", + "/api/user/v1/accounts/name_change/", + "/api/user/v1/accounts/name_change/{username}/confirm/", "/api/user/v1/users/", "/api/user/v1/users/{id}/", "/api/user/v1/user_prefs/", @@ -24,15 +37,33 @@ "/api/user/v1/preferences/time_zones/", ) +# A path parameter leaves no token behind, and the version 1 account collection +# has no trailing slash to tell it from the member address, so the two tokenize +# to one operation id and are told apart only by a numeral handed out in +# registration order. The collection answers with a list of accounts, which the +# generator names for a list, while the document that trims nothing off the +# front of each path has always published that address under the name derived +# for a single account -- the name that leaves the member address the numeral it +# carries there -- so that one is pinned. The key carries the id the generator +# derives, so an entry applies only to the document that derives it; a key no +# document derives would never be reached. +RENAMED_OPERATION_IDS = { + ("/api/user/v1/accounts", "GET", "api_user_v1_accounts_list"): "api_user_v1_accounts_retrieve", +} + PUBLISHED_PATH_PATTERN = re.compile(r"^/api/enrollment/v\d+/") # The user addresses this schema documents are the ones the version below # serves, and beside each of those the address it supersedes. Apps older than # that version are mounted under the same ``/api/user/v2/`` prefix, so matching -# the prefix alone would publish endpoints described nowhere here; the package -# a view comes from decides instead. +# the prefix alone would publish endpoints described nowhere here; the packages +# a view may come from decide instead. One resource of this version lives in +# the app that owns it rather than in the user API's own package. PUBLISHED_USER_PREFIX = "/api/user/v2/" -PUBLISHED_USER_VIEW_MODULE = "openedx.core.djangoapps.user_api.v2." +PUBLISHED_USER_VIEW_MODULES = ( + "openedx.core.djangoapps.user_api.v2.", + "openedx.core.djangoapps.profile_images.v2.", +) # Every user address, whatever its version, belongs to one tag group. A tag is # the first path segment left once the configured prefix is removed, which in a @@ -52,6 +83,83 @@ _SUPERSEDED_USER_SHAPES = frozenset(_PATH_PARAMETER.sub("{}", path) for path in SUPERSEDED_USER_PATHS) +#: What one superseded operation reads and what it answers with on success. +_SupersededBodies = namedtuple("_SupersededBodies", ("request", "response")) + + +@cache +def superseded_bodies(): + """ + Return the bodies of each superseded operation, keyed by address and method. + + The views serving those addresses name no serializer, so an address + published beside the one that replaces it would carry nothing on either + side of the exchange. Each entry below names the shape the handler reads or + returns with the serializer describing that same shape at the replacing + address, which the parity tests of this area hold to the same values; a + request of ``None`` is an operation that reads no body. An address whose + view names a serializer of its own is absent from the table and keeps the + component it has always published. + + A request is keyed by media type, because a shape named on its own is + published under every type the view's parsers accept: where that is more + types than the handler reads, a client generated from the document would + pick one it refuses, and where the handler reads a body no serializer + describes, such as an image sent as the whole body, the document would + leave that form out. An address whose body is also read at the address + replacing it takes the same mapping from there, so the two cannot drift. + """ + # The serializers read models, which are not loaded when this module is + # first imported. + # pylint: disable=import-outside-toplevel + from openedx.core.djangoapps.profile_images.v2.serializers import IMAGE_UPLOAD_REQUEST + from openedx.core.djangoapps.user_api.v2.serializers import ( + AccountSerializer, + AccountUpdateSerializer, + EmailSearchResultSerializer, + EmailSearchSerializer, + NameChangeSerializer, + VerificationStatusSerializer, + ) + from openedx.core.lib.api.parsers import MergePatchParser + + account = {200: AccountSerializer} + described = { + ("/api/user/v1/accounts", "GET"): _SupersededBodies(None, {200: AccountSerializer(many=True)}), + ("/api/user/v1/accounts/{username}", "GET"): _SupersededBodies(None, account), + ("/api/user/v1/accounts/{username}", "PATCH"): _SupersededBodies( + {MergePatchParser.media_type: AccountUpdateSerializer}, account, + ), + ("/api/user/v1/accounts/search_emails", "POST"): _SupersededBodies( + EmailSearchSerializer, {200: EmailSearchResultSerializer(many=True)}, + ), + ("/api/user/v1/accounts/{username}/deactivate/", "POST"): _SupersededBodies(None, account), + ("/api/user/v1/accounts/name_change/", "POST"): _SupersededBodies( + NameChangeSerializer, + {201: OpenApiResponse(description="The change was recorded and waits to be confirmed.")}, + ), + ("/api/user/v1/accounts/name_change/{username}/confirm/", "POST"): _SupersededBodies( + None, {204: OpenApiResponse(description="The profile carries the name that was asked for.")}, + ), + ("/api/user/v1/accounts/{username}/image", "POST"): _SupersededBodies( + IMAGE_UPLOAD_REQUEST, + {204: OpenApiResponse(description="The account now carries this image.")}, + ), + ("/api/user/v1/accounts/{username}/image", "DELETE"): _SupersededBodies( + None, {204: OpenApiResponse(description="The account carries no image of its own.")}, + ), + ("/api/user/v1/accounts/{username}/verification_status/", "GET"): _SupersededBodies( + None, {200: VerificationStatusSerializer}, + ), + } + # Parameter names are spelled differently at different points of + # generation, so an address is keyed by its shape alone. + return { + (_PATH_PARAMETER.sub("{}", path), method): bodies + for (path, method), bodies in described.items() + } + + def _is_legacy_path(path): """Conforming routes always end in a slash, so a slashless v2 path is a legacy address.""" return path.startswith(LEGACY_V2_PREFIX) and not path.endswith("/") @@ -64,7 +172,7 @@ def _is_published_user_path(path, callback): if not path.startswith(PUBLISHED_USER_PREFIX): return False view = getattr(callback, "cls", None) - return getattr(view, "__module__", "").startswith(PUBLISHED_USER_VIEW_MODULE) + return getattr(view, "__module__", "").startswith(PUBLISHED_USER_VIEW_MODULES) def lms_api_filter(endpoints): @@ -82,21 +190,27 @@ def lms_api_filter(endpoints): class LmsAutoSchema(AutoSchema): """ - Keep the one colliding address distinct, and group each operation under its own area. + Keep colliding addresses distinct, group each operation under its own area, + and name the bodies of the addresses this schema publishes as superseded, + marking a body the operation cannot be called without as one it needs. The slashless Enrollment v2 address tokenizes to the id of its conforming twin, so the two would be told apart only by a numeral suffix handed out in registration order, which says nothing about the operation and moves when the routes move; it is suffixed ``_legacy`` instead, leaving the - conforming address the clean id. Every other address keeps the id and the - tag the generator derives for it, because a client generated from a + conforming address the clean id, and the address listed above keeps the + name it is already published under. Every other address keeps the id and + the tag the generator derives for it, because a client generated from a document takes a module from each operationId and groups it by tag, so renaming either drops what a consumer already imports. """ def get_operation_id(self): - """Suffix the one colliding address so the pair never shares an operationId.""" + """Keep each address that tokenizes to another one's id distinct from it.""" operation_id = super().get_operation_id() + renamed = RENAMED_OPERATION_IDS.get((self.path, self.method, operation_id)) + if renamed is not None: + return renamed if self.path == COLLIDING_LEGACY_PATH: return f"{operation_id}_legacy" return operation_id @@ -108,6 +222,40 @@ def get_tags(self): return [USER_TAG] return tags + def _get_request_body(self, direction="request"): + """ + Publish a body as one the operation needs when any form it may be sent in is. + + An operation that names the media types it reads loses that mark as + soon as one of them is the bare body of a file, which carries no field + that can be called required. The forms are alternatives rather than + parts of one request, so a body that is required in any of them is a + body the operation cannot be called without. + """ + body = super()._get_request_body(direction) + if not body: + return body + shapes = self.get_request_serializer() + if body.get("required") or not isinstance(shapes, dict): + return body + if any(self._get_request_for_media_type(shape, direction)[1] for shape in shapes.values()): + body["required"] = True + return body + + def get_request_serializer(self): + """Return the body this operation reads, named here for the addresses this one supersedes.""" + bodies = self._superseded_bodies() + return super().get_request_serializer() if bodies is None else bodies.request + + def get_response_serializers(self): + """Return the body this operation answers with, named here for the addresses this one supersedes.""" + bodies = self._superseded_bodies() + return super().get_response_serializers() if bodies is None else bodies.response + + def _superseded_bodies(self): + """Return the bodies named for this operation, or ``None`` where none are named.""" + return superseded_bodies().get((_PATH_PARAMETER.sub("{}", self.path), self.method)) + def lms_mark_legacy_paths_deprecated(result, generator, request, public): # pylint: disable=unused-argument """Mark every superseded address ``deprecated: true``.""" diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index 66c193901f33..90d7f9a2a382 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -14,12 +14,21 @@ from rest_framework.response import Response from rest_framework.settings import api_settings -from lms.lib.spectacular import LmsAutoSchema, lms_api_filter, lms_mark_legacy_paths_deprecated +from lms.lib.spectacular import ( + RENAMED_OPERATION_IDS, + SUPERSEDED_USER_PATHS, + LmsAutoSchema, + lms_api_filter, + lms_mark_legacy_paths_deprecated, + superseded_bodies, +) from openedx.core.apidocs import get_api_docs_settings ENROLLMENT_VIEWS = "openedx.core.djangoapps.enrollments.views" USER_API_V1_VIEWS = "openedx.core.djangoapps.user_api.views" USER_API_V2_VIEWS = "openedx.core.djangoapps.user_api.v2.views" +PROFILE_IMAGE_V1_VIEWS = "openedx.core.djangoapps.profile_images.views" +PROFILE_IMAGE_V2_VIEWS = "openedx.core.djangoapps.profile_images.v2.views" USER_AUTHN_VIEWS = "openedx.core.djangoapps.user_authn.views.register" COURSE_VIEWS = "lms.djangoapps.course_api.views" @@ -47,10 +56,16 @@ def test_keeps_enrollment_this_version_and_the_addresses_it_supersedes(self): # not renamed to ``{id}`` yet. _endpoint("/api/user/v1/users/{pk}/", USER_API_V1_VIEWS), _endpoint("/api/user/v1/preferences/time_zones/", USER_API_V1_VIEWS), - # Neither served nor superseded by this version. - _endpoint("/api/user/v2/account/registration/", USER_AUTHN_VIEWS), _endpoint("/api/user/v1/accounts", USER_API_V1_VIEWS), + _endpoint("/api/user/v1/accounts/{username}", USER_API_V1_VIEWS), _endpoint("/api/user/v1/me", USER_API_V1_VIEWS), + _endpoint("/api/user/v1/accounts/{username}/image", USER_API_V1_VIEWS), + _endpoint("/api/user/v1/accounts/name_change/", USER_API_V1_VIEWS), + # Served by this version from the app that owns the resource. + _endpoint("/api/user/v2/accounts/{username}/profile_image/", PROFILE_IMAGE_V2_VIEWS), + # Neither served nor superseded by this version. + _endpoint("/api/user/v2/account/registration/", USER_AUTHN_VIEWS), + _endpoint("/api/profile_images/v1/{username}/upload", PROFILE_IMAGE_V1_VIEWS), _endpoint("/api/user/v1/preferences/{username}", USER_API_V1_VIEWS), _endpoint("/api/courses/v1/courses/", COURSE_VIEWS), _endpoint("/api/user_tours/v1/tours/"), @@ -63,6 +78,12 @@ def test_keeps_enrollment_this_version_and_the_addresses_it_supersedes(self): "/api/user/v2/user_preferences/{username},{key}/", "/api/user/v1/users/{pk}/", "/api/user/v1/preferences/time_zones/", + "/api/user/v1/accounts", + "/api/user/v1/accounts/{username}", + "/api/user/v1/me", + "/api/user/v1/accounts/{username}/image", + "/api/user/v1/accounts/name_change/", + "/api/user/v2/accounts/{username}/profile_image/", ] def test_under_the_version_prefix_the_view_package_decides(self): @@ -99,18 +120,46 @@ def test_only_the_listed_user_addresses_are_deprecated(self): "/api/user/v1/users/{id}/", "/api/user/v1/preferences/time_zones/", "/api/user/v1/accounts", + "/api/user/v1/accounts/{username}", + "/api/user/v1/accounts/{username}/deactivate/", + "/api/user/v1/me", + "/api/user/v1/accounts/{username}/image", + "/api/user/v1/accounts/name_change/", + "/api/user/v1/accounts/name_change/{username}/confirm/", + "/api/user/v1/accounts/{username}/verification_status/", + "/api/user/v1/accounts/{username}/verifications/", "/api/user/v1/preferences/{username}", + "/api/profile_images/v1/{username}/upload", "/api/user/v2/users/", + "/api/user/v2/accounts/{username}/profile_image/", "/user_api/v1/users/", + "/user_api/v1/accounts/{username}", ), None, None, False) paths = result["paths"] - assert paths["/api/user/v1/users/"]["get"]["deprecated"] is True - assert paths["/api/user/v1/users/{id}/"]["get"]["deprecated"] is True - assert paths["/api/user/v1/preferences/time_zones/"]["get"]["deprecated"] is True - assert "deprecated" not in paths["/api/user/v1/accounts"]["get"] - assert "deprecated" not in paths["/api/user/v1/preferences/{username}"]["get"] - assert "deprecated" not in paths["/api/user/v2/users/"]["get"] - assert "deprecated" not in paths["/user_api/v1/users/"]["get"] + for marked in ( + "/api/user/v1/users/", + "/api/user/v1/users/{id}/", + "/api/user/v1/preferences/time_zones/", + "/api/user/v1/accounts", + "/api/user/v1/accounts/{username}", + "/api/user/v1/accounts/{username}/deactivate/", + "/api/user/v1/me", + "/api/user/v1/accounts/{username}/image", + "/api/user/v1/accounts/name_change/", + "/api/user/v1/accounts/name_change/{username}/confirm/", + "/api/user/v1/accounts/{username}/verification_status/", + "/api/user/v1/accounts/{username}/verifications/", + ): + assert paths[marked]["get"]["deprecated"] is True, marked + for untouched in ( + "/api/user/v1/preferences/{username}", + "/api/profile_images/v1/{username}/upload", + "/api/user/v2/users/", + "/api/user/v2/accounts/{username}/profile_image/", + "/user_api/v1/users/", + "/user_api/v1/accounts/{username}", + ): + assert "deprecated" not in paths[untouched]["get"], untouched def test_paths_are_left_as_full_urls(self): """Paths are not trimmed, so every key resolves against LMS_ROOT_URL.""" @@ -176,7 +225,9 @@ def _user_routes(schema_class): """User, enrollment and non-``/api/`` addresses, inspected by ``schema_class``.""" view = type("_InspectedViewSet", (_UserApiViewSet,), {"schema": schema_class()}) return [ - path("api/user/v1/accounts", view.as_view({"get": "retrieve"})), + # The published collection answers with a list of accounts, which is + # what the generator derives a list operation id from. + path("api/user/v1/accounts", view.as_view({"get": "list"})), path("api/user/v1/accounts/", view.as_view({"get": "retrieve"})), path("api/user/v1/preferences/", view.as_view({"get": "retrieve"})), path( @@ -192,6 +243,12 @@ def _user_routes(schema_class): ] +def _derived_operations(schema_class, patches): + """The names ``schema_class`` produces with nothing pinned, which is what the generator derives.""" + with mock.patch.dict("lms.lib.spectacular.RENAMED_OPERATION_IDS", {}, clear=True): + return _named_operations(schema_class, patches) + + def _named_operations(schema_class, patches): """The ``{address: (operationId, tags)}`` ``schema_class`` produces under ``patches``.""" with patched_settings({"PREPROCESSING_HOOKS": [], **patches}): @@ -220,11 +277,20 @@ def test_the_service_wide_document_keeps_every_name_the_generator_derives(self): "/user_api/v1/preferences/{username}": ("user_api_v1_preferences_retrieve", ("user_api",)), } + def test_every_pinned_name_replaces_one_a_document_derives(self): + """An entry keyed on an id no document derives is never reached, and pins nothing.""" + derived = { + (address, "GET", operation_id) + for patches in ({}, get_api_docs_settings()) + for address, (operation_id, _tags) in _derived_operations(LmsAutoSchema, patches).items() + } + assert set(RENAMED_OPERATION_IDS) - derived == set() + def test_a_user_address_is_grouped_by_area_where_the_derived_tag_would_name_a_version(self): """In the document that trims the area off, the derived tag is the version, and ids are untouched.""" assert _named_operations(LmsAutoSchema, {}) == { - "/api/user/v1/accounts": ("v1_accounts_retrieve", ("user",)), - "/api/user/v1/accounts/{username}": ("v1_accounts_retrieve_2", ("user",)), + "/api/user/v1/accounts": ("v1_accounts_list", ("user",)), + "/api/user/v1/accounts/{username}": ("v1_accounts_retrieve", ("user",)), "/api/user/v1/preferences/{username}": ("v1_preferences_retrieve", ("user",)), "/api/user/v1/preferences/{username}/{preference_key}": ("v1_preferences_retrieve_2", ("user",)), "/api/user/v1/users/": ("v1_users_list", ("user",)), @@ -234,6 +300,85 @@ def test_a_user_address_is_grouped_by_area_where_the_derived_tag_would_name_a_ve } +#: What each superseded operation the schema describes is expected to exchange: +#: the media types of the body it reads, and the success code with the body it +#: answers with. ``None`` is a response code carrying no body at all. +SUPERSEDED_EXCHANGES = { + ("/api/user/v1/accounts", "get"): ([], {"200": "Account[]"}), + ("/api/user/v1/accounts/{username}", "get"): ([], {"200": "Account"}), + ("/api/user/v1/accounts/{username}", "patch"): (["application/merge-patch+json"], {"200": "Account"}), + ("/api/user/v1/accounts/search_emails", "post"): ( + ["application/json", "application/merge-patch+json"], {"200": "EmailSearchResult[]"}, + ), + ("/api/user/v1/accounts/{username}/deactivate/", "post"): ([], {"200": "Account"}), + ("/api/user/v1/accounts/name_change/", "post"): ( + ["application/json", "application/x-www-form-urlencoded", "multipart/form-data"], + {"201": None}, + ), + ("/api/user/v1/accounts/name_change/{username}/confirm/", "post"): ([], {"204": None}), + ("/api/user/v1/accounts/{username}/image", "post"): ( + ["image/gif", "image/jpeg", "image/pjpeg", "image/png", "multipart/form-data"], + {"204": None}, + ), + ("/api/user/v1/accounts/{username}/image", "delete"): ([], {"204": None}), + ("/api/user/v1/accounts/{username}/verification_status/", "get"): ([], {"200": "VerificationStatus"}), +} + + +def _named_body(response): + """Return the component a response carries, suffixed ``[]`` for an array, or ``None``.""" + content = response.get("content") + if not content: + return None + body = content["application/json"]["schema"] + if body.get("type") == "array": + return f"{body['items']['$ref'].rsplit('/', 1)[-1]}[]" + return body["$ref"].rsplit("/", 1)[-1] + + +class SupersededBodyTest(TestCase): + """Every address published as superseded carries the bodies it exchanges.""" + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.schema = SchemaGenerator().get_schema(request=None, public=True) + + def test_the_described_addresses_are_ones_this_schema_marks_superseded(self): + described = {address for address, _method in superseded_bodies()} + marked = {re.sub(r"\{[\w-]+\}", "{}", address) for address in SUPERSEDED_USER_PATHS} + assert described <= marked, described - marked + + def test_each_superseded_operation_publishes_what_it_reads_and_what_it_answers_with(self): + published = {} + for (address, method), _expected in SUPERSEDED_EXCHANGES.items(): + operation = self.schema["paths"][address][method] + request_media_types = sorted((operation.get("requestBody") or {}).get("content", {})) + published[(address, method)] = ( + request_media_types, + {code: _named_body(response) for code, response in operation["responses"].items()}, + ) + assert published == SUPERSEDED_EXCHANGES + + def test_a_body_one_of_the_published_forms_requires_is_published_as_required(self): + """The forms an image may be sent in are alternatives, and one of them is a form part.""" + image = self.schema["paths"]["/api/user/v1/accounts/{username}/image"]["post"] + assert image["requestBody"]["required"] is True + assert sorted(image["requestBody"]["content"]) == [ + "image/gif", "image/jpeg", "image/pjpeg", "image/png", "multipart/form-data", + ] + + def test_no_superseded_operation_answers_with_a_body_it_does_not_describe(self): + """A published success body with no schema is the half-documented state this avoids.""" + undescribed = [ + (address, method, code) + for (address, method), (_request, responses) in SUPERSEDED_EXCHANGES.items() + for code, body in responses.items() + if body is None and "content" in self.schema["paths"][address][method]["responses"][code] + ] + assert undescribed == [] + + class PublishedDocumentTest(TestCase): """What the service actually publishes: distinct ids, and one area per tag group.""" @@ -264,13 +409,19 @@ def test_only_the_one_enrollment_pair_is_told_apart_by_a_numeral_suffix(self): # Renaming this one would change an id the document already published, so it stays. assert suffixed == {"/api/enrollment/v1/enrollment/{course_id}": "v1_enrollment_retrieve_2"} - def test_no_tag_group_holds_two_areas(self): + def test_a_tag_group_holds_one_area_unless_it_marks_the_client_library(self): + """ + The group a client library is generated from marks operations in any area. + + Every other group names an area, and gathering two of them under one + name would move operations in every client generated from the document. + """ areas = defaultdict(set) for route, operation in self.operations(): for tag in operation.get("tags", []): areas[tag].add(route.split("/")[2]) assert {tag: sorted(members) for tag, members in areas.items()} == { "v1": ["enrollment"], - "openedx-platform-sdk": ["enrollment"], + "openedx-platform-sdk": ["enrollment", "user"], "user": ["user"], } diff --git a/openedx/core/djangoapps/profile_images/v2/__init__.py b/openedx/core/djangoapps/profile_images/v2/__init__.py new file mode 100644 index 000000000000..1b89a5f06f07 --- /dev/null +++ b/openedx/core/djangoapps/profile_images/v2/__init__.py @@ -0,0 +1 @@ +"""Version 2 of the profile image endpoints.""" diff --git a/openedx/core/djangoapps/profile_images/v2/serializers.py b/openedx/core/djangoapps/profile_images/v2/serializers.py new file mode 100644 index 000000000000..73683e29256e --- /dev/null +++ b/openedx/core/djangoapps/profile_images/v2/serializers.py @@ -0,0 +1,43 @@ +"""Serializers for version 2 of the profile image endpoints.""" + +import itertools + +from drf_spectacular.types import OpenApiTypes +from drf_spectacular.utils import extend_schema_field +from rest_framework import serializers + +from ..images import IMAGE_TYPES + + +# A file field is published as the address a stored file is served from, +# because that is what a response carries; this body carries the file itself. +@extend_schema_field(OpenApiTypes.BINARY) +class UploadedImageField(serializers.FileField): + """A file sent as part of the request rather than named by its address.""" + + +class ProfileImageUploadSerializer(serializers.Serializer): # pylint: disable=abstract-method + """The image a user sends to be shown beside their name.""" + + file = UploadedImageField( + help_text=( + "Image to show beside the user's name. It is stored in each size the site renders, " + "cropped to a square, and must be a JPEG, PNG or GIF within the size limits this " + "site configures." + ), + ) + + +#: The media types an image sent as the whole request body may be sent in, +#: which are the ones the site stores a picture from. +UPLOAD_MEDIA_TYPES = tuple(sorted(set( + itertools.chain(*(image_type.mimetypes for image_type in IMAGE_TYPES.values())) +))) + +#: What an upload carries, by media type: the image as a named part of a form, +#: or the image alone as the whole body sent in the media type of the image. +#: Every address that takes an image reads both forms and publishes this. +IMAGE_UPLOAD_REQUEST = { + "multipart/form-data": ProfileImageUploadSerializer, + **{media_type: OpenApiTypes.BINARY for media_type in UPLOAD_MEDIA_TYPES}, +} diff --git a/openedx/core/djangoapps/profile_images/v2/tests/__init__.py b/openedx/core/djangoapps/profile_images/v2/tests/__init__.py new file mode 100644 index 000000000000..898afe25a32b --- /dev/null +++ b/openedx/core/djangoapps/profile_images/v2/tests/__init__.py @@ -0,0 +1 @@ +"""Tests for version 2 of the profile image endpoints.""" diff --git a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py new file mode 100644 index 000000000000..3973feb31f16 --- /dev/null +++ b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py @@ -0,0 +1,905 @@ +"""Tests for the version 2 profile image views.""" + +import datetime +import os +import struct +import zlib +from contextlib import closing +from io import BytesIO +from unittest import mock +from zoneinfo import ZoneInfo + +import freezegun +import pytest +from django.core.files.uploadedfile import SimpleUploadedFile +from django.urls import reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from PIL import Image +from rest_framework import status +from rest_framework.test import APITestCase + +from common.djangoapps.student.tests.factories import UserFactory +from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user +from openedx.core.djangoapps.user_api.accounts.image_helpers import ( + get_profile_image_names, + get_profile_image_storage, +) +from openedx.core.djangolib.testing.utils import skip_unless_lms + +from ...tests.helpers import make_image_file + +PASSWORD = "Password1234" + +#: Where the view records what it refused, which is where an operator reads +#: why a caller was told their image could not be used. +VIEWS_LOGGER = "openedx.core.djangoapps.profile_images.v2.views" + +#: Where the classes the platform declares record that they read a request. +DEFAULT_AUTH_RECORDER = "openedx.core.djangolib.default_auth_classes.set_custom_attribute" + +def earlier_address(username): + """Return the version 1 address of one user's image, which takes both methods.""" + return f"/api/user/v1/accounts/{username}/image" + + +class ProfileImageTestCase(APITestCase): + """Fixtures shared by the version 2 profile image tests.""" + + def setUp(self): + super().setUp() + self.owner = UserFactory.create( + username="image-owner", email="image-owner@example.com", password=PASSWORD, + ) + self.other = UserFactory.create( + username="image-other", email="image-other@example.com", password=PASSWORD, + ) + self.staff = UserFactory.create( + username="image-staff", email="image-staff@example.com", password=PASSWORD, is_staff=True, + ) + self.url = self.image_url(self.owner.username) + self.storage = get_profile_image_storage() + self.addCleanup(self.remove_stored_images, self.owner.username) + self.addCleanup(self.remove_stored_images, self.other.username) + + def remove_stored_images(self, username): + """Take whatever this user has stored out of the image store.""" + for name in get_profile_image_names(username).values(): + self.storage.delete(name) + + def image_url(self, username): + """Return the address of one user's image.""" + return reverse("user_v2:account_profile_image", kwargs={"username": username}) + + def login(self, user): + """Sign the given user in through the session these views accept.""" + assert self.client.login(username=user.username, password=PASSWORD) + + def token_headers(self, user): + """Return the request headers that carry a token identifying the given user.""" + return {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(user)}"} + + def sign_in_as_a_case_variant_of(self, user): + """ + Sign in a caller whose own name is the given user's, in upper case. + + The variant is set in memory only, since a site that stores usernames + case-insensitively has no room for both names at once. + """ + caller = UserFactory.create( + username="image-variant", email="image-variant@example.com", password=PASSWORD, + ) + caller.username = user.username.upper() + self.client.force_authenticate(user=caller) + return caller + + def upload(self, address=None, **kwargs): + """Send an image as a form field, the way a browser does.""" + with make_image_file(**kwargs) as image_file: + return self.client.post(address or self.url, {"file": image_file}, format="multipart") + + def not_an_image(self): + """Return a file the site stores nothing from, long enough to pass the size check.""" + return SimpleUploadedFile("notes.txt", b"x" * 200, content_type="text/plain") + + def unreadable_image(self): + """ + Return a file that answers every check the site makes and still holds no image. + + The name, the media type and the leading bytes are a PNG's, so the size, + extension, media-type and leading-byte checks all pass and the file is + only found to be unreadable when the site tries to draw it. + """ + return SimpleUploadedFile( + "picture.png", bytes.fromhex("89504e470d0a1a0a") + b"\x00" * 400, content_type="image/png", + ) + + def noisy_image(self, image_format="JPEG", dimensions=(320, 240), **options): + """ + Return the bytes of an image of random pixels, in the given format. + + Random pixels compress to little less than their own size, so half of + such a file is still larger than the smallest file the site takes, + which is what makes a part of one stand in for an upload that stopped + in transfer. An image of one colour shrinks to a few hundred bytes and + would be refused for its size before anything tried to draw it. + """ + image = Image.frombytes("RGB", dimensions, os.urandom(dimensions[0] * dimensions[1] * 3)) + body = BytesIO() + image.save(body, format=image_format, **options) + return body.getvalue() + + def cut_short(self, data): + """Return the leading half of the given bytes, as an upload that stopped partway.""" + return data[: len(data) // 2] + + def image_with_unreadable_metadata(self): + """Return a JPEG carrying a metadata block that is not the metadata it announces.""" + return self.noisy_image(exif=b"Exif\x00\x00" + b"\xff" * 64) + + def image_declaring_more_pixels_than_it_holds(self, dimensions=(40000, 40000)): + """ + Return a PNG of a few hundred bytes whose header declares a vast picture. + + A PNG records its dimensions in its header and its pixels in a later + chunk, so a file that declares far more pixels than it carries is + refused on the declaration alone, without anything being decoded. + """ + def chunk(kind, payload): + return ( + struct.pack(">I", len(payload)) + kind + payload + + struct.pack(">I", zlib.crc32(kind + payload)) + ) + + header = struct.pack(">IIBBBBB", dimensions[0], dimensions[1], 8, 2, 0, 0, 0) + return ( + b"\x89PNG\r\n\x1a\x0a" + + chunk(b"IHDR", header) + + chunk(b"IDAT", zlib.compress(b"\x00" * 64)) + + chunk(b"tEXt", b"padding" + b"\x00" * 150) + + chunk(b"IEND", b"") + ) + + def stored_sizes(self, username): + """Return the sizes this user has an image stored in.""" + return { + size for size, name in get_profile_image_names(username).items() + if self.storage.exists(name) + } + + def all_sizes(self, username): + """Return every size the site stores an image in.""" + return set(get_profile_image_names(username)) + + def has_image(self, user): + """Return whether the account records an image of its own.""" + user.profile.refresh_from_db() + return user.profile.has_profile_image + + +@skip_unless_lms +class ProfileImageUploadTests(ProfileImageTestCase): + """POST /api/user/v2/accounts/{username}/profile_image/""" + + def test_a_user_sets_the_image_on_their_own_account(self): + self.login(self.owner) + response = self.upload() + assert response.status_code == status.HTTP_204_NO_CONTENT + assert response.data is None + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.has_image(self.owner) is True + + def test_each_stored_size_is_a_square_of_that_size(self): + self.login(self.owner) + self.upload(dimensions=(320, 240)) + for size, name in get_profile_image_names(self.owner.username).items(): + with closing(Image.open(self.storage.path(name))) as stored: + assert stored.size == (size, size), size + assert stored.format == "JPEG", size + + def test_the_account_records_when_the_image_was_set(self): + self.login(self.owner) + self.upload() + self.owner.profile.refresh_from_db() + assert self.owner.profile.profile_image_uploaded_at is not None + + def test_an_image_sent_as_the_whole_body_is_stored(self): + """The mobile apps send the image bytes with the media type of the image.""" + self.login(self.owner) + with make_image_file(extension=".jpg") as image_file: + response = self.client.post( + self.url, + image_file.read(), + content_type="image/jpeg", + HTTP_CONTENT_DISPOSITION='attachment; filename="image.jpg"', + ) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + + def test_a_second_image_replaces_the_first(self): + self.login(self.owner) + with freezegun.freeze_time("2024-01-01 10:00:00"): + assert self.upload(dimensions=(320, 240)).status_code == status.HTTP_204_NO_CONTENT + self.owner.profile.refresh_from_db() + assert self.owner.profile.profile_image_uploaded_at == datetime.datetime( + 2024, 1, 1, 10, 0, tzinfo=ZoneInfo("UTC"), + ) + + with freezegun.freeze_time("2024-01-01 11:30:00"): + assert self.upload(dimensions=(640, 640), prefix="second").status_code == ( + status.HTTP_204_NO_CONTENT + ) + self.owner.profile.refresh_from_db() + assert self.owner.profile.profile_image_uploaded_at == datetime.datetime( + 2024, 1, 1, 11, 30, tzinfo=ZoneInfo("UTC"), + ) + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.has_image(self.owner) is True + + def test_a_body_carrying_no_image_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.post(self.url, {}, format="multipart"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"file": ["No file was submitted."]} + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_the_site_will_not_take_is_refused_by_what_is_wrong_with_it(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.post(self.url, {"file": self.not_an_image()}, format="multipart"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "file": ["The file must be one of the following types: .jpeg, .jpg, .png, .gif."], + } + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_whose_media_type_does_not_match_its_name_is_refused(self): + self.login(self.owner) + with make_image_file(extension=".png") as image_file: + mislabelled = SimpleUploadedFile( + "picture.png", image_file.read(), content_type="image/jpeg", + ) + envelope = assert_error_envelope( + self.client.post(self.url, {"file": mislabelled}, format="multipart"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "file": [ + "The Content-Type header for this file does not match the file data. " + "The file may be corrupted.", + ], + } + assert self.stored_sizes(self.owner.username) == set() + + def test_an_image_larger_than_the_site_takes_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.upload(force_size=1024 * 1024 + 1), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"file": ["The file must be smaller than 1 MB in size."]} + assert self.stored_sizes(self.owner.username) == set() + + def test_an_image_smaller_than_the_site_takes_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.upload(dimensions=(1, 1), extension=".png", force_size=99), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"file": ["The file must be at least 100 bytes in size."]} + assert self.stored_sizes(self.owner.username) == set() + + def test_a_file_shaped_like_an_image_that_holds_none_is_refused(self): + """A file whose leading bytes are a PNG's is one nothing can be drawn from.""" + self.login(self.owner) + envelope = assert_error_envelope( + self.client.post(self.url, {"file": self.unreadable_image()}, format="multipart"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "file": ["The image could not be read. The file may be incomplete or corrupted."], + } + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_whose_bytes_stop_early_is_refused(self): + """An upload cut off partway answers every check its bytes can answer.""" + self.login(self.owner) + for image_format, name, media_type in ( + ("JPEG", "picture.jpg", "image/jpeg"), + ("PNG", "picture.png", "image/png"), + ("GIF", "picture.gif", "image/gif"), + ): + with self.subTest(image_format=image_format): + cut_off = SimpleUploadedFile( + name, self.cut_short(self.noisy_image(image_format=image_format)), + content_type=media_type, + ) + envelope = assert_error_envelope( + self.client.post(self.url, {"file": cut_off}, format="multipart"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "file": ["The image could not be read. The file may be incomplete or corrupted."], + } + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_sent_as_the_whole_body_whose_bytes_stop_early_is_refused(self): + """A body cut off in transfer is as much the caller's fault as a form part is.""" + self.login(self.owner) + with self.assertLogs(VIEWS_LOGGER, level="INFO") as logged: + response = self.client.post( + self.url, + self.cut_short(self.noisy_image(image_format="PNG")), + content_type="image/png", + HTTP_CONTENT_DISPOSITION='attachment; filename="picture.png"', + ) + assert [ + line for line in logged.output + if self.owner.username in line and "OSError" in line + ], logged.output + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "file": ["The image could not be read. The file may be incomplete or corrupted."], + } + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_whose_metadata_cannot_be_read_is_refused(self): + """Each stored size carries the metadata of the file it was drawn from.""" + self.login(self.owner) + unreadable = SimpleUploadedFile( + "picture.jpg", self.image_with_unreadable_metadata(), content_type="image/jpeg", + ) + envelope = assert_error_envelope( + self.client.post(self.url, {"file": unreadable}, format="multipart"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "file": ["The image could not be read. The file may be incomplete or corrupted."], + } + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_declaring_more_pixels_than_the_site_draws_is_refused(self): + """The refusal names the declaration, which is not the same fault as a file that stops early.""" + self.login(self.owner) + declared = SimpleUploadedFile( + "picture.png", self.image_declaring_more_pixels_than_it_holds(), content_type="image/png", + ) + envelope = assert_error_envelope( + self.client.post(self.url, {"file": declared}, format="multipart"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "file": ["The image declares more pixels than this site draws."], + } + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_sent_as_the_whole_body_without_a_name_is_refused(self): + """The name the body is sent under carries the extension, and nothing else does.""" + self.login(self.owner) + with make_image_file(extension=".jpg") as image_file: + response = self.client.post(self.url, image_file.read(), content_type="image/jpeg") + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "file": [ + "Missing filename. Request should include a Content-Disposition header " + "with a filename parameter.", + ], + } + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_sent_as_the_whole_body_under_a_name_of_another_type_is_refused(self): + """The extension of the name and the media type of the body must agree.""" + self.login(self.owner) + with make_image_file(extension=".jpg") as image_file: + response = self.client.post( + self.url, + image_file.read(), + content_type="image/jpeg", + HTTP_CONTENT_DISPOSITION='attachment; filename="image.png"', + ) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="malformed-body", + ) + assert envelope["title"] == "Malformed Request Body" + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_a_form_body_that_is_not_well_formed_is_refused_as_the_callers_fault(self): + """A multipart body sent without the boundary that separates its parts cannot be read.""" + self.login(self.owner) + response = self.client.post( + self.url, b"--nothing-here--", content_type="multipart/form-data", + ) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="malformed-body", + ) + assert envelope["title"] == "Malformed Request Body" + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_a_learner_may_not_set_another_learners_image(self): + self.login(self.other) + assert_error_envelope( + self.upload(address=self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_a_caller_named_for_the_address_in_case_alone_may_not_set_the_image(self): + """The address names one account, and a name that differs in case is another name.""" + self.sign_in_as_a_case_variant_of(self.owner) + assert_error_envelope( + self.upload(address=self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_a_name_no_account_holds_is_refused_as_somebody_elses_image(self): + """ + A name nobody holds is not the caller's own, so it is refused rather than reported missing. + + The refusal a caller meets at a name nobody holds is the one they meet + at any other account's address, which is what the published refusals + say happens here. + """ + self.login(self.owner) + assert_error_envelope( + self.upload(address=self.image_url("nobody-at-all")), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes("nobody-at-all") == set() + + def test_an_account_carrying_no_profile_is_not_found(self): + """The account is read when the image is recorded, and the refusal says so.""" + self.login(self.owner) + self.owner.profile.delete() + assert_error_envelope( + self.upload(), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + def test_a_staff_caller_may_not_set_another_account_s_image_either(self): + """Staff access is not an exception here: the image is the owner's to set.""" + self.login(self.staff) + assert_error_envelope( + self.upload(address=self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == set() + + def test_a_refused_upload_stays_refused_whatever_else_the_request_carries(self): + """Who may set this image is settled from the address, before the query string or the form is read.""" + self.login(self.other) + for address in ( + f"{self.url}?username={self.other.username}", + f"{self.url}?user={self.other.username}", + ): + with self.subTest(address=address): + assert_error_envelope( + self.upload(address=address), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + for field in ("username", "user"): + with self.subTest(field=field): + with make_image_file() as image_file: + response = self.client.post( + self.url, {"file": image_file, field: self.other.username}, format="multipart", + ) + assert_error_envelope( + response, + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == set() + assert self.stored_sizes(self.other.username) == set() + assert self.has_image(self.owner) is False + assert self.has_image(self.other) is False + + def test_a_name_sent_with_the_image_does_not_move_where_it_is_stored(self): + """The sizes are stored under the name the address carries, whatever the form carries.""" + self.login(self.owner) + with make_image_file() as image_file: + response = self.client.post( + self.url, {"file": image_file, "username": self.other.username}, format="multipart", + ) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.stored_sizes(self.other.username) == set() + assert self.has_image(self.owner) is True + assert self.has_image(self.other) is False + + def test_an_anonymous_caller_is_unauthenticated(self): + assert_error_envelope( + self.upload(), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + assert self.stored_sizes(self.owner.username) == set() + + def test_a_caller_who_has_not_confirmed_their_email_address_may_still_set_an_image(self): + self.owner.is_active = False + self.owner.save() + with make_image_file() as image_file: + response = self.client.post( + self.url, {"file": image_file}, format="multipart", **self.token_headers(self.owner), + ) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + + def test_a_token_is_read_by_the_class_the_platform_declares(self): + """ + Only the session class is replaced here, so a token is read by the platform's own. + + That class records every request it reads a token for, which is how an + operator finds the addresses that authenticate the way the platform + declares rather than by a list of their own. + """ + with mock.patch(DEFAULT_AUTH_RECORDER) as recorded: + with make_image_file() as image_file: + response = self.client.post( + self.url, {"file": image_file}, format="multipart", **self.token_headers(self.owner), + ) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert [call.args for call in recorded.call_args_list] == [("using_default_auth_classes", True)] + + def test_a_body_in_a_media_type_this_endpoint_cannot_read_is_refused(self): + self.login(self.owner) + assert_error_envelope( + self.client.post(self.url, {"file": "not an image"}, format="json"), + expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, + expected_type_slug="unsupported-media-type", + ) + assert self.stored_sizes(self.owner.username) == set() + + def test_a_query_parameter_this_endpoint_does_not_read_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.upload(address=f"{self.url}?foo=1"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"foo": ["No such query parameter. Send any of: format."]} + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_the_address_is_not_read_with_a_get(self): + self.login(self.owner) + assert_error_envelope( + self.client.get(self.url), + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + + +@skip_unless_lms +class ProfileImageRemovalTests(ProfileImageTestCase): + """DELETE /api/user/v2/accounts/{username}/profile_image/""" + + def setUp(self): + super().setUp() + self.login(self.owner) + assert self.upload().status_code == status.HTTP_204_NO_CONTENT + + def test_a_user_clears_the_image_on_their_own_account(self): + response = self.client.delete(self.url) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert response.data is None + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_clearing_an_account_that_carries_no_image_is_not_an_error(self): + assert self.client.delete(self.url).status_code == status.HTTP_204_NO_CONTENT + assert self.client.delete(self.url).status_code == status.HTTP_204_NO_CONTENT + assert self.has_image(self.owner) is False + + def test_a_query_parameter_this_endpoint_does_not_read_is_refused(self): + """A caller that guards a destructive request with a parameter is told it is not read.""" + envelope = assert_error_envelope( + self.client.delete(f"{self.url}?confirm=no&foo=1"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "confirm": ["No such query parameter. Send any of: format."], + "foo": ["No such query parameter. Send any of: format."], + } + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.has_image(self.owner) is True + + def test_a_learner_may_not_clear_another_learners_image(self): + self.client.logout() + self.login(self.other) + assert_error_envelope( + self.client.delete(self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.has_image(self.owner) is True + + def test_a_caller_named_for_the_address_in_case_alone_may_not_clear_the_image(self): + """The address names one account, and a name that differs in case is another name.""" + self.client.logout() + self.sign_in_as_a_case_variant_of(self.owner) + assert_error_envelope( + self.client.delete(self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.has_image(self.owner) is True + + def test_a_staff_caller_may_not_clear_another_account_s_image_either(self): + self.client.logout() + self.login(self.staff) + assert_error_envelope( + self.client.delete(self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.has_image(self.owner) is True + + def test_a_refused_removal_stays_refused_whatever_the_query_string_carries(self): + """Who may clear this image is settled from the address, before the query string is read.""" + self.client.logout() + self.login(self.other) + for address in ( + f"{self.url}?username={self.other.username}", + f"{self.url}?user={self.other.username}", + ): + with self.subTest(address=address): + assert_error_envelope( + self.client.delete(address), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.has_image(self.owner) is True + + def test_an_anonymous_caller_is_unauthenticated(self): + self.client.logout() + assert_error_envelope( + self.client.delete(self.url), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + + def test_an_account_that_no_longer_exists_is_not_found(self): + """The account is read when the image is cleared, and the refusal says so.""" + address = self.image_url(self.owner.username) + self.owner.profile.delete() + assert_error_envelope( + self.client.delete(address), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + def test_a_name_no_account_holds_is_refused_as_somebody_elses_image(self): + """ + A name nobody holds is not the caller's own, so it is refused rather than reported missing. + + The refusal a caller meets at a name nobody holds is the one they meet + at any other account's address, which is what the published refusals + say happens here. + """ + assert_error_envelope( + self.client.delete(self.image_url("nobody-at-all")), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + +@skip_unless_lms +class ProfileImageAddressedNameTests(ProfileImageTestCase): + """ + This address carries the name an account is stored under. + + The account collection reads ``me`` as the account of the caller; the + addresses beneath an account read the name they carry as it stands, so a + caller that sends ``me`` to this one is answered as a caller naming any + other account is. + """ + + def setUp(self): + super().setUp() + self.login(self.owner) + self.collection_name_url = self.image_url("me") + + def test_an_image_is_not_set_at_the_collections_own_name(self): + assert_error_envelope( + self.upload(address=self.collection_name_url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_an_image_is_not_cleared_at_the_collections_own_name(self): + assert self.upload().status_code == status.HTTP_204_NO_CONTENT + assert_error_envelope( + self.client.delete(self.collection_name_url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert self.has_image(self.owner) is True + + def test_the_account_holding_that_name_is_served_at_it(self): + """A user may register the name, and sets their own image where it is addressed.""" + holder = UserFactory.create(username="me", email="me@example.com", password=PASSWORD) + self.addCleanup(self.remove_stored_images, holder.username) + self.client.logout() + self.login(holder) + assert self.upload(address=self.collection_name_url).status_code == status.HTTP_204_NO_CONTENT + assert self.stored_sizes(holder.username) == self.all_sizes(holder.username) + assert self.has_image(holder) is True + + +@skip_unless_lms +class ProfileImageParityTests(ProfileImageTestCase): + """The same requests through the version 1 and the version 2 addresses.""" + + def test_both_versions_store_the_same_sizes(self): + self.login(self.owner) + earlier = self.upload(address=earlier_address(self.owner.username)) + assert earlier.status_code == status.HTTP_204_NO_CONTENT + earlier_sizes = self.stored_sizes(self.owner.username) + assert self.has_image(self.owner) is True + self.client.delete(earlier_address(self.owner.username)) + + later = self.upload() + assert later.status_code == earlier.status_code + assert later.data == earlier.data + assert self.stored_sizes(self.owner.username) == earlier_sizes + assert self.has_image(self.owner) is True + + def test_both_versions_clear_the_image_the_same_way(self): + self.login(self.owner) + self.upload() + earlier = self.client.delete(earlier_address(self.owner.username)) + assert earlier.status_code == status.HTTP_204_NO_CONTENT + assert self.stored_sizes(self.owner.username) == set() + + self.upload() + later = self.client.delete(self.url) + assert later.status_code == earlier.status_code + assert self.stored_sizes(self.owner.username) == set() + assert self.has_image(self.owner) is False + + def test_both_versions_refuse_an_image_the_site_will_not_take(self): + self.login(self.owner) + earlier = self.client.post( + earlier_address(self.owner.username), {"file": self.not_an_image()}, format="multipart", + ) + assert earlier.status_code == status.HTTP_400_BAD_REQUEST + assert earlier.data == { + "developer_message": "The file must be one of the following types: .jpeg, .jpg, .png, .gif.", + "user_message": "The file must be one of the following types: .jpeg, .jpg, .png, .gif.", + } + + later = self.client.post(self.url, {"file": self.not_an_image()}, format="multipart") + assert later.status_code == earlier.status_code + # The one declared difference: the refusal is the standard body, and + # the message version 1 carried as ``user_message`` names the field. + assert later.data["errors"] == { + "file": ["The file must be one of the following types: .jpeg, .jpg, .png, .gif."], + } + + def test_both_versions_refuse_a_body_carrying_no_image(self): + self.login(self.owner) + earlier = self.client.post(earlier_address(self.owner.username), {}, format="multipart") + assert earlier.status_code == status.HTTP_400_BAD_REQUEST + assert earlier.data == { + "developer_message": "No file provided for profile image", + "user_message": "No file provided for profile image", + } + + later = self.client.post(self.url, {}, format="multipart") + assert later.status_code == earlier.status_code + assert later.data["errors"] == {"file": ["No file was submitted."]} + + def test_both_versions_refuse_another_learners_image(self): + self.login(self.other) + earlier = self.upload(address=earlier_address(self.owner.username)) + assert earlier.status_code == status.HTTP_403_FORBIDDEN + + later = self.upload() + assert later.status_code == earlier.status_code + assert_error_envelope(later, expected_status=403, expected_type_slug="authz") + assert self.stored_sizes(self.owner.username) == set() + + +@pytest.fixture(name="image_owner") +@skip_unless_lms +def image_owner_fixture(client, django_user_model): # pylint: disable=unused-argument + """Sign a learner in and hand back the addresses of their image in both versions.""" + owner = UserFactory.create(username="count-image-owner", password=PASSWORD) + assert client.login(username=owner.username, password=PASSWORD) + # The first authenticated request of a session populates caches the rest + # of the session reuses; the counts below are the steady-state ones. + client.delete(reverse("user_v2:account_profile_image", kwargs={"username": owner.username})) + return owner + + +#: What setting and clearing an image cost, measured on the version 1 address +#: first and asserted on both. Neither version reads anything per stored size. +UPLOAD_QUERIES = 17 +REMOVAL_QUERIES = 17 + + +@pytest.mark.django_db +@skip_unless_lms +def test_setting_an_image_costs_what_the_earlier_address_costs( + client, image_owner, django_assert_num_queries, +): + storage = get_profile_image_storage() + try: + with make_image_file() as image_file, django_assert_num_queries(UPLOAD_QUERIES): + earlier = client.post( + f"/api/user/v1/accounts/{image_owner.username}/image", {"file": image_file}, + ) + assert earlier.status_code == status.HTTP_204_NO_CONTENT + + address = reverse("user_v2:account_profile_image", kwargs={"username": image_owner.username}) + with make_image_file() as image_file, django_assert_num_queries(UPLOAD_QUERIES): + later = client.post(address, {"file": image_file}) + assert later.status_code == status.HTTP_204_NO_CONTENT + finally: + for name in get_profile_image_names(image_owner.username).values(): + storage.delete(name) + + +@pytest.mark.django_db +@skip_unless_lms +def test_clearing_an_image_costs_what_the_earlier_address_costs( + client, image_owner, django_assert_num_queries, +): + with django_assert_num_queries(REMOVAL_QUERIES): + earlier = client.delete(f"/api/user/v1/accounts/{image_owner.username}/image") + assert earlier.status_code == status.HTTP_204_NO_CONTENT + + address = reverse("user_v2:account_profile_image", kwargs={"username": image_owner.username}) + with django_assert_num_queries(REMOVAL_QUERIES): + later = client.delete(address) + assert later.status_code == status.HTTP_204_NO_CONTENT diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py new file mode 100644 index 000000000000..2bda5f6923f8 --- /dev/null +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -0,0 +1,255 @@ +"""Views for version 2 of the profile image endpoints.""" + +import datetime +import logging +import struct +from contextlib import closing +from zoneinfo import ZoneInfo + +import piexif +from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema +from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser +from edx_rest_framework_extensions.mixins import StandardizedErrorMixin +from PIL import Image +from rest_framework import permissions, status +from rest_framework.exceptions import NotFound, ValidationError +from rest_framework.parsers import FormParser, MultiPartParser +from rest_framework.response import Response +from rest_framework.views import APIView + +from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names, set_has_profile_image +from openedx.core.djangoapps.user_api.errors import UserNotFound +from openedx.core.djangoapps.user_api.v2.errors import CatalogedRequestErrorsMixin +from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser +from openedx.core.djangoapps.user_api.v2.serializers import ErrorResponse +from openedx.core.djangoapps.user_api.v2.view_utils import ( + RESP_UNAUTHENTICATED, + RESP_UNREADABLE_BODY, + SDK_TAG, + StrictQueryParametersMixin, +) +from openedx.core.djangolib.default_auth_classes import DefaultJwtAuthentication +from openedx.core.lib.api.parsers import TypedFileUploadParser + +from ..exceptions import ImageValidationError +from ..images import create_profile_images, remove_profile_images, validate_uploaded_image +from .serializers import IMAGE_UPLOAD_REQUEST, UPLOAD_MEDIA_TYPES, ProfileImageUploadSerializer + +log = logging.getLogger(__name__) + +_USERNAME_PATH_PARAM = OpenApiParameter( + name="username", + description=( + "Unique name of the user whose image is addressed. The name is read as it is stored, so " + "`me` here names an account holding that name rather than the account of the caller " + "making the request." + ), + required=True, + location=OpenApiParameter.PATH, + type=str, +) + +_RESP_ANOTHER_USERS_IMAGE = OpenApiResponse( + ErrorResponse, description="The image belongs to another user, which nobody else may change.", +) +_RESP_NO_PROFILE = OpenApiResponse( + ErrorResponse, + description=( + "The account at this address carries no profile to record an image on. A name no account " + "holds is refused as somebody else's image instead of being reported here." + ), +) + +_CONTENT_DISPOSITION_HEADER_PARAM = OpenApiParameter( + name="Content-Disposition", + description=( + "Name the image is sent under, as `attachment; filename=\"picture.png\"`. Required of a " + "request that sends the image as the whole body, because the extension of that name is " + "what is held against the media type the body was sent in. A form part carries its own " + "name and needs no header." + ), + required=False, + location=OpenApiParameter.HEADER, + type=str, +) + +#: What a caller is told about a file that is shaped like an image the site +#: takes but holds nothing the site can draw. +UNREADABLE_IMAGE_MESSAGE = "The image could not be read. The file may be incomplete or corrupted." + +#: What a caller is told about a file whose header declares a picture far +#: larger than any this site draws, which is never decoded. +OVERSIZED_IMAGE_MESSAGE = "The image declares more pixels than this site draws." + +#: What the imaging library raises when the bytes handed to it hold no picture +#: it can draw: a file whose bytes stop early, or metadata that does not parse. +UNREADABLE_IMAGE_ERRORS = (OSError, struct.error) + + +class NamedImageUploadParser(TypedFileUploadParser): + """ + Reads an image sent as the whole request body, and refuses one sent without a name. + + The name a body is sent under carries the extension that is compared with + the media type, and it is read from the ``Content-Disposition`` header. A + body sent without that header has no name to compare, which is a fault in + the request, so it is refused here rather than left to fail further in. + """ + + def get_filename(self, stream, media_type, parser_context): + """Return the name the body was sent under, refusing a body sent without one.""" + filename = super().get_filename(stream, media_type, parser_context) + if not filename: + raise ValidationError({"file": [self.errors["no_filename"]]}) + return filename + + +@extend_schema(tags=[SDK_TAG]) +class ProfileImageView( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + StrictQueryParametersMixin, + APIView, +): + """ + The image shown beside a user's name, in each size the site renders. + + An account has one image, set and cleared whole and never listed or + addressed by an identifier of its own, so it is served from this single + address rather than routed as a collection. A user sets and clears the + image on their own account, and nobody else's: staff included, since + clearing an image is an account change rather than a moderation tool. That + is not what the account collection admits, which is the other reason this + is a view of its own rather than an action of that collection. The sizes + are stored under the username the address carries. The addresses those + stored sizes are served from belong to the account resource rather than to + this one. + """ + + # The site's own pages let a user who has not confirmed their email + # address set a picture, and the platform default refuses a session + # belonging to such an account. Only that one class is replaced: the token + # class stays the one the platform configures, which is what records a + # request as having been authenticated the default way. + authentication_classes = (DefaultJwtAuthentication, SessionAuthenticationAllowInactiveUser) + permission_classes = (permissions.IsAuthenticated, IsAddressedUser) + parser_classes = (MultiPartParser, FormParser, NamedImageUploadParser) + serializer_class = ProfileImageUploadSerializer + upload_media_types = UPLOAD_MEDIA_TYPES + + @extend_schema( + summary="Set the profile image", + description=( + "Stores the uploaded image in each size the site renders, cropped to a square, and " + "records on the account that it has one. An image already set is replaced. The image " + "may be sent as a form field named `file` or as the whole body, with the media type " + "of the image." + ), + parameters=[_USERNAME_PATH_PARAM, _CONTENT_DISPOSITION_HEADER_PARAM], + request=IMAGE_UPLOAD_REQUEST, + responses={ + 204: OpenApiResponse(description="The account now carries this image."), + 400: OpenApiResponse( + ErrorResponse, + description=( + "The request carries no usable image: none was sent, the body is not well " + "formed in the media type it was sent in, one sent as the whole body was sent " + "without a name or under a name whose extension names another media type, the " + "image is of a type or a size this site does not take, or no picture can be " + "drawn from the file, whose bytes may stop early, carry metadata that does " + "not parse, or declare more pixels than this site draws. A query parameter " + "this endpoint does not read is refused here too." + ), + ), + 401: RESP_UNAUTHENTICATED, + 403: _RESP_ANOTHER_USERS_IMAGE, + 404: _RESP_NO_PROFILE, + 415: RESP_UNREADABLE_BODY, + }, + ) + def post(self, request, username): + """Store the uploaded image in each size the site renders.""" + upload = ProfileImageUploadSerializer(data=request.data) + upload.is_valid(raise_exception=True) + uploaded_file = upload.validated_data["file"] + with closing(uploaded_file): + try: + validate_uploaded_image(uploaded_file) + except ImageValidationError as error: + raise self._unusable_image(username, error.user_message, error) from error + self._read_image(username, uploaded_file) + image_names = get_profile_image_names(username) + create_profile_images(uploaded_file, image_names) + self._record_image(username, True) + log.info( + "Generated and uploaded images %(image_names)s for user %(user_id)s", + {"image_names": list(image_names.values()), "user_id": request.user.id}, + ) + return Response(status=status.HTTP_204_NO_CONTENT) + + @extend_schema( + summary="Clear the profile image", + description=( + "Removes the stored sizes of the user's image and records on the account that it has " + "none, which is what the default image is shown for. Clearing an account that has no " + "image of its own is not an error." + ), + parameters=[_USERNAME_PATH_PARAM], + request=None, + responses={ + 204: OpenApiResponse(description="The account carries no image of its own."), + 400: OpenApiResponse( + ErrorResponse, description="The request carries a query parameter this endpoint does not read.", + ), + 401: RESP_UNAUTHENTICATED, + 403: _RESP_ANOTHER_USERS_IMAGE, + 404: _RESP_NO_PROFILE, + }, + ) + def delete(self, request, username): + """Remove the stored sizes of the user's image.""" + self._record_image(username, False) + image_names = get_profile_image_names(username) + remove_profile_images(image_names) + log.info( + "Deleted images %(image_names)s for user %(user_id)s", + {"image_names": list(image_names.values()), "user_id": request.user.id}, + ) + return Response(status=status.HTTP_204_NO_CONTENT) + + def _read_image(self, username, uploaded_file): + """ + Read the uploaded image once, refusing bytes no picture can be drawn from. + + Every stored size is drawn from these bytes and carries the metadata + found in them, so a file whose bytes stop early, whose metadata does + not parse, or whose header declares a picture far larger than any this + site draws fails partway through that work. Reading it here tells a + fault in the request apart from a failure to store what was drawn from + it, which is the site's own. + """ + try: + image = Image.open(uploaded_file) + image.load() + metadata = image.info.get("exif") + if metadata is not None: + piexif.load(metadata) + except Image.DecompressionBombError as error: + raise self._unusable_image(username, OVERSIZED_IMAGE_MESSAGE, error) from error + except UNREADABLE_IMAGE_ERRORS as error: + raise self._unusable_image(username, UNREADABLE_IMAGE_MESSAGE, error) from error + finally: + uploaded_file.seek(0) + + def _record_image(self, username, is_uploaded): + """Record on the account whether it carries an image of its own.""" + uploaded_at = datetime.datetime.now(ZoneInfo("UTC")) if is_uploaded else None + try: + set_has_profile_image(username, is_uploaded, uploaded_at) + except UserNotFound as exc: + raise NotFound from exc + + def _unusable_image(self, username, message, reason): + """Return the refusal telling the caller what the site cannot do with this image.""" + log.info("Profile image refused for %r: %r", username, reason) + return ValidationError({"file": [message]}) diff --git a/openedx/core/djangoapps/user_api/v2/errors.py b/openedx/core/djangoapps/user_api/v2/errors.py index 223f7d59e69a..bbd8b5ab2b60 100644 --- a/openedx/core/djangoapps/user_api/v2/errors.py +++ b/openedx/core/djangoapps/user_api/v2/errors.py @@ -1,7 +1,13 @@ """Error types this version of the User API classifies for itself.""" from edx_rest_framework_extensions.errors import register_error_type -from rest_framework.exceptions import MethodNotAllowed, NotAcceptable +from rest_framework.exceptions import ( + MethodNotAllowed, + NotAcceptable, + NotFound, + ParseError, + UnsupportedMediaType, +) class RefusedMethod(MethodNotAllowed): @@ -12,15 +18,45 @@ class UnsatisfiableAccept(NotAcceptable): """An ``Accept`` header naming no representation this API can produce.""" +class UnreadableRepresentation(UnsupportedMediaType): + """A request body in a media type this API cannot read.""" + + +class MalformedBody(ParseError): + """A request body that is not well formed in the media type it was sent as.""" + + +class RetiredAccount(NotFound): + """ + An account that has been retired, addressed by something it used to hold. + + The account is gone, so the answer is the same as for an address that was + never held; what is left of it is the retirement record, which the members + below name so that a caller able to reverse a retirement can find it. + """ + + def __init__(self, detail=None, can_cancel_retirement=False, retirement_id=None): + super().__init__(detail) + self.extension_members = { + "can_cancel_retirement": can_cancel_retirement, + "retirement_id": retirement_id, + } + + register_error_type(RefusedMethod, "method-not-allowed", "Method Not Allowed") register_error_type(UnsatisfiableAccept, "not-acceptable", "Not Acceptable") +register_error_type(UnreadableRepresentation, "unsupported-media-type", "Unsupported Media Type") +register_error_type(MalformedBody, "malformed-body", "Malformed Request Body") +register_error_type(RetiredAccount, "user/retired-account", "Retired Account") class CatalogedRequestErrorsMixin: """ - Names the error type of a refused method and of an unanswerable ``Accept`` header. + Names the error type of a refused method, an unanswerable ``Accept`` + header, a body in a media type this API cannot read and a body that is not + well formed in the media type it was sent as. - The shared catalog classifies neither, so both would reach the caller + The shared catalog classifies none of them, so each would reach the caller described as a server fault at a 4xx status. Raising this API's own subclasses of them names each error without changing how the same failure is classified for any other API in the process; once the shared catalog @@ -28,9 +64,33 @@ class CatalogedRequestErrorsMixin: """ def handle_exception(self, exc): - """Classify the two request failures the shared catalog leaves unnamed.""" + """Classify the request failures the shared catalog leaves unnamed.""" if isinstance(exc, MethodNotAllowed) and not isinstance(exc, RefusedMethod): exc = RefusedMethod(self.request.method, detail=exc.detail) elif isinstance(exc, NotAcceptable) and not isinstance(exc, UnsatisfiableAccept): exc = UnsatisfiableAccept(detail=exc.detail) + elif isinstance(exc, UnsupportedMediaType) and not isinstance(exc, UnreadableRepresentation): + exc = UnreadableRepresentation(self.request.content_type, detail=exc.detail) + elif isinstance(exc, ParseError) and not isinstance(exc, MalformedBody): + exc = MalformedBody(detail=exc.detail) return super().handle_exception(exc) + + +class ErrorExtensionsMixin: + """ + Adds the members an exception declares to the error body it produces. + + The shared envelope describes a failure with a fixed set of members, so a + failure that has more to say about the resource -- what can still be done + about it, which record holds the rest -- has nowhere to put it. An error + body may carry members beside the standard ones, and the ones an exception + declares are put there. + """ + + def handle_exception(self, exc): + """Answer with the standard body, extended by the members the exception declares.""" + response = super().handle_exception(exc) + members = getattr(exc, "extension_members", None) + if members and isinstance(getattr(response, "data", None), dict): + response.data.update(members) + return response diff --git a/openedx/core/djangoapps/user_api/v2/permissions.py b/openedx/core/djangoapps/user_api/v2/permissions.py index 80e78b269541..33fd8d8c75a3 100644 --- a/openedx/core/djangoapps/user_api/v2/permissions.py +++ b/openedx/core/djangoapps/user_api/v2/permissions.py @@ -1,5 +1,6 @@ """Permission classes for version 2 of the User API.""" +from rest_framework.exceptions import NotFound from rest_framework.permissions import BasePermission @@ -7,14 +8,72 @@ class IsActiveUser(BasePermission): """ Admits only a caller whose account is still active. - The authenticated and administrator checks read ``is_authenticated`` and - ``is_staff``, and neither reads ``is_active``. A token stays valid until it - expires and is accepted without the account being re-read for it, so an - account deactivated after a token was issued keeps every access that token - carries unless the account's state is checked here. edx-drf-extensions - ships no equivalent class, so this one stands in for it. + Neither the authenticated check nor the administrator check reads + ``is_active``, so a view whose answer turns on the state of the caller's + own account declares this class alongside them. edx-drf-extensions ships + no equivalent class, so this one stands in for it. """ def has_permission(self, request, view): """Return whether the caller's account is still active.""" return bool(request.user and request.user.is_active) + + +#: Query parameters that pick an account out by something about its owner +#: that the owner has not published. +ACCOUNT_CONTACT_SELECTORS = ("email", "lms_user_id") + + +class CanSelectAccountsByContact(BasePermission): + """ + Admits a caller selecting accounts by an owner's address or identifier while their account is active. + + An account selected by the email address or the numeric identifier of its + owner is reached without its owner having published either, which is a + privilege, so it is refused to a caller whose own account is no longer + active. A request that selects accounts no such way is admitted whatever + state the caller's account is in, because a user reaches their own account + before they have confirmed its address. + """ + + def has_permission(self, request, view): + """Return whether this request selects no account by contact, or comes from an active account.""" + if all(request.query_params.get(name) is None for name in ACCOUNT_CONTACT_SELECTORS): + return True + return bool(request.user and request.user.is_active) + + +class IsAddressedUser(BasePermission): + """ + Admits a caller whose username is exactly the one the address carries. + + The handlers behind this class select a record by the username in the + address, so that is the value compared here, character for character, and + the address is the only place a username is read from. Where usernames are + stored case-sensitively, two names differing in case alone are two + different names, so the comparison is exact. + """ + + def has_permission(self, request, view): + """Return whether the address names this caller, and nobody else.""" + user = request.user + if not (user and user.is_authenticated): + return False + return getattr(view, "kwargs", {}).get("username") == user.username + + +class IsStaffOrAbsent(BasePermission): + """ + Admits a platform administrator and reports the address as absent to anyone else. + + The endpoints this guards answer questions about other people's accounts. + Refusing a caller who may not ask them with a refusal would confirm that + the address exists and what it is for, so they are told instead that there + is nothing at it. + """ + + def has_permission(self, request, view): + """Admit an administrator, and report the address as absent to every other caller.""" + if request.user and request.user.is_staff: + return True + raise NotFound diff --git a/openedx/core/djangoapps/user_api/v2/selectors.py b/openedx/core/djangoapps/user_api/v2/selectors.py new file mode 100644 index 000000000000..096a7d6eed46 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/selectors.py @@ -0,0 +1,70 @@ +"""Selections over the user records version 2 of the User API answers from.""" + +import datetime +from zoneinfo import ZoneInfo + +from django.conf import settings +from django.contrib.auth.models import User # pylint: disable=imported-auth-user + +from openedx.core.djangoapps.user_api.models import UserRetirementStatus + + +def accounts_holding_emails(emails): + """Return the accounts holding any of these email addresses, by name.""" + return User.objects.filter(email__in=emails).order_by("username") + + +def usernames_among(names, ordering): + """ + Return the names these accounts are stored under, in the order asked for. + + The accounts an address or a query string names are the only ones the + answer carries, and a name no account holds matches nothing. The order is + settled here because it decides which rows fall on which page, and the + database compares and sorts the stored names: an account can therefore + come back under a spelling other than the one asked for. + """ + return ( + User.objects + .filter(username__in=names) + .order_by(ordering) + .values_list("username", flat=True) + ) + + +def username_holding_email(email): + """Return the name of the account holding this address, or ``None`` when no account holds it.""" + try: + return User.objects.get(email=email).username + except User.DoesNotExist: + return None + + +def username_holding_id(identifier): + """Return the name of the account holding this numeric identifier, or ``None``.""" + try: + return User.objects.get(id=identifier).username + except User.DoesNotExist: + return None + + +def cancellable_retirement_for_email(email): + """ + Return the retirement of the account that held this address, while it can still be cancelled. + + A retirement is cancellable for as long as the platform's cooling-off + period runs, so a retirement older than that is not reported here: the + address is gone either way, and only a retirement inside the period can be + undone by asking the platform to undo it. + """ + now = datetime.datetime.now(ZoneInfo("UTC")) + return ( + UserRetirementStatus.objects + .filter( + created__gt=now - datetime.timedelta(days=settings.COOL_OFF_DAYS), + created__lt=now, + original_email=email, + ) + .order_by("-created") + .first() + ) diff --git a/openedx/core/djangoapps/user_api/v2/serializers.py b/openedx/core/djangoapps/user_api/v2/serializers.py index 8c418252640d..c90d28676782 100644 --- a/openedx/core/djangoapps/user_api/v2/serializers.py +++ b/openedx/core/djangoapps/user_api/v2/serializers.py @@ -1,12 +1,17 @@ """Serializers for version 2 of the User API.""" + from django.contrib.auth.models import User # pylint: disable=imported-auth-user from django.urls import reverse from drf_spectacular.utils import extend_schema_field from edx_rest_framework_extensions.errors import ErrorResponseSerializer from rest_framework import serializers +from lms.djangoapps.verify_student.models import ManualVerification, SoftwareSecurePhotoVerification from openedx.core.djangoapps.user_api.models import UserPreference +from openedx.core.djangoapps.user_authn.views.registration_form import contains_html, contains_url + +from .paginators import UserApiPagination #: Value of the ``view`` query parameter that embeds the owning user in each preference. FULL_VIEW = "full" @@ -31,6 +36,32 @@ class ErrorResponse(ErrorResponseSerializer): # pylint: disable=abstract-method """ +class RetiredAccountErrorResponse(ErrorResponse): # pylint: disable=abstract-method + """ + The body of a refusal that also reports what is left of a retired account. + + The two members below are carried only when the account was selected by an + email address it held before being retired; every other refusal at this + status carries the standard members alone. + """ + + can_cancel_retirement = serializers.BooleanField( + required=False, + help_text=( + "Whether the retirement can still be reversed, which it can only while it is inside " + "the cooling-off period." + ), + ) + retirement_id = serializers.IntegerField( + required=False, + allow_null=True, + help_text=( + "Identifies the retirement to a caller able to reverse it, or null when there is " + "nothing left to reverse." + ), + ) + + class _KeptFieldsMixin: """ Describes an object reduced to the properties named in ``kept_fields``. @@ -204,3 +235,554 @@ class TimeZoneQuerySerializer(serializers.Serializer): # pylint: disable=abstra "the code names a country with no time zones of its own." ), ) + + +#: Value of the ``view`` query parameter that returns only the fields the +#: account's owner shares with everybody. +SHARED_VIEW = "shared" + +#: Properties the ``minimal`` preset keeps of an account. +ACCOUNT_MINIMAL_FIELDS = ("username", "email", "name", "profile_image") + +#: Properties the ``ordering`` parameter of the account list accepts. +ACCOUNT_SORT_FIELDS = ("username",) + +#: The order the account list uses when it is asked for none. Usernames are +#: unique, so sorting by one settles every row: the same selection asked for +#: twice is cut into the same pages. +ACCOUNT_DEFAULT_SORT = ACCOUNT_SORT_FIELDS[0] + + +class AccountProfileImageSerializer(serializers.Serializer): # pylint: disable=abstract-method + """Where a user's profile image can be fetched, in each size the site renders.""" + + has_image = serializers.BooleanField( + help_text="Whether the user has uploaded an image. The URLs below are a default image when it is false.", + ) + image_url_full = serializers.URLField(required=False, help_text="Address of the image at its largest size.") + image_url_large = serializers.URLField(required=False, help_text="Address of the image at its large size.") + image_url_medium = serializers.URLField(required=False, help_text="Address of the image at its medium size.") + image_url_small = serializers.URLField(required=False, help_text="Address of the image at its smallest size.") + + +class AccountLanguageSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A language the user has told the site they speak.""" + + code = serializers.CharField(help_text="Language code, for example ``en`` or ``pt-br``.") + + +class AccountSocialLinkSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A link to one of the user's profiles on another site.""" + + platform = serializers.CharField(help_text="Name of the site, for example ``facebook`` or ``linkedin``.") + social_link = serializers.CharField( + allow_blank=True, help_text="Address of the user's profile on that site.", + ) + + +class AccountExtendedFieldSerializer(serializers.Serializer): # pylint: disable=abstract-method + """One of the extra profile fields this site collects.""" + + field_name = serializers.CharField(help_text="Name the site configured the field under.") + field_value = serializers.JSONField( + help_text=( + "Value the user gave, in the shape this site stores it in: a string for a field " + "collected as text, and whatever the field holds otherwise. It is an empty string " + "when the field is unanswered and null where the site stores no value at all." + ), + ) + + +class AccountSerializer(serializers.Serializer): # pylint: disable=abstract-method + """ + A user's account and profile. + + Which properties a response carries depends on who asks: a user reading + their own account, and a staff caller reading anyone's, receive every + property below; anyone else receives the ones the account's owner shares, + which is why all but ``username``, ``profile_image`` and ``account_privacy`` + are marked optional here. + """ + + username = serializers.CharField(help_text="Unique name the user is addressed by.") + profile_image = AccountProfileImageSerializer( + allow_null=True, + help_text="Where the user's profile image can be fetched, null for an account without a profile.", + ) + account_privacy = serializers.CharField( + help_text=( + "How much of this account other learners may see: `all_users`, `private`, or `custom` " + "when the owner chose field by field." + ), + ) + email = serializers.EmailField(required=False, help_text="Address the site writes to the user at.") + id = serializers.IntegerField( + required=False, + help_text="Numeric identifier of the user. Addresses in this API use the username instead.", + ) + name = serializers.CharField( + required=False, allow_null=True, help_text="Full name the user gave, as it appears on certificates.", + ) + bio = serializers.CharField(required=False, allow_null=True, help_text="Short self-description.") + country = serializers.CharField( + required=False, allow_null=True, help_text="Two-letter ISO 3166-1 alpha-2 code of the user's country.", + ) + state = serializers.CharField( + required=False, allow_null=True, help_text="Code of the state or territory, recorded for the United States.", + ) + date_joined = serializers.DateTimeField(required=False, help_text="When the account was created.") + last_login = serializers.DateTimeField( + required=False, allow_null=True, help_text="When the user last signed in, null if they never have.", + ) + is_active = serializers.BooleanField( + required=False, help_text="Whether the user has confirmed their email address.", + ) + gender = serializers.CharField( + required=False, + allow_null=True, + help_text="Gender the user selected: `m`, `f`, `o`, or null when unanswered.", + ) + year_of_birth = serializers.IntegerField( + required=False, allow_null=True, help_text="Year the user was born, null when unanswered.", + ) + level_of_education = serializers.CharField( + required=False, + allow_null=True, + help_text=( + "Highest level of education the user selected: `p` for a doctorate, `m` for a " + "master's or professional degree, `b` for a bachelor's degree, `a` for an associate " + "degree, `hs` for secondary or high school, `jhs` for junior secondary or middle " + "school, `el` for elementary or primary school, `none` for no formal education, or " + "`other`. Null when unanswered, and an account registered long ago may carry a code " + "the site no longer offers." + ), + ) + goals = serializers.CharField( + required=False, allow_null=True, help_text="What the user said they want from the site.", + ) + mailing_address = serializers.CharField(required=False, allow_null=True, help_text="Postal address the user gave.") + phone_number = serializers.CharField( + required=False, allow_null=True, help_text="Digits, optionally led by a `+`, or null when unanswered.", + ) + language_proficiencies = AccountLanguageSerializer( + many=True, + required=False, + allow_null=True, + help_text=( + "Languages the user speaks, ordered by language code, null for an account without a profile." + ), + ) + social_links = AccountSocialLinkSerializer( + many=True, + required=False, + allow_null=True, + help_text=( + "The user's profiles on other sites, ordered by platform, null for an account without a profile." + ), + ) + extended_profile = AccountExtendedFieldSerializer( + many=True, + required=False, + allow_null=True, + help_text=( + "The extra profile fields this site collects, in configured order, null for an " + "account without a profile." + ), + ) + requires_parental_consent = serializers.BooleanField( + required=False, + allow_null=True, + help_text=( + "Whether the user is too young to share a profile without a guardian's consent, null " + "for an account without a profile." + ), + ) + pending_name_change = serializers.CharField( + required=False, allow_null=True, help_text="Name the user has asked to change to, null when none is pending.", + ) + verified_name = serializers.CharField( + required=False, allow_null=True, help_text="Name verified against the user's photo identification.", + ) + secondary_email = serializers.EmailField( + required=False, allow_null=True, help_text="Recovery address, present only where the site collects one.", + ) + secondary_email_enabled = serializers.BooleanField( + required=False, + allow_null=True, + help_text="Whether this site collects a recovery address, null where it collects none.", + ) + course_certificates = serializers.DictField( + required=False, + allow_null=True, + help_text="Always null here; certificates are served by the certificates API.", + ) + time_zone = serializers.CharField( + required=False, + allow_null=True, + help_text="Always null here; the time-zone preference is served by the preferences API.", + ) + + +class AccountMinimalSerializer(_KeptFieldsMixin, AccountSerializer): + """An account reduced to the properties that identify its owner.""" + + kept_fields = ACCOUNT_MINIMAL_FIELDS + + +class AccountProjectionSerializer(_OptionalFieldsMixin, AccountSerializer): + """An account reduced to the properties the caller selected.""" + + +class AccountQuerySerializer(serializers.Serializer): # pylint: disable=abstract-method + """Query parameters accepted by the account list.""" + + username = serializers.CharField( + required=False, + allow_blank=True, + help_text=( + "Comma-separated usernames. A name no account holds is left out of the page rather than refused. " + "Omit this and the other selectors to receive your own account." + ), + ) + email = serializers.EmailField( + required=False, + allow_blank=True, + help_text="Address of the one account to return. Only staff may select an account this way.", + ) + lms_user_id = serializers.IntegerField( + required=False, + help_text="Numeric identifier of the one account to return. Only staff may select an account this way.", + ) + view = serializers.ChoiceField( + choices=[ + (MINIMAL_VIEW, "The properties that identify the account's owner"), + (SHARED_VIEW, "The properties the owner shares with everybody"), + ], + required=False, + allow_blank=True, + help_text=( + "Response preset. `minimal` reduces each account to the properties that identify its owner; " + "`shared` returns only the properties the owner shares with everybody, even to a caller who " + "may see more. Omit it, or send it empty, to receive everything the caller may see." + ), + ) + ordering = serializers.ChoiceField( + choices=[ + *((field, f"{field}, ascending") for field in ACCOUNT_SORT_FIELDS), + *((f"-{field}", f"{field}, descending") for field in ACCOUNT_SORT_FIELDS), + ], + required=False, + allow_blank=True, + default=ACCOUNT_DEFAULT_SORT, + error_messages={ + "invalid_choice": ( + f"Sort by any of: {', '.join(ACCOUNT_SORT_FIELDS)}, each optionally prefixed with '-'." + ), + }, + help_text=( + "Property to sort the page by, prefixed with `-` to sort descending. Omit it, or " + f"send it empty, to sort by ascending `{ACCOUNT_DEFAULT_SORT}`. Usernames are unique, " + "so a selection asked for twice is cut into the same pages." + ), + ) + + +class _TextField(serializers.CharField): + """ + Text that is only taken as text. + + The base field spells out a number or a decimal as the digits that write + it, so a property sent as ``5`` arrives as ``"5"`` and is stored. Here a + value of any other type is refused, naming the property that carried it. + """ + + def to_internal_value(self, data): + """Return the text sent, or refuse a value that is not text.""" + if not isinstance(data, str): + self.fail("invalid") + return super().to_internal_value(data) + + +class AccountUpdateSerializer(serializers.Serializer): # pylint: disable=abstract-method + """ + The properties of an account a user may change. + + The request body is a merge patch, so every property is optional and only + the ones present are changed; sending null clears a property that allows it. + An empty text is taken for each property that accepts one, because what it + means there -- clearing the property, or a value the property cannot hold + -- is settled where the change is carried out. + """ + + email = serializers.EmailField( + required=False, + help_text="New address. The change takes effect only once the user confirms it from a message sent there.", + ) + secondary_email = serializers.EmailField( + required=False, help_text="New recovery address, confirmed the same way as the primary one.", + ) + name = _TextField( + required=False, + allow_blank=True, + help_text="Full name. A change may need identity verification before it takes effect.", + ) + bio = _TextField( + required=False, allow_blank=True, help_text="Short self-description. Send an empty text to clear it.", + ) + country = _TextField( + required=False, + allow_null=True, + allow_blank=True, + help_text="Two-letter ISO 3166-1 alpha-2 code of the user's country.", + ) + state = _TextField( + required=False, + allow_null=True, + allow_blank=True, + help_text="Code of the state or territory, recorded for the United States.", + ) + city = _TextField(required=False, allow_null=True, allow_blank=True, help_text="City the user lives in.") + gender = _TextField( + required=False, allow_null=True, allow_blank=True, help_text="Gender the user selects: `m`, `f` or `o`.", + ) + year_of_birth = serializers.IntegerField(required=False, allow_null=True, help_text="Year the user was born.") + level_of_education = _TextField( + required=False, + allow_null=True, + allow_blank=True, + help_text=( + "Highest level of education: `p` for a doctorate, `m` for a master's or professional " + "degree, `b` for a bachelor's degree, `a` for an associate degree, `hs` for secondary " + "or high school, `jhs` for junior secondary or middle school, `el` for elementary or " + "primary school, `none` for no formal education, or `other`." + ), + ) + goals = _TextField( + required=False, allow_null=True, allow_blank=True, help_text="What the user wants from the site.", + ) + mailing_address = _TextField( + required=False, allow_null=True, allow_blank=True, help_text="Postal address.", + ) + phone_number = _TextField( + required=False, + allow_blank=True, + help_text="Digits, optionally led by a `+`. Send an empty text to clear it.", + ) + language_proficiencies = AccountLanguageSerializer( + many=True, required=False, help_text="The whole list of languages the user speaks, replacing the stored one.", + ) + social_links = AccountSocialLinkSerializer( + many=True, + required=False, + help_text=( + "Links to add or replace, merged into the stored list by platform. " + "Send an empty address to drop a platform." + ), + ) + extended_profile = AccountExtendedFieldSerializer( + many=True, required=False, help_text="Values for the extra profile fields this site collects.", + ) + account_privacy = _TextField( + required=False, + allow_null=True, + allow_blank=True, + help_text="How much of the account other learners may see: `all_users`, `private` or `custom`.", + ) + + +class _TextListField(serializers.ListField): + """ + A list of text whose refusal is one message naming the entries at fault. + + The base field reports an entry it will not take under the position that + entry holds, which reaches a caller as a mapping of positions nested + inside the member naming the list, where nothing can display it. The + refusal here names those positions in a sentence instead. + """ + + def to_internal_value(self, data): + """Return the entries sent, refusing the whole list when one of them is not text.""" + try: + return super().to_internal_value(data) + except serializers.ValidationError as refusal: + if not isinstance(refusal.detail, dict): + raise + positions = ", ".join(str(position) for position in sorted(refusal.detail)) + raise serializers.ValidationError( + f"Every entry must be text, and the entries at these positions are not: {positions}.", + ) from refusal + + +#: Most addresses one search may name. A search answers with at most one +#: account per address, so holding the request to the largest page a caller +#: may ask for keeps the answer within a page a caller may read. +EMAIL_SEARCH_MAX_ADDRESSES = UserApiPagination.max_page_size + + +class EmailSearchSerializer(serializers.Serializer): # pylint: disable=abstract-method + """The addresses an account search is asked to resolve.""" + + emails = _TextListField( + child=serializers.CharField(allow_blank=True), + allow_empty=True, + max_length=EMAIL_SEARCH_MAX_ADDRESSES, + help_text=( + f"Email addresses to look up, at most {EMAIL_SEARCH_MAX_ADDRESSES} of them. An " + "address no account holds is left out of the results." + ), + ) + + +class EmailSearchResultSerializer(serializers.ModelSerializer): + """The account that holds one of the addresses searched for.""" + + email = serializers.EmailField(read_only=True, help_text="Registered email address of the user.") + id = serializers.IntegerField(read_only=True, help_text="Numeric identifier of the user.") + username = serializers.CharField(read_only=True, help_text="Unique name the user is addressed by.") + + class Meta: + model = User + fields = ("email", "id", "username") + read_only_fields = fields + + +#: Longest name the column holding a pending change can store. +NAME_MAX_LENGTH = 255 + + +class NameChangeSerializer(serializers.Serializer): # pylint: disable=abstract-method + """A request to put a different full name on a user's profile.""" + + name = serializers.CharField( + max_length=NAME_MAX_LENGTH, + help_text="Full name to put on the profile once the request is confirmed.", + ) + + def validate_name(self, name): + """Refuse a name carrying markup or a web address.""" + if contains_html(name): + raise serializers.ValidationError("Name cannot contain the following characters: < >") + if contains_url(name): + raise serializers.ValidationError("Name cannot contain a URL") + return name + + +#: Property the verification list is sorted by, and the order it uses when +#: asked for none: the most recently changed attempt first. +VERIFICATION_SORT_FIELD = "updated_at" +VERIFICATION_DEFAULT_SORT = f"-{VERIFICATION_SORT_FIELD}" + +#: Shape of the day a summary reports an accepted proof as running out on: +#: ``MM/DD/YYYY``, or empty while the day is not reported at all. +EXPIRATION_DAY_PATTERN = r"^(\d{2}/\d{2}/\d{4})?$" + + +class VerificationStatusSerializer(serializers.Serializer): # pylint: disable=abstract-method + """Where a user stands on having proved their identity.""" + + is_verified = serializers.BooleanField( + help_text="Whether an accepted proof of identity is on record and has not expired.", + ) + status = serializers.CharField( + help_text=( + "`none` until a proof has been sent in, `approved` once one has been accepted, " + "`pending` while one is being looked at, `must_reverify` once one has been turned " + "down, and `expired` once an accepted proof has run out." + ), + ) + expiration_datetime = serializers.RegexField( + EXPIRATION_DAY_PATTERN, + help_text=( + "Calendar day the accepted proof runs out, written as `MM/DD/YYYY`: the day alone, " + "where the attempt that carries the proof records the moment. It is empty until that " + "day is near enough for the user to be asked to prove their identity again." + ), + ) + + +class VerificationSerializer(serializers.Serializer): # pylint: disable=abstract-method + """ + One attempt a user has made at proving their identity. + + An attempt is stored by the service that carried out the check, in a table + of its own per kind of check, so the kind, what was said about the attempt + and the identifier it was filed under are read from the record rather than + held on it. + """ + + type = serializers.SerializerMethodField( + help_text=( + "How the identity was checked: `Software Secure` for a photo check, `Manual` for one " + "recorded by hand, and `SSO` for one recorded when the user signed in elsewhere, " + "which is also what a check carried out by an installed verification service is " + "reported as." + ), + ) + status = serializers.CharField( + help_text=( + "Where this attempt stands: `created` before it has been started, `ready` and " + "`submitted` while a photo check is on its way, `must_retry` once sending one on has " + "failed, `pending` while a check carried out elsewhere is being looked at, `approved` " + "once the attempt has been accepted and `denied` once it has been turned down." + ), + ) + expiration_datetime = serializers.DateTimeField( + allow_null=True, + help_text=( + "Moment this attempt stops counting as proof, to the second. It is null for an " + "attempt that never expires." + ), + ) + message = serializers.SerializerMethodField( + help_text="Why the attempt was turned down, or the reason it was accepted by hand. Empty otherwise.", + ) + updated_at = serializers.DateTimeField(help_text="When this attempt last changed.") + receipt_id = serializers.SerializerMethodField( + help_text="Identifier the photo verification service filed this attempt under, null for other kinds.", + ) + + def get_type(self, obj) -> str: + """Return how the identity was checked.""" + if isinstance(obj, SoftwareSecurePhotoVerification): + return "Software Secure" + if isinstance(obj, ManualVerification): + return "Manual" + return "SSO" + + def get_message(self, obj) -> str: + """Return what was said about this attempt: why it was turned down, or why it was accepted by hand.""" + if isinstance(obj, SoftwareSecurePhotoVerification): + return obj.error_msg + if isinstance(obj, ManualVerification): + return obj.reason + return "" + + def get_receipt_id(self, obj) -> str | None: + """Return the identifier the photo verification service filed this attempt under.""" + if isinstance(obj, SoftwareSecurePhotoVerification): + return obj.receipt_id + return None + + +class VerificationQuerySerializer(serializers.Serializer): # pylint: disable=abstract-method + """Query parameters accepted by the verification list.""" + + ordering = serializers.ChoiceField( + choices=[ + (VERIFICATION_SORT_FIELD, "Least recently changed attempt first"), + (VERIFICATION_DEFAULT_SORT, "Most recently changed attempt first"), + ], + required=False, + allow_blank=True, + default=VERIFICATION_DEFAULT_SORT, + error_messages={ + "invalid_choice": ( + f"Sort by any of: {VERIFICATION_SORT_FIELD}, each optionally prefixed with '-'." + ), + }, + help_text=( + "Property to sort the page by, prefixed with `-` to sort descending. Omit it, or send " + f"it empty, to sort by `{VERIFICATION_DEFAULT_SORT}`. Attempts changed at the same " + "moment are ordered by the receipt identifier, so a page is always in the same order." + ), + ) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py new file mode 100644 index 000000000000..54560629d99a --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py @@ -0,0 +1,574 @@ +"""Behaviour parity between the version 1 and version 2 account addresses.""" + +import json + +from django.urls import reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from rest_framework import status +from rest_framework.test import APITestCase + +from common.djangoapps.student.models import get_retired_email_by_email +from common.djangoapps.student.tests.factories import ( + ContentTypeFactory, + PermissionFactory, + UserFactory, +) +from openedx.core.djangolib.testing.utils import skip_unless_lms + +from .test_parity import diff, unexpected + +PASSWORD = "Password1234" +MERGE_PATCH = "application/merge-patch+json" + +EARLIER_ME = "/api/user/v1/me" +EARLIER_LIST = "/api/user/v1/accounts" +EARLIER_SEARCH = "/api/user/v1/accounts/search_emails" + + +def earlier_detail(username): + """Return the version 1 member address of one account.""" + return f"/api/user/v1/accounts/{username}" + + +def by_username(rows): + """ + Return the given rows in username order. + + The earlier addresses answer in whatever order the database returns the + accounts, so rows are brought into one order before their properties are + compared with this version's. The order a page comes back in is a + difference of its own and is pinned by the tests named for it. + """ + return sorted(rows, key=lambda row: row["username"]) + + +#: Differences each case is expected to show, as (json path, reason) pairs: the +#: diff must carry all of them and nothing else. A difference in the shape of a +#: body, or in the order of the rows it carries, is not a path and is pinned by +#: the test named for it instead. +INTENTIONAL_DIFFERENCES = { + "account_list": [], + "account_detail": [], + "shared_account": [], + "another_account": [], + "changed_account": [], + "email_search": [], +} + +#: Names the member address of this version reads as something other than a +#: username, with what each one names instead and what that address answers for +#: an account holding it. The earlier member address answers every one of them +#: with that account; here each is read through the collection, with +#: ``username=`` naming it. +RESERVED_MEMBER_IDENTIFIERS = ( + ("me", "the account of the caller", status.HTTP_200_OK), +) + + +@skip_unless_lms +class AccountParityTests(APITestCase): + """The same fixtures through the version 1 and the version 2 account addresses.""" + + def setUp(self): + super().setUp() + self.staff = UserFactory.create( + username="parity-staff", email="parity-staff@example.com", password=PASSWORD, is_staff=True, + ) + self.owner = UserFactory.create( + username="parity-owner", email="parity-owner@example.com", password=PASSWORD, + ) + self.other = UserFactory.create( + username="parity-other", email="parity-other@example.com", password=PASSWORD, + ) + + def login(self, user): + """Sign the given user in, which both versions authenticate the same way.""" + assert self.client.login(username=user.username, password=PASSWORD) + + def bodies(self, user, earlier_address, address, params=None): + """ + Return the decoded body each version answers the same request with. + + Both are read inside one session, because signing in again would stamp + a new last-login time on the account and so on the second body. + """ + self.login(user) + earlier = self.client.get(earlier_address, params or {}) + current = self.client.get(address, params or {}) + self.client.logout() + assert earlier.status_code == status.HTTP_200_OK, earlier.content + assert current.status_code == status.HTTP_200_OK, current.content + return json.loads(earlier.content), json.loads(current.content) + + def assert_parity(self, earlier, current, case): + """Assert the two bodies differ only where the case declares they do.""" + changed = diff(earlier, current) + intentional = INTENTIONAL_DIFFERENCES[case] + assert not unexpected(changed, intentional), ( + f"undeclared differences: {sorted(unexpected(changed, intentional))}\n" + f"earlier={earlier}\ncurrent={current}" + ) + for path, reason in intentional: + assert any( + key == path or key.startswith(path + ".") or key.startswith(path + "[") + for key in changed + ), f"declared difference did not occur: {path} ({reason})" + + def test_the_callers_own_address_answers_with_the_whole_account(self): + """Declared difference: the earlier address answers with the username alone.""" + self.login(self.owner) + earlier = json.loads(self.client.get(EARLIER_ME).content) + current = json.loads( + self.client.get(reverse("user_v2:account_detail", kwargs={"username": "me"})).content, + ) + named = json.loads( + self.client.get( + reverse("user_v2:account_detail", kwargs={"username": "parity-owner"}), + ).content, + ) + self.client.logout() + + assert earlier == {"username": "parity-owner"} + assert current["username"] == earlier["username"] + assert current["email"] == "parity-owner@example.com" + assert current == named + assert set(current) > set(earlier) + + def test_the_earlier_own_address_body_is_the_selection_of_one_property(self): + """The property the earlier address answered with is one selection of this one.""" + earlier, current = self.bodies( + self.owner, + EARLIER_ME, + reverse("user_v2:account_detail", kwargs={"username": "me"}), + {"fields": "username"}, + ) + assert earlier == current == {"username": "parity-owner"} + + def test_account_list_parity(self): + earlier, current = self.bodies( + self.staff, EARLIER_LIST, reverse("user_v2:account_list"), + {"username": "parity-other,parity-owner"}, + ) + assert isinstance(earlier, list) + assert len(earlier) == 2 + self.assert_parity(earlier, current["results"], "account_list") + + def test_the_page_carries_the_rows_the_earlier_list_returned_unbounded(self): + """ + Differences this version declares: the rows come in a page, and in username order. + + The earlier address answered with a bare array of every account named, + in the order the database returned them; here they are the page of the + envelope each list of this version answers with, ordered by username, + so the same selection asked for twice is cut into the same pages. + """ + earlier, current = self.bodies( + self.staff, EARLIER_LIST, reverse("user_v2:account_list"), + {"username": "parity-other,parity-owner"}, + ) + assert isinstance(earlier, list) + assert {account["username"] for account in earlier} == {"parity-other", "parity-owner"} + assert set(current) == { + "count", "num_pages", "current_page", "start", "next", "previous", "results", + } + assert current["count"] == len(earlier) + assert [account["username"] for account in current["results"]] == [ + "parity-other", "parity-owner", + ] + + def test_an_account_whose_name_this_version_reserves_is_read_through_the_collection(self): + """Declared difference: a reserved name addresses something else here.""" + self.login(self.staff) + for name, _names_instead, member_status in RESERVED_MEMBER_IDENTIFIERS: + held = UserFactory.create( + username=name, email=f"{name}@example.com", password=PASSWORD, + ) + earlier = self.client.get(earlier_detail(name)) + assert earlier.status_code == status.HTTP_200_OK, earlier.content + assert json.loads(earlier.content)["username"] == name + + member = self.client.get(reverse("user_v2:account_detail", kwargs={"username": name})) + assert member.status_code == member_status + assert json.loads(member.content).get("username") != name + + page = self.client.get(reverse("user_v2:account_list"), {"username": name}) + assert page.status_code == status.HTTP_200_OK + assert [row["username"] for row in json.loads(page.content)["results"]] == [name] + assert json.loads(page.content)["results"][0]["email"] == held.email + self.client.logout() + + def test_a_selection_that_matches_no_account_is_an_empty_page(self): + """Declared difference: a collection that matched nothing is empty rather than absent.""" + self.login(self.staff) + earlier = self.client.get(EARLIER_LIST, {"username": "nobody"}) + current = self.client.get(reverse("user_v2:account_list"), {"username": "nobody"}) + self.client.logout() + + assert earlier.status_code == status.HTTP_404_NOT_FOUND + assert earlier.content == b"" + assert current.status_code == status.HTTP_200_OK + assert json.loads(current.content)["count"] == 0 + assert json.loads(current.content)["results"] == [] + + def test_account_detail_parity_for_the_owner(self): + earlier, current = self.bodies( + self.owner, + earlier_detail("parity-owner"), + reverse("user_v2:account_detail", kwargs={"username": "parity-owner"}), + ) + self.assert_parity(earlier, current, "account_detail") + assert current["email"] == "parity-owner@example.com" + + def test_account_detail_parity_for_a_staff_caller(self): + earlier, current = self.bodies( + self.staff, + earlier_detail("parity-owner"), + reverse("user_v2:account_detail", kwargs={"username": "parity-owner"}), + ) + self.assert_parity(earlier, current, "account_detail") + + def test_the_properties_another_learner_may_see_are_unchanged(self): + """The field-level visibility is the whole of the record protection on this resource.""" + earlier, current = self.bodies( + self.owner, + earlier_detail("parity-other"), + reverse("user_v2:account_detail", kwargs={"username": "parity-other"}), + ) + assert set(earlier) == {"account_privacy", "profile_image", "username"} + self.assert_parity(earlier, current, "another_account") + + def test_the_shared_preset_is_unchanged(self): + earlier, current = self.bodies( + self.owner, + earlier_detail("parity-owner"), + reverse("user_v2:account_detail", kwargs={"username": "parity-owner"}), + {"view": "shared"}, + ) + assert set(earlier) == {"account_privacy", "profile_image", "username"} + self.assert_parity(earlier, current, "shared_account") + + def test_the_account_a_change_answers_with_is_unchanged(self): + self.login(self.owner) + earlier = self.client.patch( + earlier_detail("parity-owner"), json.dumps({"bio": "parity bio"}), content_type=MERGE_PATCH, + ) + current = self.client.patch( + reverse("user_v2:account_detail", kwargs={"username": "parity-owner"}), + json.dumps({"bio": "parity bio"}), + content_type=MERGE_PATCH, + ) + assert earlier.status_code == status.HTTP_200_OK, earlier.content + assert current.status_code == status.HTTP_200_OK, current.content + self.assert_parity(json.loads(earlier.content), json.loads(current.content), "changed_account") + assert json.loads(current.content)["bio"] == "parity bio" + + def test_email_search_parity(self): + emails = {"emails": ["parity-other@example.com", "parity-owner@example.com"]} + self.login(self.staff) + earlier = self.client.post(EARLIER_SEARCH, emails, format="json") + current = self.client.post(reverse("user_v2:email_search_list"), emails, format="json") + assert earlier.status_code == status.HTTP_200_OK, earlier.content + assert current.status_code == status.HTTP_200_OK, current.content + earlier_rows = by_username(json.loads(earlier.content)) + self.assert_parity(earlier_rows, json.loads(current.content)["results"], "email_search") + assert earlier_rows[0]["email"] == "parity-other@example.com" + + def test_the_search_page_carries_the_rows_the_earlier_search_returned_unbounded(self): + """ + Differences this version declares: the rows come in a page, and in username order. + + The earlier address answered with a bare array of every account it + found, in the order the database returned them; here they are the page + of the envelope each list of this version answers with, ordered by + username, so the same search asked for twice is cut into the same + pages. + """ + emails = {"emails": [ + "parity-other@example.com", "parity-owner@example.com", "parity-staff@example.com", + ]} + self.login(self.staff) + earlier = json.loads(self.client.post(EARLIER_SEARCH, emails, format="json").content) + current = json.loads( + self.client.post(reverse("user_v2:email_search_list"), emails, format="json").content, + ) + self.client.logout() + + assert isinstance(earlier, list) + assert {row["username"] for row in earlier} == { + "parity-other", "parity-owner", "parity-staff", + } + assert set(current) == { + "count", "num_pages", "current_page", "start", "next", "previous", "results", + } + assert current["count"] == len(earlier) + assert [row["username"] for row in current["results"]] == [ + "parity-other", "parity-owner", "parity-staff", + ] + assert current["next"] is None + + +@skip_unless_lms +class AccountRefusalParityTests(APITestCase): + """The refusals each version answers with, recorded beside each other.""" + + def setUp(self): + super().setUp() + self.staff = UserFactory.create( + username="refusal-staff", email="refusal-staff@example.com", password=PASSWORD, is_staff=True, + ) + self.owner = UserFactory.create( + username="refusal-owner", email="refusal-owner@example.com", password=PASSWORD, + ) + self.other = UserFactory.create( + username="refusal-other", email="refusal-other@example.com", password=PASSWORD, + ) + self.member = reverse("user_v2:account_detail", kwargs={"username": "refusal-owner"}) + + def login(self, user): + """Sign the given user in.""" + assert self.client.login(username=user.username, password=PASSWORD) + + def test_an_unauthenticated_refusal_keeps_its_status_and_changes_its_body(self): + earlier = self.client.get(EARLIER_LIST) + assert earlier.status_code == status.HTTP_401_UNAUTHORIZED + assert json.loads(earlier.content) == { + "detail": "Authentication credentials were not provided.", + } + + current = self.client.get(reverse("user_v2:account_list")) + envelope = assert_error_envelope( + current, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + assert envelope["title"] == "Authentication Required" + assert envelope["instance"] == "/api/user/v2/accounts/" + + def test_a_selection_no_account_matches_is_a_page_here_and_was_a_refusal_before(self): + """ + Selecting by an address nobody holds narrows the page to nothing instead of refusing. + + The earlier address answered one collection two ways: a name it found + nothing behind left the page empty, while an address it found nothing + behind was refused. Here every selector narrows the same way, and the + refusal is kept for an address an account held before it was retired. + """ + self.login(self.staff) + selection = {"email": "nobody@example.com"} + earlier = self.client.get(EARLIER_LIST, selection) + assert earlier.status_code == status.HTTP_404_NOT_FOUND + + current = self.client.get(reverse("user_v2:account_list"), selection) + assert current.status_code == status.HTTP_200_OK + body = json.loads(current.content) + assert body["count"] == 0 + assert body["results"] == [] + + def test_a_name_no_account_holds_keeps_its_status_and_gains_a_body(self): + self.login(self.staff) + earlier = self.client.get(earlier_detail("nobody")) + assert earlier.status_code == status.HTTP_404_NOT_FOUND + assert earlier.content == b"" + + current = self.client.get(reverse("user_v2:account_detail", kwargs={"username": "nobody"})) + envelope = assert_error_envelope( + current, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + assert envelope["detail"] == "Not found." + + def test_changing_another_account_keeps_its_status_and_gains_a_body(self): + self.login(self.owner) + earlier = self.client.patch( + earlier_detail("refusal-other"), json.dumps({"bio": "x"}), content_type=MERGE_PATCH, + ) + assert earlier.status_code == status.HTTP_403_FORBIDDEN + assert earlier.content == b"" + + current = self.client.patch( + reverse("user_v2:account_detail", kwargs={"username": "refusal-other"}), + json.dumps({"bio": "x"}), + content_type=MERGE_PATCH, + ) + assert_error_envelope( + current, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_a_refused_change_names_the_same_property_in_a_body_of_another_shape(self): + self.login(self.owner) + body = json.dumps({"year_of_birth": "recently"}) + earlier = self.client.patch(earlier_detail("refusal-owner"), body, content_type=MERGE_PATCH) + assert earlier.status_code == status.HTTP_400_BAD_REQUEST + assert json.loads(earlier.content) == { + "field_errors": { + "year_of_birth": { + "developer_message": "Value 'recently' is not valid for field 'year_of_birth': " + "['A valid integer is required.']", + "user_message": "This value is invalid.", + }, + }, + } + + current = self.client.patch(self.member, body, content_type=MERGE_PATCH) + envelope = assert_error_envelope( + current, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + # Both answers name the property and say the value is not a year. The + # earlier one says why inside its developer message and keeps a fixed + # sentence for the reader; this one says it once, where a reader looks. + assert envelope["errors"] == {"year_of_birth": ["A valid integer is required."]} + + def test_a_body_in_another_media_type_keeps_its_status_and_gains_a_body(self): + self.login(self.owner) + earlier = self.client.patch( + earlier_detail("refusal-owner"), json.dumps({"bio": "x"}), content_type="application/json", + ) + assert earlier.status_code == status.HTTP_415_UNSUPPORTED_MEDIA_TYPE + + current = self.client.patch(self.member, json.dumps({"bio": "x"}), content_type="application/json") + assert_error_envelope( + current, + expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, + expected_type_slug="unsupported-media-type", + ) + + def test_the_search_hides_itself_from_a_learner_in_both_versions(self): + self.login(self.owner) + emails = {"emails": ["refusal-owner@example.com"]} + earlier = self.client.post(EARLIER_SEARCH, emails, format="json") + assert earlier.status_code == status.HTTP_404_NOT_FOUND + assert json.loads(earlier.content) == { + "developer_message": "not_found", "user_message": "Not Found", + } + + current = self.client.post(reverse("user_v2:email_search_list"), emails, format="json") + assert_error_envelope( + current, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_a_search_without_addresses_keeps_its_status_and_names_the_property(self): + self.login(self.staff) + earlier = self.client.post(EARLIER_SEARCH, {}, format="json") + assert earlier.status_code == status.HTTP_400_BAD_REQUEST + assert json.loads(earlier.content) == { + "developer_message": "'emails' field is required", + "user_message": "'emails' field is required", + } + + current = self.client.post(reverse("user_v2:email_search_list"), {}, format="json") + envelope = assert_error_envelope( + current, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"emails": ["This field is required."]} + + def test_a_search_longer_than_a_page_is_refused_here_and_was_answered_before(self): + """ + A difference this version declares: a search names at most a hundred addresses. + + The earlier address took as many addresses as a body could carry and + read them in one query; here a search is held to what the largest page + a caller may ask for can answer with. + """ + self.login(self.staff) + emails = {"emails": [f"crowd-{index:03d}@example.com" for index in range(101)]} + + earlier = self.client.post(EARLIER_SEARCH, emails, format="json") + assert earlier.status_code == status.HTTP_200_OK, earlier.content + assert json.loads(earlier.content) == [] + + current = self.client.post(reverse("user_v2:email_search_list"), emails, format="json") + envelope = assert_error_envelope( + current, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "emails": ["Ensure this field has no more than 100 elements."], + } + + def test_the_address_of_a_retired_account_keeps_what_the_earlier_body_carried(self): + self.login(self.staff) + retired_email = self.other.email + self.other.email = get_retired_email_by_email(retired_email) + self.other.save() + + earlier = self.client.get(EARLIER_LIST, {"email": retired_email}) + assert earlier.status_code == status.HTTP_404_NOT_FOUND + earlier_body = json.loads(earlier.content) + assert set(earlier_body) == {"error_msg", "can_cancel_retirement", "retirement_id"} + + current = self.client.get(reverse("user_v2:account_list"), {"email": retired_email}) + envelope = assert_error_envelope( + current, + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="user/retired-account", + ) + assert envelope["detail"] == earlier_body["error_msg"] + assert envelope["can_cancel_retirement"] == earlier_body["can_cancel_retirement"] + assert envelope["retirement_id"] == earlier_body["retirement_id"] + + +@skip_unless_lms +class DeactivationParityTests(APITestCase): + """The deactivation of an account, through each version.""" + + def setUp(self): + super().setUp() + self.deactivator = UserFactory.create(username="parity-deactivator", password=PASSWORD) + self.deactivator.user_permissions.add( + PermissionFactory( + codename="can_deactivate_users", + content_type=ContentTypeFactory(app_label="student"), + ), + ) + self.earlier_target = UserFactory.create(username="parity-target-one", password=PASSWORD) + self.target = UserFactory.create(username="parity-target-two", password=PASSWORD) + assert self.client.login(username=self.deactivator.username, password=PASSWORD) + + def test_both_versions_make_the_password_unusable(self): + earlier = self.client.post(f"/api/user/v1/accounts/{self.earlier_target.username}/deactivate/") + assert earlier.status_code == status.HTTP_200_OK + assert json.loads(earlier.content)["username"] == "parity-target-one" + self.earlier_target.refresh_from_db() + assert not self.earlier_target.has_usable_password() + + current = self.client.post( + reverse("user_v2:account_deactivation", kwargs={"username": self.target.username}), + ) + assert current.status_code == status.HTTP_204_NO_CONTENT + assert current.content == b"" + self.target.refresh_from_db() + assert not self.target.has_usable_password() + + def test_the_reserved_identifier_names_the_same_account_on_both_addresses(self): + """``me`` is a stored username on this action in both versions, not a name for the caller.""" + held = UserFactory.create(username="me", password=PASSWORD) + earlier = self.client.post("/api/user/v1/accounts/me/deactivate/") + assert earlier.status_code == status.HTTP_200_OK + assert json.loads(earlier.content)["username"] == "me" + held.refresh_from_db() + assert not held.has_usable_password() + + held.set_password(PASSWORD) + held.save() + current = self.client.post(reverse("user_v2:account_deactivation", kwargs={"username": "me"})) + assert current.status_code == status.HTTP_204_NO_CONTENT + held.refresh_from_db() + assert not held.has_usable_password() + self.deactivator.refresh_from_db() + assert self.deactivator.has_usable_password() + + def test_the_account_is_readable_after_it_is_deactivated(self): + """The account the earlier version answered with is one read away.""" + self.client.post( + reverse("user_v2:account_deactivation", kwargs={"username": self.target.username}), + ) + account = self.client.get( + reverse("user_v2:account_detail", kwargs={"username": self.target.username}), + ) + assert account.status_code == status.HTTP_200_OK + assert json.loads(account.content)["username"] == "parity-target-two" + + def test_a_name_no_account_holds_is_not_found(self): + """An address naming no account is refused with the envelope every refusal carries.""" + current = self.client.post( + reverse("user_v2:account_deactivation", kwargs={"username": "nobody"}), + ) + assert_error_envelope( + current, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_query_counts.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_query_counts.py new file mode 100644 index 000000000000..ab67874f3bb1 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_query_counts.py @@ -0,0 +1,410 @@ +"""Query-count guards for the version 2 User API account addresses.""" + +import json + +import pytest +from django.urls import reverse + +from common.djangoapps.student.tests.factories import ( + ContentTypeFactory, + PermissionFactory, + UserFactory, +) +from openedx.core.djangoapps.user_api.accounts import ( + ACCOUNT_VISIBILITY_PREF_KEY, + ALL_USERS_VISIBILITY, + CUSTOM_VISIBILITY, + VISIBILITY_PREFIX, +) +from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangolib.testing.utils import skip_unless_lms + +PASSWORD = "Password1234" +MERGE_PATCH = "application/merge-patch+json" + +#: Collection sizes a per-account query would show up at. +ROW_COUNTS = [1, 5, 25] + +#: Page sizes, so that what a page costs can be told apart from what the +#: collection behind it costs. +PAGE_SIZES = [1, 5, 10] + +#: Year of birth the measured accounts carry. An account that records none +#: counts as a minor, and what a caller may see of it is settled by that +#: before any preference of its owner is read, which is fewer reads than a +#: populated account costs. +MEASURED_YEAR_OF_BIRTH = 1990 + +#: What one page of accounts costs a staff caller, by the number of accounts +#: on it: a constant part of sixteen, and six reads for each account the page +#: carries. The account service selects the accounts in one query and then +#: builds each one on its own, reading its recovery address, its languages, +#: its links, its pending name change, one stored preference and the switch +#: that says whether a recovery address is offered at all. The page pays none +#: of that for the accounts it leaves out, which is what these numbers pin. +ACCOUNT_LIST_QUERIES = {1: 22, 5: 46, 10: 76} + +#: The same page read by a learner, who may see of each account only what its +#: owner shares: the six reads above and the stored preference that says how +#: much that is, seven an account. +LEARNER_LIST_QUERIES = {1: 23, 5: 51, 10: 86} + +#: The same page where every owner has chosen property by property what they +#: share: the seven reads above and the preferences that choice is written in, +#: read once for the account rather than once for each property, eight an +#: account. A page carries at most a hundred accounts, so this is the dearest +#: page the list answers with. +CHOSEN_VISIBILITY_LIST_QUERIES = {1: 24, 5: 56, 10: 96} + +ACCOUNT_DETAIL_QUERIES = 20 +OWN_ACCOUNT_QUERIES = 20 + +#: Address of the one this version answers with the caller's own account. It +#: answered with the username alone and read nothing of the account to do it, +#: so what the whole account costs is what this version's answer costs more. +#: Selecting the one property the earlier body carried shapes that answer; it +#: does not make it cheaper, because the account is built before it is shaped. +#: The earlier address is read first below, so the reads a request pays once +#: are counted against it and the difference measured is the smaller one. +EARLIER_OWN_ACCOUNT = "/api/user/v1/me" +EARLIER_OWN_ACCOUNT_QUERIES = 13 +#: A search is answered a page at a time, which costs one read for the page of +#: rows and one for the number of rows there are to page through, whatever the +#: addresses asked about. +EMAIL_SEARCH_QUERIES = 15 + +#: Address of the account list this version replaces, which has no pages: it +#: serves every account named in one unbounded response and pays the per-account +#: cost above for all of them. +EARLIER_ACCOUNT_LIST = "/api/user/v1/accounts" +EARLIER_ACCOUNT_LIST_QUERIES = {1: 20, 5: 44, 25: 164} + +#: What a change of one property costs, measured on the version 1 address +#: first. Both versions do the same work and answer with the account as it now +#: stands, so the one number is asserted on both addresses. +CHANGE_QUERIES = 30 + +#: What a deactivation costs on each address. The earlier one answers with the +#: account it deactivated and pays for reading it back; this one answers with +#: nothing, so it is cheaper by exactly those reads. +EARLIER_DEACTIVATION_QUERIES = 24 +DEACTIVATION_QUERIES = 18 + + +def measured_accounts(count): + """Return ``count`` accounts carrying the profile data a populated account holds.""" + return [ + UserFactory.create( + username=f"counted{index:03d}", + email=f"counted{index:03d}@example.com", + profile__year_of_birth=MEASURED_YEAR_OF_BIRTH, + ) + for index in range(count) + ] + + +def warm_up(client): + """ + Spend what a session pays once, so the counts are the steady-state ones. + + The first authenticated request of a session populates caches the rest of + the session reuses. + """ + client.get(reverse("user_v2:account_list")) + + +@pytest.fixture(name="accounts") +@skip_unless_lms +def accounts_fixture(request, client, django_user_model): # pylint: disable=unused-argument + """Sign a staff caller in and give the site ``request.param`` other accounts.""" + staff = UserFactory.create( + username="count-staff", + password=PASSWORD, + is_staff=True, + profile__year_of_birth=MEASURED_YEAR_OF_BIRTH, + ) + users = measured_accounts(request.param) + assert client.login(username=staff.username, password=PASSWORD) + warm_up(client) + return users + + +@pytest.fixture(name="accounts_read_by_a_learner") +@skip_unless_lms +def learner_accounts_fixture(request, client, django_user_model): # pylint: disable=unused-argument + """Sign a learner in beside ``request.param`` accounts belonging to other people.""" + learner = UserFactory.create( + username="count-learner", + password=PASSWORD, + profile__year_of_birth=MEASURED_YEAR_OF_BIRTH, + ) + users = measured_accounts(request.param) + assert client.login(username=learner.username, password=PASSWORD) + warm_up(client) + return users + + +@pytest.fixture(name="accounts_shared_by_choice") +@skip_unless_lms +def chosen_visibility_fixture(request, client, django_user_model): # pylint: disable=unused-argument + """Sign a learner in beside accounts whose owners chose property by property what they share.""" + learner = UserFactory.create( + username="count-learner", + password=PASSWORD, + profile__year_of_birth=MEASURED_YEAR_OF_BIRTH, + ) + users = measured_accounts(request.param) + for user in users: + UserPreferenceFactory.create( + user=user, key=ACCOUNT_VISIBILITY_PREF_KEY, value=CUSTOM_VISIBILITY, + ) + UserPreferenceFactory.create( + user=user, key=f"{VISIBILITY_PREFIX}bio", value=ALL_USERS_VISIBILITY, + ) + assert client.login(username=learner.username, password=PASSWORD) + warm_up(client) + return users + + +def selected(users): + """Return the selector naming every account of the fixture.""" + return ",".join(user.username for user in users) + + +@pytest.mark.django_db +@pytest.mark.parametrize("accounts", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_account_list_query_count_does_not_grow_with_the_accounts_selected( + client, accounts, django_assert_num_queries, +): + url = reverse("user_v2:account_list") + with django_assert_num_queries(ACCOUNT_LIST_QUERIES[1]): + response = client.get(url, {"username": selected(accounts), "page_size": 1}) + assert response.json()["count"] == len(accounts) + assert len(response.json()["results"]) == 1 + + +@pytest.mark.django_db +@pytest.mark.parametrize("page_size", PAGE_SIZES) +@pytest.mark.parametrize("accounts", [25], indirect=True) +@skip_unless_lms +def test_the_page_costs_what_it_carries_and_not_what_the_collection_holds( + client, accounts, page_size, django_assert_num_queries, +): + url = reverse("user_v2:account_list") + with django_assert_num_queries(ACCOUNT_LIST_QUERIES[page_size]): + response = client.get(url, {"username": selected(accounts), "page_size": page_size}) + assert response.json()["count"] == 25 + assert len(response.json()["results"]) == page_size + + +@pytest.mark.django_db +@pytest.mark.parametrize("page_size", PAGE_SIZES) +@pytest.mark.parametrize("accounts_read_by_a_learner", [25], indirect=True) +@skip_unless_lms +def test_a_learner_reading_other_accounts_pays_for_the_page_and_not_the_collection( + client, accounts_read_by_a_learner, page_size, django_assert_num_queries, +): + """What a caller may see of an account is worked out for the accounts of the page alone.""" + url = reverse("user_v2:account_list") + with django_assert_num_queries(LEARNER_LIST_QUERIES[page_size]): + response = client.get( + url, {"username": selected(accounts_read_by_a_learner), "page_size": page_size}, + ) + assert response.json()["count"] == 25 + assert len(response.json()["results"]) == page_size + assert "email" not in response.json()["results"][0] + + +@pytest.mark.django_db +@pytest.mark.parametrize("page_size", PAGE_SIZES) +@pytest.mark.parametrize("accounts_shared_by_choice", [25], indirect=True) +@skip_unless_lms +def test_an_account_shared_property_by_property_costs_one_read_more( + client, accounts_shared_by_choice, page_size, django_assert_num_queries, +): + """An owner who chose what they share is asked for that choice once, not once per property.""" + url = reverse("user_v2:account_list") + with django_assert_num_queries(CHOSEN_VISIBILITY_LIST_QUERIES[page_size]): + response = client.get( + url, {"username": selected(accounts_shared_by_choice), "page_size": page_size}, + ) + assert response.json()["count"] == 25 + assert len(response.json()["results"]) == page_size + assert "bio" in response.json()["results"][0] + + +@pytest.mark.django_db +@pytest.mark.parametrize("accounts", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_the_earlier_account_list_pays_for_every_account_named( + client, accounts, django_assert_num_queries, +): + """ + Both lists are measured over the same accounts, so the saving cannot drift apart. + + The earlier address serves every account named in one response and pays + the per-account cost for all of them; this one pays it for the accounts of + the page alone. + """ + # The two pins together say that the earlier cost grows with the accounts + # named while the page's does not, so neither can be changed on its own. + assert EARLIER_ACCOUNT_LIST_QUERIES[25] > EARLIER_ACCOUNT_LIST_QUERIES[1] + assert ACCOUNT_LIST_QUERIES[1] < EARLIER_ACCOUNT_LIST_QUERIES[25] + + with django_assert_num_queries(EARLIER_ACCOUNT_LIST_QUERIES[len(accounts)]): + earlier = client.get(EARLIER_ACCOUNT_LIST, {"username": selected(accounts)}) + assert len(earlier.json()) == len(accounts) + + with django_assert_num_queries(ACCOUNT_LIST_QUERIES[1]): + current = client.get( + reverse("user_v2:account_list"), {"username": selected(accounts), "page_size": 1}, + ) + assert current.json()["count"] == len(accounts) + + +@pytest.mark.django_db +@pytest.mark.parametrize("accounts", [5], indirect=True) +@skip_unless_lms +def test_member_query_counts(client, accounts, django_assert_num_queries): + with django_assert_num_queries(ACCOUNT_DETAIL_QUERIES): + response = client.get(reverse("user_v2:account_detail", kwargs={"username": "counted000"})) + assert response.json()["username"] == "counted000" + + with django_assert_num_queries(OWN_ACCOUNT_QUERIES): + own = client.get(reverse("user_v2:account_detail", kwargs={"username": "me"})) + assert own.json()["username"] == "count-staff" + + +@pytest.mark.django_db +@pytest.mark.parametrize("accounts", [1], indirect=True) +@skip_unless_lms +def test_the_callers_own_account_costs_more_here_than_the_name_alone_did( + client, accounts, django_assert_num_queries, +): + """ + Declared difference: this address answers with the whole account. + + The earlier address answered with the username, which it had already, and + asking this one for that property alone shapes the answer rather than the + work behind it: the account is built and then reduced, so the selection + costs what the whole account costs. + """ + with django_assert_num_queries(EARLIER_OWN_ACCOUNT_QUERIES): + earlier = client.get(EARLIER_OWN_ACCOUNT) + assert earlier.json() == {"username": "count-staff"} + + with django_assert_num_queries(OWN_ACCOUNT_QUERIES): + whole = client.get(reverse("user_v2:account_detail", kwargs={"username": "me"})) + assert whole.json()["username"] == "count-staff" + assert set(whole.json()) > set(earlier.json()) + + with django_assert_num_queries(OWN_ACCOUNT_QUERIES): + one_property = client.get( + reverse("user_v2:account_detail", kwargs={"username": "me"}), {"fields": "username"}, + ) + assert one_property.json() == earlier.json() + assert OWN_ACCOUNT_QUERIES > EARLIER_OWN_ACCOUNT_QUERIES + + +@pytest.mark.django_db +@pytest.mark.parametrize("accounts", ROW_COUNTS, indirect=True) +@skip_unless_lms +def test_email_search_query_count_does_not_grow_with_the_addresses_searched( + client, accounts, django_assert_num_queries, +): + with django_assert_num_queries(EMAIL_SEARCH_QUERIES): + response = client.post( + reverse("user_v2:email_search_list"), + {"emails": [user.email for user in accounts]}, + content_type="application/json", + ) + assert response.json()["count"] == len(accounts) + + +@pytest.fixture(name="account_owner") +@skip_unless_lms +def account_owner_fixture(client, django_user_model): # pylint: disable=unused-argument + """Sign a learner in whose own account is the one changed.""" + owner = UserFactory.create( + username="count-change-owner", + password=PASSWORD, + profile__year_of_birth=MEASURED_YEAR_OF_BIRTH, + ) + assert client.login(username=owner.username, password=PASSWORD) + warm_up(client) + return owner + + +@pytest.fixture(name="deactivation_targets") +@skip_unless_lms +def deactivation_fixture(client, django_user_model): # pylint: disable=unused-argument + """Sign a caller in who may deactivate accounts, beside one account per version to deactivate.""" + deactivator = UserFactory.create(username="count-deactivator", password=PASSWORD) + deactivator.user_permissions.add( + PermissionFactory( + codename="can_deactivate_users", + content_type=ContentTypeFactory(app_label="student"), + ), + ) + targets = ( + UserFactory.create(username="count-target-one", password=PASSWORD), + UserFactory.create(username="count-target-two", password=PASSWORD), + ) + assert client.login(username=deactivator.username, password=PASSWORD) + warm_up(client) + return targets + + +@pytest.mark.django_db +@skip_unless_lms +def test_a_change_costs_what_the_earlier_address_costs( + client, account_owner, django_assert_num_queries, +): + """A property is changed for the same reads on both addresses, and each answers with the account.""" + with django_assert_num_queries(CHANGE_QUERIES): + earlier = client.patch( + f"/api/user/v1/accounts/{account_owner.username}", + json.dumps({"bio": "Earlier bio"}), + content_type=MERGE_PATCH, + ) + assert earlier.json()["bio"] == "Earlier bio" + + with django_assert_num_queries(CHANGE_QUERIES): + later = client.patch( + reverse("user_v2:account_detail", kwargs={"username": account_owner.username}), + json.dumps({"bio": "Later bio"}), + content_type=MERGE_PATCH, + ) + assert later.json()["bio"] == "Later bio" + + +@pytest.mark.django_db +@skip_unless_lms +def test_a_deactivation_costs_what_the_earlier_address_costs( + client, deactivation_targets, django_assert_num_queries, +): + """ + Each version is measured over an account of its own, so neither pays for the other's work. + + The earlier address answers with the account it deactivated; this one + answers with nothing, which is the difference between the two numbers. + """ + earlier_target, target = deactivation_targets + # The saving is the account the earlier address reads back to answer with, + # so neither number can be changed without the other. + assert DEACTIVATION_QUERIES < EARLIER_DEACTIVATION_QUERIES + + with django_assert_num_queries(EARLIER_DEACTIVATION_QUERIES): + earlier = client.post(f"/api/user/v1/accounts/{earlier_target.username}/deactivate/") + assert earlier.status_code == 200 + earlier_target.refresh_from_db() + assert not earlier_target.has_usable_password() + + with django_assert_num_queries(DEACTIVATION_QUERIES): + later = client.post( + reverse("user_v2:account_deactivation", kwargs={"username": target.username}), + ) + assert later.status_code == 204 + target.refresh_from_db() + assert not target.has_usable_password() diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py new file mode 100644 index 000000000000..4f89185ca2f9 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -0,0 +1,2579 @@ +"""Tests for the version 2 User API account views.""" + +import datetime +import json +from unittest import mock +from urllib.parse import parse_qs, urlparse + +from django.conf import settings +from django.contrib.auth.models import User # pylint: disable=imported-auth-user +from django.db import DatabaseError, connection +from django.test.utils import CaptureQueriesContext, override_settings +from django.urls import reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from rest_framework import status +from rest_framework.test import APITestCase +from waffle.testutils import override_switch + +from common.djangoapps.student.models import PendingNameChange, UserProfile, get_retired_email_by_email +from common.djangoapps.student.tests.factories import ( + ContentTypeFactory, + PermissionFactory, + SuperuserFactory, + UserFactory, +) +from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user +from openedx.core.djangoapps.site_configuration.tests.test_util import with_site_configuration_context +from openedx.core.djangoapps.user_api.accounts.utils import ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH +from openedx.core.djangoapps.user_api.models import RetirementState, UserRetirementStatus +from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangoapps.user_api.v2.permissions import ACCOUNT_CONTACT_SELECTORS +from openedx.core.djangoapps.user_api.v2.serializers import ACCOUNT_DEFAULT_SORT, AccountQuerySerializer +from openedx.core.djangoapps.user_authn.views.password_reset import PasswordResetFormNoActive +from openedx.core.djangolib.testing.utils import skip_unless_lms + +from .test_schema import name_affirmation_answering +from .test_views import PAGINATION_KEYS, write_queries, write_target + +PASSWORD = "Password1234" + +#: The properties every caller may see, whoever they are. +PUBLIC_FIELDS = {"account_privacy", "profile_image", "username"} + +#: The properties a user sees of their own account, and a staff caller of any. +FULL_FIELDS = set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["admin_fields"]) + +#: The properties a learner sees of an account whose owner shares it with everybody. +SHARED_FIELDS = set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["bulk_shareable_fields"]) + +#: The properties an owner is able to share, and so the only ones another caller +#: may select; the refusal offers them in this order. +SHAREABLE_FIELDS = set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["custom_shareable_fields"]) +SHAREABLE_FIELDS_OFFERED = ", ".join(sorted(SHAREABLE_FIELDS)) + +#: The identifying properties the ``minimal`` preset keeps, and the ones of those +#: another caller may select; the refusal offers them in this order. +MINIMAL_FIELDS = {"username", "email", "name", "profile_image"} +SHAREABLE_MINIMAL_FIELDS_OFFERED = ", ".join(sorted(SHAREABLE_FIELDS & MINIMAL_FIELDS)) + +#: The query parameters each account action reads, in the order its refusal lists them. +LIST_QUERY_PARAMS = "email, fields, format, lms_user_id, ordering, page, page_size, username, view" +MEMBER_QUERY_PARAMS = "fields, format, view" +ACTION_QUERY_PARAMS = "format, page, page_size" + +#: A deactivation carries no page, so it reads only the representation parameter. +DEACTIVATION_QUERY_PARAMS = "format" + +MERGE_PATCH = "application/merge-patch+json" + +#: Where the classes the platform declares record that they read a request. +DEFAULT_AUTH_RECORDER = "openedx.core.djangolib.default_auth_classes.set_custom_attribute" + +def counting_cache(location): + """ + Return a cache that counts what it is given, under a name of its own. + + The cache the test settings configure discards everything, so a rate limit + never counts past its first request and the path it guards is never + reached. Each test names its own cache, because the counts outlive the + test that made them. + """ + return { + "default": { + "BACKEND": "django.core.cache.backends.locmem.LocMemCache", + "LOCATION": location, + }, + } + + +class AccountApiV2TestCase(APITestCase): + """Fixtures shared by the version 2 account tests.""" + + def setUp(self): + super().setUp() + self.staff = UserFactory.create( + username="staff-caller", email="staff-caller@example.com", password=PASSWORD, is_staff=True, + ) + self.owner = UserFactory.create( + username="owner-caller", email="owner-caller@example.com", password=PASSWORD, + ) + self.other = UserFactory.create( + username="other-caller", email="other-caller@example.com", password=PASSWORD, + ) + self.list_url = reverse("user_v2:account_list") + self.own_url = reverse("user_v2:account_detail", kwargs={"username": "me"}) + + def login(self, user): + """Sign the given user in through the session these views accept.""" + assert self.client.login(username=user.username, password=PASSWORD) + + def detail_url(self, username): + """Return the member address of one account.""" + return reverse("user_v2:account_detail", kwargs={"username": username}) + + def token_headers(self, user): + """Return the request headers that carry a token identifying the given user.""" + return {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(user)}"} + + def usernames_in(self, response): + """Return the usernames carried by a page of accounts.""" + return [row["username"] for row in response.data["results"]] + + def patch(self, address, body, **kwargs): + """Send a merge patch, the only body these views read.""" + return self.client.patch(address, body, content_type=MERGE_PATCH, **kwargs) + + +@skip_unless_lms +class AccountListViewTests(AccountApiV2TestCase): + """GET /api/user/v2/accounts/""" + + def test_a_caller_with_no_selector_receives_their_own_account(self): + self.login(self.owner) + response = self.client.get(self.list_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == 1 + assert self.usernames_in(response) == ["owner-caller"] + assert set(response.data["results"][0]) == FULL_FIELDS + + def test_the_page_carries_the_whole_envelope(self): + self.login(self.staff) + response = self.client.get(self.list_url) + assert set(response.data) == PAGINATION_KEYS + assert response.data["count"] == 1 + assert response.data["num_pages"] == 1 + assert response.data["current_page"] == 1 + assert response.data["start"] == 0 + assert response.data["next"] is None + assert response.data["previous"] is None + + def test_named_accounts_come_back_in_one_page(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"username": "other-caller,owner-caller"}) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["other-caller", "owner-caller"] + + def test_the_page_is_ordered_by_username_and_the_order_can_be_reversed(self): + self.login(self.staff) + selection = {"username": "owner-caller,other-caller,staff-caller"} + ascending = self.client.get(self.list_url, selection) + assert self.usernames_in(ascending) == ["other-caller", "owner-caller", "staff-caller"] + + descending = self.client.get(self.list_url, {**selection, "ordering": "-username"}) + assert self.usernames_in(descending) == ["staff-caller", "owner-caller", "other-caller"] + + def test_the_page_is_sorted_by_username_when_no_order_is_asked_for(self): + """The order the parameter publishes as its default is the one a page comes back in.""" + self.login(self.staff) + selection = {"username": "owner-caller,other-caller,staff-caller"} + omitted = self.client.get(self.list_url, selection) + named = self.client.get(self.list_url, {**selection, "ordering": ACCOUNT_DEFAULT_SORT}) + blank = self.client.get(self.list_url, {**selection, "ordering": ""}) + assert self.usernames_in(omitted) == ["other-caller", "owner-caller", "staff-caller"] + assert self.usernames_in(named) == self.usernames_in(omitted) + assert self.usernames_in(blank) == self.usernames_in(omitted) + + def test_a_property_the_list_does_not_sort_by_is_refused(self): + """ + A sort the list does not offer is refused rather than quietly applied. + + Any other column of the user table would otherwise order the page, so + a caller who may read nothing but usernames could read the order of a + column they may not be answered with. + """ + self.login(self.staff) + for asked in ("bogus", "password", "date_joined", "-date_joined", "username,-username"): + with self.subTest(ordering=asked): + response = self.client.get( + self.list_url, {"username": "owner-caller,other-caller", "ordering": asked}, + ) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "ordering": ["Sort by any of: username, each optionally prefixed with '-'."], + } + assert "results" not in envelope + + def test_a_name_sent_with_spaces_around_it_names_the_same_account_throughout(self): + """ + The name is read the same way when the answer is shaped and when the page is cut. + + What a caller may select depends on whose accounts the page carries, + and spaces around the name they sent do not make their own account + somebody else's for that purpose. + """ + self.login(self.owner) + for asked in ("owner-caller", " owner-caller", "owner-caller "): + with self.subTest(username=asked): + response = self.client.get(self.list_url, {"username": asked, "fields": "email"}) + assert response.status_code == status.HTTP_200_OK, response.content + assert response.data["results"] == [{"email": "owner-caller@example.com"}] + + def test_a_name_no_account_holds_is_left_out_rather_than_refused(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"username": "owner-caller,nobody"}) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["owner-caller"] + + def test_a_selector_that_names_no_account_answers_an_empty_page(self): + """A collection that matched nothing is an empty page, not an absent collection.""" + self.login(self.staff) + response = self.client.get(self.list_url, {"username": "nobody"}) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PAGINATION_KEYS + assert response.data["count"] == 0 + assert response.data["results"] == [] + assert response.data["num_pages"] == 1 + assert response.data["next"] is None + assert response.data["previous"] is None + + def test_an_empty_page_reads_no_account(self): + """Nothing was selected, so no account is read to fill the page.""" + self.login(self.owner) + with CaptureQueriesContext(connection) as captured: + response = self.client.get(self.list_url, {"username": "nobody"}) + assert response.data["results"] == [] + assert [query for query in captured.captured_queries if "auth_userprofile" in query["sql"]] == [] + + def test_a_learner_sees_only_the_shared_properties_of_another_account(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"username": "other-caller"}) + assert response.status_code == status.HTTP_200_OK + assert set(response.data["results"][0]) == PUBLIC_FIELDS + assert response.data["results"][0]["username"] == "other-caller" + + def test_a_staff_caller_sees_every_property_of_another_account(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"username": "other-caller"}) + assert set(response.data["results"][0]) == FULL_FIELDS + assert response.data["results"][0]["email"] == "other-caller@example.com" + + def test_a_page_mixing_the_caller_and_others_shapes_each_row_for_its_own_owner(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"username": "owner-caller,other-caller"}) + rows = {row["username"]: set(row) for row in response.data["results"]} + assert rows == {"other-caller": PUBLIC_FIELDS, "owner-caller": FULL_FIELDS} + + def test_the_shared_preset_narrows_the_callers_own_account(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"view": "shared"}) + assert set(response.data["results"][0]) == PUBLIC_FIELDS + + def test_the_minimal_preset_keeps_the_identifying_properties(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"view": "minimal"}) + assert set(response.data["results"][0]) == {"username", "email", "name", "profile_image"} + + def test_the_minimal_preset_cannot_hand_out_a_property_the_caller_may_not_see(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"username": "other-caller", "view": "minimal"}) + assert set(response.data["results"][0]) == {"username", "profile_image"} + + def test_a_learner_selecting_an_identifying_property_they_may_not_see_is_refused(self): + """The preset keeps the identifying properties; this caller may be answered with some of them.""" + self.login(self.owner) + response = self.client.get( + self.list_url, {"username": "other-caller", "view": "minimal", "fields": "email"}, + ) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"] == [ + f"No such field: email. Select any of: {SHAREABLE_MINIMAL_FIELDS_OFFERED}.", + ] + + def test_a_caller_selects_an_identifying_property_of_their_own_account(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"view": "minimal", "fields": "email"}) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [{"email": "owner-caller@example.com"}] + + def test_selected_fields_narrow_each_row(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"fields": "username,email"}) + assert response.data["results"] == [ + {"username": "owner-caller", "email": "owner-caller@example.com"}, + ] + + def test_a_field_the_response_cannot_carry_is_refused(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"fields": "username,wallet"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"][0].startswith("No such field: wallet.") + + def test_a_learner_selecting_a_property_of_another_account_they_may_not_see_is_refused(self): + """A property this caller's page cannot carry is refused, not answered as an empty object.""" + self.login(self.owner) + response = self.client.get(self.list_url, {"username": "other-caller", "fields": "email"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"] == [ + f"No such field: email. Select any of: {SHAREABLE_FIELDS_OFFERED}.", + ] + + def test_a_learner_selecting_a_property_this_owner_does_not_share_receives_the_rest(self): + """ + A property an owner is able to share can be selected; whether they share it is their own choice. + + This owner shares nothing beyond the properties every caller may see, + so the row carries the rest of the selection rather than the property + asked for. + """ + self.login(self.owner) + response = self.client.get(self.list_url, {"username": "other-caller", "fields": "bio,username"}) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [{"username": "other-caller"}] + + def test_a_staff_caller_still_selects_a_property_only_they_may_see(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"username": "other-caller", "fields": "email"}) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [{"email": "other-caller@example.com"}] + + def test_a_caller_still_selects_a_property_only_they_may_see_of_their_own_account(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"username": "owner-caller", "fields": "email"}) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [{"email": "owner-caller@example.com"}] + + def test_a_property_the_shared_preset_leaves_out_is_refused_with_the_preset_asked_for(self): + """``shared`` answers with what the owner shares, so only those properties can be selected.""" + self.login(self.staff) + response = self.client.get( + self.list_url, {"username": "other-caller", "view": "shared", "fields": "email"}, + ) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"] == [ + f"No such field: email. Select any of: {SHAREABLE_FIELDS_OFFERED}.", + ] + + def test_a_preset_the_endpoint_does_not_offer_is_refused(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"view": "everything"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "view": ["Ask for any of: minimal, shared, or omit this parameter for the default response."], + } + + def test_a_query_parameter_the_endpoint_does_not_read_is_refused(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"usernames": "owner-caller"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "usernames": [f"No such query parameter. Send any of: {LIST_QUERY_PARAMS}."], + } + + def test_a_page_that_does_not_exist_is_not_found(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"page": 7}) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_the_collection_is_split_into_pages(self): + self.login(self.staff) + selection = {"username": "owner-caller,other-caller,staff-caller", "page_size": 2} + first = self.client.get(self.list_url, selection) + assert first.data["count"] == 3 + assert first.data["num_pages"] == 2 + assert self.usernames_in(first) == ["other-caller", "owner-caller"] + assert "page=2" in first.data["next"] + + second = self.client.get(self.list_url, {**selection, "page": 2}) + assert self.usernames_in(second) == ["staff-caller"] + assert second.data["start"] == 2 + + def test_an_anonymous_caller_is_unauthenticated(self): + response = self.client.get(self.list_url) + assert_error_envelope( + response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + +@skip_unless_lms +class AccountListSelectorTests(AccountApiV2TestCase): + """The selectors of GET /api/user/v2/accounts/ that only staff may use.""" + + def test_a_staff_caller_selects_an_account_by_email_address(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"email": "other-caller@example.com"}) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["other-caller"] + + def test_a_staff_caller_selects_an_account_by_identifier(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"lms_user_id": self.other.id}) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["other-caller"] + + def test_the_selectors_a_learner_may_not_use_are_the_ones_the_privilege_is_asked_for(self): + """Every selector the list documents as staff-only is one the permission classes gate.""" + documented = { + name for name, field in AccountQuerySerializer().fields.items() + if "Only staff" in (field.help_text or "") + } + assert documented == {"email", "lms_user_id"} + assert set(ACCOUNT_CONTACT_SELECTORS) == documented + + def test_a_learner_may_not_select_by_email_address(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"email": "other-caller@example.com"}) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_a_learner_may_not_select_by_identifier(self): + self.login(self.owner) + response = self.client.get(self.list_url, {"lms_user_id": self.other.id}) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_a_learner_may_not_select_their_own_account_by_email_address_either(self): + """The selector is the staff-only part, whoever the account it names belongs to.""" + self.login(self.owner) + response = self.client.get(self.list_url, {"email": "owner-caller@example.com"}) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_every_selector_that_finds_no_account_answers_the_same_empty_page(self): + """ + A selection no account matches is an empty page, whichever selector was given. + + A caller filtering this collection reads one answer for a selection + that matched nothing, instead of having to tell an empty page from a + refusal by which parameter it sent. + """ + self.login(self.staff) + selections = ( + {"username": "nobody"}, + {"email": "nobody@example.com"}, + {"lms_user_id": 999999}, + ) + for selection in selections: + with self.subTest(**selection): + response = self.client.get(self.list_url, selection) + assert response.status_code == status.HTTP_200_OK, response.content + assert set(response.data) == PAGINATION_KEYS + assert response.data["count"] == 0 + assert response.data["results"] == [] + assert response.data["next"] is None + + def test_an_identifier_that_is_not_a_number_is_refused(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"lms_user_id": "nope"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"lms_user_id": ["A valid integer is required."]} + + def test_an_address_that_is_not_an_email_address_is_refused(self): + self.login(self.staff) + response = self.client.get(self.list_url, {"email": "not-an-address"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"email": ["Enter a valid email address."]} + + def test_names_are_read_before_the_other_selectors(self): + self.login(self.staff) + response = self.client.get( + self.list_url, {"username": "owner-caller", "email": "other-caller@example.com"}, + ) + assert self.usernames_in(response) == ["owner-caller"] + + +@skip_unless_lms +class RetiredAccountTests(AccountApiV2TestCase): + """An email address an account held before it was retired.""" + + def setUp(self): + super().setUp() + self.login(self.staff) + self.retired_email = self.other.email + + def retire(self): + """Replace the account's address with its retired form, as retirement does.""" + self.other.email = get_retired_email_by_email(self.retired_email) + self.other.save() + + def test_the_address_of_a_retired_account_is_not_found(self): + self.retire() + response = self.client.get(self.list_url, {"email": self.retired_email}) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="user/retired-account", + ) + assert envelope["title"] == "Retired Account" + assert envelope["can_cancel_retirement"] is False + assert envelope["retirement_id"] is None + + def test_reading_the_address_of_a_retired_account_writes_nothing(self): + """The record the refusal names is read, and the refusal leaves it as it was.""" + RetirementState.objects.create(state_name="PENDING", state_execution_order=1) + UserRetirementStatus.create_retirement(self.other) + self.retire() + with CaptureQueriesContext(connection) as captured: + with self.captureOnCommitCallbacks(execute=True): + response = self.client.get(self.list_url, {"email": self.retired_email}) + assert response.status_code == status.HTTP_404_NOT_FOUND + assert write_queries(captured.captured_queries) == [] + + def test_a_retirement_still_inside_the_cooling_off_period_can_be_cancelled(self): + RetirementState.objects.create(state_name="PENDING", state_execution_order=1) + retirement = UserRetirementStatus.create_retirement(self.other) + self.retire() + response = self.client.get(self.list_url, {"email": self.retired_email}) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="user/retired-account", + ) + assert envelope["can_cancel_retirement"] is True + assert envelope["retirement_id"] == retirement.id + + def test_a_retirement_older_than_the_cooling_off_period_can_no_longer_be_cancelled(self): + RetirementState.objects.create(state_name="PENDING", state_execution_order=1) + retirement = UserRetirementStatus.create_retirement(self.other) + long_ago = datetime.datetime.now(datetime.UTC) - datetime.timedelta( + days=settings.COOL_OFF_DAYS + 1, + ) + UserRetirementStatus.objects.filter(pk=retirement.pk).update(created=long_ago) + self.retire() + envelope = assert_error_envelope( + self.client.get(self.list_url, {"email": self.retired_email}), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="user/retired-account", + ) + assert envelope["can_cancel_retirement"] is False + assert envelope["retirement_id"] is None + + +@skip_unless_lms +class AccountDetailViewTests(AccountApiV2TestCase): + """GET /api/user/v2/accounts/{username}/ and its ``me`` form.""" + + def test_a_caller_reads_their_own_account_through_the_reserved_identifier(self): + self.login(self.owner) + response = self.client.get(self.own_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["username"] == "owner-caller" + assert set(response.data) == FULL_FIELDS + + def test_the_reserved_identifier_names_the_caller_and_not_the_account_holding_it(self): + """``me`` addresses the caller, so an account holding that name is read through the list.""" + UserFactory.create(username="me", email="me@example.com", password=PASSWORD) + self.login(self.staff) + assert self.client.get(self.own_url).data["username"] == "staff-caller" + + named = self.client.get(self.list_url, {"username": "me"}) + assert named.status_code == status.HTTP_200_OK + assert self.usernames_in(named) == ["me"] + assert named.data["results"][0]["email"] == "me@example.com" + + def test_an_account_named_after_another_collection_is_served_at_its_own_address(self): + """ + A username is whatever its owner registered, and the collections beside this one take none away. + + ``email_searches`` is a name a user may hold, so the member address + carrying it belongs to that account: its owner reads and changes it + there, a staff caller reads it there, and another learner is answered + the properties that account shares rather than told it is absent. + """ + held = UserFactory.create( + username="email_searches", email="email-searches@example.com", password=PASSWORD, + ) + address = self.detail_url("email_searches") + + self.login(held) + own = self.client.get(address) + assert own.status_code == status.HTTP_200_OK + assert own.data["username"] == "email_searches" + assert own.data["email"] == "email-searches@example.com" + changed = self.patch(address, json.dumps({"bio": "named for a search"})) + assert changed.status_code == status.HTTP_200_OK + assert changed.data["bio"] == "named for a search" + self.client.logout() + + self.login(self.staff) + by_staff = self.client.get(address) + assert by_staff.status_code == status.HTTP_200_OK + assert by_staff.data["username"] == "email_searches" + named = self.client.get(self.list_url, {"username": "email_searches"}) + assert self.usernames_in(named) == ["email_searches"] + assert named.data["results"][0]["email"] == "email-searches@example.com" + self.client.logout() + + self.login(self.other) + by_a_learner = self.client.get(address) + assert by_a_learner.status_code == status.HTTP_200_OK + assert set(by_a_learner.data) == PUBLIC_FIELDS + assert by_a_learner.data["username"] == "email_searches" + + def test_a_member_address_spelled_in_another_case_carries_the_account_it_names(self): + """ + A database that holds usernames case-insensitively answers an address spelled differently. + + Whether two names differing only in case name one account is the + database's decision, and the collation MySQL applies to these columns + by default says they do, so an account can come back stored under a + spelling other than the one the address carried. The test database + compares the names exactly, so the account service is answered here as + a database holding them case-insensitively answers it. + """ + def stored_under_another_spelling(request, usernames=None, **kwargs): # pylint: disable=unused-argument + assert usernames == ["Owner-Caller"] + return [{"username": "owner-caller", "email": "owner-caller@example.com"}] + + self.login(self.staff) + with mock.patch( + "openedx.core.djangoapps.user_api.v2.views.get_account_settings", + stored_under_another_spelling, + ): + response = self.client.get(self.detail_url("Owner-Caller")) + assert response.status_code == status.HTTP_200_OK + assert response.data == {"username": "owner-caller", "email": "owner-caller@example.com"} + + def test_a_caller_reads_their_own_account_by_name(self): + self.login(self.owner) + response = self.client.get(self.detail_url("owner-caller")) + assert set(response.data) == FULL_FIELDS + assert response.data["email"] == "owner-caller@example.com" + + def test_a_learner_sees_only_the_shared_properties_of_another_account(self): + self.login(self.owner) + response = self.client.get(self.detail_url("other-caller")) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PUBLIC_FIELDS + + def test_a_staff_caller_sees_every_property_of_another_account(self): + self.login(self.staff) + response = self.client.get(self.detail_url("owner-caller")) + assert set(response.data) == FULL_FIELDS + assert response.data["email"] == "owner-caller@example.com" + + def test_the_shared_preset_narrows_the_callers_own_account(self): + self.login(self.owner) + response = self.client.get(self.detail_url("owner-caller"), {"view": "shared"}) + assert set(response.data) == PUBLIC_FIELDS + + def test_the_minimal_preset_keeps_the_identifying_properties(self): + self.login(self.owner) + response = self.client.get(self.own_url, {"view": "minimal"}) + assert set(response.data) == {"username", "email", "name", "profile_image"} + + def test_the_empty_preset_narrows_nothing_at_any_address_that_takes_one(self): + """ + A query string built from an empty variable carries a preset with no + value, which is answered with everything the caller may see. + """ + self.login(self.owner) + assert set(self.client.get(self.own_url, {"view": ""}).data) == FULL_FIELDS + assert set(self.client.get(self.list_url, {"view": ""}).data["results"][0]) == FULL_FIELDS + changed = self.patch(self.own_url, json.dumps({"bio": "unnarrowed"}), QUERY_STRING="view=") + assert changed.status_code == status.HTTP_200_OK + assert set(changed.data) == FULL_FIELDS + + def test_a_learner_selecting_an_identifying_property_they_may_not_see_is_refused(self): + """The preset keeps the identifying properties; this caller may be answered with some of them.""" + self.login(self.owner) + response = self.client.get( + self.detail_url("other-caller"), {"view": "minimal", "fields": "email"}, + ) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"] == [ + f"No such field: email. Select any of: {SHAREABLE_MINIMAL_FIELDS_OFFERED}.", + ] + + def test_selected_fields_narrow_the_account(self): + self.login(self.owner) + response = self.client.get(self.own_url, {"fields": "username,email"}) + assert response.data == {"username": "owner-caller", "email": "owner-caller@example.com"} + + def test_a_learner_selecting_a_property_of_another_account_they_may_not_see_is_refused(self): + """A property this caller's response cannot carry is refused, not answered as an empty object.""" + self.login(self.owner) + response = self.client.get(self.detail_url("other-caller"), {"fields": "email"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"] == [ + f"No such field: email. Select any of: {SHAREABLE_FIELDS_OFFERED}.", + ] + + def test_a_learner_selecting_a_property_this_owner_does_not_share_receives_the_rest(self): + """ + A property an owner is able to share can be selected; whether they share it is their own choice. + + This owner shares nothing beyond the properties every caller may see, + so the account carries the rest of the selection rather than the + property asked for. + """ + self.login(self.owner) + response = self.client.get(self.detail_url("other-caller"), {"fields": "bio,username"}) + assert response.status_code == status.HTTP_200_OK + assert response.data == {"username": "other-caller"} + + def test_a_staff_caller_still_selects_a_property_only_they_may_see(self): + self.login(self.staff) + response = self.client.get(self.detail_url("other-caller"), {"fields": "email"}) + assert response.data == {"email": "other-caller@example.com"} + + def test_the_reserved_identifier_selects_the_properties_of_the_callers_own_account(self): + self.login(self.owner) + response = self.client.get(self.own_url, {"fields": "email"}) + assert response.data == {"email": "owner-caller@example.com"} + + def test_a_name_no_account_holds_is_not_found(self): + self.login(self.staff) + response = self.client.get(self.detail_url("nobody")) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_an_anonymous_caller_is_unauthenticated(self): + response = self.client.get(self.detail_url("owner-caller")) + assert_error_envelope( + response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + def test_a_selector_of_the_list_is_not_a_parameter_of_a_member(self): + self.login(self.staff) + response = self.client.get(self.detail_url("owner-caller"), {"ordering": "username"}) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "ordering": [f"No such query parameter. Send any of: {MEMBER_QUERY_PARAMS}."], + } + + def test_a_member_carries_no_page_so_the_parameters_that_cut_one_are_refused(self): + """ + One account is not a page of them, and a parameter that cuts a page is refused here. + + A caller that mistyped a parameter of the collection and sent it to a + member would otherwise be answered the whole account as though the + parameter had been read. + """ + self.login(self.owner) + for address in (self.own_url, self.detail_url("owner-caller")): + envelope = assert_error_envelope( + self.client.get(address, {"page": 9, "page_size": 3}), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "page": [f"No such query parameter. Send any of: {MEMBER_QUERY_PARAMS}."], + "page_size": [f"No such query parameter. Send any of: {MEMBER_QUERY_PARAMS}."], + } + + def test_a_change_carries_no_page_either(self): + """A change answers with the one account it changed, so it reads no page parameter.""" + self.login(self.owner) + envelope = assert_error_envelope( + self.patch(f"{self.own_url}?page=2", json.dumps({"bio": "paged"})), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "page": [f"No such query parameter. Send any of: {MEMBER_QUERY_PARAMS}."], + } + self.owner.profile.refresh_from_db() + assert self.owner.profile.bio is None + + +@skip_unless_lms +class UnconfirmedAccountTests(AccountApiV2TestCase): + """ + A user who has not confirmed their email address still reaches their own account. + + The site sends them to account settings to change the address, so the + session class these views accept is the one that admits them. + """ + + def setUp(self): + super().setUp() + self.owner.is_active = False + self.owner.save() + + def test_an_unconfirmed_account_is_readable_by_its_owner(self): + self.login(self.owner) + response = self.client.get(self.own_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["username"] == "owner-caller" + assert response.data["is_active"] is False + + def test_an_unconfirmed_account_is_changeable_by_its_owner(self): + self.login(self.owner) + response = self.patch(self.own_url, json.dumps({"bio": "still unconfirmed"})) + assert response.status_code == status.HTTP_200_OK + assert response.data["bio"] == "still unconfirmed" + + def test_a_token_held_by_a_disabled_staff_account_may_not_select_accounts_by_contact(self): + """A privilege does not survive the deactivation of the account that held it.""" + headers = self.token_headers(self.staff) + for query in ({"email": "other-caller@example.com"}, {"lms_user_id": self.other.id}): + assert self.client.get(self.list_url, query, **headers).status_code == status.HTTP_200_OK + self.staff.is_active = False + self.staff.save() + for query in ({"email": "other-caller@example.com"}, {"lms_user_id": self.other.id}): + assert_error_envelope( + self.client.get(self.list_url, query, **headers), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_disabled_staff_account_still_reads_the_accounts_it_names(self): + """Naming an account is not the privilege a disabled account loses.""" + self.staff.is_active = False + self.staff.save() + headers = self.token_headers(self.staff) + page = self.client.get(self.list_url, {"username": "other-caller"}, **headers) + assert page.status_code == status.HTTP_200_OK + assert self.usernames_in(page) == ["other-caller"] + + def test_a_token_is_read_by_the_class_the_platform_declares(self): + """ + Only the session class is replaced here, so a token is read by the platform's own. + + That class records every request it reads a token for, which is how an + operator finds the addresses that authenticate the way the platform + declares rather than by a list of their own. + """ + with mock.patch(DEFAULT_AUTH_RECORDER) as recorded: + answer = self.client.get(self.detail_url("other-caller"), **self.token_headers(self.other)) + assert answer.status_code == status.HTTP_200_OK + assert [call.args for call in recorded.call_args_list] == [("using_default_auth_classes", True)] + + def test_an_unconfirmed_account_still_may_not_search_for_others(self): + self.staff.is_active = False + self.staff.save() + response = self.client.post( + reverse("user_v2:email_search_list"), + {"emails": ["other-caller@example.com"]}, + format="json", + **self.token_headers(self.staff), + ) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + +@skip_unless_lms +class AccountChangeTests(AccountApiV2TestCase): + """PATCH /api/user/v2/accounts/{username}/""" + + def test_an_owner_changes_their_own_account(self): + self.login(self.owner) + response = self.patch(self.detail_url("owner-caller"), json.dumps({"bio": "a new bio"})) + assert response.status_code == status.HTTP_200_OK + assert response.data["bio"] == "a new bio" + self.owner.profile.refresh_from_db() + assert self.owner.profile.bio == "a new bio" + + def test_the_reserved_identifier_changes_the_callers_own_account(self): + self.login(self.owner) + response = self.patch(self.own_url, json.dumps({"goals": "learn everything"})) + assert response.status_code == status.HTTP_200_OK + assert response.data["goals"] == "learn everything" + + def test_every_level_of_education_a_profile_stores_is_taken_as_it_is_sent(self): + """The codes are not all one letter, and each is stored as the caller sent it.""" + self.login(self.owner) + offered = [code for code, _label in UserProfile.LEVEL_OF_EDUCATION_CHOICES] + assert offered == ["p", "m", "b", "a", "hs", "jhs", "el", "none", "other"] + for code in offered: + with self.subTest(level_of_education=code): + response = self.patch(self.own_url, json.dumps({"level_of_education": code})) + assert response.status_code == status.HTTP_200_OK, response.content + assert response.data["level_of_education"] == code + self.owner.profile.refresh_from_db() + assert self.owner.profile.level_of_education == code + + def test_the_changed_account_is_shaped_like_a_read_of_it(self): + self.login(self.owner) + response = self.patch(self.own_url, json.dumps({"bio": "x"}), QUERY_STRING="view=minimal") + assert set(response.data) == {"username", "email", "name", "profile_image"} + + def test_the_shared_preset_narrows_the_changed_account_as_it_narrows_a_read_of_it(self): + """ + The preset asked for shapes what a change answers with, as it shapes what a read answers with. + + A caller asking for the shared form of their account after changing it + is answered the properties their account shares with everybody, not + the ones only they may see. + """ + self.login(self.owner) + response = self.patch( + self.own_url, json.dumps({"bio": "shared bio"}), QUERY_STRING="view=shared", + ) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PUBLIC_FIELDS + assert response.data["username"] == "owner-caller" + read = self.client.get(self.own_url, {"view": "shared"}) + assert set(read.data) == set(response.data) + + self.owner.profile.refresh_from_db() + assert self.owner.profile.bio == "shared bio" + assert self.client.get(self.own_url).data["bio"] == "shared bio" + + def test_a_property_the_shared_preset_leaves_out_cannot_be_selected_from_a_change(self): + self.login(self.owner) + response = self.patch( + self.own_url, json.dumps({"bio": "x"}), QUERY_STRING="view=shared&fields=email", + ) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"] == [ + f"No such field: email. Select any of: {SHAREABLE_FIELDS_OFFERED}.", + ] + self.owner.profile.refresh_from_db() + assert self.owner.profile.bio is None + + def test_a_learner_may_not_change_another_account(self): + self.login(self.owner) + response = self.patch(self.detail_url("other-caller"), json.dumps({"bio": "not mine"})) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + self.other.profile.refresh_from_db() + assert self.other.profile.bio is None + + def test_a_staff_caller_may_not_change_another_account_either(self): + """Reading somebody else's account is a staff privilege; changing it is nobody's.""" + self.login(self.staff) + response = self.patch(self.detail_url("owner-caller"), json.dumps({"bio": "not mine"})) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_a_name_no_account_holds_is_refused_before_it_is_looked_up(self): + """Only the caller's own account can be changed, so no other name is reached.""" + self.login(self.owner) + response = self.patch(self.detail_url("nobody"), json.dumps({"bio": "x"})) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_an_anonymous_caller_is_unauthenticated(self): + response = self.patch(self.detail_url("owner-caller"), json.dumps({"bio": "x"})) + assert_error_envelope( + response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + def test_a_body_in_another_media_type_is_refused(self): + self.login(self.owner) + response = self.client.patch( + self.detail_url("owner-caller"), json.dumps({"bio": "x"}), content_type="application/json", + ) + assert_error_envelope( + response, + expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, + expected_type_slug="unsupported-media-type", + ) + + def test_a_body_that_is_not_well_formed_is_refused_as_the_callers_fault(self): + self.login(self.owner) + response = self.client.patch(self.own_url, "{not json", content_type=MERGE_PATCH) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="malformed-body", + ) + assert envelope["title"] == "Malformed Request Body" + + def test_a_body_that_is_not_an_object_is_refused(self): + self.login(self.owner) + response = self.patch(self.detail_url("owner-caller"), json.dumps(["bio"])) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "non_field_errors": ["Send the properties to change as an object."], + } + + def test_a_value_the_property_cannot_take_is_refused_with_the_property_named(self): + self.login(self.owner) + response = self.patch(self.own_url, json.dumps({"year_of_birth": "recently"})) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"year_of_birth": ["A valid integer is required."]} + + def test_a_value_of_the_right_type_the_account_will_not_hold_is_refused_by_the_account(self): + """ + What a property may hold is still settled where the change is carried out. + + The body is measured against the published shape first, and that is + about types and nothing else: a value of the right type that this + property cannot hold comes back refused in the account's own words. + """ + self.login(self.owner) + response = self.patch(self.own_url, json.dumps({"country": "Neverland", "bio": "x" * 4000})) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "country": ["This value is invalid."], + "bio": ["The about me field must be at most 300 characters long."], + } + self.owner.profile.refresh_from_db() + assert self.owner.profile.country is None + assert self.owner.profile.bio is None + + def test_a_property_this_version_does_not_publish_still_reaches_the_account(self): + """ + The body is checked against the published shape and then carried out as it was sent. + + A property the published shape does not carry is left for the account + to deal with, which either changes something by it or ignores it; what + it must not do is disappear here, because the account is where the + properties that may not be changed are refused. + """ + self.login(self.owner) + ignored = self.patch(self.own_url, json.dumps({"time_zone": "Asia/Tokyo"})) + assert ignored.status_code == status.HTTP_200_OK + + refused = self.patch(self.own_url, json.dumps({"is_active": False})) + envelope = assert_error_envelope( + refused, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"is_active": ["The 'is_active' field cannot be edited."]} + self.owner.refresh_from_db() + assert self.owner.is_active is True + + def test_a_property_that_cannot_be_changed_is_refused_with_the_property_named(self): + self.login(self.owner) + response = self.patch(self.own_url, json.dumps({"username": "renamed"})) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"username": ["The 'username' field cannot be edited."]} + self.owner.refresh_from_db() + assert self.owner.username == "owner-caller" + + def test_no_change_is_kept_when_one_property_of_the_body_is_refused(self): + self.login(self.owner) + response = self.patch( + self.own_url, json.dumps({"bio": "kept?", "year_of_birth": "recently"}), + ) + assert response.status_code == status.HTTP_400_BAD_REQUEST + self.owner.profile.refresh_from_db() + assert self.owner.profile.bio is None + + @override_settings(EMAIL_CHANGE_RATE_LIMIT="1/d", CACHES=counting_cache("email-change-refused")) + def test_changing_an_email_address_too_often_is_refused(self): + self.login(self.owner) + first = self.patch(self.own_url, json.dumps({"email": "owner-first@example.com"})) + assert first.status_code == status.HTTP_200_OK + + second = self.patch(self.own_url, json.dumps({"email": "owner-second@example.com"})) + envelope = assert_error_envelope( + second, expected_status=status.HTTP_429_TOO_MANY_REQUESTS, expected_type_slug="rate-limited", + ) + assert envelope["detail"] == "Wait before changing email again." + + @override_settings(EMAIL_CHANGE_RATE_LIMIT="1/d", CACHES=counting_cache("email-change-allowed")) + def test_the_rate_limit_leaves_a_change_of_another_property_alone(self): + self.login(self.owner) + assert self.patch(self.own_url, json.dumps({"email": "owner-first@example.com"})).status_code == ( + status.HTTP_200_OK + ) + later = self.patch(self.own_url, json.dumps({"bio": "unrelated"})) + assert later.status_code == status.HTTP_200_OK + assert later.data["bio"] == "unrelated" + + def test_a_property_the_body_cannot_carry_a_null_for_is_cleared_with_an_empty_text(self): + """Neither property takes a null, so the change that empties each one is pinned here.""" + self.login(self.owner) + assert self.patch( + self.own_url, json.dumps({"bio": "a bio", "phone_number": "+15550000"}), + ).status_code == status.HTTP_200_OK + + cleared = self.patch(self.own_url, json.dumps({"bio": "", "phone_number": ""})) + assert cleared.status_code == status.HTTP_200_OK + assert cleared.data["bio"] is None + assert cleared.data["phone_number"] is None + + def test_an_email_change_waits_for_the_owner_to_confirm_it(self): + self.login(self.owner) + response = self.patch(self.own_url, json.dumps({"email": "owner-new@example.com"})) + assert response.status_code == status.HTTP_200_OK + self.owner.refresh_from_db() + assert self.owner.email == "owner-caller@example.com" + + +#: Not text, so not a name: the refusals below quote these back. +NOT_TEXT = "Not a valid string." +#: What a property that carries a list of objects says about anything else. +NOT_A_LIST = 'Expected a list of items but got type "{}".' +#: Nothing at all, where the property carries something or is left out. +NOT_SENDABLE_AS_NULL = "This field may not be null." +#: What a property holding an email address says about anything else. +NOT_AN_ADDRESS = "Enter a valid email address." + +#: A property of an account, a value of a type it is not sent as, and what the +#: caller is told. Each pair reached the account service unmeasured before the +#: body was checked against the shape this endpoint publishes, and several were +#: answered as a failure of the server. +WRONGLY_TYPED_CHANGES = ( + ("name", None, NOT_SENDABLE_AS_NULL), + ("name", 5, NOT_TEXT), + ("name", [], NOT_TEXT), + ("name", {}, NOT_TEXT), + ("name", True, NOT_TEXT), + ("bio", None, NOT_SENDABLE_AS_NULL), + ("bio", 5, NOT_TEXT), + ("email", None, NOT_SENDABLE_AS_NULL), + ("email", 5, NOT_AN_ADDRESS), + ("email", True, NOT_AN_ADDRESS), + ("secondary_email", 5, NOT_AN_ADDRESS), + ("country", [], NOT_TEXT), + ("country", {}, NOT_TEXT), + ("phone_number", 5, NOT_TEXT), + ("phone_number", [], NOT_TEXT), + ("phone_number", {}, NOT_TEXT), + ("phone_number", True, NOT_TEXT), + ("year_of_birth", [], "A valid integer is required."), + ("account_privacy", [], NOT_TEXT), + ("social_links", None, NOT_SENDABLE_AS_NULL), +) + + +@skip_unless_lms +class AccountChangeBodyShapeTests(AccountApiV2TestCase): + """ + A change is measured against the shape this endpoint publishes before it is carried out. + + The account service reads a body of its own shape and its helpers assume a + property arrives as the type the document gives it, so a value of another + type used to reach them unmeasured. Here each one is the caller's fault, + named property by property, and the account is left as it was. + """ + + def setUp(self): + super().setUp() + self.owner.profile.bio = "A bio that stays." + self.owner.profile.name = "Owner Caller" + self.owner.profile.country = "GB" + self.owner.profile.phone_number = "+15550000" + self.owner.profile.save() + self.login(self.owner) + + def stored(self): + """Return the stored values of the properties these bodies try to change.""" + self.owner.refresh_from_db() + self.owner.profile.refresh_from_db() + return { + "email": self.owner.email, + "name": self.owner.profile.name, + "bio": self.owner.profile.bio, + "country": self.owner.profile.country.code, + "phone_number": self.owner.profile.phone_number, + } + + def test_a_property_sent_as_another_type_is_refused_with_the_property_named(self): + """Each pair is answered 400, naming the property and what it will not take.""" + before = self.stored() + for name, value, reason in WRONGLY_TYPED_CHANGES: + with self.subTest(property=name, value=value): + response = self.patch(self.own_url, json.dumps({name: value})) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {name: [reason]} + assert self.stored() == before + + def test_a_null_for_a_property_the_body_publishes_no_null_for_is_refused(self): + """``bio`` and ``name`` carry text and no null, and each says so rather than failing.""" + for name in ("bio", "name"): + with self.subTest(property=name): + response = self.patch(self.own_url, json.dumps({name: None})) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {name: ["This field may not be null."]} + assert self.stored()["bio"] == "A bio that stays." + assert self.stored()["name"] == "Owner Caller" + + def test_a_number_is_not_read_as_the_digits_that_spell_it(self): + """A property that carries text takes text, and the account keeps the text it had.""" + response = self.patch(self.own_url, json.dumps({"bio": 5})) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"bio": ["Not a valid string."]} + assert self.stored()["bio"] == "A bio that stays." + + def test_a_property_that_carries_a_list_is_refused_when_it_is_not_one(self): + """ + The refusal names the property and says a list is what belongs there. + + It is quoted rather than matched whole because the envelope carries one + line of text per property, and a refusal that came from inside a list + is written into that line as it stood. + """ + for name, sent, kind in ( + ("language_proficiencies", 5, "int"), + ("extended_profile", {}, "dict"), + ("social_links", "https://www.facebook.com/owner", "str"), + ): + with self.subTest(property=name): + response = self.patch(self.own_url, json.dumps({name: sent})) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert list(envelope["errors"]) == [name] + assert NOT_A_LIST.format(kind) in envelope["errors"][name][0] + + def test_an_incomplete_object_inside_the_body_is_refused(self): + """A property that is an object of its own is sent whole, not a part at a time.""" + response = self.patch( + self.own_url, json.dumps({"social_links": [{"platform": "facebook"}]}), + ) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + # The envelope carries one line per property, so a refusal from inside a + # list arrives as the text of the refusal rather than as its own object. + assert list(envelope["errors"]) == ["social_links"] + assert "social_link" in envelope["errors"]["social_links"][0] + assert "This field is required." in envelope["errors"]["social_links"][0] + assert self.owner.profile.social_links.count() == 0 + + def test_an_empty_address_still_drops_a_platform(self): + """The body publishes an empty address as the way to drop a link, and it is taken.""" + assert self.patch( + self.own_url, + json.dumps({"social_links": [{"platform": "facebook", "social_link": "https://www.facebook.com/owner"}]}), + ).status_code == status.HTTP_200_OK + assert self.owner.profile.social_links.count() == 1 + + dropped = self.patch( + self.own_url, json.dumps({"social_links": [{"platform": "facebook", "social_link": ""}]}), + ) + assert dropped.status_code == status.HTTP_200_OK + assert dropped.data["social_links"] == [] + assert self.owner.profile.social_links.count() == 0 + + def test_the_change_a_refused_body_asked_for_alongside_is_not_carried_out(self): + """One unusable value refuses the whole body, as one the account rejects does.""" + self.owner.profile.goals = "Finish the course." + self.owner.profile.save() + + response = self.patch(self.own_url, json.dumps({"goals": "learn", "name": 5})) + assert response.status_code == status.HTTP_400_BAD_REQUEST + self.owner.profile.refresh_from_db() + assert self.owner.profile.goals == "Finish the course." + + +@skip_unless_lms +class AccountChangeFailureTests(AccountApiV2TestCase): + """ + A change that was asked for correctly and could not be carried out is this server's fault. + + What is left once the body has been measured and the account has had its + say is the work itself failing, and a caller cannot mend that by sending + something else: it is reported as a failure here, not as an unusable + request. + """ + + def setUp(self): + super().setUp() + self.login(self.owner) + + def test_a_change_that_cannot_be_stored_is_answered_as_this_servers_failure(self): + with mock.patch( + "openedx.core.djangoapps.user_api.accounts.api.AccountLegacyProfileSerializer.save", + side_effect=DatabaseError("the rows would not take it"), + ): + response = self.patch(self.own_url, json.dumps({"bio": "a bio"})) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_500_INTERNAL_SERVER_ERROR, + expected_type_slug="internal", + ) + assert envelope["detail"] == "The change could not be carried out." + self.owner.profile.refresh_from_db() + assert self.owner.profile.bio is None + + def test_a_message_that_cannot_be_sent_is_answered_as_this_servers_failure(self): + """The address is confirmed from a message, so a change of it fails when none can be sent.""" + with mock.patch( + "openedx.core.djangoapps.user_api.accounts.api.student_views.do_email_change_request", + side_effect=ValueError("Unable to send email activation link. Please try again later."), + ): + response = self.patch(self.own_url, json.dumps({"email": "owner-new@example.com"})) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_500_INTERNAL_SERVER_ERROR, + expected_type_slug="internal", + ) + assert envelope["detail"] == "The change could not be carried out." + self.owner.refresh_from_db() + assert self.owner.email == "owner-caller@example.com" + + def test_what_the_failure_says_is_the_same_whatever_went_wrong(self): + """Neither answer carries what the account service said, which names rows and addresses.""" + with mock.patch( + "openedx.core.djangoapps.user_api.accounts.api.AccountLegacyProfileSerializer.save", + side_effect=DatabaseError("relation user_profile does not exist"), + ): + response = self.patch(self.own_url, json.dumps({"bio": "a bio"})) + assert "relation" not in json.dumps(response.data) + assert response.data["title"] == "Internal Server Error" + + @override_settings(ALLOW_EMAIL_ADDRESS_CHANGE=False) + def test_a_site_that_does_not_change_addresses_here_says_so_about_the_address(self): + """ + The refusal names ``email``, so a form can show it where the caller typed. + + A site that does not take an address change through this endpoint is + not a failure of the request and not a failure of the server; it is the + one property this endpoint will not change, and it is reported as that. + """ + response = self.patch(self.own_url, json.dumps({"email": "owner-new@example.com"})) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "email": ["This site does not let an email address be changed here."], + } + self.owner.refresh_from_db() + assert self.owner.email == "owner-caller@example.com" + + @override_settings(ALLOW_EMAIL_ADDRESS_CHANGE=False) + def test_a_site_that_does_not_change_addresses_here_still_changes_the_rest(self): + response = self.patch(self.own_url, json.dumps({"bio": "still changeable"})) + assert response.status_code == status.HTTP_200_OK + assert response.data["bio"] == "still changeable" + + +@skip_unless_lms +class SelectionIsSettledBeforeTheAddressIsReadTests(AccountApiV2TestCase): + """ + A selection this endpoint cannot answer is refused before the account is read or written. + + Which properties an answer can carry depends on the caller and on the + address, so a selection naming a property this caller cannot be given at + this address is refused whoever holds the name and whether or not anybody + does. The refusal names the selection and nothing else, so it says no more + about who holds a name than the refusal that would follow it, and the + account the address names is neither read nor changed on the way to it. + """ + + def setUp(self): + super().setUp() + self.login(self.owner) + + def assert_selection_refused(self, response, missing): + """Assert the answer is the refusal of the selection, naming the property asked for.""" + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"]["fields"][0].startswith(f"No such field: {missing}.") + return envelope + + def test_a_selection_the_answer_cannot_carry_leaves_the_account_as_it_was(self): + response = self.patch( + f"{self.own_url}?fields=nosuchfield", json.dumps({"bio": "a bio"}), + ) + self.assert_selection_refused(response, "nosuchfield") + self.owner.profile.refresh_from_db() + assert self.owner.profile.bio is None + + def test_a_property_another_owner_keeps_is_refused_at_their_address(self): + """``email`` is a property of an account that only its owner and staff read.""" + refused = self.patch( + f"{self.detail_url('other-caller')}?fields=email", json.dumps({"bio": "a bio"}), + ) + self.assert_selection_refused(refused, "email") + self.other.profile.refresh_from_db() + assert self.other.profile.bio is None + + def test_the_same_selection_is_refused_the_same_way_at_a_name_nobody_holds(self): + """What comes back names the selection, so it tells nothing about who holds the name.""" + held = self.patch( + f"{self.detail_url('other-caller')}?fields=email", json.dumps({"bio": "a bio"}), + ) + unheld = self.patch( + f"{self.detail_url('nobody-at-all')}?fields=email", json.dumps({"bio": "a bio"}), + ) + assert held.status_code == unheld.status_code == status.HTTP_400_BAD_REQUEST + assert held.data["errors"] == unheld.data["errors"] + + def test_a_request_that_names_no_selection_is_answered_by_the_address(self): + """Without a selection there is nothing to settle, and the address answers as it does.""" + for address in (self.detail_url("other-caller"), self.detail_url("nobody-at-all")): + response = self.patch(address, json.dumps({"bio": "a bio"})) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + +@skip_unless_lms +class OtherApiClassificationTests(AccountApiV2TestCase): + """ + What another API calls a request failure is not changed by what this one calls it. + + The catalog of error types is shared by every API in the process, so naming + one of the failures below for this API by registering the type it is raised + as would rename it for all of them. The names used here belong to this + API's own exception classes; the same two failures are read below at a + standardized address of another API, which keeps the name the shared + catalog gives a failure it does not know. + """ + + #: Standardized, served by another API, and reads a request body. + OTHER_API_WRITE_URL = "/api/enrollment/v2/enrollment/" + + def setUp(self): + super().setUp() + self.login(self.staff) + + def assert_unnamed(self, response, expected_status): + """Assert the failure is reported as one the shared catalog does not name.""" + envelope = assert_error_envelope( + response, expected_status=expected_status, expected_type_slug="internal", + ) + assert envelope["title"] == "Internal Server Error" + + def test_another_apis_malformed_body_keeps_the_name_the_shared_catalog_gives_it(self): + response = self.client.post( + self.OTHER_API_WRITE_URL, "{not json", content_type="application/json", + ) + self.assert_unnamed(response, status.HTTP_400_BAD_REQUEST) + + def test_another_apis_unreadable_body_keeps_the_name_the_shared_catalog_gives_it(self): + response = self.client.post( + self.OTHER_API_WRITE_URL, "course_id=course-v1:edX+DemoX+Demo", content_type="text/plain", + ) + self.assert_unnamed(response, status.HTTP_415_UNSUPPORTED_MEDIA_TYPE) + + def test_the_same_two_failures_are_named_at_an_address_of_this_api(self): + """The contrast the two above are measured against.""" + malformed = self.client.patch(self.own_url, "{not json", content_type=MERGE_PATCH) + assert_error_envelope( + malformed, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="malformed-body", + ) + unreadable = self.client.patch(self.own_url, "bio=x", content_type="text/plain") + assert_error_envelope( + unreadable, + expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, + expected_type_slug="unsupported-media-type", + ) + + +@skip_unless_lms +class EmailSearchTests(AccountApiV2TestCase): + """POST /api/user/v2/email_searches/""" + + def setUp(self): + super().setUp() + self.url = reverse("user_v2:email_search_list") + + def search(self, emails, **kwargs): + """Ask for the accounts holding the given addresses.""" + return self.client.post(self.url, {"emails": emails}, format="json", **kwargs) + + def test_a_staff_caller_resolves_addresses_to_accounts(self): + self.login(self.staff) + response = self.search(["owner-caller@example.com", "other-caller@example.com"]) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [ + {"email": "other-caller@example.com", "id": self.other.id, "username": "other-caller"}, + {"email": "owner-caller@example.com", "id": self.owner.id, "username": "owner-caller"}, + ] + + def test_the_page_carries_the_whole_envelope(self): + self.login(self.staff) + response = self.search(["owner-caller@example.com"]) + assert set(response.data) == PAGINATION_KEYS + assert response.data["count"] == 1 + + def test_an_address_no_account_holds_is_left_out_of_the_page(self): + self.login(self.staff) + response = self.search(["owner-caller@example.com", "nobody@example.com"]) + assert [row["username"] for row in response.data["results"]] == ["owner-caller"] + assert response.data["count"] == 1 + + def test_an_empty_search_finds_nothing(self): + self.login(self.staff) + response = self.search([]) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [] + assert response.data["count"] == 0 + + def test_a_body_without_the_addresses_is_refused(self): + self.login(self.staff) + response = self.client.post(self.url, {}, format="json") + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"emails": ["This field is required."]} + + def test_an_entry_that_is_not_an_address_is_refused_with_a_message(self): + """ + A refusal names the entries at fault in a sentence a client can show. + + An entry reported under the position it holds would reach the caller + as a mapping nested inside the member naming the list, which nothing + can display. + """ + self.login(self.staff) + response = self.client.post( + self.url, {"emails": [None, "owner-caller@example.com", {"address": "x"}]}, format="json", + ) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "emails": ["Every entry must be text, and the entries at these positions are not: 0, 2."], + } + + def test_addresses_that_are_not_a_list_are_refused(self): + self.login(self.staff) + response = self.client.post(self.url, {"emails": "owner-caller@example.com"}, format="json") + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"emails": ['Expected a list of items but got type "str".']} + + def test_a_body_that_is_not_well_formed_is_refused_as_the_callers_fault(self): + self.login(self.staff) + response = self.client.post(self.url, "{not json", content_type="application/json") + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="malformed-body", + ) + assert envelope["title"] == "Malformed Request Body" + + def test_a_learner_is_told_there_is_nothing_at_this_address(self): + """The search is hidden rather than refused, so it does not confirm what it is for.""" + self.login(self.owner) + response = self.search(["owner-caller@example.com"]) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_an_anonymous_caller_is_unauthenticated_rather_than_hidden_from(self): + response = self.search(["owner-caller@example.com"]) + assert_error_envelope( + response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + def test_a_staff_token_reaches_the_search(self): + response = self.search(["owner-caller@example.com"], **self.token_headers(self.staff)) + assert response.status_code == status.HTTP_200_OK + assert [row["username"] for row in response.data["results"]] == ["owner-caller"] + + def test_a_token_held_by_a_deactivated_staff_account_is_refused(self): + headers = self.token_headers(self.staff) + assert self.search(["owner-caller@example.com"], **headers).status_code == status.HTTP_200_OK + self.staff.is_active = False + self.staff.save() + assert_error_envelope( + self.search(["owner-caller@example.com"], **headers), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_session_whose_owner_has_not_confirmed_their_address_identifies_nobody_here(self): + """ + Searching other people's accounts is not done from the pages an unconfirmed account reaches. + + The account addresses accept such a session because the site's own + settings pages are reached with one; this address keeps the platform + default, under which it identifies nobody, and the same session still + reads the account it belongs to. + """ + self.staff.is_active = False + self.staff.save() + self.login(self.staff) + assert_error_envelope( + self.search(["owner-caller@example.com"]), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + own = self.client.get(self.own_url) + assert own.status_code == status.HTTP_200_OK + assert own.data["username"] == "staff-caller" + + def test_the_search_is_not_read_with_a_get(self): + self.login(self.staff) + response = self.client.get(self.url) + assert_error_envelope( + response, + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + + def test_the_rest_of_a_search_is_read_by_sending_the_body_to_the_link_again(self): + """ + A caller who asked for pages reads the rest by sending the same body to the link. + + The link is an address like any other, and this collection is only + read by sending the addresses to it, so a caller follows the link the + way they made the first request rather than by fetching it. + """ + self.login(self.staff) + addresses = [f"paged-{index:02d}@example.com" for index in range(12)] + User.objects.bulk_create( + User(username=f"paged-{index:02d}", email=address) + for index, address in enumerate(addresses) + ) + + first = self.client.post(f"{self.url}?page_size=10", {"emails": addresses}, format="json") + assert first.status_code == status.HTTP_200_OK + assert first.data["count"] == 12 + assert first.data["num_pages"] == 2 + assert [row["username"] for row in first.data["results"]] == [ + f"paged-{index:02d}" for index in range(10) + ] + + link = first.data["next"] + assert urlparse(link).path == "/api/user/v2/email_searches/" + assert parse_qs(urlparse(link).query) == {"page": ["2"], "page_size": ["10"]} + rest = self.client.post(link, {"emails": addresses}, format="json") + assert rest.status_code == status.HTTP_200_OK + assert [row["username"] for row in rest.data["results"]] == ["paged-10", "paged-11"] + assert rest.data["next"] is None + assert urlparse(rest.data["previous"]).path == "/api/user/v2/email_searches/" + assert parse_qs(urlparse(rest.data["previous"]).query) == {"page_size": ["10"]} + + def test_a_search_is_answered_a_page_at_a_time_when_the_caller_asks_for_no_size(self): + """ + A search that found more accounts than a page carries answers with the first page of them. + + The answer is a list like every other list of this version: it carries + the rows one page holds and a link to the rest, rather than every + account found however many that is. + """ + self.login(self.staff) + addresses = [f"whole-{index:02d}@example.com" for index in range(12)] + User.objects.bulk_create( + User(username=f"whole-{index:02d}", email=address) + for index, address in enumerate(addresses) + ) + + answer = self.search(addresses) + assert answer.status_code == status.HTTP_200_OK + assert answer.data["count"] == 12 + assert answer.data["num_pages"] == 2 + assert [row["username"] for row in answer.data["results"]] == [ + f"whole-{index:02d}" for index in range(10) + ] + assert parse_qs(urlparse(answer.data["next"]).query) == {"page": ["2"]} + assert answer.data["previous"] is None + + def test_a_search_may_name_as_many_addresses_as_the_largest_page_carries(self): + """A hundred addresses is the most one search takes, and it is answered.""" + self.login(self.staff) + addresses = [f"bound-{index:03d}@example.com" for index in range(100)] + User.objects.bulk_create( + User(username=f"bound-{index:03d}", email=address) + for index, address in enumerate(addresses) + ) + + answer = self.search(addresses) + assert answer.status_code == status.HTTP_200_OK + assert answer.data["count"] == 100 + assert answer.data["num_pages"] == 10 + assert [row["username"] for row in answer.data["results"]] == [ + f"bound-{index:03d}" for index in range(10) + ] + + def test_a_search_naming_more_addresses_than_that_is_refused(self): + """ + A search is held to the addresses the largest page could answer for. + + An unbounded list would be read in one database query as long as the + body, and could ask for more accounts than any page may carry. + """ + self.login(self.staff) + response = self.search([f"bound-{index:03d}@example.com" for index in range(101)]) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "emails": ["Ensure this field has no more than 100 elements."], + } + + def test_fetching_the_link_to_the_rest_of_a_search_is_not_how_it_is_read(self): + """The link addresses this collection, which is read by sending the addresses to it.""" + self.login(self.staff) + response = self.client.get(f"{self.url}?page=2") + assert_error_envelope( + response, + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + + def test_a_page_the_search_does_not_have_is_not_found(self): + self.login(self.staff) + response = self.client.post( + f"{self.url}?page=7", {"emails": ["owner-caller@example.com"]}, format="json", + ) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_a_query_parameter_is_not_read_by_the_search(self): + self.login(self.staff) + response = self.client.post( + f"{self.url}?view=minimal", {"emails": []}, format="json", + ) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "view": [f"No such query parameter. Send any of: {ACTION_QUERY_PARAMS}."], + } + + +@skip_unless_lms +class AccountPageSizeTests(AccountApiV2TestCase): + """ + How many accounts a page carries when the caller does not say, and the most it will carry. + + Both lists are asked for more rows than they will give, against rows that + really exist, so what is pinned is the page the endpoint answers with + rather than the numbers a paginator class holds. + """ + + DEFAULT_PAGE_SIZE = 10 + MAX_PAGE_SIZE = 100 + + def extra_accounts(self, count): + """Create the given number of accounts and return their names in page order.""" + User.objects.bulk_create( + User(username=f"paged-{index:03d}", email=f"paged-{index:03d}@example.com") + for index in range(count) + ) + return [f"paged-{index:03d}" for index in range(count)] + + def test_a_page_of_accounts_carries_ten_of_them_when_the_caller_asks_for_no_size(self): + names = self.extra_accounts(self.DEFAULT_PAGE_SIZE + 1) + self.login(self.staff) + response = self.client.get(self.list_url, {"username": ",".join(names)}) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == self.DEFAULT_PAGE_SIZE + 1 + assert self.usernames_in(response) == names[:self.DEFAULT_PAGE_SIZE] + assert response.data["num_pages"] == 2 + assert "page=2" in response.data["next"] + + def test_a_page_of_accounts_carries_a_hundred_of_them_however_many_are_asked_for(self): + names = self.extra_accounts(self.MAX_PAGE_SIZE + 1) + self.login(self.staff) + response = self.client.get( + self.list_url, {"username": ",".join(names), "page_size": 1000}, + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == self.MAX_PAGE_SIZE + 1 + assert self.usernames_in(response) == names[:self.MAX_PAGE_SIZE] + assert response.data["num_pages"] == 2 + assert response.data["next"] is not None + + def test_a_page_of_found_addresses_carries_ten_of_them_when_the_caller_asks_for_no_size(self): + names = self.extra_accounts(self.DEFAULT_PAGE_SIZE + 1) + self.login(self.staff) + response = self.client.post( + reverse("user_v2:email_search_list"), + {"emails": [f"{name}@example.com" for name in names]}, + format="json", + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == self.DEFAULT_PAGE_SIZE + 1 + assert [row["username"] for row in response.data["results"]] == names[:self.DEFAULT_PAGE_SIZE] + assert response.data["num_pages"] == 2 + assert "page=2" in response.data["next"] + + def test_the_longest_search_allowed_fits_in_the_largest_page_a_caller_may_ask_for(self): + """ + What a search may ask about and what a page may carry are the same number. + + A caller that names the most addresses a search takes and asks for a + page larger than the cap is answered with all of them at once, so no + search can find more accounts than one page will hold. + """ + names = self.extra_accounts(self.MAX_PAGE_SIZE) + self.login(self.staff) + response = self.client.post( + f"{reverse('user_v2:email_search_list')}?page_size=1000", + {"emails": [f"{name}@example.com" for name in names]}, + format="json", + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == self.MAX_PAGE_SIZE + assert [row["username"] for row in response.data["results"]] == names + assert response.data["num_pages"] == 1 + assert response.data["next"] is None + + +@skip_unless_lms +class AccountDeactivationTests(AccountApiV2TestCase): + """POST /api/user/v2/accounts/{username}/deactivation/""" + + def setUp(self): + super().setUp() + self.url = reverse("user_v2:account_deactivation", kwargs={"username": "other-caller"}) + self.deactivator = UserFactory.create(username="deactivator", password=PASSWORD) + self.deactivator.user_permissions.add( + PermissionFactory( + codename="can_deactivate_users", + content_type=ContentTypeFactory(app_label="student"), + ), + ) + + def test_a_caller_holding_the_privilege_deactivates_an_account(self): + self.login(self.deactivator) + assert self.other.has_usable_password() + response = self.client.post(self.url) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert not response.content + self.other.refresh_from_db() + assert not self.other.has_usable_password() + + def test_asking_for_a_password_reset_does_not_bring_a_deactivated_account_back(self): + """ + The reset flow refuses an account whose password is unusable, which is what this leaves. + + The description of this operation tells a support caller what a + deactivation can and cannot be undone by, so the refusal it names is + pinned here: a reset asked for on the deactivated address is refused, + and the account still has no usable password afterwards. + """ + self.login(self.deactivator) + assert self.client.post(self.url).status_code == status.HTTP_204_NO_CONTENT + form = PasswordResetFormNoActive(data={"email": self.other.email}) + assert form.is_valid() is False + assert form.errors["email"] == [ + "The user account associated with this e-mail address cannot reset the password.", + ] + self.other.refresh_from_db() + assert not self.other.has_usable_password() + + def test_a_deactivated_account_keeps_its_data(self): + self.login(self.deactivator) + self.client.post(self.url) + self.other.refresh_from_db() + assert self.other.is_active is True + assert self.other.username == "other-caller" + assert self.other.email == "other-caller@example.com" + + def test_a_superuser_deactivates_an_account(self): + superuser = SuperuserFactory(username="super-caller", password=PASSWORD) + self.login(superuser) + assert self.client.post(self.url).status_code == status.HTTP_204_NO_CONTENT + + def test_a_staff_caller_without_the_privilege_is_refused(self): + self.login(self.staff) + assert_error_envelope( + self.client.post(self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + self.other.refresh_from_db() + assert self.other.has_usable_password() + + def test_a_learner_is_refused(self): + self.login(self.owner) + assert_error_envelope( + self.client.post(self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_learner_may_not_deactivate_their_own_account_either(self): + self.login(self.owner) + response = self.client.post( + reverse("user_v2:account_deactivation", kwargs={"username": "owner-caller"}), + ) + assert_error_envelope( + response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + self.owner.refresh_from_db() + assert self.owner.has_usable_password() + + def test_the_reserved_identifier_names_the_account_holding_it_and_not_the_caller(self): + """This action names the account to disable, so ``me`` is the username it looks like.""" + held = UserFactory.create(username="me", password=PASSWORD) + self.login(self.deactivator) + response = self.client.post( + reverse("user_v2:account_deactivation", kwargs={"username": "me"}), + ) + assert response.status_code == status.HTTP_204_NO_CONTENT + held.refresh_from_db() + assert not held.has_usable_password() + self.deactivator.refresh_from_db() + assert self.deactivator.has_usable_password() + + def test_the_reserved_identifier_is_not_found_when_no_account_holds_it(self): + """Nobody is named ``me`` here, so there is no account at that address to disable.""" + self.login(self.deactivator) + response = self.client.post( + reverse("user_v2:account_deactivation", kwargs={"username": "me"}), + ) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + self.deactivator.refresh_from_db() + assert self.deactivator.has_usable_password() + + def test_an_anonymous_caller_is_unauthenticated(self): + assert_error_envelope( + self.client.post(self.url), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + + def test_a_query_parameter_is_not_read_by_a_deactivation(self): + """A parameter this action reads nothing from is refused before the account is touched.""" + self.login(self.deactivator) + response = self.client.post(f"{self.url}?view=minimal") + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "view": [f"No such query parameter. Send any of: {DEACTIVATION_QUERY_PARAMS}."], + } + self.other.refresh_from_db() + assert self.other.has_usable_password() + + def test_a_name_no_account_holds_is_not_found(self): + self.login(self.deactivator) + response = self.client.post( + reverse("user_v2:account_deactivation", kwargs={"username": "nobody"}), + ) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_a_token_held_by_a_deactivated_caller_is_refused(self): + headers = self.token_headers(self.deactivator) + self.deactivator.is_active = False + self.deactivator.save() + assert_error_envelope( + self.client.post(self.url, **headers), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + self.other.refresh_from_db() + assert self.other.has_usable_password() + + def test_a_token_held_by_an_active_caller_reaches_the_action(self): + response = self.client.post(self.url, **self.token_headers(self.deactivator)) + assert response.status_code == status.HTTP_204_NO_CONTENT + + def test_the_account_is_not_deactivated_by_reading_it(self): + self.login(self.deactivator) + response = self.client.get(self.url) + assert_error_envelope( + response, + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + self.other.refresh_from_db() + assert self.other.has_usable_password() + + +@skip_unless_lms +class ProfilelessAccountTests(AccountApiV2TestCase): + """An account whose user has no profile row is served rather than failing.""" + + def setUp(self): + super().setUp() + self.profileless = UserFactory.create(username="no-profile", password=PASSWORD) + self.profileless.profile.delete() + + def test_a_learner_reading_an_account_without_a_profile_sees_the_shared_properties(self): + self.login(self.owner) + response = self.client.get(self.detail_url("no-profile")) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PUBLIC_FIELDS + assert response.data["username"] == "no-profile" + + def test_a_staff_caller_reading_an_account_without_a_profile_sees_empty_properties(self): + self.login(self.staff) + response = self.client.get(self.detail_url("no-profile")) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == FULL_FIELDS + assert response.data["name"] is None + assert response.data["country"] is None + + def test_the_owner_of_an_account_without_a_profile_reads_it_too(self): + self.login(self.profileless) + response = self.client.get(self.own_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["username"] == "no-profile" + + +@skip_unless_lms +@override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=True) +class SecondaryEmailEnabledTests(AccountApiV2TestCase): + """The recovery address is collected on this site.""" + + def test_the_account_says_the_site_collects_a_recovery_address(self): + self.login(self.owner) + response = self.client.get(self.own_url) + assert response.data["secondary_email_enabled"] is True + assert response.data["secondary_email"] is None + + +@skip_unless_lms +@override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=False) +class SecondaryEmailDisabledTests(AccountApiV2TestCase): + """The recovery address is not collected on this site.""" + + def test_the_account_says_nothing_about_a_recovery_address(self): + self.login(self.owner) + response = self.client.get(self.own_url) + assert response.data["secondary_email_enabled"] is None + assert response.data["secondary_email"] is None + + +@skip_unless_lms +class ExtendedProfileConfiguredTests(AccountApiV2TestCase): + """A site that collects extra profile fields.""" + + def setUp(self): + super().setUp() + # The configuration is entered per test. The helper that applies it + # wraps a function, so a class given to it comes back as a function and + # the runner finds no tests inside it at all. + self.enterContext( + with_site_configuration_context(configuration={"extended_profile_fields": ["department"]}), + ) + + def test_the_account_carries_a_value_for_each_configured_field(self): + self.login(self.owner) + response = self.client.get(self.own_url) + assert response.data["extended_profile"] == [{"field_name": "department", "field_value": ""}] + + def test_an_extra_field_is_changed_by_its_owner(self): + self.login(self.owner) + response = self.patch( + self.own_url, + json.dumps({"extended_profile": [{"field_name": "department", "field_value": "physics"}]}), + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["extended_profile"] == [ + {"field_name": "department", "field_value": "physics"}, + ] + + def test_an_extra_field_keeps_the_shape_the_site_stored_it_in(self): + """A field a site collects as something other than text comes back as that, not as its text.""" + self.login(self.owner) + response = self.patch( + self.own_url, + json.dumps({"extended_profile": [{"field_name": "department", "field_value": 41}]}), + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["extended_profile"] == [{"field_name": "department", "field_value": 41}] + reread = self.client.get(self.own_url) + assert reread.data["extended_profile"] == [{"field_name": "department", "field_value": 41}] + + def test_a_field_the_site_does_not_collect_is_left_out_of_the_account(self): + """Only the fields the site asks for are carried, whatever else the profile holds.""" + self.owner.profile.meta = json.dumps({"department": "physics", "shoe_size": 44}) + self.owner.profile.save() + self.login(self.owner) + response = self.client.get(self.own_url) + assert response.data["extended_profile"] == [ + {"field_name": "department", "field_value": "physics"}, + ] + + +@skip_unless_lms +class ExtendedProfileUnconfiguredTests(AccountApiV2TestCase): + """A site that collects no extra profile fields.""" + + def test_the_account_carries_no_extra_fields(self): + self.login(self.owner) + response = self.client.get(self.own_url) + assert response.data["extended_profile"] == [] + + +@skip_unless_lms +class AccountVisibilityTests(AccountApiV2TestCase): + """What one learner sees of another account is what that account's owner shares.""" + + def setUp(self): + super().setUp() + # A profile that does not say how old its owner is counts as a child's, + # and a child shares nothing, so the account being read is an adult's + # wherever the owner's own choice is what decides. + self.other.profile.year_of_birth = 1985 + self.other.profile.bio = "Teaches mathematics." + self.other.profile.save() + self.login(self.owner) + + def prefer(self, key, value): + """Record one of the account owner's visibility choices.""" + UserPreferenceFactory.create(user=self.other, key=key, value=value) + + def test_an_account_shared_with_everybody_carries_what_its_owner_shares(self): + response = self.client.get(self.detail_url("other-caller")) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == SHARED_FIELDS + assert response.data["account_privacy"] == "all_users" + assert response.data["bio"] == "Teaches mathematics." + + def test_a_page_carries_the_same_shared_properties_as_the_account_itself(self): + response = self.client.get(self.list_url, {"username": "other-caller"}) + assert response.status_code == status.HTTP_200_OK + assert set(response.data["results"][0]) == SHARED_FIELDS + assert response.data["results"][0]["bio"] == "Teaches mathematics." + + def test_an_account_shared_property_by_property_carries_the_ones_chosen(self): + self.prefer("account_privacy", "custom") + self.prefer("visibility.bio", "all_users") + response = self.client.get(self.detail_url("other-caller")) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PUBLIC_FIELDS | {"bio"} + assert response.data["account_privacy"] == "custom" + assert response.data["bio"] == "Teaches mathematics." + + def test_an_account_kept_private_carries_only_what_everybody_may_see(self): + self.prefer("account_privacy", "private") + response = self.client.get(self.detail_url("other-caller")) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PUBLIC_FIELDS + assert response.data["account_privacy"] == "private" + + def test_an_account_whose_profile_does_not_say_how_old_its_owner_is_shares_nothing(self): + self.other.profile.year_of_birth = None + self.other.profile.save() + self.prefer("account_privacy", "all_users") + response = self.client.get(self.detail_url("other-caller")) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PUBLIC_FIELDS + assert response.data["account_privacy"] == "private" + + def test_the_owner_of_a_shared_account_still_sees_every_property_of_it(self): + self.login(self.other) + response = self.client.get(self.own_url) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == FULL_FIELDS + + def test_a_selected_property_an_owner_shares_with_everybody_is_answered(self): + response = self.client.get(self.detail_url("other-caller"), {"fields": "bio"}) + assert response.status_code == status.HTTP_200_OK + assert response.data == {"bio": "Teaches mathematics."} + + def test_a_selected_property_an_owner_shares_by_choice_is_answered(self): + self.prefer("account_privacy", "custom") + self.prefer("visibility.bio", "all_users") + response = self.client.get(self.detail_url("other-caller"), {"fields": "bio"}) + assert response.status_code == status.HTTP_200_OK + assert response.data == {"bio": "Teaches mathematics."} + + def test_a_selected_property_an_owner_chose_not_to_share_is_left_out(self): + """ + Which properties an owner shares is theirs to decide, so a selection can come back empty. + + What can be selected is settled from the properties an owner is able + to share, which is the same question for every account; whether this + owner shares this one is a different question, and it is answered + where the account is read. + """ + self.prefer("account_privacy", "custom") + self.prefer("visibility.country", "all_users") + response = self.client.get(self.detail_url("other-caller"), {"fields": "bio"}) + assert response.status_code == status.HTTP_200_OK + assert response.data == {} + + def test_a_selected_property_of_an_account_kept_private_is_left_out(self): + self.prefer("account_privacy", "private") + response = self.client.get(self.detail_url("other-caller"), {"fields": "bio"}) + assert response.status_code == status.HTTP_200_OK + assert response.data == {} + + def test_a_property_only_a_chosen_few_share_is_left_out_of_an_account_shared_with_everybody(self): + """Sharing with everybody shares a set the site fixes, and the full name is outside it.""" + response = self.client.get(self.detail_url("other-caller"), {"fields": "name"}) + assert response.status_code == status.HTTP_200_OK + assert response.data == {} + + def test_a_staff_caller_selecting_the_same_property_is_answered_it(self): + """The empty answer above is the owner's choice and not a property the endpoint cannot carry.""" + self.login(self.staff) + self.prefer("account_privacy", "private") + response = self.client.get(self.detail_url("other-caller"), {"fields": "bio"}) + assert response.status_code == status.HTTP_200_OK + assert response.data == {"bio": "Teaches mathematics."} + + def test_a_page_answers_each_row_by_the_choice_of_the_owner_it_belongs_to(self): + """One selection over two accounts answers what each owner shares, row by row.""" + self.prefer("account_privacy", "private") + self.owner.profile.bio = "Learning mathematics." + self.owner.profile.save() + response = self.client.get( + self.list_url, {"username": "other-caller,owner-caller", "fields": "bio"}, + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [{}, {"bio": "Learning mathematics."}] + + +class AccountReadsDoNotWriteMixin: + """ + Reading an account changes nothing, on every branch a read can take. + + The capture runs the callbacks a request defers to the end of its + transaction, because a write made from one is a write the request made. + """ + + def captured_writes(self, method, address, params=None, expect=status.HTTP_200_OK, **headers): + """ + Return the statements a request made that would change stored data. + + The body the request answered with is left on ``self.answer``, so a + test can show which branch of the read the capture went through + instead of asserting that an unidentified read wrote nothing. Request + headers given here reach the client, which is how a read presented + with a token is captured alongside one made from a session. + """ + with CaptureQueriesContext(connection) as captured: + with self.captureOnCommitCallbacks(execute=True): + self.answer = getattr(self.client, method)(address, params or {}, **headers) + assert self.answer.status_code == expect, self.answer.content + return write_queries(captured.captured_queries) + + def populate(self, user): + """Give an account a value for each kind of data a read of it branches on.""" + user.profile.year_of_birth = 1985 + user.profile.bio = "Teaches mathematics." + user.profile.country = "US" + user.profile.state = "MA" + user.profile.profile_image_uploaded_at = datetime.datetime( + 2020, 1, 1, tzinfo=datetime.UTC, + ) + user.profile.meta = json.dumps({"department": "physics"}) + user.profile.save() + user.profile.language_proficiencies.create(code="fr") + user.profile.social_links.create( + platform="twitter", social_link="https://www.twitter.com/example", + ) + return user + + def test_a_staff_caller_reading_the_collection_writes_nothing(self): + self.login(self.staff) + assert self.captured_writes("get", self.list_url, {"username": "owner-caller,other-caller"}) == [] + + def test_a_learner_reading_the_collection_writes_nothing(self): + self.login(self.owner) + assert self.captured_writes("get", self.list_url) == [] + assert self.captured_writes("get", self.list_url, {"username": "other-caller"}) == [] + + def test_reading_a_member_writes_nothing(self): + self.login(self.owner) + assert self.captured_writes("get", self.own_url) == [] + assert self.captured_writes("get", self.detail_url("other-caller")) == [] + + def test_a_staff_caller_reading_a_member_writes_nothing(self): + self.login(self.staff) + assert self.captured_writes("get", self.detail_url("owner-caller")) == [] + + def test_the_shared_preset_writes_nothing(self): + self.login(self.owner) + assert self.captured_writes("get", self.own_url, {"view": "shared"}) == [] + + def test_heading_the_collection_and_a_member_writes_nothing(self): + self.login(self.owner) + assert self.captured_writes("head", self.list_url) == [] + assert self.captured_writes("head", self.own_url) == [] + + def test_a_search_writes_nothing(self): + self.login(self.staff) + with CaptureQueriesContext(connection) as captured: + with self.captureOnCommitCallbacks(execute=True): + response = self.client.post( + reverse("user_v2:email_search_list"), + {"emails": ["owner-caller@example.com"]}, + format="json", + ) + assert response.status_code == status.HTTP_200_OK + assert write_queries(captured.captured_queries) == [] + + def test_narrowing_what_a_read_carries_writes_nothing(self): + self.login(self.owner) + assert self.captured_writes("get", self.list_url, {"view": "minimal"}) == [] + assert self.captured_writes("get", self.own_url, {"view": "minimal"}) == [] + assert self.captured_writes("get", self.list_url, {"fields": "username,email"}) == [] + assert self.captured_writes("get", self.own_url, {"fields": "username,email"}) == [] + + def test_selecting_an_account_by_something_other_than_its_name_writes_nothing(self): + self.login(self.staff) + assert self.captured_writes("get", self.list_url, {"email": "owner-caller@example.com"}) == [] + assert self.captured_writes("get", self.list_url, {"lms_user_id": str(self.owner.id)}) == [] + + def test_reading_an_account_with_a_name_change_outstanding_writes_nothing(self): + PendingNameChange.objects.create( + user=self.owner, new_name="Changed Name", rationale="Asked for in a test", + ) + self.login(self.owner) + assert self.captured_writes("get", self.own_url) == [] + + def test_a_read_that_finds_no_account_writes_nothing(self): + self.login(self.staff) + assert self.captured_writes( + "get", self.detail_url("nobody-at-all"), expect=status.HTTP_404_NOT_FOUND, + ) == [] + assert self.captured_writes( + "get", self.list_url, {"email": "nobody@example.com"}, + ) == [] + assert self.answer.data["results"] == [] + + def test_a_read_a_token_identifies_its_caller_by_writes_nothing(self): + """ + A caller resolved from a token reads as a signed-in one does. + + A token is how a service or a micro-frontend reaches these addresses, + and the layer that resolves one runs before the handler, so each read + is captured under both ways of identifying the caller. + """ + self.populate(self.owner) + headers = self.token_headers(self.owner) + assert self.captured_writes("get", self.own_url, **headers) == [] + assert self.answer.data["username"] == "owner-caller" + assert self.captured_writes("get", self.detail_url("other-caller"), **headers) == [] + assert set(self.answer.data) == PUBLIC_FIELDS + assert self.captured_writes("get", self.list_url, **headers) == [] + assert self.usernames_in(self.answer) == ["owner-caller"] + + def test_a_read_a_staff_token_identifies_its_caller_by_writes_nothing(self): + self.populate(self.other) + headers = self.token_headers(self.staff) + assert self.captured_writes( + "get", self.list_url, {"username": "other-caller,owner-caller"}, **headers, + ) == [] + assert self.usernames_in(self.answer) == ["other-caller", "owner-caller"] + assert self.captured_writes("get", self.detail_url("other-caller"), **headers) == [] + assert self.answer.data["bio"] == "Teaches mathematics." + + def test_a_search_a_token_identifies_its_caller_by_writes_nothing(self): + headers = self.token_headers(self.staff) + with CaptureQueriesContext(connection) as captured: + with self.captureOnCommitCallbacks(execute=True): + response = self.client.post( + reverse("user_v2:email_search_list"), + {"emails": ["owner-caller@example.com"]}, + format="json", + **headers, + ) + assert response.status_code == status.HTTP_200_OK, response.content + assert [row["username"] for row in response.data["results"]] == ["owner-caller"] + assert write_queries(captured.captured_queries) == [] + + def test_reading_an_account_whose_name_was_checked_against_an_identity_document_writes_nothing(self): + """The service holding a checked name is consulted by every read, and the read still writes nothing.""" + self.login(self.owner) + with name_affirmation_answering("Checked Name"): + assert self.captured_writes("get", self.own_url) == [] + assert self.answer.data["verified_name"] == "Checked Name" + assert self.captured_writes("get", self.list_url) == [] + assert self.answer.data["results"][0]["verified_name"] == "Checked Name" + + def test_reading_an_account_the_name_service_holds_no_checked_name_for_writes_nothing(self): + """The same read on an account the service has nothing for carries no name and writes nothing.""" + self.login(self.owner) + with name_affirmation_answering(None) as service: + service.return_value.get_verified_name.return_value = None + assert self.captured_writes("get", self.own_url) == [] + assert self.answer.data["verified_name"] is None + + def test_reading_an_account_that_holds_every_kind_of_data_writes_nothing(self): + """The read has a branch per kind of stored data, and none of them writes.""" + self.populate(self.owner) + self.login(self.owner) + assert self.captured_writes("get", self.own_url) == [] + assert self.answer.data["bio"] == "Teaches mathematics." + assert self.answer.data["country"] == "US" + assert self.answer.data["language_proficiencies"] == [{"code": "fr"}] + assert self.answer.data["social_links"] == [ + {"platform": "twitter", "social_link": "https://www.twitter.com/example"}, + ] + assert self.answer.data["profile_image"]["has_image"] is True + assert self.captured_writes("get", self.list_url) == [] + assert self.answer.data["results"][0]["bio"] == "Teaches mathematics." + + def test_a_staff_caller_reading_an_account_that_holds_every_kind_of_data_writes_nothing(self): + self.populate(self.other) + self.login(self.staff) + assert self.captured_writes("get", self.detail_url("other-caller")) == [] + assert self.answer.data["bio"] == "Teaches mathematics." + assert self.answer.data["profile_image"]["has_image"] is True + + def test_reading_an_account_whose_site_collects_extra_profile_fields_writes_nothing(self): + self.populate(self.owner) + self.login(self.owner) + with with_site_configuration_context( + configuration={"extended_profile_fields": ["department"]}, + ): + assert self.captured_writes("get", self.own_url) == [] + assert self.answer.data["extended_profile"] == [ + {"field_name": "department", "field_value": "physics"}, + ] + + def test_reading_an_account_that_has_no_profile_writes_nothing(self): + profileless = UserFactory.create(username="unprofiled-caller", password=PASSWORD) + profileless.profile.delete() + self.login(self.staff) + assert self.captured_writes("get", self.detail_url("unprofiled-caller")) == [] + assert self.answer.data["name"] is None + self.login(self.owner) + assert self.captured_writes("get", self.detail_url("unprofiled-caller")) == [] + assert set(self.answer.data) == PUBLIC_FIELDS + + def test_a_learner_reading_an_account_kept_private_writes_nothing(self): + """The read that answers with the properties everybody may see writes nothing either.""" + self.populate(self.other) + UserPreferenceFactory.create(user=self.other, key="account_privacy", value="private") + self.login(self.owner) + assert self.captured_writes("get", self.detail_url("other-caller")) == [] + assert set(self.answer.data) == PUBLIC_FIELDS + assert self.answer.data["account_privacy"] == "private" + + def test_the_shared_preset_over_another_account_writes_nothing(self): + self.populate(self.other) + self.login(self.staff) + assert self.captured_writes( + "get", self.detail_url("other-caller"), {"view": "shared"}, + ) == [] + assert set(self.answer.data) == SHARED_FIELDS + assert self.captured_writes( + "get", self.list_url, {"username": "other-caller", "view": "shared"}, + ) == [] + assert set(self.answer.data["results"][0]) == SHARED_FIELDS + + def test_reading_the_collection_a_page_at_a_time_writes_nothing(self): + self.populate(self.owner) + self.login(self.staff) + selection = {"username": "owner-caller,other-caller,staff-caller", "page_size": 2} + assert self.captured_writes("get", self.list_url, selection) == [] + assert self.usernames_in(self.answer) == ["other-caller", "owner-caller"] + assert self.captured_writes("get", self.list_url, {**selection, "page": 2}) == [] + assert self.usernames_in(self.answer) == ["staff-caller"] + + def test_asking_for_a_page_the_collection_does_not_have_writes_nothing(self): + self.login(self.staff) + assert self.captured_writes( + "get", self.list_url, {"page": 7}, expect=status.HTTP_404_NOT_FOUND, + ) == [] + + def test_reading_the_collection_in_either_order_writes_nothing(self): + self.populate(self.owner) + self.login(self.staff) + selection = {"username": "owner-caller,other-caller,staff-caller"} + assert self.captured_writes( + "get", self.list_url, {**selection, "ordering": ACCOUNT_DEFAULT_SORT}, + ) == [] + assert self.usernames_in(self.answer) == ["other-caller", "owner-caller", "staff-caller"] + assert self.captured_writes( + "get", self.list_url, {**selection, "ordering": f"-{ACCOUNT_DEFAULT_SORT}"}, + ) == [] + assert self.usernames_in(self.answer) == ["staff-caller", "owner-caller", "other-caller"] + + def test_a_learner_reading_an_account_shared_with_everybody_writes_nothing(self): + """The visibility a read consults is stored as a preference, which is read and not written.""" + self.other.profile.year_of_birth = 1985 + self.other.profile.save() + UserPreferenceFactory.create(user=self.other, key="account_privacy", value="custom") + UserPreferenceFactory.create(user=self.other, key="visibility.bio", value="all_users") + self.login(self.owner) + assert self.captured_writes("get", self.detail_url("other-caller")) == [] + self.other.preferences.filter(key="account_privacy").delete() + assert self.captured_writes("get", self.detail_url("other-caller")) == [] + + +@skip_unless_lms +class TokenProvisionedAccountTests(AccountApiV2TestCase): + """What a token naming an account no row holds leaves behind.""" + + #: The tables written the first time a token names an account that does + #: not exist: the account itself, and the two rows the platform gives + #: every new account through the receivers that run when one is created. + PROVISIONED_TABLES = ["auth_user", "notifications_notificationpreference", "user_tours_usertour"] + + #: The body of the read most recently captured. + answer = None + + def token_for_a_name_no_account_holds(self): + """Return request headers carrying a token for a name no row holds.""" + user = UserFactory.create(username="token-only-caller", email="token-only@example.com") + headers = self.token_headers(user) + User.objects.filter(pk=user.pk).delete() + return headers + + def tables_written(self, address, headers, expect=status.HTTP_200_OK): + """Return the tables one read changed, and leave its body on ``self.answer``.""" + with CaptureQueriesContext(connection) as captured: + with self.captureOnCommitCallbacks(execute=True): + self.answer = self.client.get(address, **headers) + assert self.answer.status_code == expect, self.answer.content + return sorted({write_target(sql) for sql in write_queries(captured.captured_queries)}) + + def test_the_first_read_a_token_for_an_unknown_name_makes_creates_that_account(self): + """ + A token carrying a name no account holds signs that name up. + + The authentication layer the whole platform shares resolves a token by + the name in it and creates the account when it finds none; the + receivers that run on a new account then add the rows belonging with + it. All of that happens before any handler of this API is reached, and + it is declared here rather than left out of the captures, because it + is the one way a read of these addresses is followed by new rows. + """ + headers = self.token_for_a_name_no_account_holds() + assert self.tables_written(self.own_url, headers) == self.PROVISIONED_TABLES + assert self.answer.data["username"] == "token-only-caller" + assert User.objects.filter(username="token-only-caller").count() == 1 + + def test_a_later_read_the_same_token_makes_writes_nothing(self): + """Once the account exists, the reads behind that token write nothing at all.""" + headers = self.token_for_a_name_no_account_holds() + assert self.client.get(self.own_url, **headers).status_code == status.HTTP_200_OK + assert self.tables_written(self.own_url, headers) == [] + assert self.answer.data["username"] == "token-only-caller" + assert self.tables_written(self.list_url, headers) == [] + assert self.usernames_in(self.answer) == ["token-only-caller"] + + def test_the_earlier_address_answers_such_a_token_the_same_way(self): + """Both versions sign the name up, because the layer in front of both does it.""" + headers = self.token_for_a_name_no_account_holds() + assert self.tables_written("/api/user/v1/me", headers) == self.PROVISIONED_TABLES + assert self.answer.data["username"] == "token-only-caller" + + +@skip_unless_lms +@override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=False) +class AccountReadsDoNotWriteTests(AccountReadsDoNotWriteMixin, AccountApiV2TestCase): + """Reading an account on a site that collects no recovery address writes nothing.""" + + +@skip_unless_lms +@override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=True) +class AccountReadsWithARecoveryAddressDoNotWriteTests(AccountReadsDoNotWriteMixin, AccountApiV2TestCase): + """The same reads on a site that collects a recovery address, which is another row to read.""" diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py new file mode 100644 index 000000000000..8ff088720cf2 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py @@ -0,0 +1,567 @@ +"""Tests for the version 2 User API profile name change views.""" + +import pytest +from django.urls import reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from rest_framework import status +from rest_framework.test import APITestCase + +from common.djangoapps.student.models import PendingNameChange +from common.djangoapps.student.tests.factories import UserFactory +from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user +from openedx.core.djangolib.testing.utils import skip_unless_lms + +PASSWORD = "Password1234" + +#: The version 1 addresses these views supersede. +EARLIER_REQUEST = "/api/user/v1/accounts/name_change/" + + +def earlier_confirmation(username): + """Return the version 1 address that confirms one user's requested name.""" + return f"/api/user/v1/accounts/name_change/{username}/confirm/" + + +class NameChangeTestCase(APITestCase): + """Fixtures shared by the version 2 name change tests.""" + + def setUp(self): + super().setUp() + self.staff = UserFactory.create( + username="name-staff", email="name-staff@example.com", password=PASSWORD, is_staff=True, + ) + self.owner = UserFactory.create( + username="name-owner", email="name-owner@example.com", password=PASSWORD, + ) + self.other = UserFactory.create( + username="name-other", email="name-other@example.com", password=PASSWORD, + ) + self.owner.profile.name = "Original Name" + self.owner.profile.save() + self.request_url = reverse("user_v2:name_change_list") + + def login(self, user): + """Sign the given user in through the session these views accept.""" + assert self.client.login(username=user.username, password=PASSWORD) + + def token_headers(self, user): + """Return the request headers that carry a token identifying the given user.""" + return {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(user)}"} + + def confirmation_url(self, username): + """Return the address that confirms one user's requested name.""" + return reverse("user_v2:name_change_confirmation", kwargs={"username": username}) + + def request_name(self, name, **kwargs): + """Ask for a profile name as the signed-in caller.""" + return self.client.post(self.request_url, {"name": name}, format="json", **kwargs) + + def pending_name(self, user): + """Return the name this user has asked for, or None when they have asked for none.""" + pending = PendingNameChange.objects.filter(user=user).first() + return pending.new_name if pending else None + + def profile_name(self, user): + """Return the name the user's profile carries right now.""" + user.profile.refresh_from_db() + return user.profile.name + + +@skip_unless_lms +class NameChangeRequestTests(NameChangeTestCase): + """POST /api/user/v2/name_changes/""" + + def test_a_caller_asks_for_a_name_on_their_own_profile(self): + self.login(self.owner) + response = self.request_name("Jon Doe") + assert response.status_code == status.HTTP_201_CREATED + assert response.data == {"name": "Jon Doe"} + assert self.pending_name(self.owner) == "Jon Doe" + assert self.profile_name(self.owner) == "Original Name" + + def test_the_request_records_who_asked_for_it(self): + self.login(self.owner) + self.request_name("Jon Doe") + pending = PendingNameChange.objects.get(user=self.owner) + assert pending.rationale == "Name change requested through account API by name-owner" + + def test_a_second_request_replaces_the_first(self): + self.login(self.owner) + self.request_name("First Try") + response = self.request_name("Second Try") + assert response.status_code == status.HTTP_201_CREATED + assert PendingNameChange.objects.filter(user=self.owner).count() == 1 + assert self.pending_name(self.owner) == "Second Try" + + def test_a_caller_may_only_ask_for_a_name_on_their_own_profile(self): + """The address carries no username, so a request is about the caller and nobody else.""" + self.login(self.other) + self.request_name("Jon Doe") + assert self.pending_name(self.other) == "Jon Doe" + assert self.pending_name(self.owner) is None + + def test_the_name_the_profile_already_carries_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.request_name("Original Name"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"name": ["The profile already carries this name."]} + assert self.pending_name(self.owner) is None + + def test_a_name_carrying_markup_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.request_name("Jon Doe"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "name": ["Name cannot contain the following characters: < >"], + } + assert self.pending_name(self.owner) is None + + def test_a_name_carrying_a_web_address_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.request_name("Jon Doe https://example.com"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"name": ["Name cannot contain a URL"]} + assert self.pending_name(self.owner) is None + + def test_a_body_carrying_no_name_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.post(self.request_url, {}, format="json"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"name": ["This field is required."]} + + def test_an_empty_name_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.request_name(""), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"name": ["This field may not be blank."]} + + def test_a_name_longer_than_the_column_that_stores_it_is_refused(self): + """The stored column holds 255 characters, and a longer one would fail at the database.""" + self.login(self.owner) + envelope = assert_error_envelope( + self.request_name("N" * 256), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "name": ["Ensure this field has no more than 255 characters."], + } + assert self.pending_name(self.owner) is None + assert PendingNameChange.objects.count() == 0 + + def test_a_name_exactly_as_long_as_the_column_is_accepted(self): + self.login(self.owner) + assert self.request_name("N" * 255).status_code == status.HTTP_201_CREATED + assert self.pending_name(self.owner) == "N" * 255 + + def test_an_account_carrying_no_profile_has_no_name_to_change(self): + self.login(self.other) + self.other.profile.delete() + assert_error_envelope( + self.request_name("Jon Doe"), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + assert PendingNameChange.objects.count() == 0 + + def test_an_anonymous_caller_is_unauthenticated(self): + assert_error_envelope( + self.request_name("Jon Doe"), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + assert PendingNameChange.objects.count() == 0 + + def test_a_token_held_by_a_caller_who_has_not_confirmed_their_address_asks_for_a_name(self): + """Asking for a name is about the caller's own profile, which a token reaches while unconfirmed.""" + self.owner.is_active = False + self.owner.save() + response = self.request_name("Jon Doe", **self.token_headers(self.owner)) + assert response.status_code == status.HTTP_201_CREATED + assert self.pending_name(self.owner) == "Jon Doe" + + def test_a_session_held_by_such_a_caller_identifies_nobody_here(self): + """A session here is read the way the platform reads one, and that is a token's work.""" + self.login(self.owner) + self.owner.is_active = False + self.owner.save() + assert_error_envelope( + self.request_name("Jon Doe"), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + assert PendingNameChange.objects.count() == 0 + + def test_an_unknown_query_parameter_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.post(f"{self.request_url}?username=name-other", {"name": "Jon Doe"}, format="json"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "username": ["No such query parameter. Send any of: format."], + } + assert PendingNameChange.objects.count() == 0 + + def test_a_body_that_is_not_well_formed_is_refused_as_the_callers_fault(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.post(self.request_url, "{not json", content_type="application/json"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="malformed-body", + ) + assert envelope["title"] == "Malformed Request Body" + assert PendingNameChange.objects.count() == 0 + + def test_a_body_in_a_media_type_this_endpoint_cannot_read_is_refused(self): + self.login(self.owner) + assert_error_envelope( + self.client.post(self.request_url, "Jon Doe", content_type="application/xml"), + expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, + expected_type_slug="unsupported-media-type", + ) + assert PendingNameChange.objects.count() == 0 + + def test_a_name_sent_as_a_web_form_is_recorded_the_way_one_sent_as_json_is(self): + self.login(self.owner) + encoded = self.client.post( + self.request_url, "name=Jon+Doe", content_type="application/x-www-form-urlencoded", + ) + assert encoded.status_code == status.HTTP_201_CREATED + assert encoded.data == {"name": "Jon Doe"} + assert self.pending_name(self.owner) == "Jon Doe" + + uploaded = self.client.post(self.request_url, {"name": "Jane Doe"}, format="multipart") + assert uploaded.status_code == status.HTTP_201_CREATED + assert uploaded.data == {"name": "Jane Doe"} + assert self.pending_name(self.owner) == "Jane Doe" + + def test_the_collection_is_not_read_with_a_get(self): + self.login(self.owner) + assert_error_envelope( + self.client.get(self.request_url), + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + + +@skip_unless_lms +class NameChangeConfirmationTests(NameChangeTestCase): + """POST /api/user/v2/name_changes/{username}/confirmations/""" + + def setUp(self): + super().setUp() + PendingNameChange.objects.create( + user=self.owner, new_name="Jon Doe", rationale="asked for in a test", + ) + self.url = self.confirmation_url(self.owner.username) + + def test_a_staff_caller_puts_the_requested_name_on_the_profile(self): + self.login(self.staff) + response = self.client.post(self.url) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert response.data is None + assert self.profile_name(self.owner) == "Jon Doe" + assert self.pending_name(self.owner) is None + + def test_the_name_the_profile_carried_is_kept_in_its_history(self): + self.login(self.staff) + self.client.post(self.url) + self.owner.profile.refresh_from_db() + recorded = self.owner.profile.get_meta()["old_names"] + assert len(recorded) == 1 + assert recorded[0][0] == "Original Name" + assert recorded[0][1] == "asked for in a test" + + def test_the_user_who_asked_may_not_confirm_their_own_request(self): + self.login(self.owner) + assert_error_envelope( + self.client.post(self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.profile_name(self.owner) == "Original Name" + assert self.pending_name(self.owner) == "Jon Doe" + + def test_another_learner_may_not_confirm_a_request_either(self): + self.login(self.other) + assert_error_envelope( + self.client.post(self.url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.profile_name(self.owner) == "Original Name" + + def test_an_anonymous_caller_is_unauthenticated(self): + assert_error_envelope( + self.client.post(self.url), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + assert self.profile_name(self.owner) == "Original Name" + + def test_a_token_held_by_a_deactivated_staff_account_is_refused(self): + headers = self.token_headers(self.staff) + self.staff.is_active = False + self.staff.save() + assert_error_envelope( + self.client.post(self.url, **headers), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert self.profile_name(self.owner) == "Original Name" + assert self.pending_name(self.owner) == "Jon Doe" + + def test_a_token_held_by_an_active_staff_account_reaches_the_action(self): + response = self.client.post(self.url, **self.token_headers(self.staff)) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert self.profile_name(self.owner) == "Jon Doe" + + def test_a_user_who_has_asked_for_nothing_has_nothing_to_confirm(self): + self.login(self.staff) + assert_error_envelope( + self.client.post(self.confirmation_url(self.other.username)), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + assert self.profile_name(self.other) == self.other.profile.name + + def test_the_reserved_identifier_is_read_as_a_stored_name_here(self): + """``me`` names an account holding that name at this address, as the parameter says.""" + self.login(self.staff) + assert_error_envelope( + self.client.post(self.confirmation_url("me")), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + named = UserFactory.create(username="me", email="me@example.com", password=PASSWORD) + PendingNameChange.objects.create( + user=named, new_name="Named Me", rationale="asked for in a test", + ) + assert self.client.post(self.confirmation_url("me")).status_code == status.HTTP_204_NO_CONTENT + assert self.profile_name(named) == "Named Me" + assert self.pending_name(self.owner) == "Jon Doe" + + def test_an_unknown_username_is_not_found(self): + self.login(self.staff) + assert_error_envelope( + self.client.post(self.confirmation_url("nobody-at-all")), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + def test_an_account_carrying_no_profile_has_no_name_to_change(self): + self.login(self.staff) + self.owner.profile.delete() + assert_error_envelope( + self.client.post(self.url), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + assert self.pending_name(self.owner) == "Jon Doe" + + def test_the_address_is_not_read_with_a_get(self): + self.login(self.staff) + assert_error_envelope( + self.client.get(self.url), + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + assert self.profile_name(self.owner) == "Original Name" + + def test_an_unknown_query_parameter_is_refused(self): + self.login(self.staff) + envelope = assert_error_envelope( + self.client.post(f"{self.url}?confirm=true"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "confirm": ["No such query parameter. Send any of: format."], + } + assert self.profile_name(self.owner) == "Original Name" + + +@skip_unless_lms +class NameChangeParityTests(NameChangeTestCase): + """The same requests through the version 1 and the version 2 addresses.""" + + def test_both_versions_record_the_same_request(self): + self.login(self.owner) + earlier = self.client.post(EARLIER_REQUEST, {"name": "Jon Doe"}, format="json") + assert earlier.status_code == status.HTTP_201_CREATED + assert earlier.data is None + earlier_pending = PendingNameChange.objects.get(user=self.owner) + earlier_name, earlier_rationale = earlier_pending.new_name, earlier_pending.rationale + earlier_pending.delete() + + later = self.request_name("Jon Doe") + later_pending = PendingNameChange.objects.get(user=self.owner) + assert (later_pending.new_name, later_pending.rationale) == (earlier_name, earlier_rationale) + assert later.status_code == earlier.status_code + # The one declared difference: the created request is returned as the + # body where version 1 answered with none. + assert later.data == {"name": "Jon Doe"} + + def test_neither_version_records_a_request_from_an_unconfirmed_session(self): + """Both addresses read a session the way the platform reads one, and so refuse the same ones.""" + self.login(self.owner) + self.owner.is_active = False + self.owner.save() + earlier = self.client.post(EARLIER_REQUEST, {"name": "Jon Doe"}, format="json") + later = self.request_name("Jon Doe") + assert earlier.status_code == status.HTTP_401_UNAUTHORIZED + assert later.status_code == earlier.status_code + assert_error_envelope(later, expected_status=401, expected_type_slug="authn") + assert PendingNameChange.objects.count() == 0 + + def test_both_versions_read_a_name_sent_as_a_web_form(self): + """A form posts its fields encoded rather than as JSON, and both addresses take them.""" + self.login(self.owner) + body, encoded = "name=Jon+Doe", "application/x-www-form-urlencoded" + earlier = self.client.post(EARLIER_REQUEST, body, content_type=encoded) + assert earlier.status_code == status.HTTP_201_CREATED + assert self.pending_name(self.owner) == "Jon Doe" + PendingNameChange.objects.get(user=self.owner).delete() + + later = self.client.post(self.request_url, body, content_type=encoded) + assert later.status_code == earlier.status_code + assert self.pending_name(self.owner) == "Jon Doe" + + def test_both_versions_refuse_the_name_the_profile_already_carries(self): + self.login(self.owner) + earlier = self.client.post(EARLIER_REQUEST, {"name": "Original Name"}, format="json") + assert earlier.status_code == status.HTTP_400_BAD_REQUEST + assert earlier.data == { + "new_name": "The profile name given was identical to the current name.", + } + + later = self.request_name("Original Name") + assert later.status_code == earlier.status_code + assert later.data["errors"] == {"name": ["The profile already carries this name."]} + + def test_both_versions_refuse_a_name_carrying_markup(self): + self.login(self.owner) + earlier = self.client.post(EARLIER_REQUEST, {"name": "Jon Doe"}, format="json") + assert earlier.status_code == status.HTTP_400_BAD_REQUEST + assert earlier.data == { + "new_name": ["Name cannot contain the following characters: < >"], + } + + later = self.request_name("Jon Doe") + assert later.status_code == earlier.status_code + assert later.data["errors"] == { + "name": ["Name cannot contain the following characters: < >"], + } + assert PendingNameChange.objects.count() == 0 + + def test_both_versions_confirm_a_request_the_same_way(self): + PendingNameChange.objects.create(user=self.owner, new_name="Jon Doe", rationale="a test") + self.login(self.staff) + earlier = self.client.post(earlier_confirmation(self.owner.username)) + assert earlier.status_code == status.HTTP_204_NO_CONTENT + assert self.profile_name(self.owner) == "Jon Doe" + earlier_history = self.owner.profile.get_meta()["old_names"] + + self.owner.profile.name = "Original Name" + self.owner.profile.save() + PendingNameChange.objects.create(user=self.owner, new_name="Jon Doe", rationale="a test") + later = self.client.post(self.confirmation_url(self.owner.username)) + assert later.status_code == earlier.status_code + assert self.profile_name(self.owner) == "Jon Doe" + later_history = self.owner.profile.get_meta()["old_names"] + assert [entry[:2] for entry in later_history] == [entry[:2] for entry in earlier_history] * 2 + + def test_both_versions_refuse_a_confirmation_from_a_caller_who_is_not_staff(self): + PendingNameChange.objects.create(user=self.owner, new_name="Jon Doe", rationale="a test") + self.login(self.other) + earlier = self.client.post(earlier_confirmation(self.owner.username)) + assert earlier.status_code == status.HTTP_403_FORBIDDEN + assert earlier.data is None + + later = self.client.post(self.confirmation_url(self.owner.username)) + assert later.status_code == earlier.status_code + # The one declared difference: version 1 answers with an empty body. + assert_error_envelope(later, expected_status=403, expected_type_slug="authz") + assert self.profile_name(self.owner) == "Original Name" + + def test_a_name_no_account_holds_is_not_found(self): + """A confirmation addressed to no account is refused before anything is looked up.""" + self.login(self.staff) + later = self.client.post(self.confirmation_url("nobody-at-all")) + assert_error_envelope( + later, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + +#: What each address costs, measured on the version 1 address first and +#: asserted on both. Neither version reads anything per row: the request reads +#: the caller's profile and stores the name asked for, and the confirmation +#: reads the user, their request and their profile before writing the new name +#: and deleting the request. +REQUEST_QUERIES = 20 +CONFIRMATION_QUERIES = 20 + + +@pytest.fixture(name="name_change") +@skip_unless_lms +def name_change_fixture(client, django_user_model): # pylint: disable=unused-argument + """Sign a staff caller in beside the learner whose profile is renamed.""" + staff = UserFactory.create(username="count-name-staff", password=PASSWORD, is_staff=True) + owner = UserFactory.create(username="count-name-owner", password=PASSWORD) + owner.profile.name = "Original Name" + owner.profile.save() + assert client.login(username=staff.username, password=PASSWORD) + # The first authenticated request of a session populates caches the rest + # of the session reuses; the counts below are the steady-state ones. + client.post(reverse("user_v2:name_change_list"), {"name": "Warm Up"}, content_type="application/json") + PendingNameChange.objects.all().delete() + return staff, owner + + +@pytest.mark.django_db +@skip_unless_lms +def test_a_request_costs_what_the_earlier_address_costs(client, name_change, django_assert_num_queries): + body = {"name": "Jon Doe"} + with django_assert_num_queries(REQUEST_QUERIES): + earlier = client.post(EARLIER_REQUEST, body, content_type="application/json") + assert earlier.status_code == status.HTTP_201_CREATED + PendingNameChange.objects.all().delete() + + with django_assert_num_queries(REQUEST_QUERIES): + later = client.post(reverse("user_v2:name_change_list"), body, content_type="application/json") + assert later.status_code == status.HTTP_201_CREATED + + +@pytest.mark.django_db +@skip_unless_lms +def test_a_confirmation_costs_what_the_earlier_address_costs(client, name_change, django_assert_num_queries): + _staff, owner = name_change + + PendingNameChange.objects.create(user=owner, new_name="Jon Doe", rationale="a test") + with django_assert_num_queries(CONFIRMATION_QUERIES): + earlier = client.post(earlier_confirmation(owner.username)) + assert earlier.status_code == status.HTTP_204_NO_CONTENT + + PendingNameChange.objects.create(user=owner, new_name="Jon Doe Again", rationale="a test") + with django_assert_num_queries(CONFIRMATION_QUERIES): + later = client.post( + reverse("user_v2:name_change_confirmation", kwargs={"username": owner.username}), + ) + assert later.status_code == status.HTTP_204_NO_CONTENT diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index de29bdae413e..75a5acd412c6 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -2,6 +2,7 @@ import json from importlib import import_module +from unittest import mock import jsonschema import pytest @@ -9,17 +10,51 @@ from django.urls import reverse from drf_spectacular.generators import SchemaGenerator from drf_spectacular.settings import patched_settings - -from common.djangoapps.student.tests.factories import AdminFactory -from lms.lib.spectacular import SUPERSEDED_USER_PATHS, lms_mark_legacy_paths_deprecated +from waffle.testutils import override_switch + +from common.djangoapps.student.models import PendingNameChange, UserProfile +from common.djangoapps.student.tests.factories import AccountRecoveryFactory, AdminFactory, UserFactory +from lms.djangoapps.verify_student.models import IDVerificationAttempt, VerificationAttempt +from lms.lib.spectacular import ( + RENAMED_OPERATION_IDS, + SUPERSEDED_USER_PATHS, + lms_mark_legacy_paths_deprecated, +) from openedx.core.apidocs import get_api_docs_settings +from openedx.core.djangoapps.profile_images.tests.helpers import make_image_file +from openedx.core.djangoapps.site_configuration.tests.test_util import with_site_configuration_context +from openedx.core.djangoapps.user_api.accounts.image_helpers import ( + get_profile_image_names, + get_profile_image_storage, +) +from openedx.core.djangoapps.user_api.accounts.utils import ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory -from openedx.core.djangoapps.user_api.v2.serializers import TimeZoneQuerySerializer +from openedx.core.djangoapps.user_api.v2.serializers import ( + ACCOUNT_DEFAULT_SORT, + ACCOUNT_MINIMAL_FIELDS, + EXPIRATION_DAY_PATTERN, + AccountQuerySerializer, + TimeZoneQuerySerializer, + VerificationQuerySerializer, +) from openedx.core.djangoapps.user_api.v2.views import PREFERENCE_KEY_PATTERN_PARTIAL from openedx.core.djangolib.testing.utils import skip_unless_lms PASSWORD = "Password1234" +#: Stands for a property a response does not carry, where that is the assertion. +ABSENT = "absent" + +ACCOUNT_LIST_PATH = "/api/user/v2/accounts/" +ACCOUNT_MEMBER_PATH = "/api/user/v2/accounts/{username}/" +ACCOUNT_DEACTIVATION_PATH = "/api/user/v2/accounts/{username}/deactivation/" +PROFILE_IMAGE_PATH = "/api/user/v2/accounts/{username}/profile_image/" +VERIFICATION_STATUS_PATH = "/api/user/v2/accounts/{username}/verification_status/" +VERIFICATION_LIST_PATH = "/api/user/v2/accounts/{username}/verifications/" +EMAIL_SEARCH_PATH = "/api/user/v2/email_searches/" +NAME_CHANGE_PATH = "/api/user/v2/name_changes/" +NAME_CHANGE_CONFIRMATION_PATH = "/api/user/v2/name_changes/{username}/confirmations/" + USER_MEMBER_PATH = "/api/user/v2/users/{username}/" PREFERENCE_MEMBER_PATH = "/api/user/v2/user_preferences/{username},{key}/" TIME_ZONE_LIST_PATH = "/api/user/v2/time_zones/" @@ -27,13 +62,37 @@ #: The addresses that answer with a page of rows, and the ones that answer with #: a single record. LIST_PATHS = { + ACCOUNT_LIST_PATH, + VERIFICATION_LIST_PATH, "/api/user/v2/users/", "/api/user/v2/user_preferences/", TIME_ZONE_LIST_PATH, } -MEMBER_PATHS = {USER_MEMBER_PATH, PREFERENCE_MEMBER_PATH} +MEMBER_PATHS = { + ACCOUNT_MEMBER_PATH, + VERIFICATION_STATUS_PATH, + USER_MEMBER_PATH, + PREFERENCE_MEMBER_PATH, +} + +#: The addresses that act on a resource rather than answer with one. +ACTION_PATHS = { + EMAIL_SEARCH_PATH, + ACCOUNT_DEACTIVATION_PATH, + PROFILE_IMAGE_PATH, + NAME_CHANGE_PATH, + NAME_CHANGE_CONFIRMATION_PATH, +} -VERSION_TWO_PATHS = LIST_PATHS | MEMBER_PATHS +#: The addresses a generated client library is built from. +SDK_PATHS = { + ACCOUNT_LIST_PATH, + ACCOUNT_MEMBER_PATH, + VERIFICATION_STATUS_PATH, + VERIFICATION_LIST_PATH, +} | ACTION_PATHS + +VERSION_TWO_PATHS = LIST_PATHS | MEMBER_PATHS | ACTION_PATHS PAGINATION_MEMBERS = {"count", "num_pages", "current_page", "start", "next", "previous", "results"} @@ -42,10 +101,26 @@ #: The components this version contributes to the document. VERSION_TWO_COMPONENTS = ( + "Account", + "AccountExtendedField", + "AccountLanguage", + "AccountMinimal", + "AccountProfileImage", + "AccountProjection", + "AccountResponse", + "AccountSocialLink", + "EmailSearch", + "EmailSearchResult", "ErrorResponse", + "NameChange", + "PaginatedAccountResponseList", + "PaginatedEmailSearchResultList", + "PaginatedVerificationList", + "PatchedAccountUpdate", "PaginatedTimeZoneList", "PaginatedUserDirectoryResponseList", "PaginatedUserPreferenceRecordResponseList", + "ProfileImageUpload", "TimeZone", "UserDirectory", "UserDirectoryMinimal", @@ -55,43 +130,98 @@ "UserPreferenceRecordMinimal", "UserPreferenceRecordProjection", "UserPreferenceRecordResponse", + "Verification", + "VerificationStatus", ) -#: Every body these endpoints return: the address and parameters that produce -#: it, the published path it is documented under, and the rows it carries. +#: Every body these endpoints return: the published path it is documented +#: under, the address and parameters that produce it, and the component that +#: describes each record the body carries. SHAPE_CASES = ( - ("/api/user/v2/users/", "/api/user/v2/users/", {}), - ("/api/user/v2/users/", "/api/user/v2/users/", {"view": "minimal"}), - ("/api/user/v2/users/", "/api/user/v2/users/", {"fields": "username,email"}), - ("/api/user/v2/users/", "/api/user/v2/users/", {"view": "minimal", "fields": "username"}), - ("/api/user/v2/users/{username}/", "/api/user/v2/users/shape-admin/", {}), - ("/api/user/v2/users/{username}/", "/api/user/v2/users/shape-admin/", {"view": "minimal"}), - ("/api/user/v2/users/{username}/", "/api/user/v2/users/shape-admin/", {"fields": "id,url"}), - ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {}), - ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {"view": "full"}), - ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {"view": "minimal"}), - ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {"fields": "key,value"}), + ("/api/user/v2/users/", "/api/user/v2/users/", {}, "UserDirectory"), + ("/api/user/v2/users/", "/api/user/v2/users/", {"view": "minimal"}, "UserDirectoryMinimal"), + ("/api/user/v2/users/", "/api/user/v2/users/", {"fields": "username,email"}, "UserDirectoryProjection"), + ( + "/api/user/v2/users/", + "/api/user/v2/users/", + {"view": "minimal", "fields": "username"}, + "UserDirectoryProjection", + ), + ("/api/user/v2/users/{username}/", "/api/user/v2/users/shape-admin/", {}, "UserDirectory"), + ( + "/api/user/v2/users/{username}/", + "/api/user/v2/users/shape-admin/", + {"view": "minimal"}, + "UserDirectoryMinimal", + ), + ( + "/api/user/v2/users/{username}/", + "/api/user/v2/users/shape-admin/", + {"fields": "id,url"}, + "UserDirectoryProjection", + ), + ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {}, "UserPreferenceRecord"), + ("/api/user/v2/user_preferences/", "/api/user/v2/user_preferences/", {"view": "full"}, "UserPreferenceRecord"), + ( + "/api/user/v2/user_preferences/", + "/api/user/v2/user_preferences/", + {"view": "minimal"}, + "UserPreferenceRecordMinimal", + ), + ( + "/api/user/v2/user_preferences/", + "/api/user/v2/user_preferences/", + {"fields": "key,value"}, + "UserPreferenceRecordProjection", + ), ( "/api/user/v2/user_preferences/{username},{key}/", "/api/user/v2/user_preferences/shape-admin,pref-lang/", {}, + "UserPreferenceRecord", ), ( "/api/user/v2/user_preferences/{username},{key}/", "/api/user/v2/user_preferences/shape-admin,pref-lang/", {"view": "full"}, + "UserPreferenceRecord", ), ( "/api/user/v2/user_preferences/{username},{key}/", "/api/user/v2/user_preferences/shape-admin,pref-lang/", {"view": "minimal"}, + "UserPreferenceRecordMinimal", ), ( "/api/user/v2/user_preferences/{username},{key}/", "/api/user/v2/user_preferences/shape-admin,pref-lang/", {"fields": "value"}, + "UserPreferenceRecordProjection", + ), + ("/api/user/v2/time_zones/", "/api/user/v2/time_zones/", {"country_code": "FR"}, "TimeZone"), + ("/api/user/v2/accounts/", "/api/user/v2/accounts/", {}, "Account"), + ("/api/user/v2/accounts/", "/api/user/v2/accounts/", {"view": "minimal"}, "AccountMinimal"), + ("/api/user/v2/accounts/", "/api/user/v2/accounts/", {"view": "shared"}, "Account"), + ( + "/api/user/v2/accounts/", + "/api/user/v2/accounts/", + {"fields": "username,email"}, + "AccountProjection", + ), + ("/api/user/v2/accounts/{username}/", "/api/user/v2/accounts/me/", {}, "Account"), + ("/api/user/v2/accounts/{username}/", "/api/user/v2/accounts/shape-admin/", {}, "Account"), + ( + "/api/user/v2/accounts/{username}/", + "/api/user/v2/accounts/shape-admin/", + {"view": "minimal"}, + "AccountMinimal", + ), + ( + "/api/user/v2/accounts/{username}/", + "/api/user/v2/accounts/shape-admin/", + {"fields": "username"}, + "AccountProjection", ), - ("/api/user/v2/time_zones/", "/api/user/v2/time_zones/", {"country_code": "FR"}), ) @@ -113,14 +243,61 @@ def as_json_schema(node): return converted +def published_ordering(schema, path): + """Return the sort parameter a list publishes.""" + return next( + published for published in schema["paths"][path]["get"]["parameters"] + if published["name"] == "ordering" + ) + + def published_body_schema(schema, path): """Return what a successful body of ``path`` must satisfy, components included.""" body = schema["paths"][path]["get"]["responses"]["200"]["content"]["application/json"]["schema"] return as_json_schema({**body, "components": schema["components"]}) + +def published_component_schema(schema, name): + """Return one published component as a document a validator can read on its own.""" + return as_json_schema({ + "$ref": f"#/components/schemas/{name}", + "components": schema["components"], + }) + + +def records_of(body): + """Return the records a body carries, whether it is a page of them or a single one.""" + return body["results"] if "results" in body else [body] + + +def assert_records_match(schema, body, component, case=None): + """ + Assert every record of ``body`` is what the named component says it is. + + A body is checked against the one component that describes it rather than + against the alternatives its address may answer with, because any of those + alternatives accepts a body the others would reject, and a property no + alternative describes is as much a difference as one typed wrongly. + """ + validator = jsonschema.Draft202012Validator(published_component_schema(schema, component)) + published = set(schema["components"]["schemas"][component]["properties"]) + for record in records_of(body): + assert [error.message for error in validator.iter_errors(record)] == [], (case, component, record) + assert set(record) <= published, (case, component, set(record) - published) + #: The version 1 addresses this change supersedes, written out independently of #: the constant the hook reads so that changing either one shows up here. SUPERSEDED_USER_ADDRESSES = { + "/api/user/v1/me": ACCOUNT_MEMBER_PATH, + "/api/user/v1/accounts": ACCOUNT_LIST_PATH, + "/api/user/v1/accounts/search_emails": EMAIL_SEARCH_PATH, + "/api/user/v1/accounts/{username}": ACCOUNT_MEMBER_PATH, + "/api/user/v1/accounts/{username}/deactivate/": ACCOUNT_DEACTIVATION_PATH, + "/api/user/v1/accounts/{username}/image": PROFILE_IMAGE_PATH, + "/api/user/v1/accounts/{username}/verification_status/": VERIFICATION_STATUS_PATH, + "/api/user/v1/accounts/{username}/verifications/": VERIFICATION_LIST_PATH, + "/api/user/v1/accounts/name_change/": NAME_CHANGE_PATH, + "/api/user/v1/accounts/name_change/{username}/confirm/": NAME_CHANGE_CONFIRMATION_PATH, "/api/user/v1/users/": "/api/user/v2/users/", "/api/user/v1/users/{id}/": "/api/user/v2/users/{username}/", "/api/user/v1/user_prefs/": "/api/user/v2/user_preferences/", @@ -191,13 +368,31 @@ def test_version_two_addresses_are_published(schema): @skip_unless_lms -def test_version_two_operations_carry_the_area_tag(schema): +def test_every_operation_of_this_version_is_published_under_one_group(schema): + """ + An operation a client library is generated from carries that mark alone. + + A client takes one class per group, so an operation in two of them is + written into both; every operation the platform generates a library from + carries the one mark, and the rest name the area they belong to. + """ tags = { operation["operationId"]: operation.get("tags") for path, _method, operation in operations(schema) if path in VERSION_TWO_PATHS } assert tags == { + "v2_accounts_list": ["openedx-platform-sdk"], + "v2_accounts_retrieve": ["openedx-platform-sdk"], + "v2_accounts_partial_update": ["openedx-platform-sdk"], + "v2_email_searches_create": ["openedx-platform-sdk"], + "v2_accounts_deactivation_create": ["openedx-platform-sdk"], + "v2_accounts_profile_image_create": ["openedx-platform-sdk"], + "v2_accounts_profile_image_destroy": ["openedx-platform-sdk"], + "v2_accounts_verification_status_retrieve": ["openedx-platform-sdk"], + "v2_accounts_verifications_list": ["openedx-platform-sdk"], + "v2_name_changes_create": ["openedx-platform-sdk"], + "v2_name_changes_confirmations_create": ["openedx-platform-sdk"], "v2_users_list": ["user"], "v2_users_retrieve": ["user"], "v2_user_preferences_list": ["user"], @@ -231,22 +426,23 @@ def test_only_this_version_and_the_addresses_it_supersedes_are_published(schema) def test_addresses_owned_by_other_apps_are_not_published(schema): """Neighbours of the mounts this change adds, including one under its own prefix.""" for path in ( - "/api/user/v1/accounts", - "/api/user/v1/me", + "/api/user/v1/accounts/deactivate_logout/", + "/api/user/v1/accounts/{username}/retirement_status/", "/api/user/v1/preferences/{username}", "/api/user/v1/account/registration/", "/api/user/v2/account/registration/", + "/api/profile_images/v1/{username}/upload", + "/api/profile_images/v1/{username}/remove", ): assert path not in schema["paths"], path @skip_unless_lms def test_pagination_envelope_is_published_in_full(schema): - for component in ( - "PaginatedUserDirectoryResponseList", - "PaginatedUserPreferenceRecordResponseList", - "PaginatedTimeZoneList", - ): + """Every paged body this version publishes carries the whole envelope, not DRF's four members.""" + paged = [name for name in VERSION_TWO_COMPONENTS if name.startswith("Paginated")] + assert len(paged) == 6 + for component in paged: published = schema["components"]["schemas"][component] assert set(published["properties"]) == PAGINATION_MEMBERS, component @@ -264,14 +460,33 @@ def test_published_pagination_envelope_matches_the_response_body(client, schema) @skip_unless_lms def test_error_responses_reference_the_shared_envelope(schema): + """One refusal carries more than the envelope, and it is the only one that may.""" + extends_the_envelope = {(ACCOUNT_LIST_PATH, "get", "404"): "RetiredAccountErrorResponse"} for path, method, operation in operations(schema): if path not in VERSION_TWO_PATHS: continue for code, response in operation["responses"].items(): - if not code.startswith("4"): + if not code.startswith(("4", "5")): continue + component = extends_the_envelope.get((path, method, code), "ErrorResponse") schema_ref = response["content"]["application/json"]["schema"] - assert schema_ref == {"$ref": "#/components/schemas/ErrorResponse"}, (path, method, code) + assert schema_ref == {"$ref": f"#/components/schemas/{component}"}, (path, method, code) + + +@skip_unless_lms +def test_a_refusal_that_does_not_depend_on_the_resource_reads_the_same_at_every_address(schema): + """Each of these codes is published with one text, whichever resource of this version answers it.""" + published = {"401": set(), "415": set()} + for path, _method, operation in operations(schema): + if path not in VERSION_TWO_PATHS: + continue + for code, response in operation["responses"].items(): + if code in published: + published[code].add(response["description"]) + assert published == { + "401": {"The requester is not authenticated."}, + "415": {"The request body is in a media type this endpoint cannot read."}, + } @skip_unless_lms @@ -285,6 +500,9 @@ def test_an_operation_that_takes_a_response_preset_publishes_the_refusal(schema) and "400" in operation["responses"] ] assert sorted(takes_a_preset) == [ + (ACCOUNT_LIST_PATH, "get"), + (ACCOUNT_MEMBER_PATH, "get"), + (ACCOUNT_MEMBER_PATH, "patch"), ("/api/user/v2/user_preferences/", "get"), ("/api/user/v2/user_preferences/{username},{key}/", "get"), ("/api/user/v2/users/", "get"), @@ -328,16 +546,25 @@ def test_enum_post_processing_runs_before_the_deprecation_hook(): def test_hook_leaves_other_resources_alone(): """The hook marks only the addresses it lists, even among their neighbours.""" untouched = [ - "/api/user/v1/accounts", - "/api/user/v1/me", + "/api/profile_images/v1/{username}/upload", + "/api/profile_images/v1/{username}/remove", + "/api/user/v1/accounts/deactivate_logout/", "/api/user/v1/preferences/email_opt_in/", "/api/user/v2/account/registration/", "/user_api/v1/users/", + "/user_api/v1/accounts/{username}", "/user_api/v1/preferences/time_zones/", "/api/enrollment/v2/enrollments/", "/api/courses/v1/courses/", ] - marked = ["/api/user/v1/users/", "/api/enrollment/v2/enrollments"] + marked = [ + "/api/user/v1/users/", + "/api/user/v1/accounts", + "/api/user/v1/accounts/{username}", + "/api/user/v1/accounts/{username}/image", + "/api/user/v1/accounts/name_change/", + "/api/enrollment/v2/enrollments", + ] result = {"paths": {path: {"get": {"operationId": path}} for path in untouched + marked}} lms_mark_legacy_paths_deprecated(result, generator=None, request=None, public=True) @@ -356,6 +583,46 @@ def test_every_superseded_address_has_a_published_replacement(schema): assert replacement in schema["paths"] +#: The media types each superseded body is published in, by address and method. +SUPERSEDED_REQUEST_MEDIA_TYPES = { + ("/api/user/v1/accounts/{username}", "patch"): {"application/merge-patch+json"}, + ("/api/user/v1/accounts/search_emails", "post"): { + "application/json", "application/merge-patch+json", + }, +} + + +@pytest.mark.django_db +@skip_unless_lms +def test_each_superseded_body_is_published_in_the_media_types_that_address_reads(client, schema): + """ + Every media type published for a superseded body is sent to that address here. + + Those bodies are named for addresses whose views name no serializer, and a + shape named on its own is published in every media type the view's parsers + accept, which can be more than the handler reads. A generated client sends + the first type the document offers, so each one is answered by the running + endpoint here, and a type the document leaves out is sent as well. + """ + staff = AdminFactory.create(username="media_type_staff", password=PASSWORD) + assert client.login(username=staff.username, password=PASSWORD) + member = f"/api/user/v1/accounts/{staff.username}" + requests = { + ("/api/user/v1/accounts/{username}", "patch"): (member, "{}"), + ("/api/user/v1/accounts/search_emails", "post"): ( + "/api/user/v1/accounts/search_emails", json.dumps({"emails": [staff.email]}), + ), + } + for (path, method), media_types in SUPERSEDED_REQUEST_MEDIA_TYPES.items(): + assert set(schema["paths"][path][method]["requestBody"]["content"]) == media_types, path + address, body = requests[(path, method)] + for media_type in media_types: + answer = getattr(client, method)(address, data=body, content_type=media_type) + assert answer.status_code == 200, (address, media_type, answer.content) + left_out = client.patch(member, data="{}", content_type="application/json") + assert left_out.status_code == 415 + + @pytest.mark.django_db @skip_unless_lms def test_this_version_only_adds_to_the_service_wide_document(): @@ -407,14 +674,74 @@ def test_every_response_shape_is_published(schema): ), component +#: A value for every property of a profile an account carries, so that a body +#: checked against its component carries a value the component has to accept +#: rather than a null every type accepts. +FILLED_IN_PROFILE = { + "bio": "Teaches mathematics.", + "city": "Cambridge", + "country": "US", + "gender": "f", + "goals": "Finish the course.", + "level_of_education": "m", + "mailing_address": "12 Park Avenue", + "phone_number": "+18005555555", + "state": "MA", + "year_of_birth": 1985, +} + +#: The properties of an account that only a filled-in one carries: each is held +#: outside the profile, or is left null by a user who never gave it. +FILLED_IN_ONLY_PROPERTIES = ( + "country", + "level_of_education", + "mailing_address", + "pending_name_change", + "phone_number", + "secondary_email", + "state", + "verified_name", +) + + +def fill_in(user): + """Give the user's profile a value for each property it holds, and a name change outstanding.""" + for name, value in FILLED_IN_PROFILE.items(): + setattr(user.profile, name, value) + user.profile.save() + user.profile.language_proficiencies.create(code="fr") + user.profile.social_links.create(platform="twitter", social_link="https://www.twitter.com/example") + PendingNameChange.objects.create( + user=user, new_name="Changed Name", rationale="Asked for in a test", + ) + return user + + +def name_affirmation_answering(verified_name): + """ + Return a patch installing a name affirmation service that holds one accepted name. + + The service is an optional install, and the property it fills is null + wherever it is absent, so the account that carries one is built with a + stand-in rather than left untested on the sites that do not have it. + """ + service = mock.Mock() + service.get_verified_name.return_value = mock.Mock(verified_name=verified_name) + return mock.patch( + "openedx.core.djangoapps.user_api.accounts.serializers.get_name_affirmation_service", + return_value=service, + ) + + @pytest.mark.django_db @skip_unless_lms def test_published_shapes_accept_every_body_the_endpoints_return(client, schema): """Every preset and selection the parameters offer returns a body the document describes.""" admin = AdminFactory.create(username="shape-admin", password=PASSWORD) UserPreferenceFactory.create(user=admin, key="pref-lang", value="en") + fill_in(admin) assert client.login(username=admin.username, password=PASSWORD) - for published_path, address, params in SHAPE_CASES: + for published_path, address, params, component in SHAPE_CASES: case = (address, params) response = client.get(address, params) assert response.status_code == 200, case @@ -423,6 +750,7 @@ def test_published_shapes_accept_every_body_the_endpoints_return(client, schema) assert body["count"] == 1, case validator = jsonschema.Draft202012Validator(published_body_schema(schema, published_path)) assert [error.message for error in validator.iter_errors(body)] == [], case + assert_records_match(schema, body, component, case) @skip_unless_lms @@ -443,13 +771,15 @@ def test_sort_parameter_publishes_the_fields_it_accepts(schema): @skip_unless_lms def test_every_list_publishes_the_page_that_does_not_exist(schema): """Asking for a page past the end of a list is answered 404, so each list documents it.""" - assert LIST_PATHS | MEMBER_PATHS == set(VERSION_TWO_PATHS) + assert LIST_PATHS | MEMBER_PATHS | ACTION_PATHS == set(VERSION_TWO_PATHS) documented = { path: sorted(operation["responses"]) for path, _method, operation in operations(schema) if path in LIST_PATHS } assert documented == { + ACCOUNT_LIST_PATH: ["200", "400", "401", "403", "404"], + VERIFICATION_LIST_PATH: ["200", "400", "401", "403", "404"], "/api/user/v2/users/": ["200", "400", "401", "403", "404"], "/api/user/v2/user_preferences/": ["200", "400", "401", "403", "404"], TIME_ZONE_LIST_PATH: ["200", "400", "404"], @@ -468,6 +798,28 @@ def test_member_addresses_describe_the_parts_they_are_built_from(schema): if parameter["in"] == "path" } assert published == { + (ACCOUNT_MEMBER_PATH, "username"): { + "in": "path", + "name": "username", + "required": True, + "schema": username_schema, + "description": ( + "Unique name of the user whose account is addressed. `me` names the account of " + "the caller, so an account holding that name is read through the collection, " + "with `username=` naming it." + ), + }, + (VERIFICATION_STATUS_PATH, "username"): { + "in": "path", + "name": "username", + "required": True, + "schema": username_schema, + "description": ( + "Unique name of the user whose identity verification is addressed. The name is " + "read as it is stored, so `me` here names an account holding that name rather " + "than the account of the caller making the request." + ), + }, (USER_MEMBER_PATH, "username"): { "in": "path", "name": "username", @@ -529,3 +881,848 @@ def test_published_text_is_written_for_the_clients_that_read_it(schema): assert schema["components"]["schemas"]["ErrorResponse"]["description"].startswith( "The body of every unsuccessful response." ) + + +@skip_unless_lms +def test_the_library_tag_marks_the_addresses_a_client_is_built_from_and_nothing_else(schema): + """The operations a generated client library is built from say so, one by one.""" + tagged = { + path for path, _method, operation in operations(schema) + if path.startswith("/api/user/") and "openedx-platform-sdk" in (operation.get("tags") or []) + } + assert tagged == SDK_PATHS + + +@skip_unless_lms +def test_account_list_publishes_its_selectors(schema): + parameters = { + parameter["name"]: parameter + for parameter in schema["paths"][ACCOUNT_LIST_PATH]["get"]["parameters"] + } + assert set(parameters) == { + "email", "fields", "lms_user_id", "ordering", "page", "page_size", "username", "view", + } + assert parameters["lms_user_id"]["schema"] == {"type": "integer"} + # An empty value narrows nothing, the way an empty value of any other + # parameter does, and is published as one the parameter accepts. + assert parameters["view"]["schema"]["enum"] == ["minimal", "shared", ""] + assert parameters["ordering"]["schema"]["enum"] == ["username", "-username", ""] + assert parameters["ordering"]["schema"]["default"] == ACCOUNT_DEFAULT_SORT == "username" + assert [name for name, parameter in parameters.items() if parameter.get("deprecated")] == [] + + +@skip_unless_lms +def test_the_selectors_are_published_from_the_serializer_that_validates_them(schema): + """The constraint a caller is held to is the one the published parameter carries.""" + declared = AccountQuerySerializer().fields + published = { + parameter["name"]: parameter + for parameter in schema["paths"][ACCOUNT_LIST_PATH]["get"]["parameters"] + } + for name, field in declared.items(): + assert published[name]["description"].startswith(field.help_text), name + assert "required" not in published[name], name + assert published["view"]["description"].endswith( + "* `minimal` - The properties that identify the account's owner\n" + "* `shared` - The properties the owner shares with everybody", + ) + + +@skip_unless_lms +def test_the_education_levels_published_are_the_ones_a_profile_stores(schema): + """Every code the profile offers is named where the property is published, both read and written.""" + offered = [code for code, _label in UserProfile.LEVEL_OF_EDUCATION_CHOICES] + assert offered == ["p", "m", "b", "a", "hs", "jhs", "el", "none", "other"] + for component in ("Account", "PatchedAccountUpdate"): + published = schema["components"]["schemas"][component]["properties"]["level_of_education"] + assert [code for code in offered if f"`{code}`" in published["description"]] == offered, component + + +@skip_unless_lms +def test_a_change_publishes_the_body_it_reads_and_the_media_type_it_reads_it_in(schema): + request = schema["paths"][ACCOUNT_MEMBER_PATH]["patch"]["requestBody"] + assert set(request["content"]) == {"application/merge-patch+json"} + assert request["content"]["application/merge-patch+json"]["schema"] == { + "$ref": "#/components/schemas/PatchedAccountUpdate", + } + changeable = schema["components"]["schemas"]["PatchedAccountUpdate"] + assert "required" not in changeable + assert {"email", "name", "bio", "social_links", "extended_profile"} <= set(changeable["properties"]) + assert "username" not in changeable["properties"] + + +@pytest.mark.django_db +@skip_unless_lms +def test_the_order_the_account_list_publishes_as_its_default_is_the_one_it_answers_with(client, schema): + """ + The default is read off the document and asked of the running list. + + An order stated in the document and an order applied in the handler are + two declarations of one thing, and a client that omits the parameter is + answered by the second while it was built from the first. + """ + parameter = next( + published for published in schema["paths"][ACCOUNT_LIST_PATH]["get"]["parameters"] + if published["name"] == "ordering" + ) + default = parameter["schema"]["default"] + staff = AdminFactory.create(username="sorting_staff", password=PASSWORD) + for name in ("sorted_c", "sorted_a", "sorted_b"): + UserFactory.create(username=name) + assert client.login(username=staff.username, password=PASSWORD) + selection = {"username": "sorted_c,sorted_a,sorted_b"} + + omitted = client.get(ACCOUNT_LIST_PATH, selection) + assert [row["username"] for row in omitted.json()["results"]] == [ + "sorted_a", "sorted_b", "sorted_c", + ] + asked_for = client.get(ACCOUNT_LIST_PATH, {**selection, "ordering": default}) + assert [row["username"] for row in asked_for.json()["results"]] == [ + "sorted_a", "sorted_b", "sorted_c", + ] + the_other_way = client.get(ACCOUNT_LIST_PATH, {**selection, "ordering": f"-{default}"}) + assert [row["username"] for row in the_other_way.json()["results"]] == [ + "sorted_c", "sorted_b", "sorted_a", + ] + + +@pytest.mark.django_db +@skip_unless_lms +def test_every_property_the_change_publishes_a_null_for_is_cleared_by_one(client, schema): + """ + A null is sent for each property published as taking one, and is answered. + + A generated client offers a null exactly where the body publishes one, so + each of those is a change this endpoint has to carry out rather than fail + on, and a property that cannot be cleared this way belongs outside the set. + """ + published = schema["components"]["schemas"]["PatchedAccountUpdate"]["properties"] + takes_a_null = sorted(name for name, shape in published.items() if shape.get("nullable")) + assert takes_a_null == [ + "account_privacy", "city", "country", "gender", "goals", "level_of_education", + "mailing_address", "state", "year_of_birth", + ] + owner = UserFactory.create(username="clearing_owner", password=PASSWORD) + assert client.login(username=owner.username, password=PASSWORD) + address = f"/api/user/v2/accounts/{owner.username}/" + for name in takes_a_null: + answer = client.patch( + address, data=json.dumps({name: None}), content_type="application/merge-patch+json", + ) + assert answer.status_code == 200, (name, answer.content) + # The account the last change answered with holds every one of them cleared, + # bar the city, which a change carries and no response does. + account = answer.json() + assert {name: account.get(name, ABSENT) for name in takes_a_null} == { + # Clearing the visibility choice hands the account back to the visibility + # the site gives an account whose profile does not say how old its owner + # is, the year of birth having been cleared here as well. + "account_privacy": "private", + "city": ABSENT, + "country": None, + "gender": None, + "goals": None, + "level_of_education": None, + "mailing_address": None, + "state": None, + "year_of_birth": None, + } + + +@skip_unless_lms +def test_a_change_publishes_the_refusals_only_it_can_answer_with(schema): + assert sorted(schema["paths"][ACCOUNT_MEMBER_PATH]["patch"]["responses"]) == [ + "200", "400", "401", "403", "404", "415", "429", "500", + ] + assert schema["paths"][ACCOUNT_MEMBER_PATH]["patch"]["responses"]["500"]["description"] == ( + "The change was asked for correctly and could not be carried out. Sending it again " + "with something else in it does not help; sending the same request later may." + ) + assert sorted(schema["paths"][ACCOUNT_MEMBER_PATH]["get"]["responses"]) == [ + "200", "400", "401", "403", "404", + ] + + +@skip_unless_lms +def test_the_operations_that_read_a_body_publish_the_refusal_of_one_they_cannot_read(schema): + """A body the endpoint cannot parse is the caller's fault, and every such address says so.""" + for path, method in ( + (ACCOUNT_MEMBER_PATH, "patch"), + (EMAIL_SEARCH_PATH, "post"), + (NAME_CHANGE_PATH, "post"), + ): + assert schema["paths"][path][method]["responses"]["400"]["description"] == ( + "The request body is not well formed in the media type it was sent in, or carries a " + "value this endpoint will not take. A query parameter this endpoint does not read is " + "refused here too." + ), path + assert schema["paths"][PROFILE_IMAGE_PATH]["post"]["responses"]["400"]["description"] == ( + "The request carries no usable image: none was sent, the body is not well formed in the " + "media type it was sent in, one sent as the whole body was sent without a name or under a " + "name whose extension names another media type, the image is of a type or a size this " + "site does not take, or no picture can be drawn from the file, whose bytes may stop " + "early, carry metadata that does not parse, or declare more pixels than this site draws. " + "A query parameter this endpoint does not read is refused here too." + ) + + +@skip_unless_lms +def test_the_operations_only_an_owner_reaches_publish_the_cause_their_refusal_really_has(schema): + """ + Where only the owner is admitted, nothing is published as missing that is refused instead. + + A name nobody holds is not the caller's own, so these operations refuse it + as another account's rather than report it absent. What is left for the + absent answer is an account whose profile is gone, and that is what the + document describes, so a client reading one of these branches meets it. + """ + assert schema["paths"][ACCOUNT_MEMBER_PATH]["patch"]["responses"]["404"]["description"] == ( + "The account that was addressed is no longer there. Only the caller's own account is " + "changed here, so a name nobody holds is refused as somebody else's account instead of " + "being reported as missing." + ) + for method in ("post", "delete"): + assert schema["paths"][PROFILE_IMAGE_PATH][method]["responses"]["404"]["description"] == ( + "The account at this address carries no profile to record an image on. A name no " + "account holds is refused as somebody else's image instead of being reported here." + ), method + assert schema["paths"][NAME_CHANGE_PATH]["post"]["responses"]["404"]["description"] == ( + "The account of the caller carries no profile to put a name on." + ) + + +@skip_unless_lms +def test_the_search_publishes_the_addresses_it_reads_and_the_page_it_answers_with(schema): + operation = schema["paths"][EMAIL_SEARCH_PATH]["post"] + assert operation["requestBody"]["content"]["application/json"]["schema"] == { + "$ref": "#/components/schemas/EmailSearch", + } + assert operation["responses"]["200"]["content"]["application/json"]["schema"] == { + "$ref": "#/components/schemas/PaginatedEmailSearchResultList", + } + assert set( + schema["components"]["schemas"]["PaginatedEmailSearchResultList"]["properties"], + ) == PAGINATION_MEMBERS + # The most addresses one search may name is published, so a client knows + # the bound before it sends a body the search will refuse. + addresses = schema["components"]["schemas"]["EmailSearch"]["properties"]["emails"] + assert addresses["type"] == "array" + assert addresses["maxItems"] == 100 + assert sorted(operation["responses"]) == ["200", "400", "401", "403", "404", "415"] + # The page is the only thing it reads from the query string. + assert [parameter["name"] for parameter in operation["parameters"]] == ["page", "page_size"] + + +@skip_unless_lms +def test_a_deactivation_publishes_that_it_answers_with_nothing(schema): + operation = schema["paths"][ACCOUNT_DEACTIVATION_PATH]["post"] + assert "requestBody" not in operation + assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404"] + assert "content" not in operation["responses"]["204"] + assert operation["responses"]["204"]["description"] == "The account was deactivated." + + +@skip_unless_lms +def test_the_name_a_deactivation_disables_is_published_as_a_stored_one(schema): + """``me`` names the caller where an account is read, and a stored account where one is disabled.""" + disabled = { + parameter["name"]: parameter + for parameter in schema["paths"][ACCOUNT_DEACTIVATION_PATH]["post"]["parameters"] + } + assert disabled["username"]["description"] == ( + "Unique name of the user whose account is deactivated. The name is read as it is " + "stored, `me` included: this action disables the account the address names, never the " + "account of the caller making the request." + ) + + +#: The properties of an account that always carry a value when they are sent. +ALWAYS_VALUED_ACCOUNT_PROPERTIES = {"account_privacy", "date_joined", "email", "id", "is_active", "username"} + +#: The properties a profile holds, which an account without one answers with null. +PROFILE_HELD_PROPERTIES = ( + "extended_profile", + "language_proficiencies", + "profile_image", + "requires_parental_consent", + "social_links", +) + + +@skip_unless_lms +def test_an_account_is_published_with_the_properties_visibility_decides(schema): + """Only the properties every caller may see are published as always present.""" + components = schema["components"]["schemas"] + assert components["AccountResponse"]["anyOf"] == [ + {"$ref": "#/components/schemas/Account"}, + {"$ref": "#/components/schemas/AccountMinimal"}, + {"$ref": "#/components/schemas/AccountProjection"}, + ] + assert sorted(components["Account"]["required"]) == [ + "account_privacy", "profile_image", "username", + ] + assert set(components["Account"]["properties"]) == set( + settings.ACCOUNT_VISIBILITY_CONFIGURATION["admin_fields"], + ) + assert sorted(components["AccountMinimal"]["required"]) == ["profile_image", "username"] + assert set(components["AccountMinimal"]["properties"]) == { + "username", "email", "name", "profile_image", + } + assert "required" not in components["AccountProjection"] + + +@skip_unless_lms +def test_an_account_publishes_which_of_its_properties_can_come_back_without_a_value(schema): + """A property that is only sometimes held has to be published as one that can be null.""" + components = schema["components"]["schemas"] + properties = components["Account"]["properties"] + assert { + name for name, published in properties.items() if not published.get("nullable") + } == ALWAYS_VALUED_ACCOUNT_PROPERTIES + extra_field_value = components["AccountExtendedField"]["properties"]["field_value"] + assert "type" not in extra_field_value, "an extra field answers with whatever the site stored in it" + + +def account_owner(client, username, **profile_values): + """Create a user old enough to share a profile, sign them in, and return them.""" + user = UserFactory.create(username=username, password=PASSWORD) + user.profile.year_of_birth = 1985 + for name, value in profile_values.items(): + setattr(user.profile, name, value) + user.profile.save() + assert client.login(username=username, password=PASSWORD) + return user + + +@pytest.mark.django_db +@skip_unless_lms +def test_an_owner_reading_their_account_where_no_recovery_address_is_collected(client, schema): + """The site collects no recovery address, which the account says by carrying none.""" + account_owner(client, "shape-owner") + with override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=False): + body = client.get("/api/user/v2/accounts/me/").json() + assert body["secondary_email_enabled"] is None + assert body["secondary_email"] is None + assert_records_match(schema, body, "Account") + + +@pytest.mark.django_db +@skip_unless_lms +def test_an_owner_reading_their_account_where_a_recovery_address_is_collected(client, schema): + """The other side of the same choice: the account says the site collects one.""" + account_owner(client, "shape-owner") + with override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=True): + body = client.get("/api/user/v2/accounts/me/").json() + assert body["secondary_email_enabled"] is True + assert body["secondary_email"] is None + assert_records_match(schema, body, "Account") + + +@pytest.mark.django_db +@skip_unless_lms +def test_a_staff_caller_reading_an_account_that_has_no_profile(client, schema): + """Every property a profile holds comes back null for an account that has none.""" + staff = AdminFactory.create(username="shape-staff", password=PASSWORD) + profileless = UserFactory.create(username="shape-profileless", password=PASSWORD) + profileless.profile.delete() + assert client.login(username=staff.username, password=PASSWORD) + body = client.get("/api/user/v2/accounts/shape-profileless/").json() + assert {name: body[name] for name in PROFILE_HELD_PROPERTIES} == dict.fromkeys(PROFILE_HELD_PROPERTIES) + assert_records_match(schema, body, "Account") + + +@pytest.mark.django_db +@skip_unless_lms +def test_a_learner_reading_an_account_whose_owner_shares_it_with_everybody(client, schema): + """A profile shared with all users carries more than the properties everybody may see.""" + shared = UserFactory.create(username="shape-shared", password=PASSWORD) + shared.profile.year_of_birth = 1985 + shared.profile.bio = "Teaches mathematics." + shared.profile.save() + account_owner(client, "shape-reader") + body = client.get("/api/user/v2/accounts/shape-shared/").json() + assert body["account_privacy"] == "all_users" + assert body["bio"] == "Teaches mathematics." + assert body["course_certificates"] is None + assert_records_match(schema, body, "Account") + + +@pytest.mark.django_db +@skip_unless_lms +def test_an_owner_reading_their_account_on_a_site_that_collects_extra_profile_fields(client, schema): + """An extra field answers with the value the site stored, which is not always text.""" + owner = account_owner(client, "shape-owner") + owner.profile.meta = json.dumps({"department": None, "age": 41}) + owner.profile.save() + with with_site_configuration_context(configuration={"extended_profile_fields": ["department", "age"]}): + body = client.get("/api/user/v2/accounts/me/").json() + assert body["extended_profile"] == [ + {"field_name": "department", "field_value": None}, + {"field_name": "age", "field_value": 41}, + ] + assert_records_match(schema, body, "Account") + + +@pytest.mark.django_db +@skip_unless_lms +def test_an_account_holding_a_value_for_every_property_matches_its_component(client, schema): + """ + An account with every property valued is checked against the component. + + A property a body only ever carries as null is one no validator can tell + the published type of, so this account holds what a profile, an + outstanding name change, a recovery address and an accepted name give it. + + This is also the one body the component is held to in both directions. + Elsewhere a record may carry fewer properties than the component + describes, because an owner shares only some of theirs; here the account + is the caller's own and carries every property the answer can hold, so a + property the component promises and this account no longer carries is a + promise to a client that nothing else would catch. + """ + owner = account_owner(client, "shape-filled") + fill_in(owner) + AccountRecoveryFactory.create(user=owner, secondary_email="shape-filled-recovery@example.com") + with override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=True): + with name_affirmation_answering("Checked Name"): + body = client.get("/api/user/v2/accounts/me/").json() + assert {name: body[name] for name in FILLED_IN_ONLY_PROPERTIES} == { + "country": "US", + "level_of_education": "m", + "mailing_address": "12 Park Avenue", + "pending_name_change": "Changed Name", + "phone_number": "+18005555555", + "secondary_email": "shape-filled-recovery@example.com", + "state": "MA", + "verified_name": "Checked Name", + } + assert body["bio"] == "Teaches mathematics." + assert body["gender"] == "f" + assert body["goals"] == "Finish the course." + assert body["year_of_birth"] == 1985 + assert body["language_proficiencies"] == [{"code": "fr"}] + assert body["social_links"] == [ + {"platform": "twitter", "social_link": "https://www.twitter.com/example"}, + ] + assert_records_match(schema, body, "Account") + assert set(body) == set(schema["components"]["schemas"]["Account"]["properties"]) + + +@pytest.mark.django_db +@skip_unless_lms +def test_a_change_body_built_from_what_the_document_publishes_is_one_the_endpoint_applies(client, schema): + """ + The published change body is checked by sending one and reading the answer. + + A body a generated client builds comes from the request component alone, + so each property it offers is sent here with a value of the type it + publishes, and the account that comes back has to hold every one of them. + """ + account_owner(client, "shape-changer") + change = { + "bio": "Teaches mathematics.", + "country": "US", + "gender": "f", + "goals": "Finish the course.", + "level_of_education": "m", + "mailing_address": "12 Park Avenue", + "name": "Changed Name", + "phone_number": "+18005555555", + "state": "MA", + "year_of_birth": 1985, + } + validator = jsonschema.Draft202012Validator(published_component_schema(schema, "PatchedAccountUpdate")) + assert [error.message for error in validator.iter_errors(change)] == [] + answer = client.patch( + "/api/user/v2/accounts/me/", + data=json.dumps(change), + content_type="application/merge-patch+json", + ) + assert answer.status_code == 200, answer.content + account = answer.json() + assert {name: account[name] for name in change} == change + assert_records_match(schema, account, "Account") + + +@skip_unless_lms +def test_the_refusal_for_a_retired_email_address_publishes_what_it_adds_to_the_envelope(schema): + """The two members that refusal carries beyond the envelope are typed, not left to be guessed.""" + components = schema["components"]["schemas"] + published = components["RetiredAccountErrorResponse"] + assert set(components["ErrorResponse"]["properties"]) < set(published["properties"]) + assert published["properties"]["can_cancel_retirement"] == { + "type": "boolean", + "description": ( + "Whether the retirement can still be reversed, which it can only while it is inside " + "the cooling-off period." + ), + } + assert published["properties"]["retirement_id"] == { + "type": "integer", + "nullable": True, + "description": ( + "Identifies the retirement to a caller able to reverse it, or null when there is " + "nothing left to reverse." + ), + } + assert published["required"] == components["ErrorResponse"]["required"] + refusal = schema["paths"][ACCOUNT_LIST_PATH]["get"]["responses"]["404"] + assert refusal["content"]["application/json"]["schema"] == { + "$ref": "#/components/schemas/RetiredAccountErrorResponse", + } + + +@skip_unless_lms +def test_the_version_one_account_addresses_keep_an_operation_id_of_their_own(schema): + """The collection and the member tokenize alike, and are published apart.""" + published = { + (path, method): operation["operationId"] + for path, method, operation in operations(schema) + if path in SUPERSEDED_USER_ADDRESSES + } + assert published[("/api/user/v1/accounts", "get")] == "v1_accounts_list" + assert published[("/api/user/v1/accounts/{username}", "get")] == "v1_accounts_retrieve" + assert published[("/api/user/v1/accounts/{username}", "patch")] == "v1_accounts_partial_update" + assert len(set(published.values())) == len(published) + + +@skip_unless_lms +def test_each_renamed_operation_id_names_an_address_in_the_document_that_derives_it(schema): + """ + A rename that outlived the address it was written for would name nothing. + + An entry is keyed by the id the generator derives, which differs between the + document that trims the area off the front of each path and the one that + trims nothing, so each entry applies to exactly one of them. + """ + documents = {"this version": schema, "service-wide": service_wide_schema()} + for (path, method, _derived), operation_id in RENAMED_OPERATION_IDS.items(): + naming = [ + name for name, document in documents.items() + if document["paths"].get(path, {}).get(method.lower(), {}).get("operationId") == operation_id + ] + assert len(naming) == 1, (path, method, operation_id, naming) + + +@skip_unless_lms +def test_a_name_change_publishes_the_body_it_reads_and_the_one_it_returns(schema): + operation = schema["paths"][NAME_CHANGE_PATH]["post"] + # A name is posted from a web form as often as it is sent as JSON, so the + # media types a form submits in are published alongside it. + assert set(operation["requestBody"]["content"]) == { + "application/json", "application/x-www-form-urlencoded", "multipart/form-data", + } + for media_type in operation["requestBody"]["content"]: + assert operation["requestBody"]["content"][media_type]["schema"] == { + "$ref": "#/components/schemas/NameChange", + }, media_type + assert operation["responses"]["201"]["content"]["application/json"]["schema"] == { + "$ref": "#/components/schemas/NameChange", + } + assert sorted(operation["responses"]) == ["201", "400", "401", "404", "415"] + published = schema["components"]["schemas"]["NameChange"] + assert published["required"] == ["name"] + assert published["properties"]["name"]["maxLength"] == 255 + assert published["properties"]["name"]["description"] == ( + "Full name to put on the profile once the request is confirmed." + ) + + +@skip_unless_lms +def test_a_confirmation_publishes_that_it_reads_nothing_and_answers_with_nothing(schema): + operation = schema["paths"][NAME_CHANGE_CONFIRMATION_PATH]["post"] + assert "requestBody" not in operation + assert operation["responses"]["204"]["description"] == ( + "The profile now carries the name that was asked for." + ) + assert "content" not in operation["responses"]["204"] + assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404"] + + +#: Every form an image may be sent in: the media type, the name a body sent in +#: that type carries, and the extension of the image to send. The extension of +#: the name is held against the media type, and a form part carries its own +#: name, so it needs none. +IMAGE_UPLOAD_FORMS = ( + ("multipart/form-data", None, ".jpeg"), + ("image/gif", "picture.gif", ".gif"), + ("image/jpeg", "picture.jpg", ".jpg"), + ("image/pjpeg", "picture.jpg", ".jpg"), + ("image/png", "picture.png", ".png"), +) + +#: The address the image upload supersedes, which reads the same forms. +SUPERSEDED_IMAGE_PATH = "/api/user/v1/accounts/{username}/image" + + +@skip_unless_lms +def test_the_profile_image_publishes_every_media_type_it_reads_the_image_in(schema): + """The image is read as a part of a form or as the whole body, and both are published.""" + operation = schema["paths"][PROFILE_IMAGE_PATH]["post"] + content = operation["requestBody"]["content"] + assert set(content) == {media_type for media_type, _name, _extension in IMAGE_UPLOAD_FORMS} + assert operation["requestBody"]["required"] is True + assert content["multipart/form-data"]["schema"] == { + "$ref": "#/components/schemas/ProfileImageUpload", + } + for media_type in set(content) - {"multipart/form-data"}: + assert content[media_type]["schema"] == {"type": "string", "format": "binary"}, media_type + header = [ + parameter for parameter in operation["parameters"] if parameter["in"] == "header" + ] + assert [parameter["name"] for parameter in header] == ["Content-Disposition"] + assert header[0].get("required", False) is False + assert 'filename="picture.png"' in header[0]["description"] + published = schema["components"]["schemas"]["ProfileImageUpload"] + assert published["required"] == ["file"] + assert published["properties"]["file"] == { + "type": "string", + "format": "binary", + "description": ( + "Image to show beside the user's name. It is stored in each size the site renders, " + "cropped to a square, and must be a JPEG, PNG or GIF within the size limits this " + "site configures." + ), + } + assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404", "415"] + + +@pytest.mark.django_db +@skip_unless_lms +def test_every_media_type_published_for_an_image_is_one_the_endpoint_stores_it_from(client, schema): + """ + Each form the document offers for an image is sent to the endpoints that serve it. + + A client generated from the document sends one of the published types, so + a type published at either address and refused there would leave such a + client with no way to set an image. Both addresses read the same forms and + publish the same list, which is read from the document here rather than + written out again. + """ + owner = UserFactory.create(username="image_media_types", password=PASSWORD) + assert client.login(username=owner.username, password=PASSWORD) + addresses = { + SUPERSEDED_IMAGE_PATH: f"/api/user/v1/accounts/{owner.username}/image", + PROFILE_IMAGE_PATH: f"/api/user/v2/accounts/{owner.username}/profile_image/", + } + storage = get_profile_image_storage() + try: + for published, address in addresses.items(): + offered = set(schema["paths"][published]["post"]["requestBody"]["content"]) + assert offered == {media_type for media_type, _name, _ext in IMAGE_UPLOAD_FORMS}, published + for media_type, name, extension in IMAGE_UPLOAD_FORMS: + with make_image_file(extension=extension) as image_file: + if name is None: + answer = client.post(address, {"file": image_file}) + else: + answer = client.post( + address, + data=image_file.read(), + content_type=media_type, + HTTP_CONTENT_DISPOSITION=f'attachment; filename="{name}"', + ) + assert answer.status_code == 204, (address, media_type, answer.content) + finally: + for stored in get_profile_image_names(owner.username).values(): + storage.delete(stored) + + +@skip_unless_lms +def test_clearing_the_profile_image_publishes_that_it_reads_nothing(schema): + operation = schema["paths"][PROFILE_IMAGE_PATH]["delete"] + assert "requestBody" not in operation + assert [parameter["name"] for parameter in operation["parameters"]] == ["username"] + assert operation["responses"]["204"]["description"] == "The account carries no image of its own." + assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404"] + assert operation["responses"]["400"]["description"] == ( + "The request carries a query parameter this endpoint does not read." + ) + + +@skip_unless_lms +def test_a_verification_status_publishes_the_properties_it_carries(schema): + body = schema["paths"][VERIFICATION_STATUS_PATH]["get"]["responses"]["200"] + assert body["content"]["application/json"]["schema"] == { + "$ref": "#/components/schemas/VerificationStatus", + } + published = schema["components"]["schemas"]["VerificationStatus"] + assert set(published["properties"]) == {"is_verified", "status", "expiration_datetime"} + assert sorted(published["required"]) == ["expiration_datetime", "is_verified", "status"] + assert published["properties"]["is_verified"]["type"] == "boolean" + assert all(published["properties"][name]["description"] for name in published["properties"]) + + +@skip_unless_lms +def test_the_day_a_summary_reports_is_published_as_the_day_it_carries(schema): + """ + The summary reports a calendar day and an attempt records a moment, under one name. + + A summary says when an accepted proof runs out as the day alone, so the + property is published with the shape of that day rather than as a + date-time, which is what the same property of an attempt carries. + """ + summary = schema["components"]["schemas"]["VerificationStatus"]["properties"]["expiration_datetime"] + attempt = schema["components"]["schemas"]["Verification"]["properties"]["expiration_datetime"] + assert summary["type"] == "string" + assert summary["pattern"] == EXPIRATION_DAY_PATTERN + assert "format" not in summary + assert "MM/DD/YYYY" in summary["description"] + assert attempt["type"] == "string" + assert attempt["format"] == "date-time" + assert attempt["nullable"] is True + + +@skip_unless_lms +def test_every_status_a_recorded_attempt_can_hold_is_published(schema): + """ + A client switching on these values meets no stored value the text leaves out. + + The attempts come from a table per kind of check, and the statuses those + tables hold are not the same set, so what is published has to name every + one of them. + """ + published = schema["components"]["schemas"]["Verification"]["properties"]["status"]["description"] + stored = { + str(value) + for choices in (IDVerificationAttempt.STATUS, VerificationAttempt.STATUS) + for value, _label in choices + } + assert stored == {"created", "ready", "submitted", "must_retry", "pending", "approved", "denied"} + for value in sorted(stored): + assert f"`{value}`" in published, value + + +@skip_unless_lms +def test_a_verification_attempt_publishes_the_properties_it_carries(schema): + page = schema["components"]["schemas"]["PaginatedVerificationList"] + assert page["properties"]["results"]["items"] == {"$ref": "#/components/schemas/Verification"} + published = schema["components"]["schemas"]["Verification"] + assert set(published["properties"]) == { + "type", "status", "expiration_datetime", "message", "updated_at", "receipt_id", + } + assert published["properties"]["expiration_datetime"]["nullable"] is True + assert published["properties"]["receipt_id"]["nullable"] is True + assert published["properties"]["type"]["readOnly"] is True + assert all(published["properties"][name]["description"] for name in published["properties"]) + + +@skip_unless_lms +def test_an_account_publishes_an_example_of_each_shape_it_answers_with(schema): + """ + Each example a client author reads is a body this endpoint really returns. + + The answer is whichever of three shapes the caller's standing and request + produce, so each is published, and each is held to the component and to + the set of properties that shape carries. + """ + published = schema["paths"][ACCOUNT_MEMBER_PATH]["get"]["responses"]["200"] + examples = published["content"]["application/json"]["examples"] + described_by = { + "YourOwnAccount": "Account", + "AnAccountSomebodyElseOwns": "Account", + "AnAccountReducedToWhatIdentifiesItsOwner": "AccountMinimal", + } + assert list(examples) == list(described_by) + assert [example["description"] for example in examples.values()] == [ + "Everything an account carries, which is what its owner and a staff caller receive.", + "The properties this owner shares with every learner. An owner who shares field by field " + "shares fewer, and one who shares nothing leaves only the three properties every account " + "carries.", + "What `view=minimal` answers with; `fields` selects any other set.", + ] + for name, example in examples.items(): + assert_records_match(schema, example["value"], described_by[name], case=name) + + whole = examples["YourOwnAccount"]["value"] + assert set(whole) == set(schema["components"]["schemas"]["Account"]["properties"]) + shared = examples["AnAccountSomebodyElseOwns"]["value"] + assert set(shared) == set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["bulk_shareable_fields"]) + assert shared["account_privacy"] == "all_users" + reduced = examples["AnAccountReducedToWhatIdentifiesItsOwner"]["value"] + assert set(reduced) == set(ACCOUNT_MINIMAL_FIELDS) + + +@skip_unless_lms +def test_the_verification_list_publishes_the_order_it_can_be_read_in(schema): + """The values published are the values the serializer takes, so the two cannot drift apart.""" + field = VerificationQuerySerializer().fields["ordering"] + parameter = published_ordering(schema, VERIFICATION_LIST_PATH) + assert parameter["schema"]["enum"] == ["updated_at", "-updated_at", ""] + assert parameter["schema"]["enum"] == [*field.choices, ""] + assert parameter["schema"]["default"] == "-updated_at" == field.default + assert parameter["description"].startswith(field.help_text) + assert parameter.get("required", False) is False + + +@skip_unless_lms +def test_every_list_publishes_its_sort_as_the_values_it_takes_and_the_order_it_uses_without_one(schema): + """ + The sort of every list is asked for under one name, and each publishes both + the values it takes and the order a caller that sends none is answered in. + + A list that can be sorted by several properties at once takes them as a + comma-separated array; one with a single sortable property takes that + property on its own, with the empty value asking for the default. + """ + published = {} + for path in ( + "/api/user/v2/users/", + "/api/user/v2/user_preferences/", + ACCOUNT_LIST_PATH, + VERIFICATION_LIST_PATH, + ): + shape = published_ordering(schema, path)["schema"] + published[path] = (shape["type"], sorted(shape.get("items", shape)["enum"]), shape["default"]) + assert published == { + "/api/user/v2/users/": ( + "array", ["-date_joined", "-username", "date_joined", "username"], ["username"], + ), + "/api/user/v2/user_preferences/": ( + "array", ["-key", "-username", "key", "username"], ["username", "key"], + ), + ACCOUNT_LIST_PATH: ("string", ["", "-username", "username"], "username"), + VERIFICATION_LIST_PATH: ("string", ["", "-updated_at", "updated_at"], "-updated_at"), + } + + +@skip_unless_lms +def test_an_account_and_a_row_of_the_account_collection_are_narrowed_by_the_same_presets(schema): + """One account is shaped by the presets that shape a row of the collection, and by the same values.""" + presets = {} + for path, method in ((ACCOUNT_LIST_PATH, "get"), (ACCOUNT_MEMBER_PATH, "get"), (ACCOUNT_MEMBER_PATH, "patch")): + parameter = next( + published for published in schema["paths"][path][method]["parameters"] + if published["name"] == "view" + ) + presets[path, method] = set(parameter["schema"]["enum"]) + assert presets == { + (ACCOUNT_LIST_PATH, "get"): {"minimal", "shared", ""}, + (ACCOUNT_MEMBER_PATH, "get"): {"minimal", "shared", ""}, + (ACCOUNT_MEMBER_PATH, "patch"): {"minimal", "shared", ""}, + } + + +@skip_unless_lms +def test_the_addresses_this_phase_adds_publish_no_other_query_parameters(schema): + """Each of these addresses reads what it names and nothing else.""" + published = { + path: sorted( + parameter["name"] for parameter in operation.get("parameters", []) + if parameter["in"] == "query" + ) + for path, _method, operation in operations(schema) + if path in { + NAME_CHANGE_PATH, + NAME_CHANGE_CONFIRMATION_PATH, + PROFILE_IMAGE_PATH, + VERIFICATION_STATUS_PATH, + VERIFICATION_LIST_PATH, + } + } + assert published == { + NAME_CHANGE_PATH: [], + NAME_CHANGE_CONFIRMATION_PATH: [], + PROFILE_IMAGE_PATH: [], + VERIFICATION_STATUS_PATH: [], + VERIFICATION_LIST_PATH: ["ordering", "page", "page_size"], + } diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py b/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py new file mode 100644 index 000000000000..c8ea8a1ed190 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py @@ -0,0 +1,106 @@ +"""Tests for the selections version 2 of the User API answers from.""" + +import datetime + +from django.conf import settings +from django.test import TestCase + +from common.djangoapps.student.tests.factories import UserFactory +from openedx.core.djangoapps.user_api.models import RetirementState, UserRetirementStatus +from openedx.core.djangoapps.user_api.v2.selectors import ( + accounts_holding_emails, + cancellable_retirement_for_email, + username_holding_email, + username_holding_id, + usernames_among, +) +from openedx.core.djangolib.testing.utils import skip_unless_lms + + +@skip_unless_lms +class AccountSelectionTests(TestCase): + """What the account selections answer, asked for outside a request.""" + + def setUp(self): + super().setUp() + self.first = UserFactory.create(username="first-holder", email="first@example.com") + self.second = UserFactory.create(username="second-holder", email="second@example.com") + + def test_the_accounts_holding_a_set_of_addresses_come_back_by_name(self): + found = accounts_holding_emails(["second@example.com", "first@example.com"]) + assert [user.username for user in found] == ["first-holder", "second-holder"] + + def test_an_address_no_account_holds_is_left_out(self): + found = accounts_holding_emails(["first@example.com", "nobody@example.com"]) + assert [user.username for user in found] == ["first-holder"] + + def test_no_addresses_find_no_accounts(self): + assert not list(accounts_holding_emails([])) + + def test_the_accounts_named_come_back_in_the_order_asked_for(self): + assert list(usernames_among(["second-holder", "first-holder"], "username")) == [ + "first-holder", "second-holder", + ] + assert list(usernames_among(["first-holder", "second-holder"], "-username")) == [ + "second-holder", "first-holder", + ] + + def test_a_name_no_account_holds_is_left_out_of_the_selection(self): + assert list(usernames_among(["first-holder", "nobody-at-all"], "username")) == ["first-holder"] + + def test_no_names_select_no_accounts(self): + assert not list(usernames_among([], "username")) + + def test_the_account_holding_one_address_is_named(self): + assert username_holding_email("second@example.com") == "second-holder" + + def test_no_account_holds_an_unregistered_address(self): + assert username_holding_email("nobody@example.com") is None + + def test_the_account_holding_one_identifier_is_named(self): + assert username_holding_id(self.second.id) == "second-holder" + + def test_no_account_holds_an_unused_identifier(self): + assert username_holding_id(self.second.id + 1000) is None + + +@skip_unless_lms +class RetirementSelectionTests(TestCase): + """Which retirement of a retired address can still be cancelled.""" + + def setUp(self): + super().setUp() + RetirementState.objects.create(state_name="PENDING", state_execution_order=1) + self.user = UserFactory.create(username="leaving", email="leaving@example.com") + + def age(self, retirement, days): + """Record the given retirement as having been asked for that many days ago.""" + asked = datetime.datetime.now(datetime.UTC) - datetime.timedelta(days=days) + UserRetirementStatus.objects.filter(pk=retirement.pk).update(created=asked) + + def test_a_retirement_inside_the_cooling_off_period_is_the_one_reported(self): + retirement = UserRetirementStatus.create_retirement(self.user) + found = cancellable_retirement_for_email("leaving@example.com") + assert found is not None + assert found.pk == retirement.pk + assert found.original_email == "leaving@example.com" + + def test_a_retirement_older_than_the_cooling_off_period_is_not_reported(self): + retirement = UserRetirementStatus.create_retirement(self.user) + self.age(retirement, settings.COOL_OFF_DAYS + 1) + assert cancellable_retirement_for_email("leaving@example.com") is None + + def test_an_address_with_no_retirement_behind_it_has_none(self): + UserRetirementStatus.create_retirement(self.user) + assert cancellable_retirement_for_email("staying@example.com") is None + + def test_the_most_recently_asked_for_retirement_of_an_address_is_the_one_reported(self): + """One address can have been held and left more than once; the last one is cancellable.""" + earlier = UserRetirementStatus.create_retirement(self.user) + self.age(earlier, 2) + again = UserFactory.create(username="leaving-again", email="leaving-again@example.com") + later = UserRetirementStatus.create_retirement(again) + UserRetirementStatus.objects.filter(pk=later.pk).update(original_email="leaving@example.com") + found = cancellable_retirement_for_email("leaving@example.com") + assert found.pk == later.pk + assert found.user_id == again.id diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_urls.py b/openedx/core/djangoapps/user_api/v2/tests/test_urls.py index c51ceab78a13..7f14cd526cb2 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_urls.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_urls.py @@ -5,20 +5,34 @@ import pytest from django.core.exceptions import ImproperlyConfigured from django.urls import get_resolver, resolve, reverse +from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser from edx_rest_framework_extensions.testing import assert_error_envelope from rest_framework import status from rest_framework.request import Request +from rest_framework.settings import api_settings from rest_framework.test import APIRequestFactory, APITestCase +from rest_framework.views import APIView from common.djangoapps.student.tests.factories import AdminFactory +from openedx.core.djangoapps.profile_images.v2.views import ProfileImageView from openedx.core.djangoapps.user_api.v2 import urls as v2_urls -from openedx.core.djangoapps.user_api.v2.views import UserPreferenceViewSet, UserViewSet +from openedx.core.djangoapps.user_api.v2.views import ( + AccountDeactivationView, + AccountViewSet, + IDVerificationStatusView, + IDVerificationViewSet, + NameChangeViewSet, + UserPreferenceViewSet, + UserViewSet, +) from openedx.core.djangolib.testing.utils import skip_unless_lms PASSWORD = "Password1234" V2_VIEW_MODULE = "openedx.core.djangoapps.user_api.v2.views" +PROFILE_IMAGE_VIEW_MODULE = "openedx.core.djangoapps.profile_images.v2.views" V1_VIEW_MODULE = "openedx.core.djangoapps.user_api.views" +V1_ACCOUNT_VIEW_MODULE = "openedx.core.djangoapps.user_api.accounts.views" V2_NAMESPACE = "user_v2" #: A route name is lower case, starts with a letter and separates words with @@ -27,6 +41,30 @@ VERSION_IN_NAME = re.compile(r"v\d") EXPECTED_ADDRESSES = { + "user_v2:account_list": ({}, "/api/user/v2/accounts/"), + "user_v2:account_detail": ({"username": "alice"}, "/api/user/v2/accounts/alice/"), + "user_v2:email_search_list": ({}, "/api/user/v2/email_searches/"), + "user_v2:account_deactivation": ( + {"username": "alice"}, + "/api/user/v2/accounts/alice/deactivation/", + ), + "user_v2:account_profile_image": ( + {"username": "alice"}, + "/api/user/v2/accounts/alice/profile_image/", + ), + "user_v2:account_verification_status": ( + {"username": "alice"}, + "/api/user/v2/accounts/alice/verification_status/", + ), + "user_v2:account_verification_list": ( + {"username": "alice"}, + "/api/user/v2/accounts/alice/verifications/", + ), + "user_v2:name_change_list": ({}, "/api/user/v2/name_changes/"), + "user_v2:name_change_confirmation": ( + {"username": "alice"}, + "/api/user/v2/name_changes/alice/confirmations/", + ), "user_v2:user_list": ({}, "/api/user/v2/users/"), "user_v2:user_detail": ({"username": "alice"}, "/api/user/v2/users/alice/"), "user_v2:user_preference_list": ({}, "/api/user/v2/user_preferences/"), @@ -65,6 +103,16 @@ def routed_actions(view_func): return {method: action for method, action in view_func.actions.items() if method != "head"} +def served_methods(view_func): + """ + Return the request methods a route mounted on a plain view serves. + + A viewset mount carries its method-to-action map; a plain view has one + handler per method instead, and the set of those is what the route serves. + """ + return set(view_func.view_class().allowed_methods) + + def view_identity(view_func): """ Return the module and class name of the view a route is mounted on. @@ -96,6 +144,15 @@ def test_resolved_names_are_the_names_that_reverse(self): resolved = resolved_route_names() assert resolved == registered_route_names() for address, name in ( + ("/api/user/v2/accounts/", "account_list"), + ("/api/user/v2/accounts/alice/", "account_detail"), + ("/api/user/v2/email_searches/", "email_search_list"), + ("/api/user/v2/accounts/alice/deactivation/", "account_deactivation"), + ("/api/user/v2/accounts/alice/profile_image/", "account_profile_image"), + ("/api/user/v2/accounts/alice/verification_status/", "account_verification_status"), + ("/api/user/v2/accounts/alice/verifications/", "account_verification_list"), + ("/api/user/v2/name_changes/", "name_change_list"), + ("/api/user/v2/name_changes/alice/confirmations/", "name_change_confirmation"), ("/api/user/v2/users/", "user_list"), ("/api/user/v2/users/alice/", "user_detail"), ("/api/user/v2/user_preferences/", "user_preference_list"), @@ -107,6 +164,16 @@ def test_resolved_names_are_the_names_that_reverse(self): assert match.view_name == f"{V2_NAMESPACE}:{name}", address def test_viewsets_build_action_addresses_under_this_mount(self): + accounts = AccountViewSet(basename="account") + assert accounts.reverse_action("list") == "/api/user/v2/accounts/" + assert accounts.reverse_action( + "detail", kwargs={"username": "alice"}, + ) == "/api/user/v2/accounts/alice/" + name_changes = NameChangeViewSet(basename="name_change") + assert name_changes.reverse_action("list") == "/api/user/v2/name_changes/" + assert name_changes.reverse_action( + "confirmation", kwargs={"username": "alice"}, + ) == "/api/user/v2/name_changes/alice/confirmations/" assert UserViewSet(basename="user").reverse_action("list") == "/api/user/v2/users/" assert UserViewSet(basename="user").reverse_action( "detail", kwargs={"username": "alice"}, @@ -125,6 +192,18 @@ def test_action_addresses_follow_the_namespace_the_request_arrived_on(self): def test_addresses_resolve_to_the_version_two_viewsets(self): expected = { + "/api/user/v2/accounts/": ("AccountViewSet", {"get": "list"}), + "/api/user/v2/accounts/alice/": ( + "AccountViewSet", {"get": "retrieve", "patch": "partial_update"}, + ), + "/api/user/v2/accounts/alice/verifications/": ( + "IDVerificationViewSet", {"get": "list"}, + ), + "/api/user/v2/email_searches/": ("EmailSearchViewSet", {"post": "create"}), + "/api/user/v2/name_changes/": ("NameChangeViewSet", {"post": "create"}), + "/api/user/v2/name_changes/alice/confirmations/": ( + "NameChangeViewSet", {"post": "confirmations"}, + ), "/api/user/v2/users/": ("UserViewSet", {"get": "list"}), "/api/user/v2/users/alice/": ("UserViewSet", {"get": "retrieve"}), "/api/user/v2/user_preferences/": ("UserPreferenceViewSet", {"get": "list"}), @@ -138,6 +217,72 @@ def test_addresses_resolve_to_the_version_two_viewsets(self): assert view_identity(match.func) == (V2_VIEW_MODULE, class_name), address assert routed_actions(match.func) == actions, address + def test_a_deactivation_authenticates_the_way_the_platform_does(self): + """ + The view serving a deactivation declares no authentication of its own. + + Disabling an account is reached with whatever credentials the platform + accepts everywhere else, so the view carries no list of its own that a + deployment changing that setting would have to be changed alongside. + """ + view_class = resolve("/api/user/v2/accounts/alice/deactivation/").func.view_class + assert view_class is AccountDeactivationView + assert "authentication_classes" not in vars(AccountDeactivationView) + assert AccountDeactivationView.authentication_classes is APIView.authentication_classes + + def test_the_views_reached_before_an_address_is_confirmed_replace_one_class(self): + """ + An account and its picture are reached with the platform's token class and a wider session one. + + The site's own settings pages are reached by a user who has not + confirmed their email address, whom the session class the platform + configures refuses, so that one class is replaced. The class reading a + token is left as the platform declares it, which is what records these + requests alongside every other request authenticated that way. + """ + platform_token = api_settings.DEFAULT_AUTHENTICATION_CLASSES[0] + for view_class in (AccountViewSet, ProfileImageView): + assert view_class.authentication_classes == ( + platform_token, SessionAuthenticationAllowInactiveUser, + ), view_class.__name__ + + def test_what_is_recorded_about_an_account_authenticates_the_way_the_platform_does(self): + """ + The views serving what has been recorded about an account declare no authentication. + + The account itself is reached with the session class that admits a + user who has not confirmed their address, because the site's own + settings pages are reached that way; what has been recorded about that + account is reached with whatever credentials the platform accepts + everywhere else, so these views carry no list of their own that a + deployment changing that setting would have to be changed alongside. + """ + assert resolve( + "/api/user/v2/accounts/alice/verifications/", + ).func.cls is IDVerificationViewSet + for view_class in (IDVerificationStatusView, IDVerificationViewSet): + assert "authentication_classes" not in vars(view_class), view_class.__name__ + assert view_class.authentication_classes is APIView.authentication_classes + + def test_the_hand_routed_addresses_resolve_to_the_views_that_serve_them(self): + """The addresses that are not router-generated carry a view and a method set too.""" + expected = { + "/api/user/v2/accounts/alice/deactivation/": ( + V2_VIEW_MODULE, "AccountDeactivationView", {"POST", "OPTIONS"}, + ), + "/api/user/v2/accounts/alice/profile_image/": ( + PROFILE_IMAGE_VIEW_MODULE, "ProfileImageView", {"POST", "DELETE", "OPTIONS"}, + ), + "/api/user/v2/accounts/alice/verification_status/": ( + V2_VIEW_MODULE, "IDVerificationStatusView", {"GET", "OPTIONS"}, + ), + } + for address, (module, class_name, methods) in expected.items(): + match = resolve(address) + assert view_identity(match.func) == (module, class_name), address + assert served_methods(match.func) == methods, address + assert match.kwargs == {"username": "alice"}, address + def test_username_with_a_dot_resolves_to_the_member_route(self): match = resolve("/api/user/v2/users/ada.lovelace/") assert view_identity(match.func) == (V2_VIEW_MODULE, "UserViewSet") @@ -179,6 +324,15 @@ class RouteShapeTests(APITestCase): def test_every_address_is_named_and_ends_in_a_slash(self): addresses = [pattern for pattern in v2_urls.urlpatterns if pattern.name] assert sorted(pattern.name for pattern in addresses) == [ + "account_deactivation", + "account_detail", + "account_list", + "account_profile_image", + "account_verification_list", + "account_verification_status", + "email_search_list", + "name_change_confirmation", + "name_change_list", "time_zone_list", "user_detail", "user_list", @@ -195,6 +349,12 @@ def test_the_router_route_that_is_replaced_has_to_exist(self): assert v2_urls.REPLACED_ROUTER_ROUTE in {route.name for route in routes} kept = v2_urls.without_route(routes, v2_urls.REPLACED_ROUTER_ROUTE) assert [route.name for route in kept] == [ + "account_list", + "account_detail", + "account_verification_list", + "email_search_list", + "name_change_list", + "name_change_confirmation", "user_list", "user_detail", "user_preference_list", @@ -214,6 +374,60 @@ def test_the_one_unnamed_pattern_is_the_fallback_and_it_is_matched_last(self): class LegacyAddressTests(APITestCase): """Mounting version 2 leaves the version 1 surface exactly where it was.""" + def test_version_one_account_addresses_still_reach_the_version_one_views(self): + expected = { + "/api/user/v1/me": ("AccountViewSet", {"get": "get"}), + "/api/user/v1/accounts": ("AccountViewSet", {"get": "list"}), + "/api/user/v1/accounts/search_emails": ("AccountViewSet", {"post": "search_emails"}), + "/api/user/v1/accounts/alice": ( + "AccountViewSet", {"get": "retrieve", "patch": "partial_update"}, + ), + } + for address, (class_name, actions) in expected.items(): + match = resolve(address) + assert view_identity(match.func) == (V1_ACCOUNT_VIEW_MODULE, class_name), address + assert routed_actions(match.func) == actions, address + + deactivation = resolve("/api/user/v1/accounts/alice/deactivate/") + assert view_identity(deactivation.func) == ( + V1_ACCOUNT_VIEW_MODULE, "AccountDeactivationView", + ) + + def test_version_one_addresses_of_the_resources_this_version_adds_are_unchanged(self): + name_changes = { + "/api/user/v1/accounts/name_change/": {"post": "create"}, + "/api/user/v1/accounts/name_change/alice/confirm/": {"post": "confirm"}, + } + for address, actions in name_changes.items(): + match = resolve(address) + assert view_identity(match.func) == (V1_ACCOUNT_VIEW_MODULE, "NameChangeView"), address + assert routed_actions(match.func) == actions, address + + image = resolve("/api/user/v1/accounts/alice/image") + assert view_identity(image.func) == ( + "openedx.core.djangoapps.profile_images.views", "ProfileImageView", + ) + for address, class_name in ( + ("/api/user/v1/accounts/alice/verification_status/", "IDVerificationStatusView"), + ("/api/user/v1/accounts/alice/verifications/", "IDVerificationStatusDetailsView"), + ): + match = resolve(address) + assert view_identity(match.func) == ( + "openedx.core.djangoapps.user_api.verification_api.views", class_name, + ), address + + def test_the_profile_image_twins_in_their_own_app_are_left_where_they_are(self): + """This version adds no second address for them, and theirs keep their names.""" + assert reverse("profile_image_upload", kwargs={"username": "alice"}) == ( + "/api/profile_images/v1/alice/upload" + ) + assert reverse("profile_image_remove", kwargs={"username": "alice"}) == ( + "/api/profile_images/v1/alice/remove" + ) + for name in ("profile_image_upload", "profile_image_remove"): + match = resolve(reverse(name, kwargs={"username": "alice"})) + assert match.func.view_class.__module__ == "openedx.core.djangoapps.profile_images.views" + def test_version_one_addresses_still_reach_the_version_one_views(self): expected = { "/api/user/v1/users/": "UserViewSet", @@ -231,6 +445,24 @@ def test_version_one_addresses_still_reach_the_version_one_views(self): def test_version_one_url_names_still_reverse(self): assert reverse("accounts_api", kwargs={"username": "alice"}) == "/api/user/v1/accounts/alice" assert reverse("own_username_api") == "/api/user/v1/me" + assert reverse("accounts_detail_api") == "/api/user/v1/accounts" + assert reverse("accounts_search_emails_api") == "/api/user/v1/accounts/search_emails" + assert reverse("accounts_deactivation", kwargs={"username": "alice"}) == ( + "/api/user/v1/accounts/alice/deactivate/" + ) + assert reverse("accounts_profile_image_api", kwargs={"username": "alice"}) == ( + "/api/user/v1/accounts/alice/image" + ) + assert reverse("request_name_change") == "/api/user/v1/accounts/name_change/" + assert reverse("confirm_name_change", kwargs={"username": "alice"}) == ( + "/api/user/v1/accounts/name_change/alice/confirm/" + ) + assert reverse("verification_status", kwargs={"username": "alice"}) == ( + "/api/user/v1/accounts/alice/verification_status/" + ) + assert reverse("verification_details", kwargs={"username": "alice"}) == ( + "/api/user/v1/accounts/alice/verifications/" + ) assert reverse("preferences_api", kwargs={"username": "alice"}) == "/api/user/v1/preferences/alice" def test_unversioned_twins_still_resolve(self): @@ -294,3 +526,40 @@ def test_the_version_this_mount_shares_its_prefix_with_is_left_alone(self): assert match.func.view_class.__module__.startswith( "openedx.core.djangoapps.user_authn", ), address + + def test_the_singular_spelling_of_the_account_collection_is_refused_in_json(self): + """The nearest misspelling of a collection of this version is answered by it.""" + for address in ( + "/api/user/v2/account/", + "/api/user/v2/account/alice/", + "/api/user/v2/account/alice/profile_image/", + ): + response = self.client.get(address, HTTP_ACCEPT="application/json") + assert view_identity(resolve(address).func) == (V2_VIEW_MODULE, "UnknownAddressView"), address + self.assert_refused_in_json(response) + + def test_an_address_of_the_other_app_sent_without_its_slash_is_still_redirected(self): + """That app serves the slashed form, which the caller is sent to as it was before.""" + response = self.client.get("/api/user/v2/account/registration") + assert response.status_code == status.HTTP_301_MOVED_PERMANENTLY + assert response["Location"] == "/api/user/v2/account/registration/" + + def test_every_address_left_to_the_other_app_is_one_that_app_serves(self): + """ + An address that app adds under this prefix is answered here until it is named. + + The two are matched by the pattern that keeps them out of the fallback + and are read back from the routes serving them, so neither side can be + edited alone. + """ + left_alone = re.compile(rf"{v2_urls.OTHER_APP_ADDRESSES}\Z") + served = { + reverse("user_api_registration_v2"), + reverse("user_api_login_session", kwargs={"api_version": "v2"}), + } + assert served == { + "/api/user/v2/account/registration/", + "/api/user/v2/account/login_session/", + } + for address in served: + assert left_alone.match(address.removeprefix("/api/user/v2/")), address diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py new file mode 100644 index 000000000000..12332694864d --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py @@ -0,0 +1,1047 @@ +"""Tests for the version 2 User API identity verification views.""" + +import datetime +from zoneinfo import ZoneInfo + +import pytest +from django.db import connection +from django.test.utils import CaptureQueriesContext, override_settings +from django.urls import reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from rest_framework import status +from rest_framework.test import APITestCase + +from common.djangoapps.student.models import UserProfile +from common.djangoapps.student.tests.factories import UserFactory +from lms.djangoapps.verify_student.models import ( + ManualVerification, + SoftwareSecurePhotoVerification, + VerificationAttempt, +) +from lms.djangoapps.verify_student.tests.factories import SSOVerificationFactory +from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user +from openedx.core.djangolib.testing.utils import skip_unless_lms + +from .test_views import PAGINATION_KEYS, write_queries + +PASSWORD = "Password1234" + +#: Identity checks are good for a year on this site, and a user is asked to go +#: through one again in the three weeks before an accepted proof runs out. +VERIFY_STUDENT = {"DAYS_GOOD_FOR": 365, "EXPIRING_SOON_WINDOW": 20} + + +def earlier_status_address(username): + """Return the version 1 address of one user's verification status.""" + return f"/api/user/v1/accounts/{username}/verification_status/" + + +def earlier_list_address(username): + """Return the version 1 address of one user's verification attempts.""" + return f"/api/user/v1/accounts/{username}/verifications/" + + +@override_settings(VERIFY_STUDENT=VERIFY_STUDENT) +class VerificationTestCase(APITestCase): + """Fixtures shared by the version 2 identity verification tests.""" + + def setUp(self): + super().setUp() + self.owner = UserFactory.create( + username="verify-owner", email="verify-owner@example.com", password=PASSWORD, + ) + self.other = UserFactory.create( + username="verify-other", email="verify-other@example.com", password=PASSWORD, + ) + self.staff = UserFactory.create( + username="verify-staff", email="verify-staff@example.com", password=PASSWORD, is_staff=True, + ) + self.attempt = SoftwareSecurePhotoVerification.objects.create( + user=self.owner, status="submitted", + ) + self.status_url = self.status_address(self.owner.username) + self.list_url = self.list_address(self.owner.username) + + def status_address(self, username): + """Return the address of one user's verification status.""" + return reverse("user_v2:account_verification_status", kwargs={"username": username}) + + def list_address(self, username): + """Return the address of one user's verification attempts.""" + return reverse("user_v2:account_verification_list", kwargs={"username": username}) + + def login(self, user): + """Sign the given user in through the session these views accept.""" + assert self.client.login(username=user.username, password=PASSWORD) + + def token_headers(self, user): + """Return the request headers that carry a token identifying the given user.""" + return {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(user)}"} + + def sign_in_as_a_case_variant_of(self, user): + """ + Sign in a caller whose own name is the given user's, in upper case. + + The variant is set in memory only, since a site that stores usernames + case-insensitively has no room for both names at once. + """ + caller = UserFactory.create( + username="verify-variant", email="verify-variant@example.com", password=PASSWORD, + ) + caller.username = user.username.upper() + self.client.force_authenticate(user=caller) + return caller + + def approve(self, attempt, expires_in_days=200): + """Record an attempt as accepted, running out the given number of days from now.""" + attempt.status = "approved" + attempt.expiration_date = datetime.datetime.now(ZoneInfo("UTC")) + datetime.timedelta( + days=expires_in_days, + ) + attempt.save() + return attempt + + def run_out(self, attempt, days_ago=1): + """Record an attempt as accepted and no longer good, the given number of days ago.""" + return self.approve(attempt, expires_in_days=-days_ago) + + +@skip_unless_lms +class VerificationStatusTests(VerificationTestCase): + """GET /api/user/v2/accounts/{username}/verification_status/""" + + def test_a_user_reads_their_own_status(self): + self.login(self.owner) + response = self.client.get(self.status_url) + assert response.status_code == status.HTTP_200_OK + assert response.data == { + "is_verified": False, "status": "pending", "expiration_datetime": "", + } + + def test_an_accepted_proof_is_reported_as_verified(self): + self.approve(self.attempt) + self.login(self.owner) + response = self.client.get(self.status_url) + assert response.data == { + "is_verified": True, "status": "approved", "expiration_datetime": "", + } + + def test_an_accepted_proof_about_to_run_out_carries_the_day_it_does(self): + """The day is published only once the user is near being asked to verify again.""" + attempt = self.approve(self.attempt, expires_in_days=10) + self.login(self.owner) + response = self.client.get(self.status_url) + assert response.data["status"] == "approved" + assert response.data["is_verified"] is True + assert response.data["expiration_datetime"] == attempt.expiration_datetime.date().strftime( + "%m/%d/%Y", + ) + + def test_the_summary_reports_the_day_and_the_attempt_the_moment_it_runs_out(self): + """ + The property of this name carries a day in the summary and a moment in the attempt. + + The summary reports the day the user is told about; the attempt holding + the proof records when it stops counting, to the second. + """ + attempt = self.approve(self.attempt, expires_in_days=10) + self.login(self.owner) + summary = self.client.get(self.status_url) + listed = self.client.get(self.list_url).data["results"][0]["expiration_datetime"] + assert summary.data["expiration_datetime"] == attempt.expiration_datetime.date().strftime( + "%m/%d/%Y", + ) + assert listed.startswith(attempt.expiration_datetime.strftime("%Y-%m-%dT%H:%M:%S")) + + def test_a_turned_down_proof_asks_the_user_to_try_again(self): + self.attempt.status = "denied" + self.attempt.error_msg = '[{"userPhotoReasons": ["Face out of view"]}]' + self.attempt.save() + self.login(self.owner) + response = self.client.get(self.status_url) + assert response.data["status"] == "must_reverify" + assert response.data["is_verified"] is False + + def test_a_proof_that_is_no_longer_good_is_reported_as_run_out(self): + self.run_out(self.attempt) + self.login(self.owner) + response = self.client.get(self.status_url) + assert response.data["status"] == "expired" + assert response.data["is_verified"] is False + + def test_a_proof_the_user_was_never_shown_stands_at_none_once_it_runs_out(self): + """A check whose outcome is never shown to its subject is as if it had not been made.""" + self.attempt.delete() + self.run_out(ManualVerification.objects.create( + user=self.owner, status="approved", reason="Checked in person", + )) + self.login(self.owner) + response = self.client.get(self.status_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["status"] == "none" + assert response.data["is_verified"] is False + + def test_a_staff_caller_reads_another_users_status(self): + self.login(self.staff) + response = self.client.get(self.status_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["status"] == "pending" + + def test_a_learner_may_not_read_another_users_status(self): + self.login(self.other) + assert_error_envelope( + self.client.get(self.status_url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_refused_read_stays_refused_whatever_the_query_string_carries(self): + """Who may read this status is settled from the address, before the query string is read.""" + self.login(self.other) + for query in ( + f"username={self.other.username}", + f"user={self.other.username}", + "format=json", + ): + assert_error_envelope( + self.client.get(f"{self.status_url}?{query}"), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_caller_named_for_the_address_in_case_alone_may_not_read_the_status(self): + self.sign_in_as_a_case_variant_of(self.owner) + assert_error_envelope( + self.client.get(self.status_url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_an_anonymous_caller_is_unauthenticated(self): + assert_error_envelope( + self.client.get(self.status_url), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + + def test_a_user_who_has_never_been_checked_stands_at_none(self): + """Nothing on record is something to report: the summary says so rather than going missing.""" + self.login(self.other) + response = self.client.get(self.status_address(self.other.username)) + assert response.status_code == status.HTTP_200_OK + assert response.data == { + "is_verified": False, "status": "none", "expiration_datetime": "", + } + + def test_a_user_who_has_never_been_checked_is_told_apart_from_one_who_does_not_exist(self): + self.login(self.staff) + assert self.client.get(self.status_address(self.other.username)).status_code == status.HTTP_200_OK + assert_error_envelope( + self.client.get(self.status_address("nobody-at-all")), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + def test_an_unknown_username_is_not_found(self): + self.login(self.staff) + assert_error_envelope( + self.client.get(self.status_address("nobody-at-all")), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + def test_an_unknown_query_parameter_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.get(f"{self.status_url}?expand=attempts"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "expand": ["No such query parameter. Send any of: format."], + } + + def test_the_name_in_the_address_is_refused_in_the_query_string_as_well(self): + """The address carries the username, so a parameter repeating it is one this view never reads.""" + for caller in (self.owner, self.staff): + self.login(caller) + envelope = assert_error_envelope( + self.client.get(f"{self.status_url}?username={self.owner.username}"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "username": ["No such query parameter. Send any of: format."], + } + self.client.logout() + + def test_the_status_is_not_changed_through_this_address(self): + self.login(self.owner) + assert_error_envelope( + self.client.post(self.status_url, {}, format="json"), + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + + +@skip_unless_lms +class VerificationListTests(VerificationTestCase): + """GET /api/user/v2/accounts/{username}/verifications/""" + + def setUp(self): + super().setUp() + self.manual = ManualVerification.objects.create( + user=self.owner, status="approved", reason="Checked in person", + ) + + def test_a_user_reads_their_own_attempts(self): + self.login(self.owner) + response = self.client.get(self.list_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == 2 + assert {row["type"] for row in response.data["results"]} == {"Software Secure", "Manual"} + + def test_each_attempt_carries_what_was_recorded_about_it(self): + self.login(self.owner) + rows = {row["type"]: row for row in self.client.get(self.list_url).data["results"]} + assert rows["Manual"]["status"] == "approved" + assert rows["Manual"]["message"] == "Checked in person" + assert rows["Manual"]["receipt_id"] is None + assert rows["Software Secure"]["status"] == "submitted" + assert rows["Software Secure"]["receipt_id"] == str(self.attempt.receipt_id) + + def test_each_kind_of_check_is_named_with_what_was_said_about_it(self): + """The kind of check, the remark on it and the receipt are read from the record holding the attempt.""" + self.attempt.status = "denied" + self.attempt.error_msg = '[{"userPhotoReasons": ["Face out of view"]}]' + self.attempt.save() + SSOVerificationFactory(user=self.owner, status="approved", identity_provider_slug="idp") + self.login(self.owner) + rows = {row["type"]: row for row in self.client.get(self.list_url).data["results"]} + assert set(rows) == {"Software Secure", "Manual", "SSO"} + assert rows["Software Secure"]["message"] == '[{"userPhotoReasons": ["Face out of view"]}]' + assert rows["Software Secure"]["receipt_id"] == str(self.attempt.receipt_id) + assert rows["Manual"]["message"] == "Checked in person" + assert rows["Manual"]["receipt_id"] is None + assert rows["SSO"]["message"] == "" + assert rows["SSO"]["receipt_id"] is None + + def test_an_attempt_carries_the_status_the_table_holding_it_records(self): + """ + The tables behind these attempts do not hold the same statuses, and each is carried as it stands. + + A photo check that failed to go through is held as ``must_retry``, and a + check carried out elsewhere is held as ``pending`` while it is looked at. + """ + self.attempt.status = "must_retry" + self.attempt.save() + VerificationAttempt.objects.create(user=self.owner, name="Verify Owner", status="pending") + self.login(self.owner) + rows = {row["type"]: row for row in self.client.get(self.list_url).data["results"]} + assert set(rows) == {"Software Secure", "Manual", "SSO"} + assert rows["Software Secure"]["status"] == "must_retry" + assert rows["SSO"]["status"] == "pending" + assert rows["SSO"]["message"] == "" + assert rows["SSO"]["receipt_id"] is None + assert rows["SSO"]["expiration_datetime"] is None + + def test_the_page_carries_the_whole_envelope(self): + self.login(self.owner) + response = self.client.get(self.list_url) + assert set(response.data) == PAGINATION_KEYS + assert response.data["count"] == 2 + assert response.data["num_pages"] == 1 + assert response.data["current_page"] == 1 + assert response.data["start"] == 0 + assert response.data["next"] is None + assert response.data["previous"] is None + + def test_the_page_is_bounded(self): + for index in range(5): + SSOVerificationFactory(user=self.owner, status="approved", identity_provider_slug=f"idp{index}") + self.login(self.owner) + response = self.client.get(self.list_url, {"page_size": 3}) + assert response.data["count"] == 7 + assert len(response.data["results"]) == 3 + assert response.data["num_pages"] == 3 + assert response.data["next"].endswith("page=2&page_size=3") + + def test_the_attempts_come_back_newest_first_and_the_order_can_be_reversed(self): + self.login(self.owner) + descending = self.client.get(self.list_url).data["results"] + assert [row["updated_at"] for row in descending] == sorted( + [row["updated_at"] for row in descending], reverse=True, + ) + ascending = self.client.get(self.list_url, {"ordering": "updated_at"}).data["results"] + assert [row["type"] for row in ascending] == [row["type"] for row in reversed(descending)] + + def test_attempts_changed_at_the_same_moment_are_ordered_by_their_receipt(self): + """ + Two attempts sharing a timestamp are told apart by their receipt identifier. + + The service hands back one table after another, so the order the rows + arrive in is not an order the caller asked for: a page that falls back + to it reads the same both ways round. + """ + moment = datetime.datetime(2024, 5, 1, 12, 0, tzinfo=ZoneInfo("UTC")) + for attempt in (self.attempt, self.manual): + type(attempt).objects.filter(pk=attempt.pk).update(updated_at=moment) + self.login(self.owner) + + descending = self.client.get(self.list_url).data["results"] + assert [row["receipt_id"] for row in descending] == [str(self.attempt.receipt_id), None] + ascending = self.client.get(self.list_url, {"ordering": "updated_at"}).data["results"] + assert [row["receipt_id"] for row in ascending] == [None, str(self.attempt.receipt_id)] + + def test_a_sort_the_list_does_not_offer_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.get(self.list_url, {"ordering": "status"}), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "ordering": ["Sort by any of: updated_at, each optionally prefixed with '-'."], + } + + def test_an_unknown_query_parameter_is_refused(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.get(self.list_url, {"status": "approved"}), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "status": ["No such query parameter. Send any of: format, ordering, page, page_size."], + } + + def test_the_name_in_the_address_is_refused_in_the_query_string_as_well(self): + """The address carries the username, so a parameter repeating it is one this view never reads.""" + for caller in (self.owner, self.staff): + self.login(caller) + envelope = assert_error_envelope( + self.client.get(f"{self.list_url}?username={self.owner.username}"), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == { + "username": ["No such query parameter. Send any of: format, ordering, page, page_size."], + } + self.client.logout() + + def test_a_staff_caller_reads_another_users_attempts(self): + self.login(self.staff) + response = self.client.get(self.list_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == 2 + + def test_a_learner_may_not_read_another_users_attempts(self): + self.login(self.other) + assert_error_envelope( + self.client.get(self.list_url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_refused_read_stays_refused_whatever_the_query_string_carries(self): + """Who may read these attempts is settled from the address, before the query string is read.""" + self.login(self.other) + for query in ( + f"username={self.other.username}", + f"user={self.other.username}", + "ordering=-updated_at", + ): + assert_error_envelope( + self.client.get(f"{self.list_url}?{query}"), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_caller_named_for_the_address_in_case_alone_may_not_read_the_attempts(self): + self.sign_in_as_a_case_variant_of(self.owner) + assert_error_envelope( + self.client.get(self.list_url), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_an_anonymous_caller_is_unauthenticated(self): + assert_error_envelope( + self.client.get(self.list_url), + expected_status=status.HTTP_401_UNAUTHORIZED, + expected_type_slug="authn", + ) + + def test_a_user_who_has_been_through_no_checks_has_an_empty_page(self): + """An existing user with nothing to list is an empty collection, not an absent one.""" + self.login(self.other) + response = self.client.get(self.list_address(self.other.username)) + assert response.status_code == status.HTTP_200_OK + assert set(response.data) == PAGINATION_KEYS + assert response.data["count"] == 0 + assert response.data["results"] == [] + assert response.data["num_pages"] == 1 + assert response.data["next"] is None + + def test_a_user_who_has_been_through_no_checks_is_told_apart_from_one_who_does_not_exist(self): + self.login(self.staff) + empty = self.client.get(self.list_address(self.other.username)) + unknown = self.client.get(self.list_address("nobody-at-all")) + assert empty.status_code == status.HTTP_200_OK + assert unknown.status_code == status.HTTP_404_NOT_FOUND + assert empty.data["count"] == 0 + + def test_an_unknown_username_is_not_found(self): + self.login(self.staff) + assert_error_envelope( + self.client.get(self.list_address("nobody-at-all")), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + def test_a_page_that_does_not_exist_is_refused(self): + self.login(self.owner) + assert_error_envelope( + self.client.get(self.list_url, {"page": 9}), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + def test_the_attempts_are_not_changed_through_this_address(self): + self.login(self.owner) + assert_error_envelope( + self.client.post(self.list_url, {}, format="json"), + expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, + expected_type_slug="method-not-allowed", + ) + + +@skip_unless_lms +class VerificationPageSizeTests(VerificationTestCase): + """ + How many attempts a page carries when the caller does not say, and the most it will carry. + + The list is asked for more attempts than it will give, against attempts + that really exist, so what is pinned is the page the endpoint answers + with rather than the numbers a paginator class holds. + """ + + DEFAULT_PAGE_SIZE = 10 + MAX_PAGE_SIZE = 100 + + def extra_attempts(self, count): + """Record the given number of further checks for the owner.""" + for index in range(count): + SSOVerificationFactory( + user=self.owner, status="approved", identity_provider_slug=f"idp{index:03d}", + ) + + def test_a_page_of_attempts_carries_ten_of_them_when_the_caller_asks_for_no_size(self): + self.extra_attempts(self.DEFAULT_PAGE_SIZE) + self.login(self.owner) + response = self.client.get(self.list_url) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == self.DEFAULT_PAGE_SIZE + 1 + assert len(response.data["results"]) == self.DEFAULT_PAGE_SIZE + assert response.data["num_pages"] == 2 + assert "page=2" in response.data["next"] + + def test_a_page_of_attempts_carries_a_hundred_of_them_however_many_are_asked_for(self): + self.extra_attempts(self.MAX_PAGE_SIZE) + self.login(self.owner) + response = self.client.get(self.list_url, {"page_size": 1000}) + assert response.status_code == status.HTTP_200_OK + assert response.data["count"] == self.MAX_PAGE_SIZE + 1 + assert len(response.data["results"]) == self.MAX_PAGE_SIZE + assert response.data["num_pages"] == 2 + assert response.data["next"] is not None + + +@skip_unless_lms +class VerificationReadsDoNotWriteTests(VerificationTestCase): + """Reading identity verification changes nothing a later read would see.""" + + def setUp(self): + super().setUp() + ManualVerification.objects.create(user=self.owner, status="approved", reason="Checked in person") + + def assert_no_writes(self, address, params=None, expect=status.HTTP_200_OK, **headers): + """ + Read the address and assert the request wrote nothing, whatever it answered. + + Request headers given here reach the client, which is how a read + presented with a token is captured alongside one made from a session. + Work handed to the end of the transaction is run inside the capture, + so a write put off until the request is over is seen here too. + """ + with CaptureQueriesContext(connection) as captured: + with self.captureOnCommitCallbacks(execute=True): + response = self.client.get(address, params or {}, **headers) + assert response.status_code == expect + assert write_queries(captured) == [] + return response + + def other_status_address(self): + """Return the status address of the account the branch fixtures below belong to.""" + return self.status_address(self.other.username) + + def test_reading_a_status_writes_nothing(self): + self.login(self.owner) + response = self.assert_no_writes(self.status_url) + assert response.data["status"] == "approved" + + def test_reading_an_accepted_status_writes_nothing(self): + self.approve(self.attempt) + self.login(self.owner) + response = self.assert_no_writes(self.status_url) + assert response.data["status"] == "approved" + + def test_reading_an_accepted_status_about_to_run_out_writes_nothing(self): + attempt = self.approve( + SoftwareSecurePhotoVerification.objects.create(user=self.other, status="submitted"), + expires_in_days=10, + ) + self.login(self.other) + response = self.assert_no_writes(self.other_status_address()) + assert response.data["status"] == "approved" + assert response.data["expiration_datetime"] == attempt.expiration_datetime.date().strftime( + "%m/%d/%Y", + ) + + def test_reading_a_pending_status_writes_nothing(self): + SoftwareSecurePhotoVerification.objects.create(user=self.other, status="submitted") + self.login(self.other) + response = self.assert_no_writes(self.other_status_address()) + assert response.data["status"] == "pending" + + def test_reading_a_turned_down_status_writes_nothing(self): + SoftwareSecurePhotoVerification.objects.create( + user=self.other, status="denied", error_msg='[{"userPhotoReasons": ["Face out of view"]}]', + ) + self.login(self.other) + response = self.assert_no_writes(self.other_status_address()) + assert response.data["status"] == "must_reverify" + + def test_reading_a_status_whose_proof_has_run_out_writes_nothing(self): + self.run_out(SoftwareSecurePhotoVerification.objects.create(user=self.other, status="submitted")) + self.login(self.other) + response = self.assert_no_writes(self.other_status_address()) + assert response.data["status"] == "expired" + + def test_reading_the_status_of_a_proof_that_ran_out_unseen_writes_nothing(self): + self.run_out(ManualVerification.objects.create( + user=self.other, status="approved", reason="Checked in person", + )) + self.login(self.other) + response = self.assert_no_writes(self.other_status_address()) + assert response.data["status"] == "none" + assert response.data["is_verified"] is False + + def test_reading_a_status_proved_by_signing_in_elsewhere_writes_nothing(self): + SSOVerificationFactory(user=self.other, status="approved", identity_provider_slug="idp") + self.login(self.other) + response = self.assert_no_writes(self.other_status_address()) + assert response.data["status"] == "approved" + assert response.data["is_verified"] is True + + def test_reading_a_status_proved_in_person_writes_nothing(self): + ManualVerification.objects.create(user=self.other, status="approved", reason="Checked in person") + self.login(self.other) + response = self.assert_no_writes(self.other_status_address()) + assert response.data["status"] == "approved" + assert response.data["is_verified"] is True + + def test_reading_a_status_as_staff_writes_nothing(self): + self.login(self.staff) + response = self.assert_no_writes(self.status_url) + assert response.data["status"] == "approved" + + def test_asking_for_a_status_with_a_head_request_writes_nothing(self): + self.login(self.owner) + with CaptureQueriesContext(connection) as captured: + with self.captureOnCommitCallbacks(execute=True): + response = self.client.head(self.status_url) + assert response.status_code == status.HTTP_200_OK + assert write_queries(captured) == [] + + def test_reading_the_attempts_writes_nothing(self): + self.login(self.owner) + response = self.assert_no_writes(self.list_url) + assert response.data["count"] == 2 + + def test_reading_the_attempts_in_the_other_order_writes_nothing(self): + self.login(self.owner) + response = self.assert_no_writes(self.list_url, {"ordering": "updated_at"}) + assert response.data["count"] == 2 + + def test_reading_a_page_further_in_writes_nothing(self): + for index in range(5): + SSOVerificationFactory(user=self.owner, status="approved", identity_provider_slug=f"idp{index}") + self.login(self.owner) + response = self.assert_no_writes(self.list_url, {"page": 2, "page_size": 3}) + assert response.data["current_page"] == 2 + assert len(response.data["results"]) == 3 + + def test_reading_an_empty_page_of_attempts_writes_nothing(self): + self.login(self.other) + response = self.assert_no_writes(self.list_address(self.other.username)) + assert response.data["count"] == 0 + + def test_reading_the_attempts_as_staff_writes_nothing(self): + self.login(self.staff) + response = self.assert_no_writes(self.list_url) + assert response.data["count"] == 2 + + def test_asking_for_the_attempts_with_a_head_request_writes_nothing(self): + self.login(self.owner) + with CaptureQueriesContext(connection) as captured: + with self.captureOnCommitCallbacks(execute=True): + response = self.client.head(self.list_url) + assert response.status_code == status.HTTP_200_OK + assert write_queries(captured) == [] + + def test_reading_a_status_a_token_identifies_its_caller_by_writes_nothing(self): + """ + A caller resolved from a token reads as a signed-in one does. + + A token is how a service or a micro-frontend reaches these addresses, + and the layer that resolves one runs before the handler, so the reads + are captured under both ways of identifying the caller. + """ + response = self.assert_no_writes(self.status_url, **self.token_headers(self.owner)) + assert response.data["status"] == "approved" + + def test_reading_the_attempts_a_token_identifies_its_caller_by_writes_nothing(self): + response = self.assert_no_writes(self.list_url, **self.token_headers(self.owner)) + assert response.data["count"] == 2 + + def test_a_staff_token_reading_another_users_status_and_attempts_writes_nothing(self): + headers = self.token_headers(self.staff) + status_answer = self.assert_no_writes(self.status_url, **headers) + assert status_answer.data["status"] == "approved" + list_answer = self.assert_no_writes(self.list_url, **headers) + assert list_answer.data["count"] == 2 + + def test_refusing_an_anonymous_caller_writes_nothing(self): + for address in (self.status_url, self.list_url): + response = self.assert_no_writes(address, expect=status.HTTP_401_UNAUTHORIZED) + assert_error_envelope(response, expected_status=401, expected_type_slug="authn") + + def test_refusing_another_learner_writes_nothing(self): + self.login(self.other) + for address in (self.status_url, self.list_url): + response = self.assert_no_writes(address, expect=status.HTTP_403_FORBIDDEN) + assert_error_envelope(response, expected_status=403, expected_type_slug="authz") + + def test_reporting_a_name_no_account_holds_writes_nothing(self): + self.login(self.staff) + for address in (self.status_address("nobody-at-all"), self.list_address("nobody-at-all")): + response = self.assert_no_writes(address, expect=status.HTTP_404_NOT_FOUND) + assert_error_envelope(response, expected_status=404, expected_type_slug="not-found") + + def test_refusing_a_query_parameter_these_addresses_do_not_read_writes_nothing(self): + self.login(self.owner) + for address in (self.status_url, self.list_url): + response = self.assert_no_writes( + address, {"username": self.owner.username}, expect=status.HTTP_400_BAD_REQUEST, + ) + assert_error_envelope(response, expected_status=400, expected_type_slug="validation") + + +@skip_unless_lms +class NothingOnRecordTests(VerificationTestCase): + """What the addresses under one account answer for a user who has done nothing yet.""" + + def setUp(self): + super().setUp() + self.newcomer = UserFactory.create( + username="verify-newcomer", email="verify-newcomer@example.com", password=PASSWORD, + ) + UserProfile.objects.filter(user=self.newcomer).delete() + assert not UserProfile.objects.filter(user=self.newcomer).exists() + + def test_an_account_with_nothing_on_record_is_answered_at_each_of_its_addresses(self): + """ + A user who has been through no check and holds no profile is answered at all three addresses. + + Nothing on record is something to report, so the summary, the page of + attempts and the account itself all answer, and they answer the same + way as each other. + """ + self.login(self.newcomer) + standing = self.client.get(self.status_address(self.newcomer.username)) + assert standing.status_code == status.HTTP_200_OK + assert standing.data == { + "is_verified": False, "status": "none", "expiration_datetime": "", + } + + attempts = self.client.get(self.list_address(self.newcomer.username)) + assert attempts.status_code == status.HTTP_200_OK + assert attempts.data["count"] == 0 + assert attempts.data["results"] == [] + + account = self.client.get(reverse("user_v2:account_detail", kwargs={"username": "me"})) + assert account.status_code == status.HTTP_200_OK + assert account.data["username"] == self.newcomer.username + + def test_the_addresses_of_a_name_no_account_holds_are_all_absent(self): + """A missing user is what makes one of these addresses absent, and the only thing that does.""" + self.login(self.staff) + for address in ( + self.status_address("nobody-at-all"), + self.list_address("nobody-at-all"), + reverse("user_v2:account_detail", kwargs={"username": "nobody-at-all"}), + ): + assert_error_envelope( + self.client.get(address), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + +@skip_unless_lms +class VerificationDisabledCallerTests(VerificationTestCase): + """What these addresses answer a caller whose own account has been disabled.""" + + def test_a_token_held_by_a_disabled_staff_account_may_not_read_another_users_records(self): + """A privilege does not survive the deactivation of the account that held it.""" + headers = self.token_headers(self.staff) + assert self.client.get(self.status_url, **headers).status_code == status.HTTP_200_OK + assert self.client.get(self.list_url, **headers).status_code == status.HTTP_200_OK + self.staff.is_active = False + self.staff.save() + for address in (self.status_url, self.list_url): + assert_error_envelope( + self.client.get(address, **headers), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_disabled_account_still_reads_its_own_records(self): + """What a user proved about themselves stays readable to them while the account is disabled.""" + headers = self.token_headers(self.owner) + self.owner.is_active = False + self.owner.save() + summary = self.client.get(self.status_url, **headers) + assert summary.status_code == status.HTTP_200_OK + assert summary.data == {"is_verified": False, "status": "pending", "expiration_datetime": ""} + page = self.client.get(self.list_url, **headers) + assert page.status_code == status.HTTP_200_OK + assert page.data["count"] == 1 + + def test_a_disabled_staff_account_still_reads_its_own_records(self): + """The staff half of the check is the one the disabled account loses.""" + headers = self.token_headers(self.staff) + self.staff.is_active = False + self.staff.save() + summary = self.client.get(self.status_address(self.staff.username), **headers) + assert summary.status_code == status.HTTP_200_OK + assert summary.data == {"is_verified": False, "status": "none", "expiration_datetime": ""} + page = self.client.get(self.list_address(self.staff.username), **headers) + assert page.status_code == status.HTTP_200_OK + assert page.data["count"] == 0 + + +@skip_unless_lms +class VerificationAddressedNameTests(VerificationTestCase): + """ + These addresses carry the name an account is stored under. + + The account collection reads ``me`` as the account of the caller; the + addresses beneath an account read the name they carry as it stands, so a + caller that sends ``me`` to one of them is answered as a caller naming any + other account is. + """ + + def test_a_learner_sending_the_collections_own_name_is_refused(self): + self.login(self.owner) + for address in (self.status_address("me"), self.list_address("me")): + assert_error_envelope( + self.client.get(address), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + + def test_a_staff_caller_sending_it_is_told_no_account_holds_that_name(self): + self.login(self.staff) + for address in (self.status_address("me"), self.list_address("me")): + assert_error_envelope( + self.client.get(address), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + + def test_the_account_holding_that_name_is_served_at_it(self): + """A user may register the name, and reads their own records where it is addressed.""" + holder = UserFactory.create(username="me", email="me@example.com", password=PASSWORD) + SoftwareSecurePhotoVerification.objects.create(user=holder, status="approved") + self.login(holder) + summary = self.client.get(self.status_address("me")) + assert summary.status_code == status.HTTP_200_OK + assert summary.data["status"] == "approved" + page = self.client.get(self.list_address("me")) + assert page.status_code == status.HTTP_200_OK + assert page.data["count"] == 1 + assert page.data["results"][0]["status"] == "approved" + + +@skip_unless_lms +class VerificationParityTests(VerificationTestCase): + """The same fixtures through the version 1 and the version 2 addresses.""" + + def setUp(self): + super().setUp() + ManualVerification.objects.create(user=self.owner, status="approved", reason="Checked in person") + + def test_both_versions_report_the_same_status(self): + self.login(self.owner) + earlier = self.client.get(earlier_status_address(self.owner.username)) + later = self.client.get(self.status_url) + assert earlier.status_code == later.status_code == status.HTTP_200_OK + assert later.data == earlier.data + + def test_both_versions_report_the_same_accepted_status(self): + self.approve(self.attempt, expires_in_days=10) + self.login(self.owner) + earlier = self.client.get(earlier_status_address(self.owner.username)) + later = self.client.get(self.status_url) + assert later.data == earlier.data + assert later.data["is_verified"] is True + + def test_both_versions_carry_the_same_attempts(self): + self.login(self.owner) + earlier = self.client.get(earlier_list_address(self.owner.username)) + later = self.client.get(self.list_url) + assert earlier.status_code == later.status_code == status.HTTP_200_OK + # The one declared difference: the attempts come back in a page rather + # than as a bare list, and the rows themselves are unchanged. + assert isinstance(earlier.data, list) + assert later.data["results"] == earlier.data + assert later.data["count"] == len(earlier.data) + + def test_both_versions_refuse_a_learner_reading_another_users_attempts(self): + self.login(self.other) + earlier = self.client.get(earlier_list_address(self.owner.username)) + later = self.client.get(self.list_url) + assert earlier.status_code == later.status_code == status.HTTP_403_FORBIDDEN + assert earlier.data == {"detail": "You do not have permission to perform this action."} + assert_error_envelope(later, expected_status=403, expected_type_slug="authz") + + def test_the_status_of_a_user_who_has_been_through_no_checks_is_reported_rather_than_refused(self): + """ + Declared difference: a user with nothing on record has a status here. + + The earlier address answers the same way for a user who has been + through no check and for a name no account holds, so a client cannot + tell a typo from a user who has not started. Here the summary says + `none` and the refusal is kept for the name no account holds, which + the second half asserts. + """ + self.login(self.other) + earlier = self.client.get(earlier_status_address(self.other.username)) + later = self.client.get(self.status_address(self.other.username)) + assert earlier.status_code == status.HTTP_404_NOT_FOUND + assert later.status_code == status.HTTP_200_OK + assert later.data == {"is_verified": False, "status": "none", "expiration_datetime": ""} + + self.client.logout() + self.login(self.staff) + assert self.client.get(self.status_address("nobody-at-all")).status_code == status.HTTP_404_NOT_FOUND + + def test_the_attempts_of_a_user_who_has_been_through_no_checks_are_an_empty_page(self): + """ + Declared difference: an existing user with no attempts has an empty page here. + + The earlier address answers the same way for a user who has made no + attempt and for a name no account holds, so a client cannot tell a typo + from an empty history. Here the page is empty and the refusal is kept + for the name no account holds, which the second half asserts. + """ + self.login(self.other) + earlier = self.client.get(earlier_list_address(self.other.username)) + later = self.client.get(self.list_address(self.other.username)) + assert earlier.status_code == status.HTTP_404_NOT_FOUND + assert later.status_code == status.HTTP_200_OK + assert later.data["count"] == 0 + assert later.data["results"] == [] + + self.client.logout() + self.login(self.staff) + assert self.client.get(self.list_address("nobody-at-all")).status_code == status.HTTP_404_NOT_FOUND + + def test_both_versions_refuse_an_address_that_is_not_exactly_the_callers_name(self): + self.login(self.owner) + shouted = self.owner.username.upper() + for earlier_address, later_address in ( + (earlier_status_address(shouted), self.status_address(shouted)), + (earlier_list_address(shouted), self.list_address(shouted)), + ): + earlier = self.client.get(earlier_address) + later = self.client.get(later_address) + assert earlier.status_code == status.HTTP_403_FORBIDDEN + assert earlier.data == {"detail": "You do not have permission to perform this action."} + assert_error_envelope(later, expected_status=403, expected_type_slug="authz") + + def test_an_anonymous_caller_is_refused_by_both_and_told_so_by_this_one(self): + earlier = self.client.get(earlier_list_address(self.owner.username)) + later = self.client.get(self.list_url) + assert earlier.status_code == later.status_code == status.HTTP_401_UNAUTHORIZED + assert_error_envelope(later, expected_status=401, expected_type_slug="authn") + + +#: What a page of attempts costs, and what a status costs, measured on the +#: version 1 addresses first. The attempts come from four tables, one per kind +#: of check, and the page is cut from what they return, so a page costs the +#: same whatever it carries. A status reads those four tables and then works +#: out when an accepted proof runs out, which costs more. Both versions read +#: the same rows over the same fixtures, so each number is the one number +#: asserted on both addresses: a change on either side is a change in what the +#: answer costs. +LIST_QUERIES = EARLIER_LIST_QUERIES = 18 +STATUS_QUERIES = EARLIER_STATUS_QUERIES = 22 + + +@pytest.fixture(name="verified_user") +@skip_unless_lms +def verified_user_fixture(client, django_user_model): # pylint: disable=unused-argument + """Sign a learner in who has been through several identity checks.""" + owner = UserFactory.create(username="count-verify-owner", password=PASSWORD) + SoftwareSecurePhotoVerification.objects.create(user=owner, status="submitted") + ManualVerification.objects.create(user=owner, status="approved", reason="Checked in person") + for index in range(4): + SSOVerificationFactory(user=owner, status="approved", identity_provider_slug=f"idp{index}") + assert client.login(username=owner.username, password=PASSWORD) + # The first authenticated request of a session populates caches the rest + # of the session reuses; the counts below are the steady-state ones. + client.get(reverse("user_v2:account_verification_list", kwargs={"username": owner.username})) + return owner + + +@pytest.mark.django_db +@pytest.mark.parametrize("page_size", [1, 3, 6]) +@skip_unless_lms +def test_a_page_of_attempts_costs_what_the_earlier_address_costs( + client, verified_user, page_size, django_assert_num_queries, +): + with django_assert_num_queries(EARLIER_LIST_QUERIES): + earlier = client.get(f"/api/user/v1/accounts/{verified_user.username}/verifications/") + assert len(earlier.json()) == 6 + + address = reverse("user_v2:account_verification_list", kwargs={"username": verified_user.username}) + with django_assert_num_queries(LIST_QUERIES): + later = client.get(address, {"page_size": page_size}) + assert later.json()["count"] == 6 + assert len(later.json()["results"]) == page_size + + +@pytest.mark.django_db +@skip_unless_lms +def test_a_status_costs_what_the_earlier_address_costs(client, verified_user, django_assert_num_queries): + with django_assert_num_queries(EARLIER_STATUS_QUERIES): + earlier = client.get(f"/api/user/v1/accounts/{verified_user.username}/verification_status/") + assert earlier.json()["status"] == "approved" + + address = reverse("user_v2:account_verification_status", kwargs={"username": verified_user.username}) + with django_assert_num_queries(STATUS_QUERIES): + later = client.get(address) + assert later.json() == earlier.json() diff --git a/openedx/core/djangoapps/user_api/v2/urls.py b/openedx/core/djangoapps/user_api/v2/urls.py index 911fb321af69..c9a299596cbf 100644 --- a/openedx/core/djangoapps/user_api/v2/urls.py +++ b/openedx/core/djangoapps/user_api/v2/urls.py @@ -5,9 +5,17 @@ from django.urls import re_path from rest_framework.routers import SimpleRouter +from openedx.core.djangoapps.profile_images.v2.views import ProfileImageView + from .views import ( PREFERENCE_KEY_PATTERN_PARTIAL, + AccountDeactivationView, + AccountViewSet, CountryTimeZoneViewSet, + EmailSearchViewSet, + IDVerificationStatusView, + IDVerificationViewSet, + NameChangeViewSet, UnknownAddressView, UserPreferenceViewSet, UserViewSet, @@ -20,6 +28,14 @@ #: below under the same name. REPLACED_ROUTER_ROUTE = "user_preference_detail" +#: The addresses under this prefix that belong to the authentication app, which +#: this mount is matched before. They are spelled out one by one rather than by +#: the segment they share, so that only what that app serves is left to it and +#: every other address under this prefix is answered here. The trailing slash is +#: optional, which leaves an address sent without one to be redirected to the +#: slashed form the app serves rather than answered as unknown. +OTHER_APP_ADDRESSES = r"account/(registration|login_session)/?" + def without_route(routes, name): """ @@ -48,7 +64,23 @@ class SnakeCaseRouter(SimpleRouter): routes = [route._replace(name=route.name.replace("-", "_")) for route in SimpleRouter.routes] +# An address beneath an account is plural where it names rows that accumulate +# behind it, and singular where it names the one thing every account has. router = SnakeCaseRouter() +router.register(r"accounts", AccountViewSet, basename="account") +# An identity check belongs to the user who went through it and is reached by +# no other route, so the collection is registered beneath the account it +# belongs to. +router.register( + rf"accounts/(?P{settings.USERNAME_REGEX_PARTIAL})/verifications", + IDVerificationViewSet, + basename="account_verification", +) +# What follows the account collection in an address is the name of an account, +# and a user may register any name, so the search over email addresses stands +# beside the accounts rather than under them. +router.register(r"email_searches", EmailSearchViewSet, basename="email_search") +router.register(r"name_changes", NameChangeViewSet, basename="name_change") router.register(r"users", UserViewSet, basename="user") router.register(r"user_preferences", UserPreferenceViewSet, basename="user_preference") router.register(r"time_zones", CountryTimeZoneViewSet, basename="time_zone") @@ -56,6 +88,29 @@ class SnakeCaseRouter(SimpleRouter): urlpatterns = [ *without_route(router.urls, REPLACED_ROUTER_ROUTE), + # The image belongs to one account and is stored in several sizes, so it + # is addressed as a property of that account rather than as a collection. + re_path( + rf"^accounts/(?P{settings.USERNAME_REGEX_PARTIAL})/profile_image/$", + ProfileImageView.as_view(), + name="account_profile_image", + ), + # Disabling an account is something a privileged caller does to somebody + # else's account rather than a property of that account, so it is served + # by a view of its own beneath the account it names. + re_path( + rf"^accounts/(?P{settings.USERNAME_REGEX_PARTIAL})/deactivation/$", + AccountDeactivationView.as_view(), + name="account_deactivation", + ), + # Where one account's owner stands on having proved their identity is + # worked out from the attempts behind it rather than stored, and there is + # one such summary per account, so it is served from an address of its own. + re_path( + rf"^accounts/(?P{settings.USERNAME_REGEX_PARTIAL})/verification_status/$", + IDVerificationStatusView.as_view(), + name="account_verification_status", + ), # The username half carries the pattern a username is allowed to match and # the key half takes the rest of the segment. re_path( @@ -64,8 +119,9 @@ class SnakeCaseRouter(SimpleRouter): UserPreferenceViewSet.as_view({"get": "retrieve"}), name="user_preference_detail", ), - # The authentication app serves two addresses under this prefix, which this - # mount is matched before; everything else under it belongs to this version. - # The route answers rather than reverses, so it carries no name. - re_path(r"^(?!account/).*$", UnknownAddressView.as_view()), + # Everything under this prefix that the authentication app does not serve + # belongs to this version, including an address no route of it answers, + # which is refused in the body the rest of this version answers with. The + # route answers rather than reverses, so it carries no name. + re_path(rf"^(?!{OTHER_APP_ADDRESSES}$).*$", UnknownAddressView.as_view()), ] diff --git a/openedx/core/djangoapps/user_api/v2/view_utils.py b/openedx/core/djangoapps/user_api/v2/view_utils.py new file mode 100644 index 000000000000..4a7b9124ab0f --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/view_utils.py @@ -0,0 +1,73 @@ +"""View behaviour shared by the endpoints of version 2 of the User API.""" + +import logging + +from drf_spectacular.utils import OpenApiResponse +from rest_framework.exceptions import ValidationError +from rest_framework.settings import api_settings + +from .serializers import ErrorResponse + +log = logging.getLogger(__name__) + +#: Groups the user addresses of every version under one heading in the schema. +USER_TAG = "user" + +#: Marks the operations a generated client library is built from. +SDK_TAG = "openedx-platform-sdk" + +#: The framework's own representation selector. This deployment reads nothing +#: from it, since ``URL_FORMAT_OVERRIDE`` is unset and JSON is the only +#: renderer, and a caller that sends it anyway is answered rather than refused. +FORMAT_PARAM = "format" + +RESP_UNAUTHENTICATED = OpenApiResponse(ErrorResponse, description="The requester is not authenticated.") +RESP_UNREADABLE_BODY = OpenApiResponse( + ErrorResponse, description="The request body is in a media type this endpoint cannot read.", +) + + +class StrictQueryParametersMixin: + """ + Refuses a query parameter the view reads nothing from. + + An unknown parameter is otherwise dropped in silence: a caller that + mistyped a filter, or kept one an earlier version of the endpoint + answered, receives the whole collection and reads it as the narrowed page + it asked for. The names a view answers to are assembled from what it + declares (its paginator, its sort backend, its filter set, and the + serializer that validates its query string), so a parameter that is added + or renamed cannot fall out of step with this check. + """ + + #: Names the view reads that none of the declarations below account for. + extra_query_params = () + + def known_query_params(self): + """Return the names of the query parameters this view reads.""" + names = {FORMAT_PARAM, api_settings.URL_FORMAT_OVERRIDE, *self.extra_query_params} + pagination_class = getattr(self, "pagination_class", None) + if pagination_class is not None: + names.update({pagination_class.page_query_param, pagination_class.page_size_query_param}) + for backend in getattr(self, "filter_backends", ()): + names.add(getattr(backend, "ordering_param", None)) + filterset_class = getattr(self, "filterset_class", None) + if filterset_class is not None: + names.update(filterset_class.base_filters) + query_serializer_class = getattr(self, "query_serializer_class", None) + if query_serializer_class is not None: + names.update(query_serializer_class().fields) + return names - {None} + + def initial(self, request, *args, **kwargs): + """Check the query string once the caller has been admitted.""" + super().initial(request, *args, **kwargs) + known = self.known_query_params() + unknown = sorted(set(request.query_params) - known) + if unknown: + log.info("Query refused on %s: %r", type(self).__name__, unknown) + offered = ", ".join(sorted(known)) + raise ValidationError({ + name: [f"No such query parameter. Send any of: {offered}."] + for name in unknown + }) diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 6022c5dcec40..7268cce40f36 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -4,34 +4,83 @@ from django.conf import settings from django.contrib.auth.models import User # pylint: disable=imported-auth-user +from django.db import transaction from django.db.models import F from django.http import Http404 from django_filters.rest_framework import DjangoFilterBackend -from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema, extend_schema_view +from django_ratelimit.core import is_ratelimited +from drf_spectacular.utils import ( + OpenApiExample, + OpenApiParameter, + OpenApiResponse, + extend_schema, + extend_schema_view, +) +from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser from edx_rest_framework_extensions.mixins import StandardizedErrorMixin from edx_rest_framework_extensions.paginators import IterablePaginationMixin +from edx_rest_framework_extensions.permissions import IsStaff from edx_rest_framework_extensions.scoping import FullScopePolicy, ScopedQuerysetMixin from edx_rest_framework_extensions.shaping import MinimalViewMixin, project -from rest_framework import permissions, viewsets -from rest_framework.exceptions import NotFound, ValidationError +from rest_framework import permissions, status, viewsets +from rest_framework.decorators import action +from rest_framework.exceptions import APIException, NotFound, PermissionDenied, Throttled, ValidationError +from rest_framework.parsers import JSONParser +from rest_framework.response import Response from rest_framework.reverse import reverse from rest_framework.settings import api_settings from rest_framework.views import APIView +from common.djangoapps.student.models import UserProfile, is_email_retired +from common.djangoapps.student.models_api import confirm_name_change, do_name_change_request, get_pending_name_change +from common.djangoapps.track import segment +from lms.djangoapps.verify_student.services import IDVerificationService +from openedx.core.djangoapps.user_api import accounts +from openedx.core.djangoapps.user_api.accounts.api import get_account_settings, update_account_settings +from openedx.core.djangoapps.user_api.accounts.permissions import CanDeactivateUser, CanGetAccountInfo +from openedx.core.djangoapps.user_api.errors import ( + AccountUpdateError, + AccountValidationError, + UserNotAuthorized, + UserNotFound, +) from openedx.core.djangoapps.user_api.models import UserPreference from openedx.core.djangoapps.user_api.preferences.api import get_country_time_zones +from openedx.core.djangolib.default_auth_classes import DefaultJwtAuthentication +from openedx.core.lib.api.parsers import MergePatchParser -from .errors import CatalogedRequestErrorsMixin +from .errors import CatalogedRequestErrorsMixin, ErrorExtensionsMixin, RetiredAccount from .filters import StrictOrderingFilter, UserFilterSet, UserPreferenceFilterSet from .paginators import UserApiPagination -from .permissions import IsActiveUser +from .permissions import CanSelectAccountsByContact, IsActiveUser, IsAddressedUser, IsStaffOrAbsent from .schema import ResponseShapes +from .selectors import ( + accounts_holding_emails, + cancellable_retirement_for_email, + username_holding_email, + username_holding_id, + usernames_among, +) from .serializers import ( + ACCOUNT_DEFAULT_SORT, + ACCOUNT_MINIMAL_FIELDS, + EMAIL_SEARCH_MAX_ADDRESSES, FULL_VIEW, MINIMAL_VIEW, PREFERENCE_MINIMAL_FIELDS, + SHARED_VIEW, USER_MINIMAL_FIELDS, + VERIFICATION_DEFAULT_SORT, + AccountMinimalSerializer, + AccountProjectionSerializer, + AccountQuerySerializer, + AccountSerializer, + AccountUpdateSerializer, + EmailSearchResultSerializer, + EmailSearchSerializer, ErrorResponse, + NameChangeSerializer, + RetiredAccountErrorResponse, TimeZoneQuerySerializer, TimeZoneSerializer, UserDirectoryMinimalSerializer, @@ -40,13 +89,21 @@ UserPreferenceRecordMinimalSerializer, UserPreferenceRecordProjectionSerializer, UserPreferenceRecordSerializer, + VerificationQuerySerializer, + VerificationSerializer, + VerificationStatusSerializer, full_view_requested, ) +from .view_utils import ( + RESP_UNAUTHENTICATED, + RESP_UNREADABLE_BODY, + SDK_TAG, + USER_TAG, + StrictQueryParametersMixin, +) log = logging.getLogger(__name__) -USER_TAG = "user" - #: Fields the user directory sorts on, and the order it uses when asked for none. USER_SORT_FIELDS = ("username", "date_joined") USER_DEFAULT_SORT = ("username",) @@ -60,6 +117,10 @@ #: segment; the route and the published address are built from this one pattern. PREFERENCE_KEY_PATTERN_PARTIAL = "[^/]+" +#: What the identity verification service reports for a user whose proof of +#: identity has been accepted. +APPROVED_STATUS = "approved" + def _query_param(name, description, **kwargs): """Build an optional query parameter for the published schema.""" @@ -102,16 +163,28 @@ def _path_param(name, description, pattern): rf"^{PREFERENCE_KEY_PATTERN_PARTIAL}$", ) +#: The presets an account response answers to. +ACCOUNT_PRESETS = (MINIMAL_VIEW, SHARED_VIEW) + +#: The member of the account collection that addresses the caller's own account. +OWN_ACCOUNT_IDENTIFIER = "me" + +#: The account actions that answer with an account, and so read the parameters +#: that shape one. +SHAPED_ACCOUNT_ACTIONS = ("list", "retrieve", "partial_update") + +#: The properties whose change is limited to a rate, and the setting carrying +#: the limit of each. +RATE_LIMITED_ACCOUNT_FIELDS = ( + ("email", "EMAIL_CHANGE_RATE_LIMIT"), + ("secondary_email", "SECONDARY_EMAIL_RATE_LIMIT"), +) + #: Parameters that shape a response rather than select the rows in it. VIEW_PARAM = "view" FIELDS_PARAM = "fields" RESPONSE_SHAPING_PARAMS = (VIEW_PARAM, FIELDS_PARAM) -#: The framework's own representation selector. This deployment reads nothing -#: from it, since ``URL_FORMAT_OVERRIDE`` is unset and JSON is the only -#: renderer, and a caller that sends it anyway is answered rather than refused. -FORMAT_PARAM = "format" - _FIELDS_PARAM = _query_param( FIELDS_PARAM, "Comma-separated list of top-level field names to keep in each returned object. " @@ -154,13 +227,50 @@ def _ordering_param(sort_fields, default): _USER_ORDERING_PARAM = _ordering_param(USER_SORT_FIELDS, USER_DEFAULT_SORT) _PREFERENCE_ORDERING_PARAM = _ordering_param(PREFERENCE_SORT_FIELDS, PREFERENCE_DEFAULT_SORT) -_RESP_UNAUTHENTICATED = OpenApiResponse(ErrorResponse, description="The requester is not authenticated.") _RESP_FORBIDDEN = OpenApiResponse(ErrorResponse, description="The requester may not use this endpoint.") _RESP_NOT_FOUND = OpenApiResponse(ErrorResponse, description="No such resource.") _RESP_NO_SUCH_PAGE = OpenApiResponse(ErrorResponse, description="There is no such page of results.") _RESP_BAD_REQUEST = OpenApiResponse( ErrorResponse, description="A query parameter is missing, invalid, or not one this endpoint reads.", ) +_RESP_UNUSABLE_BODY = OpenApiResponse( + ErrorResponse, + description=( + "The request body is not well formed in the media type it was sent in, or carries a " + "value this endpoint will not take. A query parameter this endpoint does not read is " + "refused here too." + ), +) +_RESP_RATE_LIMITED = OpenApiResponse( + ErrorResponse, description="The caller has changed this property too often lately and has to wait.", +) +_RESP_CHANGE_FAILED = OpenApiResponse( + ErrorResponse, + description=( + "The change was asked for correctly and could not be carried out. Sending it again " + "with something else in it does not help; sending the same request later may." + ), +) +_RESP_NO_SUCH_ACCOUNT = OpenApiResponse( + ErrorResponse, description="No account is held at the address given.", +) +_RESP_CHANGED_ACCOUNT_GONE = OpenApiResponse( + ErrorResponse, + description=( + "The account that was addressed is no longer there. Only the caller's own account is " + "changed here, so a name nobody holds is refused as somebody else's account instead of " + "being reported as missing." + ), +) +_RESP_NO_SUCH_PAGE_OR_RETIRED = OpenApiResponse( + RetiredAccountErrorResponse, + description=( + "There is no such page of results, or the `email` address given is one an account held " + "before it was retired. In that second case the body also carries `can_cancel_retirement` " + "and `retirement_id`, which name what is left of that account to a caller able to reverse " + "the retirement." + ), +) #: A directory entry comes back whole, as the identifying fields the ``minimal`` #: preset keeps, or as the properties ``fields`` selected. @@ -173,6 +283,128 @@ def _ordering_param(sort_fields, default): ], ) +_ACCOUNT_PATH_PARAM = _path_param( + "username", + "Unique name of the user whose account is addressed. " + f"`{OWN_ACCOUNT_IDENTIFIER}` names the account of the caller, so an account holding that " + "name is read through the collection, with `username=` naming it.", + _USERNAME_PATTERN, +) +_DEACTIVATION_PATH_PARAM = _path_param( + "username", + "Unique name of the user whose account is deactivated. The name is read as it is stored, " + f"`{OWN_ACCOUNT_IDENTIFIER}` included: this action disables the account the address names, " + "never the account of the caller making the request.", + _USERNAME_PATTERN, +) +_ACCOUNT_VIEW_PARAM = _query_param( + VIEW_PARAM, + "Response preset. `minimal` reduces the account to the properties that identify its owner; " + "`shared` returns only the properties the owner shares with everybody, even to a caller who " + "may see more. Omit it, or send it empty, to receive everything the caller may see.", + enum=[*ACCOUNT_PRESETS, ""], +) + +#: An account comes back with every property the caller may see, as the +#: identifying properties the ``minimal`` preset keeps, or as the properties +#: ``fields`` selected. +_ACCOUNT_SHAPES = ResponseShapes( + component_name="AccountResponse", + serializers=[ + AccountSerializer, + AccountMinimalSerializer, + AccountProjectionSerializer, + ], +) + +_ACCOUNT_IMAGE_EXAMPLE = { + "has_image": True, + "image_url_full": "https://example.com/media/profile_images/jane_doe_500.jpg", + "image_url_large": "https://example.com/media/profile_images/jane_doe_120.jpg", + "image_url_medium": "https://example.com/media/profile_images/jane_doe_50.jpg", + "image_url_small": "https://example.com/media/profile_images/jane_doe_30.jpg", +} + +_ACCOUNT_EXAMPLES = [ + OpenApiExample( + "Your own account", + description=( + "Everything an account carries, which is what its owner and a staff caller receive." + ), + value={ + "username": "jane_doe", + "profile_image": _ACCOUNT_IMAGE_EXAMPLE, + "account_privacy": "custom", + "email": "jane.doe@example.com", + "id": 42, + "name": "Jane Doe", + "bio": "Teaches mathematics.", + "country": "US", + "state": "MA", + "date_joined": "2024-03-01T09:30:00Z", + "last_login": "2026-02-11T18:02:41Z", + "is_active": True, + "gender": "f", + "year_of_birth": 1985, + "level_of_education": "m", + "goals": "Finish the course.", + "mailing_address": "12 Park Avenue", + "phone_number": "+18005555555", + "language_proficiencies": [{"code": "fr"}], + "social_links": [ + {"platform": "twitter", "social_link": "https://www.twitter.com/example"}, + ], + "extended_profile": [{"field_name": "occupation", "field_value": "Teacher"}], + "requires_parental_consent": False, + "pending_name_change": None, + "verified_name": "Jane Doe", + "secondary_email": None, + "secondary_email_enabled": None, + "course_certificates": None, + "time_zone": None, + }, + response_only=True, + status_codes=["200"], + ), + OpenApiExample( + "An account somebody else owns", + description=( + "The properties this owner shares with every learner. An owner who shares field by " + "field shares fewer, and one who shares nothing leaves only the three properties " + "every account carries." + ), + value={ + "username": "jane_doe", + "profile_image": _ACCOUNT_IMAGE_EXAMPLE, + "account_privacy": "all_users", + "bio": "Teaches mathematics.", + "country": "US", + "course_certificates": None, + "date_joined": "2024-03-01T09:30:00Z", + "language_proficiencies": [{"code": "fr"}], + "level_of_education": "m", + "social_links": [ + {"platform": "twitter", "social_link": "https://www.twitter.com/example"}, + ], + "time_zone": None, + }, + response_only=True, + status_codes=["200"], + ), + OpenApiExample( + "An account reduced to what identifies its owner", + description="What `view=minimal` answers with; `fields` selects any other set.", + value={ + "username": "jane_doe", + "email": "jane.doe@example.com", + "name": "Jane Doe", + "profile_image": _ACCOUNT_IMAGE_EXAMPLE, + }, + response_only=True, + status_codes=["200"], + ), +] + #: A stored preference comes back whole, as the three fields the ``minimal`` #: preset keeps, or as the properties ``fields`` selected. _PREFERENCE_SHAPES = ResponseShapes( @@ -185,6 +417,14 @@ def _ordering_param(sort_fields, default): ) +def _user_named(username): + """Return the user an address names, or refuse the address.""" + try: + return User.objects.get(username=username) + except User.DoesNotExist as exc: + raise NotFound from exc + + class _MemberLookupMixin: """Report a missing member through the standard error envelope.""" @@ -225,52 +465,6 @@ def _requested_field_names(raw): return [name.strip().split(".", 1)[0] for name in raw.split(",") if name.strip()] -class _StrictQueryParametersMixin: - """ - Refuses a query parameter the view reads nothing from. - - An unknown parameter is otherwise dropped in silence: a caller that - mistyped a filter, or kept one an earlier version of the endpoint - answered, receives the whole collection and reads it as the narrowed page - it asked for. The names a view answers to are assembled from what it - declares (its paginator, its sort backend, its filter set, and the - serializer that validates its query string), so a parameter that is added - or renamed cannot fall out of step with this check. - """ - - #: Names the view reads that none of the declarations below account for. - extra_query_params = () - - def known_query_params(self): - """Return the names of the query parameters this view reads.""" - names = {FORMAT_PARAM, api_settings.URL_FORMAT_OVERRIDE, *self.extra_query_params} - pagination_class = getattr(self, "pagination_class", None) - if pagination_class is not None: - names.update({pagination_class.page_query_param, pagination_class.page_size_query_param}) - for backend in getattr(self, "filter_backends", ()): - names.add(getattr(backend, "ordering_param", None)) - filterset_class = getattr(self, "filterset_class", None) - if filterset_class is not None: - names.update(filterset_class.base_filters) - query_serializer_class = getattr(self, "query_serializer_class", None) - if query_serializer_class is not None: - names.update(query_serializer_class().fields) - return names - {None} - - def initial(self, request, *args, **kwargs): - """Check the query string once the caller has been admitted.""" - super().initial(request, *args, **kwargs) - known = self.known_query_params() - unknown = sorted(set(request.query_params) - known) - if unknown: - log.info("Query refused on %s: %r", type(self).__name__, unknown) - offered = ", ".join(sorted(known)) - raise ValidationError({ - name: [f"No such query parameter. Send any of: {offered}."] - for name in unknown - }) - - class _ResponsePresetMixin(MinimalViewMixin): """ Applies the ``view`` and ``fields`` presets to an already serialized payload. @@ -280,6 +474,12 @@ class _ResponsePresetMixin(MinimalViewMixin): payload and would otherwise be handed the full one without being told. The same holds for a field name the response cannot carry, which would otherwise select nothing and leave the caller with empty objects. + + Both are settled as the request enters, before the address it names is + read or written. Which properties an answer can carry depends on the + caller and on the address, so the refusal comes back the same at a name + nobody holds as at one somebody does, and nothing is read or changed on + the way to it. """ #: Presets this view answers to. An empty ``view`` narrows nothing, the way @@ -287,7 +487,7 @@ class _ResponsePresetMixin(MinimalViewMixin): response_presets = () def initial(self, request, *args, **kwargs): - """Check the requested preset and fields once the caller has been admitted.""" + """Check the requested preset and fields once the caller has been admitted, before anything else.""" super().initial(request, *args, **kwargs) preset = request.query_params.get(VIEW_PARAM) if preset and preset not in self.response_presets: @@ -346,7 +546,7 @@ def shape_page(self, response, request): responses={ 200: _USER_SHAPES, 400: _RESP_BAD_REQUEST, - 401: _RESP_UNAUTHENTICATED, + 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NO_SUCH_PAGE, }, @@ -358,7 +558,7 @@ def shape_page(self, response, request): responses={ 200: _USER_SHAPES, 400: _RESP_BAD_REQUEST, - 401: _RESP_UNAUTHENTICATED, + 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NOT_FOUND, }, @@ -370,7 +570,7 @@ class UserViewSet( _ActionAddressMixin, _MemberLookupMixin, _ResponsePresetMixin, - _StrictQueryParametersMixin, + StrictQueryParametersMixin, ScopedQuerysetMixin, viewsets.ReadOnlyModelViewSet, ): @@ -430,7 +630,7 @@ def retrieve(self, request, *args, **kwargs): responses={ 200: _PREFERENCE_SHAPES, 400: _RESP_BAD_REQUEST, - 401: _RESP_UNAUTHENTICATED, + 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NO_SUCH_PAGE, }, @@ -452,7 +652,7 @@ def retrieve(self, request, *args, **kwargs): responses={ 200: _PREFERENCE_SHAPES, 400: _RESP_BAD_REQUEST, - 401: _RESP_UNAUTHENTICATED, + 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NOT_FOUND, }, @@ -463,7 +663,7 @@ class UserPreferenceViewSet( CatalogedRequestErrorsMixin, _ActionAddressMixin, _ResponsePresetMixin, - _StrictQueryParametersMixin, + StrictQueryParametersMixin, ScopedQuerysetMixin, viewsets.ReadOnlyModelViewSet, ): @@ -530,7 +730,7 @@ class CountryTimeZoneViewSet( StandardizedErrorMixin, CatalogedRequestErrorsMixin, _ActionAddressMixin, - _StrictQueryParametersMixin, + StrictQueryParametersMixin, IterablePaginationMixin, viewsets.ViewSet, ): @@ -576,6 +776,777 @@ def list(self, request): return self.paginate_iterable(request, time_zones) +def _shareable_account_fields(): + """Return every property an account's owner is able to share with another user.""" + return set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["custom_shareable_fields"]) + + +@extend_schema(tags=[SDK_TAG]) +@extend_schema_view( + list=extend_schema( + summary="List accounts", + description=( + "Returns a page of accounts. Name them with `username`, or select the one holding an " + "`email` address or an `lms_user_id`; omit all three to receive your own account. A " + "name, an address or an identifier no account holds is left out of the page, which is " + "empty when nothing given is held. Each account carries the properties the caller may " + "see: everything for your own account and for a staff caller, and otherwise the " + "properties its owner shares. " + "A property named in `fields` that an owner does not share is left out of their " + "account rather than refused, so a row of the page can come back empty." + ), + parameters=[AccountQuerySerializer, _FIELDS_PARAM], + responses={ + 200: _ACCOUNT_SHAPES, + 400: _RESP_BAD_REQUEST, + 401: RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_NO_SUCH_PAGE_OR_RETIRED, + }, + ), + retrieve=extend_schema( + summary="Get one account", + description=( + "Returns the account of this user, carrying the properties the caller may see. " + "Address `me` for the account of the caller. A property named in `fields` that " + "this owner does not share is left out rather than refused, so the answer can be " + "an empty object." + ), + parameters=[_ACCOUNT_PATH_PARAM, _ACCOUNT_VIEW_PARAM, _FIELDS_PARAM], + responses={ + 200: _ACCOUNT_SHAPES, + 400: _RESP_BAD_REQUEST, + 401: RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_NO_SUCH_ACCOUNT, + }, + examples=_ACCOUNT_EXAMPLES, + ), + partial_update=extend_schema( + summary="Change one account", + description=( + "Changes the properties named in the body and returns the account as it now stands. " + "A user may change only their own account, which `me` also addresses. The body is a " + "merge patch: only the properties it carries are changed, and `social_links` are " + "merged into the stored list by platform. A new email address takes effect only once " + "the user confirms it from the message sent there." + ), + parameters=[_ACCOUNT_PATH_PARAM, _ACCOUNT_VIEW_PARAM, _FIELDS_PARAM], + request=AccountUpdateSerializer, + responses={ + 200: _ACCOUNT_SHAPES, + 400: _RESP_UNUSABLE_BODY, + 401: RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_CHANGED_ACCOUNT_GONE, + 415: RESP_UNREADABLE_BODY, + 429: _RESP_RATE_LIMITED, + 500: _RESP_CHANGE_FAILED, + }, + ), +) +class AccountViewSet( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + ErrorExtensionsMixin, + _ActionAddressMixin, + _ResponsePresetMixin, + StrictQueryParametersMixin, + IterablePaginationMixin, + viewsets.ViewSet, +): + """ + Accounts of the platform's users, addressed by username or by ``me``. + + The properties of an account are read from the account service rather than + from a queryset of this app's, so this is a plain ViewSet; which accounts + the answer carries is settled first, from the accounts holding the names + the caller gave, in the order the page is cut in. Access is layered: the + permission classes decide who may call an action at all, the service + decides which properties of each account the caller may see -- everything + for their own account and for a staff caller, the owner's shared + properties otherwise -- and the selectors decide which accounts the page + carries. + + A selector that finds nothing narrows the page to nothing, whichever of + the three it is, so a selection no account matches is answered by an empty + page rather than by a refusal. An address an account held before it was + retired is the one exception: that account was there and is not a row this + page can carry, so it is refused, with whether the retirement can still be + cancelled. That refusal is why the selectors are read from the query + string by a serializer and applied here rather than declared as a filter + set, which has no room for it. + + A selection of properties is measured against the properties a response of + this kind can carry for this caller, so one no account could ever show + them is refused rather than answered as an empty object. Which of the rest + a particular owner shares is settled per account, so a selected property + that this owner keeps to themselves is left out of their object, which can + leave it empty. + + ``me`` stands for the caller's own account wherever a caller reads or + changes one here. + """ + + # Account settings are reached from the site's own pages by users who have + # not confirmed their email address yet, and the platform default refuses + # a session belonging to such an account. Only that one class is replaced: + # the token class stays the one the platform configures, which is what + # records a request as having been authenticated the default way. + authentication_classes = (DefaultJwtAuthentication, SessionAuthenticationAllowInactiveUser) + permission_classes = ( + permissions.IsAuthenticated, + CanGetAccountInfo, + CanSelectAccountsByContact, + ) + #: A change is a merge patch: a body in any other media type is refused. + parser_classes = (MergePatchParser,) + serializer_class = AccountSerializer + #: Validates the query string of the list, and names the parameters it reads. + query_serializer_class = AccountQuerySerializer + pagination_class = UserApiPagination + lookup_field = "username" + # The router's default lookup pattern excludes dots, which usernames allow. + lookup_value_regex = settings.USERNAME_REGEX_PARTIAL + minimal_fields = ACCOUNT_MINIMAL_FIELDS + response_presets = ACCOUNT_PRESETS + extra_query_params = RESPONSE_SHAPING_PARAMS + #: The validated query string of the request being served, read once. + _validated_selection = None + + def get_serializer(self, *args, **kwargs): + """Build the output serializer; a plain ViewSet has no generic machinery to do it.""" + return self.serializer_class(*args, **kwargs) + + def known_query_params(self): + """Return the query parameters the action being served reads.""" + names = super().known_query_params() + if self.action != "list": + # One account is answered whole, so neither the selectors that + # choose which accounts a page carries nor the parameters that cut + # it into pages are read at a member address. + names -= set(self.query_serializer_class().fields) - {VIEW_PARAM} + names -= { + self.pagination_class.page_query_param, + self.pagination_class.page_size_query_param, + } + if self.action not in SHAPED_ACCOUNT_ACTIONS: + names -= set(RESPONSE_SHAPING_PARAMS) + return names + + def shapeable_fields(self): + """Return the properties an account response can carry for the caller making it.""" + describable = set(AccountSerializer().fields) + if self.is_minimal_view_requested(): + describable &= set(self.minimal_fields) + if self._whole_accounts_are_readable(self.request): + return describable + return describable & _shareable_account_fields() + + def _whole_accounts_are_readable(self, request): + """Whether every account this request addresses comes back whole to this caller.""" + if request.query_params.get(VIEW_PARAM) == SHARED_VIEW: + return False + if request.user.is_staff: + return True + return self._addressed_names(request) == [request.user.username] + + def _selection(self, request): + """ + Return the query string as the serializer that validates it reads it. + + Which accounts a request addresses is read both before the handler + runs, to settle what the answer can carry, and inside it, to cut the + page. Both read the values the serializer validated, so a name sent + with spaces around it names the same account at each point; and the + serializer runs once, because it is what refuses a selector the list + does not take. + """ + if self._validated_selection is None: + query = self.query_serializer_class(data=request.query_params) + query.is_valid(raise_exception=True) + self._validated_selection = query.validated_data + return self._validated_selection + + def _addressed_names(self, request): + """Return the usernames this request addresses, as the address and the query string give them.""" + if self.action != "list": + return [self._addressed_username(request, self.kwargs.get("username"))] + selection = self._selection(request) + named = selection.get("username") + if named: + return [name for name in named.strip(",").split(",") if name] + if {"email", "lms_user_id"} & set(selection): + return [] + return [request.user.username] + + def list(self, request): + """Return a page of accounts, shaped as the caller asked.""" + selection = self._selection(request) + preset = selection.get(VIEW_PARAM) + page = self.paginate_iterable( + request, + self._selected_usernames(request, selection), + serialize=lambda usernames: self._accounts_named(request, usernames, preset), + ) + return self.shape_page(page, request) + + def retrieve(self, request, username): + """Return one account, shaped as the caller asked.""" + account = self._accounts_named( + request, + [self._addressed_username(request, username)], + request.query_params.get(VIEW_PARAM), + )[0] + return Response(self.shape(account, request)) + + def partial_update(self, request, username): + """Change the properties the body carries and return the account as it now stands.""" + username = self._addressed_username(request, username) + changes = request.data + if not isinstance(changes, dict): + raise ValidationError({ + api_settings.NON_FIELD_ERRORS_KEY: ["Send the properties to change as an object."], + }) + # The body is measured against the shape this endpoint publishes before + # anything is done with it, and then carried out as it was sent: the + # account service takes properties this version does not publish, and + # refuses the ones that cannot be changed, which dropping them here + # would turn into silence. Every property is optional of itself, which + # is what makes the body a merge patch, and a property that is an + # object of its own is still sent whole. + AccountUpdateSerializer(data=changes).is_valid(raise_exception=True) + if "email" in changes and not settings.ALLOW_EMAIL_ADDRESS_CHANGE: + raise ValidationError({"email": ["This site does not let an email address be changed here."]}) + self._check_change_rate(request, changes) + try: + with transaction.atomic(): + update_account_settings(request.user, changes, username=username) + account = self._accounts_named( + request, [username], request.query_params.get(VIEW_PARAM), + )[0] + except UserNotAuthorized as exc: + raise PermissionDenied from exc + except UserNotFound as exc: + raise NotFound from exc + except AccountValidationError as exc: + raise self._refused_changes(username, exc) from exc + except AccountUpdateError as exc: + raise self._failed_change(username, exc) from exc + return Response(self.shape(account, request)) + + def _addressed_username(self, request, username): + """Return the username an address names, reading ``me`` as the caller's own.""" + if username == OWN_ACCOUNT_IDENTIFIER: + return request.user.username + return username + + def _accounts_named(self, request, usernames, preset=None): + """Return each named account, in the order asked for, as this caller may see it.""" + names = list(usernames) + if not names: + return [] + try: + found = get_account_settings(request, names, view=preset if preset == SHARED_VIEW else None) + except UserNotFound as exc: + raise NotFound from exc + # The accounts come back in the order the database returned them, which + # is not the order of the page they were selected for. Each name is + # matched to its account by the name that account stores, and failing + # that by its case-folded form: the database decides which names a + # selection matches, and the collation MySQL applies to these columns + # by default matches names differing only in case, so an account can + # come back stored under a spelling other than the one asked for. + by_name = {account["username"]: account for account in found} + folded = {} + for stored, account in by_name.items(): + folded.setdefault(stored.casefold(), account) + ordered = [] + for name in names: + account = by_name.get(name) + if account is None: + account = folded.get(name.casefold()) + if account is not None: + ordered.append(account) + return ordered + + def _selected_usernames(self, request, selection): + """Return the usernames the selectors name, in the order the page carries them.""" + return usernames_among( + self._selected_names(request, selection), + selection.get("ordering") or ACCOUNT_DEFAULT_SORT, + ) + + def _selected_names(self, request, selection): + """ + Return the usernames named by whichever selector the caller used. + + Every selector narrows the same collection, so each one that finds + nothing narrows it to nothing and leaves the page empty, whether it + was given a name, an address or an identifier. An address an account + held before it was retired is the exception: the account was there and + is not a row this page can carry, which is reported rather than left + out in silence. + """ + usernames = selection.get("username") + if usernames: + return [name for name in usernames.strip(",").split(",") if name] + email = selection.get("email") + if email: + return self._usernames_holding_email(email) + identifier = selection.get("lms_user_id") + if identifier is not None: + return self._usernames_holding_identifier(identifier) + return [request.user.username] + + def _usernames_holding_email(self, email): + """Return the account holding this address, and nothing when none does.""" + if is_email_retired(email): + raise self._retired_account(email) + username = username_holding_email(email) + return [username] if username is not None else [] + + def _usernames_holding_identifier(self, identifier): + """Return the account holding this numeric identifier, and nothing when none does.""" + username = username_holding_id(identifier) + return [username] if username is not None else [] + + def _retired_account(self, email): + """Build the refusal for an address an account held before it was retired.""" + retirement = cancellable_retirement_for_email(email) + return RetiredAccount( + accounts.RETIRED_EMAIL_MSG, + can_cancel_retirement=retirement is not None, + retirement_id=retirement.id if retirement is not None else None, + ) + + def _check_change_rate(self, request, changes): + """Refuse a property the caller has changed too often lately.""" + for field, limit_setting in RATE_LIMITED_ACCOUNT_FIELDS: + limit = getattr(settings, limit_setting, None) + if not (changes.get(field) and limit): + continue + if is_ratelimited( + request=request, + group=f"{field}_change_rate_limit", + key="user", + rate=limit, + increment=True, + ): + log.info("Change of %r refused for %r: over the rate limit", field, request.user.username) + raise Throttled(detail=f"Wait before changing {field} again.") + + def _refused_changes(self, username, error): + """Return the refusal naming the property that each failed validation.""" + log.info("Account %r not changed: %r", username, error.field_errors) + refusals = {} + for field, reported in error.field_errors.items(): + message = reported.get("user_message") if isinstance(reported, dict) else None + refusals[field] = [message or "This value cannot be used here."] + return ValidationError(refusals) + + def _failed_change(self, username, error): + """ + Return the failure for a change that was asked for correctly and could not be carried out. + + The body has already been measured against what this endpoint takes, + and a value the account refuses is reported property by property, so + what is left here is the work itself failing: a row that would not + save, a message that would not send. Neither is answered by sending + the request again with something else in it, so neither is the + caller's fault. + """ + log.error("Account %r not changed: %s", username, error.developer_message) + return APIException("The change could not be carried out.") + + +@extend_schema(tags=[SDK_TAG]) +@extend_schema_view( + post=extend_schema( + summary="Deactivate an account", + description=( + "Makes the account's password unusable, so its owner can no longer sign in with it. " + "The account and the data belonging to it are kept, and none of it is removed. Asking " + "for a password reset does not undo this: the reset flow refuses an account whose " + "password is unusable, so signing in again takes a new password set on the account by " + "other means." + ), + parameters=[_DEACTIVATION_PATH_PARAM], + request=None, + responses={ + 204: OpenApiResponse(description="The account was deactivated."), + 400: _RESP_BAD_REQUEST, + 401: RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_NOT_FOUND, + }, + ), +) +class AccountDeactivationView( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + StrictQueryParametersMixin, + APIView, +): + """ + Disables the account the address names. + + This is an operation a privileged caller carries out on somebody else's + account rather than a property of that account, and it shares nothing with + the way an account is read or changed: the caller holds the privilege to + disable accounts and has confirmed their own address, the body is read as + JSON rather than as a merge patch, and the name in the address is read as + a stored username, ``me`` included, so a caller that addressed one account + is never answered by disabling another. It is therefore its own view + rather than an action of the account collection. + """ + + permission_classes = (permissions.IsAuthenticated, IsActiveUser, CanDeactivateUser) + + def post(self, request, username): + """Make the password of the named account unusable and record it as disabled.""" + user = _user_named(username) + segment.identify(user.id, {"is_disabled": "true"}) + user.set_unusable_password() + user.save() + return Response(status=status.HTTP_204_NO_CONTENT) + + +@extend_schema(tags=[SDK_TAG]) +@extend_schema_view( + create=extend_schema( + summary="Search accounts by email address", + description=( + "Returns a page of the accounts holding the email addresses in the body. An address " + "no account holds is left out of the answer, and a search names at most " + f"{EMAIL_SEARCH_MAX_ADDRESSES} addresses. The addresses travel in the body so that " + "they are not written to a server log or a browser history, which is why this reads " + "with a POST. For the same reason the `next` and `previous` links of the page are " + "reached by sending the same body to them, the way this request was sent, rather " + "than by fetching them." + ), + request=EmailSearchSerializer, + responses={ + 200: EmailSearchResultSerializer(many=True), + 400: _RESP_UNUSABLE_BODY, + 401: RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: _RESP_NOT_FOUND, + 415: RESP_UNREADABLE_BODY, + }, + ), +) +class EmailSearchViewSet( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + StrictQueryParametersMixin, + IterablePaginationMixin, + viewsets.ViewSet, +): + """ + The accounts holding a given set of email addresses. + + The addresses are sent in a request body rather than in a query string, so + that they stay out of server logs and browser histories, which is why a + search is made with a POST, and why the links on a page of results are + followed by sending the body to them again rather than by fetching them. + The search is a collection of its own rather than an action under the + accounts, because what follows the account collection in an address is the + name of an account, and an account may be named anything a user may + register. Only a platform administrator may search, and every other caller + is told there is nothing at this address. + """ + + permission_classes = ( + permissions.IsAuthenticated, + IsActiveUser, + CanGetAccountInfo, + IsStaffOrAbsent, + ) + parser_classes = (JSONParser,) + serializer_class = EmailSearchResultSerializer + pagination_class = UserApiPagination + + def get_serializer(self, *args, **kwargs): + """Build the output serializer; a plain ViewSet has no generic machinery to do it.""" + return self.serializer_class(*args, **kwargs) + + def create(self, request): + """Return a page of the accounts holding the addresses the body carries.""" + search = EmailSearchSerializer(data=request.data) + search.is_valid(raise_exception=True) + return self.paginate_iterable(request, accounts_holding_emails(search.validated_data["emails"])) + + +_NAME_CHANGE_PATH_PARAM = _path_param( + "username", + "Unique name of the user whose requested change is confirmed. The name is read as it is " + f"stored, so `{OWN_ACCOUNT_IDENTIFIER}` here names an account holding that name rather than " + "the account of the caller making the request.", + _USERNAME_PATTERN, +) + + +@extend_schema(tags=[SDK_TAG]) +@extend_schema_view( + create=extend_schema( + summary="Request a profile name change", + description=( + "Records the full name the caller wants on their profile. The profile keeps its " + "current name until the request is confirmed, and a caller who already has a request " + "outstanding replaces it with this one." + ), + request=NameChangeSerializer, + responses={ + 201: NameChangeSerializer, + 400: _RESP_UNUSABLE_BODY, + 401: RESP_UNAUTHENTICATED, + 404: OpenApiResponse( + ErrorResponse, + description="The account of the caller carries no profile to put a name on.", + ), + 415: RESP_UNREADABLE_BODY, + }, + ), +) +class NameChangeViewSet( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + _ActionAddressMixin, + StrictQueryParametersMixin, + viewsets.ViewSet, +): + """ + Requests to put a different full name on a user's profile. + + A user asks for the name they want; the profile keeps the name it has + until a member of staff confirms the request, which is the point at which + the old name is recorded in the profile's history. + """ + + permission_classes = (permissions.IsAuthenticated,) + serializer_class = NameChangeSerializer + lookup_field = "username" + # The router's default lookup pattern excludes dots, which usernames allow. + lookup_value_regex = settings.USERNAME_REGEX_PARTIAL + + def get_serializer(self, *args, **kwargs): + """Build the serializer; a plain ViewSet has no generic machinery to do it.""" + return self.serializer_class(*args, **kwargs) + + def create(self, request): + """Record the name the caller wants on their profile.""" + requested = self.get_serializer(data=request.data) + requested.is_valid(raise_exception=True) + name = requested.validated_data["name"] + rationale = f"Name change requested through account API by {request.user.username}" + pending = self._requested_change(request.user, name, rationale) + if pending is None: + raise ValidationError({"name": ["The profile already carries this name."]}) + return Response( + self.get_serializer({"name": pending.new_name}).data, + status=status.HTTP_201_CREATED, + ) + + @extend_schema( + summary="Confirm a requested profile name change", + description=( + "Puts the name the user asked for on their profile and keeps the name it carried " + "until now in the profile's history. Only a member of staff may confirm a request." + ), + parameters=[_NAME_CHANGE_PATH_PARAM], + request=None, + responses={ + 204: OpenApiResponse(description="The profile now carries the name that was asked for."), + 400: _RESP_BAD_REQUEST, + 401: RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: OpenApiResponse( + ErrorResponse, + description="No such user, or the user has asked for no name change.", + ), + }, + ) + @action( + detail=True, + methods=["post"], + url_path="confirmations", + url_name="confirmation", + # Confirming somebody else's requested name is a privilege, so this + # action also refuses a caller whose own account is no longer active. + permission_classes=[permissions.IsAuthenticated, IsActiveUser, IsStaff], + ) + def confirmations(self, request, username): + """Put the name the named user asked for on their profile.""" + user = _user_named(username) + pending = get_pending_name_change(user) + if pending is None: + raise NotFound + self._confirm_change(user, pending) + return Response(status=status.HTTP_204_NO_CONTENT) + + def _requested_change(self, user, name, rationale): + """Store the name this user asks for, or return nothing when it is the name they have.""" + try: + return do_name_change_request(user, name, rationale)[0] + except UserProfile.DoesNotExist as exc: + log.warning("Name change refused for %r: the account carries no profile", user.username) + raise NotFound from exc + + def _confirm_change(self, user, pending): + """Put the requested name on the profile.""" + try: + confirm_name_change(user, pending) + except UserProfile.DoesNotExist as exc: + log.warning("Name change refused for %r: the account carries no profile", user.username) + raise NotFound from exc + + +_VERIFICATION_PATH_PARAM = _path_param( + "username", + "Unique name of the user whose identity verification is addressed. The name is read as it is " + f"stored, so `{OWN_ACCOUNT_IDENTIFIER}` here names an account holding that name rather than " + "the account of the caller making the request.", + _USERNAME_PATTERN, +) + + +def _verification_sort_key(attempt): + """Return what an attempt is ordered by, with a tie-break that is always comparable.""" + return (attempt.updated_at, str(getattr(attempt, "receipt_id", "") or "")) + + +@extend_schema(tags=[SDK_TAG]) +class IDVerificationStatusView( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + StrictQueryParametersMixin, + APIView, +): + """ + Whether a user has proved their identity, as one summary. + + An account has one such summary, computed rather than stored and never + listed, so it is served from this single address rather than routed as a + collection. The summary is read from the identity verification service + rather than from this app's own tables, and the username in the address + names the user whose summary is read. A user may read their own summary, + and a staff caller whose own account is active may read anyone's, which is + not what the account collection admits, so the summary is served by a view + of its own rather than as an action of that collection. Every account has a + summary: one belonging to a user who has been through no check says so, and + the address is absent only when the user it names is. + """ + + permission_classes = ( + permissions.IsAuthenticated, + # Reading somebody else's summary is a privilege, so the staff half + # also refuses a caller whose own account is no longer active. + (IsStaff & IsActiveUser) | IsAddressedUser, + ) + serializer_class = VerificationStatusSerializer + + def get_serializer(self, *args, **kwargs): + """Build the serializer; a plain APIView has no generic machinery to do it.""" + return self.serializer_class(*args, **kwargs) + + @extend_schema( + summary="Get the identity verification status", + description=( + "Returns where this user stands on having proved their identity. A user may read " + "their own status, and a staff caller may read anyone's. A user who has been through " + "no check stands at `none`." + ), + parameters=[_VERIFICATION_PATH_PARAM], + responses={ + 200: VerificationStatusSerializer, + 400: _RESP_BAD_REQUEST, + 401: RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: OpenApiResponse(ErrorResponse, description="No such user."), + }, + ) + def get(self, request, username): + """Return where this user stands on having proved their identity.""" + standing = IDVerificationService.user_status(_user_named(username)) + return Response(self.get_serializer({ + "is_verified": standing.get("status") == APPROVED_STATUS, + "status": standing.get("status"), + "expiration_datetime": standing.get("verification_expiry", ""), + }).data) + + +@extend_schema(tags=[SDK_TAG]) +@extend_schema_view( + list=extend_schema( + summary="List identity verification attempts", + description=( + "Returns a page of the attempts this user has made at proving their identity, the " + "most recently changed one first. A user who has been through no checks has an " + "empty page. A user may read their own attempts, and a staff caller may read " + "anyone's." + ), + # The sort is published from the serializer that validates it, so the + # values a caller is held to are the values it reads. + parameters=[_VERIFICATION_PATH_PARAM, VerificationQuerySerializer], + responses={ + 200: VerificationSerializer(many=True), + 400: _RESP_BAD_REQUEST, + 401: RESP_UNAUTHENTICATED, + 403: _RESP_FORBIDDEN, + 404: OpenApiResponse( + ErrorResponse, description="No such user, or no such page of attempts.", + ), + }, + ), +) +class IDVerificationViewSet( + StandardizedErrorMixin, + CatalogedRequestErrorsMixin, + StrictQueryParametersMixin, + IterablePaginationMixin, + viewsets.ViewSet, +): + """ + The attempts one user has made at proving their identity. + + The attempts are collected from the identity verification service, which + holds a table per kind of check, so there is no queryset of this app's to + narrow: the page is cut from what those tables return and is sorted here + rather than by a filter backend. An attempt belongs to the user who made + it and is reached by no other route, so the collection is addressed + beneath that user's account. A user may read their own attempts, and a + staff caller may read anyone's. A user who has been through no checks has + an empty page: the address is absent only when the user it names is. + """ + + permission_classes = ( + permissions.IsAuthenticated, + # Reading somebody else's attempts is a privilege, so the staff half + # also refuses a caller whose own account is no longer active. + (IsStaff & IsActiveUser) | IsAddressedUser, + ) + serializer_class = VerificationSerializer + pagination_class = UserApiPagination + #: Validates the query string, and names the parameters this view reads. + query_serializer_class = VerificationQuerySerializer + + def get_serializer(self, *args, **kwargs): + """Build the serializer; a plain ViewSet has no generic machinery to do it.""" + return self.serializer_class(*args, **kwargs) + + def list(self, request, username): + """Return a page of this user's attempts, in the order the caller asked for.""" + query = self.query_serializer_class(data=request.query_params) + query.is_valid(raise_exception=True) + attempts = IDVerificationService.verifications_for_user(_user_named(username)) + ordering = query.validated_data.get("ordering") or VERIFICATION_DEFAULT_SORT + return self.paginate_iterable( + request, + sorted(attempts, key=_verification_sort_key, reverse=ordering.startswith("-")), + ) + + @extend_schema(exclude=True) class UnknownAddressView(StandardizedErrorMixin, APIView): """ From 72a869de98bafa55011d94147bf91f6a30b24c34 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Tue, 27 Oct 2026 00:00:34 +0500 Subject: [PATCH 04/61] fix: let the account tests be collected under the CMS settings This package is shared with the CMS, and the CI shard that runs it under cms.envs.test could not import this module at all: it read settings.ACCOUNT_VISIBILITY_CONFIGURATION, an LMS setting, in the module body. Collection failed, which failed the shard, which cancelled the rest of the matrix. Every test here that reads these sets is already @skip_unless_lms, but a module body runs before any skip can apply, so the setting is now read through the same guard user_api/accounts/tests/test_views.py uses for it, and the field sets fall back to empty when it is absent. Under cms.envs.test this module now collects, and the failures left in these two packages are the same 44 as on master, in the same tests -- an artefact of running two of the shard's sixty-nine paths rather than anything in this branch. Under lms.envs.test nothing changes. --- .../user_api/v2/tests/test_account_views.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 4f89185ca2f9..0be8fa555a50 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -40,15 +40,23 @@ #: The properties every caller may see, whoever they are. PUBLIC_FIELDS = {"account_privacy", "profile_image", "username"} +#: ``ACCOUNT_VISIBILITY_CONFIGURATION`` is an LMS setting, and this package is +#: shared with the CMS. Every test below that reads these sets is +#: ``@skip_unless_lms``, but a module body runs before any skip can apply, so a +#: missing setting is tolerated here instead of breaking collection under the +#: CMS settings. The same guard is used for the same setting in +#: ``user_api/accounts/tests/test_views.py``. +_VISIBILITY = getattr(settings, "ACCOUNT_VISIBILITY_CONFIGURATION", {}) + #: The properties a user sees of their own account, and a staff caller of any. -FULL_FIELDS = set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["admin_fields"]) +FULL_FIELDS = set(_VISIBILITY.get("admin_fields", ())) #: The properties a learner sees of an account whose owner shares it with everybody. -SHARED_FIELDS = set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["bulk_shareable_fields"]) +SHARED_FIELDS = set(_VISIBILITY.get("bulk_shareable_fields", ())) #: The properties an owner is able to share, and so the only ones another caller #: may select; the refusal offers them in this order. -SHAREABLE_FIELDS = set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["custom_shareable_fields"]) +SHAREABLE_FIELDS = set(_VISIBILITY.get("custom_shareable_fields", ())) SHAREABLE_FIELDS_OFFERED = ", ".join(sorted(SHAREABLE_FIELDS)) #: The identifying properties the ``minimal`` preset keeps, and the ones of those From 222917e64fa8c18d04afa9e26a46e1aa858ccecf Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Mon, 26 Oct 2026 23:32:24 +0500 Subject: [PATCH 05/61] fix: name the library JWT class on the views that replace a default auth class Four views declare their own authentication_classes so that a caller who has not yet confirmed their email address can still reach their own account, its picture, its preferences and its email choice: the session class the platform configures refuses such a caller, so that half is replaced. For the token half they named DefaultJwtAuthentication. That class exists only to be named in DEFAULT_AUTHENTICATION_CLASSES -- its own module says it is only meant for that -- and the using_default_auth_classes attribute it records exists so an operator can find the endpoints that are on the defaults. A view that declares its own classes is not one of those, so recording the attribute filed a false signal and polluted the query the attribute serves. Nothing on master declares the class: two files name it, both definitional, against the library class used throughout the rest of the platform. The four views now name JwtAuthentication, the class the platform's own pair is built on. Two of these addresses, the account and its picture, were added earlier on this branch and are corrected in place here. The guards assert the attribute is absent, each alongside a control request to a sibling address that declares no classes and must still record it, so a pin cannot pass merely because a patch target was mistyped. --- .../profile_images/v2/tests/test_views.py | 23 ++++++++++++++----- .../djangoapps/profile_images/v2/views.py | 11 +++++---- .../user_api/v2/tests/test_account_views.py | 23 ++++++++++++++----- .../djangoapps/user_api/v2/tests/test_urls.py | 11 +++++---- openedx/core/djangoapps/user_api/v2/views.py | 11 +++++---- 5 files changed, 53 insertions(+), 26 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py index 3973feb31f16..b9e5dd5ce49e 100644 --- a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py +++ b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py @@ -565,13 +565,16 @@ def test_a_caller_who_has_not_confirmed_their_email_address_may_still_set_an_ima assert response.status_code == status.HTTP_204_NO_CONTENT assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) - def test_a_token_is_read_by_the_class_the_platform_declares(self): + def test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaults(self): """ - Only the session class is replaced here, so a token is read by the platform's own. - - That class records every request it reads a token for, which is how an - operator finds the addresses that authenticate the way the platform - declares rather than by a list of their own. + This address names its own classes, so it is not one the default pair serves. + + The pair the platform configures records every request it reads a + token for, so that an operator can list the addresses it serves. This + one replaces the session half of it and is therefore not among them, + and nothing here is recorded as if it were. The address read afterwards + names no classes of its own and is recorded, which is what shows the + record is reachable from a request made this way at all. """ with mock.patch(DEFAULT_AUTH_RECORDER) as recorded: with make_image_file() as image_file: @@ -579,6 +582,14 @@ def test_a_token_is_read_by_the_class_the_platform_declares(self): self.url, {"file": image_file}, format="multipart", **self.token_headers(self.owner), ) assert response.status_code == status.HTTP_204_NO_CONTENT + assert self.stored_sizes(self.owner.username) == self.all_sizes(self.owner.username) + assert recorded.call_args_list == [] + + with mock.patch(DEFAULT_AUTH_RECORDER) as recorded: + on_the_default_pair = self.client.get( + reverse("user_v2:user_preference_list"), **self.token_headers(self.staff), + ) + assert on_the_default_pair.status_code == status.HTTP_200_OK assert [call.args for call in recorded.call_args_list] == [("using_default_auth_classes", True)] def test_a_body_in_a_media_type_this_endpoint_cannot_read_is_refused(self): diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index 2bda5f6923f8..29438971e9bb 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -8,6 +8,7 @@ import piexif from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema +from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser from edx_rest_framework_extensions.mixins import StandardizedErrorMixin from PIL import Image @@ -28,7 +29,6 @@ SDK_TAG, StrictQueryParametersMixin, ) -from openedx.core.djangolib.default_auth_classes import DefaultJwtAuthentication from openedx.core.lib.api.parsers import TypedFileUploadParser from ..exceptions import ImageValidationError @@ -128,10 +128,11 @@ class ProfileImageView( # The site's own pages let a user who has not confirmed their email # address set a picture, and the platform default refuses a session - # belonging to such an account. Only that one class is replaced: the token - # class stays the one the platform configures, which is what records a - # request as having been authenticated the default way. - authentication_classes = (DefaultJwtAuthentication, SessionAuthenticationAllowInactiveUser) + # belonging to such an account. Only the session class differs in what it + # admits: a token is read by the library class the platform's own pair is + # built on, named here because a view declaring its own classes is not one + # that pair serves. + authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser) permission_classes = (permissions.IsAuthenticated, IsAddressedUser) parser_classes = (MultiPartParser, FormParser, NamedImageUploadParser) serializer_class = ProfileImageUploadSerializer diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 0be8fa555a50..eaa3e82b36ed 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -856,17 +856,28 @@ def test_a_disabled_staff_account_still_reads_the_accounts_it_names(self): assert page.status_code == status.HTTP_200_OK assert self.usernames_in(page) == ["other-caller"] - def test_a_token_is_read_by_the_class_the_platform_declares(self): + def test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaults(self): """ - Only the session class is replaced here, so a token is read by the platform's own. - - That class records every request it reads a token for, which is how an - operator finds the addresses that authenticate the way the platform - declares rather than by a list of their own. + This address names its own classes, so it is not one the default pair serves. + + The pair the platform configures records every request it reads a + token for, so that an operator can list the addresses it serves. This + one replaces the session half of it and is therefore not among them, + and nothing here is recorded as if it were. The address read afterwards + names no classes of its own and is recorded, which is what shows the + record is reachable from a request made this way at all. """ with mock.patch(DEFAULT_AUTH_RECORDER) as recorded: answer = self.client.get(self.detail_url("other-caller"), **self.token_headers(self.other)) assert answer.status_code == status.HTTP_200_OK + assert answer.json()["username"] == "other-caller" + assert recorded.call_args_list == [] + + with mock.patch(DEFAULT_AUTH_RECORDER) as recorded: + on_the_default_pair = self.client.get( + reverse("user_v2:user_preference_list"), **self.token_headers(self.staff), + ) + assert on_the_default_pair.status_code == status.HTTP_200_OK assert [call.args for call in recorded.call_args_list] == [("using_default_auth_classes", True)] def test_an_unconfirmed_account_still_may_not_search_for_others(self): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_urls.py b/openedx/core/djangoapps/user_api/v2/tests/test_urls.py index 7f14cd526cb2..b2a764d068cd 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_urls.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_urls.py @@ -5,6 +5,7 @@ import pytest from django.core.exceptions import ImproperlyConfigured from django.urls import get_resolver, resolve, reverse +from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser from edx_rest_framework_extensions.testing import assert_error_envelope from rest_framework import status @@ -232,18 +233,20 @@ def test_a_deactivation_authenticates_the_way_the_platform_does(self): def test_the_views_reached_before_an_address_is_confirmed_replace_one_class(self): """ - An account and its picture are reached with the platform's token class and a wider session one. + An account and its picture are reached with the library's token class and a wider session one. The site's own settings pages are reached by a user who has not confirmed their email address, whom the session class the platform configures refuses, so that one class is replaced. The class reading a - token is left as the platform declares it, which is what records these - requests alongside every other request authenticated that way. + token is the one the platform's own pair is built on, named here rather + than inherited, because a view that declares its own classes is not one + that pair serves and is not recorded as one. """ platform_token = api_settings.DEFAULT_AUTHENTICATION_CLASSES[0] + assert issubclass(platform_token, JwtAuthentication) for view_class in (AccountViewSet, ProfileImageView): assert view_class.authentication_classes == ( - platform_token, SessionAuthenticationAllowInactiveUser, + JwtAuthentication, SessionAuthenticationAllowInactiveUser, ), view_class.__name__ def test_what_is_recorded_about_an_account_authenticates_the_way_the_platform_does(self): diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 7268cce40f36..65475d0fda79 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -16,6 +16,7 @@ extend_schema, extend_schema_view, ) +from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser from edx_rest_framework_extensions.mixins import StandardizedErrorMixin from edx_rest_framework_extensions.paginators import IterablePaginationMixin @@ -46,7 +47,6 @@ ) from openedx.core.djangoapps.user_api.models import UserPreference from openedx.core.djangoapps.user_api.preferences.api import get_country_time_zones -from openedx.core.djangolib.default_auth_classes import DefaultJwtAuthentication from openedx.core.lib.api.parsers import MergePatchParser from .errors import CatalogedRequestErrorsMixin, ErrorExtensionsMixin, RetiredAccount @@ -890,10 +890,11 @@ class AccountViewSet( # Account settings are reached from the site's own pages by users who have # not confirmed their email address yet, and the platform default refuses - # a session belonging to such an account. Only that one class is replaced: - # the token class stays the one the platform configures, which is what - # records a request as having been authenticated the default way. - authentication_classes = (DefaultJwtAuthentication, SessionAuthenticationAllowInactiveUser) + # a session belonging to such an account. Only the session class differs in + # what it admits: a token is read by the library class the platform's own + # pair is built on, named here because a view declaring its own classes is + # not one that pair serves. + authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser) permission_classes = ( permissions.IsAuthenticated, CanGetAccountInfo, From 7cb862f9ebefb53f613beee7bed9473ccc26c3aa Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Tue, 27 Oct 2026 01:29:33 +0500 Subject: [PATCH 06/61] fix: align four published details across the three /api/user/v2/ phases An audit across the three phases on this branch found four defects, each introduced by an earlier phase and each visible to a caller or to a generated client. They are corrected together here, as the JWT class was, rather than left to differ between sibling addresses of one version. The profile image published a username with no pattern, the only one of the eleven username path parameters in this version without it, so a generated client validated the name before the request on nine addresses of the resource and not on the tenth. The parameter helpers and the username pattern move from views.py into view_utils.py, which that module already imports from, and the parameter is built with the helper. The helper being private to one module was the cause, and a further module would have hit it again. The stored-preference resource pinned one operation id inline, which applies to every document, so the service-wide document published that operation beside a collection read carrying a different prefix, and a client generated from it derived the two from different modules. The pin moves into the per-document table beside the entries that already do this, so the resource's operations share their leading tokens in each document. One id changes, in the service-wide document only, to a name that document has never published. The username filter accepted a single exact name on two collections and a comma-separated list on a third, so a caller who learned the list form on the account collection was answered a 200 with an empty page rather than told the filter does not take a list. All three now accept the list, through one shared selector, matching the member address of that resource, which already reads a comma as a separator. The email search was the one collection in this version reading accounts directly without declaring a scoping seam, while the two collections over the same table declare one. It now declares the same policy through a queryset the shared mixin can wrap. No caller gains or loses access and no row changes: the policy is a pass-through today, and the seam is what was missing. --- lms/lib/spectacular.py | 19 ++++ lms/lib/tests/test_spectacular.py | 20 +++- .../djangoapps/profile_images/v2/views.py | 18 ++- .../core/djangoapps/user_api/v2/filters.py | 24 +++- .../user_api/v2/tests/test_account_views.py | 34 ++++++ .../user_api/v2/tests/test_schema.py | 106 +++++++++++++++++- .../user_api/v2/tests/test_views.py | 90 +++++++++++++++ .../core/djangoapps/user_api/v2/view_utils.py | 45 +++++++- openedx/core/djangoapps/user_api/v2/views.py | 105 +++++++++-------- 9 files changed, 391 insertions(+), 70 deletions(-) diff --git a/lms/lib/spectacular.py b/lms/lib/spectacular.py index 4ac182ea1bb7..a80cef111441 100644 --- a/lms/lib/spectacular.py +++ b/lms/lib/spectacular.py @@ -47,8 +47,27 @@ # carries there -- so that one is pinned. The key carries the id the generator # derives, so an entry applies only to the document that derives it; a key no # document derives would never be reached. +# +# A stored preference is addressed by the pair that identifies it, and the +# comma between the two parameters is left behind as a token of its own, so +# every document derives an id for that read carrying a bare separator where +# the rest of the resource carries a word. That read is named here in each +# document through the id that document derives, which leaves the collection +# read and the member read of the resource under the same leading tokens +# wherever they are published; neither document has published either name, so +# nothing a client imports is taken away. RENAMED_OPERATION_IDS = { ("/api/user/v1/accounts", "GET", "api_user_v1_accounts_list"): "api_user_v1_accounts_retrieve", + ( + "/api/user/v2/user_preferences/{username},{key}/", + "GET", + "v2_user_preferences_,_retrieve", + ): "v2_user_preferences_retrieve", + ( + "/api/user/v2/user_preferences/{username},{key}/", + "GET", + "api_user_v2_user_preferences_,_retrieve", + ): "api_user_v2_user_preferences_retrieve", } PUBLISHED_PATH_PATTERN = re.compile(r"^/api/enrollment/v\d+/") diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index 90d7f9a2a382..9a24fe93e701 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -236,6 +236,13 @@ def _user_routes(schema_class): ), path("api/user/v1/users/", view.as_view({"get": "list"})), path("api/user/v2/users/", view.as_view({"get": "list"})), + # A stored preference is addressed by its owner and its name together, + # and the comma between them is a token of the address like any other, + # so the generator leaves it in the name it derives. + path( + "api/user/v2/user_preferences/,/", + view.as_view({"get": "retrieve"}), + ), path("api/enrollment/v1/enrollments/", view.as_view({"get": "list"})), # Outside ``/api/``, so a document that derives its prefix from the # routes it covers derives the one the service-wide document has. @@ -264,7 +271,13 @@ class UserOperationIdTest(SimpleTestCase): """User addresses keep the names the generator derives; only their tag group is chosen here.""" def test_the_service_wide_document_keeps_every_name_the_generator_derives(self): - """Each of these is the name that document already published, and a client imports it by name.""" + """ + Each of these is the name that document publishes, and a client imports it by name. + + An address that document has published for years keeps the name it + derived there, numeral and all; an address of a version it has not + published yet carries the name pinned for it. + """ assert _named_operations(LmsAutoSchema, get_api_docs_settings()) == { "/api/user/v1/accounts": ("api_user_v1_accounts_retrieve", ("api",)), "/api/user/v1/accounts/{username}": ("api_user_v1_accounts_retrieve_2", ("api",)), @@ -273,6 +286,8 @@ def test_the_service_wide_document_keeps_every_name_the_generator_derives(self): ("api_user_v1_preferences_retrieve_2", ("api",)), "/api/user/v1/users/": ("api_user_v1_users_list", ("api",)), "/api/user/v2/users/": ("api_user_v2_users_list", ("api",)), + "/api/user/v2/user_preferences/{username},{key}/": + ("api_user_v2_user_preferences_retrieve", ("api",)), "/api/enrollment/v1/enrollments/": ("api_enrollment_v1_enrollments_list", ("api",)), "/user_api/v1/preferences/{username}": ("user_api_v1_preferences_retrieve", ("user_api",)), } @@ -295,6 +310,9 @@ def test_a_user_address_is_grouped_by_area_where_the_derived_tag_would_name_a_ve "/api/user/v1/preferences/{username}/{preference_key}": ("v1_preferences_retrieve_2", ("user",)), "/api/user/v1/users/": ("v1_users_list", ("user",)), "/api/user/v2/users/": ("v2_users_list", ("user",)), + "/api/user/v2/user_preferences/{username},{key}/": ( + "v2_user_preferences_retrieve", ("user",), + ), "/api/enrollment/v1/enrollments/": ("v1_enrollments_list", ("v1",)), "/user_api/v1/preferences/{username}": ("user_api_v1_preferences_retrieve", ("user_api",)), } diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index 29438971e9bb..2efcc5a55d03 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -27,7 +27,9 @@ RESP_UNAUTHENTICATED, RESP_UNREADABLE_BODY, SDK_TAG, + USERNAME_PATTERN, StrictQueryParametersMixin, + path_param, ) from openedx.core.lib.api.parsers import TypedFileUploadParser @@ -37,16 +39,12 @@ log = logging.getLogger(__name__) -_USERNAME_PATH_PARAM = OpenApiParameter( - name="username", - description=( - "Unique name of the user whose image is addressed. The name is read as it is stored, so " - "`me` here names an account holding that name rather than the account of the caller " - "making the request." - ), - required=True, - location=OpenApiParameter.PATH, - type=str, +_USERNAME_PATH_PARAM = path_param( + "username", + "Unique name of the user whose image is addressed. The name is read as it is stored, so " + "`me` here names an account holding that name rather than the account of the caller " + "making the request.", + USERNAME_PATTERN, ) _RESP_ANOTHER_USERS_IMAGE = OpenApiResponse( diff --git a/openedx/core/djangoapps/user_api/v2/filters.py b/openedx/core/djangoapps/user_api/v2/filters.py index 741aaee5fc12..60c35adf072d 100644 --- a/openedx/core/djangoapps/user_api/v2/filters.py +++ b/openedx/core/djangoapps/user_api/v2/filters.py @@ -13,6 +13,8 @@ from openedx.core.djangoapps.user_api.models import UserPreference +from .view_utils import names_in + log = logging.getLogger(__name__) @@ -96,7 +98,13 @@ class UserFilterSet(filters.FilterSet): course has defined matches no users and is not created. """ - username = filters.CharFilter(help_text="Return the user with exactly this username.") + username = filters.CharFilter( + method="filter_usernames", + help_text=( + "Comma-separated usernames. Only these users are returned, and a name no user holds " + "is left out of the page rather than refused." + ), + ) email = filters.CharFilter(help_text="Return the user with exactly this email address.") is_active = StrictBooleanFilter( help_text="Return only users whose account is active, or only inactive ones. true or false.", @@ -133,6 +141,10 @@ def filter_queryset(self, queryset): raise ValidationError({"forum_role": ["This parameter is required when course_key is supplied."]}) return super().filter_queryset(queryset) + def filter_usernames(self, queryset, name, value): + """Keep the users the value names, which it carries as a comma-separated list.""" + return queryset.filter(**{f"{name}__in": names_in(value)}) + def filter_preference_key(self, queryset, name, value): # pylint: disable=unused-argument """Keep users who have stored a preference under ``value``.""" return queryset.filter(preferences__key=value) @@ -170,9 +182,17 @@ class UserPreferenceFilterSet(filters.FilterSet): key = filters.CharFilter(help_text="Return only preferences stored under exactly this key.") username = filters.CharFilter( field_name="user__username", - help_text="Return only preferences belonging to this user.", + method="filter_usernames", + help_text=( + "Comma-separated usernames. Only these users' preferences are returned, and a name " + "no user holds is left out of the page rather than refused." + ), ) class Meta: model = UserPreference fields = ("key", "username") + + def filter_usernames(self, queryset, name, value): + """Keep the preferences of the users the value names, read as a comma-separated list.""" + return queryset.filter(**{f"{name}__in": names_in(value)}) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index eaa3e82b36ed..e80a8351f17b 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -10,6 +10,7 @@ from django.db import DatabaseError, connection from django.test.utils import CaptureQueriesContext, override_settings from django.urls import reverse +from edx_rest_framework_extensions.scoping import FullScopePolicy from edx_rest_framework_extensions.testing import assert_error_envelope from rest_framework import status from rest_framework.test import APITestCase @@ -29,6 +30,7 @@ from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory from openedx.core.djangoapps.user_api.v2.permissions import ACCOUNT_CONTACT_SELECTORS from openedx.core.djangoapps.user_api.v2.serializers import ACCOUNT_DEFAULT_SORT, AccountQuerySerializer +from openedx.core.djangoapps.user_api.v2.views import EmailSearchViewSet from openedx.core.djangoapps.user_authn.views.password_reset import PasswordResetFormNoActive from openedx.core.djangolib.testing.utils import skip_unless_lms @@ -1539,6 +1541,38 @@ def test_an_address_no_account_holds_is_left_out_of_the_page(self): assert [row["username"] for row in response.data["results"]] == ["owner-caller"] assert response.data["count"] == 1 + def test_the_page_carries_the_accounts_the_visibility_layer_leaves(self): + """ + The page is answered from a selection the view's policy has narrowed. + + The policy this view declares keeps every matched account, and the + only caller admitted may read them all, so what is held here is the + layer rather than a narrowing: a policy that keeps a row back is one + the page is answered under, not one the search reads past. The rows + come from the same table the collections of this version narrow, so + the same policy applies to the search as to them. + """ + class _WithoutTheOtherAccount: + """Keeps one account back, standing for a policy narrower than the declared one.""" + + def scope(self, queryset, subject): # pylint: disable=unused-argument + """Return the accounts of this selection other than the other caller's.""" + return queryset.exclude(username="other-caller") + + self.login(self.staff) + with mock.patch.object(EmailSearchViewSet, "scoping_policy", _WithoutTheOtherAccount()): + response = self.search(["owner-caller@example.com", "other-caller@example.com"]) + assert response.status_code == status.HTTP_200_OK + assert [row["username"] for row in response.data["results"]] == ["owner-caller"] + assert response.data["count"] == 1 + + def test_the_search_declares_which_of_the_accounts_it_finds_a_caller_may_see(self): + """Every account the addresses match is answered, because that is what the policy keeps.""" + assert isinstance(EmailSearchViewSet.scoping_policy, FullScopePolicy) + self.login(self.staff) + response = self.search(["owner-caller@example.com", "other-caller@example.com"]) + assert [row["username"] for row in response.data["results"]] == ["other-caller", "owner-caller"] + def test_an_empty_search_finds_nothing(self): self.login(self.staff) response = self.search([]) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index 75a5acd412c6..794d5cf0a41e 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -55,7 +55,9 @@ NAME_CHANGE_PATH = "/api/user/v2/name_changes/" NAME_CHANGE_CONFIRMATION_PATH = "/api/user/v2/name_changes/{username}/confirmations/" +USER_LIST_PATH = "/api/user/v2/users/" USER_MEMBER_PATH = "/api/user/v2/users/{username}/" +PREFERENCE_LIST_PATH = "/api/user/v2/user_preferences/" PREFERENCE_MEMBER_PATH = "/api/user/v2/user_preferences/{username},{key}/" TIME_ZONE_LIST_PATH = "/api/user/v2/time_zones/" @@ -64,8 +66,8 @@ LIST_PATHS = { ACCOUNT_LIST_PATH, VERIFICATION_LIST_PATH, - "/api/user/v2/users/", - "/api/user/v2/user_preferences/", + USER_LIST_PATH, + PREFERENCE_LIST_PATH, TIME_ZONE_LIST_PATH, } MEMBER_PATHS = { @@ -535,6 +537,37 @@ def test_preference_list_publishes_its_filters(schema): assert [name for name, parameter in parameters.items() if parameter.get("deprecated")] == [] +@skip_unless_lms +def test_every_collection_that_selects_accounts_by_name_publishes_the_same_kind_of_value(schema): + """ + A value learned on one of these collections selects the same accounts on the others. + + Each of the three reads a list of names, and a name no account holds is + left out of the page rather than refused, so the published description + opens with the same sentence and the value is published as the text that + carries the list. + """ + published = { + path: next( + parameter for parameter in operation["parameters"] if parameter["name"] == "username" + ) + for path, _method, operation in operations(schema) + if path in {ACCOUNT_LIST_PATH, USER_LIST_PATH, PREFERENCE_LIST_PATH} + } + assert {path: parameter["schema"] for path, parameter in published.items()} == { + ACCOUNT_LIST_PATH: {"type": "string"}, + USER_LIST_PATH: {"type": "string"}, + PREFERENCE_LIST_PATH: {"type": "string"}, + } + assert { + path: parameter["description"].split(".")[0] for path, parameter in published.items() + } == { + ACCOUNT_LIST_PATH: "Comma-separated usernames", + USER_LIST_PATH: "Comma-separated usernames", + PREFERENCE_LIST_PATH: "Comma-separated usernames", + } + + @skip_unless_lms def test_enum_post_processing_runs_before_the_deprecation_hook(): hooks = settings.SPECTACULAR_SETTINGS["POSTPROCESSING_HOOKS"] @@ -849,6 +882,44 @@ def test_member_addresses_describe_the_parts_they_are_built_from(schema): } +#: Every part of an address of this version that carries a username. A client +#: built from the document holds a value to what the route matches before it +#: sends a request, so an address left off this list is one whose caller learns +#: from a refusal what every sibling address refuses for it. +USERNAME_ADDRESS_PARTS = ( + ACCOUNT_MEMBER_PATH, + ACCOUNT_DEACTIVATION_PATH, + PROFILE_IMAGE_PATH, + VERIFICATION_STATUS_PATH, + VERIFICATION_LIST_PATH, + NAME_CHANGE_CONFIRMATION_PATH, + USER_MEMBER_PATH, + PREFERENCE_MEMBER_PATH, +) + + +@skip_unless_lms +def test_every_part_of_an_address_that_carries_a_username_publishes_what_the_route_matches(schema): + """ + One resource does not admit a name at one of its addresses and refuse it at the next. + + The addresses of this version are matched on the same spelling of a + username, whichever app serves them, so each of them is published with + that spelling and a client refuses the same names the routes do. + """ + published = { + (path, parameter["name"]): parameter["schema"] + for path, _method, operation in operations(schema) + if path in VERSION_TWO_PATHS + for parameter in operation.get("parameters", []) + if parameter["in"] == "path" and parameter["name"] == "username" + } + assert published == { + (path, "username"): {"type": "string", "pattern": rf"^{settings.USERNAME_REGEX_PARTIAL}$"} + for path in USERNAME_ADDRESS_PARTS + } + + @skip_unless_lms def test_the_country_parameter_publishes_the_constraint_it_is_held_to(schema): """The parameter comes from the serializer that validates it, so the two cannot disagree.""" @@ -1726,3 +1797,34 @@ def test_the_addresses_this_phase_adds_publish_no_other_query_parameters(schema) VERIFICATION_STATUS_PATH: [], VERIFICATION_LIST_PATH: ["ordering", "page", "page_size"], } + + +@skip_unless_lms +def test_the_stored_preference_reads_are_named_alike_in_every_document_that_publishes_them(schema): + """ + The collection read and the member read of this resource keep one prefix wherever published. + + A client takes the module it writes an operation into from the leading + tokens of that operation's name, so a document naming the two reads of one + resource differently splits the resource across two modules. The documents + derive different names for the member read, because one trims the area off + the front of every path and the other trims nothing, so it is named in + each of them through the name that document derives. + """ + service_wide = service_wide_schema() + assert { + (path, method): operation["operationId"] + for path, method, operation in operations(schema) + if path in {PREFERENCE_LIST_PATH, PREFERENCE_MEMBER_PATH} + } == { + (PREFERENCE_LIST_PATH, "get"): "v2_user_preferences_list", + (PREFERENCE_MEMBER_PATH, "get"): "v2_user_preferences_retrieve", + } + assert { + (path, method): operation["operationId"] + for path, method, operation in operations(service_wide) + if path in {PREFERENCE_LIST_PATH, PREFERENCE_MEMBER_PATH} + } == { + (PREFERENCE_LIST_PATH, "get"): "api_user_v2_user_preferences_list", + (PREFERENCE_MEMBER_PATH, "get"): "api_user_v2_user_preferences_retrieve", + } diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index 6f6b30e80f91..e30730c11d8a 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -254,6 +254,43 @@ def test_one_unknown_field_refuses_the_whole_sort(self): response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", ) + def test_filter_by_username(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "bob", "page_size": 100}) + assert self.usernames_in(response) == ["bob"] + + def test_several_names_select_the_entries_of_each(self): + """ + The value is a list of names, as it is on the account collection. + + A caller that learned the list on one collection of this version and + sent it to another was answered with an empty page, which reads as a + page of the accounts asked for rather than as a value this collection + does not take. + """ + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice,bob", "page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["alice", "bob"] + assert response.data["count"] == 2 + + def test_a_name_in_the_list_that_no_account_holds_is_left_out_of_the_page(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice,nobody", "page_size": 100}) + assert self.usernames_in(response) == ["alice"] + assert response.data["count"] == 1 + + def test_a_position_in_the_list_that_carries_nothing_names_nothing(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": ",alice,,bob,", "page_size": 100}) + assert self.usernames_in(response) == ["alice", "bob"] + + def test_an_empty_name_narrows_nothing(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "", "page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] + def test_filter_by_email(self): self.login(self.admin) response = self.client.get(self.url, {"email": "bob@example.com"}) @@ -715,6 +752,25 @@ def test_filter_by_username(self): response = self.client.get(self.url, {"username": "bob", "page_size": 100}) assert self.keys_in(response) == [("bob", "time_zone")] + def test_several_names_select_the_preferences_of_each(self): + """The value is a list of names, as it is on the sibling collections of this version.""" + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice,bob", "page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "time_zone")] + assert response.data["count"] == 2 + + def test_a_name_in_the_list_that_no_account_holds_is_left_out_of_the_page(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "alice,nobody", "page_size": 100}) + assert self.keys_in(response) == [("alice", "pref-lang")] + + def test_an_empty_name_narrows_nothing(self): + self.login(self.admin) + response = self.client.get(self.url, {"username": "", "page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "time_zone")] + def test_the_owner_id_the_earlier_list_took_is_refused_rather_than_ignored(self): """A caller that ported by changing the version segment is told, not quietly unfiltered.""" self.login(self.admin) @@ -868,6 +924,40 @@ def test_head_writes_nothing(self): assert write_queries(captured.captured_queries) == [] +@skip_unless_lms +class NameSelectorTests(UserApiV2TestCase): + """``?username=`` on the collections of this version that select accounts by name.""" + + def test_every_collection_that_selects_accounts_by_name_reads_one_list(self): + """ + One value names the same accounts wherever it is sent. + + The member address of the stored preferences already reads a comma as + the separator between the two names that identify a preference, so a + collection of this version that read the comma as part of a username + would be answering a value its own addresses spell differently. + """ + self.login(self.admin) + selection = {"username": "alice,bob", "page_size": 100} + pages = { + name: self.client.get(reverse(f"user_v2:{name}"), selection) + for name in ("user_list", "user_preference_list", "account_list") + } + assert {name: page.status_code for name, page in pages.items()} == { + "user_list": status.HTTP_200_OK, + "user_preference_list": status.HTTP_200_OK, + "account_list": status.HTTP_200_OK, + } + assert { + name: sorted({row["username"] for row in page.data["results"]}) + for name, page in pages.items() + } == { + "user_list": ["alice", "bob"], + "user_preference_list": ["alice", "bob"], + "account_list": ["alice", "bob"], + } + + @skip_unless_lms class TimeZoneListViewTests(UserApiV2TestCase): """GET /api/user/v2/time_zones/""" diff --git a/openedx/core/djangoapps/user_api/v2/view_utils.py b/openedx/core/djangoapps/user_api/v2/view_utils.py index 4a7b9124ab0f..30bb6c833cf6 100644 --- a/openedx/core/djangoapps/user_api/v2/view_utils.py +++ b/openedx/core/djangoapps/user_api/v2/view_utils.py @@ -2,7 +2,8 @@ import logging -from drf_spectacular.utils import OpenApiResponse +from django.conf import settings +from drf_spectacular.utils import OpenApiParameter, OpenApiResponse from rest_framework.exceptions import ValidationError from rest_framework.settings import api_settings @@ -21,6 +22,48 @@ #: renderer, and a caller that sends it anyway is answered rather than refused. FORMAT_PARAM = "format" +#: The whole of a username, as every route of this version matches one. A +#: client built from the published document holds a name to this shape before +#: it sends a request, so each address that carries a name is described with +#: it and no address of one resource admits a name another refuses. +USERNAME_PATTERN = rf"^{settings.USERNAME_REGEX_PARTIAL}$" + + +def query_param(name, description, **kwargs): + """Build an optional query parameter for the published schema.""" + return OpenApiParameter( + name=name, + description=description, + required=False, + location=OpenApiParameter.QUERY, + **kwargs, + ) + + +def path_param(name, description, pattern): + """Build a path parameter for the published schema, carrying what its route matches.""" + return OpenApiParameter( + name=name, + description=description, + required=True, + location=OpenApiParameter.PATH, + type=str, + pattern=pattern, + ) + + +def names_in(value): + """ + Return the names a comma-separated value carries, in the order they were sent. + + A position carrying nothing names nothing, so an empty one is left out + rather than read as a name no account holds. Every collection of this + version that selects rows by name reads its value through here, so the + same value selects the same rows wherever it is sent. + """ + return [name for name in value.strip(",").split(",") if name] + + RESP_UNAUTHENTICATED = OpenApiResponse(ErrorResponse, description="The requester is not authenticated.") RESP_UNREADABLE_BODY = OpenApiResponse( ErrorResponse, description="The request body is in a media type this endpoint cannot read.", diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 65475d0fda79..5e28494ea956 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -9,13 +9,7 @@ from django.http import Http404 from django_filters.rest_framework import DjangoFilterBackend from django_ratelimit.core import is_ratelimited -from drf_spectacular.utils import ( - OpenApiExample, - OpenApiParameter, - OpenApiResponse, - extend_schema, - extend_schema_view, -) +from drf_spectacular.utils import OpenApiExample, OpenApiResponse, extend_schema, extend_schema_view from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser from edx_rest_framework_extensions.mixins import StandardizedErrorMixin @@ -99,7 +93,11 @@ RESP_UNREADABLE_BODY, SDK_TAG, USER_TAG, + USERNAME_PATTERN, StrictQueryParametersMixin, + names_in, + path_param, + query_param, ) log = logging.getLogger(__name__) @@ -121,43 +119,17 @@ #: identity has been accepted. APPROVED_STATUS = "approved" - -def _query_param(name, description, **kwargs): - """Build an optional query parameter for the published schema.""" - return OpenApiParameter( - name=name, - description=description, - required=False, - location=OpenApiParameter.QUERY, - **kwargs, - ) - - -def _path_param(name, description, pattern): - """Build a path parameter for the published schema, carrying what its route matches.""" - return OpenApiParameter( - name=name, - description=description, - required=True, - location=OpenApiParameter.PATH, - type=str, - pattern=pattern, - ) - - -_USERNAME_PATTERN = rf"^{settings.USERNAME_REGEX_PARTIAL}$" - -_USER_PATH_PARAM = _path_param( +_USER_PATH_PARAM = path_param( "username", "Unique name of the user whose directory entry is returned.", - _USERNAME_PATTERN, + USERNAME_PATTERN, ) -_PREFERENCE_USERNAME_PATH_PARAM = _path_param( +_PREFERENCE_USERNAME_PATH_PARAM = path_param( "username", "Username of the user the preference belongs to: the part of the address before the comma.", - _USERNAME_PATTERN, + USERNAME_PATTERN, ) -_PREFERENCE_KEY_PATH_PARAM = _path_param( +_PREFERENCE_KEY_PATH_PARAM = path_param( "key", "Name the preference is stored under: the part of the address after the comma.", rf"^{PREFERENCE_KEY_PATTERN_PARTIAL}$", @@ -185,7 +157,7 @@ def _path_param(name, description, pattern): FIELDS_PARAM = "fields" RESPONSE_SHAPING_PARAMS = (VIEW_PARAM, FIELDS_PARAM) -_FIELDS_PARAM = _query_param( +_FIELDS_PARAM = query_param( FIELDS_PARAM, "Comma-separated list of top-level field names to keep in each returned object. " "A name the response cannot carry is refused.", @@ -195,13 +167,13 @@ def _path_param(name, description, pattern): USER_PRESETS = (MINIMAL_VIEW,) PREFERENCE_PRESETS = (FULL_VIEW, MINIMAL_VIEW) -_MINIMAL_VIEW_PARAM = _query_param( +_MINIMAL_VIEW_PARAM = query_param( VIEW_PARAM, "Response preset. `minimal` reduces each user to its identifying fields " "(`id`, `username`, `email`). Omit it to receive the full entry.", enum=list(USER_PRESETS), ) -_PREFERENCE_VIEW_PARAM = _query_param( +_PREFERENCE_VIEW_PARAM = query_param( VIEW_PARAM, "Response preset. `full` embeds the owning user's whole directory entry in each " "preference; `minimal` returns only `username`, `key` and `value`. Omit it to " @@ -212,7 +184,7 @@ def _path_param(name, description, pattern): def _ordering_param(sort_fields, default): """Build the sort parameter of a list, naming the fields it accepts.""" - return _query_param( + return query_param( "ordering", "Fields to sort by, in order of precedence, each optionally prefixed with `-` to sort " "descending. A field that is not listed here is refused.", @@ -283,21 +255,21 @@ def _ordering_param(sort_fields, default): ], ) -_ACCOUNT_PATH_PARAM = _path_param( +_ACCOUNT_PATH_PARAM = path_param( "username", "Unique name of the user whose account is addressed. " f"`{OWN_ACCOUNT_IDENTIFIER}` names the account of the caller, so an account holding that " "name is read through the collection, with `username=` naming it.", - _USERNAME_PATTERN, + USERNAME_PATTERN, ) -_DEACTIVATION_PATH_PARAM = _path_param( +_DEACTIVATION_PATH_PARAM = path_param( "username", "Unique name of the user whose account is deactivated. The name is read as it is stored, " f"`{OWN_ACCOUNT_IDENTIFIER}` included: this action disables the account the address names, " "never the account of the caller making the request.", - _USERNAME_PATTERN, + USERNAME_PATTERN, ) -_ACCOUNT_VIEW_PARAM = _query_param( +_ACCOUNT_VIEW_PARAM = query_param( VIEW_PARAM, "Response preset. `minimal` reduces the account to the properties that identify its owner; " "`shared` returns only the properties the owner shares with everybody, even to a caller who " @@ -642,7 +614,6 @@ def retrieve(self, request, *args, **kwargs): "identified by the pair, which the address carries as the username, a comma and " "the key, for example `alice,time_zone`." ), - operation_id="v2_user_preferences_retrieve", parameters=[ _PREFERENCE_USERNAME_PATH_PARAM, _PREFERENCE_KEY_PATH_PARAM, @@ -1091,7 +1062,7 @@ def _selected_names(self, request, selection): """ usernames = selection.get("username") if usernames: - return [name for name in usernames.strip(",").split(",") if name] + return names_in(usernames) email = selection.get("email") if email: return self._usernames_holding_email(email) @@ -1213,6 +1184,24 @@ def post(self, request, username): return Response(status=status.HTTP_204_NO_CONTENT) +class _SearchedAccountsMixin: + """ + The accounts a search names, before it is narrowed to the ones a caller may see. + + A view's scoping policy is applied on top of the selection the classes + resolved after it answer with, so the unnarrowed selection is declared + here rather than on the view, where it would stand in front of the layer + that narrows it and leave the policy with nothing to do. + """ + + #: The addresses asked about, held for as long as one request is served. + searched_emails = () + + def get_queryset(self): + """Return the accounts holding the addresses this request asked about.""" + return accounts_holding_emails(self.searched_emails) + + @extend_schema(tags=[SDK_TAG]) @extend_schema_view( create=extend_schema( @@ -1242,6 +1231,8 @@ class EmailSearchViewSet( CatalogedRequestErrorsMixin, StrictQueryParametersMixin, IterablePaginationMixin, + ScopedQuerysetMixin, + _SearchedAccountsMixin, viewsets.ViewSet, ): """ @@ -1264,6 +1255,11 @@ class EmailSearchViewSet( CanGetAccountInfo, IsStaffOrAbsent, ) + # A platform administrator may read every account the addresses match, so + # the policy keeps the selection whole; a narrower policy can replace it + # without touching the search below, and the accounts come from the same + # table the other collections of this version narrow. + scoping_policy = FullScopePolicy() parser_classes = (JSONParser,) serializer_class = EmailSearchResultSerializer pagination_class = UserApiPagination @@ -1276,15 +1272,16 @@ def create(self, request): """Return a page of the accounts holding the addresses the body carries.""" search = EmailSearchSerializer(data=request.data) search.is_valid(raise_exception=True) - return self.paginate_iterable(request, accounts_holding_emails(search.validated_data["emails"])) + self.searched_emails = search.validated_data["emails"] + return self.paginate_iterable(request, self.get_queryset()) -_NAME_CHANGE_PATH_PARAM = _path_param( +_NAME_CHANGE_PATH_PARAM = path_param( "username", "Unique name of the user whose requested change is confirmed. The name is read as it is " f"stored, so `{OWN_ACCOUNT_IDENTIFIER}` here names an account holding that name rather than " "the account of the caller making the request.", - _USERNAME_PATTERN, + USERNAME_PATTERN, ) @@ -1403,12 +1400,12 @@ def _confirm_change(self, user, pending): raise NotFound from exc -_VERIFICATION_PATH_PARAM = _path_param( +_VERIFICATION_PATH_PARAM = path_param( "username", "Unique name of the user whose identity verification is addressed. The name is read as it is " f"stored, so `{OWN_ACCOUNT_IDENTIFIER}` here names an account holding that name rather than " "the account of the caller making the request.", - _USERNAME_PATTERN, + USERNAME_PATTERN, ) From a3e74454d410f48515119dc88083e80ff21a6d6a Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Fri, 30 Oct 2026 00:53:37 +0500 Subject: [PATCH 07/61] test: hold the four corrected success codes to the handlers that answer them Both documents already published these four addresses with a 200 and no body before their bodies were described. No handler answers that: each answers 204. The corrected code is now pinned in both documents and each handler is driven on its success path in the same test, so the published code and the answered one can only move together. Replaces the pin that covered two of the four in one document. --- lms/lib/tests/test_spectacular.py | 91 ++++++++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 1 deletion(-) diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index 9a24fe93e701..516f6fae9525 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -5,7 +5,7 @@ from types import SimpleNamespace from unittest import mock -from django.test import SimpleTestCase, TestCase +from django.test import Client, SimpleTestCase, TestCase from django.urls import path from drf_spectacular.generators import SchemaGenerator from drf_spectacular.settings import patched_settings, spectacular_settings @@ -14,6 +14,8 @@ from rest_framework.response import Response from rest_framework.settings import api_settings +from common.djangoapps.student.models_api import do_name_change_request +from common.djangoapps.student.tests.factories import TEST_PASSWORD, UserFactory from lms.lib.spectacular import ( RENAMED_OPERATION_IDS, SUPERSEDED_USER_PATHS, @@ -23,6 +25,11 @@ superseded_bodies, ) from openedx.core.apidocs import get_api_docs_settings +from openedx.core.djangoapps.profile_images.tests.helpers import make_image_file +from openedx.core.djangoapps.user_api.accounts.image_helpers import ( + get_profile_image_names, + get_profile_image_storage, +) ENROLLMENT_VIEWS = "openedx.core.djangoapps.enrollments.views" USER_API_V1_VIEWS = "openedx.core.djangoapps.user_api.views" @@ -397,6 +404,88 @@ def test_no_superseded_operation_answers_with_a_body_it_does_not_describe(self): assert undescribed == [] +#: Each address this document already published before its body was described, +#: and the success code its handler really answers. That document carried a 200 +#: with no body for both, which no handler answers; the code each is +#: published under now is driven below. +CORRECTED_SUCCESS_CODES = ( + ("post", "/api/user/v1/accounts/name_change/{username}/confirm/", "204"), + ("post", "/api/user/v1/accounts/{username}/image", "204"), +) + + +class CorrectedSuccessCodeTest(TestCase): + """ + Two addresses both documents already published answer a success code neither carried. + + These are not new addresses: a client generated before this change branches + on the code the document gave them, so each is pinned here in both + documents and each handler is driven, so that the published code can only + change again together with the handler that answers it. + """ + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.documents = {"published": SchemaGenerator().get_schema(request=None, public=True)} + with patched_settings(get_api_docs_settings()): + cls.documents["service-wide"] = SchemaGenerator().get_schema(request=None, public=True) + + def setUp(self): + super().setUp() + self.owner = UserFactory.create(username="codeowner", password=TEST_PASSWORD) + self.owner.profile.year_of_birth = 1980 + self.owner.profile.save() + self.staff = UserFactory.create(username="codestaff", password=TEST_PASSWORD, is_staff=True) + self.storage = get_profile_image_storage() + + def tearDown(self): + for name in get_profile_image_names(self.owner.username).values(): + self.storage.delete(name) + super().tearDown() + + def _as(self, user): + """A client signed in as that account.""" + client = Client() + assert client.login(username=user.username, password=TEST_PASSWORD) + return client + + def _answered(self): + """Drive each of the two on its success path and return the code it answers.""" + owner, staff = self._as(self.owner), self._as(self.staff) + do_name_change_request(self.owner, "Another Name", "a reason") + answered = { + ("post", "/api/user/v1/accounts/name_change/{username}/confirm/"): staff.post( + f"/api/user/v1/accounts/name_change/{self.owner.username}/confirm/", + ).status_code, + } + with make_image_file() as image_file: + answered[("post", "/api/user/v1/accounts/{username}/image")] = owner.post( + f"/api/user/v1/accounts/{self.owner.username}/image", {"file": image_file}, + ).status_code + return answered + + def test_each_handler_answers_the_code_it_is_published_under(self): + assert self._answered() == { + (method, address): int(code) for method, address, code in CORRECTED_SUCCESS_CODES + } + + def test_every_document_publishes_that_code_and_nothing_beside_it(self): + published = {} + for name, document in self.documents.items(): + for method, address, _code in CORRECTED_SUCCESS_CODES: + responses = document["paths"][address][method]["responses"] + published[(name, method, address)] = ( + sorted(responses), + ["content" in response for response in responses.values()], + ) + assert published == { + (name, method, address): ([code], [False]) + for name in self.documents + for method, address, code in CORRECTED_SUCCESS_CODES + } + + class PublishedDocumentTest(TestCase): """What the service actually publishes: distinct ids, and one area per tag group.""" From 94af55b74da169576dba907210db5a57e1d93c11 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Fri, 30 Oct 2026 00:57:20 +0500 Subject: [PATCH 08/61] fix: mark the superseded user addresses Studio serves as superseded there too Studio mounts the user API at the same addresses the LMS does and publishes its own unauthenticated document at /api-docs/, built from its own settings, so none of the marking applied in the LMS reached it: all twenty-five of those operations were published there as current while the LMS published them as superseded. A client generated from Studio's document therefore offered a caller an address the LMS document steers them off. The list of superseded addresses and the hook that reads it are shared rather than restated, so the two services cannot drift apart. Measured on the two generated documents: Studio marks 25 of 25, as the LMS does, and nothing else in Studio's document changes -- no path, operation, operationId or component is added or lost. The narrow Authoring API document Studio also serves carries none of these addresses, so the hook cannot reach it. --- cms/envs/common.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/cms/envs/common.py b/cms/envs/common.py index ed0d2b0cbf3c..4f43d47e7363 100644 --- a/cms/envs/common.py +++ b/cms/envs/common.py @@ -1338,6 +1338,14 @@ def _should_send_xblock_events(settings): 'drf_spectacular.hooks.postprocess_schema_enums', 'cms.lib.spectacular.cms_mark_superseded_paths', 'cms.lib.spectacular.cms_mark_migrated_paths', + # Studio mounts the user API at the same addresses the LMS does, and + # both services publish an unauthenticated document at /api-docs/, so + # an address superseded in one is superseded in the other. The list of + # them and the hook that reads it are shared rather than restated here, + # which is what stops a client generated from Studio's document from + # offering an address as current that the LMS document marks as + # superseded. + 'lms.lib.spectacular.lms_mark_legacy_paths_deprecated', 'openedx.core.apidocs.untag_deprecated_operations', ], # Stripped from each path to derive its tags and operationId, so changing From b572b73135be33ca500e3159fbdce4f0b75b96ef Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Fri, 30 Oct 2026 01:03:28 +0500 Subject: [PATCH 09/61] fix: carry the service's appended components into the documentation settings The documentation settings replaced the appended components wholesale rather than adding the security schemes to them, so any component name the service settings append was dropped from the settings the published reference is generated from. Nothing showed it: the name simply stops being in the reference, and in every client built from it, while every count stays where it was. They now add to what they inherit. The test loads those settings in a process of its own -- loading them here would turn every feature flag on and add Studio's applications to the settings this process already runs under -- and checks that a component the service settings append arrives alongside the security schemes. --- docs/docs_settings.py | 7 ++++ lms/lib/tests/test_spectacular.py | 65 +++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) diff --git a/docs/docs_settings.py b/docs/docs_settings.py index 48ec4a5cc63e..12e1bca30c9b 100644 --- a/docs/docs_settings.py +++ b/docs/docs_settings.py @@ -82,7 +82,14 @@ # OpenAPI 3 security schemes, consumed by drf-spectacular. "Basic" uses the # OpenAPI 3 http/basic form rather than Swagger 2.0's type: basic. +# +# Whatever the service settings already append is carried through rather than +# replaced: that key holds component names the published reference is expected +# to carry, and dropping one here takes it out of the generated reference and +# out of every client built from it without changing any count that would show +# it had gone. SPECTACULAR_SETTINGS["APPEND_COMPONENTS"] = { # noqa: F405 + **SPECTACULAR_SETTINGS.get("APPEND_COMPONENTS", {}), # noqa: F405 "securitySchemes": { "Basic": { "type": "http", diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index 516f6fae9525..8ed309a7139a 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -1,7 +1,12 @@ """Tests for the LMS drf-spectacular hooks and schema class.""" +import json +import os import re +import subprocess +import sys from collections import defaultdict +from pathlib import Path from types import SimpleNamespace from unittest import mock @@ -486,6 +491,66 @@ def test_every_document_publishes_that_code_and_nothing_beside_it(self): } +#: Loaded in a process of its own below. The service settings append a +#: component, and the documentation settings are then asked what they append, +#: so that a key one of them carries is seen to reach the other. +DOCUMENTATION_SETTINGS_CHILD = """ +import json +import os + +import lms.envs.common as service_settings + +service_settings.SPECTACULAR_SETTINGS["APPEND_COMPONENTS"] = { + "schemas": {"ServiceComponent": {"type": "object"}}, +} + +os.environ["DJANGO_SETTINGS_MODULE"] = "docs.docs_settings" +from django.conf import settings + +appended = settings.SPECTACULAR_SETTINGS.get("APPEND_COMPONENTS", {}) +print("APPENDED " + json.dumps({ + "keys": sorted(appended), + "schemas": sorted(appended.get("schemas", {})), + "security": sorted(appended.get("securitySchemes", {})), +})) +""" + + +class DocumentationSettingsTest(SimpleTestCase): + """ + The settings the published reference is generated from keep what the service appends. + + They are loaded in a process of their own because they turn every feature + flag on and add Studio's applications to the settings object this process + is already running under, so loading them here would reconfigure the + service for every test that follows. What they append holds component + names the published reference is expected to carry, and one dropped there + leaves the reference and every client built from it without that name + while no count moves. + """ + + def test_a_component_the_service_appends_reaches_the_published_reference(self): + repository = Path(__file__).resolve().parents[3] + environment = dict(os.environ, PYTHONPATH=str(repository)) + environment.pop("DJANGO_SETTINGS_MODULE", None) + finished = subprocess.run( + [sys.executable, "-c", DOCUMENTATION_SETTINGS_CHILD], + cwd=str(repository), + env=environment, + capture_output=True, + text=True, + check=False, + ) + assert finished.returncode == 0, finished.stderr[-2000:] + reported = [line for line in finished.stdout.splitlines() if line.startswith("APPENDED ")] + assert len(reported) == 1, finished.stdout[-2000:] + assert json.loads(reported[0].split(" ", 1)[1]) == { + "keys": ["schemas", "securitySchemes"], + "schemas": ["ServiceComponent"], + "security": ["Basic", "csrf", "jwt"], + } + + class PublishedDocumentTest(TestCase): """What the service actually publishes: distinct ids, and one area per tag group.""" From 0e0124ff03c17719b03eb334d1dfdd2c6dcde874 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Fri, 30 Oct 2026 00:33:08 +0500 Subject: [PATCH 10/61] fix: refuse a page size no collection of this version will give Asking for a page of nothing, of fewer than nothing, or of something that is not a whole number of rows was answered 200 with the default page of ten, on every collection of this version that pages its rows. The framework drops a size it cannot honour and falls back without telling the caller, so the page reads as the one that was asked for; the links on it carry the value back, so a client that follows them keeps sending a number nothing reads. The shared paginator now reads the value itself and refuses one no page can have, the way this version already refuses a query parameter it does not read, a sort field it does not offer and a boolean naming neither side. A number above what a page carries is still answered with a full page, which is what it has always meant, and a value carrying nothing still leaves the size alone. --- .../core/djangoapps/user_api/v2/paginators.py | 39 ++++- .../user_api/v2/tests/test_pagination.py | 154 ++++++++++++++++++ 2 files changed, 191 insertions(+), 2 deletions(-) create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_pagination.py diff --git a/openedx/core/djangoapps/user_api/v2/paginators.py b/openedx/core/djangoapps/user_api/v2/paginators.py index 5e796180d3cb..8251e1c3f52d 100644 --- a/openedx/core/djangoapps/user_api/v2/paginators.py +++ b/openedx/core/djangoapps/user_api/v2/paginators.py @@ -1,19 +1,54 @@ """Pagination for version 2 of the User API.""" +import logging + from edx_rest_framework_extensions.paginators import DefaultPagination +from rest_framework.exceptions import ValidationError + +log = logging.getLogger(__name__) class UserApiPagination(DefaultPagination): """ - Page-number pagination whose published schema matches the body it returns. + Page-number pagination whose published schema matches the body it returns, + and which refuses a number of rows no page of it can carry. ``DefaultPagination`` answers with ``count``, ``num_pages``, ``current_page``, ``start``, ``next``, ``previous`` and ``results`` but inherits the four-member schema of DRF's ``PageNumberPagination``, so a generated client would not know about the three page-position members. - This subclass only restates the response schema; the body is unchanged. + The response schema below only restates them; the body is unchanged. """ + def get_page_size(self, request): + """ + Return how many rows a page carries, refusing a number no page can have. + + The number asked for is otherwise dropped where it cannot be honoured + and the default page answered in its place, which a caller reads as + the page it asked for; worse, the links on that page carry the value + back, so a client that follows them keeps sending a number that is + never read. A number above what a page carries is still answered with + as many rows as it carries, because asking for more rows than a page + holds is asking for a full one. + """ + asked = request.query_params.get(self.page_size_query_param) + if asked is None or asked == "": + return self.page_size + try: + rows = int(asked) + except ValueError: + rows = 0 + if rows < 1: + log.info("Page size refused at %s: %r", request.path, asked) + raise ValidationError({ + self.page_size_query_param: [ + "Enter a whole number of rows of at least 1. A larger number than " + f"{self.max_page_size} returns {self.max_page_size} rows.", + ], + }) + return min(rows, self.max_page_size) + def get_paginated_response_schema(self, schema): """Describe the full envelope the paginator returns.""" return { diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_pagination.py b/openedx/core/djangoapps/user_api/v2/tests/test_pagination.py new file mode 100644 index 000000000000..667417184f4c --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_pagination.py @@ -0,0 +1,154 @@ +"""Page-size handling on the paginated collections of version 2 of the User API.""" + +import inspect + +from django.urls import reverse +from edx_rest_framework_extensions.testing import assert_error_envelope +from rest_framework import status +from rest_framework.test import APITestCase + +from common.djangoapps.student.tests.factories import AdminFactory, UserFactory +from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangoapps.user_api.v2 import views as user_api_views +from openedx.core.djangoapps.user_api.v2.paginators import UserApiPagination +from openedx.core.djangolib.testing.utils import skip_unless_lms + +PASSWORD = "Password1234" + +#: Values naming a number of rows no page can carry: none at all, fewer than +#: none, and values that are not a whole number of rows in the first place. +UNHONOURED_PAGE_SIZES = ("0", "-1", "abc", "1.5", "0x10", "%20") + +#: What a caller is told when it asks for one of them. +REFUSAL = ( + "Enter a whole number of rows of at least 1. A larger number than " + f"{UserApiPagination.max_page_size} returns {UserApiPagination.max_page_size} rows." +) + + +@skip_unless_lms +class PageSizeTests(APITestCase): + """ + A page size the collection will not give is refused rather than answered. + + The size asked for is dropped by the framework when it cannot be honoured + and the default page is answered in its place, which a caller reads as the + page it asked for; the links on that page carry the value back, so a + client following them keeps sending a number that is never read. Each + collection below is checked, because the number is read by the paginator + they share and a collection that stopped sharing it would stop refusing. + """ + + def setUp(self): + super().setUp() + self.admin = AdminFactory.create(username="page-admin", password=PASSWORD) + self.learner = UserFactory.create(username="page-learner", password=PASSWORD) + UserPreferenceFactory.create(user=self.learner, key="time_zone", value="UTC") + + def collections(self): + """Return each paginated collection, the caller it admits and how it is asked.""" + return { + "user_list": (self.admin, reverse("user_v2:user_list"), {}), + "user_preference_list": (self.admin, reverse("user_v2:user_preference_list"), {}), + "time_zone_list": (None, reverse("user_v2:time_zone_list"), {}), + "account_list": (self.learner, reverse("user_v2:account_list"), {}), + "account_verification_list": ( + self.learner, + reverse( + "user_v2:account_verification_list", + kwargs={"username": self.learner.username}, + ), + {}, + ), + "email_search_list": ( + self.admin, + reverse("user_v2:email_search_list"), + {"body": {"emails": [self.learner.email]}}, + ), + } + + def ask(self, caller, address, page_size, body=None): + """Ask one collection for a page of ``page_size`` rows as ``caller``.""" + self.client.logout() + if caller is not None: + assert self.client.login(username=caller.username, password=PASSWORD) + query = "" if page_size is None else f"?page_size={page_size}" + if body is None: + return self.client.get(f"{address}{query}") + return self.client.post(f"{address}{query}", body, format="json") + + def test_a_number_of_rows_no_page_can_carry_is_refused(self): + for name, (caller, address, extra) in self.collections().items(): + for page_size in UNHONOURED_PAGE_SIZES: + with self.subTest(collection=name, page_size=page_size): + response = self.ask(caller, address, page_size, **extra) + envelope = assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"page_size": [REFUSAL]} + + def test_a_value_carrying_nothing_asks_for_nothing_and_is_answered(self): + """An empty value leaves the size alone, as an empty selector leaves the rows alone.""" + for name, (caller, address, extra) in self.collections().items(): + with self.subTest(collection=name): + response = self.ask(caller, address, "", **extra) + assert response.status_code in ( + status.HTTP_200_OK, status.HTTP_201_CREATED, + ), response.content + assert len(response.data["results"]) <= UserApiPagination.page_size + + def test_more_rows_than_a_page_carries_is_answered_with_as_many_as_it_carries(self): + """A number above the cap keeps being answered with the cap rather than refused.""" + for index in range(UserApiPagination.max_page_size + 5): + UserFactory.create(username=f"page-filler{index:03d}") + self.client.logout() + assert self.client.login(username=self.admin.username, password=PASSWORD) + response = self.client.get(reverse("user_v2:user_list"), {"page_size": 100000}) + assert response.status_code == status.HTTP_200_OK, response.content + assert len(response.data["results"]) == UserApiPagination.max_page_size + + def test_the_link_to_the_next_page_carries_a_size_the_next_page_will_give(self): + """ + A refused size cannot reach the links, and an honoured one is carried back unchanged. + + A link carrying a size the collection drops sends the client back with + the same value on every page it follows, and every one of those pages + is a different size from the one it asked for. + """ + for index in range(5): + UserFactory.create(username=f"page-walked{index:03d}") + self.client.logout() + assert self.client.login(username=self.admin.username, password=PASSWORD) + response = self.client.get(reverse("user_v2:user_list"), {"page_size": 2}) + assert response.status_code == status.HTTP_200_OK, response.content + assert len(response.data["results"]) == 2 + assert response.data["next"].endswith("?page=2&page_size=2") + + followed = self.client.get(response.data["next"]) + assert followed.status_code == status.HTTP_200_OK, followed.content + assert len(followed.data["results"]) == 2 + + def test_every_collection_of_this_version_that_pages_is_checked_here(self): + """ + The refusal lives in one paginator, so the check is only worth what it covers. + + A collection added later that pages its rows with the same paginator + is listed above or this fails, rather than the refusal quietly + applying to an address nothing exercises. + """ + paging = { + name + for name, member in inspect.getmembers(user_api_views, inspect.isclass) + if getattr(member, "pagination_class", None) is UserApiPagination + } + assert paging == { + "AccountViewSet", + "CountryTimeZoneViewSet", + "EmailSearchViewSet", + "IDVerificationViewSet", + "UserPreferenceViewSet", + "UserViewSet", + } + assert len(self.collections()) == len(paging) From cdffcf7c4c95e5dbb049f392f5d5ef61ff096530 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Fri, 30 Oct 2026 01:01:49 +0500 Subject: [PATCH 11/61] fix: say in words why a request was refused, not in printed data The standard error body carries one line for a person to read beside the list of what each parameter or property was refused for. Where the refusal named parameters, that line was produced by printing the list itself, so a caller read back the brackets, the quoting and the class names that write a data structure out instead of a sentence. Everything that puts the line in front of a person showed it: the message of the exception a generated client raises, a line in an integration log, the notification a page puts up. The line is now written from the same values as a sentence, naming each parameter and what it was refused for; a refusal that names nothing in particular is spelled on its own. The list itself is untouched, and a refusal that never had a list -- an address that matches nothing, a caller that may not read, a method the address does not serve -- keeps the line it had. --- openedx/core/djangoapps/user_api/v2/errors.py | 46 ++++++- .../user_api/v2/tests/test_parity.py | 129 ++++++++++++++++++ 2 files changed, 174 insertions(+), 1 deletion(-) diff --git a/openedx/core/djangoapps/user_api/v2/errors.py b/openedx/core/djangoapps/user_api/v2/errors.py index bbd8b5ab2b60..f21dee73dc4c 100644 --- a/openedx/core/djangoapps/user_api/v2/errors.py +++ b/openedx/core/djangoapps/user_api/v2/errors.py @@ -8,6 +8,7 @@ ParseError, UnsupportedMediaType, ) +from rest_framework.settings import api_settings class RefusedMethod(MethodNotAllowed): @@ -50,7 +51,46 @@ def __init__(self, detail=None, can_cancel_retirement=False, retirement_id=None) register_error_type(RetiredAccount, "user/retired-account", "Retired Account") -class CatalogedRequestErrorsMixin: +def refusal_sentence(refusals): + """ + Return one sentence naming what each parameter or property was refused for. + + A refusal that names nothing in particular is spelled on its own, so the + sentence reads the same whether or not the thing refused has a name. + """ + return " ".join( + reason if name == api_settings.NON_FIELD_ERRORS_KEY else f"{name}: {reason}" + for name, reasons in refusals.items() + for reason in reasons + ) + + +class ReadableErrorDetailMixin: + """ + Writes the one-line message of a refused request as a sentence. + + The standard error body carries a line for a person to read beside the + list of what each parameter or property was refused for, and where the + refusal names them that line was produced by printing the list itself. + Everything that puts the line in front of a person then shows the + brackets, the quoting and the class names that write a data structure + out: the message of the exception a generated client raises, a line in an + integration's log, the notification a page puts on the screen. The list is + left exactly as it was; only the line is rewritten, from the same values. + """ + + def handle_exception(self, exc): + """Answer with the standard body, its one-line message written in words.""" + response = super().handle_exception(exc) + body = getattr(response, "data", None) + if isinstance(body, dict) and isinstance(body.get("errors"), dict): + sentence = refusal_sentence(body["errors"]) + if sentence: + body["detail"] = sentence + return response + + +class CatalogedRequestErrorsMixin(ReadableErrorDetailMixin): """ Names the error type of a refused method, an unanswerable ``Accept`` header, a body in a media type this API cannot read and a body that is not @@ -61,6 +101,10 @@ class CatalogedRequestErrorsMixin: subclasses of them names each error without changing how the same failure is classified for any other API in the process; once the shared catalog covers them, the subclasses can give way to it. + + A view that classifies its request failures also wants the one-line + message of each of them to read as a sentence, so this carries what the + class it extends does as well, and a view names one mixin rather than two. """ def handle_exception(self, exc): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_parity.py index 38a75fe6bd13..f5caac0bb7a5 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_parity.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_parity.py @@ -372,3 +372,132 @@ def test_an_identifier_held_by_a_caller_resolves_to_the_username_the_entry_is_ke entry = self.conforming(reverse("user_v2:user_detail", kwargs={"username": "parity-user"})) assert entry.status_code == status.HTTP_200_OK assert json.loads(entry.content)["id"] == self.user.id + + +@skip_unless_lms +class RefusedRequestMessageTests(APITestCase): + """ + What a person reads when a request of either version is refused. + + The earlier addresses answer a refusal with one sentence, and the + standardized body of this version keeps a member for that sentence beside + the list of what each parameter was refused for. Where the refusal names + parameters, that sentence was being built by printing the list itself, so + the quoting, the bracketing and the class names of the data structure + holding it reached everything that shows the sentence to a person: the + message of an exception a generated client raises, a line in an + integration's log, the notification a page puts on the screen. + """ + + def setUp(self): + super().setUp() + self.admin = AdminFactory.create(username="refusal-admin", password=PASSWORD) + + def refused(self, address, params): + """Call a version 2 address as the administrator it is gated by.""" + assert self.client.login(username=self.admin.username, password=PASSWORD) + response = self.client.get(address, params) + self.client.logout() + return assert_error_envelope( + response, + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + + def test_the_sentence_of_a_refusal_naming_one_parameter_is_the_sentence_that_parameter_got(self): + cases = [ + ( + reverse("user_v2:user_list"), + {"forum_role": "Moderator"}, + {"course_key": ["This parameter is required when forum_role is supplied."]}, + "course_key: This parameter is required when forum_role is supplied.", + ), + ( + reverse("user_v2:user_list"), + {"is_active": "maybe"}, + {"is_active": ["Enter true or false."]}, + "is_active: Enter true or false.", + ), + ( + reverse("user_v2:user_preference_list"), + {"page_size": "0"}, + { + "page_size": [ + "Enter a whole number of rows of at least 1. " + "A larger number than 100 returns 100 rows.", + ], + }, + "page_size: Enter a whole number of rows of at least 1. " + "A larger number than 100 returns 100 rows.", + ), + ] + for address, params, expected_errors, expected_sentence in cases: + with self.subTest(address=address, params=params): + envelope = self.refused(address, params) + assert envelope["errors"] == expected_errors + assert envelope["detail"] == expected_sentence + + def test_the_sentence_of_a_refusal_naming_several_parameters_names_each_of_them(self): + """Every parameter refused is in the sentence, in the order the list carries them.""" + envelope = self.refused(reverse("user_v2:user_list"), {"nope": "1", "alsonope": "2"}) + assert sorted(envelope["errors"]) == ["alsonope", "nope"] + assert envelope["detail"] == " ".join( + f"{name}: {message}" + for name, messages in envelope["errors"].items() + for message in messages + ) + assert envelope["detail"].startswith("alsonope: No such query parameter.") + + def test_a_refusal_that_names_nothing_in_particular_is_spelled_on_its_own(self): + """A body of the wrong shape is refused with no property to hang the refusal on.""" + assert self.client.login(username=self.admin.username, password=PASSWORD) + response = self.client.post(reverse("user_v2:email_search_list"), [], format="json") + self.client.logout() + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == { + "non_field_errors": ["Invalid data. Expected a dictionary, but got list."], + } + assert envelope["detail"] == "Invalid data. Expected a dictionary, but got list." + + def test_a_refusal_naming_no_parameter_says_what_it_has_always_said(self): + """Only the refusals built from a list of parameters change; the rest are untouched.""" + assert self.client.login(username=self.admin.username, password=PASSWORD) + missing = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "nobody"})) + envelope = assert_error_envelope( + missing, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + assert envelope["detail"] == "Not found." + assert "errors" not in envelope + + def test_no_sentence_of_a_refusal_carries_the_printed_form_of_a_list_or_a_mapping(self): + """ + One sweep over the refusals this version produces, rather than a case each. + + A sentence built by printing a data structure carries the brackets, + the quotes and the class names that write it, none of which belong in + something a person reads. + """ + refusals = [ + (reverse("user_v2:user_list"), {"is_active": "maybe"}), + (reverse("user_v2:user_list"), {"forum_role": "Moderator"}), + (reverse("user_v2:user_list"), {"course_key": "course-v1:edX+DemoX+Demo"}), + (reverse("user_v2:user_list"), {"ordering": "password"}), + (reverse("user_v2:user_list"), {"nope": "1"}), + (reverse("user_v2:user_list"), {"page_size": "0"}), + (reverse("user_v2:user_preference_list"), {"ordering": "nope"}), + (reverse("user_v2:user_preference_list"), {"page_size": "-1"}), + (reverse("user_v2:time_zone_list"), {"country_code": "nowhere"}), + ] + for address, params in refusals: + with self.subTest(address=address, params=params): + envelope = self.refused(address, params) + sentence = envelope["detail"] + assert isinstance(sentence, str) + assert not any(mark in sentence for mark in ("{", "}", "[", "]", "ErrorDetail(")), sentence + assert sentence == " ".join( + f"{name}: {message}" + for name, messages in envelope["errors"].items() + for message in messages + ) From f1e6e65ea0966fc4e156596c8c3c22696d1cd2cc Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 20:07:03 +0500 Subject: [PATCH 12/61] fix: answer a member account address from the record the lookup resolved it to A member address of the account collection was answered by matching the name it carried against the name each record that came back is stored under, by a reduced form of that name failing that, and anything matching neither was dropped. The database settles which stored records a name resolves to, and the name it resolves to need not be written the way the address wrote it: where it resolved to a record neither comparison matched, the list came back empty, the member handler indexed the first element of it, and an authenticated caller was answered 500. The superseded address answers 200 with that record, so the replacement was worse than the address it stands in for, and a client or MFE that pads or transliterates a name turned a working read into a server fault. A member address is now answered from the records the lookup resolved it to: the one stored under exactly the name given when there is one, and otherwise the single record that came back. An address the lookup resolves to several records, none of them stored under the name given, names no one of them, so it is refused with 400 rather than answered with whichever came back first. A lookup that comes back with nothing is reported as an absent address rather than as a fault. The page of a list keeps the order its names were asked in, which is what the matching is for; a record it resolved to under a name none of them is written as is now carried at the end of the page rather than left out of it in silence. Tests: a member address the lookup resolves to a record stored differently, one it resolves to nothing, one it resolves to several records with and without an exact match among them, and a page carrying a record resolved under another name. Each fails against the previous code, the first three with the 500 this corrects. --- .../user_api/v2/tests/test_account_views.py | 113 +++++++++++++++--- openedx/core/djangoapps/user_api/v2/views.py | 87 ++++++++++---- 2 files changed, 160 insertions(+), 40 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index e80a8351f17b..ceee3bd9f957 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -30,7 +30,7 @@ from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory from openedx.core.djangoapps.user_api.v2.permissions import ACCOUNT_CONTACT_SELECTORS from openedx.core.djangoapps.user_api.v2.serializers import ACCOUNT_DEFAULT_SORT, AccountQuerySerializer -from openedx.core.djangoapps.user_api.v2.views import EmailSearchViewSet +from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS, EmailSearchViewSet from openedx.core.djangoapps.user_authn.views.password_reset import PasswordResetFormNoActive from openedx.core.djangolib.testing.utils import skip_unless_lms @@ -79,6 +79,10 @@ #: Where the classes the platform declares record that they read a request. DEFAULT_AUTH_RECORDER = "openedx.core.djangolib.default_auth_classes.set_custom_attribute" +#: Where the account views look an account up, which the database answers. A +#: test that stands in for the database answers it from here. +ACCOUNT_LOOKUP = "openedx.core.djangoapps.user_api.v2.views.get_account_settings" + def counting_cache(location): """ Return a cache that counts what it is given, under a name of its own. @@ -228,6 +232,27 @@ def test_a_name_no_account_holds_is_left_out_rather_than_refused(self): assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["owner-caller"] + def test_an_account_the_lookup_resolved_a_name_to_is_carried_by_the_page(self): + """ + A page carries every account its lookup came back with. + + The rows are put back in the order the names were asked for by the name + each account is stored under. An account stored under a name none of + them is written as is carried at the end of the page rather than + dropped from it in silence. + """ + def one_account_written_apart(request, usernames=None, **kwargs): # pylint: disable=unused-argument + assert usernames == ["owner-caller"] + return [{"username": "owner-caller ", "email": "owner-caller@example.com"}] + + self.login(self.staff) + with mock.patch(ACCOUNT_LOOKUP, one_account_written_apart): + response = self.client.get(self.list_url, {"username": "owner-caller"}) + assert response.status_code == status.HTTP_200_OK + assert response.data["results"] == [ + {"username": "owner-caller ", "email": "owner-caller@example.com"}, + ] + def test_a_selector_that_names_no_account_answers_an_empty_page(self): """A collection that matched nothing is an empty page, not an absent collection.""" self.login(self.staff) @@ -634,30 +659,90 @@ def test_an_account_named_after_another_collection_is_served_at_its_own_address( assert set(by_a_learner.data) == PUBLIC_FIELDS assert by_a_learner.data["username"] == "email_searches" - def test_a_member_address_spelled_in_another_case_carries_the_account_it_names(self): + def test_a_member_address_a_stored_account_answers_to_carries_that_account(self): """ - A database that holds usernames case-insensitively answers an address spelled differently. - - Whether two names differing only in case name one account is the - database's decision, and the collation MySQL applies to these columns - by default says they do, so an account can come back stored under a - spelling other than the one the address carried. The test database - compares the names exactly, so the account service is answered here as - a database holding them case-insensitively answers it. + An address the lookup resolves to a stored account is answered with that account. + + Which stored names an address resolves to is the database's decision, + and the name it resolves to can be written differently from the one the + address carried. The test database resolves a name only to the record + stored under exactly it, so the account service is answered here the + way it answers where an address resolves more widely. """ def stored_under_another_spelling(request, usernames=None, **kwargs): # pylint: disable=unused-argument assert usernames == ["Owner-Caller"] return [{"username": "owner-caller", "email": "owner-caller@example.com"}] self.login(self.staff) - with mock.patch( - "openedx.core.djangoapps.user_api.v2.views.get_account_settings", - stored_under_another_spelling, - ): + with mock.patch(ACCOUNT_LOOKUP, stored_under_another_spelling): response = self.client.get(self.detail_url("Owner-Caller")) assert response.status_code == status.HTTP_200_OK assert response.data == {"username": "owner-caller", "email": "owner-caller@example.com"} + def test_a_member_address_resolving_to_a_name_written_further_apart_carries_that_account(self): + """ + An address resolving to a record whose name shares less with it is answered with that record. + + The name asked for is matched to the record the lookup came back with + so that a page carries its rows in the order they were asked for. At a + member address the record the lookup resolved to is the answer whatever + it is stored under, which is what the superseded version answers. + """ + def stored_under_a_name_written_further_apart(request, usernames=None, **kwargs): # pylint: disable=unused-argument + assert usernames == ["owner-caller "] + return [{"username": "owner-caller", "email": "owner-caller@example.com"}] + + self.login(self.staff) + with mock.patch(ACCOUNT_LOOKUP, stored_under_a_name_written_further_apart): + response = self.client.get(self.detail_url("owner-caller ")) + assert response.status_code == status.HTTP_200_OK + assert response.data == {"username": "owner-caller", "email": "owner-caller@example.com"} + + def test_a_member_address_the_lookup_resolves_to_nothing_is_reported_as_absent(self): + """A lookup that comes back with no account is an absent address rather than a fault.""" + self.login(self.staff) + with mock.patch(ACCOUNT_LOOKUP, lambda *args, **kwargs: []): + response = self.client.get(self.detail_url("owner-caller")) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_a_member_address_more_than_one_account_answers_to_is_refused(self): + """ + An address resolving to several accounts names none of them, so it is refused. + + Answering with one of them would hand the caller an account they did + not address, and which one it was would be settled by the order the + records came back in. + """ + def two_accounts(request, usernames=None, **kwargs): # pylint: disable=unused-argument + return [ + {"username": "owner-caller", "email": "owner-caller@example.com"}, + {"username": "Owner-Caller", "email": "second@example.com"}, + ] + + self.login(self.staff) + with mock.patch(ACCOUNT_LOOKUP, two_accounts): + response = self.client.get(self.detail_url("owner-caller ")) + envelope = assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} + + def test_a_member_address_one_of_several_accounts_is_stored_under_carries_that_one(self): + """The account stored under exactly the name addressed is the answer, in whatever order they come.""" + def two_accounts(request, usernames=None, **kwargs): # pylint: disable=unused-argument + return [ + {"username": "Owner-Caller", "email": "second@example.com"}, + {"username": "owner-caller", "email": "owner-caller@example.com"}, + ] + + self.login(self.staff) + with mock.patch(ACCOUNT_LOOKUP, two_accounts): + response = self.client.get(self.detail_url("owner-caller")) + assert response.status_code == status.HTTP_200_OK + assert response.data == {"username": "owner-caller", "email": "owner-caller@example.com"} + def test_a_caller_reads_their_own_account_by_name(self): self.login(self.owner) response = self.client.get(self.detail_url("owner-caller")) diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 5e28494ea956..c49e1734e005 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -141,6 +141,11 @@ #: The member of the account collection that addresses the caller's own account. OWN_ACCOUNT_IDENTIFIER = "me" +#: What a caller is told about a member address that more than one account +#: answers to. One account is addressed there, so an address several of them +#: answer to names none of them in particular. +AMBIGUOUS_ACCOUNT_ADDRESS = "More than one account answers to this address. Name one of them as it is stored." + #: The account actions that answer with an account, and so read the parameters #: that shape one. SHAPED_ACCOUNT_ACTIONS = ("list", "retrieve", "partial_update") @@ -389,6 +394,26 @@ def _ordering_param(sort_fields, default): ) +def _the_one_addressed(username, records, name_of): + """ + Return the one of these records the address names, or refuse the address. + + A name can be answered with more than one record, in which case the record + stored under exactly the name given is the one addressed. Where none of + them is stored under it the address names no one of them, so it is refused + rather than worked on: which record came back first is no basis for + reading or changing an account. + """ + stored_under_it = [record for record in records if name_of(record) == username] + if stored_under_it: + return stored_under_it[0] + if len(records) > 1: + raise ValidationError({api_settings.NON_FIELD_ERRORS_KEY: [AMBIGUOUS_ACCOUNT_ADDRESS]}) + if not records: + raise NotFound + return records[0] + + def _user_named(username): """Return the user an address names, or refuse the address.""" try: @@ -965,11 +990,11 @@ def list(self, request): def retrieve(self, request, username): """Return one account, shaped as the caller asked.""" - account = self._accounts_named( + account = self._account_addressed( request, - [self._addressed_username(request, username)], + self._addressed_username(request, username), request.query_params.get(VIEW_PARAM), - )[0] + ) return Response(self.shape(account, request)) def partial_update(self, request, username): @@ -994,9 +1019,9 @@ def partial_update(self, request, username): try: with transaction.atomic(): update_account_settings(request.user, changes, username=username) - account = self._accounts_named( - request, [username], request.query_params.get(VIEW_PARAM), - )[0] + account = self._account_addressed( + request, username, request.query_params.get(VIEW_PARAM), + ) except UserNotAuthorized as exc: raise PermissionDenied from exc except UserNotFound as exc: @@ -1018,30 +1043,40 @@ def _accounts_named(self, request, usernames, preset=None): names = list(usernames) if not names: return [] - try: - found = get_account_settings(request, names, view=preset if preset == SHARED_VIEW else None) - except UserNotFound as exc: - raise NotFound from exc + found = self._accounts_found(request, names, preset) # The accounts come back in the order the database returned them, which - # is not the order of the page they were selected for. Each name is - # matched to its account by the name that account stores, and failing - # that by its case-folded form: the database decides which names a - # selection matches, and the collation MySQL applies to these columns - # by default matches names differing only in case, so an account can - # come back stored under a spelling other than the one asked for. + # is not the order of the page they were selected for, so each is put + # back under the name it is stored as. Which stored names a selection + # resolves to is the database's decision and need not be the names it + # was given, so an account none of those names is written as is carried + # at the end of the page rather than left out of it. by_name = {account["username"]: account for account in found} - folded = {} - for stored, account in by_name.items(): - folded.setdefault(stored.casefold(), account) - ordered = [] - for name in names: - account = by_name.get(name) - if account is None: - account = folded.get(name.casefold()) - if account is not None: - ordered.append(account) + claimed = {name for name in names if name in by_name} + ordered = [by_name[name] for name in names if name in by_name] + ordered.extend(account for account in found if account["username"] not in claimed) return ordered + def _account_addressed(self, request, username, preset=None): + """ + Return the one account a member address names, as this caller may see it. + + The lookup settles which stored account an address names, so the + account it comes back with is the answer here whatever name that + account is stored under. An address the lookup comes back from with + several accounts and none of them stored under exactly the name given + names no one of them, so it is refused rather than answered with + whichever of them came back first. + """ + found = self._accounts_found(request, [username], preset) + return _the_one_addressed(username, found, lambda account: account["username"]) + + def _accounts_found(self, request, names, preset): + """Return the accounts the lookup comes back with for these names.""" + try: + return get_account_settings(request, names, view=preset if preset == SHARED_VIEW else None) + except UserNotFound as exc: + raise NotFound from exc + def _selected_usernames(self, request, selection): """Return the usernames the selectors name, in the order the page carries them.""" return usernames_among( From c9be2069896348c95955ab9e012411ae8e0f119f Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 20:09:18 +0500 Subject: [PATCH 13/61] fix: answer every account holding a selected email address The account collection selects by the email address of an owner with a lookup that takes one record and refuses to answer at all where there is more than one. Nothing in the user model keeps one address to one account, so a staff caller looking up an address two accounts hold was answered 500, with nothing in the answer to say why. The superseded address fails the same way, so this was carried forward rather than introduced. The selector now names every account holding the address, and the page carries them all. A collection is what this address answers, and a page of the accounts holding an address is already what the search over addresses beside it answers with, so the page is the answer here whether the address is held once or several times. An address no account holds still leaves the page empty. Tests: the selector asked for an address two accounts hold, and the collection read by a staff caller for the same address, asserting both accounts in the page. Both fail against the previous code, the second with the 500 this corrects. --- .../core/djangoapps/user_api/v2/selectors.py | 15 +++++++++------ .../user_api/v2/tests/test_account_views.py | 18 ++++++++++++++++++ .../user_api/v2/tests/test_selectors.py | 11 ++++++++--- openedx/core/djangoapps/user_api/v2/views.py | 17 +++++++++-------- 4 files changed, 44 insertions(+), 17 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/selectors.py b/openedx/core/djangoapps/user_api/v2/selectors.py index 096a7d6eed46..913416cce46d 100644 --- a/openedx/core/djangoapps/user_api/v2/selectors.py +++ b/openedx/core/djangoapps/user_api/v2/selectors.py @@ -32,12 +32,15 @@ def usernames_among(names, ordering): ) -def username_holding_email(email): - """Return the name of the account holding this address, or ``None`` when no account holds it.""" - try: - return User.objects.get(email=email).username - except User.DoesNotExist: - return None +def usernames_holding_email(email): + """ + Return the names of the accounts holding this address. + + Nothing keeps one email address to one account, so an address can be held + by more than one of them. Every account holding it is named, and nothing + is named for an address no account holds. + """ + return list(accounts_holding_emails([email]).values_list("username", flat=True)) def username_holding_id(identifier): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index ceee3bd9f957..cab4f529a91e 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -462,6 +462,24 @@ def test_the_selectors_a_learner_may_not_use_are_the_ones_the_privilege_is_asked assert documented == {"email", "lms_user_id"} assert set(ACCOUNT_CONTACT_SELECTORS) == documented + def test_a_staff_caller_selecting_an_address_more_than_one_account_holds_receives_them_all(self): + """ + A page carries every account holding the address it was given. + + Nothing keeps one email address to one account, so an address can be + held by more than one of them. The page of accounts holding an address + is what the search over addresses answers with as well, and it is the + answer here whether the address is held once or several times. + """ + UserFactory.create( + username="owner-second", email="owner-caller@example.com", password=PASSWORD, + ) + self.login(self.staff) + response = self.client.get(self.list_url, {"email": "owner-caller@example.com"}) + assert response.status_code == status.HTTP_200_OK, response.content + assert response.data["count"] == 2 + assert self.usernames_in(response) == ["owner-caller", "owner-second"] + def test_a_learner_may_not_select_by_email_address(self): self.login(self.owner) response = self.client.get(self.list_url, {"email": "other-caller@example.com"}) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py b/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py index c8ea8a1ed190..e98aa70c86e7 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py @@ -10,8 +10,8 @@ from openedx.core.djangoapps.user_api.v2.selectors import ( accounts_holding_emails, cancellable_retirement_for_email, - username_holding_email, username_holding_id, + usernames_holding_email, usernames_among, ) from openedx.core.djangolib.testing.utils import skip_unless_lms @@ -52,10 +52,15 @@ def test_no_names_select_no_accounts(self): assert not list(usernames_among([], "username")) def test_the_account_holding_one_address_is_named(self): - assert username_holding_email("second@example.com") == "second-holder" + assert usernames_holding_email("second@example.com") == ["second-holder"] def test_no_account_holds_an_unregistered_address(self): - assert username_holding_email("nobody@example.com") is None + assert usernames_holding_email("nobody@example.com") == [] + + def test_every_account_holding_one_address_is_named(self): + """Nothing keeps one address to one account, so an address can be held by several.""" + UserFactory.create(username="also-second", email="second@example.com") + assert usernames_holding_email("second@example.com") == ["also-second", "second-holder"] def test_the_account_holding_one_identifier_is_named(self): assert username_holding_id(self.second.id) == "second-holder" diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index c49e1734e005..d5f23578751c 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -51,9 +51,9 @@ from .selectors import ( accounts_holding_emails, cancellable_retirement_for_email, - username_holding_email, username_holding_id, usernames_among, + usernames_holding_email, ) from .serializers import ( ACCOUNT_DEFAULT_SORT, @@ -782,10 +782,12 @@ def _shareable_account_fields(): list=extend_schema( summary="List accounts", description=( - "Returns a page of accounts. Name them with `username`, or select the one holding an " - "`email` address or an `lms_user_id`; omit all three to receive your own account. A " - "name, an address or an identifier no account holds is left out of the page, which is " - "empty when nothing given is held. Each account carries the properties the caller may " + "Returns a page of accounts. Name them with `username`, or select the accounts " + "holding an `email` address or the one holding an `lms_user_id`; omit all three to " + "receive your own account. A name, an address or an identifier no account holds is " + "left out of the page, which is empty when nothing given is held. An address held by " + "more than one account brings back each of them. " + "Each account carries the properties the caller may " "see: everything for your own account and for a staff caller, and otherwise the " "properties its owner shares. " "A property named in `fields` that an owner does not share is left out of their " @@ -1107,11 +1109,10 @@ def _selected_names(self, request, selection): return [request.user.username] def _usernames_holding_email(self, email): - """Return the account holding this address, and nothing when none does.""" + """Return the accounts holding this address, by name, and nothing when none does.""" if is_email_retired(email): raise self._retired_account(email) - username = username_holding_email(email) - return [username] if username is not None else [] + return usernames_holding_email(email) def _usernames_holding_identifier(self, identifier): """Return the account holding this numeric identifier, and nothing when none does.""" From d54e8fd82b2bc8055507ef11f0523a21b5b6c87b Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 20:27:44 +0500 Subject: [PATCH 14/61] fix: admit an operation on one account by the rules of the account resource The accounts are one collection however many addresses reach into them, and six operations that read or change a row of it were served by views standing apart from it: the identity verification summary and attempts, the preference document and one preference of it, and setting and clearing the image, each declaring a flat list of classes of its own, none of them reading what the account resource admits a caller by. A rule declared for that resource therefore did not reach them. Measured with a rule admitting nobody added to the resource: the account read answered 403 while the summary, the attempts and the preferences answered 200, one preference and an upload reached their handlers, and clearing the image answered 204 and cleared the stored image -- a change to an account carried out while every read of the same account was refused. Deactivating an account read nothing of the resource either. The classes the resource admits a caller by are now declared once and carried by every address that works on one of its accounts, which applies them first and the classes of its own address after. The same measurement now refuses all eight, and the stored image is left alone. The declaration is read from the shared tuple rather than from the collection's own attribute because that attribute is added to in place by the first request to reach a view that reads a token, which would otherwise make admission depend on which addresses a process had served already. The account an address names is resolved through the resource as well, by one rule: the record stored under exactly the name given, or the single record the name came back with, and otherwise a refusal. Three operations resolved the record they write to with a lookup that takes one record and fails outright on more, each catching only the not-found case, while the class in front of them had settled the question on the name as text. Making a password unusable, confirming a profile name and recording an image can therefore no longer land on a record nobody addressed: each is refused with 400 and writes nothing. Recording an image is looked up again by the writing helper, which this version does not own, so the refusal is raised where that lookup comes back with more than one record. The preference addresses keep their own two-tier rule -- a read of somebody else's is a privilege, a change of it belongs to the owner -- and declare it through the hook the shared gate calls, so both tiers still apply and the resource's rules apply before them. One test outside this version's own modules moves with it: the preference guard harness handed a bare request to classes that are given the wrapped one by the view, and the classes carried in from the resource read the request through it, so the harness now authenticates the request the way the test client does. Tests: every read and every change of one account measured twice, once as they stand and once with a rule admitting nobody added to the resource, with the stored image asserted untouched after the refusal; a deactivation refused with the privilege for it held, so that the refusal measured is the resource's; and each of the three write targets, refused when the address names no one account and landing on the account stored under the name when it does. Removing the shared gate from the four views, or emptying the shared declaration, turns the refusal tests red. --- .../djangoapps/profile_images/v2/views.py | 18 +- .../core/djangoapps/user_api/v2/selectors.py | 11 + .../user_api/v2/tests/test_account_views.py | 219 ++++++++++++++++++ .../v2/tests/test_name_change_views.py | 65 ++++++ openedx/core/djangoapps/user_api/v2/views.py | 69 +++++- 5 files changed, 371 insertions(+), 11 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index 2efcc5a55d03..fc285cfa0496 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -7,6 +7,7 @@ from zoneinfo import ZoneInfo import piexif +from django.core.exceptions import MultipleObjectsReturned from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser @@ -16,12 +17,14 @@ from rest_framework.exceptions import NotFound, ValidationError from rest_framework.parsers import FormParser, MultiPartParser from rest_framework.response import Response +from rest_framework.settings import api_settings from rest_framework.views import APIView from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names, set_has_profile_image from openedx.core.djangoapps.user_api.errors import UserNotFound from openedx.core.djangoapps.user_api.v2.errors import CatalogedRequestErrorsMixin from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser +from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS, AccountResourceMixin from openedx.core.djangoapps.user_api.v2.serializers import ErrorResponse from openedx.core.djangoapps.user_api.v2.view_utils import ( RESP_UNAUTHENTICATED, @@ -106,6 +109,7 @@ def get_filename(self, stream, media_type, parser_context): class ProfileImageView( StandardizedErrorMixin, CatalogedRequestErrorsMixin, + AccountResourceMixin, StrictQueryParametersMixin, APIView, ): @@ -241,12 +245,24 @@ def _read_image(self, username, uploaded_file): uploaded_file.seek(0) def _record_image(self, username, is_uploaded): - """Record on the account whether it carries an image of its own.""" + """ + Record on the account whether it carries an image of its own. + + The account is looked up again by the name in the address to record + this, and a name that answers for more than one account settles on + none of them, so nothing is recorded and the request is refused rather + than written to whichever account came back. + """ uploaded_at = datetime.datetime.now(ZoneInfo("UTC")) if is_uploaded else None try: set_has_profile_image(username, is_uploaded, uploaded_at) except UserNotFound as exc: raise NotFound from exc + except MultipleObjectsReturned as exc: + log.info("Profile image not recorded for %r: the name answers for more than one account", username) + raise ValidationError({ + api_settings.NON_FIELD_ERRORS_KEY: [AMBIGUOUS_ACCOUNT_ADDRESS], + }) from exc def _unusable_image(self, username, message, reason): """Return the refusal telling the caller what the site cannot do with this image.""" diff --git a/openedx/core/djangoapps/user_api/v2/selectors.py b/openedx/core/djangoapps/user_api/v2/selectors.py index 913416cce46d..d4c75611b71a 100644 --- a/openedx/core/djangoapps/user_api/v2/selectors.py +++ b/openedx/core/djangoapps/user_api/v2/selectors.py @@ -14,6 +14,17 @@ def accounts_holding_emails(emails): return User.objects.filter(email__in=emails).order_by("username") +def accounts_named(name): + """ + Return the accounts this name addresses. + + The database settles which stored names an address answers to, and it need + not be only the one written exactly as the address writes it, so a name + can bring back more than one account. + """ + return list(User.objects.filter(username=name)) + + def usernames_among(names, ordering): """ Return the names these accounts are stored under, in the order asked for. diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index cab4f529a91e..98808cfbbc9f 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -13,6 +13,7 @@ from edx_rest_framework_extensions.scoping import FullScopePolicy from edx_rest_framework_extensions.testing import assert_error_envelope from rest_framework import status +from rest_framework.permissions import BasePermission from rest_framework.test import APITestCase from waffle.testutils import override_switch @@ -30,6 +31,7 @@ from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory from openedx.core.djangoapps.user_api.v2.permissions import ACCOUNT_CONTACT_SELECTORS from openedx.core.djangoapps.user_api.v2.serializers import ACCOUNT_DEFAULT_SORT, AccountQuerySerializer +from openedx.core.djangoapps.user_api.v2 import views from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS, EmailSearchViewSet from openedx.core.djangoapps.user_authn.views.password_reset import PasswordResetFormNoActive from openedx.core.djangolib.testing.utils import skip_unless_lms @@ -83,6 +85,23 @@ #: test that stands in for the database answers it from here. ACCOUNT_LOOKUP = "openedx.core.djangoapps.user_api.v2.views.get_account_settings" +class RefusesEveryCaller(BasePermission): + """A rule that admits nobody, added to a declaration to see how far it reaches.""" + + def has_permission(self, request, view): + """Refuse every caller.""" + return False + + +def refusing_account_resource(): + """Add a rule admitting nobody to the classes the account resource is read with.""" + return mock.patch.object( + views, + "ACCOUNT_RESOURCE_PERMISSIONS", + (*views.ACCOUNT_RESOURCE_PERMISSIONS, RefusesEveryCaller), + ) + + def counting_cache(location): """ Return a cache that counts what it is given, under a name of its own. @@ -1988,6 +2007,206 @@ def test_the_longest_search_allowed_fits_in_the_largest_page_a_caller_may_ask_fo assert response.data["next"] is None +@skip_unless_lms +class AccountWriteTargetTests(AccountApiV2TestCase): + """ + A change whose address names no one account is refused rather than written somewhere. + + What an address resolves to is the database's answer, and more than one + account can come back for one name. The record the work lands on is + settled from that answer rather than taken as the first of it, so a change + either lands on the account the address names or on nothing at all. The + test database resolves a name only to the record stored under exactly it, + so the lookups are answered here the way they answer where a name resolves + more widely. + """ + + def setUp(self): + super().setUp() + self.deactivator = UserFactory.create(username="target-deactivator", password=PASSWORD) + self.deactivator.user_permissions.add( + PermissionFactory( + codename="can_deactivate_users", + content_type=ContentTypeFactory(app_label="student"), + ), + ) + self.owner.profile.profile_image_uploaded_at = datetime.datetime.now(datetime.UTC) + self.owner.profile.save() + + def test_a_deactivation_whose_address_names_more_than_one_account_deactivates_none(self): + address = reverse("user_v2:account_deactivation", kwargs={"username": self.owner.username}) + self.login(self.deactivator) + with mock.patch( + "openedx.core.djangoapps.user_api.v2.views.accounts_named", + lambda name: [self.other, self.staff], + ): + envelope = assert_error_envelope( + self.client.post(address), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} + for user in (self.owner, self.other, self.staff): + user.refresh_from_db() + assert user.has_usable_password(), user.username + + def test_a_deactivation_lands_on_the_account_stored_under_the_name_addressed(self): + address = reverse("user_v2:account_deactivation", kwargs={"username": self.owner.username}) + self.login(self.deactivator) + with mock.patch( + "openedx.core.djangoapps.user_api.v2.views.accounts_named", + lambda name: [self.other, self.owner], + ): + assert self.client.post(address).status_code == status.HTTP_204_NO_CONTENT + self.owner.refresh_from_db() + self.other.refresh_from_db() + assert not self.owner.has_usable_password() + assert self.other.has_usable_password() + + def test_an_image_whose_address_names_more_than_one_account_is_left_alone(self): + """ + The image is recorded against the account the address names, or against none. + + The record it is written to is resolved again by the name in the + address when it is written, so a name that answers for more than one + account is refused there and the stored image is left as it stands. + """ + address = reverse( + "user_v2:account_profile_image", kwargs={"username": self.owner.username}, + ) + self.login(self.owner) + with mock.patch( + "openedx.core.djangoapps.profile_images.v2.views.set_has_profile_image", + side_effect=UserProfile.MultipleObjectsReturned, + ): + envelope = assert_error_envelope( + self.client.delete(address), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} + self.owner.profile.refresh_from_db() + assert self.owner.profile.has_profile_image is True + + +@skip_unless_lms +class AccountResourceGateTests(AccountApiV2TestCase): + """ + A rule the account resource admits a caller by reaches every operation on an account. + + The accounts are one collection however many addresses reach into them, so + a rule declared for the resource has to be applied by every operation that + reads or changes one of its accounts, wherever that operation is served + from. Each one is measured twice: once as it stands, and once with a rule + that admits nobody added to the resource's declaration, which every one of + them must then refuse. Measuring both ways is what makes the second + measurement an answer about the rule rather than about the address. + """ + + def setUp(self): + super().setUp() + self.owner.profile.profile_image_uploaded_at = datetime.datetime.now(datetime.UTC) + self.owner.profile.save() + self.deactivator = UserFactory.create(username="gate-deactivator", password=PASSWORD) + self.deactivator.user_permissions.add( + PermissionFactory( + codename="can_deactivate_users", + content_type=ContentTypeFactory(app_label="student"), + ), + ) + + def reads(self): + """Return each read of one account, by the address it is sent to.""" + name = self.owner.username + return { + "the account": lambda: self.client.get(self.detail_url(name)), + "the verification summary": lambda: self.client.get( + reverse("user_v2:account_verification_status", kwargs={"username": name}), + ), + "the verification attempts": lambda: self.client.get( + reverse("user_v2:account_verification_list", kwargs={"username": name}), + ), + } + + def writes(self): + """Return each change to one account, by the address it is sent to.""" + name = self.owner.username + return { + "the image": lambda: self.client.post( + reverse("user_v2:account_profile_image", kwargs={"username": name}), + ), + "the stored image": lambda: self.client.delete( + reverse("user_v2:account_profile_image", kwargs={"username": name}), + ), + } + + def has_image(self): + """Return whether the account carries an image of its own.""" + self.owner.profile.refresh_from_db() + return self.owner.profile.has_profile_image + + def test_every_read_of_one_account_is_answered_while_the_resource_admits_the_caller(self): + self.login(self.owner) + for case, send in self.reads().items(): + assert send().status_code == status.HTTP_200_OK, case + + def test_a_rule_the_resource_refuses_every_caller_by_refuses_every_read_of_one_account(self): + self.login(self.owner) + with refusing_account_resource(): + for case, send in self.reads().items(): + assert_error_envelope( + send(), expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_every_change_to_one_account_reaches_its_handler_while_the_resource_admits_the_caller(self): + """ + The handler is reached, which is what the refusal below is measured against. + + A change is sent here as a caller sends it wrong, so that what is + measured is the request reaching the handler rather than the change + itself: an upload carrying no image is refused by the handler, and + clearing the image is carried out. + """ + self.login(self.owner) + answers = {case: send() for case, send in self.writes().items()} + assert answers["the image"].status_code == status.HTTP_400_BAD_REQUEST + assert answers["the stored image"].status_code == status.HTTP_204_NO_CONTENT + assert self.has_image() is False + + def test_a_rule_the_resource_refuses_every_caller_by_refuses_every_change_to_one_account(self): + """A change refused by the resource leaves the account as it stands.""" + self.login(self.owner) + with refusing_account_resource(): + for case, send in self.writes().items(): + assert_error_envelope( + send(), expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + assert self.has_image() is True + + def test_a_rule_the_resource_refuses_every_caller_by_refuses_a_deactivation(self): + """ + The privilege to deactivate is held and the resource still decides. + + The caller holds the privilege this address asks for, so the refusal + measured here is the resource's rather than that privilege's, and the + password is still usable afterwards. + """ + address = reverse("user_v2:account_deactivation", kwargs={"username": self.owner.username}) + self.login(self.deactivator) + with refusing_account_resource(): + assert_error_envelope( + self.client.post(address), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + self.owner.refresh_from_db() + assert self.owner.has_usable_password() + + assert self.client.post(address).status_code == status.HTTP_204_NO_CONTENT + self.owner.refresh_from_db() + assert not self.owner.has_usable_password() + + @skip_unless_lms class AccountDeactivationTests(AccountApiV2TestCase): """POST /api/user/v2/accounts/{username}/deactivation/""" diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py index 8ff088720cf2..b3e7f89b1956 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py @@ -1,5 +1,7 @@ """Tests for the version 2 User API profile name change views.""" +from unittest import mock + import pytest from django.urls import reverse from edx_rest_framework_extensions.testing import assert_error_envelope @@ -9,6 +11,7 @@ from common.djangoapps.student.models import PendingNameChange from common.djangoapps.student.tests.factories import UserFactory from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user +from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS from openedx.core.djangolib.testing.utils import skip_unless_lms PASSWORD = "Password1234" @@ -398,6 +401,68 @@ def test_an_unknown_query_parameter_is_refused(self): assert self.profile_name(self.owner) == "Original Name" +@skip_unless_lms +class NameChangeAmbiguousTargetTests(NameChangeTestCase): + """A confirmation whose address names no one account changes no profile.""" + + def setUp(self): + super().setUp() + PendingNameChange.objects.create( + user=self.owner, new_name="Jon Doe", rationale="asked for in a test", + ) + self.url = self.confirmation_url(self.owner.username) + + def test_an_address_naming_more_than_one_account_changes_nothing(self): + """ + The profile the work lands on is the one the address names, or none at all. + + What the address resolves to is the database's answer, and more than + one account can come back for one name. Writing to whichever came back + first would put a name on an account nobody addressed, so the request + is refused and both profiles are left as they stand. The test database + resolves a name only to the record stored under exactly it, so the + lookup is answered here the way it answers where a name resolves more + widely. + """ + sibling = UserFactory.create( + username="name-sibling", email="name-sibling@example.com", password=PASSWORD, + ) + sibling.profile.name = "Sibling Name" + sibling.profile.save() + self.login(self.staff) + with mock.patch( + "openedx.core.djangoapps.user_api.v2.views.accounts_named", + lambda name: [sibling, self.other], + ): + envelope = assert_error_envelope( + self.client.post(self.url), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} + assert self.profile_name(self.owner) == "Original Name" + assert self.pending_name(self.owner) == "Jon Doe" + sibling.profile.refresh_from_db() + assert sibling.profile.name == "Sibling Name" + + def test_the_account_stored_under_the_name_addressed_is_the_one_changed(self): + """Among several, the account stored under exactly the name addressed is the one written to.""" + sibling = UserFactory.create( + username="name-sibling", email="name-sibling@example.com", password=PASSWORD, + ) + sibling.profile.name = "Sibling Name" + sibling.profile.save() + self.login(self.staff) + with mock.patch( + "openedx.core.djangoapps.user_api.v2.views.accounts_named", + lambda name: [sibling, self.owner], + ): + assert self.client.post(self.url).status_code == status.HTTP_204_NO_CONTENT + assert self.profile_name(self.owner) == "Jon Doe" + sibling.profile.refresh_from_db() + assert sibling.profile.name == "Sibling Name" + + @skip_unless_lms class NameChangeParityTests(NameChangeTestCase): """The same requests through the version 1 and the version 2 addresses.""" diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index d5f23578751c..fffaf2baa70d 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -50,6 +50,7 @@ from .schema import ResponseShapes from .selectors import ( accounts_holding_emails, + accounts_named, cancellable_retirement_for_email, username_holding_id, usernames_among, @@ -416,10 +417,7 @@ def _the_one_addressed(username, records, name_of): def _user_named(username): """Return the user an address names, or refuse the address.""" - try: - return User.objects.get(username=username) - except User.DoesNotExist as exc: - raise NotFound from exc + return _the_one_addressed(username, accounts_named(username), lambda user: user.username) class _MemberLookupMixin: @@ -777,6 +775,57 @@ def _shareable_account_fields(): return set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["custom_shareable_fields"]) +#: The classes every operation on an account admits a caller by, wherever it is +#: served from. The account collection declares this tuple and every address +#: that works on one of its accounts carries it, so the rules of the resource +#: are declared once rather than restated by each address that reaches into it. +#: It is read from here rather than from the collection's own attribute because +#: that attribute is added to in place, by the first request to reach a view +#: that reads a token, and admission must not depend on which addresses a +#: process has served already. +ACCOUNT_RESOURCE_PERMISSIONS = ( + permissions.IsAuthenticated, + CanGetAccountInfo, + CanSelectAccountsByContact, +) + + +class AccountResourceMixin: + """ + Carries the rules of the account resource into the operations on one account. + + An address beneath an account works on a row of the collection the account + resource answers from, so a caller that resource refuses is a caller the + operation refuses too: the classes the resource declares are applied first + and the ones this address declares after, which keeps an address reached + this way from standing open to a caller the resource is closed to. The + account the address names is resolved here as well, so the record a + permission settled the request on is the record the work lands on. + """ + + def account_resource_permissions(self): + """Return the classes the account resource admits a caller by.""" + return ACCOUNT_RESOURCE_PERMISSIONS + + def declared_permissions(self): + """Return the classes the address being served declares of its own.""" + return super().get_permissions() + + def get_permissions(self): + """Return the collection's classes, then the ones this address declares.""" + declared = self.declared_permissions() + already_carried = {type(permission) for permission in declared} + carried = [ + permission() for permission in self.account_resource_permissions() + if permission not in already_carried + ] + return carried + declared + + def addressed_account(self): + """Return the account this address names, refusing an address that names no one account.""" + return _user_named(self.kwargs["username"]) + + @extend_schema(tags=[SDK_TAG]) @extend_schema_view( list=extend_schema( @@ -847,6 +896,7 @@ class AccountViewSet( StandardizedErrorMixin, CatalogedRequestErrorsMixin, ErrorExtensionsMixin, + AccountResourceMixin, _ActionAddressMixin, _ResponsePresetMixin, StrictQueryParametersMixin, @@ -893,11 +943,7 @@ class AccountViewSet( # pair is built on, named here because a view declaring its own classes is # not one that pair serves. authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser) - permission_classes = ( - permissions.IsAuthenticated, - CanGetAccountInfo, - CanSelectAccountsByContact, - ) + permission_classes = ACCOUNT_RESOURCE_PERMISSIONS #: A change is a merge patch: a body in any other media type is refused. parser_classes = (MergePatchParser,) serializer_class = AccountSerializer @@ -1193,6 +1239,7 @@ def _failed_change(self, username, error): class AccountDeactivationView( StandardizedErrorMixin, CatalogedRequestErrorsMixin, + AccountResourceMixin, StrictQueryParametersMixin, APIView, ): @@ -1213,7 +1260,7 @@ class AccountDeactivationView( def post(self, request, username): """Make the password of the named account unusable and record it as disabled.""" - user = _user_named(username) + user = self.addressed_account() segment.identify(user.id, {"is_disabled": "true"}) user.set_unusable_password() user.save() @@ -1454,6 +1501,7 @@ def _verification_sort_key(attempt): class IDVerificationStatusView( StandardizedErrorMixin, CatalogedRequestErrorsMixin, + AccountResourceMixin, StrictQueryParametersMixin, APIView, ): @@ -1537,6 +1585,7 @@ def get(self, request, username): class IDVerificationViewSet( StandardizedErrorMixin, CatalogedRequestErrorsMixin, + AccountResourceMixin, StrictQueryParametersMixin, IterablePaginationMixin, viewsets.ViewSet, From da426237bffca552447f28ef2552091dd79acd15 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 20:31:12 +0500 Subject: [PATCH 15/61] fix: describe each address by the body and the media types it reads The answer to an OPTIONS request is built from the parsers and the serializer declared on the view, which belong to the view rather than to the address being asked about, and two addresses of this version were described wrongly because of it. The preference document of one account is read and changed as a merge patch and a body in any other media type is refused, which is what the published document says of it. The description of that address named the three media types the platform reads bodies in everywhere else and left out the one it takes, because the parsers follow the action being served and the action recorded for this question is not the change. A caller negotiating from the description -- the one mechanism offered for it -- therefore sent a body in a media type the address refuses and was answered 415, with the two published descriptions of one address contradicting each other. The parsers now follow the methods the address serves, and the description reports the ones it would read a body with. Confirming a requested profile name carries out the change already asked for and reads no body, which is what the published operation says. The description of that address offered a body with a required name in it, built from the view's serializer, so a client or a form driven by it asked the operator for a name before confirming the change and sent a body the address ignores. An action that reads no body is now declared as such and no body is described for it. The address that asks for a name still describes the one it takes. Tests: the media types named by each preference address, a change sent in every media type the document address names being carried out, no body described for a confirmation, and the body still described for asking. Each fails against the previous code, the negotiated change with the 415 this corrects, and each half of the description turns its own tests red when taken back off. --- .../v2/tests/test_name_change_views.py | 33 ++++++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 38 +++++++++++++++++++ 2 files changed, 71 insertions(+) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py index b3e7f89b1956..bb62d4a2fb21 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py @@ -401,6 +401,39 @@ def test_an_unknown_query_parameter_is_refused(self): assert self.profile_name(self.owner) == "Original Name" +@skip_unless_lms +class NameChangeAddressDescriptionTests(NameChangeTestCase): + """What OPTIONS answers about the addresses that ask for and confirm a name.""" + + def setUp(self): + super().setUp() + PendingNameChange.objects.create( + user=self.owner, new_name="Jon Doe", rationale="asked for in a test", + ) + self.url = self.confirmation_url(self.owner.username) + + def test_the_confirmation_address_describes_no_body(self): + """ + A confirmation carries out the change already asked for, so there is nothing to send. + + A client or a form built from this description would otherwise ask the + operator for a name before confirming the change, and send a body the + address does not read. + """ + self.login(self.staff) + answer = self.client.options(self.url) + assert answer.status_code == status.HTTP_200_OK + assert "actions" not in answer.json() + + def test_asking_for_a_name_is_still_described_by_the_body_it_takes(self): + """The collection reads a body, and the description of it is not what the above removes.""" + self.login(self.owner) + answer = self.client.options(self.request_url) + assert answer.status_code == status.HTTP_200_OK + assert set(answer.json()["actions"]["POST"]) == {"name"} + assert answer.json()["actions"]["POST"]["name"]["required"] is True + + @skip_unless_lms class NameChangeAmbiguousTargetTests(NameChangeTestCase): """A confirmation whose address names no one account changes no profile.""" diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index fffaf2baa70d..76081a952f41 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -21,6 +21,7 @@ from rest_framework.decorators import action from rest_framework.exceptions import APIException, NotFound, PermissionDenied, Throttled, ValidationError from rest_framework.parsers import JSONParser +from rest_framework.metadata import SimpleMetadata from rest_framework.response import Response from rest_framework.reverse import reverse from rest_framework.settings import api_settings @@ -188,6 +189,37 @@ ) +class AddressMetadata(SimpleMetadata): + """ + Describes an address by what it reads, rather than by what its view declares. + + The standard description is built from the parsers and the serializer + declared on the view, which belong to the view as a whole rather than to + the address being asked about: an address that reads one media type is + otherwise described as reading every media type the platform reads + anywhere, and a method whose handler reads no body is described as taking + the one the view's serializer carries. A caller that negotiates from this + description sends what it was told to send, so each half of it is answered + from the address and the method being described. + """ + + def determine_metadata(self, request, view): + """Describe the address, naming the media types the bodies it takes are read in.""" + description = super().determine_metadata(request, view) + description["parses"] = [parser.media_type for parser in view.get_parsers()] + return description + + def determine_actions(self, request, view): + """Describe the body of each method that takes one, and leave out the methods that take none.""" + described = super().determine_actions(request, view) + served = getattr(view, "action_map", None) or {} + bodiless = set(getattr(view, "bodiless_actions", ())) + return { + method: fields for method, fields in described.items() + if served.get(method.lower()) not in bodiless + } + + def _ordering_param(sort_fields, default): """Build the sort parameter of a list, naming the fields it accepts.""" return query_param( @@ -1407,6 +1439,12 @@ class NameChangeViewSet( permission_classes = (permissions.IsAuthenticated,) serializer_class = NameChangeSerializer + #: Describes each address by the body and the media types it reads. + metadata_class = AddressMetadata + #: The actions whose handler reads no body, which their address describes + #: none for. Confirming a change carries out the one already asked for, so + #: there is nothing for a caller to send. + bodiless_actions = ("confirmations",) lookup_field = "username" # The router's default lookup pattern excludes dots, which usernames allow. lookup_value_regex = settings.USERNAME_REGEX_PARTIAL From d02caae7a9fdd8e478927a1cce0a52b624d4f0d5 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 20:37:08 +0500 Subject: [PATCH 16/61] docs: record where the retirement of a re-used address is read differently An address can have been held and left more than once, so more than one retirement of it can sit inside the cooling-off period. This version reports the most recent, being the only one a caller could still undo; the superseded version reads the same window with a lookup that takes a single record and so fails outright on the second. The window boundaries are the same in both. The selection is on a path declared to answer as the superseded one answers, and this is the one input they answer differently for, so the selector now says so where the next reader of it will be. --- .../djangoapps/profile_images/v2/views.py | 2 +- .../core/djangoapps/user_api/v2/selectors.py | 7 ++++++ .../user_api/v2/tests/test_account_views.py | 22 ++++++++++--------- .../v2/tests/test_name_change_views.py | 4 ++-- .../user_api/v2/tests/test_selectors.py | 2 +- openedx/core/djangoapps/user_api/v2/views.py | 2 +- 6 files changed, 24 insertions(+), 15 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index fc285cfa0496..6c5cb445a551 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -24,7 +24,6 @@ from openedx.core.djangoapps.user_api.errors import UserNotFound from openedx.core.djangoapps.user_api.v2.errors import CatalogedRequestErrorsMixin from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser -from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS, AccountResourceMixin from openedx.core.djangoapps.user_api.v2.serializers import ErrorResponse from openedx.core.djangoapps.user_api.v2.view_utils import ( RESP_UNAUTHENTICATED, @@ -34,6 +33,7 @@ StrictQueryParametersMixin, path_param, ) +from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS, AccountResourceMixin from openedx.core.lib.api.parsers import TypedFileUploadParser from ..exceptions import ImageValidationError diff --git a/openedx/core/djangoapps/user_api/v2/selectors.py b/openedx/core/djangoapps/user_api/v2/selectors.py index d4c75611b71a..3216134f0c71 100644 --- a/openedx/core/djangoapps/user_api/v2/selectors.py +++ b/openedx/core/djangoapps/user_api/v2/selectors.py @@ -70,6 +70,13 @@ def cancellable_retirement_for_email(email): period runs, so a retirement older than that is not reported here: the address is gone either way, and only a retirement inside the period can be undone by asking the platform to undo it. + + One address can have been held and left more than once, so more than one + retirement of it can sit inside the period. The most recent is the one + reported, being the only one still open to being undone. This is the one + place where the answer differs from the superseded version, which reads + the same window with a lookup that takes a single record and so fails + outright on the second. """ now = datetime.datetime.now(ZoneInfo("UTC")) return ( diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 98808cfbbc9f..b03db8237992 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -29,9 +29,9 @@ from openedx.core.djangoapps.user_api.accounts.utils import ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH from openedx.core.djangoapps.user_api.models import RetirementState, UserRetirementStatus from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangoapps.user_api.v2 import views from openedx.core.djangoapps.user_api.v2.permissions import ACCOUNT_CONTACT_SELECTORS from openedx.core.djangoapps.user_api.v2.serializers import ACCOUNT_DEFAULT_SORT, AccountQuerySerializer -from openedx.core.djangoapps.user_api.v2 import views from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS, EmailSearchViewSet from openedx.core.djangoapps.user_authn.views.password_reset import PasswordResetFormNoActive from openedx.core.djangolib.testing.utils import skip_unless_lms @@ -738,7 +738,7 @@ def stored_under_a_name_written_further_apart(request, usernames=None, **kwargs) def test_a_member_address_the_lookup_resolves_to_nothing_is_reported_as_absent(self): """A lookup that comes back with no account is an absent address rather than a fault.""" self.login(self.staff) - with mock.patch(ACCOUNT_LOOKUP, lambda *args, **kwargs: []): + with mock.patch(ACCOUNT_LOOKUP, return_value=[]): response = self.client.get(self.detail_url("owner-caller")) assert_error_envelope( response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", @@ -2038,7 +2038,7 @@ def test_a_deactivation_whose_address_names_more_than_one_account_deactivates_no self.login(self.deactivator) with mock.patch( "openedx.core.djangoapps.user_api.v2.views.accounts_named", - lambda name: [self.other, self.staff], + return_value=[self.other, self.staff], ): envelope = assert_error_envelope( self.client.post(address), @@ -2055,7 +2055,7 @@ def test_a_deactivation_lands_on_the_account_stored_under_the_name_addressed(sel self.login(self.deactivator) with mock.patch( "openedx.core.djangoapps.user_api.v2.views.accounts_named", - lambda name: [self.other, self.owner], + return_value=[self.other, self.owner], ): assert self.client.post(address).status_code == status.HTTP_204_NO_CONTENT self.owner.refresh_from_db() @@ -2154,9 +2154,10 @@ def test_a_rule_the_resource_refuses_every_caller_by_refuses_every_read_of_one_a self.login(self.owner) with refusing_account_resource(): for case, send in self.reads().items(): - assert_error_envelope( - send(), expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", - ) + with self.subTest(case=case): + assert_error_envelope( + send(), expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) def test_every_change_to_one_account_reaches_its_handler_while_the_resource_admits_the_caller(self): """ @@ -2178,9 +2179,10 @@ def test_a_rule_the_resource_refuses_every_caller_by_refuses_every_change_to_one self.login(self.owner) with refusing_account_resource(): for case, send in self.writes().items(): - assert_error_envelope( - send(), expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", - ) + with self.subTest(case=case): + assert_error_envelope( + send(), expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) assert self.has_image() is True def test_a_rule_the_resource_refuses_every_caller_by_refuses_a_deactivation(self): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py index bb62d4a2fb21..4321e5a49e33 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py @@ -465,7 +465,7 @@ def test_an_address_naming_more_than_one_account_changes_nothing(self): self.login(self.staff) with mock.patch( "openedx.core.djangoapps.user_api.v2.views.accounts_named", - lambda name: [sibling, self.other], + return_value=[sibling, self.other], ): envelope = assert_error_envelope( self.client.post(self.url), @@ -488,7 +488,7 @@ def test_the_account_stored_under_the_name_addressed_is_the_one_changed(self): self.login(self.staff) with mock.patch( "openedx.core.djangoapps.user_api.v2.views.accounts_named", - lambda name: [sibling, self.owner], + return_value=[sibling, self.owner], ): assert self.client.post(self.url).status_code == status.HTTP_204_NO_CONTENT assert self.profile_name(self.owner) == "Jon Doe" diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py b/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py index e98aa70c86e7..3cb4af2fbc9b 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_selectors.py @@ -11,8 +11,8 @@ accounts_holding_emails, cancellable_retirement_for_email, username_holding_id, - usernames_holding_email, usernames_among, + usernames_holding_email, ) from openedx.core.djangolib.testing.utils import skip_unless_lms diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 76081a952f41..bb5516146a9a 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -20,8 +20,8 @@ from rest_framework import permissions, status, viewsets from rest_framework.decorators import action from rest_framework.exceptions import APIException, NotFound, PermissionDenied, Throttled, ValidationError -from rest_framework.parsers import JSONParser from rest_framework.metadata import SimpleMetadata +from rest_framework.parsers import JSONParser from rest_framework.response import Response from rest_framework.reverse import reverse from rest_framework.settings import api_settings From 7da47ed44fa1b13be6942657b15b291c9e088977 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 21:22:50 +0500 Subject: [PATCH 17/61] test: guard the record-visibility layer of the two queryset-backed user collections --- .../user_api/v2/tests/test_views.py | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index e30730c11d8a..1e4b6f7cf3a6 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -3,8 +3,10 @@ import re from datetime import UTC, datetime from math import ceil +from unittest.mock import patch from django.contrib.auth.models import User # pylint: disable=imported-auth-user +from django.core.exceptions import ImproperlyConfigured from django.db import connection from django.test import SimpleTestCase from django.test.utils import CaptureQueriesContext @@ -22,6 +24,7 @@ from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory from openedx.core.djangoapps.user_api.v2.filters import UserFilterSet from openedx.core.djangoapps.user_api.v2.serializers import UserPreferenceRecordSerializer +from openedx.core.djangoapps.user_api.v2.views import UserPreferenceViewSet, UserViewSet from openedx.core.djangolib.testing.utils import skip_unless_lms PASSWORD = "Password1234" @@ -1489,3 +1492,122 @@ def test_url_is_relative_without_a_request(self): data = UserPreferenceRecordSerializer(preference).data assert data["url"] == "/api/user/v2/user_preferences/alice,pref-lang/" assert data["user"] is None + + +class RecordingScopePolicy: + """A record-visibility policy that drops one owner's rows and records each call.""" + + def __init__(self, hidden_username): + self.hidden_username = hidden_username + self.calls = [] + + def scope(self, queryset, subject): + """Return the rows of ``queryset`` that do not belong to the hidden owner.""" + self.calls.append((queryset.model, subject)) + owner_field = "username" if queryset.model is User else "user__username" + return queryset.exclude(**{owner_field: self.hidden_username}) + + +@skip_unless_lms +class QuerysetScopingSeamTests(UserApiV2TestCase): + """ + The record-visibility layer of the two collections backed by a queryset. + + Each of these collections declares a policy that decides which rows a + caller may see, and the rows it leaves out are absent from the answer + rather than refused. The policy that ships keeps every row, because only + platform administrators reach these collections at all, so these tests + put a narrowing policy in its place and read the answer: a collection + that stopped consulting its policy would hand back the rows the policy + left out, and a collection that no longer declared one would narrow + nothing whatever policy it was given. + """ + + def scoped(self, view_class, hidden_username): + """Run the view class with a policy that hides one owner's rows.""" + policy = RecordingScopePolicy(hidden_username) + return patch.object(view_class, "scoping_policy", policy, create=True), policy + + def test_user_list_leaves_out_the_rows_its_policy_excludes(self): + self.login(self.admin) + patched, policy = self.scoped(UserViewSet, "alice") + with patched: + response = self.client.get(reverse("user_v2:user_list")) + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["admin-caller", "bob", "learner-caller"] + assert policy.calls == [(User, self.admin)] + + def test_user_detail_of_an_excluded_row_is_not_found(self): + self.login(self.admin) + patched, _ = self.scoped(UserViewSet, "alice") + with patched: + response = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "alice"})) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_user_detail_of_an_included_row_is_returned(self): + self.login(self.admin) + patched, _ = self.scoped(UserViewSet, "alice") + with patched: + response = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "bob"})) + assert response.status_code == status.HTTP_200_OK + assert response.data["username"] == "bob" + + def test_preference_list_leaves_out_the_rows_its_policy_excludes(self): + self.login(self.admin) + patched, policy = self.scoped(UserPreferenceViewSet, "alice") + with patched: + response = self.client.get(reverse("user_v2:user_preference_list")) + assert response.status_code == status.HTTP_200_OK + assert [(row["username"], row["key"]) for row in response.data["results"]] == [("bob", "time_zone")] + assert policy.calls == [(UserPreference, self.admin)] + + def test_preference_detail_of_an_excluded_row_is_not_found(self): + self.login(self.admin) + patched, _ = self.scoped(UserPreferenceViewSet, "alice") + with patched: + response = self.client.get( + reverse("user_v2:user_preference_detail", kwargs={"username": "alice", "key": "pref-lang"}), + ) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + + def test_preference_detail_of_an_included_row_is_returned(self): + self.login(self.admin) + patched, _ = self.scoped(UserPreferenceViewSet, "alice") + with patched: + response = self.client.get( + reverse("user_v2:user_preference_detail", kwargs={"username": "bob", "key": "time_zone"}), + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["value"] == "UTC" + + def test_each_scoped_collection_declares_a_policy_of_its_own(self): + """ + Each of these two views names the policy that governs its rows. + + A view that inherited the default instead of naming one would be left + with no policy at all, so the declaration is read from the view's own + attributes rather than from anything it inherits. + """ + for view_class in (UserViewSet, UserPreferenceViewSet): + declared = vars(view_class).get("scoping_policy") + assert declared is not None, f"{view_class.__name__} declares no record-visibility policy" + assert callable(getattr(declared, "scope", None)), ( + f"{view_class.__name__} declares a record-visibility policy that cannot narrow rows" + ) + + def test_the_rows_are_fetched_through_the_declared_policy(self): + """ + The policy is what the rows are fetched through, not a step that can be skipped. + + A view left without a usable policy hands back no rows at all rather + than every row, which is how a collection that stopped consulting its + policy is told apart from one whose policy happens to keep every row. + """ + for view_class in (UserViewSet, UserPreferenceViewSet): + with patch.object(view_class, "scoping_policy", None, create=True): + with self.assertRaises(ImproperlyConfigured): + view_class().get_queryset() From eb6e0f2be8f82851ab486b72aaf4c15611572949 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 21:33:10 +0500 Subject: [PATCH 18/61] fix: describe each address of this version to the caller that asks, not to a maintainer --- .../djangoapps/profile_images/v2/views.py | 22 ++- .../user_api/v2/tests/test_views.py | 94 +++++++++ openedx/core/djangoapps/user_api/v2/views.py | 186 ++++++++++-------- 3 files changed, 207 insertions(+), 95 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index 6c5cb445a551..ed0100958bdb 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -116,18 +116,20 @@ class ProfileImageView( """ The image shown beside a user's name, in each size the site renders. - An account has one image, set and cleared whole and never listed or - addressed by an identifier of its own, so it is served from this single - address rather than routed as a collection. A user sets and clears the - image on their own account, and nobody else's: staff included, since - clearing an image is an account change rather than a moderation tool. That - is not what the account collection admits, which is the other reason this - is a view of its own rather than an action of that collection. The sizes - are stored under the username the address carries. The addresses those - stored sizes are served from belong to the account resource rather than to - this one. + A user sets and clears the image on their own account and nobody else's, + staff included. Setting an image replaces one already set, and clearing an + account that carries no image of its own is not an error. The addresses + the stored sizes are served from are carried by the account itself. """ + # An account has one image, set and cleared whole and never listed or + # addressed by an identifier of its own, so it is served from this one + # address rather than routed as a collection. Clearing an image is an + # account change rather than a moderation tool, so staff are not admitted + # to somebody else's; that is not what the account collection admits, + # which is the other reason this is a view of its own rather than an + # action of that collection. + # The site's own pages let a user who has not confirmed their email # address set a picture, and the platform default refuses a session # belonging to such an account. Only the session class differs in what it diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index 1e4b6f7cf3a6..812b421340fe 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -22,6 +22,7 @@ from openedx.core.djangoapps.user_api.models import UserPreference from openedx.core.djangoapps.user_api.preferences.api import get_country_time_zones from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangoapps.user_api.v2 import urls as v2_urls from openedx.core.djangoapps.user_api.v2.filters import UserFilterSet from openedx.core.djangoapps.user_api.v2.serializers import UserPreferenceRecordSerializer from openedx.core.djangoapps.user_api.v2.views import UserPreferenceViewSet, UserViewSet @@ -1611,3 +1612,96 @@ def test_the_rows_are_fetched_through_the_declared_policy(self): with patch.object(view_class, "scoping_policy", None, create=True): with self.assertRaises(ImproperlyConfigured): view_class().get_queryset() + + +def routed_view_classes(): + """Return every view class this version mounts, by the name it is routed under.""" + classes = {} + for entry in v2_urls.urlpatterns: + view_class = getattr(entry.callback, "cls", None) + if view_class is not None: + classes[view_class.__name__] = view_class + return classes + + +#: Words that name how an address is built rather than what it answers. A +#: description carrying one of these was written for somebody reading this +#: module, and the body of an OPTIONS request is not where they will read it. +IMPLEMENTATION_TERMS = ( + "ViewSet", + "queryset", + "permission_classes", + "serializer", + "filter set", + "filter backend", + "mixin", + "scoping policy", + "router", + "selectors", + "class attribute", +) + +#: The longest description an address gives of itself. The client-facing text +#: is a short paragraph; the maintainer-facing text these replaced ran to four. +DESCRIPTION_LIMIT = 700 + + +@skip_unless_lms +class AddressSelfDescriptionTests(UserApiV2TestCase): + """ + What each address of this version says about itself to a caller that asks. + + An OPTIONS request is answered with the description the view class + carries, so that description is published text and is read by clients and + by documentation browsers alongside the description of the same address in + the schema. These tests hold it to being written for the caller: no markup + that renders as itself in a JSON body, no vocabulary from the + implementation, and no essay. + """ + + def test_every_mounted_address_is_described(self): + """Each view this version mounts says something about itself.""" + described = { + name: view_class().get_view_description() + for name, view_class in routed_view_classes().items() + } + assert len(described) == 11, sorted(described) + assert [name for name, text in described.items() if not text.strip()] == [] + + def test_no_address_describes_itself_in_implementation_terms(self): + offenders = { + name: [term for term in IMPLEMENTATION_TERMS if term in view_class().get_view_description()] + for name, view_class in routed_view_classes().items() + } + assert {name: terms for name, terms in offenders.items() if terms} == {} + + def test_no_address_describes_itself_with_markup_a_caller_sees_as_itself(self): + """Double backticks are markup in this module's own documentation and text in a JSON body.""" + carrying_markup = [ + name for name, view_class in routed_view_classes().items() + if "``" in view_class().get_view_description() + ] + assert carrying_markup == [] + + def test_no_address_describes_itself_at_length(self): + too_long = { + name: len(view_class().get_view_description()) + for name, view_class in routed_view_classes().items() + if len(view_class().get_view_description()) > DESCRIPTION_LIMIT + } + assert too_long == {} + + def test_options_answers_with_the_description_the_view_carries(self): + """ + The description a view carries is the one a caller is handed. + + This is what makes the text above published rather than internal: the + framework answers an OPTIONS request with it verbatim. + """ + self.login(self.admin) + answer = self.client.options(reverse("user_v2:user_list")) + assert answer.status_code == status.HTTP_200_OK + assert answer.json()["description"] == UserViewSet().get_view_description() + assert answer.json()["description"].startswith( + "Directory entries of the platform's users, each addressed by username.", + ) diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index bb5516146a9a..d4aff3f412a3 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -602,14 +602,19 @@ class UserViewSet( viewsets.ReadOnlyModelViewSet, ): """ - Read-only directory of platform users, addressed by username. + Directory entries of the platform's users, each addressed by username. - Access is layered: ``permission_classes`` admits only platform - administrators whose account is still active, the scoping policy decides - which rows such an administrator may see, and the filter set narrows those - rows further by the caller's query parameters. + An entry carries the identifying properties of one account together with + the preferences stored against it. Only a platform administrator whose own + account is still active may read this directory. """ + # Who may read the directory is settled in three layers, each of which can + # be replaced on its own: the permission classes below settle who may call + # the collection at all, the record-visibility policy settles which rows + # such a caller may see, and the filter set narrows those rows by the + # parameters the request carries. + permission_classes = (permissions.IsAuthenticated, IsActiveUser, permissions.IsAdminUser) serializer_class = UserDirectorySerializer pagination_class = UserApiPagination @@ -694,14 +699,19 @@ class UserPreferenceViewSet( viewsets.ReadOnlyModelViewSet, ): """ - Read-only list of stored user preferences, each addressed by its owner and key. + Preferences stored for the platform's users, each addressed by its owner and its name. - A preference is identified by the pair, so the member address is - ``{username},{key}`` rather than a database id. Access is layered the same - way as the user directory: permission classes, then the scoping policy, - then the filter set. + A preference is identified by the two together, so a member address + carries the owner's username, a comma and the name the preference is + stored under, as in alice,time_zone. Only a platform administrator whose + own account is still active may read these. """ + # The pair identifies a row, so the member address is built from it rather + # than from a database id, and the route that serves it is declared with + # the collection rather than generated. Who may read these rows is settled + # in the same three layers as the user directory. + permission_classes = (permissions.IsAuthenticated, IsActiveUser, permissions.IsAdminUser) serializer_class = UserPreferenceRecordSerializer pagination_class = UserApiPagination @@ -763,12 +773,14 @@ class CountryTimeZoneViewSet( """ Time zones commonly used in a country, or every time zone when no country is named. - The rows come from the time-zone database rather than from a queryset, so - this is a plain ViewSet whose one query parameter is validated by a - serializer. The reference data it returns is the same for every caller and - is public on purpose. + The list is the same for every caller and is open to anyone. """ + # The rows come from the time-zone database rather than from a table of + # this app's, so there is no queryset to narrow and the one parameter the + # view reads is validated by a serializer instead of a filter set. The + # data is reference data, which is why no caller is turned away. + permission_classes = (permissions.AllowAny,) serializer_class = TimeZoneSerializer #: Validates the query string, and names the parameters this view reads. @@ -936,38 +948,34 @@ class AccountViewSet( viewsets.ViewSet, ): """ - Accounts of the platform's users, addressed by username or by ``me``. - - The properties of an account are read from the account service rather than - from a queryset of this app's, so this is a plain ViewSet; which accounts - the answer carries is settled first, from the accounts holding the names - the caller gave, in the order the page is cut in. Access is layered: the - permission classes decide who may call an action at all, the service - decides which properties of each account the caller may see -- everything - for their own account and for a staff caller, the owner's shared - properties otherwise -- and the selectors decide which accounts the page - carries. - - A selector that finds nothing narrows the page to nothing, whichever of - the three it is, so a selection no account matches is answered by an empty - page rather than by a refusal. An address an account held before it was - retired is the one exception: that account was there and is not a row this - page can carry, so it is refused, with whether the retirement can still be - cancelled. That refusal is why the selectors are read from the query - string by a serializer and applied here rather than declared as a filter - set, which has no room for it. - - A selection of properties is measured against the properties a response of - this kind can carry for this caller, so one no account could ever show - them is refused rather than answered as an empty object. Which of the rest - a particular owner shares is settled per account, so a selected property - that this owner keeps to themselves is left out of their object, which can - leave it empty. - - ``me`` stands for the caller's own account wherever a caller reads or - changes one here. + Accounts of the platform's users. Address one by username, or me for your own. + + An account carries the properties the caller may see: all of them for your + own account and for a staff caller, and otherwise the ones its owner + shares. A property an owner does not share is left out of their account + rather than refused, so an account can come back as an empty object. + + Selecting accounts that nothing holds gives an empty page rather than a + refusal. An address an account held before it was retired is refused + instead, and that refusal says whether the retirement can still be + cancelled. + + A property no account of this kind could show this caller is refused + rather than answered as an empty object. """ + # The properties of an account are read from the account service rather + # than from a table of this app's, so there is no queryset to narrow and + # the page is cut from the names the selection resolved to. The service is + # what settles which properties of each account the caller may see; the + # selection settles which accounts the page carries, and is applied in the + # handler rather than declared as a filter set because a filter set has no + # room for the retired-address refusal, which reports rows it cannot carry + # instead of leaving them out. Which properties the answer can carry is + # settled before the address is read, so a request for a property this + # kind of answer never carries is refused without reading or writing + # anything on the way to it. + # Account settings are reached from the site's own pages by users who have # not confirmed their email address yet, and the platform default refuses # a session belonging to such an account. Only the session class differs in @@ -1276,18 +1284,20 @@ class AccountDeactivationView( APIView, ): """ - Disables the account the address names. - - This is an operation a privileged caller carries out on somebody else's - account rather than a property of that account, and it shares nothing with - the way an account is read or changed: the caller holds the privilege to - disable accounts and has confirmed their own address, the body is read as - JSON rather than as a merge patch, and the name in the address is read as - a stored username, ``me`` included, so a caller that addressed one account - is never answered by disabling another. It is therefore its own view - rather than an action of the account collection. + Disables the account the address names, so its owner can no longer sign in with it. + + The account and everything belonging to it are kept, and none of it is + removed. Asking for a password reset does not undo this. """ + # Disabling an account is something a privileged caller does to somebody + # else's account rather than a property of that account, and it shares + # neither its callers nor its body with the way an account is read or + # changed: the caller holds the privilege to disable accounts and has + # confirmed their own address, and the body is read as JSON rather than as + # a merge patch. It is therefore a view of its own rather than an action + # of the account collection. + permission_classes = (permissions.IsAuthenticated, IsActiveUser, CanDeactivateUser) def post(self, request, username): @@ -1353,17 +1363,20 @@ class EmailSearchViewSet( """ The accounts holding a given set of email addresses. - The addresses are sent in a request body rather than in a query string, so - that they stay out of server logs and browser histories, which is why a - search is made with a POST, and why the links on a page of results are - followed by sending the body to them again rather than by fetching them. - The search is a collection of its own rather than an action under the - accounts, because what follows the account collection in an address is the - name of an account, and an account may be named anything a user may - register. Only a platform administrator may search, and every other caller - is told there is nothing at this address. + The addresses to look for are sent in the request body, so a search is + made with POST, and the links on a page of results are followed by sending + the body to them again rather than by fetching them. Only a platform + administrator may search here; every other caller is told there is nothing + at this address. """ + # The addresses are sent in a body so that they stay out of server logs + # and browser histories, which is what makes the search a POST and what + # makes its pages be followed with a body. The search stands beside the + # accounts rather than under them because what follows the account + # collection in an address is the name of an account, and a user may + # register any name. + permission_classes = ( permissions.IsAuthenticated, IsActiveUser, @@ -1546,18 +1559,19 @@ class IDVerificationStatusView( """ Whether a user has proved their identity, as one summary. - An account has one such summary, computed rather than stored and never - listed, so it is served from this single address rather than routed as a - collection. The summary is read from the identity verification service - rather than from this app's own tables, and the username in the address - names the user whose summary is read. A user may read their own summary, - and a staff caller whose own account is active may read anyone's, which is - not what the account collection admits, so the summary is served by a view - of its own rather than as an action of that collection. Every account has a - summary: one belonging to a user who has been through no check says so, and - the address is absent only when the user it names is. + Every account has a summary, and one belonging to a user who has been + through no check says so; the address is absent only when the user it + names is. A user may read their own summary, and a staff caller whose own + account is still active may read anyone's. """ + # The summary is computed rather than stored and is never listed, so it is + # served from this one address rather than routed as a collection, and it + # is read from the identity verification service rather than from a table + # of this app's. It admits a different set of callers from the account + # collection, which is why it is a view of its own rather than an action + # of that collection. + permission_classes = ( permissions.IsAuthenticated, # Reading somebody else's summary is a privilege, so the staff half @@ -1631,16 +1645,18 @@ class IDVerificationViewSet( """ The attempts one user has made at proving their identity. - The attempts are collected from the identity verification service, which - holds a table per kind of check, so there is no queryset of this app's to - narrow: the page is cut from what those tables return and is sorted here - rather than by a filter backend. An attempt belongs to the user who made - it and is reached by no other route, so the collection is addressed - beneath that user's account. A user may read their own attempts, and a - staff caller may read anyone's. A user who has been through no checks has - an empty page: the address is absent only when the user it names is. + A user may read their own attempts, and a staff caller may read anyone's. + A user who has been through no checks has an empty page; the address is + absent only when the user it names is. """ + # The attempts are collected from the identity verification service, which + # holds a table per kind of check, so there is no queryset of this app's to + # narrow: the page is cut from what those tables return and is sorted in + # the view rather than by a filter backend. An attempt is reached by no + # route other than this one, which is why the collection is addressed + # beneath the account it belongs to. + permission_classes = ( permissions.IsAuthenticated, # Reading somebody else's attempts is a privilege, so the staff half @@ -1671,11 +1687,11 @@ def list(self, request, username): @extend_schema(exclude=True) class UnknownAddressView(StandardizedErrorMixin, APIView): """ - Refuses every address under this version of the API that no route serves. + Refuses an address under this version of the API that no route serves. - It serves no resource: it exists so that a mistyped address is answered - with the same JSON body as every other failure instead of the service's - HTML error page, which a client that asked for JSON cannot read. + The refusal carries the same JSON body as every other failure of this + version, rather than the service's HTML error page, which a client that + asked for JSON cannot read. """ permission_classes = (permissions.AllowAny,) From ffcf6cf30eb03f77813bd300318c3f20a868c92b Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 21:36:25 +0500 Subject: [PATCH 19/61] fix: refuse a selected property name that reaches into a property --- .../user_api/v2/tests/test_account_views.py | 51 ++++++++++++++++ .../user_api/v2/tests/test_views.py | 60 +++++++++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 14 ++++- 3 files changed, 122 insertions(+), 3 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index b03db8237992..76d34b1f9e12 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -2954,3 +2954,54 @@ class AccountReadsDoNotWriteTests(AccountReadsDoNotWriteMixin, AccountApiV2TestC @override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=True) class AccountReadsWithARecoveryAddressDoNotWriteTests(AccountReadsDoNotWriteMixin, AccountApiV2TestCase): """The same reads on a site that collects a recovery address, which is another row to read.""" + + +@skip_unless_lms +class AccountSelectedPropertyNameTests(AccountApiV2TestCase): + """ + What a selected property name may be at the account addresses. + + An account carries properties that are objects of their own. A name + written with a dot in it reads as a name of no property the account + carries, because the account carries the object whole and the parameter + selects the properties of the account rather than the properties of those + objects. + """ + + def test_a_name_reaching_into_a_property_is_refused_on_one_account(self): + self.login(self.owner) + response = self.client.get(f"{self.own_url}?fields=profile_image.has_image") + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert response.json()["errors"]["fields"][0].startswith( + "No such field: profile_image.has_image. Select any of: ", + ) + + def test_a_name_reaching_into_a_property_is_refused_on_the_account_list(self): + self.login(self.owner) + response = self.client.get(f"{self.list_url}?fields=profile_image.image_url_full") + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert response.json()["errors"]["fields"][0].startswith( + "No such field: profile_image.image_url_full. Select any of: ", + ) + + def test_a_name_reaching_into_a_property_is_refused_on_a_change(self): + self.login(self.owner) + response = self.patch(f"{self.own_url}?fields=profile_image.has_image", json.dumps({"bio": "a bio"})) + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert UserProfile.objects.get(user=self.owner).bio != "a bio" + + def test_naming_the_property_itself_returns_the_whole_object(self): + """The object is what the account carries, so naming it brings all of it back.""" + self.login(self.owner) + response = self.client.get(f"{self.own_url}?fields=profile_image") + assert response.status_code == status.HTTP_200_OK + assert sorted(response.json()) == ["profile_image"] + assert sorted(response.json()["profile_image"]) == [ + "has_image", "image_url_full", "image_url_large", "image_url_medium", "image_url_small", + ] diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index 812b421340fe..d3513e7710a4 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -1705,3 +1705,63 @@ def test_options_answers_with_the_description_the_view_carries(self): assert answer.json()["description"].startswith( "Directory entries of the platform's users, each addressed by username.", ) + + +@skip_unless_lms +class SelectedPropertyNameTests(UserApiV2TestCase): + """ + What a selected property name may be, at the collections that take one. + + The parameter takes the names of properties the answer carries. A name + written with a dot in it names no such property: the answer carries the + property the name starts with, whole, and the rest of the name selects + nothing. Reading such a name as its first part would hand a caller the + whole of a property it asked one piece of, and would accept a second part + that names nothing at all. + """ + + def setUp(self): + super().setUp() + self.list_url = reverse("user_v2:user_list") + self.member_url = reverse("user_v2:user_detail", kwargs={"username": "alice"}) + self.preference_list_url = reverse("user_v2:user_preference_list") + self.login(self.admin) + + def test_a_name_written_with_a_dot_is_refused_on_the_directory_list(self): + response = self.client.get(f"{self.list_url}?fields=username.first") + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert response.json()["errors"]["fields"] == [ + "No such field: username.first. Select any of: email, id, name, preferences, url, " + "username.", + ] + + def test_a_name_written_with_a_dot_is_refused_on_a_directory_entry(self): + response = self.client.get(f"{self.member_url}?fields=preferences.pref-lang") + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert "No such field: preferences.pref-lang." in response.json()["errors"]["fields"][0] + + def test_a_name_written_with_a_dot_is_refused_on_the_preference_list(self): + response = self.client.get(f"{self.preference_list_url}?fields=user.email") + assert_error_envelope( + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert "No such field: user.email." in response.json()["errors"]["fields"][0] + + def test_a_plain_name_still_selects_that_property_alone(self): + response = self.client.get(f"{self.member_url}?fields=username") + assert response.status_code == status.HTTP_200_OK + assert response.json() == {"username": "alice"} + + def test_a_plain_name_still_selects_that_property_alone_on_a_list(self): + response = self.client.get(f"{self.list_url}?fields=username,email&ordering=username") + assert response.status_code == status.HTTP_200_OK + assert response.json()["results"] == [ + {"username": "admin-caller", "email": self.admin.email}, + {"username": "alice", "email": "alice@example.com"}, + {"username": "bob", "email": "bob@example.com"}, + {"username": "learner-caller", "email": self.learner.email}, + ] diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index d4aff3f412a3..a8cd416fe174 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -486,10 +486,18 @@ def reverse_action(self, url_name, *args, **kwargs): def _requested_field_names(raw): - """Return the top-level property names a ``fields`` value asks for.""" + """ + Return the property names a ``fields`` value asks for, each as it was written. + + A name is held against the properties the answer carries whole, so a name + written with a dot in it names no such property and is refused. Reading + only the part before the dot would hand back the whole of a property the + caller asked one piece of, and would take a part after it that names + nothing at all without saying so. + """ if not raw: return [] - return [name.strip().split(".", 1)[0] for name in raw.split(",") if name.strip()] + return [name.strip() for name in raw.split(",") if name.strip()] class _ResponsePresetMixin(MinimalViewMixin): @@ -547,7 +555,7 @@ def check_requested_fields(self, request): def shape(self, data, request): """Return ``data`` reduced to the preset and the fields the caller asked for.""" data = self.shape_minimal(data, request) - requested_fields = request.query_params.get(FIELDS_PARAM) + requested_fields = _requested_field_names(request.query_params.get(FIELDS_PARAM)) if not requested_fields: return data if isinstance(data, list): From 78299b00af318df53b258599497fac5f3c1afe36 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 21:39:07 +0500 Subject: [PATCH 20/61] fix: test and describe the rate limit on changing a recovery address --- .../user_api/v2/tests/test_account_views.py | 61 +++++++++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 11 +++- 2 files changed, 70 insertions(+), 2 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 76d34b1f9e12..6b80746ce769 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -3005,3 +3005,64 @@ def test_naming_the_property_itself_returns_the_whole_object(self): assert sorted(response.json()["profile_image"]) == [ "has_image", "image_url_full", "image_url_large", "image_url_medium", "image_url_small", ] + + +@skip_unless_lms +@override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=True) +class RecoveryAddressRateLimitedTests(AccountApiV2TestCase): + """A site that limits how often a recovery address may be changed.""" + + @override_settings( + SECONDARY_EMAIL_RATE_LIMIT="1/d", CACHES=counting_cache("recovery-address-refused"), + ) + def test_changing_a_recovery_address_too_often_is_refused(self): + self.login(self.owner) + first = self.patch(self.own_url, json.dumps({"secondary_email": "owner-recovery@example.com"})) + assert first.status_code == status.HTTP_200_OK + + second = self.patch(self.own_url, json.dumps({"secondary_email": "owner-other@example.com"})) + envelope = assert_error_envelope( + second, expected_status=status.HTTP_429_TOO_MANY_REQUESTS, expected_type_slug="rate-limited", + ) + assert envelope["detail"] == "Wait before changing secondary_email again." + + @override_settings( + SECONDARY_EMAIL_RATE_LIMIT="1/d", CACHES=counting_cache("recovery-address-allowed"), + ) + def test_the_limit_leaves_a_change_of_the_sign_in_address_alone(self): + """Each property is counted under a name of its own, so one limit does not spend another.""" + self.login(self.owner) + assert self.patch( + self.own_url, json.dumps({"secondary_email": "owner-recovery@example.com"}), + ).status_code == status.HTTP_200_OK + later = self.patch(self.own_url, json.dumps({"email": "owner-signin@example.com"})) + assert later.status_code == status.HTTP_200_OK + + +@skip_unless_lms +@override_switch(ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH, active=True) +@override_settings(CACHES=counting_cache("recovery-address-unlimited")) +class RecoveryAddressUnlimitedTests(AccountApiV2TestCase): + """ + A site that has given no limit, which is how the platform ships. + + Neither of the two properties that can be limited carries a limit out of + the box, so the refusal this endpoint publishes for changing one too often + is answered only by a deployment that has given the matching setting a + value. That is recorded here so that the published refusal is not read as + something every deployment produces. + """ + + def test_the_platform_default_gives_no_limit(self): + assert settings.SECONDARY_EMAIL_RATE_LIMIT == "" + assert settings.EMAIL_CHANGE_RATE_LIMIT == "" + + def test_a_recovery_address_may_be_changed_again_and_again(self): + self.login(self.owner) + answered = [] + for attempt in range(3): + response = self.patch( + self.own_url, json.dumps({"secondary_email": f"owner-recovery-{attempt}@example.com"}), + ) + answered.append(response.status_code) + assert answered == [status.HTTP_200_OK] * 3 diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index a8cd416fe174..74e7b449507e 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -153,7 +153,9 @@ SHAPED_ACCOUNT_ACTIONS = ("list", "retrieve", "partial_update") #: The properties whose change is limited to a rate, and the setting carrying -#: the limit of each. +#: the limit of each. Both settings are empty until a deployment gives one of +#: them a value, and an empty limit limits nothing, so a site that has +#: configured neither takes every change to either property. RATE_LIMITED_ACCOUNT_FIELDS = ( ("email", "EMAIL_CHANGE_RATE_LIMIT"), ("secondary_email", "SECONDARY_EMAIL_RATE_LIMIT"), @@ -252,7 +254,12 @@ def _ordering_param(sort_fields, default): ), ) _RESP_RATE_LIMITED = OpenApiResponse( - ErrorResponse, description="The caller has changed this property too often lately and has to wait.", + ErrorResponse, + description=( + "The caller has changed this property too often lately and has to wait. Only a site that " + "has given a limit for the property answers this; a site that has given none, which is " + "how the platform ships, takes every change." + ), ) _RESP_CHANGE_FAILED = OpenApiResponse( ErrorResponse, From 87047e92d3493e1aefb011706a4de8191bac90e5 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 21:47:24 +0500 Subject: [PATCH 21/61] fix: describe the body a search is asked for in, not the one it answers with --- .../user_api/v2/tests/test_account_views.py | 43 +++++++++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 18 ++++++-- 2 files changed, 57 insertions(+), 4 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 6b80746ce769..f9e169eb04f8 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -3066,3 +3066,46 @@ def test_a_recovery_address_may_be_changed_again_and_again(self): ) answered.append(response.status_code) assert answered == [status.HTTP_200_OK] * 3 + + +@skip_unless_lms +class EmailSearchAddressDescriptionTests(AccountApiV2TestCase): + """What OPTIONS answers about the body a search is asked for in.""" + + def setUp(self): + super().setUp() + self.url = reverse("user_v2:email_search_list") + + def test_the_address_names_the_body_a_search_is_sent_in(self): + """ + The body the answer describes is the one the address reads, not the one it returns. + + A search is asked for by sending the addresses to look for, and is + answered with an account per address found. Describing the answer here + would have a caller build its request out of the shape it is going to + receive, which this address does not read. + """ + self.login(self.staff) + answer = self.client.options(self.url) + assert answer.status_code == status.HTTP_200_OK + assert sorted(answer.json()["actions"]["POST"]) == ["emails"] + + def test_every_name_the_described_body_carries_is_one_the_search_needs(self): + """Leaving any one of the described names out is refused, so the description is the body.""" + self.login(self.staff) + described = self.client.options(self.url).json()["actions"]["POST"] + assert described + for omitted in described: + body = {name: ["owner-caller@example.com"] for name in described if name != omitted} + response = self.client.post(self.url, body, format="json") + assert response.status_code == status.HTTP_400_BAD_REQUEST, omitted + + def test_a_search_built_from_the_described_body_is_answered(self): + """The description is taken at its word: what it names is a body the address reads.""" + self.login(self.staff) + described = self.client.options(self.url).json()["actions"]["POST"] + response = self.client.post( + self.url, {name: ["owner-caller@example.com"] for name in described}, format="json", + ) + assert response.status_code == status.HTTP_200_OK + assert [row["username"] for row in response.data["results"]] == ["owner-caller"] diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 74e7b449507e..a4c9a6554c74 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -199,10 +199,12 @@ class AddressMetadata(SimpleMetadata): declared on the view, which belong to the view as a whole rather than to the address being asked about: an address that reads one media type is otherwise described as reading every media type the platform reads - anywhere, and a method whose handler reads no body is described as taking - the one the view's serializer carries. A caller that negotiates from this - description sends what it was told to send, so each half of it is answered - from the address and the method being described. + anywhere, a method whose handler reads no body is described as taking the + one the view's serializer carries, and a method whose body differs from + what the view answers with is described as taking the answer. A caller + that negotiates from this description sends what it was told to send, so + each part of it is answered from the address and the method being + described. """ def determine_metadata(self, request, view): @@ -216,6 +218,9 @@ def determine_actions(self, request, view): described = super().determine_actions(request, view) served = getattr(view, "action_map", None) or {} bodiless = set(getattr(view, "bodiless_actions", ())) + taken = getattr(view, "request_serializer_class", None) + if taken is not None: + described = {method: self.get_serializer_info(taken()) for method in described} return { method: fields for method, fields in described.items() if served.get(method.lower()) not in bodiless @@ -1404,7 +1409,12 @@ class EmailSearchViewSet( # table the other collections of this version narrow. scoping_policy = FullScopePolicy() parser_classes = (JSONParser,) + metadata_class = AddressMetadata serializer_class = EmailSearchResultSerializer + #: A search is asked for by sending the addresses to look for and is + #: answered with an account per address found, so the body it takes is not + #: the shape it answers with. + request_serializer_class = EmailSearchSerializer pagination_class = UserApiPagination def get_serializer(self, *args, **kwargs): From 69c5b73c6788f38f34c61fa029bc206a26d2a164 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 21:49:18 +0500 Subject: [PATCH 22/61] fix: say both things that get a clearing of a profile image refused --- openedx/core/djangoapps/profile_images/v2/views.py | 6 +++++- openedx/core/djangoapps/user_api/v2/tests/test_schema.py | 3 ++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index ed0100958bdb..349e4e4189cc 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -204,7 +204,11 @@ def post(self, request, username): responses={ 204: OpenApiResponse(description="The account carries no image of its own."), 400: OpenApiResponse( - ErrorResponse, description="The request carries a query parameter this endpoint does not read.", + ErrorResponse, + description=( + "The request carries a query parameter this endpoint does not read, or the " + "address names more than one account and so names none of them in particular." + ), ), 401: RESP_UNAUTHENTICATED, 403: _RESP_ANOTHER_USERS_IMAGE, diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index 794d5cf0a41e..cf0fba2cfd54 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -1606,7 +1606,8 @@ def test_clearing_the_profile_image_publishes_that_it_reads_nothing(schema): assert operation["responses"]["204"]["description"] == "The account carries no image of its own." assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404"] assert operation["responses"]["400"]["description"] == ( - "The request carries a query parameter this endpoint does not read." + "The request carries a query parameter this endpoint does not read, or the address names " + "more than one account and so names none of them in particular." ) From f4c6f0feb1c68686217d1c081d975a3e00cccb70 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sat, 31 Oct 2026 22:04:52 +0500 Subject: [PATCH 23/61] fix: publish the two refusals every address of this version could already answer --- .../djangoapps/profile_images/v2/views.py | 8 +- .../user_api/v2/tests/test_schema.py | 59 ++++++++--- .../user_api/v2/tests/test_views.py | 98 ++++++++++++++++++- openedx/core/djangoapps/user_api/v2/views.py | 34 +++++++ 4 files changed, 184 insertions(+), 15 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index 349e4e4189cc..864c9b52a9d3 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -33,7 +33,11 @@ StrictQueryParametersMixin, path_param, ) -from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS, AccountResourceMixin +from openedx.core.djangoapps.user_api.v2.views import ( + AMBIGUOUS_ACCOUNT_ADDRESS, + RESP_NOT_ACCEPTABLE, + AccountResourceMixin, +) from openedx.core.lib.api.parsers import TypedFileUploadParser from ..exceptions import ImageValidationError @@ -169,6 +173,7 @@ class ProfileImageView( 401: RESP_UNAUTHENTICATED, 403: _RESP_ANOTHER_USERS_IMAGE, 404: _RESP_NO_PROFILE, + 406: RESP_NOT_ACCEPTABLE, 415: RESP_UNREADABLE_BODY, }, ) @@ -213,6 +218,7 @@ def post(self, request, username): 401: RESP_UNAUTHENTICATED, 403: _RESP_ANOTHER_USERS_IMAGE, 404: _RESP_NO_PROFILE, + 406: RESP_NOT_ACCEPTABLE, }, ) def delete(self, request, username): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index cf0fba2cfd54..c9b39067c651 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -811,11 +811,11 @@ def test_every_list_publishes_the_page_that_does_not_exist(schema): if path in LIST_PATHS } assert documented == { - ACCOUNT_LIST_PATH: ["200", "400", "401", "403", "404"], - VERIFICATION_LIST_PATH: ["200", "400", "401", "403", "404"], - "/api/user/v2/users/": ["200", "400", "401", "403", "404"], - "/api/user/v2/user_preferences/": ["200", "400", "401", "403", "404"], - TIME_ZONE_LIST_PATH: ["200", "400", "404"], + ACCOUNT_LIST_PATH: ["200", "400", "401", "403", "404", "406"], + VERIFICATION_LIST_PATH: ["200", "400", "401", "403", "404", "406"], + "/api/user/v2/users/": ["200", "400", "401", "403", "404", "406"], + "/api/user/v2/user_preferences/": ["200", "400", "401", "403", "404", "406"], + TIME_ZONE_LIST_PATH: ["200", "400", "404", "406"], } @@ -1103,14 +1103,14 @@ def test_every_property_the_change_publishes_a_null_for_is_cleared_by_one(client @skip_unless_lms def test_a_change_publishes_the_refusals_only_it_can_answer_with(schema): assert sorted(schema["paths"][ACCOUNT_MEMBER_PATH]["patch"]["responses"]) == [ - "200", "400", "401", "403", "404", "415", "429", "500", + "200", "400", "401", "403", "404", "406", "415", "429", "500", ] assert schema["paths"][ACCOUNT_MEMBER_PATH]["patch"]["responses"]["500"]["description"] == ( "The change was asked for correctly and could not be carried out. Sending it again " "with something else in it does not help; sending the same request later may." ) assert sorted(schema["paths"][ACCOUNT_MEMBER_PATH]["get"]["responses"]) == [ - "200", "400", "401", "403", "404", + "200", "400", "401", "403", "404", "406", ] @@ -1179,7 +1179,7 @@ def test_the_search_publishes_the_addresses_it_reads_and_the_page_it_answers_wit addresses = schema["components"]["schemas"]["EmailSearch"]["properties"]["emails"] assert addresses["type"] == "array" assert addresses["maxItems"] == 100 - assert sorted(operation["responses"]) == ["200", "400", "401", "403", "404", "415"] + assert sorted(operation["responses"]) == ["200", "400", "401", "403", "404", "406", "415"] # The page is the only thing it reads from the query string. assert [parameter["name"] for parameter in operation["parameters"]] == ["page", "page_size"] @@ -1188,7 +1188,7 @@ def test_the_search_publishes_the_addresses_it_reads_and_the_page_it_answers_wit def test_a_deactivation_publishes_that_it_answers_with_nothing(schema): operation = schema["paths"][ACCOUNT_DEACTIVATION_PATH]["post"] assert "requestBody" not in operation - assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404"] + assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404", "406"] assert "content" not in operation["responses"]["204"] assert operation["responses"]["204"]["description"] == "The account was deactivated." @@ -1490,7 +1490,7 @@ def test_a_name_change_publishes_the_body_it_reads_and_the_one_it_returns(schema assert operation["responses"]["201"]["content"]["application/json"]["schema"] == { "$ref": "#/components/schemas/NameChange", } - assert sorted(operation["responses"]) == ["201", "400", "401", "404", "415"] + assert sorted(operation["responses"]) == ["201", "400", "401", "403", "404", "406", "415"] published = schema["components"]["schemas"]["NameChange"] assert published["required"] == ["name"] assert published["properties"]["name"]["maxLength"] == 255 @@ -1507,7 +1507,7 @@ def test_a_confirmation_publishes_that_it_reads_nothing_and_answers_with_nothing "The profile now carries the name that was asked for." ) assert "content" not in operation["responses"]["204"] - assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404"] + assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404", "406"] #: Every form an image may be sent in: the media type, the name a body sent in @@ -1555,7 +1555,7 @@ def test_the_profile_image_publishes_every_media_type_it_reads_the_image_in(sche "site configures." ), } - assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404", "415"] + assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404", "406", "415"] @pytest.mark.django_db @@ -1604,7 +1604,7 @@ def test_clearing_the_profile_image_publishes_that_it_reads_nothing(schema): assert "requestBody" not in operation assert [parameter["name"] for parameter in operation["parameters"]] == ["username"] assert operation["responses"]["204"]["description"] == "The account carries no image of its own." - assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404"] + assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404", "406"] assert operation["responses"]["400"]["description"] == ( "The request carries a query parameter this endpoint does not read, or the address names " "more than one account and so names none of them in particular." @@ -1829,3 +1829,36 @@ def test_the_stored_preference_reads_are_named_alike_in_every_document_that_publ (PREFERENCE_LIST_PATH, "get"): "api_user_v2_user_preferences_list", (PREFERENCE_MEMBER_PATH, "get"): "api_user_v2_user_preferences_retrieve", } + + +#: What every operation of this version says about a request it can give no +#: answer to. Which representations an answer can be given in is settled as +#: the request enters, before the address it names is read or written, so the +#: refusal reaches an operation that answers with a body and one that does not +#: alike. +UNSATISFIABLE_ACCEPT_DESCRIPTION = ( + "The `Accept` header of the request names no representation this endpoint can answer in." +) + + +@skip_unless_lms +def test_every_operation_publishes_the_refusal_of_an_accept_it_cannot_satisfy(schema): + """ + No operation of this version leaves this refusal unpublished. + + This is asserted over every operation rather than per address, so an + operation added later is held to it without this test being changed. + """ + unpublished = { + f"{method.upper()} {path}" + for path, method, operation in operations(schema) + if path in VERSION_TWO_PATHS and "406" not in operation["responses"] + } + assert unpublished == set() + wrongly_described = { + f"{method.upper()} {path}": operation["responses"]["406"]["description"] + for path, method, operation in operations(schema) + if path in VERSION_TWO_PATHS + and operation["responses"]["406"]["description"] != UNSATISFIABLE_ACCEPT_DESCRIPTION + } + assert wrongly_described == {} diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index d3513e7710a4..b525a159f7a0 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -14,11 +14,12 @@ from edx_rest_framework_extensions.testing import assert_error_envelope from opaque_keys.edx.keys import CourseKey from rest_framework import status -from rest_framework.test import APITestCase +from rest_framework.test import APIClient, APITestCase from common.djangoapps.student.tests.factories import AdminFactory, UserFactory from openedx.core.djangoapps.django_comment_common.models import Role from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user +from common.djangoapps.student.models import PendingNameChange, UserProfile from openedx.core.djangoapps.user_api.models import UserPreference from openedx.core.djangoapps.user_api.preferences.api import get_country_time_zones from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory @@ -1765,3 +1766,98 @@ def test_a_plain_name_still_selects_that_property_alone_on_a_list(self): {"username": "bob", "email": "bob@example.com"}, {"username": "learner-caller", "email": self.learner.email}, ] + + +@skip_unless_lms +class UnsatisfiableAcceptTests(UserApiV2TestCase): + """ + What an address answers a request it can give no acceptable answer to. + + Which representations an answer may be given in is settled as the request + enters, so the refusal reaches an address that answers with a body and one + that answers with none alike. It is published by every operation of this + version, and these are the measurements that publication rests on. + """ + + def addresses(self): + """Return a representative request to each kind of address of this version, by method.""" + return [ + ("get", reverse("user_v2:user_list"), self.admin), + ("get", reverse("user_v2:user_detail", kwargs={"username": "alice"}), self.admin), + ("get", reverse("user_v2:user_preference_list"), self.admin), + ("get", reverse("user_v2:time_zone_list"), self.learner), + ("get", reverse("user_v2:account_list"), self.learner), + ("get", reverse("user_v2:account_detail", kwargs={"username": "me"}), self.learner), + ("delete", reverse("user_v2:account_profile_image", kwargs={"username": "alice"}), self.alice), + ] + + def test_an_accept_header_naming_nothing_the_address_answers_in_is_refused(self): + answered = {} + for method, url, caller in self.addresses(): + self.client.logout() + self.login(caller) + response = getattr(self.client, method)(url, HTTP_ACCEPT="text/csv") + answered[f"{method.upper()} {url}"] = response.status_code + assert set(answered.values()) == {status.HTTP_406_NOT_ACCEPTABLE}, answered + + def test_the_refusal_comes_back_in_the_body_this_version_answers_with(self): + """The refusal is readable even though the caller asked for a representation it is not in.""" + self.login(self.admin) + response = self.client.get(reverse("user_v2:user_list"), HTTP_ACCEPT="text/csv") + assert_error_envelope( + response, expected_status=status.HTTP_406_NOT_ACCEPTABLE, expected_type_slug="not-acceptable", + ) + + def test_an_address_that_answers_with_no_body_refuses_it_too(self): + """ + Nothing is read or changed on the way to the refusal. + + Clearing an image answers with no body at all, so the representation + asked for could make no difference to what comes back; the refusal is + settled before the handler runs, and the stored image is left alone. + """ + UserProfile.objects.filter(user=self.alice).update(profile_image_uploaded_at=datetime.now(UTC)) + self.login(self.alice) + response = self.client.delete( + reverse("user_v2:account_profile_image", kwargs={"username": "alice"}), + HTTP_ACCEPT="text/csv", + ) + assert response.status_code == status.HTTP_406_NOT_ACCEPTABLE + self.alice.profile.refresh_from_db() + assert self.alice.profile.has_profile_image is True + + def test_an_accept_header_the_address_can_satisfy_is_answered(self): + """The refusal is about what was asked for, not about asking at all.""" + self.login(self.admin) + response = self.client.get(reverse("user_v2:user_list"), HTTP_ACCEPT="application/json") + assert response.status_code == status.HTTP_200_OK + assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] + + +@skip_unless_lms +class SessionWithoutItsTokenTests(UserApiV2TestCase): + """ + What a write answers a session the site cannot tie to a page it served. + + The name change collection records something for the caller, is reached + from the site's own pages, and refuses such a session. + """ + + def test_asking_for_a_name_change_with_a_session_without_its_token_is_refused(self): + client = APIClient(enforce_csrf_checks=True) + assert client.login(username=self.alice.username, password=PASSWORD) + assert_error_envelope( + client.post(reverse("user_v2:name_change_list"), {"name": "Alice Example"}, format="json"), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert PendingNameChange.objects.filter(user=self.alice).count() == 0 + + def test_a_name_change_asked_for_with_the_token_the_session_carries_is_recorded(self): + """The refusal is about the missing token, not about the address.""" + self.login(self.alice) + response = self.client.post( + reverse("user_v2:name_change_list"), {"name": "Alice Example"}, format="json", + ) + assert response.status_code == status.HTTP_201_CREATED + assert PendingNameChange.objects.get(user=self.alice).new_name == "Alice Example" diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index a4c9a6554c74..3597858f6006 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -245,6 +245,25 @@ def _ordering_param(sort_fields, default): _PREFERENCE_ORDERING_PARAM = _ordering_param(PREFERENCE_SORT_FIELDS, PREFERENCE_DEFAULT_SORT) _RESP_FORBIDDEN = OpenApiResponse(ErrorResponse, description="The requester may not use this endpoint.") +#: Published by every operation of this version. Which representations an +#: answer can be given in is settled as the request enters, before the address +#: it names is read or written, so an ``Accept`` header naming none of them is +#: refused at every address whether or not that address answers with a body. +_RESP_SESSION_WITHOUT_ITS_TOKEN = OpenApiResponse( + ErrorResponse, + description=( + "The request was made with a session cookie and carried none of the request token the " + "site hands out with it, so the site cannot tell that the request came from a page it " + "served. Sending that token with the session, or a signed token in place of the " + "session, is answered." + ), +) +RESP_NOT_ACCEPTABLE = OpenApiResponse( + ErrorResponse, + description=( + "The `Accept` header of the request names no representation this endpoint can answer in." + ), +) _RESP_NOT_FOUND = OpenApiResponse(ErrorResponse, description="No such resource.") _RESP_NO_SUCH_PAGE = OpenApiResponse(ErrorResponse, description="There is no such page of results.") _RESP_BAD_REQUEST = OpenApiResponse( @@ -596,6 +615,7 @@ def shape_page(self, response, request): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NO_SUCH_PAGE, + 406: RESP_NOT_ACCEPTABLE, }, ), retrieve=extend_schema( @@ -608,6 +628,7 @@ def shape_page(self, response, request): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NOT_FOUND, + 406: RESP_NOT_ACCEPTABLE, }, ), ) @@ -685,6 +706,7 @@ def retrieve(self, request, *args, **kwargs): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NO_SUCH_PAGE, + 406: RESP_NOT_ACCEPTABLE, }, ), retrieve=extend_schema( @@ -706,6 +728,7 @@ def retrieve(self, request, *args, **kwargs): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NOT_FOUND, + 406: RESP_NOT_ACCEPTABLE, }, ), ) @@ -824,6 +847,7 @@ def get_serializer(self, *args, **kwargs): 200: TimeZoneSerializer, 400: _RESP_BAD_REQUEST, 404: _RESP_NO_SUCH_PAGE, + 406: RESP_NOT_ACCEPTABLE, }, ) def list(self, request): @@ -913,6 +937,7 @@ def addressed_account(self): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NO_SUCH_PAGE_OR_RETIRED, + 406: RESP_NOT_ACCEPTABLE, }, ), retrieve=extend_schema( @@ -930,6 +955,7 @@ def addressed_account(self): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NO_SUCH_ACCOUNT, + 406: RESP_NOT_ACCEPTABLE, }, examples=_ACCOUNT_EXAMPLES, ), @@ -950,6 +976,7 @@ def addressed_account(self): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_CHANGED_ACCOUNT_GONE, + 406: RESP_NOT_ACCEPTABLE, 415: RESP_UNREADABLE_BODY, 429: _RESP_RATE_LIMITED, 500: _RESP_CHANGE_FAILED, @@ -1293,6 +1320,7 @@ def _failed_change(self, username, error): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NOT_FOUND, + 406: RESP_NOT_ACCEPTABLE, }, ), ) @@ -1367,6 +1395,7 @@ def get_queryset(self): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: _RESP_NOT_FOUND, + 406: RESP_NOT_ACCEPTABLE, 415: RESP_UNREADABLE_BODY, }, ), @@ -1452,10 +1481,12 @@ def create(self, request): 201: NameChangeSerializer, 400: _RESP_UNUSABLE_BODY, 401: RESP_UNAUTHENTICATED, + 403: _RESP_SESSION_WITHOUT_ITS_TOKEN, 404: OpenApiResponse( ErrorResponse, description="The account of the caller carries no profile to put a name on.", ), + 406: RESP_NOT_ACCEPTABLE, 415: RESP_UNREADABLE_BODY, }, ), @@ -1522,6 +1553,7 @@ def create(self, request): ErrorResponse, description="No such user, or the user has asked for no name change.", ), + 406: RESP_NOT_ACCEPTABLE, }, ) @action( @@ -1623,6 +1655,7 @@ def get_serializer(self, *args, **kwargs): 401: RESP_UNAUTHENTICATED, 403: _RESP_FORBIDDEN, 404: OpenApiResponse(ErrorResponse, description="No such user."), + 406: RESP_NOT_ACCEPTABLE, }, ) def get(self, request, username): @@ -1656,6 +1689,7 @@ def get(self, request, username): 404: OpenApiResponse( ErrorResponse, description="No such user, or no such page of attempts.", ), + 406: RESP_NOT_ACCEPTABLE, }, ), ) From 540d11ad292a57afdacccf5dc164d19debd34743 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 06:30:29 +0500 Subject: [PATCH 24/61] fix: stop naming the site's sharing configuration in a refusal about another account --- .../user_api/v2/tests/test_account_views.py | 91 +++++++++++++++++-- openedx/core/djangoapps/user_api/v2/views.py | 42 +++++++-- 2 files changed, 119 insertions(+), 14 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index f9e169eb04f8..7da854967419 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -59,14 +59,13 @@ SHARED_FIELDS = set(_VISIBILITY.get("bulk_shareable_fields", ())) #: The properties an owner is able to share, and so the only ones another caller -#: may select; the refusal offers them in this order. +#: may select. A refusal about somebody else's account names none of them; one +#: about an answer the caller narrowed itself offers them in this order. SHAREABLE_FIELDS = set(_VISIBILITY.get("custom_shareable_fields", ())) SHAREABLE_FIELDS_OFFERED = ", ".join(sorted(SHAREABLE_FIELDS)) -#: The identifying properties the ``minimal`` preset keeps, and the ones of those -#: another caller may select; the refusal offers them in this order. +#: The identifying properties the ``minimal`` preset keeps. MINIMAL_FIELDS = {"username", "email", "name", "profile_image"} -SHAREABLE_MINIMAL_FIELDS_OFFERED = ", ".join(sorted(SHAREABLE_FIELDS & MINIMAL_FIELDS)) #: The query parameters each account action reads, in the order its refusal lists them. LIST_QUERY_PARAMS = "email, fields, format, lms_user_id, ordering, page, page_size, username, view" @@ -336,7 +335,8 @@ def test_a_learner_selecting_an_identifying_property_they_may_not_see_is_refused response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", ) assert envelope["errors"]["fields"] == [ - f"No such field: email. Select any of: {SHAREABLE_MINIMAL_FIELDS_OFFERED}.", + "No such field: email. An account another user holds carries only the " + "properties its owner shares.", ] def test_a_caller_selects_an_identifying_property_of_their_own_account(self): @@ -368,7 +368,8 @@ def test_a_learner_selecting_a_property_of_another_account_they_may_not_see_is_r response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", ) assert envelope["errors"]["fields"] == [ - f"No such field: email. Select any of: {SHAREABLE_FIELDS_OFFERED}.", + "No such field: email. An account another user holds carries only the " + "properties its owner shares.", ] def test_a_learner_selecting_a_property_this_owner_does_not_share_receives_the_rest(self): @@ -830,7 +831,8 @@ def test_a_learner_selecting_an_identifying_property_they_may_not_see_is_refused response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", ) assert envelope["errors"]["fields"] == [ - f"No such field: email. Select any of: {SHAREABLE_MINIMAL_FIELDS_OFFERED}.", + "No such field: email. An account another user holds carries only the " + "properties its owner shares.", ] def test_selected_fields_narrow_the_account(self): @@ -846,7 +848,8 @@ def test_a_learner_selecting_a_property_of_another_account_they_may_not_see_is_r response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", ) assert envelope["errors"]["fields"] == [ - f"No such field: email. Select any of: {SHAREABLE_FIELDS_OFFERED}.", + "No such field: email. An account another user holds carries only the " + "properties its owner shares.", ] def test_a_learner_selecting_a_property_this_owner_does_not_share_receives_the_rest(self): @@ -3109,3 +3112,75 @@ def test_a_search_built_from_the_described_body_is_answered(self): ) assert response.status_code == status.HTTP_200_OK assert [row["username"] for row in response.data["results"]] == ["owner-caller"] + + +@skip_unless_lms +class RefusalDisclosureTests(AccountApiV2TestCase): + """ + What a refusal about somebody else's account gives away. + + A caller that selects a property of another user's account it may not see + is told that it cannot. Which properties an owner shares is that owner's + to decide, and the set the site offers them to choose from is the site's + own configuration, so a refusal about an account the caller does not hold + names neither: it would otherwise hand every signed-in caller the whole + configured list, including names nobody on the site shares. + """ + + REFUSAL_ABOUT_ANOTHER_ACCOUNT = ( + "No such field: email. An account another user holds carries only the properties " + "its owner shares." + ) + + def test_a_refusal_about_another_account_names_nothing_the_site_configures(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.get(self.detail_url("other-caller"), {"fields": "email"}), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + message = envelope["errors"]["fields"][0] + assert message == self.REFUSAL_ABOUT_ANOTHER_ACCOUNT + assert sorted(name for name in SHAREABLE_FIELDS if name in message) == [] + + def test_a_refusal_about_another_account_on_the_list_names_nothing_either(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.get(self.list_url, {"username": "other-caller", "fields": "email"}), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + message = envelope["errors"]["fields"][0] + assert message == self.REFUSAL_ABOUT_ANOTHER_ACCOUNT + assert sorted(name for name in SHAREABLE_FIELDS if name in message) == [] + + def test_a_refusal_about_another_account_under_a_preset_names_nothing_either(self): + self.login(self.owner) + envelope = assert_error_envelope( + self.client.get(self.detail_url("other-caller"), {"view": "minimal", "fields": "email"}), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"]["fields"][0] == self.REFUSAL_ABOUT_ANOTHER_ACCOUNT + + def test_a_refusal_about_the_callers_own_account_still_says_what_may_be_selected(self): + """The caller sees every property of their own account, so naming them gives nothing away.""" + self.login(self.owner) + envelope = assert_error_envelope( + self.client.get(self.own_url, {"fields": "wallet"}), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + message = envelope["errors"]["fields"][0] + assert message.startswith("No such field: wallet. Select any of: ") + assert "username" in message + + def test_a_refusal_to_a_staff_caller_still_says_what_may_be_selected(self): + """A staff caller reads every property of every account, so the list tells them nothing new.""" + self.login(self.staff) + envelope = assert_error_envelope( + self.client.get(self.detail_url("other-caller"), {"fields": "wallet"}), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"]["fields"][0].startswith("No such field: wallet. Select any of: ") diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 3597858f6006..5523b3a590a1 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -571,16 +571,26 @@ def shapeable_fields(self): return set(self.minimal_fields) return set(self.get_serializer_class()().fields) + #: What a caller is told in place of the names, at a view that may withhold + #: them. A view that narrows what a response carries by who is asking says + #: here what it tells a caller it has narrowed the answer for. + withheld_fields_message = "" + + def shapeable_fields_may_be_named(self): + """Whether a refusal may list the properties a response of this view can carry.""" + return True + def check_requested_fields(self, request): """Refuse a selected field the response cannot carry, naming the ones it can.""" available = self.shapeable_fields() unknown = sorted(set(_requested_field_names(request.query_params.get(FIELDS_PARAM))) - available) if unknown: + if self.shapeable_fields_may_be_named(): + rest = f"Select any of: {', '.join(sorted(available))}." + else: + rest = self.withheld_fields_message raise ValidationError({ - FIELDS_PARAM: [ - f"No such field: {', '.join(unknown)}. " - f"Select any of: {', '.join(sorted(available))}.", - ], + FIELDS_PARAM: [f"No such field: {', '.join(unknown)}. {rest}"], }) def shape(self, data, request): @@ -1043,6 +1053,7 @@ class AccountViewSet( minimal_fields = ACCOUNT_MINIMAL_FIELDS response_presets = ACCOUNT_PRESETS extra_query_params = RESPONSE_SHAPING_PARAMS + withheld_fields_message = "An account another user holds carries only the properties its owner shares." #: The validated query string of the request being served, read once. _validated_selection = None @@ -1075,13 +1086,32 @@ def shapeable_fields(self): return describable return describable & _shareable_account_fields() + def shapeable_fields_may_be_named(self): + """ + Whether a refusal may list the properties an answer of this kind can carry. + + Which properties an owner shares is that owner's to decide, and the + set the site offers them to choose from is the site's own + configuration. A caller addressing an account it does not hold is + therefore told that it may not select what it selected, and not what + the site holds for other people: the list would otherwise name every + property the site is configured to let an owner share, including ones + nobody on the site shares. A caller that narrowed the answer itself, + by asking for a preset, is still told what that preset carries. + """ + return not self._only_shared_properties_are_readable(self.request) + def _whole_accounts_are_readable(self, request): """Whether every account this request addresses comes back whole to this caller.""" if request.query_params.get(VIEW_PARAM) == SHARED_VIEW: return False + return not self._only_shared_properties_are_readable(request) + + def _only_shared_properties_are_readable(self, request): + """Whether who the caller is keeps them from every property of the accounts addressed.""" if request.user.is_staff: - return True - return self._addressed_names(request) == [request.user.username] + return False + return self._addressed_names(request) != [request.user.username] def _selection(self, request): """ From 8f6b550134d3a53def7c93993eac180236663ebc Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 06:51:34 +0500 Subject: [PATCH 25/61] fix: fetch rows carried inside another resource through the policy that governs them --- .../user_api/v2/tests/test_url_mount.py | 42 ++++++ .../user_api/v2/tests/test_views.py | 123 +++++++++++++++++- openedx/core/djangoapps/user_api/v2/urls.py | 8 ++ openedx/core/djangoapps/user_api/v2/views.py | 41 +++++- 4 files changed, 206 insertions(+), 8 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py b/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py index 019d3c535434..475cd056e00c 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py @@ -7,6 +7,7 @@ AUTHN_LOGIN_VIEWS = "openedx.core.djangoapps.user_authn.views.login" AUTHN_REGISTER_VIEWS = "openedx.core.djangoapps.user_authn.views.register" +V2_VIEWS = "openedx.core.djangoapps.user_api.v2.views" @skip_unless_lms @@ -66,3 +67,44 @@ def test_both_shared_prefix_addresses_still_reverse_to_themselves(self): assert reverse( "user_api_login_session", kwargs={"api_version": "v2"}, ) == "/api/user/v2/account/login_session/" + + +@skip_unless_lms +class ClaimedPrefixTests(SimpleTestCase): + """ + Every address under this prefix that no route serves is answered by this version. + + The mount matches the whole prefix, so an address under it that none of + the routes and neither of the two addresses the authentication app keeps + matches is answered here rather than left to anything mounted later. That + is what makes a mistyped address come back as JSON, and it is also what + keeps an address registered under this prefix by anything mounted after + this version from being reached at all. + """ + + def assert_refused_here(self, address): + """Assert an address under the prefix is answered by this version's refusal.""" + match = resolve(address) + view_class = match.func.view_class + assert (view_class.__module__, view_class.__name__) == (V2_VIEWS, "UnknownAddressView"), address + + def test_a_mistyped_address_is_answered_by_this_version(self): + self.assert_refused_here("/api/user/v2/acounts/") + + def test_an_address_below_a_route_of_this_version_is_answered_by_this_version(self): + self.assert_refused_here("/api/user/v2/accounts/alice/not-a-property/") + + def test_a_third_address_of_the_other_apps_shape_is_answered_here(self): + """Only the two addresses spelled out for that app are left to it; a third is not.""" + self.assert_refused_here("/api/user/v2/account/password_reset/") + + def test_an_address_a_later_mount_would_serve_is_answered_here_instead(self): + """ + The prefix is claimed whole, which is the constraint an operator needs. + + Anything mounted after this version that registers an address under + the prefix is unreachable, so the shape of such an address is pinned + here rather than left to be discovered from a 404 in a deployment. + """ + self.assert_refused_here("/api/user/v2/some_plugin/thing/") + self.assert_refused_here("/api/user/v2/badges/") diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index b525a159f7a0..4d8615b27582 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -5,6 +5,7 @@ from math import ceil from unittest.mock import patch +import pytest from django.contrib.auth.models import User # pylint: disable=imported-auth-user from django.core.exceptions import ImproperlyConfigured from django.db import connection @@ -16,10 +17,10 @@ from rest_framework import status from rest_framework.test import APIClient, APITestCase +from common.djangoapps.student.models import PendingNameChange, UserProfile from common.djangoapps.student.tests.factories import AdminFactory, UserFactory from openedx.core.djangoapps.django_comment_common.models import Role from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user -from common.djangoapps.student.models import PendingNameChange, UserProfile from openedx.core.djangoapps.user_api.models import UserPreference from openedx.core.djangoapps.user_api.preferences.api import get_country_time_zones from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory @@ -1611,7 +1612,7 @@ def test_the_rows_are_fetched_through_the_declared_policy(self): """ for view_class in (UserViewSet, UserPreferenceViewSet): with patch.object(view_class, "scoping_policy", None, create=True): - with self.assertRaises(ImproperlyConfigured): + with pytest.raises(ImproperlyConfigured): view_class().get_queryset() @@ -1861,3 +1862,121 @@ def test_a_name_change_asked_for_with_the_token_the_session_carries_is_recorded( ) assert response.status_code == status.HTTP_201_CREATED assert PendingNameChange.objects.get(user=self.alice).new_name == "Alice Example" + + +class HiddenKeyPolicy: + """A record-visibility policy that drops the preferences stored under one name.""" + + def __init__(self, hidden_key): + self.hidden_key = hidden_key + self.calls = 0 + + def scope(self, queryset, subject): # pylint: disable=unused-argument + """Return the rows of ``queryset`` stored under any other name.""" + self.calls += 1 + return queryset.exclude(key=self.hidden_key) + + +@skip_unless_lms +class EmbeddedRowScopingTests(UserApiV2TestCase): + """ + Rows of one resource carried inside another come through the policy that governs them. + + A directory entry carries the preferences stored against its account, and + a stored preference asked for whole carries its owner's entry, which + carries those preferences again. Those rows belong to the other + collection, so the policy that decides which of them a caller may see is + that collection's and not the one the entry came from. Applying it is + arranged where the page is fetched, so it costs no query per row. + """ + + def directory_of(self, rows): + """Create ``rows`` users, each with two stored preferences.""" + made = [] + for index in range(rows): + user = UserFactory.create(username=f"row-{index:03d}", password=PASSWORD) + UserPreferenceFactory.create(user=user, key="pref-lang", value="en") + UserPreferenceFactory.create(user=user, key="time_zone", value="UTC") + made.append(user) + return made + + def test_the_preferences_inside_a_directory_entry_come_through_their_own_policy(self): + policy = HiddenKeyPolicy("pref-lang") + self.login(self.admin) + with patch.object(UserViewSet, "embedded_preference_policy", policy, create=True): + response = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "alice"})) + assert response.status_code == status.HTTP_200_OK + assert response.data["preferences"] == {} + assert policy.calls == 1 + + def test_a_preference_the_embedded_policy_keeps_is_still_carried(self): + policy = HiddenKeyPolicy("pref-lang") + self.login(self.admin) + with patch.object(UserViewSet, "embedded_preference_policy", policy, create=True): + response = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "bob"})) + assert response.status_code == status.HTTP_200_OK + assert response.data["preferences"] == {"time_zone": "UTC"} + + def test_the_preferences_inside_a_page_of_entries_come_through_their_own_policy(self): + self.directory_of(5) + policy = HiddenKeyPolicy("pref-lang") + self.login(self.admin) + with patch.object(UserViewSet, "embedded_preference_policy", policy, create=True): + response = self.client.get(reverse("user_v2:user_list"), {"page_size": 100}) + assert response.status_code == status.HTTP_200_OK + carried = {row["username"]: row["preferences"] for row in response.data["results"]} + assert [name for name, preferences in carried.items() if "pref-lang" in preferences] == [] + assert carried["row-000"] == {"time_zone": "UTC"} + + def test_narrowing_the_embedded_preferences_costs_no_query_per_row(self): + """ + The policy is applied where the page is fetched, so it is run once however many rows there are. + + One row would hide a per-row query that cancels a prefetch, so this is + measured at five rows and again at twenty-five. + """ + self.login(self.admin) + measured = {} + for rows in (5, 25): + User.objects.filter(username__startswith="row-").delete() + self.directory_of(rows) + policy = HiddenKeyPolicy("pref-lang") + with patch.object(UserViewSet, "embedded_preference_policy", policy, create=True): + # The first request of a signed-in client pays for its session, + # which is not part of what is being measured here. + self.client.get(reverse("user_v2:user_list"), {"page_size": 100}) + with CaptureQueriesContext(connection) as captured: + response = self.client.get(reverse("user_v2:user_list"), {"page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert len(response.data["results"]) == rows + 4 + measured[rows] = len(captured) + assert measured[5] == measured[25], measured + + def test_the_preferences_inside_an_embedded_owner_come_through_their_own_policy(self): + """A preference asked for whole carries its owner, whose own preferences are narrowed too.""" + policy = HiddenKeyPolicy("pref-lang") + self.login(self.admin) + with patch.object(UserPreferenceViewSet, "embedded_preference_policy", policy, create=True): + response = self.client.get( + reverse("user_v2:user_preference_detail", kwargs={"username": "alice", "key": "pref-lang"}), + {"view": "full"}, + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["user"]["preferences"] == {} + + def test_narrowing_an_embedded_owners_preferences_costs_no_query_per_row(self): + self.login(self.admin) + measured = {} + for rows in (5, 25): + User.objects.filter(username__startswith="row-").delete() + self.directory_of(rows) + policy = HiddenKeyPolicy("pref-lang") + address = reverse("user_v2:user_preference_list") + with patch.object(UserPreferenceViewSet, "embedded_preference_policy", policy, create=True): + self.client.get(address, {"view": "full", "page_size": 100}) + with CaptureQueriesContext(connection) as captured: + response = self.client.get(address, {"view": "full", "page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert len(response.data["results"]) == rows * 2 + 2 + measured[rows] = len(captured) + assert measured[5] == measured[25], measured diff --git a/openedx/core/djangoapps/user_api/v2/urls.py b/openedx/core/djangoapps/user_api/v2/urls.py index c9a299596cbf..fef6e8336093 100644 --- a/openedx/core/djangoapps/user_api/v2/urls.py +++ b/openedx/core/djangoapps/user_api/v2/urls.py @@ -123,5 +123,13 @@ class SnakeCaseRouter(SimpleRouter): # belongs to this version, including an address no route of it answers, # which is refused in the body the rest of this version answers with. The # route answers rather than reverses, so it carries no name. + # + # This claims the whole prefix: it matches every address under it that the + # routes above and the addresses named in OTHER_APP_ADDRESSES do not, and + # the service mounts it ahead of the patterns contributed by installed + # plugins. An address a plugin registers under this prefix is therefore + # reached by nothing and answered 404 here. A plugin that needs an address + # of its own serves it under a prefix of its own; one that has to extend + # this version is added to OTHER_APP_ADDRESSES or to the routes above. re_path(rf"^(?!{OTHER_APP_ADDRESSES}$).*$", UnknownAddressView.as_view()), ] diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 5523b3a590a1..33c9731dc964 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -5,7 +5,7 @@ from django.conf import settings from django.contrib.auth.models import User # pylint: disable=imported-auth-user from django.db import transaction -from django.db.models import F +from django.db.models import F, Prefetch from django.http import Http404 from django_filters.rest_framework import DjangoFilterBackend from django_ratelimit.core import is_ratelimited @@ -669,11 +669,17 @@ class UserViewSet( permission_classes = (permissions.IsAuthenticated, IsActiveUser, permissions.IsAdminUser) serializer_class = UserDirectorySerializer pagination_class = UserApiPagination - queryset = User.objects.all().prefetch_related("preferences").select_related("profile") + queryset = User.objects.all().select_related("profile") # Platform administrators may read every entry, so the policy keeps the # queryset whole; a narrower policy can replace it without touching the # filtering below. scoping_policy = FullScopePolicy() + #: The preferences carried inside an entry are rows of the stored + #: preference collection, so which of them a caller may see is that + #: collection's to decide and not this one's. It is declared separately for + #: that reason, and applied where the page is fetched rather than once per + #: entry, which would cost a query per row. + embedded_preference_policy = FullScopePolicy() lookup_field = "username" # The router's default lookup pattern excludes dots, which usernames allow. lookup_value_regex = settings.USERNAME_REGEX_PARTIAL @@ -690,6 +696,17 @@ class UserViewSet( response_presets = USER_PRESETS extra_query_params = RESPONSE_SHAPING_PARAMS + def get_queryset(self): + """Fetch the preferences carried inside each entry through the policy that governs them.""" + return super().get_queryset().prefetch_related( + Prefetch( + "preferences", + queryset=self.embedded_preference_policy.scope( + UserPreference.objects.all(), self.request.user, + ), + ), + ) + def list(self, request, *args, **kwargs): """Return a page of directory entries, shaped as the caller asked.""" return self.shape_page(super().list(request, *args, **kwargs), request) @@ -774,6 +791,11 @@ class UserPreferenceViewSet( .annotate(username=F("user__username")) ) scoping_policy = FullScopePolicy() + #: The entry of a preference's owner carries that owner's own preferences, + #: which are rows of this same collection but are reached through the + #: entry rather than as rows of the page, so the policy that governs them + #: is applied where they are fetched. + embedded_preference_policy = FullScopePolicy() filter_backends = (DjangoFilterBackend, StrictOrderingFilter) filterset_class = UserPreferenceFilterSet ordering_fields = PREFERENCE_SORT_FIELDS @@ -785,11 +807,18 @@ class UserPreferenceViewSet( response_presets = PREFERENCE_PRESETS extra_query_params = RESPONSE_SHAPING_PARAMS - def filter_queryset(self, queryset): - """Fetch each owner's own preferences too when they are about to be embedded.""" - queryset = super().filter_queryset(queryset) + def get_queryset(self): + """Fetch each owner's own preferences through the policy that governs them, when embedding.""" + queryset = super().get_queryset() if full_view_requested(getattr(self, "request", None)): - queryset = queryset.prefetch_related("user__preferences") + queryset = queryset.prefetch_related( + Prefetch( + "user__preferences", + queryset=self.embedded_preference_policy.scope( + UserPreference.objects.all(), self.request.user, + ), + ), + ) return queryset def get_object(self): From 5346d5b31e4513b30b36756e2404c1a08c7a374e Mon Sep 17 00:00:00 2001 From: Abdul Muqadim Date: Sun, 1 Nov 2026 07:54:03 +0500 Subject: [PATCH 26/61] fix: describe the superseded user addresses the same way in both services' documents --- cms/lib/spectacular.py | 12 ++- cms/lib/tests/test_spectacular.py | 150 +++++++++++++++++++++++++++++- lms/lib/spectacular.py | 75 +++++++++------ 3 files changed, 207 insertions(+), 30 deletions(-) diff --git a/cms/lib/spectacular.py b/cms/lib/spectacular.py index 662cf80c65f0..53819f34ac00 100644 --- a/cms/lib/spectacular.py +++ b/cms/lib/spectacular.py @@ -4,6 +4,8 @@ from drf_spectacular.openapi import AutoSchema +from lms.lib.spectacular import SupersededUserOperations + # Legacy operations superseded by a conforming address under /api/authoring/. # Each is listed in the truncated spelling as well as the full one: the routes # make the final character optional, so both addresses resolve, and which one @@ -72,7 +74,7 @@ def cms_mark_superseded_paths(result, generator, request, public): # pylint: di return result -class CmsAutoSchema(AutoSchema): +class CmsAutoSchema(SupersededUserOperations, AutoSchema): """ Give a colliding legacy address a distinct operationId. @@ -80,6 +82,14 @@ class CmsAutoSchema(AutoSchema): operationId, drf-spectacular would otherwise break the tie with a numeral suffix in registration order. The conforming address keeps the clean id; the deprecated one is suffixed ``_legacy``. + + This service also serves the user API at the same addresses the service + that replaces it does, and both publish an unauthenticated document of + everything they serve. The shared behaviour describes those addresses the + one way, so that a client generated from either document reads the same + signature and the same success code for the same request; it is taken from + where that API's own schema lives rather than copied, because two copies + of a description drift. """ def get_operation_id(self): diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py index 193f3c98c448..19d4090201f7 100644 --- a/cms/lib/tests/test_spectacular.py +++ b/cms/lib/tests/test_spectacular.py @@ -6,9 +6,10 @@ from django.conf import settings from django.test import SimpleTestCase +from django.test import TestCase as DjangoTestCase from django.urls import path as url_path from drf_spectacular.generators import SchemaGenerator -from drf_spectacular.settings import spectacular_settings +from drf_spectacular.settings import patched_settings, spectacular_settings from rest_framework import serializers, viewsets from rest_framework.response import Response from rest_framework.settings import api_settings @@ -20,6 +21,8 @@ cms_mark_migrated_paths, cms_mark_superseded_paths, ) +from lms.lib.spectacular import SUPERSEDED_USER_PATHS, superseded_bodies +from openedx.core.apidocs import get_api_docs_settings def _endpoint(path): @@ -215,3 +218,148 @@ def test_only_the_colliding_legacy_address_is_suffixed(self): # Already distinct from its conforming twin's id, so it keeps its name. assert ids["/api/authoring/v4/courses/"] == "v4_courses_list" assert ids["/api/contentstore/v4/home/courses/"] == "v4_home_courses_list" + + +#: What each superseded user operation this service serves is expected to +#: exchange: the media types of the body it reads, and the success code with +#: the body it answers with. ``None`` is a response carrying no body at all. +#: +#: The table is spelled out here rather than taken from the tests of the +#: service that serves the replacements, so that a change made to what one of +#: the two documents says about these addresses and not to the other is a +#: failure here rather than a difference a client only finds after generating +#: from both. +SUPERSEDED_USER_EXCHANGES = { + ("/api/user/v1/accounts", "get"): ([], {"200": "Account[]"}), + ("/api/user/v1/accounts/{username}", "get"): ([], {"200": "Account"}), + ("/api/user/v1/accounts/{username}", "patch"): (["application/merge-patch+json"], {"200": "Account"}), + ("/api/user/v1/accounts/search_emails", "post"): ( + ["application/json", "application/merge-patch+json"], {"200": "EmailSearchResult[]"}, + ), + ("/api/user/v1/accounts/{username}/deactivate/", "post"): ([], {"200": "Account"}), + ("/api/user/v1/accounts/name_change/", "post"): ( + ["application/json", "application/x-www-form-urlencoded", "multipart/form-data"], + {"201": None}, + ), + ("/api/user/v1/accounts/name_change/{username}/confirm/", "post"): ([], {"204": None}), + ("/api/user/v1/accounts/{username}/image", "post"): ( + ["image/gif", "image/jpeg", "image/pjpeg", "image/png", "multipart/form-data"], + {"204": None}, + ), + ("/api/user/v1/accounts/{username}/image", "delete"): ([], {"204": None}), + ("/api/user/v1/accounts/{username}/verification_status/", "get"): ([], {"200": "VerificationStatus"}), +} + +#: Every operation of a superseded user address this service serves, with the +#: name it is published under. The names are the ones both documents have +#: always carried: a client imports a function per name, so an operation that +#: comes back under a different one has been taken away from it. +SUPERSEDED_USER_OPERATION_IDS = { + ("/api/user/v1/accounts", "get"): "api_user_v1_accounts_retrieve", + ("/api/user/v1/accounts/name_change/", "post"): "api_user_v1_accounts_name_change_create", + ("/api/user/v1/accounts/name_change/{username}/confirm/", "post"): ( + "api_user_v1_accounts_name_change_confirm_create" + ), + ("/api/user/v1/accounts/search_emails", "post"): "api_user_v1_accounts_search_emails_create", + ("/api/user/v1/accounts/{username}", "get"): "api_user_v1_accounts_retrieve_2", + ("/api/user/v1/accounts/{username}", "patch"): "api_user_v1_accounts_partial_update", + ("/api/user/v1/accounts/{username}/deactivate/", "post"): "api_user_v1_accounts_deactivate_create", + ("/api/user/v1/accounts/{username}/image", "delete"): "api_user_v1_accounts_image_destroy", + ("/api/user/v1/accounts/{username}/image", "post"): "api_user_v1_accounts_image_create", + ("/api/user/v1/accounts/{username}/verification_status/", "get"): ( + "api_user_v1_accounts_verification_status_retrieve" + ), + ("/api/user/v1/accounts/{username}/verifications/", "get"): "api_user_v1_accounts_verifications_list", + ("/api/user/v1/forum_roles/{name}/users/", "get"): "api_user_v1_forum_roles_users_list", + ("/api/user/v1/me", "get"): "api_user_v1_me_retrieve", + ("/api/user/v1/preferences/time_zones/", "get"): "api_user_v1_preferences_time_zones_list", + ("/api/user/v1/preferences/{pref_key}/users/", "get"): "api_user_v1_preferences_users_list", + ("/api/user/v1/user_prefs/", "get"): "api_user_v1_user_prefs_list", + ("/api/user/v1/user_prefs/{id}/", "get"): "api_user_v1_user_prefs_retrieve", + ("/api/user/v1/users/", "get"): "api_user_v1_users_list", + ("/api/user/v1/users/{id}/", "get"): "api_user_v1_users_retrieve", +} + + +def _named_body(response): + """ + Return what a response carries: the component it names, or the shape itself. + + A component is named by its own name, suffixed ``[]`` where the body is an + array of it; a body described in place comes back as that description, and + a response with no body at all as ``None``. + """ + content = response.get("content") + if not content: + return None + body = content["application/json"]["schema"] + if body.get("type") == "array": + return f"{body['items']['$ref'].rsplit('/', 1)[-1]}[]" + if "$ref" not in body: + return body + return body["$ref"].rsplit("/", 1)[-1] + + +class SupersededUserOperationTest(DjangoTestCase): + """ + The user addresses this service serves beside the service that replaces them. + + Both services mount that API at the same addresses and both publish an + unauthenticated document of everything they serve, so what one of those + documents says about an address is what the other has to say too: the same + body on each side of the exchange, the same success code, the same + published name, and the same mark saying a replacement exists. A client + generated from this service's document would otherwise offer a different + signature, and no mark, for the very same request. + """ + + @classmethod + def setUpClass(cls): + super().setUpClass() + with patched_settings(get_api_docs_settings()): + cls.schema = SchemaGenerator().get_schema(request=None, public=True) + + def _operations(self): + """Every operation of a superseded address this document carries.""" + return { + (path, method): operation + for path in SUPERSEDED_USER_PATHS if path in self.schema["paths"] + for method, operation in self.schema["paths"][path].items() + if isinstance(operation, dict) and "operationId" in operation + } + + def test_this_service_serves_every_superseded_address(self): + """The marking and the bodies below are claims about all of them, not about some.""" + served = [path for path in SUPERSEDED_USER_PATHS if path in self.schema["paths"]] + assert served == list(SUPERSEDED_USER_PATHS) + + def test_every_operation_of_those_addresses_is_marked_superseded(self): + marked = {key: operation.get("deprecated") for key, operation in self._operations().items()} + assert marked == dict.fromkeys(SUPERSEDED_USER_OPERATION_IDS, True) + + def test_every_operation_keeps_the_name_it_is_published_under(self): + published = {key: operation["operationId"] for key, operation in self._operations().items()} + assert published == SUPERSEDED_USER_OPERATION_IDS + + def test_each_superseded_operation_publishes_what_it_reads_and_what_it_answers_with(self): + published = {} + for (address, method) in SUPERSEDED_USER_EXCHANGES: + operation = self.schema["paths"][address][method] + published[(address, method)] = ( + sorted((operation.get("requestBody") or {}).get("content", {})), + {code: _named_body(response) for code, response in operation["responses"].items()}, + ) + assert published == SUPERSEDED_USER_EXCHANGES + + def test_an_image_may_be_sent_as_the_whole_body_or_as_a_form_part(self): + """The forms are alternatives, and a body one of them needs is one the operation needs.""" + image = self.schema["paths"]["/api/user/v1/accounts/{username}/image"]["post"]["requestBody"] + assert image["required"] is True + assert sorted(image["content"]) == [ + "image/gif", "image/jpeg", "image/pjpeg", "image/png", "multipart/form-data", + ] + + def test_the_described_addresses_are_ones_this_document_marks_superseded(self): + described = {address for address, _method in superseded_bodies()} + marked = {re.sub(r"\{[\w-]+\}", "{}", address) for address in SUPERSEDED_USER_PATHS} + assert described <= marked, described - marked diff --git a/lms/lib/spectacular.py b/lms/lib/spectacular.py index a80cef111441..669611a9e038 100644 --- a/lms/lib/spectacular.py +++ b/lms/lib/spectacular.py @@ -207,39 +207,29 @@ def lms_api_filter(endpoints): return filtered -class LmsAutoSchema(AutoSchema): +class SupersededUserOperations: """ - Keep colliding addresses distinct, group each operation under its own area, - and name the bodies of the addresses this schema publishes as superseded, - marking a body the operation cannot be called without as one it needs. - - The slashless Enrollment v2 address tokenizes to the id of its conforming - twin, so the two would be told apart only by a numeral suffix handed out - in registration order, which says nothing about the operation and moves - when the routes move; it is suffixed ``_legacy`` instead, leaving the - conforming address the clean id, and the address listed above keeps the - name it is already published under. Every other address keeps the id and - the tag the generator derives for it, because a client generated from a - document takes a module from each operationId and groups it by tag, so - renaming either drops what a consumer already imports. + Describe the superseded user addresses wherever a service publishes them. + + Both services mount that API at the same addresses and both publish an + unauthenticated document of everything they serve, so what one of those + documents says about one of these addresses is what the other has to say + about it as well: a client generated from either reads the same body on + each side of the exchange, branches on the same success code, and imports + the same name. The behaviour is shared rather than restated in each + service's schema class, which is what keeps the two documents a deployment + publishes from describing one address two ways. + + Every address ``RENAMED_OPERATION_IDS`` does not name keeps the id the + generator derives for it, because a client generated from a document takes + a module from each operationId, so renaming one drops what a consumer + already imports. """ def get_operation_id(self): - """Keep each address that tokenizes to another one's id distinct from it.""" + """Keep the name an address is published under where describing its bodies would move it.""" operation_id = super().get_operation_id() - renamed = RENAMED_OPERATION_IDS.get((self.path, self.method, operation_id)) - if renamed is not None: - return renamed - if self.path == COLLIDING_LEGACY_PATH: - return f"{operation_id}_legacy" - return operation_id - - def get_tags(self): - """Name the area whenever the tag derived for a user address would name a version.""" - tags = super().get_tags() - if self.path.startswith(USER_PATH_PREFIX) and tags and _VERSION_TAG.fullmatch(tags[0]): - return [USER_TAG] - return tags + return RENAMED_OPERATION_IDS.get((self.path, self.method, operation_id), operation_id) def _get_request_body(self, direction="request"): """ @@ -276,6 +266,35 @@ def _superseded_bodies(self): return superseded_bodies().get((_PATH_PARAMETER.sub("{}", self.path), self.method)) +class LmsAutoSchema(SupersededUserOperations, AutoSchema): + """ + Keep colliding addresses distinct and group each operation under its own area. + + The slashless Enrollment v2 address tokenizes to the id of its conforming + twin, so the two would be told apart only by a numeral suffix, which says + which of the two addresses sorts first rather than anything about the + operation; it is suffixed ``_legacy`` instead, leaving the conforming + address the clean id, and the address listed above keeps the name it is + already published under. Each operation keeps the tag the generator derives + for it unless that tag names a version, because a client generated from a + document groups the operations it offers by tag. + """ + + def get_operation_id(self): + """Keep each address that tokenizes to another one's id distinct from it.""" + operation_id = super().get_operation_id() + if self.path == COLLIDING_LEGACY_PATH: + return f"{operation_id}_legacy" + return operation_id + + def get_tags(self): + """Name the area whenever the tag derived for a user address would name a version.""" + tags = super().get_tags() + if self.path.startswith(USER_PATH_PREFIX) and tags and _VERSION_TAG.fullmatch(tags[0]): + return [USER_TAG] + return tags + + def lms_mark_legacy_paths_deprecated(result, generator, request, public): # pylint: disable=unused-argument """Mark every superseded address ``deprecated: true``.""" for path, path_item in result.get("paths", {}).items(): From cd436b71a833b47c190460fc665f3affe609f40f Mon Sep 17 00:00:00 2001 From: Abdul Muqadim Date: Sun, 1 Nov 2026 08:04:56 +0500 Subject: [PATCH 27/61] fix: mount the prefix that answers unknown addresses after the applications' own --- lms/tests.py | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++- lms/urls.py | 14 ++++++-- 2 files changed, 104 insertions(+), 3 deletions(-) diff --git a/lms/tests.py b/lms/tests.py index 4a45b86a2699..5e5f6ad4f5dd 100644 --- a/lms/tests.py +++ b/lms/tests.py @@ -7,9 +7,18 @@ from django.conf import settings # pylint: disable=unused-import # noqa: F401 from django.core.cache import cache from django.test import TestCase, override_settings -from django.urls import path +from django.urls import Resolver404, URLResolver, path, resolve, reverse +from django.urls.resolvers import RegexPattern +from django.views.generic import View +from edx_django_utils.plugins import get_plugin_url_patterns +import lms.urls from openedx.core.apidocs import cached_schema_view +from openedx.core.djangoapps.plugins.constants import ProjectType +from openedx.core.djangoapps.user_api.v2.views import AccountViewSet as CurrentAccountViewSet +from openedx.core.djangoapps.user_api.v2.views import UnknownAddressView +from openedx.core.djangoapps.user_authn.views.login import LoginSessionView +from openedx.core.djangoapps.user_authn.views.register import RegistrationView log = logging.getLogger(__name__) @@ -86,4 +95,86 @@ def test_api_docs_schema_cache_per_urlconf(self): assert again.content == full.content +class ClaimedPrefixTests(TestCase): + """ + A prefix whose mount answers every address under it that its own routes do not. + + The current version of the user API is mounted that way, so nothing after + it is ever consulted for an address under that prefix. An installed + application contributes its patterns at one point in the URLconf, which + leaves the order between the two as what decides whether an address such an + application registers under the prefix can be served at all. + + The authentication application registers two addresses there, so that order + is measurable against real patterns rather than asserted about a copy. + """ + + LANDMARK = "api/user/v2/account/registration/" + + def _index_of(self, route): + """Where in the URLconf the pattern that answers that address sits.""" + for index, pattern in enumerate(lms.urls.urlpatterns): + try: + if pattern.resolve(route): + return index + except Resolver404: + continue + raise AssertionError(f"nothing in the URLconf answers {route}") + + def test_the_landmark_address_is_one_an_installed_application_contributes(self): + """The order below says nothing unless an application really registers an address here.""" + contributed = URLResolver(RegexPattern(r"^/"), get_plugin_url_patterns(ProjectType.LMS)) + assert contributed.resolve(f"/{self.LANDMARK}").func.cls is RegistrationView + + def test_the_mount_that_claims_the_prefix_is_consulted_after_those_applications(self): + claimed = self._index_of("api/user/v2/nothing_here/") + assert claimed > self._index_of(self.LANDMARK) + + def test_an_address_an_application_registers_under_the_prefix_reaches_its_view(self): + class _Calendars(View): + """Stand-in for a view an installed application serves under that prefix.""" + + patterns = list(lms.urls.urlpatterns) + patterns.insert( + self._index_of(self.LANDMARK) + 1, + path("api/user/v2/calendars/", _Calendars.as_view()), + ) + resolved = URLResolver(RegexPattern(r"^/"), patterns).resolve("/api/user/v2/calendars/") + assert resolved.func.view_class is _Calendars, resolved.func.view_class + + def test_an_address_nothing_registers_is_still_answered_by_the_mount(self): + assert resolve("/api/user/v2/nothing_here/").func.cls is UnknownAddressView + + def test_the_version_serves_its_own_resources(self): + assert resolve("/api/user/v2/accounts/").func.cls is CurrentAccountViewSet + + def test_the_addresses_another_application_serves_under_the_prefix_still_reach_it(self): + reached = { + address: resolve(address).func.cls + for address in ( + "/api/user/v2/account/registration/", + "/api/user/v2/account/login_session/", + ) + } + assert reached == { + "/api/user/v2/account/registration/": RegistrationView, + "/api/user/v2/account/login_session/": LoginSessionView, + } + + def test_those_addresses_keep_the_names_they_are_reversed_by(self): + reversed_names = { + "user_api_registration_v2": reverse("user_api_registration_v2"), + "user_api_login_session": reverse("user_api_login_session", kwargs={"api_version": "v2"}), + } + assert reversed_names == { + "user_api_registration_v2": "/api/user/v2/account/registration/", + "user_api_login_session": "/api/user/v2/account/login_session/", + } + + def test_one_of_them_sent_without_its_trailing_slash_is_still_redirected_to_it(self): + response = self.client.get("/api/user/v2/account/registration") + assert response.status_code == 301 + assert response["Location"] == "/api/user/v2/account/registration/" + + urlpatterns = [path('api-docs/schema/', cached_schema_view())] diff --git a/lms/urls.py b/lms/urls.py index 8a4c1cc929ae..dded010ee06e 100644 --- a/lms/urls.py +++ b/lms/urls.py @@ -141,8 +141,8 @@ # Course API path('api/courses/', include('lms.djangoapps.course_api.urls')), - # User API endpoints - path('api/user/v2/', include('openedx.core.djangoapps.user_api.v2.urls')), + # User API endpoints. The current version is mounted at the end of this + # file instead, for the reason given there. path('api/user/', include('openedx.core.djangoapps.user_api.urls')), # Note: these are older versions of the User API that will eventually be # subsumed by api/user listed above. @@ -1078,6 +1078,16 @@ def _enterprise_enabled(): urlpatterns.extend(get_plugin_url_patterns(ProjectType.LMS)) +# The current version of the User API, mounted after everything an installed +# application contributes. That mount answers every address under its prefix +# that its own routes do not serve, so an address registered under the prefix +# by anything mounted later is reached by nothing; mounting it here leaves such +# an address to the application that registers it, and leaves the mount only +# the addresses nothing serves. +urlpatterns += [ + path('api/user/v2/', include('openedx.core.djangoapps.user_api.v2.urls')), +] + # Course Home API urls urlpatterns += [ # This is a BFF ("backend for frontend") djangoapp for the Learning MFE (like courseware_api). From e9331333b460b0bcc39691d8cac4d0a2ca37a0b0 Mon Sep 17 00:00:00 2001 From: Abdul Muqadim Date: Sun, 1 Nov 2026 08:17:37 +0500 Subject: [PATCH 28/61] fix: serve the document published for client generation from the cache as well --- lms/tests.py | 107 +++++++++++++++++++++++++++++++++++++--- lms/urls.py | 11 ++++- openedx/core/apidocs.py | 38 ++++++++------ 3 files changed, 134 insertions(+), 22 deletions(-) diff --git a/lms/tests.py b/lms/tests.py index 5e5f6ad4f5dd..8738cface569 100644 --- a/lms/tests.py +++ b/lms/tests.py @@ -3,16 +3,19 @@ import logging import mimetypes +from unittest import mock from django.conf import settings # pylint: disable=unused-import # noqa: F401 from django.core.cache import cache +from django.http import HttpResponse from django.test import TestCase, override_settings from django.urls import Resolver404, URLResolver, path, resolve, reverse from django.urls.resolvers import RegexPattern -from django.views.generic import View +from drf_spectacular.generators import SchemaGenerator from edx_django_utils.plugins import get_plugin_url_patterns import lms.urls +from common.djangoapps.student.tests.factories import TEST_PASSWORD, UserFactory from openedx.core.apidocs import cached_schema_view from openedx.core.djangoapps.plugins.constants import ProjectType from openedx.core.djangoapps.user_api.v2.views import AccountViewSet as CurrentAccountViewSet @@ -95,6 +98,101 @@ def test_api_docs_schema_cache_per_urlconf(self): assert again.content == full.content +class NarrowSchemaCacheTests(TestCase): + """ + The document this service publishes for client generation is served from the cache. + + It is public, it costs a full generation pass, and it is the one schema + address with nothing in front of it. The cache may only serve it if every + caller is given the same document, so that is measured here too. + """ + + ADDRESS = '/lms-api/schema/' + + def _generations(self): + """Count the passes the generator makes, leaving it otherwise alone.""" + return mock.patch.object( + SchemaGenerator, + 'get_schema', + autospec=True, + side_effect=SchemaGenerator.get_schema, + ) + + @override_settings( + OPENAPI_CACHE_TIMEOUT=60, + CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}, + ) + def test_two_requests_generate_the_document_once(self): + cache.clear() + with self._generations() as generated: + first = self.client.get(self.ADDRESS) + second = self.client.get(self.ADDRESS) + assert first.status_code == 200 + assert first.content.startswith(b'openapi:') + assert second.content == first.content + assert second['Content-Type'] == first['Content-Type'] + assert generated.call_count == 1 + + @override_settings( + OPENAPI_CACHE_TIMEOUT=0, + CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}, + ) + def test_without_a_timeout_each_request_generates_it_again(self): + """A deployment that turns the cache off is served exactly what it was before.""" + cache.clear() + with self._generations() as generated: + first = self.client.get(self.ADDRESS) + second = self.client.get(self.ADDRESS) + assert first.status_code == 200 + assert second.content == first.content + assert generated.call_count == 2 + + @override_settings( + OPENAPI_CACHE_TIMEOUT=60, + CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}, + ) + def test_the_two_documents_this_service_serves_are_not_stored_under_one_key(self): + cache.clear() + narrow = self.client.get(self.ADDRESS) + wide = self.client.get('/api-docs/schema/') + assert narrow.status_code == 200 and wide.status_code == 200 + assert len(narrow.content) < len(wide.content) + assert self.client.get(self.ADDRESS).content == narrow.content + assert self.client.get('/api-docs/schema/').content == wide.content + + @override_settings( + OPENAPI_CACHE_TIMEOUT=60, + CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}, + ) + def test_another_language_is_not_served_the_document_already_stored(self): + cache.clear() + english = self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='en') + spanish = self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='es-419') + assert english.status_code == 200 and spanish.status_code == 200 + assert english.content != spanish.content + assert self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='en').content == english.content + + def test_every_caller_is_given_the_same_document(self): + """What the cache may hold: one document, not one per caller.""" + staff = UserFactory.create(username='narrowstaff', password=TEST_PASSWORD, is_staff=True) + root = UserFactory.create( + username='narrowroot', password=TEST_PASSWORD, is_staff=True, is_superuser=True, + ) + anonymous = self.client.get(self.ADDRESS) + served = {'anonymous': anonymous.content} + for user in (staff, root): + assert self.client.login(username=user.username, password=TEST_PASSWORD) + served[user.username] = self.client.get(self.ADDRESS).content + self.client.logout() + assert anonymous.status_code == 200 + assert set(served.values()) == {anonymous.content} + + +def _calendars_of_an_application(request): # pylint: disable=unused-argument + """Stand-in for an address an installed application serves under a claimed prefix.""" + return HttpResponse() + + class ClaimedPrefixTests(TestCase): """ A prefix whose mount answers every address under it that its own routes do not. @@ -131,16 +229,13 @@ def test_the_mount_that_claims_the_prefix_is_consulted_after_those_applications( assert claimed > self._index_of(self.LANDMARK) def test_an_address_an_application_registers_under_the_prefix_reaches_its_view(self): - class _Calendars(View): - """Stand-in for a view an installed application serves under that prefix.""" - patterns = list(lms.urls.urlpatterns) patterns.insert( self._index_of(self.LANDMARK) + 1, - path("api/user/v2/calendars/", _Calendars.as_view()), + path("api/user/v2/calendars/", _calendars_of_an_application), ) resolved = URLResolver(RegexPattern(r"^/"), patterns).resolve("/api/user/v2/calendars/") - assert resolved.func.view_class is _Calendars, resolved.func.view_class + assert resolved.func is _calendars_of_an_application, resolved.func def test_an_address_nothing_registers_is_still_answered_by_the_mount(self): assert resolve("/api/user/v2/nothing_here/").func.cls is UnknownAddressView diff --git a/lms/urls.py b/lms/urls.py index dded010ee06e..d1b78cbecdbd 100644 --- a/lms/urls.py +++ b/lms/urls.py @@ -1150,7 +1150,14 @@ def _enterprise_enabled(): path('xqueue/', include((submissions_urls, 'submissions'), namespace='submissions')), ] -# LMS API schema for openedx-platform-sdk generation. +# LMS API schema for openedx-platform-sdk generation. Served from the same +# cache the service-wide document uses: it is public, it is generated from +# scratch on every request, and it grew several times over when this API was +# added to it. urlpatterns += [ - path('lms-api/schema/', SpectacularAPIView.as_view(), name='lms-schema'), + path( + 'lms-api/schema/', + cached_schema_view(SpectacularAPIView.as_view(), resource='lms-api-schema'), + name='lms-schema', + ), ] diff --git a/openedx/core/apidocs.py b/openedx/core/apidocs.py index 05f8f59888f0..1450e7a27c52 100644 --- a/openedx/core/apidocs.py +++ b/openedx/core/apidocs.py @@ -84,9 +84,16 @@ def untag_deprecated_operations(result, generator, request, public): # pylint: return result -def cached_schema_view(): +def cached_schema_view(view=None, resource='apidocs-schema'): """ - Build the ``/api-docs`` schema view, caching the rendered document compressed. + Serve a generated schema document from the cache, stored compressed. + + With no arguments this builds the service-wide ``/api-docs`` view. A view + passed in is served the same way under the ``resource`` name given, which + is what keeps each document a service publishes in a key space of its own: + the narrower document each service serves for client generation is + otherwise regenerated on every anonymous request, and it is the one schema + address with nothing in front of it. ``cache_page`` stores the pickled ``Response``, which for this schema is over memcached's default 1MB item limit. ``CACHES['default']`` sets @@ -95,16 +102,18 @@ def cached_schema_view(): whole schema on every request. Storing the zlib-compressed body instead brings it to roughly a tenth of the limit. - The key covers the URLconf, the path, the negotiated representation and the - active language. The URLconf because the LMS and the CMS serve this view at - the same path and share one cache by default, so without it whichever - service generated first would serve its document at the other's URL. The - language because drf-spectacular renders the document under whatever - language is active, and ``LocaleMiddleware`` sets that from the request's - cookie or ``Accept-Language`` before this runs. Nothing else in it varies by - requester -- ``SERVE_PUBLIC`` defaults to ``True``, ``SERVE_*`` cannot be set - through ``custom_settings``, and ``API_DOCS_SETTINGS`` sets ``'SERVERS': []`` - so no ``servers`` block is emitted. + The key covers the resource, the URLconf, the path, the negotiated + representation and the active language. The URLconf because the LMS and the + CMS serve this view at the same path and share one cache by default, so + without it whichever service generated first would serve its document at + the other's URL. The language because drf-spectacular renders the document + under whatever language is active, and ``LocaleMiddleware`` sets that from + the request's cookie or ``Accept-Language`` before this runs. + + The key does not cover who asked: a document stored here is served to every + later caller, so an address wrapped this way must publish one document for + all of them. The narrower document is held to that by a test that asks for + it anonymously, as staff and as a superuser and compares the three. Only GET and HEAD are cached, as ``cache_page`` did: DRF answers OPTIONS on this view with a 200 metadata document, which would otherwise be stored and @@ -118,7 +127,8 @@ def cached_schema_view(): """ from drf_spectacular.views import SpectacularAPIView # pylint: disable=import-outside-toplevel - view = SpectacularAPIView.as_view(custom_settings=get_api_docs_settings()) + if view is None: + view = SpectacularAPIView.as_view(custom_settings=get_api_docs_settings()) def _response(content_type, body): """Build the response, marking it uncacheable downstream as drf-yasg did.""" @@ -132,7 +142,7 @@ def schema_view(request, *args, **kwargs): return view(request, *args, **kwargs) cache_key = get_cache_key( - resource='apidocs-schema', + resource=resource, urlconf=settings.ROOT_URLCONF, path=request.get_full_path(), accept=request.META.get('HTTP_ACCEPT', ''), From 7cc2a8ec0a7d7c6507ba6c63784be6d7bc77cff7 Mon Sep 17 00:00:00 2001 From: Abdul Muqadim Date: Sun, 1 Nov 2026 09:12:21 +0500 Subject: [PATCH 29/61] test: hold the settings module the published reference is generated from --- cms/lib/tests/test_spectacular.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py index 19d4090201f7..2051f7a1b14b 100644 --- a/cms/lib/tests/test_spectacular.py +++ b/cms/lib/tests/test_spectacular.py @@ -181,6 +181,17 @@ def test_environments_do_not_replace_the_common_settings(self): # A hook is set by its quoted key; a comment that names one is fine. assert not re.search(r"_HOOKS['\"]", source), module + def test_the_module_the_published_reference_is_generated_from_inherits_this_configuration(self): + """ + It takes the hooks and the prefix by inheritance rather than restating them. + + The committed reference for this service is generated under that + module, and assigning the key there would replace this configuration + wholesale, as the two modules above do -- which would publish the whole + service under no title instead of this API's own surface. + """ + assert "SPECTACULAR_SETTINGS" not in self._source("cms/envs/development.py") + class _EmptySerializer(serializers.Serializer): # pylint: disable=abstract-method pass From 2aef2177e465a473e042101b1807f0448e58dbb3 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 07:58:41 +0500 Subject: [PATCH 30/61] fix: carry inside a preference only the owner entries the caller may be given --- .../djangoapps/user_api/v2/serializers.py | 21 ++- .../user_api/v2/tests/test_query_counts.py | 34 +++- .../user_api/v2/tests/test_views.py | 156 ++++++++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 31 ++++ 4 files changed, 237 insertions(+), 5 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/serializers.py b/openedx/core/djangoapps/user_api/v2/serializers.py index c90d28676782..97335013029f 100644 --- a/openedx/core/djangoapps/user_api/v2/serializers.py +++ b/openedx/core/djangoapps/user_api/v2/serializers.py @@ -25,6 +25,13 @@ #: Properties the ``minimal`` preset keeps of a stored preference. PREFERENCE_MINIMAL_FIELDS = ("username", "key", "value") +#: Context member naming the users whose whole directory entry a response may +#: carry, by id. A directory entry belongs to the user collection, so which +#: entries a caller may be given is that collection's decision; the view +#: settles it for a whole page and leaves the answer here, so that reading it +#: costs no query per row. +EMBEDDABLE_OWNER_IDS = "embeddable_owner_ids" + class ErrorResponse(ErrorResponseSerializer): # pylint: disable=abstract-method """ @@ -159,8 +166,9 @@ class UserPreferenceRecordSerializer(serializers.ModelSerializer): A stored preference, identified by the user that owns it and its key. ``user`` carries the owner's whole directory entry and is included only - when the caller asks for the ``full`` response preset; by default the - owner appears as the ``username`` string alone. + when the caller asks for the ``full`` response preset and is one the + caller may be given; by default the owner appears as the ``username`` + string alone. """ url = serializers.SerializerMethodField(help_text="Absolute URL of this preference.") @@ -172,7 +180,10 @@ class UserPreferenceRecordSerializer(serializers.ModelSerializer): key = serializers.CharField(read_only=True, help_text="Name of the preference.") value = serializers.CharField(read_only=True, help_text="Stored value of the preference.") user = serializers.SerializerMethodField( - help_text="Directory entry of the owning user; null unless the full response preset is asked for.", + help_text=( + "Directory entry of the owning user; null unless the full response preset is asked " + "for and the entry is one the caller may be given." + ), ) class Meta: @@ -192,9 +203,11 @@ def get_url(self, preference): @extend_schema_field(UserDirectorySerializer(allow_null=True)) def get_user(self, preference): - """Embed the owner only when the caller asked for the full preset.""" + """Embed the owner's entry when the caller asked for the full preset and may be given it.""" if not full_view_requested(self.context.get("request")): return None + if preference.user_id not in (self.context.get(EMBEDDABLE_OWNER_IDS) or ()): + return None return UserDirectorySerializer(preference.user, context=self.context).data diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py b/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py index e8cc522fa8f1..fc41425a9e89 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py @@ -22,8 +22,15 @@ USER_LIST_QUERIES = 16 USER_DETAIL_QUERIES = 15 PREFERENCE_LIST_QUERIES = 15 -PREFERENCE_LIST_FULL_VIEW_QUERIES = 16 +#: One more than the list costs without the preset: the owners whose entry +#: a page may carry are resolved for the whole page in a single query, +#: whatever the number of rows. +PREFERENCE_LIST_FULL_VIEW_QUERIES = 17 PREFERENCE_DETAIL_QUERIES = 14 +#: What the same address costs with the owner's entry asked for: the entry's +#: own preferences, and the one query that settles which owners' entries may +#: be carried. +PREFERENCE_DETAIL_FULL_VIEW_QUERIES = 16 TIME_ZONE_LIST_QUERIES = 13 #: Address of the stored-preference list this version replaces, and the key it @@ -150,6 +157,31 @@ def test_member_query_counts(client, directory, django_assert_num_queries): assert response.json()["value"] == "en" +@pytest.mark.django_db +@pytest.mark.parametrize("directory", [5], indirect=True) +@skip_unless_lms +def test_the_member_address_pays_a_flat_cost_for_the_entry_it_carries( + client, directory, django_assert_num_queries, +): # pylint: disable=unused-argument + """ + Asking for one preference whole costs the same whatever else is stored. + + The entry the row carries brings the owner's own preferences with it and + the owners whose entry may be carried are resolved once, so the cost is + the member cost plus a fixed amount and does not move with the number of + rows the collection holds. + """ + address = reverse( + "user_v2:user_preference_detail", kwargs={"username": "counted0", "key": "pref-lang"}, + ) + with django_assert_num_queries(PREFERENCE_DETAIL_FULL_VIEW_QUERIES): + response = client.get(address, {"view": "full"}) + body = response.json() + assert body["value"] == "en" + assert body["user"]["username"] == "counted0" + assert body["user"]["preferences"] == {"pref-lang": "en", "time_zone": "UTC"} + + @pytest.mark.django_db @pytest.mark.parametrize("directory", ROW_COUNTS, indirect=True) @skip_unless_lms diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index 4d8615b27582..b3867dc44b0f 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -1980,3 +1980,159 @@ def test_narrowing_an_embedded_owners_preferences_costs_no_query_per_row(self): assert len(response.data["results"]) == rows * 2 + 2 measured[rows] = len(captured) assert measured[5] == measured[25], measured + + +class HiddenOwnerPolicy: + """A record-visibility policy over owners that hides one of them and counts its calls.""" + + def __init__(self, hidden_username): + self.hidden_username = hidden_username + self.calls = 0 + + def scope(self, queryset, subject): # pylint: disable=unused-argument + """Return the rows of ``queryset`` that are not the hidden owner.""" + self.calls += 1 + return queryset.exclude(username=self.hidden_username) + + +@skip_unless_lms +class EmbeddedOwnerScopingTests(UserApiV2TestCase): + """ + The owner carried inside a stored preference comes through the policy that governs owners. + + A preference asked for whole carries its owner's directory entry, which is + a row of the directory and not of the preference collection, so which + owners a caller may see is the directory's decision. An entry the caller + may not see is left out of the answer; the preference itself is still + returned, named by the owner it is stored against, because which + preferences come back is the preference collection's own decision. + """ + + def preferences_of(self, rows): + """Create ``rows`` users, each with two stored preferences.""" + for index in range(rows): + user = UserFactory.create(username=f"row-{index:03d}", password=PASSWORD) + UserPreferenceFactory.create(user=user, key="pref-lang", value="en") + UserPreferenceFactory.create(user=user, key="time_zone", value="UTC") + + def test_an_owner_the_embedded_policy_leaves_out_is_not_carried_inside_a_page(self): + policy = HiddenOwnerPolicy("alice") + self.login(self.admin) + with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): + response = self.client.get( + reverse("user_v2:user_preference_list"), {"view": "full", "page_size": 100}, + ) + assert response.status_code == status.HTTP_200_OK + carried = {row["username"]: row["user"] for row in response.data["results"]} + assert set(carried) == {"alice", "bob"} + assert carried["alice"] is None + assert carried["bob"]["username"] == "bob" + assert carried["bob"]["email"] == "bob@example.com" + + def test_an_owner_the_embedded_policy_leaves_out_is_not_carried_inside_one_preference(self): + policy = HiddenOwnerPolicy("alice") + self.login(self.admin) + with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): + response = self.client.get( + reverse("user_v2:user_preference_detail", kwargs={"username": "alice", "key": "pref-lang"}), + {"view": "full"}, + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["user"] is None + assert response.data["username"] == "alice" + assert response.data["key"] == "pref-lang" + assert response.data["value"] == "en" + + def test_an_owner_the_embedded_policy_keeps_is_still_carried(self): + """ + An owner the policy keeps comes back whole. + + This is a control rather than a guard: it reads a preference whose + owner the policy keeps, so it is green whether or not the policy is + consulted. It is here to show the answer is not narrowed too far. + """ + policy = HiddenOwnerPolicy("alice") + self.login(self.admin) + with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): + response = self.client.get( + reverse("user_v2:user_preference_detail", kwargs={"username": "bob", "key": "time_zone"}), + {"view": "full"}, + ) + assert response.status_code == status.HTTP_200_OK + assert response.data["user"]["username"] == "bob" + assert response.data["user"]["preferences"] == {"time_zone": "UTC"} + + def test_the_owners_of_a_page_are_resolved_once_however_many_rows_it_carries(self): + """ + The owners a page may carry are settled for the whole page, so the cost does not grow with rows. + + One row would hide a per-row lookup, so this is measured at five rows + and again at twenty-five, and the policy is asked once either way. + """ + self.login(self.admin) + measured = {} + address = reverse("user_v2:user_preference_list") + for rows in (5, 25): + User.objects.filter(username__startswith="row-").delete() + self.preferences_of(rows) + policy = HiddenOwnerPolicy("alice") + with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): + # The first request of a signed-in client pays for its session, + # which is not part of what is being measured here. + self.client.get(address, {"view": "full", "page_size": 100}) + with CaptureQueriesContext(connection) as captured: + response = self.client.get(address, {"view": "full", "page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert len(response.data["results"]) == rows * 2 + 2 + assert policy.calls == 2, "the owners of a page are resolved once per request" + measured[rows] = len(captured) + assert measured[5] == measured[25], measured + + def test_no_owner_is_resolved_for_a_page_that_carries_none(self): + """A page that does not carry its owners does not ask which owners it could carry.""" + self.login(self.admin) + policy = HiddenOwnerPolicy("alice") + with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): + response = self.client.get(reverse("user_v2:user_preference_list"), {"page_size": 100}) + assert response.status_code == status.HTTP_200_OK + assert [row["username"] for row in response.data["results"]] == ["alice", "bob"] + assert policy.calls == 0 + + def test_a_policy_answering_with_a_collection_of_its_own_still_narrows_what_is_carried(self): + """ + A policy need not narrow the collection it is handed for its answer to hold. + + The owners of the page are taken out of what the policy answers with, + so a policy that builds its own collection instead of narrowing the + one it is given narrows the page just the same. + """ + class OwnCollectionPolicy: + """A policy that answers with a collection of its own.""" + + def scope(self, queryset, subject): # pylint: disable=unused-argument + """Return the one owner this policy keeps, built without the given collection.""" + return User.objects.filter(username="bob") + + self.login(self.admin) + with patch.object(UserPreferenceViewSet, "embedded_user_policy", OwnCollectionPolicy(), create=True): + response = self.client.get( + reverse("user_v2:user_preference_list"), {"view": "full", "page_size": 100}, + ) + assert response.status_code == status.HTTP_200_OK + carried = {row["username"]: row["user"] for row in response.data["results"]} + assert carried["alice"] is None + assert carried["bob"]["username"] == "bob" + + def test_the_embedded_owner_policy_is_declared_by_the_view_that_embeds(self): + """ + The view names the policy that governs the owners it carries, rather than inheriting one. + + A view that inherited the default would be left with no policy over + the entries it embeds, which is how a view that stopped declaring one + is told apart from a view whose policy happens to keep every owner. + """ + declared = vars(UserPreferenceViewSet).get("embedded_user_policy") + assert declared is not None, "UserPreferenceViewSet declares no policy over the owners it carries" + assert callable(getattr(declared, "scope", None)), ( + "UserPreferenceViewSet declares a policy over the owners it carries that cannot narrow rows" + ) diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 33c9731dc964..4f6f66297e49 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -61,6 +61,7 @@ ACCOUNT_DEFAULT_SORT, ACCOUNT_MINIMAL_FIELDS, EMAIL_SEARCH_MAX_ADDRESSES, + EMBEDDABLE_OWNER_IDS, FULL_VIEW, MINIMAL_VIEW, PREFERENCE_MINIMAL_FIELDS, @@ -796,6 +797,15 @@ class UserPreferenceViewSet( #: entry rather than as rows of the page, so the policy that governs them #: is applied where they are fetched. embedded_preference_policy = FullScopePolicy() + #: The owner's entry is itself a row of the user collection rather than of + #: this one, so which owners a caller may be given the entry of is that + #: collection's decision and is declared separately for that reason. It is + #: settled for a whole page in one query, because asking it of each row in + #: turn would cost a query per row. An owner the policy leaves out is left + #: out of the row that carries it; the row itself stays, named by the owner + #: it is stored against, because which rows come back is this collection's + #: own decision and is made by the policy above it. + embedded_user_policy = FullScopePolicy() filter_backends = (DjangoFilterBackend, StrictOrderingFilter) filterset_class = UserPreferenceFilterSet ordering_fields = PREFERENCE_SORT_FIELDS @@ -821,6 +831,27 @@ def get_queryset(self): ) return queryset + def get_serializer(self, *args, **kwargs): + """Build the serializer, having settled which owners the rows it is given may carry.""" + serializer = super().get_serializer(*args, **kwargs) + if args and full_view_requested(getattr(self, "request", None)): + serializer.context[EMBEDDABLE_OWNER_IDS] = self._embeddable_owner_ids(args[0]) + return serializer + + def _embeddable_owner_ids(self, rows): + """Return the ids of the owners of ``rows`` whose entry the caller may be given, in one query.""" + if isinstance(rows, UserPreference): + rows = [rows] + owner_ids = {row.user_id for row in rows} + if not owner_ids: + return frozenset() + # The owners of the page are taken out of the policy's answer rather + # than handed to it: a policy free to answer with a collection of its + # own is then still narrowed to this page, and what comes back is the + # size of the page rather than the size of the collection. + owners = self.embedded_user_policy.scope(User.objects.all(), self.request.user) + return frozenset(owners.filter(pk__in=owner_ids).values_list("pk", flat=True)) + def get_object(self): """Look the preference up by the username and key that identify it.""" try: From 33f7e929230b32dee57cce8e100733d29b43e005 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 08:04:42 +0500 Subject: [PATCH 31/61] fix: name the refusal of an address more than one account answers to --- openedx/core/djangoapps/profile_images/v2/views.py | 4 ++-- openedx/core/djangoapps/user_api/v2/errors.py | 13 +++++++++++++ .../user_api/v2/tests/test_account_views.py | 7 ++++--- .../user_api/v2/tests/test_name_change_views.py | 2 +- openedx/core/djangoapps/user_api/v2/views.py | 4 ++-- 5 files changed, 22 insertions(+), 8 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index 864c9b52a9d3..b46980f68e6b 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -22,7 +22,7 @@ from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names, set_has_profile_image from openedx.core.djangoapps.user_api.errors import UserNotFound -from openedx.core.djangoapps.user_api.v2.errors import CatalogedRequestErrorsMixin +from openedx.core.djangoapps.user_api.v2.errors import AmbiguousAccountName, CatalogedRequestErrorsMixin from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser from openedx.core.djangoapps.user_api.v2.serializers import ErrorResponse from openedx.core.djangoapps.user_api.v2.view_utils import ( @@ -272,7 +272,7 @@ def _record_image(self, username, is_uploaded): raise NotFound from exc except MultipleObjectsReturned as exc: log.info("Profile image not recorded for %r: the name answers for more than one account", username) - raise ValidationError({ + raise AmbiguousAccountName({ api_settings.NON_FIELD_ERRORS_KEY: [AMBIGUOUS_ACCOUNT_ADDRESS], }) from exc diff --git a/openedx/core/djangoapps/user_api/v2/errors.py b/openedx/core/djangoapps/user_api/v2/errors.py index f21dee73dc4c..6bd6b184f0cf 100644 --- a/openedx/core/djangoapps/user_api/v2/errors.py +++ b/openedx/core/djangoapps/user_api/v2/errors.py @@ -7,6 +7,7 @@ NotFound, ParseError, UnsupportedMediaType, + ValidationError, ) from rest_framework.settings import api_settings @@ -27,6 +28,17 @@ class MalformedBody(ParseError): """A request body that is not well formed in the media type it was sent as.""" +class AmbiguousAccountName(ValidationError): + """ + An address answered by more than one account, naming no one of them. + + The refusal is one about what the request asked for, so it keeps the + status of the refusals beside it; what it adds is a name for the one + condition, which a caller can tell apart from a value it sent being + wrong and can act on by naming an account as it is stored. + """ + + class RetiredAccount(NotFound): """ An account that has been retired, addressed by something it used to hold. @@ -49,6 +61,7 @@ def __init__(self, detail=None, can_cancel_retirement=False, retirement_id=None) register_error_type(UnreadableRepresentation, "unsupported-media-type", "Unsupported Media Type") register_error_type(MalformedBody, "malformed-body", "Malformed Request Body") register_error_type(RetiredAccount, "user/retired-account", "Retired Account") +register_error_type(AmbiguousAccountName, "user/ambiguous-account-name", "Ambiguous Account Name") def refusal_sentence(refusals): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 7da854967419..b9075b49cd5b 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -763,8 +763,9 @@ def two_accounts(request, usernames=None, **kwargs): # pylint: disable=unused-a with mock.patch(ACCOUNT_LOOKUP, two_accounts): response = self.client.get(self.detail_url("owner-caller ")) envelope = assert_error_envelope( - response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="user/ambiguous-account-name", ) + assert envelope["title"] == "Ambiguous Account Name" assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} def test_a_member_address_one_of_several_accounts_is_stored_under_carries_that_one(self): @@ -2046,7 +2047,7 @@ def test_a_deactivation_whose_address_names_more_than_one_account_deactivates_no envelope = assert_error_envelope( self.client.post(address), expected_status=status.HTTP_400_BAD_REQUEST, - expected_type_slug="validation", + expected_type_slug="user/ambiguous-account-name", ) assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} for user in (self.owner, self.other, self.staff): @@ -2085,7 +2086,7 @@ def test_an_image_whose_address_names_more_than_one_account_is_left_alone(self): envelope = assert_error_envelope( self.client.delete(address), expected_status=status.HTTP_400_BAD_REQUEST, - expected_type_slug="validation", + expected_type_slug="user/ambiguous-account-name", ) assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} self.owner.profile.refresh_from_db() diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py index 4321e5a49e33..cdd8cc294a39 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py @@ -470,7 +470,7 @@ def test_an_address_naming_more_than_one_account_changes_nothing(self): envelope = assert_error_envelope( self.client.post(self.url), expected_status=status.HTTP_400_BAD_REQUEST, - expected_type_slug="validation", + expected_type_slug="user/ambiguous-account-name", ) assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} assert self.profile_name(self.owner) == "Original Name" diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 4f6f66297e49..2885dc2dd48a 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -44,7 +44,7 @@ from openedx.core.djangoapps.user_api.preferences.api import get_country_time_zones from openedx.core.lib.api.parsers import MergePatchParser -from .errors import CatalogedRequestErrorsMixin, ErrorExtensionsMixin, RetiredAccount +from .errors import AmbiguousAccountName, CatalogedRequestErrorsMixin, ErrorExtensionsMixin, RetiredAccount from .filters import StrictOrderingFilter, UserFilterSet, UserPreferenceFilterSet from .paginators import UserApiPagination from .permissions import CanSelectAccountsByContact, IsActiveUser, IsAddressedUser, IsStaffOrAbsent @@ -473,7 +473,7 @@ def _the_one_addressed(username, records, name_of): if stored_under_it: return stored_under_it[0] if len(records) > 1: - raise ValidationError({api_settings.NON_FIELD_ERRORS_KEY: [AMBIGUOUS_ACCOUNT_ADDRESS]}) + raise AmbiguousAccountName({api_settings.NON_FIELD_ERRORS_KEY: [AMBIGUOUS_ACCOUNT_ADDRESS]}) if not records: raise NotFound return records[0] From 45d906f05d91555ab75b860f392e1b032e0bfeb1 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 08:15:59 +0500 Subject: [PATCH 32/61] fix: record a profile image on the account the request was admitted for --- .../profile_images/v2/tests/test_views.py | 62 +++++++++++++++++++ .../djangoapps/profile_images/v2/views.py | 35 +++-------- .../user_api/accounts/image_helpers.py | 14 +++-- .../user_api/v2/tests/test_account_views.py | 22 +++---- .../user_api/v2/tests/test_schema.py | 3 +- 5 files changed, 91 insertions(+), 45 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py index b9e5dd5ce49e..b997af657c5e 100644 --- a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py +++ b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py @@ -11,6 +11,7 @@ import freezegun import pytest +from django.contrib.auth.models import User # pylint: disable=imported-auth-user from django.core.files.uploadedfile import SimpleUploadedFile from django.urls import reverse from edx_rest_framework_extensions.testing import assert_error_envelope @@ -23,7 +24,9 @@ from openedx.core.djangoapps.user_api.accounts.image_helpers import ( get_profile_image_names, get_profile_image_storage, + set_has_profile_image, ) +from openedx.core.djangoapps.user_api.errors import UserNotFound from openedx.core.djangolib.testing.utils import skip_unless_lms from ...tests.helpers import make_image_file @@ -861,6 +864,65 @@ def test_both_versions_refuse_another_learners_image(self): assert self.stored_sizes(self.owner.username) == set() +@skip_unless_lms +class ImageRecordingTests(APITestCase): + """ + What an image is recorded on is the account handed over, not a name read again. + + The recording helper takes either the account itself or the name of one. A + caller that has already settled which account it is acting on hands over + that account, and that is the account written to; a caller that has only a + name is served by the name, as before. + """ + + def setUp(self): + super().setUp() + self.owner = UserFactory.create(username="recorded-owner", password=PASSWORD) + self.uploaded_at = datetime.datetime(2026, 3, 4, 5, 6, tzinfo=ZoneInfo("UTC")) + + def test_the_account_handed_over_is_the_account_recorded_on(self): + """ + The account's own row is the one written, so no name is read on the way to it. + + The account is given a different name in the database behind the + record handed over, which a write that read a name would not find. + """ + User.objects.filter(pk=self.owner.pk).update(username="recorded-owner-elsewhere") + set_has_profile_image(self.owner, True, self.uploaded_at) + self.owner.profile.refresh_from_db() + assert self.owner.profile.has_profile_image is True + assert self.owner.profile.profile_image_uploaded_at == self.uploaded_at + + def test_an_account_handed_over_for_clearing_is_the_account_cleared(self): + set_has_profile_image(self.owner, True, self.uploaded_at) + User.objects.filter(pk=self.owner.pk).update(username="recorded-owner-elsewhere") + set_has_profile_image(self.owner, False) + self.owner.profile.refresh_from_db() + assert self.owner.profile.has_profile_image is False + assert self.owner.profile.profile_image_uploaded_at is None + + def test_a_name_handed_over_is_still_read_as_a_name(self): + """A caller holding a name rather than an account is served as it was.""" + set_has_profile_image(self.owner.username, True, self.uploaded_at) + self.owner.profile.refresh_from_db() + assert self.owner.profile.has_profile_image is True + assert self.owner.profile.profile_image_uploaded_at == self.uploaded_at + + def test_a_name_no_account_holds_is_refused(self): + with pytest.raises(UserNotFound): + set_has_profile_image("nobody-holds-this-name", False) + + def test_an_account_carrying_no_profile_is_refused(self): + profileless = UserFactory.create(username="recorded-no-profile", password=PASSWORD) + profileless.profile.delete() + with pytest.raises(UserNotFound): + set_has_profile_image(profileless, False) + + def test_recording_an_image_without_saying_when_is_refused(self): + with pytest.raises(ValueError): + set_has_profile_image(self.owner, True) + + @pytest.fixture(name="image_owner") @skip_unless_lms def image_owner_fixture(client, django_user_model): # pylint: disable=unused-argument diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index b46980f68e6b..f96de675431e 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -7,7 +7,6 @@ from zoneinfo import ZoneInfo import piexif -from django.core.exceptions import MultipleObjectsReturned from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser @@ -17,12 +16,11 @@ from rest_framework.exceptions import NotFound, ValidationError from rest_framework.parsers import FormParser, MultiPartParser from rest_framework.response import Response -from rest_framework.settings import api_settings from rest_framework.views import APIView from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names, set_has_profile_image from openedx.core.djangoapps.user_api.errors import UserNotFound -from openedx.core.djangoapps.user_api.v2.errors import AmbiguousAccountName, CatalogedRequestErrorsMixin +from openedx.core.djangoapps.user_api.v2.errors import CatalogedRequestErrorsMixin from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser from openedx.core.djangoapps.user_api.v2.serializers import ErrorResponse from openedx.core.djangoapps.user_api.v2.view_utils import ( @@ -33,11 +31,7 @@ StrictQueryParametersMixin, path_param, ) -from openedx.core.djangoapps.user_api.v2.views import ( - AMBIGUOUS_ACCOUNT_ADDRESS, - RESP_NOT_ACCEPTABLE, - AccountResourceMixin, -) +from openedx.core.djangoapps.user_api.v2.views import RESP_NOT_ACCEPTABLE, AccountResourceMixin from openedx.core.lib.api.parsers import TypedFileUploadParser from ..exceptions import ImageValidationError @@ -190,7 +184,7 @@ def post(self, request, username): self._read_image(username, uploaded_file) image_names = get_profile_image_names(username) create_profile_images(uploaded_file, image_names) - self._record_image(username, True) + self._record_image(request.user, True) log.info( "Generated and uploaded images %(image_names)s for user %(user_id)s", {"image_names": list(image_names.values()), "user_id": request.user.id}, @@ -210,10 +204,7 @@ def post(self, request, username): 204: OpenApiResponse(description="The account carries no image of its own."), 400: OpenApiResponse( ErrorResponse, - description=( - "The request carries a query parameter this endpoint does not read, or the " - "address names more than one account and so names none of them in particular." - ), + description="The request carries a query parameter this endpoint does not read.", ), 401: RESP_UNAUTHENTICATED, 403: _RESP_ANOTHER_USERS_IMAGE, @@ -223,7 +214,7 @@ def post(self, request, username): ) def delete(self, request, username): """Remove the stored sizes of the user's image.""" - self._record_image(username, False) + self._record_image(request.user, False) image_names = get_profile_image_names(username) remove_profile_images(image_names) log.info( @@ -256,25 +247,19 @@ def _read_image(self, username, uploaded_file): finally: uploaded_file.seek(0) - def _record_image(self, username, is_uploaded): + def _record_image(self, user, is_uploaded): """ Record on the account whether it carries an image of its own. - The account is looked up again by the name in the address to record - this, and a name that answers for more than one account settles on - none of them, so nothing is recorded and the request is refused rather - than written to whichever account came back. + The account recorded on is the one the request was admitted for, which + is handed over here, so what is recorded lands on that account and on + no other. """ uploaded_at = datetime.datetime.now(ZoneInfo("UTC")) if is_uploaded else None try: - set_has_profile_image(username, is_uploaded, uploaded_at) + set_has_profile_image(user, is_uploaded, uploaded_at) except UserNotFound as exc: raise NotFound from exc - except MultipleObjectsReturned as exc: - log.info("Profile image not recorded for %r: the name answers for more than one account", username) - raise AmbiguousAccountName({ - api_settings.NON_FIELD_ERRORS_KEY: [AMBIGUOUS_ACCOUNT_ADDRESS], - }) from exc def _unusable_image(self, username, message, reason): """Return the refusal telling the caller what the site cannot do with this image.""" diff --git a/openedx/core/djangoapps/user_api/accounts/image_helpers.py b/openedx/core/djangoapps/user_api/accounts/image_helpers.py index bb2ff19321cb..3917a1957ed4 100644 --- a/openedx/core/djangoapps/user_api/accounts/image_helpers.py +++ b/openedx/core/djangoapps/user_api/accounts/image_helpers.py @@ -160,14 +160,17 @@ def _get_default_profile_image_urls(): ) -def set_has_profile_image(username, is_uploaded, upload_dt=None): +def set_has_profile_image(user, is_uploaded, upload_dt=None): """ System (not user-facing) API call used to store whether the user has uploaded a profile image, and if so, when. Used by profile_image API. Arguments: - username (django.contrib.auth.User.username): references the user who - uploaded an image. + user (django.contrib.auth.User or django.contrib.auth.User.username): + the user who uploaded an image, as either that user or the + username of one. A caller that has already settled which user it + is acting for passes that user, so that this records the image on + that user and nothing else is consulted on the way to it. is_uploaded (bool): whether or not the user has an uploaded profile image. @@ -178,14 +181,15 @@ def set_has_profile_image(username, is_uploaded, upload_dt=None): Raises: ValueError: is_uploaded was True, but no upload datetime was supplied. - UserNotFound: no user with username `username` exists. + UserNotFound: there is no such user, or the user has no profile. """ if is_uploaded and upload_dt is None: # pylint: disable=no-else-raise raise ValueError("No upload datetime was supplied.") elif not is_uploaded: upload_dt = None + selected = {'user__username': user} if isinstance(user, str) else {'user': user} try: - profile = UserProfile.objects.get(user__username=username) + profile = UserProfile.objects.get(**selected) except ObjectDoesNotExist: raise UserNotFound() # pylint: disable=raise-missing-from # noqa: B904 diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index b9075b49cd5b..3a227c10bdd2 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -2067,13 +2067,13 @@ def test_a_deactivation_lands_on_the_account_stored_under_the_name_addressed(sel assert not self.owner.has_usable_password() assert self.other.has_usable_password() - def test_an_image_whose_address_names_more_than_one_account_is_left_alone(self): + def test_an_image_is_recorded_on_the_account_the_request_was_admitted_for(self): """ - The image is recorded against the account the address names, or against none. + What the image is recorded on is the account the request was admitted for. - The record it is written to is resolved again by the name in the - address when it is written, so a name that answers for more than one - account is refused there and the stored image is left as it stands. + The account is handed to the write as a record rather than as a name + for the write to find for itself, which is what keeps the account + written to the account the caller was admitted for. """ address = reverse( "user_v2:account_profile_image", kwargs={"username": self.owner.username}, @@ -2081,14 +2081,10 @@ def test_an_image_whose_address_names_more_than_one_account_is_left_alone(self): self.login(self.owner) with mock.patch( "openedx.core.djangoapps.profile_images.v2.views.set_has_profile_image", - side_effect=UserProfile.MultipleObjectsReturned, - ): - envelope = assert_error_envelope( - self.client.delete(address), - expected_status=status.HTTP_400_BAD_REQUEST, - expected_type_slug="user/ambiguous-account-name", - ) - assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} + ) as recorded: + assert self.client.delete(address).status_code == status.HTTP_204_NO_CONTENT + assert recorded.call_args.args[0] == self.owner + assert recorded.call_args.args[1] is False self.owner.profile.refresh_from_db() assert self.owner.profile.has_profile_image is True diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index c9b39067c651..3745efc857f0 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -1606,8 +1606,7 @@ def test_clearing_the_profile_image_publishes_that_it_reads_nothing(schema): assert operation["responses"]["204"]["description"] == "The account carries no image of its own." assert sorted(operation["responses"]) == ["204", "400", "401", "403", "404", "406"] assert operation["responses"]["400"]["description"] == ( - "The request carries a query parameter this endpoint does not read, or the address names " - "more than one account and so names none of them in particular." + "The request carries a query parameter this endpoint does not read." ) From 03b3301cfed2c1835028d3fbdb58c4160a72f43f Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 09:12:17 +0500 Subject: [PATCH 33/61] fix: read an address held and left more than once through the addresses --- .../user_api/v2/tests/test_account_views.py | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 3a227c10bdd2..89b59632c754 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -619,6 +619,43 @@ def test_a_retirement_still_inside_the_cooling_off_period_can_be_cancelled(self) assert envelope["can_cancel_retirement"] is True assert envelope["retirement_id"] == retirement.id + def test_an_address_held_and_left_more_than_once_reports_the_most_recent_retirement(self): + """ + Where one address has been held and left more than once, the retirement reported is the last. + + Only the most recent retirement of an address is still open to being + undone, so that is the one the refusal names. The second account is + given the address outright rather than registered with it, because an + address an account held before it was retired is refused to a new one. + Each account here is this test's own: what retirement leaves behind of + an account cannot be shared with another test. + """ + RetirementState.objects.create(state_name="PENDING", state_execution_order=1) + address = "held-and-left-twice@example.com" + first = UserFactory.create(username="first-holder", email=address, password=PASSWORD) + earliest = UserRetirementStatus.create_retirement(first) + first.email = get_retired_email_by_email(address) + first.save() + second = UserFactory.create( + username="second-holder", email="second-holder@example.com", password=PASSWORD, + ) + User.objects.filter(pk=second.pk).update(email=address) + second.refresh_from_db() + latest = UserRetirementStatus.create_retirement(second) + second.email = get_retired_email_by_email(address) + second.save() + assert sorted( + UserRetirementStatus.objects.filter(original_email=address).values_list("id", flat=True), + ) == sorted([earliest.id, latest.id]) + + envelope = assert_error_envelope( + self.client.get(self.list_url, {"email": address}), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="user/retired-account", + ) + assert envelope["can_cancel_retirement"] is True + assert envelope["retirement_id"] == latest.id + def test_a_retirement_older_than_the_cooling_off_period_can_no_longer_be_cancelled(self): RetirementState.objects.create(state_name="PENDING", state_execution_order=1) retirement = UserRetirementStatus.create_retirement(self.other) From 4095ee551d859df31d484682fec3eab67617cc33 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 09:16:31 +0500 Subject: [PATCH 34/61] docs: record beside the name in an address what each address does with it --- .../djangoapps/profile_images/v2/views.py | 6 ++++ .../user_api/v2/tests/test_schema.py | 33 +++++++++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 7 ++++ 3 files changed, 46 insertions(+) diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index f96de675431e..5096cfb14ef7 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -40,6 +40,12 @@ log = logging.getLogger(__name__) +# The name in this address is read as the name of a stored account, and the +# shorthand the account collection takes for the caller's own account is not +# translated here: a request sent under that name works on the account +# registered under it. The description below publishes that to a caller; it is +# written here for the reader of the module, because an address serving one +# account from another app follows the same rule. _USERNAME_PATH_PARAM = path_param( "username", "Unique name of the user whose image is addressed. The name is read as it is stored, so " diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index 3745efc857f0..e0c5ec846c05 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -882,6 +882,39 @@ def test_member_addresses_describe_the_parts_they_are_built_from(schema): } +@skip_unless_lms +def test_the_addresses_that_work_on_one_account_describe_the_name_they_carry(schema): + """ + An address that works on one account publishes what the name in it is read as. + + Neither of these addresses takes the shorthand the account collection + takes for the caller's own account, so what each of them does with a + request sent under that name is published rather than left for a caller to + find out by sending one. + """ + published = { + (path, method): parameter["description"] + for path, method, operation in operations(schema) + if path in (ACCOUNT_DEACTIVATION_PATH, PROFILE_IMAGE_PATH) + for parameter in operation["parameters"] + if parameter["in"] == "path" and parameter["name"] == "username" + } + image_description = ( + "Unique name of the user whose image is addressed. The name is read as it is stored, so " + "`me` here names an account holding that name rather than the account of the caller " + "making the request." + ) + assert published == { + (ACCOUNT_DEACTIVATION_PATH, "post"): ( + "Unique name of the user whose account is deactivated. The name is read as it is " + "stored, `me` included: this action disables the account the address names, never " + "the account of the caller making the request." + ), + (PROFILE_IMAGE_PATH, "post"): image_description, + (PROFILE_IMAGE_PATH, "delete"): image_description, + } + + #: Every part of an address of this version that carries a username. A client #: built from the document holds a value to what the route matches before it #: sends a request, so an address left off this list is one whose caller learns diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 2885dc2dd48a..e891d262d35f 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -142,6 +142,13 @@ ACCOUNT_PRESETS = (MINIMAL_VIEW, SHARED_VIEW) #: The member of the account collection that addresses the caller's own account. +#: It belongs to that collection, and the addresses beneath one account do not +#: translate it: each of those reads the name it is given as the name of a +#: stored account, so a request sent to one of them under this name works on +#: the account registered under it, whichever account that is. The deactivation +#: of an account publishes that in the description of the name it carries; it +#: is written here as well because an address added beside it inherits the rule +#: and not the sentence. OWN_ACCOUNT_IDENTIFIER = "me" #: What a caller is told about a member address that more than one account From 3c194e95d4af9168f0043caeb4554fc43832c11f Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 09:22:01 +0500 Subject: [PATCH 35/61] test: say which refusal the recording of an image without a date is expected to be --- openedx/core/djangoapps/profile_images/v2/tests/test_views.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py index b997af657c5e..a3511b40aff7 100644 --- a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py +++ b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py @@ -919,7 +919,7 @@ def test_an_account_carrying_no_profile_is_refused(self): set_has_profile_image(profileless, False) def test_recording_an_image_without_saying_when_is_refused(self): - with pytest.raises(ValueError): + with pytest.raises(ValueError, match="No upload datetime was supplied."): set_has_profile_image(self.owner, True) From 44063e801fcdff66fc687b452e38146cb41c6f02 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 22:14:15 +0500 Subject: [PATCH 36/61] refactor: hold these addresses, their descriptions and the hook that marks them outside both services The LMS and Studio serve the same user addresses and each publishes a document of everything it serves, so the list of those addresses, the names they keep, the bodies they exchange, the schema behaviour that applies all three and the hook that marks each one as replaced now live with the user API itself. Each service's schema module keeps only what that service decides for its own mounts, and each service's settings name the shared hook rather than the other service's module. The serializers the table of bodies reads are picked up by name while a document is being generated, as the application they belong to is picked up by name in the settings of each service that installs it. Both documents each service generates are unchanged, byte for byte. --- cms/envs/common.py | 2 +- cms/lib/spectacular.py | 2 +- cms/lib/tests/test_spectacular.py | 6 +- lms/envs/common.py | 1 + lms/lib/spectacular.py | 209 +---------------- lms/lib/tests/test_spectacular.py | 33 +-- openedx/core/djangoapps/user_api/schema.py | 221 ++++++++++++++++++ .../user_api/v2/tests/test_schema.py | 13 +- openedx/core/tests/test_apidocs.py | 16 +- 9 files changed, 272 insertions(+), 231 deletions(-) create mode 100644 openedx/core/djangoapps/user_api/schema.py diff --git a/cms/envs/common.py b/cms/envs/common.py index 4f43d47e7363..99d97cf88c34 100644 --- a/cms/envs/common.py +++ b/cms/envs/common.py @@ -1345,7 +1345,7 @@ def _should_send_xblock_events(settings): # which is what stops a client generated from Studio's document from # offering an address as current that the LMS document marks as # superseded. - 'lms.lib.spectacular.lms_mark_legacy_paths_deprecated', + 'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths', 'openedx.core.apidocs.untag_deprecated_operations', ], # Stripped from each path to derive its tags and operationId, so changing diff --git a/cms/lib/spectacular.py b/cms/lib/spectacular.py index 53819f34ac00..2498827d777d 100644 --- a/cms/lib/spectacular.py +++ b/cms/lib/spectacular.py @@ -4,7 +4,7 @@ from drf_spectacular.openapi import AutoSchema -from lms.lib.spectacular import SupersededUserOperations +from openedx.core.djangoapps.user_api.schema import SupersededUserOperations # Legacy operations superseded by a conforming address under /api/authoring/. # Each is listed in the truncated spelling as well as the full one: the routes diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py index 2051f7a1b14b..8693fd4511e9 100644 --- a/cms/lib/tests/test_spectacular.py +++ b/cms/lib/tests/test_spectacular.py @@ -21,8 +21,12 @@ cms_mark_migrated_paths, cms_mark_superseded_paths, ) -from lms.lib.spectacular import SUPERSEDED_USER_PATHS, superseded_bodies from openedx.core.apidocs import get_api_docs_settings +from openedx.core.djangoapps.user_api.schema import ( + SUPERSEDED_USER_PATHS, + SupersededUserOperations, + superseded_bodies, +) def _endpoint(path): diff --git a/lms/envs/common.py b/lms/envs/common.py index 6f27f270965f..00c3aee24785 100644 --- a/lms/envs/common.py +++ b/lms/envs/common.py @@ -2190,6 +2190,7 @@ 'POSTPROCESSING_HOOKS': [ 'drf_spectacular.hooks.postprocess_schema_enums', 'lms.lib.spectacular.lms_mark_legacy_paths_deprecated', + 'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths', 'openedx.core.apidocs.untag_deprecated_operations', ], # Stripped from each path to derive its tags and operationId, so changing diff --git a/lms/lib/spectacular.py b/lms/lib/spectacular.py index 669611a9e038..51a908c62bc7 100644 --- a/lms/lib/spectacular.py +++ b/lms/lib/spectacular.py @@ -1,11 +1,10 @@ """Helper functions for drf-spectacular (LMS schema).""" import re -from collections import namedtuple -from functools import cache from drf_spectacular.openapi import AutoSchema -from drf_spectacular.utils import OpenApiResponse + +from openedx.core.djangoapps.user_api.schema import SupersededUserOperations, is_superseded_user_path LEGACY_V2_PREFIX = "/api/enrollment/v2/" @@ -14,62 +13,6 @@ # addresses already have distinct ids and keep them. COLLIDING_LEGACY_PATH = "/api/enrollment/v2/enrollments" -# Addresses listed here are superseded by a conforming address this schema also -# publishes. Each entry is spelled out rather than matched by prefix, so an -# address whose replacement has not been written yet is never marked. -SUPERSEDED_USER_PATHS = ( - "/api/user/v1/me", - "/api/user/v1/accounts", - "/api/user/v1/accounts/search_emails", - "/api/user/v1/accounts/{username}", - "/api/user/v1/accounts/{username}/deactivate/", - "/api/user/v1/accounts/{username}/image", - "/api/user/v1/accounts/{username}/verification_status/", - "/api/user/v1/accounts/{username}/verifications/", - "/api/user/v1/accounts/name_change/", - "/api/user/v1/accounts/name_change/{username}/confirm/", - "/api/user/v1/users/", - "/api/user/v1/users/{id}/", - "/api/user/v1/user_prefs/", - "/api/user/v1/user_prefs/{id}/", - "/api/user/v1/preferences/{pref_key}/users/", - "/api/user/v1/forum_roles/{name}/users/", - "/api/user/v1/preferences/time_zones/", -) - -# A path parameter leaves no token behind, and the version 1 account collection -# has no trailing slash to tell it from the member address, so the two tokenize -# to one operation id and are told apart only by a numeral handed out in -# registration order. The collection answers with a list of accounts, which the -# generator names for a list, while the document that trims nothing off the -# front of each path has always published that address under the name derived -# for a single account -- the name that leaves the member address the numeral it -# carries there -- so that one is pinned. The key carries the id the generator -# derives, so an entry applies only to the document that derives it; a key no -# document derives would never be reached. -# -# A stored preference is addressed by the pair that identifies it, and the -# comma between the two parameters is left behind as a token of its own, so -# every document derives an id for that read carrying a bare separator where -# the rest of the resource carries a word. That read is named here in each -# document through the id that document derives, which leaves the collection -# read and the member read of the resource under the same leading tokens -# wherever they are published; neither document has published either name, so -# nothing a client imports is taken away. -RENAMED_OPERATION_IDS = { - ("/api/user/v1/accounts", "GET", "api_user_v1_accounts_list"): "api_user_v1_accounts_retrieve", - ( - "/api/user/v2/user_preferences/{username},{key}/", - "GET", - "v2_user_preferences_,_retrieve", - ): "v2_user_preferences_retrieve", - ( - "/api/user/v2/user_preferences/{username},{key}/", - "GET", - "api_user_v2_user_preferences_,_retrieve", - ): "api_user_v2_user_preferences_retrieve", -} - PUBLISHED_PATH_PATTERN = re.compile(r"^/api/enrollment/v\d+/") # The user addresses this schema documents are the ones the version below @@ -93,91 +36,8 @@ USER_PATH_PREFIX = "/api/user/" USER_TAG = "user" -_PATH_PARAMETER = re.compile(r"\{([\w-]+)\}") _VERSION_TAG = re.compile(r"v\d+") -# The superseded addresses with their parameter names removed. The generator -# renames a ``{pk}`` parameter to ``{id}`` only after this filter has run, so -# the comparison cannot depend on how a parameter is spelled. -_SUPERSEDED_USER_SHAPES = frozenset(_PATH_PARAMETER.sub("{}", path) for path in SUPERSEDED_USER_PATHS) - - -#: What one superseded operation reads and what it answers with on success. -_SupersededBodies = namedtuple("_SupersededBodies", ("request", "response")) - - -@cache -def superseded_bodies(): - """ - Return the bodies of each superseded operation, keyed by address and method. - - The views serving those addresses name no serializer, so an address - published beside the one that replaces it would carry nothing on either - side of the exchange. Each entry below names the shape the handler reads or - returns with the serializer describing that same shape at the replacing - address, which the parity tests of this area hold to the same values; a - request of ``None`` is an operation that reads no body. An address whose - view names a serializer of its own is absent from the table and keeps the - component it has always published. - - A request is keyed by media type, because a shape named on its own is - published under every type the view's parsers accept: where that is more - types than the handler reads, a client generated from the document would - pick one it refuses, and where the handler reads a body no serializer - describes, such as an image sent as the whole body, the document would - leave that form out. An address whose body is also read at the address - replacing it takes the same mapping from there, so the two cannot drift. - """ - # The serializers read models, which are not loaded when this module is - # first imported. - # pylint: disable=import-outside-toplevel - from openedx.core.djangoapps.profile_images.v2.serializers import IMAGE_UPLOAD_REQUEST - from openedx.core.djangoapps.user_api.v2.serializers import ( - AccountSerializer, - AccountUpdateSerializer, - EmailSearchResultSerializer, - EmailSearchSerializer, - NameChangeSerializer, - VerificationStatusSerializer, - ) - from openedx.core.lib.api.parsers import MergePatchParser - - account = {200: AccountSerializer} - described = { - ("/api/user/v1/accounts", "GET"): _SupersededBodies(None, {200: AccountSerializer(many=True)}), - ("/api/user/v1/accounts/{username}", "GET"): _SupersededBodies(None, account), - ("/api/user/v1/accounts/{username}", "PATCH"): _SupersededBodies( - {MergePatchParser.media_type: AccountUpdateSerializer}, account, - ), - ("/api/user/v1/accounts/search_emails", "POST"): _SupersededBodies( - EmailSearchSerializer, {200: EmailSearchResultSerializer(many=True)}, - ), - ("/api/user/v1/accounts/{username}/deactivate/", "POST"): _SupersededBodies(None, account), - ("/api/user/v1/accounts/name_change/", "POST"): _SupersededBodies( - NameChangeSerializer, - {201: OpenApiResponse(description="The change was recorded and waits to be confirmed.")}, - ), - ("/api/user/v1/accounts/name_change/{username}/confirm/", "POST"): _SupersededBodies( - None, {204: OpenApiResponse(description="The profile carries the name that was asked for.")}, - ), - ("/api/user/v1/accounts/{username}/image", "POST"): _SupersededBodies( - IMAGE_UPLOAD_REQUEST, - {204: OpenApiResponse(description="The account now carries this image.")}, - ), - ("/api/user/v1/accounts/{username}/image", "DELETE"): _SupersededBodies( - None, {204: OpenApiResponse(description="The account carries no image of its own.")}, - ), - ("/api/user/v1/accounts/{username}/verification_status/", "GET"): _SupersededBodies( - None, {200: VerificationStatusSerializer}, - ), - } - # Parameter names are spelled differently at different points of - # generation, so an address is keyed by its shape alone. - return { - (_PATH_PARAMETER.sub("{}", path), method): bodies - for (path, method), bodies in described.items() - } - def _is_legacy_path(path): """Conforming routes always end in a slash, so a slashless v2 path is a legacy address.""" @@ -186,7 +46,7 @@ def _is_legacy_path(path): def _is_published_user_path(path, callback): """A user address is documented when this version serves it, or when this version replaces it.""" - if _PATH_PARAMETER.sub("{}", path) in _SUPERSEDED_USER_SHAPES: + if is_superseded_user_path(path): return True if not path.startswith(PUBLISHED_USER_PREFIX): return False @@ -207,65 +67,6 @@ def lms_api_filter(endpoints): return filtered -class SupersededUserOperations: - """ - Describe the superseded user addresses wherever a service publishes them. - - Both services mount that API at the same addresses and both publish an - unauthenticated document of everything they serve, so what one of those - documents says about one of these addresses is what the other has to say - about it as well: a client generated from either reads the same body on - each side of the exchange, branches on the same success code, and imports - the same name. The behaviour is shared rather than restated in each - service's schema class, which is what keeps the two documents a deployment - publishes from describing one address two ways. - - Every address ``RENAMED_OPERATION_IDS`` does not name keeps the id the - generator derives for it, because a client generated from a document takes - a module from each operationId, so renaming one drops what a consumer - already imports. - """ - - def get_operation_id(self): - """Keep the name an address is published under where describing its bodies would move it.""" - operation_id = super().get_operation_id() - return RENAMED_OPERATION_IDS.get((self.path, self.method, operation_id), operation_id) - - def _get_request_body(self, direction="request"): - """ - Publish a body as one the operation needs when any form it may be sent in is. - - An operation that names the media types it reads loses that mark as - soon as one of them is the bare body of a file, which carries no field - that can be called required. The forms are alternatives rather than - parts of one request, so a body that is required in any of them is a - body the operation cannot be called without. - """ - body = super()._get_request_body(direction) - if not body: - return body - shapes = self.get_request_serializer() - if body.get("required") or not isinstance(shapes, dict): - return body - if any(self._get_request_for_media_type(shape, direction)[1] for shape in shapes.values()): - body["required"] = True - return body - - def get_request_serializer(self): - """Return the body this operation reads, named here for the addresses this one supersedes.""" - bodies = self._superseded_bodies() - return super().get_request_serializer() if bodies is None else bodies.request - - def get_response_serializers(self): - """Return the body this operation answers with, named here for the addresses this one supersedes.""" - bodies = self._superseded_bodies() - return super().get_response_serializers() if bodies is None else bodies.response - - def _superseded_bodies(self): - """Return the bodies named for this operation, or ``None`` where none are named.""" - return superseded_bodies().get((_PATH_PARAMETER.sub("{}", self.path), self.method)) - - class LmsAutoSchema(SupersededUserOperations, AutoSchema): """ Keep colliding addresses distinct and group each operation under its own area. @@ -296,9 +97,9 @@ def get_tags(self): def lms_mark_legacy_paths_deprecated(result, generator, request, public): # pylint: disable=unused-argument - """Mark every superseded address ``deprecated: true``.""" + """Mark every legacy enrollment address ``deprecated: true``.""" for path, path_item in result.get("paths", {}).items(): - if not (_is_legacy_path(path) or path in SUPERSEDED_USER_PATHS): + if not _is_legacy_path(path): continue for operation in path_item.values(): if isinstance(operation, dict): diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index 8ed309a7139a..2e42f59b273b 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -21,20 +21,19 @@ from common.djangoapps.student.models_api import do_name_change_request from common.djangoapps.student.tests.factories import TEST_PASSWORD, UserFactory -from lms.lib.spectacular import ( - RENAMED_OPERATION_IDS, - SUPERSEDED_USER_PATHS, - LmsAutoSchema, - lms_api_filter, - lms_mark_legacy_paths_deprecated, - superseded_bodies, -) +from lms.lib.spectacular import LmsAutoSchema, lms_api_filter, lms_mark_legacy_paths_deprecated from openedx.core.apidocs import get_api_docs_settings from openedx.core.djangoapps.profile_images.tests.helpers import make_image_file from openedx.core.djangoapps.user_api.accounts.image_helpers import ( get_profile_image_names, get_profile_image_storage, ) +from openedx.core.djangoapps.user_api.schema import ( + RENAMED_OPERATION_IDS, + SUPERSEDED_USER_PATHS, + mark_superseded_user_paths, + superseded_bodies, +) ENROLLMENT_VIEWS = "openedx.core.djangoapps.enrollments.views" USER_API_V1_VIEWS = "openedx.core.djangoapps.user_api.views" @@ -126,8 +125,17 @@ def test_only_slashless_v2_paths_are_deprecated(self): assert "deprecated" not in paths["/api/enrollment/v2/courses/{course_key}/"]["get"] assert "deprecated" not in paths["/api/enrollment/v1/enrollment"]["get"] + def test_paths_are_left_as_full_urls(self): + """Paths are not trimmed, so every key resolves against LMS_ROOT_URL.""" + result = lms_mark_legacy_paths_deprecated(_schema("/api/enrollment/v2/enrollments/"), None, None, False) + assert list(result["paths"]) == ["/api/enrollment/v2/enrollments/"] + + +class MarkSupersededUserPathsTest(SimpleTestCase): + """Only the addresses the shared list names are marked, wherever a service publishes them.""" + def test_only_the_listed_user_addresses_are_deprecated(self): - result = lms_mark_legacy_paths_deprecated(_schema( + result = mark_superseded_user_paths(_schema( "/api/user/v1/users/", "/api/user/v1/users/{id}/", "/api/user/v1/preferences/time_zones/", @@ -173,11 +181,6 @@ def test_only_the_listed_user_addresses_are_deprecated(self): ): assert "deprecated" not in paths[untouched]["get"], untouched - def test_paths_are_left_as_full_urls(self): - """Paths are not trimmed, so every key resolves against LMS_ROOT_URL.""" - result = lms_mark_legacy_paths_deprecated(_schema("/api/enrollment/v2/enrollments/"), None, None, False) - assert list(result["paths"]) == ["/api/enrollment/v2/enrollments/"] - class _EmptySerializer(serializers.Serializer): # pylint: disable=abstract-method pass @@ -264,7 +267,7 @@ def _user_routes(schema_class): def _derived_operations(schema_class, patches): """The names ``schema_class`` produces with nothing pinned, which is what the generator derives.""" - with mock.patch.dict("lms.lib.spectacular.RENAMED_OPERATION_IDS", {}, clear=True): + with mock.patch.dict("openedx.core.djangoapps.user_api.schema.RENAMED_OPERATION_IDS", {}, clear=True): return _named_operations(schema_class, patches) diff --git a/openedx/core/djangoapps/user_api/schema.py b/openedx/core/djangoapps/user_api/schema.py new file mode 100644 index 000000000000..430bedf57955 --- /dev/null +++ b/openedx/core/djangoapps/user_api/schema.py @@ -0,0 +1,221 @@ +"""How a document describes the addresses of this API that a conforming one replaces.""" + +import re +from collections import namedtuple +from functools import cache +from importlib import import_module + +from drf_spectacular.utils import OpenApiResponse + +# Addresses listed here are superseded by a conforming address this schema also +# publishes. Each entry is spelled out rather than matched by prefix, so an +# address whose replacement has not been written yet is never marked. +SUPERSEDED_USER_PATHS = ( + "/api/user/v1/me", + "/api/user/v1/accounts", + "/api/user/v1/accounts/search_emails", + "/api/user/v1/accounts/{username}", + "/api/user/v1/accounts/{username}/deactivate/", + "/api/user/v1/accounts/{username}/image", + "/api/user/v1/accounts/{username}/verification_status/", + "/api/user/v1/accounts/{username}/verifications/", + "/api/user/v1/accounts/name_change/", + "/api/user/v1/accounts/name_change/{username}/confirm/", + "/api/user/v1/users/", + "/api/user/v1/users/{id}/", + "/api/user/v1/user_prefs/", + "/api/user/v1/user_prefs/{id}/", + "/api/user/v1/preferences/{pref_key}/users/", + "/api/user/v1/forum_roles/{name}/users/", + "/api/user/v1/preferences/time_zones/", +) + +# A path parameter leaves no token behind, and the version 1 account collection +# has no trailing slash to tell it from the member address, so the two tokenize +# to one operation id and are told apart only by a numeral handed out in +# registration order. The collection answers with a list of accounts, which the +# generator names for a list, while the document that trims nothing off the +# front of each path has always published that address under the name derived +# for a single account -- the name that leaves the member address the numeral it +# carries there -- so that one is pinned. The key carries the id the generator +# derives, so an entry applies only to the document that derives it; a key no +# document derives would never be reached. +# +# A stored preference is addressed by the pair that identifies it, and the +# comma between the two parameters is left behind as a token of its own, so +# every document derives an id for that read carrying a bare separator where +# the rest of the resource carries a word. That read is named here in each +# document through the id that document derives, which leaves the collection +# read and the member read of the resource under the same leading tokens +# wherever they are published; neither document has published either name, so +# nothing a client imports is taken away. +RENAMED_OPERATION_IDS = { + ("/api/user/v1/accounts", "GET", "api_user_v1_accounts_list"): "api_user_v1_accounts_retrieve", + ( + "/api/user/v2/user_preferences/{username},{key}/", + "GET", + "v2_user_preferences_,_retrieve", + ): "v2_user_preferences_retrieve", + ( + "/api/user/v2/user_preferences/{username},{key}/", + "GET", + "api_user_v2_user_preferences_,_retrieve", + ): "api_user_v2_user_preferences_retrieve", +} + + +_PATH_PARAMETER = re.compile(r"\{([\w-]+)\}") + +# The superseded addresses with their parameter names removed. The generator +# renames a ``{pk}`` parameter to ``{id}`` only after this filter has run, so +# the comparison cannot depend on how a parameter is spelled. +_SUPERSEDED_USER_SHAPES = frozenset(_PATH_PARAMETER.sub("{}", path) for path in SUPERSEDED_USER_PATHS) + + +def is_superseded_user_path(path): + """Say whether this address is one of those a conforming address replaces.""" + return _PATH_PARAMETER.sub("{}", path) in _SUPERSEDED_USER_SHAPES + +#: What one superseded operation reads and what it answers with on success. +_SupersededBodies = namedtuple("_SupersededBodies", ("request", "response")) + + +@cache +def superseded_bodies(): + """ + Return the bodies of each superseded operation, keyed by address and method. + + The views serving those addresses name no serializer, so an address + published beside the one that replaces it would carry nothing on either + side of the exchange. Each entry below names the shape the handler reads or + returns with the serializer describing that same shape at the replacing + address, which the parity tests of this area hold to the same values; a + request of ``None`` is an operation that reads no body. An address whose + view names a serializer of its own is absent from the table and keeps the + component it has always published. + + A request is keyed by media type, because a shape named on its own is + published under every type the view's parsers accept: where that is more + types than the handler reads, a client generated from the document would + pick one it refuses, and where the handler reads a body no serializer + describes, such as an image sent as the whole body, the document would + leave that form out. An address whose body is also read at the address + replacing it takes the same mapping from there, so the two cannot drift. + """ + # The serializers read models, which are not loaded when this module is + # first imported, so each module is read inside this one. One of them + # reaches models belonging to a single service, which code shared by both + # services may not import: a service picks that application up by name + # through its settings, and that module is picked up by name here for the + # same reason. + # pylint: disable=import-outside-toplevel + from openedx.core.djangoapps.profile_images.v2.serializers import IMAGE_UPLOAD_REQUEST + from openedx.core.lib.api.parsers import MergePatchParser + + replacing = import_module("openedx.core.djangoapps.user_api.v2.serializers") + + account = {200: replacing.AccountSerializer} + described = { + ("/api/user/v1/accounts", "GET"): _SupersededBodies(None, {200: replacing.AccountSerializer(many=True)}), + ("/api/user/v1/accounts/{username}", "GET"): _SupersededBodies(None, account), + ("/api/user/v1/accounts/{username}", "PATCH"): _SupersededBodies( + {MergePatchParser.media_type: replacing.AccountUpdateSerializer}, account, + ), + ("/api/user/v1/accounts/search_emails", "POST"): _SupersededBodies( + replacing.EmailSearchSerializer, {200: replacing.EmailSearchResultSerializer(many=True)}, + ), + ("/api/user/v1/accounts/{username}/deactivate/", "POST"): _SupersededBodies(None, account), + ("/api/user/v1/accounts/name_change/", "POST"): _SupersededBodies( + replacing.NameChangeSerializer, + {201: OpenApiResponse(description="The change was recorded and waits to be confirmed.")}, + ), + ("/api/user/v1/accounts/name_change/{username}/confirm/", "POST"): _SupersededBodies( + None, {204: OpenApiResponse(description="The profile carries the name that was asked for.")}, + ), + ("/api/user/v1/accounts/{username}/image", "POST"): _SupersededBodies( + IMAGE_UPLOAD_REQUEST, + {204: OpenApiResponse(description="The account now carries this image.")}, + ), + ("/api/user/v1/accounts/{username}/image", "DELETE"): _SupersededBodies( + None, {204: OpenApiResponse(description="The account carries no image of its own.")}, + ), + ("/api/user/v1/accounts/{username}/verification_status/", "GET"): _SupersededBodies( + None, {200: replacing.VerificationStatusSerializer}, + ), + } + # Parameter names are spelled differently at different points of + # generation, so an address is keyed by its shape alone. + return { + (_PATH_PARAMETER.sub("{}", path), method): bodies + for (path, method), bodies in described.items() + } + + +class SupersededUserOperations: + """ + Describe the superseded user addresses wherever a service publishes them. + + Both services mount that API at the same addresses and both publish an + unauthenticated document of everything they serve, so what one of those + documents says about one of these addresses is what the other has to say + about it as well: a client generated from either reads the same body on + each side of the exchange, branches on the same success code, and imports + the same name. The behaviour is shared rather than restated in each + service's schema class, which is what keeps the two documents a deployment + publishes from describing one address two ways. + + Every address ``RENAMED_OPERATION_IDS`` does not name keeps the id the + generator derives for it, because a client generated from a document takes + a module from each operationId, so renaming one drops what a consumer + already imports. + """ + + def get_operation_id(self): + """Keep the name an address is published under where describing its bodies would move it.""" + operation_id = super().get_operation_id() + return RENAMED_OPERATION_IDS.get((self.path, self.method, operation_id), operation_id) + + def _get_request_body(self, direction="request"): + """ + Publish a body as one the operation needs when any form it may be sent in is. + + An operation that names the media types it reads loses that mark as + soon as one of them is the bare body of a file, which carries no field + that can be called required. The forms are alternatives rather than + parts of one request, so a body that is required in any of them is a + body the operation cannot be called without. + """ + body = super()._get_request_body(direction) + if not body: + return body + shapes = self.get_request_serializer() + if body.get("required") or not isinstance(shapes, dict): + return body + if any(self._get_request_for_media_type(shape, direction)[1] for shape in shapes.values()): + body["required"] = True + return body + + def get_request_serializer(self): + """Return the body this operation reads, named here for the addresses this one supersedes.""" + bodies = self._superseded_bodies() + return super().get_request_serializer() if bodies is None else bodies.request + + def get_response_serializers(self): + """Return the body this operation answers with, named here for the addresses this one supersedes.""" + bodies = self._superseded_bodies() + return super().get_response_serializers() if bodies is None else bodies.response + + def _superseded_bodies(self): + """Return the bodies named for this operation, or ``None`` where none are named.""" + return superseded_bodies().get((_PATH_PARAMETER.sub("{}", self.path), self.method)) + + +def mark_superseded_user_paths(result, generator, request, public): # pylint: disable=unused-argument + """Post-processing hook: mark every address a conforming one replaces ``deprecated: true``.""" + for path, path_item in result.get("paths", {}).items(): + if path not in SUPERSEDED_USER_PATHS: + continue + for operation in path_item.values(): + if isinstance(operation, dict): + operation["deprecated"] = True + return result diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index e0c5ec846c05..292a7ee26520 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -15,11 +15,7 @@ from common.djangoapps.student.models import PendingNameChange, UserProfile from common.djangoapps.student.tests.factories import AccountRecoveryFactory, AdminFactory, UserFactory from lms.djangoapps.verify_student.models import IDVerificationAttempt, VerificationAttempt -from lms.lib.spectacular import ( - RENAMED_OPERATION_IDS, - SUPERSEDED_USER_PATHS, - lms_mark_legacy_paths_deprecated, -) +from lms.lib.spectacular import lms_mark_legacy_paths_deprecated from openedx.core.apidocs import get_api_docs_settings from openedx.core.djangoapps.profile_images.tests.helpers import make_image_file from openedx.core.djangoapps.site_configuration.tests.test_util import with_site_configuration_context @@ -28,6 +24,11 @@ get_profile_image_storage, ) from openedx.core.djangoapps.user_api.accounts.utils import ENABLE_SECONDARY_EMAIL_FEATURE_SWITCH +from openedx.core.djangoapps.user_api.schema import ( + RENAMED_OPERATION_IDS, + SUPERSEDED_USER_PATHS, + mark_superseded_user_paths, +) from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory from openedx.core.djangoapps.user_api.v2.serializers import ( ACCOUNT_DEFAULT_SORT, @@ -573,6 +574,7 @@ def test_enum_post_processing_runs_before_the_deprecation_hook(): hooks = settings.SPECTACULAR_SETTINGS["POSTPROCESSING_HOOKS"] assert hooks[0] == "drf_spectacular.hooks.postprocess_schema_enums" assert "lms.lib.spectacular.lms_mark_legacy_paths_deprecated" in hooks[1:] + assert "openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths" in hooks[1:] @skip_unless_lms @@ -601,6 +603,7 @@ def test_hook_leaves_other_resources_alone(): result = {"paths": {path: {"get": {"operationId": path}} for path in untouched + marked}} lms_mark_legacy_paths_deprecated(result, generator=None, request=None, public=True) + mark_superseded_user_paths(result, generator=None, request=None, public=True) for path in untouched: assert "deprecated" not in result["paths"][path]["get"], path diff --git a/openedx/core/tests/test_apidocs.py b/openedx/core/tests/test_apidocs.py index 4d7d79a49eb2..308c9685cf66 100644 --- a/openedx/core/tests/test_apidocs.py +++ b/openedx/core/tests/test_apidocs.py @@ -44,13 +44,21 @@ class UntagDeprecatedOperationsRegistrationTest(SimpleTestCase): """Every schema configuration runs the hook after the hooks that mark operations deprecated.""" # The other environments inherit the hooks from these two modules. + SHARED_HOOK = "'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths'," MARKING_HOOKS = { - "cms/envs/common.py": "'cms.lib.spectacular.cms_mark_migrated_paths',", - "lms/envs/common.py": "'lms.lib.spectacular.lms_mark_legacy_paths_deprecated',", + "cms/envs/common.py": ( + "'cms.lib.spectacular.cms_mark_migrated_paths',", + SHARED_HOOK, + ), + "lms/envs/common.py": ( + "'lms.lib.spectacular.lms_mark_legacy_paths_deprecated',", + SHARED_HOOK, + ), } def test_the_hook_runs_last(self): - for module, marking_hook in self.MARKING_HOOKS.items(): + for module, marking_hooks in self.MARKING_HOOKS.items(): source = (REPO_ROOT / module).read_text() assert HOOK in source, module - assert source.index(marking_hook) < source.index(HOOK), module + for marking_hook in marking_hooks: + assert source.index(marking_hook) < source.index(HOOK), (module, marking_hook) From ffe739ca8b17fb9d8ce02307f65b1c78db9b0e6c Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 22:14:21 +0500 Subject: [PATCH 37/61] test: check that neither schema module reaches into the other service The description of these addresses is held in one place so that the two documents cannot disagree, and either service copying it or reading it out of the other's package would undo that. One test names where the shared behaviour is read from; two read the source of the modules this service's schema class is built out of and refuse an import of either service. --- cms/lib/tests/test_spectacular.py | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py index 8693fd4511e9..06898c70099c 100644 --- a/cms/lib/tests/test_spectacular.py +++ b/cms/lib/tests/test_spectacular.py @@ -197,6 +197,37 @@ def test_the_module_the_published_reference_is_generated_from_inherits_this_conf assert "SPECTACULAR_SETTINGS" not in self._source("cms/envs/development.py") +class SharedSchemaBehaviourTest(SimpleTestCase): + """ + Where the description this service shares with the one replacing these addresses is kept. + + Both services publish the same user addresses, so what they say about them + is held once, in a module belonging to the API being described rather than + to either service. A service reaching into the other's package for it + would tie the two together, and a copy of it here would drift from the + original the moment one of the two was corrected. + """ + + #: The module holding what the two services say the same way. + SHARED_MODULE = "openedx/core/djangoapps/user_api/schema.py" + + @staticmethod + def _source(module): + return (Path(__file__).resolve().parents[3] / module).read_text() + + def test_the_shared_description_is_read_from_the_api_it_describes(self): + assert SupersededUserOperations.__module__ == "openedx.core.djangoapps.user_api.schema" + assert SupersededUserOperations in CmsAutoSchema.__mro__ + + def test_the_shared_module_reads_no_part_of_either_service(self): + found = re.findall(r"(?m)^\s*(?:from|import) (?:lms|cms)\b", self._source(self.SHARED_MODULE)) + assert found == [] + + def test_the_schema_helpers_of_this_service_read_no_part_of_the_other(self): + found = re.findall(r"(?m)^\s*(?:from|import) lms\b", self._source("cms/lib/spectacular.py")) + assert found == [] + + class _EmptySerializer(serializers.Serializer): # pylint: disable=abstract-method pass From 87ea4c5fd3934723c1a9d051983fa8e732caa322 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 22:32:59 +0500 Subject: [PATCH 38/61] test: hold each version to the refusal it answers with The parity case for an address spelled with a different capitalisation held both versions to one refusal code. They refuse such a request in different terms, so each is measured against what it answers, and both are still held to handing back nothing of the account that was asked for. --- .../user_api/v2/tests/test_verification_views.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py index 12332694864d..e364d7ce1bf6 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py @@ -970,6 +970,13 @@ def test_the_attempts_of_a_user_who_has_been_through_no_checks_are_an_empty_page assert self.client.get(self.list_address("nobody-at-all")).status_code == status.HTTP_404_NOT_FOUND def test_both_versions_refuse_an_address_that_is_not_exactly_the_callers_name(self): + """ + Neither version answers an account to a caller who addressed it differently. + + The two refuse such a request in different terms, so each is held to + the code it answers rather than both to one code, and neither hands + back anything of the account that was asked for. + """ self.login(self.owner) shouted = self.owner.username.upper() for earlier_address, later_address in ( @@ -978,8 +985,8 @@ def test_both_versions_refuse_an_address_that_is_not_exactly_the_callers_name(se ): earlier = self.client.get(earlier_address) later = self.client.get(later_address) - assert earlier.status_code == status.HTTP_403_FORBIDDEN - assert earlier.data == {"detail": "You do not have permission to perform this action."} + assert earlier.status_code == status.HTTP_404_NOT_FOUND + assert "verification" not in str(earlier.data) assert_error_envelope(later, expected_status=403, expected_type_slug="authz") def test_an_anonymous_caller_is_refused_by_both_and_told_so_by_this_one(self): From f5fd5ae618b3934ce33b212d8f9ed45cdc2a2f1b Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Sun, 1 Nov 2026 21:15:38 +0500 Subject: [PATCH 39/61] style: satisfy the repository's own lint on the lines this work adds Three findings the repository's quality job reports and our own run did not: an unpacked loop name this body never reads, and two assertions that joined two independent claims with and, so a failure named neither. --- lms/tests.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lms/tests.py b/lms/tests.py index 8738cface569..c3c78c8b9e04 100644 --- a/lms/tests.py +++ b/lms/tests.py @@ -155,7 +155,8 @@ def test_the_two_documents_this_service_serves_are_not_stored_under_one_key(self cache.clear() narrow = self.client.get(self.ADDRESS) wide = self.client.get('/api-docs/schema/') - assert narrow.status_code == 200 and wide.status_code == 200 + assert narrow.status_code == 200 + assert wide.status_code == 200 assert len(narrow.content) < len(wide.content) assert self.client.get(self.ADDRESS).content == narrow.content assert self.client.get('/api-docs/schema/').content == wide.content @@ -168,7 +169,8 @@ def test_another_language_is_not_served_the_document_already_stored(self): cache.clear() english = self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='en') spanish = self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='es-419') - assert english.status_code == 200 and spanish.status_code == 200 + assert english.status_code == 200 + assert spanish.status_code == 200 assert english.content != spanish.content assert self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='en').content == english.content From 9892aa2fa8c7240ad01d2678fe8c7e39f425ff76 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 17:57:11 +0500 Subject: [PATCH 40/61] fix: refuse a restricted application's token on every operation of /api/user/v2/ Confirming a requested name change took its classes from the action's own permission_classes, which the JWT middleware never sees: it adds the restricted-application refusal to a view's class attribute only. A token issued to a restricted application on behalf of a staff account was therefore answered 204 at /api/user/v2/name_changes/{username}/confirmations/ and confirmed the change, where /api/user/v1/accounts/name_change/{username}/confirm/ refuses the same token with 403. Every view of this version, and the profile image view mounted under it, now inherits a mixin that appends NotJwtRestrictedApplication to whatever get_permissions resolves, so the refusal no longer depends on how an operation composes its classes or on the middleware having run. The confirmation now answers that token 403 and changes nothing; every other operation already answered 403 and still does. Tests: every routed view inherits the mixin and every routed operation resolves the refusal without a request reaching it; each of the sixteen operations refuses a restricted token with 403 and leaves its data unchanged, and answers the same staff account's ordinary token. Co-Authored-By: Claude Opus 5.5 --- .../djangoapps/profile_images/v2/views.py | 3 +- .../djangoapps/user_api/v2/permissions.py | 21 ++ .../v2/tests/test_restricted_applications.py | 243 ++++++++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 19 +- 4 files changed, 283 insertions(+), 3 deletions(-) create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_restricted_applications.py diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index 5096cfb14ef7..893ed47dc549 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -21,7 +21,7 @@ from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names, set_has_profile_image from openedx.core.djangoapps.user_api.errors import UserNotFound from openedx.core.djangoapps.user_api.v2.errors import CatalogedRequestErrorsMixin -from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser +from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser, RestrictedApplicationGuardMixin from openedx.core.djangoapps.user_api.v2.serializers import ErrorResponse from openedx.core.djangoapps.user_api.v2.view_utils import ( RESP_UNAUTHENTICATED, @@ -112,6 +112,7 @@ def get_filename(self, stream, media_type, parser_context): @extend_schema(tags=[SDK_TAG]) class ProfileImageView( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, AccountResourceMixin, StrictQueryParametersMixin, diff --git a/openedx/core/djangoapps/user_api/v2/permissions.py b/openedx/core/djangoapps/user_api/v2/permissions.py index 33fd8d8c75a3..1454be5f17ed 100644 --- a/openedx/core/djangoapps/user_api/v2/permissions.py +++ b/openedx/core/djangoapps/user_api/v2/permissions.py @@ -1,5 +1,6 @@ """Permission classes for version 2 of the User API.""" +from edx_rest_framework_extensions.permissions import NotJwtRestrictedApplication from rest_framework.exceptions import NotFound from rest_framework.permissions import BasePermission @@ -77,3 +78,23 @@ def has_permission(self, request, view): if request.user and request.user.is_staff: return True raise NotFound + + +class RestrictedApplicationGuardMixin: + """ + Refuses a token issued to a restricted application on every operation of the view. + + ``EnsureJWTAuthSettingsMiddleware`` adds this refusal to a view's + ``permission_classes`` attribute and nowhere else, so an operation whose + classes come from somewhere else, such as the ``permission_classes`` of an + extra action, would be left without it. Appending it to whatever + ``get_permissions`` resolves keeps it on every operation however that + operation composes its classes. A request that carries no token passes it. + """ + + def get_permissions(self): + """Return the classes this operation resolves, ending with the restricted-application refusal.""" + resolved = list(super().get_permissions()) + if not any(isinstance(permission, NotJwtRestrictedApplication) for permission in resolved): + resolved.append(NotJwtRestrictedApplication()) + return resolved diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_restricted_applications.py b/openedx/core/djangoapps/user_api/v2/tests/test_restricted_applications.py new file mode 100644 index 000000000000..852e4a2b9270 --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_restricted_applications.py @@ -0,0 +1,243 @@ +"""Tests of the refusal every address of version 2 of the User API gives a restricted application's token.""" + +import json +from datetime import UTC, datetime + +import ddt +from django.contrib.auth.models import User # pylint: disable=imported-auth-user +from django.test import SimpleTestCase +from django.urls import reverse +from edx_rest_framework_extensions.auth.jwt.tests.utils import generate_jwt +from edx_rest_framework_extensions.permissions import NotJwtRestrictedApplication +from edx_rest_framework_extensions.testing import assert_error_envelope +from rest_framework import status +from rest_framework.test import APITestCase + +from common.djangoapps.student.models import PendingNameChange, UserProfile +from common.djangoapps.student.tests.factories import UserFactory +from openedx.core.djangoapps.profile_images.images import get_profile_image_storage +from openedx.core.djangoapps.profile_images.tests.helpers import make_image_file +from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names +from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory +from openedx.core.djangoapps.user_api.v2 import urls as v2_urls +from openedx.core.djangoapps.user_api.v2.permissions import RestrictedApplicationGuardMixin +from openedx.core.djangolib.testing.utils import skip_unless_lms + +PASSWORD = "Password1234" +MERGE_PATCH = "application/merge-patch+json" + + +def routed_views(): + """ + Yield the view class, the route name and the operations of every route of this version. + + The operations are the handler names a route dispatches to: the actions of + a viewset, or the methods an ``APIView`` implements. + """ + for pattern in v2_urls.urlpatterns: + callback = pattern.callback + view_class = getattr(callback, "cls", None) or callback.view_class + if getattr(callback, "actions", None): + operations = sorted(set(callback.actions.values())) + else: + operations = sorted( + method for method in view_class.http_method_names + if method not in ("options", "head") and hasattr(view_class, method) + ) + yield view_class, pattern.name, callback.initkwargs, operations + + +@skip_unless_lms +class EveryOperationCarriesTheRefusalTests(SimpleTestCase): + """ + Each operation resolves the restricted-application refusal among its own classes. + + These read the classes an operation resolves without a request reaching + it, so the platform middleware, which adds the refusal only once a view + has served a request, plays no part in what they see. + """ + + def test_every_routed_view_inherits_the_guard(self): + unguarded = sorted( + {view_class.__name__ for view_class, _, _, _ in routed_views() + if not issubclass(view_class, RestrictedApplicationGuardMixin)} + ) + assert unguarded == [] + + def test_every_operation_resolves_the_refusal(self): + missing = [] + for view_class, name, initkwargs, operations in routed_views(): + for operation in operations: + view = view_class(**initkwargs) + view.action = operation + view.kwargs = {} + resolved = view.get_permissions() + if not any(isinstance(permission, NotJwtRestrictedApplication) for permission in resolved): + missing.append((name, operation)) + assert not missing, missing + + def test_the_name_change_confirmation_keeps_its_own_classes_and_gains_the_refusal(self): + pattern = next(p for p in v2_urls.urlpatterns if p.name == "name_change_confirmation") + view = pattern.callback.cls(**pattern.callback.initkwargs) + view.action = "confirmations" + assert [type(permission).__name__ for permission in view.get_permissions()] == [ + "IsAuthenticated", "IsActiveUser", "IsStaff", "NotJwtRestrictedApplication", + ] + + +@skip_unless_lms +@ddt.ddt +class RestrictedApplicationTokenTests(APITestCase): + """ + A token issued to a restricted application is refused at every operation that reads a token. + + Each operation is called twice by the same staff account, once with a + token issued to an ordinary application, which the operation answers, and + once with the same token flagged as issued to a restricted application, + which it refuses before changing anything. + """ + + def setUp(self): + super().setUp() + self.staff = UserFactory.create( + username="token-staff", email="token-staff@example.com", password=PASSWORD, + is_staff=True, is_superuser=True, + ) + self.learner = UserFactory.create( + username="token-learner", email="token-learner@example.com", password=PASSWORD, + ) + UserPreferenceFactory.create(user=self.learner, key="pref-lang", value="en") + PendingNameChange.objects.create( + user=self.learner, new_name="Renamed Learner", rationale="asked for in a test", + ) + self.addCleanup(self.remove_stored_images, self.staff.username) + + def remove_stored_images(self, username): + """Take whatever this user has stored out of the image store.""" + storage = get_profile_image_storage() + for name in get_profile_image_names(username).values(): + storage.delete(name) + + def token_headers(self, is_restricted): + """Return headers carrying the staff account's token, flagged restricted or not.""" + return {"HTTP_AUTHORIZATION": f"JWT {generate_jwt(self.staff, is_restricted=is_restricted)}"} + + def prepare(self, operation): + """Put in place what ``operation`` acts on beyond the fixtures every operation shares.""" + if operation == "profile_image_clear": + UserProfile.objects.filter(user=self.staff).update(profile_image_uploaded_at=datetime.now(UTC)) + + def call(self, operation, headers): + """Send the request that exercises ``operation``.""" + staff, learner = self.staff.username, self.learner.username + client = self.client + if operation == "user_list": + return client.get(reverse("user_v2:user_list"), **headers) + if operation == "user_detail": + return client.get(reverse("user_v2:user_detail", kwargs={"username": learner}), **headers) + if operation == "user_preference_list": + return client.get(reverse("user_v2:user_preference_list"), **headers) + if operation == "user_preference_detail": + return client.get( + reverse("user_v2:user_preference_detail", kwargs={"username": learner, "key": "pref-lang"}), + **headers, + ) + if operation == "time_zone_list": + return client.get(reverse("user_v2:time_zone_list"), **headers) + if operation == "account_list": + return client.get(reverse("user_v2:account_list"), **headers) + if operation == "account_detail": + return client.get(reverse("user_v2:account_detail", kwargs={"username": staff}), **headers) + if operation == "account_partial_update": + return client.patch( + reverse("user_v2:account_detail", kwargs={"username": staff}), + json.dumps({"bio": "Changed by a token"}), content_type=MERGE_PATCH, **headers, + ) + if operation == "account_deactivation": + return client.post(reverse("user_v2:account_deactivation", kwargs={"username": learner}), **headers) + if operation == "email_search": + return client.post( + reverse("user_v2:email_search_list"), {"emails": [self.learner.email]}, format="json", **headers, + ) + if operation == "name_change_request": + return client.post( + reverse("user_v2:name_change_list"), {"name": "Renamed Staff"}, format="json", **headers, + ) + if operation == "name_change_confirmation": + return client.post( + reverse("user_v2:name_change_confirmation", kwargs={"username": learner}), **headers, + ) + if operation == "verification_status": + return client.get( + reverse("user_v2:account_verification_status", kwargs={"username": learner}), **headers, + ) + if operation == "verification_list": + return client.get( + reverse("user_v2:account_verification_list", kwargs={"username": learner}), **headers, + ) + if operation == "profile_image_set": + with make_image_file() as image_file: + return client.post( + reverse("user_v2:account_profile_image", kwargs={"username": staff}), + {"file": image_file}, format="multipart", **headers, + ) + if operation == "profile_image_clear": + return client.delete(reverse("user_v2:account_profile_image", kwargs={"username": staff}), **headers) + raise AssertionError(f"No request is defined for {operation}") + + def state(self): + """Return what any of these operations could change.""" + staff = UserProfile.objects.get(user=self.staff) + learner = User.objects.get(pk=self.learner.pk) + return { + "staff_bio": staff.bio, + "staff_has_profile_image": staff.has_profile_image, + "staff_pending_name": PendingNameChange.objects.filter(user=self.staff).count(), + "learner_name": UserProfile.objects.get(user=self.learner).name, + "learner_password_usable": learner.has_usable_password(), + } + + OPERATIONS = { + "user_list": status.HTTP_200_OK, + "user_detail": status.HTTP_200_OK, + "user_preference_list": status.HTTP_200_OK, + "user_preference_detail": status.HTTP_200_OK, + "time_zone_list": status.HTTP_200_OK, + "account_list": status.HTTP_200_OK, + "account_detail": status.HTTP_200_OK, + "account_partial_update": status.HTTP_200_OK, + "account_deactivation": status.HTTP_204_NO_CONTENT, + "email_search": status.HTTP_200_OK, + "name_change_request": status.HTTP_201_CREATED, + "name_change_confirmation": status.HTTP_204_NO_CONTENT, + "verification_status": status.HTTP_200_OK, + "verification_list": status.HTTP_200_OK, + "profile_image_set": status.HTTP_204_NO_CONTENT, + "profile_image_clear": status.HTTP_204_NO_CONTENT, + } + + @ddt.data(*OPERATIONS) + def test_a_restricted_applications_token_is_refused(self, operation): + self.prepare(operation) + before = self.state() + response = self.call(operation, self.token_headers(is_restricted=True)) + assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") + assert self.state() == before + + @ddt.data(*OPERATIONS.items()) + @ddt.unpack + def test_the_same_token_from_an_ordinary_application_is_answered(self, operation, expected_status): + self.prepare(operation) + response = self.call(operation, self.token_headers(is_restricted=False)) + assert response.status_code == expected_status, response.content + + def test_a_restricted_token_leaves_a_requested_name_unconfirmed(self): + self.call("name_change_confirmation", self.token_headers(is_restricted=True)) + assert UserProfile.objects.get(user=self.learner).name != "Renamed Learner" + assert PendingNameChange.objects.filter(user=self.learner, new_name="Renamed Learner").exists() + + def test_an_ordinary_token_confirms_the_requested_name(self): + response = self.call("name_change_confirmation", self.token_headers(is_restricted=False)) + assert response.status_code == status.HTTP_204_NO_CONTENT + assert UserProfile.objects.get(user=self.learner).name == "Renamed Learner" + assert not PendingNameChange.objects.filter(user=self.learner).exists() diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index e891d262d35f..bb49f8502749 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -47,7 +47,13 @@ from .errors import AmbiguousAccountName, CatalogedRequestErrorsMixin, ErrorExtensionsMixin, RetiredAccount from .filters import StrictOrderingFilter, UserFilterSet, UserPreferenceFilterSet from .paginators import UserApiPagination -from .permissions import CanSelectAccountsByContact, IsActiveUser, IsAddressedUser, IsStaffOrAbsent +from .permissions import ( + CanSelectAccountsByContact, + IsActiveUser, + IsAddressedUser, + IsStaffOrAbsent, + RestrictedApplicationGuardMixin, +) from .schema import ResponseShapes from .selectors import ( accounts_holding_emails, @@ -652,6 +658,7 @@ def shape_page(self, response, request): ) class UserViewSet( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, _ActionAddressMixin, _MemberLookupMixin, @@ -769,6 +776,7 @@ def retrieve(self, request, *args, **kwargs): ) class UserPreferenceViewSet( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, _ActionAddressMixin, _ResponsePresetMixin, @@ -884,6 +892,7 @@ def retrieve(self, request, *args, **kwargs): @extend_schema(tags=[USER_TAG]) class CountryTimeZoneViewSet( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, _ActionAddressMixin, StrictQueryParametersMixin, @@ -1062,6 +1071,7 @@ def addressed_account(self): ) class AccountViewSet( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, ErrorExtensionsMixin, AccountResourceMixin, @@ -1423,6 +1433,7 @@ def _failed_change(self, username, error): ) class AccountDeactivationView( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, AccountResourceMixin, StrictQueryParametersMixin, @@ -1499,6 +1510,7 @@ def get_queryset(self): ) class EmailSearchViewSet( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, StrictQueryParametersMixin, IterablePaginationMixin, @@ -1590,6 +1602,7 @@ def create(self, request): ) class NameChangeViewSet( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, _ActionAddressMixin, StrictQueryParametersMixin, @@ -1705,6 +1718,7 @@ def _verification_sort_key(attempt): @extend_schema(tags=[SDK_TAG]) class IDVerificationStatusView( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, AccountResourceMixin, StrictQueryParametersMixin, @@ -1792,6 +1806,7 @@ def get(self, request, username): ) class IDVerificationViewSet( StandardizedErrorMixin, + RestrictedApplicationGuardMixin, CatalogedRequestErrorsMixin, AccountResourceMixin, StrictQueryParametersMixin, @@ -1841,7 +1856,7 @@ def list(self, request, username): @extend_schema(exclude=True) -class UnknownAddressView(StandardizedErrorMixin, APIView): +class UnknownAddressView(StandardizedErrorMixin, RestrictedApplicationGuardMixin, APIView): """ Refuses an address under this version of the API that no route serves. From 466c8bd511e3416f28c47870803d59a97bf8a719 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:08:10 +0500 Subject: [PATCH 41/61] fix: admit the API key at the user directory and stored preferences, as v1 does /api/user/v1/users/, its forum-role listing, /api/user/v1/user_prefs/ and its per-key listing admit a request by the site's API key in the X-Edx-Api-Key header and by nothing else. Their replacements, /api/user/v2/users/ and /api/user/v2/user_preferences/, admitted active platform administrators instead, so every integration that reads the directory with the key was refused 401 there and had no credential to carry over, while a staff account that v1 refuses was handed the directory. Both viewsets now declare the same permission class v1 declares. A request carrying the key is answered whoever sends it, as on v1; a staff or learner session or token without it is refused 403, and an anonymous request or one with another key 401, as on v1. The published descriptions say that the key is what admits a caller. Tests: the key alone reaches every directory address at both versions; a staff token or session without the key, a learner, the record's owner, and a key other than the site's are refused at every address; the directory tests now call with the key, and the query counts are measured for that caller, the same one the v1 comparison already used. Co-Authored-By: Claude Opus 5.5 --- .../profile_images/v2/tests/test_views.py | 2 +- .../user_api/v2/tests/test_account_views.py | 2 +- .../user_api/v2/tests/test_pagination.py | 24 +- .../user_api/v2/tests/test_parity.py | 83 ++-- .../user_api/v2/tests/test_query_counts.py | 50 +-- .../v2/tests/test_restricted_applications.py | 16 +- .../user_api/v2/tests/test_schema.py | 14 +- .../user_api/v2/tests/test_views.py | 390 ++++++++++-------- openedx/core/djangoapps/user_api/v2/views.py | 32 +- 9 files changed, 357 insertions(+), 256 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py index a3511b40aff7..208d7c867ae8 100644 --- a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py +++ b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py @@ -590,7 +590,7 @@ def test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaul with mock.patch(DEFAULT_AUTH_RECORDER) as recorded: on_the_default_pair = self.client.get( - reverse("user_v2:user_preference_list"), **self.token_headers(self.staff), + reverse("user_v2:time_zone_list"), **self.token_headers(self.staff), ) assert on_the_default_pair.status_code == status.HTTP_200_OK assert [call.args for call in recorded.call_args_list] == [("using_default_auth_classes", True)] diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 89b59632c754..1d012faddd97 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -1040,7 +1040,7 @@ def test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaul with mock.patch(DEFAULT_AUTH_RECORDER) as recorded: on_the_default_pair = self.client.get( - reverse("user_v2:user_preference_list"), **self.token_headers(self.staff), + reverse("user_v2:time_zone_list"), **self.token_headers(self.staff), ) assert on_the_default_pair.status_code == status.HTTP_200_OK assert [call.args for call in recorded.call_args_list] == [("using_default_auth_classes", True)] diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_pagination.py b/openedx/core/djangoapps/user_api/v2/tests/test_pagination.py index 667417184f4c..c45aecec2c55 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_pagination.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_pagination.py @@ -2,6 +2,7 @@ import inspect +from django.test.utils import override_settings from django.urls import reverse from edx_rest_framework_extensions.testing import assert_error_envelope from rest_framework import status @@ -14,6 +15,10 @@ from openedx.core.djangolib.testing.utils import skip_unless_lms PASSWORD = "Password1234" +API_KEY = "page-test-api-key" + +#: Stands for the caller the directory admits: a request carrying the site's API key. +KEY_HOLDER = object() #: Values naming a number of rows no page can carry: none at all, fewer than #: none, and values that are not a whole number of rows in the first place. @@ -27,6 +32,7 @@ @skip_unless_lms +@override_settings(EDX_API_KEY=API_KEY) class PageSizeTests(APITestCase): """ A page size the collection will not give is refused rather than answered. @@ -48,8 +54,8 @@ def setUp(self): def collections(self): """Return each paginated collection, the caller it admits and how it is asked.""" return { - "user_list": (self.admin, reverse("user_v2:user_list"), {}), - "user_preference_list": (self.admin, reverse("user_v2:user_preference_list"), {}), + "user_list": (KEY_HOLDER, reverse("user_v2:user_list"), {}), + "user_preference_list": (KEY_HOLDER, reverse("user_v2:user_preference_list"), {}), "time_zone_list": (None, reverse("user_v2:time_zone_list"), {}), "account_list": (self.learner, reverse("user_v2:account_list"), {}), "account_verification_list": ( @@ -70,7 +76,10 @@ def collections(self): def ask(self, caller, address, page_size, body=None): """Ask one collection for a page of ``page_size`` rows as ``caller``.""" self.client.logout() - if caller is not None: + self.client.credentials() + if caller is KEY_HOLDER: + self.client.credentials(HTTP_X_EDX_API_KEY=API_KEY) + elif caller is not None: assert self.client.login(username=caller.username, password=PASSWORD) query = "" if page_size is None else f"?page_size={page_size}" if body is None: @@ -103,9 +112,9 @@ def test_more_rows_than_a_page_carries_is_answered_with_as_many_as_it_carries(se """A number above the cap keeps being answered with the cap rather than refused.""" for index in range(UserApiPagination.max_page_size + 5): UserFactory.create(username=f"page-filler{index:03d}") - self.client.logout() - assert self.client.login(username=self.admin.username, password=PASSWORD) - response = self.client.get(reverse("user_v2:user_list"), {"page_size": 100000}) + response = self.client.get( + reverse("user_v2:user_list"), {"page_size": 100000}, HTTP_X_EDX_API_KEY=API_KEY, + ) assert response.status_code == status.HTTP_200_OK, response.content assert len(response.data["results"]) == UserApiPagination.max_page_size @@ -119,8 +128,7 @@ def test_the_link_to_the_next_page_carries_a_size_the_next_page_will_give(self): """ for index in range(5): UserFactory.create(username=f"page-walked{index:03d}") - self.client.logout() - assert self.client.login(username=self.admin.username, password=PASSWORD) + self.client.credentials(HTTP_X_EDX_API_KEY=API_KEY) response = self.client.get(reverse("user_v2:user_list"), {"page_size": 2}) assert response.status_code == status.HTTP_200_OK, response.content assert len(response.data["results"]) == 2 diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_parity.py index f5caac0bb7a5..3c74118ca116 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_parity.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_parity.py @@ -114,11 +114,8 @@ def legacy(self, address, params=None): return self.client.get(address, params or {}, HTTP_X_EDX_API_KEY=API_KEY) def conforming(self, address, params=None): - """Call a version 2 address as the administrator it is gated by.""" - assert self.client.login(username=self.admin.username, password=PASSWORD) - response = self.client.get(address, params or {}) - self.client.logout() - return response + """Call a version 2 address with the same API key.""" + return self.client.get(address, params or {}, HTTP_X_EDX_API_KEY=API_KEY) def assert_parity(self, legacy, new, case, expected_status=status.HTTP_200_OK): """ @@ -161,28 +158,53 @@ def test_the_conforming_page_is_ordered_by_username_whatever_the_creation_order( legacy_usernames = [row["username"] for row in json.loads(legacy.content)["results"]] assert sorted(legacy_usernames) == usernames - def test_the_api_key_admits_at_the_legacy_addresses_only(self): - """The header the version 1 addresses are gated by is not a credential at version 2.""" - legacy = self.legacy("/api/user/v1/users/", {"page_size": 100}) - assert legacy.status_code == status.HTTP_200_OK, legacy.content - assert sorted(row["username"] for row in json.loads(legacy.content)["results"]) == [ - "parity-admin", "parity-user", - ] - - for address in ( - reverse("user_v2:user_list"), - reverse("user_v2:user_detail", kwargs={"username": "parity-user"}), - reverse("user_v2:user_preference_list"), - reverse( - "user_v2:user_preference_detail", - kwargs={"username": "parity-user", "key": "pref-lang"}, + def directory_addresses(self): + """Return each directory address of version 1 beside the version 2 address replacing it.""" + return { + "user_list": ("/api/user/v1/users/", reverse("user_v2:user_list")), + "user_detail": ( + f"/api/user/v1/users/{self.user.id}/", + reverse("user_v2:user_detail", kwargs={"username": "parity-user"}), ), - ): - refused = self.client.get(address, HTTP_X_EDX_API_KEY=API_KEY) - envelope = assert_error_envelope( - refused, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", - ) - assert envelope["detail"] == "Authentication credentials were not provided.", address + "preference_list": ("/api/user/v1/user_prefs/", reverse("user_v2:user_preference_list")), + "preference_detail": ( + f"/api/user/v1/user_prefs/{self.preference.id}/", + reverse( + "user_v2:user_preference_detail", + kwargs={"username": "parity-user", "key": "pref-lang"}, + ), + ), + } + + def test_the_api_key_alone_admits_at_both_versions(self): + """The header the version 1 addresses are read with is what admits a caller to version 2.""" + for name, (legacy_address, address) in self.directory_addresses().items(): + with self.subTest(address=name): + legacy = self.legacy(legacy_address) + assert legacy.status_code == status.HTTP_200_OK, legacy.content + new = self.conforming(address) + assert new.status_code == status.HTTP_200_OK, new.content + + def test_a_staff_account_without_the_key_is_refused_at_both_versions(self): + assert self.client.login(username=self.admin.username, password=PASSWORD) + for name, (legacy_address, address) in self.directory_addresses().items(): + with self.subTest(address=name): + legacy = self.client.get(legacy_address) + assert legacy.status_code == status.HTTP_403_FORBIDDEN, legacy.content + envelope = assert_error_envelope( + self.client.get(address), expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + assert envelope["detail"] == json.loads(legacy.content)["detail"] + + def test_a_key_other_than_the_sites_is_refused_at_both_versions(self): + for name, (legacy_address, address) in self.directory_addresses().items(): + with self.subTest(address=name): + legacy = self.client.get(legacy_address, HTTP_X_EDX_API_KEY=f"{API_KEY}-other") + assert legacy.status_code == status.HTTP_401_UNAUTHORIZED, legacy.content + assert_error_envelope( + self.client.get(address, HTTP_X_EDX_API_KEY=f"{API_KEY}-other"), + expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) def test_user_detail_parity(self): legacy = self.legacy(f"/api/user/v1/users/{self.user.id}/") @@ -375,6 +397,7 @@ def test_an_identifier_held_by_a_caller_resolves_to_the_username_the_entry_is_ke @skip_unless_lms +@override_settings(EDX_API_KEY=API_KEY) class RefusedRequestMessageTests(APITestCase): """ What a person reads when a request of either version is refused. @@ -394,9 +417,9 @@ def setUp(self): self.admin = AdminFactory.create(username="refusal-admin", password=PASSWORD) def refused(self, address, params): - """Call a version 2 address as the administrator it is gated by.""" + """Call a version 2 address as an administrator carrying the site's API key.""" assert self.client.login(username=self.admin.username, password=PASSWORD) - response = self.client.get(address, params) + response = self.client.get(address, params, HTTP_X_EDX_API_KEY=API_KEY) self.client.logout() return assert_error_envelope( response, @@ -464,7 +487,9 @@ def test_a_refusal_that_names_nothing_in_particular_is_spelled_on_its_own(self): def test_a_refusal_naming_no_parameter_says_what_it_has_always_said(self): """Only the refusals built from a list of parameters change; the rest are untouched.""" assert self.client.login(username=self.admin.username, password=PASSWORD) - missing = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "nobody"})) + missing = self.client.get( + reverse("user_v2:user_detail", kwargs={"username": "nobody"}), HTTP_X_EDX_API_KEY=API_KEY, + ) envelope = assert_error_envelope( missing, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", ) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py b/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py index fc41425a9e89..9e4d90ec9e8e 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_query_counts.py @@ -1,15 +1,13 @@ """Query-count guards for the version 2 User API list and member addresses.""" import pytest -from django.test.utils import override_settings from django.urls import reverse -from common.djangoapps.student.tests.factories import AdminFactory, UserFactory +from common.djangoapps.student.tests.factories import UserFactory from openedx.core.djangoapps.django_comment_common.models import Role from openedx.core.djangoapps.user_api.tests.factories import UserPreferenceFactory from openedx.core.djangolib.testing.utils import skip_unless_lms -PASSWORD = "Password1234" COURSE_KEY = "course-v1:edX+DemoX+Demo" #: Row counts a per-row query would show up at. @@ -19,24 +17,26 @@ #: not database rows and whose size is therefore set by the page alone. PAGE_SIZES = [1, 10, 100] -USER_LIST_QUERIES = 16 -USER_DETAIL_QUERIES = 15 -PREFERENCE_LIST_QUERIES = 15 +USER_LIST_QUERIES = 11 +USER_DETAIL_QUERIES = 10 +PREFERENCE_LIST_QUERIES = 10 #: One more than the list costs without the preset: the owners whose entry #: a page may carry are resolved for the whole page in a single query, #: whatever the number of rows. -PREFERENCE_LIST_FULL_VIEW_QUERIES = 17 -PREFERENCE_DETAIL_QUERIES = 14 +PREFERENCE_LIST_FULL_VIEW_QUERIES = 12 +PREFERENCE_DETAIL_QUERIES = 9 #: What the same address costs with the owner's entry asked for: the entry's #: own preferences, and the one query that settles which owners' entries may #: be carried. -PREFERENCE_DETAIL_FULL_VIEW_QUERIES = 16 -TIME_ZONE_LIST_QUERIES = 13 +PREFERENCE_DETAIL_FULL_VIEW_QUERIES = 11 +TIME_ZONE_LIST_QUERIES = 8 -#: Address of the stored-preference list this version replaces, and the key it -#: is gated by, so the cost of the two can be compared in one measurement. +#: Address of the stored-preference list this version replaces, measured with +#: the same key so that the cost of the two is compared in one measurement. EARLIER_PREFERENCE_LIST = "/api/user/v1/user_prefs/" -EARLIER_API_KEY = "query-count-api-key" + +#: The site's API key, which both versions of the directory are read with. +API_KEY = "query-count-api-key" #: What that list costs for a page holding two rows per user, measured the same #: way as the counts above: a constant part plus five queries for every user on @@ -47,18 +47,18 @@ @pytest.fixture(name="directory") @skip_unless_lms -def directory_fixture(request, client, django_user_model): # pylint: disable=unused-argument - """Sign an administrator in and populate the directory with ``request.param`` users.""" - admin = AdminFactory.create(username="count-admin", password=PASSWORD) +def directory_fixture(request, client, settings, django_user_model): # pylint: disable=unused-argument + """Send the site's API key with every request and populate the directory with ``request.param`` users.""" + settings.EDX_API_KEY = API_KEY + client.defaults["HTTP_X_EDX_API_KEY"] = API_KEY users = [UserFactory.create(username=f"counted{index}") for index in range(request.param)] for user in users: UserPreferenceFactory.create(user=user, key="pref-lang", value="en") UserPreferenceFactory.create(user=user, key="time_zone", value="UTC") role = Role.objects.create(course_id=COURSE_KEY, name="Moderator") role.users.add(*users) - assert client.login(username=admin.username, password=PASSWORD) - # The first authenticated request of a session populates caches the rest - # of the session reuses; the counts below are the steady-state ones. + # The first request populates caches the later ones reuse; the counts + # below are the steady-state ones. client.get(reverse("user_v2:user_list")) return users @@ -70,7 +70,7 @@ def test_user_list_query_count_does_not_grow_with_rows(client, directory, django url = reverse("user_v2:user_list") with django_assert_num_queries(USER_LIST_QUERIES): response = client.get(url, {"page_size": 100}) - assert len(response.json()["results"]) == len(directory) + 1 + assert len(response.json()["results"]) == len(directory) @pytest.mark.django_db @@ -199,12 +199,6 @@ def test_the_earlier_preference_list_pays_per_row_where_this_one_does_not( current = client.get(reverse("user_v2:user_preference_list"), {"page_size": 100}) assert len(current.json()["results"]) == 2 * len(directory) - client.logout() - with override_settings(EDX_API_KEY=EARLIER_API_KEY): - with django_assert_num_queries(EARLIER_PREFERENCE_LIST_QUERIES[len(directory)]): - earlier = client.get( - EARLIER_PREFERENCE_LIST, - {"page_size": 100}, - HTTP_X_EDX_API_KEY=EARLIER_API_KEY, - ) + with django_assert_num_queries(EARLIER_PREFERENCE_LIST_QUERIES[len(directory)]): + earlier = client.get(EARLIER_PREFERENCE_LIST, {"page_size": 100}) assert len(earlier.json()["results"]) == 2 * len(directory) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_restricted_applications.py b/openedx/core/djangoapps/user_api/v2/tests/test_restricted_applications.py index 852e4a2b9270..ce348ef7e708 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_restricted_applications.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_restricted_applications.py @@ -6,6 +6,7 @@ import ddt from django.contrib.auth.models import User # pylint: disable=imported-auth-user from django.test import SimpleTestCase +from django.test.utils import override_settings from django.urls import reverse from edx_rest_framework_extensions.auth.jwt.tests.utils import generate_jwt from edx_rest_framework_extensions.permissions import NotJwtRestrictedApplication @@ -25,6 +26,7 @@ PASSWORD = "Password1234" MERGE_PATCH = "application/merge-patch+json" +API_KEY = "restricted-token-test-api-key" def routed_views(): @@ -87,6 +89,7 @@ def test_the_name_change_confirmation_keeps_its_own_classes_and_gains_the_refusa @skip_unless_lms @ddt.ddt +@override_settings(EDX_API_KEY=API_KEY) class RestrictedApplicationTokenTests(APITestCase): """ A token issued to a restricted application is refused at every operation that reads a token. @@ -94,7 +97,9 @@ class RestrictedApplicationTokenTests(APITestCase): Each operation is called twice by the same staff account, once with a token issued to an ordinary application, which the operation answers, and once with the same token flagged as issued to a restricted application, - which it refuses before changing anything. + which it refuses before changing anything. The directory addresses are + sent the site's API key as well, since that is what admits a caller there, + so the token is the only thing that can refuse the request. """ def setUp(self): @@ -131,16 +136,17 @@ def call(self, operation, headers): """Send the request that exercises ``operation``.""" staff, learner = self.staff.username, self.learner.username client = self.client + directory = {**headers, "HTTP_X_EDX_API_KEY": API_KEY} if operation == "user_list": - return client.get(reverse("user_v2:user_list"), **headers) + return client.get(reverse("user_v2:user_list"), **directory) if operation == "user_detail": - return client.get(reverse("user_v2:user_detail", kwargs={"username": learner}), **headers) + return client.get(reverse("user_v2:user_detail", kwargs={"username": learner}), **directory) if operation == "user_preference_list": - return client.get(reverse("user_v2:user_preference_list"), **headers) + return client.get(reverse("user_v2:user_preference_list"), **directory) if operation == "user_preference_detail": return client.get( reverse("user_v2:user_preference_detail", kwargs={"username": learner, "key": "pref-lang"}), - **headers, + **directory, ) if operation == "time_zone_list": return client.get(reverse("user_v2:time_zone_list"), **headers) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index 292a7ee26520..1a59819998c3 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -42,6 +42,8 @@ from openedx.core.djangolib.testing.utils import skip_unless_lms PASSWORD = "Password1234" +#: The site's API key, which the user directory and the stored preferences are read with. +API_KEY = "schema-test-api-key" #: Stands for a property a response does not carry, where that is the assertion. ABSENT = "absent" @@ -452,11 +454,11 @@ def test_pagination_envelope_is_published_in_full(schema): @pytest.mark.django_db @skip_unless_lms -def test_published_pagination_envelope_matches_the_response_body(client, schema): +def test_published_pagination_envelope_matches_the_response_body(client, schema, settings): + settings.EDX_API_KEY = API_KEY admin = AdminFactory.create(username="schema-admin", password=PASSWORD) UserPreferenceFactory.create(user=admin, key="pref-lang", value="en") - assert client.login(username=admin.username, password=PASSWORD) - body = client.get(reverse("user_v2:user_preference_list")).json() + body = client.get(reverse("user_v2:user_preference_list"), HTTP_X_EDX_API_KEY=API_KEY).json() published = schema["components"]["schemas"]["PaginatedUserPreferenceRecordResponseList"] assert set(body) == set(published["properties"]) @@ -771,12 +773,16 @@ def name_affirmation_answering(verified_name): @pytest.mark.django_db @skip_unless_lms -def test_published_shapes_accept_every_body_the_endpoints_return(client, schema): +def test_published_shapes_accept_every_body_the_endpoints_return(client, schema, settings): """Every preset and selection the parameters offer returns a body the document describes.""" + settings.EDX_API_KEY = API_KEY admin = AdminFactory.create(username="shape-admin", password=PASSWORD) UserPreferenceFactory.create(user=admin, key="pref-lang", value="en") fill_in(admin) assert client.login(username=admin.username, password=PASSWORD) + # The account addresses read the signed-in administrator; the directory + # addresses read the key. + client.defaults["HTTP_X_EDX_API_KEY"] = API_KEY for published_path, address, params, component in SHAPE_CASES: case = (address, params) response = client.get(address, params) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index b3867dc44b0f..a2e6b6ec3ffc 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -10,7 +10,7 @@ from django.core.exceptions import ImproperlyConfigured from django.db import connection from django.test import SimpleTestCase -from django.test.utils import CaptureQueriesContext +from django.test.utils import CaptureQueriesContext, override_settings from django.urls import reverse from edx_rest_framework_extensions.testing import assert_error_envelope from opaque_keys.edx.keys import CourseKey @@ -31,6 +31,7 @@ from openedx.core.djangolib.testing.utils import skip_unless_lms PASSWORD = "Password1234" +API_KEY = "directory-test-api-key" COURSE_KEY = CourseKey.from_string("course-v1:edX+DemoX+Demo") OTHER_COURSE_KEY = CourseKey.from_string("course-v1:edX+OtherX+Other") @@ -143,6 +144,7 @@ def test_the_target_table_is_read_through_any_backend_quoting(self): assert write_target(self.USER_SELECT) is None +@override_settings(EDX_API_KEY=API_KEY) class UserApiV2TestCase(APITestCase): """Fixtures shared by the version 2 User API tests.""" @@ -159,6 +161,10 @@ def login(self, user): """Sign the given user in through the session the platform default accepts.""" assert self.client.login(username=user.username, password=PASSWORD) + def send_api_key(self): + """Send the site's API key with every later request, which is how the directory is read.""" + self.client.credentials(HTTP_X_EDX_API_KEY=API_KEY) + def usernames_in(self, response): """Return the usernames carried by a paginated directory page.""" return [row["username"] for row in response.data["results"]] @@ -176,18 +182,18 @@ def test_anonymous_caller_is_unauthenticated(self): response = self.client.get(self.url) assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") - def test_non_admin_caller_is_forbidden(self): + def test_a_caller_without_the_key_is_forbidden(self): self.login(self.learner) response = self.client.get(self.url) assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") - def test_non_admin_cannot_list_another_users_preference_holders(self): + def test_a_caller_without_the_key_cannot_list_another_users_preference_holders(self): self.login(self.learner) response = self.client.get(self.url, {"preference_key": "pref-lang"}) assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") - def test_admin_caller_receives_the_directory(self): - self.login(self.admin) + def test_a_caller_with_the_key_receives_the_directory(self): + self.send_api_key() response = self.client.get(self.url, {"page_size": 100}) assert response.status_code == status.HTTP_200_OK assert set(response.data) == PAGINATION_KEYS @@ -198,7 +204,7 @@ def test_admin_caller_receives_the_directory(self): assert response.data["start"] == 0 def test_row_shape_matches_the_declared_fields(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice"}) row = response.data["results"][0] assert set(row) == {"id", "url", "email", "name", "username", "preferences"} @@ -209,7 +215,7 @@ def test_row_shape_matches_the_declared_fields(self): assert row["url"].endswith("/api/user/v2/users/alice/") def test_second_page_reports_its_position(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"page_size": 2, "page": 2}) assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["bob", "learner-caller"] @@ -220,17 +226,17 @@ def test_second_page_reports_its_position(self): assert response.data["next"] is None def test_a_page_beyond_the_last_one_is_not_found(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"page": 9999}) assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") def test_a_page_number_that_is_not_a_number_is_not_found(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"page": "abc"}) assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") def test_ordering_can_be_reversed(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"ordering": "-username", "page_size": 100}) assert self.usernames_in(response) == ["learner-caller", "bob", "alice", "admin-caller"] @@ -239,12 +245,12 @@ def test_ordering_by_join_date(self): self.alice.save() self.bob.date_joined = datetime(2019, 1, 1, tzinfo=UTC) self.bob.save() - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"ordering": "date_joined", "page_size": 100}) assert self.usernames_in(response)[-2:] == ["bob", "alice"] def test_unknown_ordering_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"ordering": "password", "page_size": 100}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -254,14 +260,14 @@ def test_unknown_ordering_is_refused(self): } def test_one_unknown_field_refuses_the_whole_sort(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"ordering": "username,password", "page_size": 100}) assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", ) def test_filter_by_username(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "bob", "page_size": 100}) assert self.usernames_in(response) == ["bob"] @@ -274,45 +280,45 @@ def test_several_names_select_the_entries_of_each(self): page of the accounts asked for rather than as a value this collection does not take. """ - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice,bob", "page_size": 100}) assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["alice", "bob"] assert response.data["count"] == 2 def test_a_name_in_the_list_that_no_account_holds_is_left_out_of_the_page(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice,nobody", "page_size": 100}) assert self.usernames_in(response) == ["alice"] assert response.data["count"] == 1 def test_a_position_in_the_list_that_carries_nothing_names_nothing(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": ",alice,,bob,", "page_size": 100}) assert self.usernames_in(response) == ["alice", "bob"] def test_an_empty_name_narrows_nothing(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "", "page_size": 100}) assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] def test_filter_by_email(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"email": "bob@example.com"}) assert self.usernames_in(response) == ["bob"] def test_filter_by_is_active(self): self.alice.is_active = False self.alice.save() - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"is_active": "false", "page_size": 100}) assert self.usernames_in(response) == ["alice"] def test_filter_by_is_active_keeps_only_the_active_accounts(self): self.alice.is_active = False self.alice.save() - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"is_active": "true", "page_size": 100}) assert self.usernames_in(response) == ["admin-caller", "bob", "learner-caller"] @@ -320,7 +326,7 @@ def test_an_is_active_value_that_names_no_side_is_refused(self): """A mistyped value must be refused, not read as "no preference" and answered unfiltered.""" self.alice.is_active = False self.alice.save() - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"is_active": "maybe", "page_size": 100}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -330,18 +336,18 @@ def test_an_is_active_value_that_names_no_side_is_refused(self): def test_an_empty_is_active_value_narrows_nothing(self): self.alice.is_active = False self.alice.save() - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"is_active": "", "page_size": 100}) assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] def test_filter_by_preference_key(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"preference_key": "pref-lang", "page_size": 100}) assert self.usernames_in(response) == ["alice"] def test_filter_by_unknown_preference_key_returns_no_rows(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"preference_key": "nope", "page_size": 100}) assert response.data["results"] == [] assert response.data["count"] == 0 @@ -356,7 +362,7 @@ def test_filter_by_forum_role_and_course(self): self.give_alice_the_moderator_role() other_role = Role.objects.create(course_id=OTHER_COURSE_KEY, name="Moderator") other_role.users.add(self.bob) - self.login(self.admin) + self.send_api_key() response = self.client.get( self.url, {"forum_role": "Moderator", "course_key": str(COURSE_KEY), "page_size": 100}, ) @@ -369,7 +375,7 @@ def test_anonymous_caller_cannot_list_a_courses_forum_role_holders(self): ) assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") - def test_non_admin_cannot_list_a_courses_forum_role_holders(self): + def test_a_caller_without_the_key_cannot_list_a_courses_forum_role_holders(self): self.give_alice_the_moderator_role() self.login(self.learner) response = self.client.get( @@ -393,14 +399,14 @@ def test_the_published_course_key_example_can_be_pasted_into_a_query_string(self ).group(1) role = Role.objects.create(course_id=COURSE_KEY, name="Moderator") role.users.add(self.alice) - self.login(self.admin) + self.send_api_key() response = self.client.get(f"{self.url}?forum_role=Moderator&course_key={example}") assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["alice"] def test_a_course_key_whose_plus_signs_are_not_encoded_is_refused(self): """An unencoded plus sign arrives as a space, which no course key may contain.""" - self.login(self.admin) + self.send_api_key() response = self.client.get( f"{self.url}?forum_role=Moderator&course_key=course-v1:edX+DemoX+Demo", ) @@ -414,7 +420,7 @@ def test_a_user_holding_the_role_through_several_rows_is_listed_once(self): for _ in range(2): role = Role.objects.create(course_id=COURSE_KEY, name="Moderator") role.users.add(self.alice) - self.login(self.admin) + self.send_api_key() response = self.client.get( self.url, {"forum_role": "Moderator", "course_key": str(COURSE_KEY), "page_size": 100}, ) @@ -422,7 +428,7 @@ def test_a_user_holding_the_role_through_several_rows_is_listed_once(self): assert response.data["count"] == 1 def test_forum_role_without_course_key_is_rejected(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"forum_role": "Moderator"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -432,7 +438,7 @@ def test_forum_role_without_course_key_is_rejected(self): } def test_course_key_without_forum_role_is_rejected(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"course_key": str(COURSE_KEY)}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -442,7 +448,7 @@ def test_course_key_without_forum_role_is_rejected(self): } def test_malformed_course_key_is_rejected(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"forum_role": "Moderator", "course_key": "not a course"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -450,7 +456,7 @@ def test_malformed_course_key_is_rejected(self): assert envelope["errors"] == {"course_key": ["Enter a valid course key."]} def test_unknown_forum_role_returns_no_rows_and_creates_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: response = self.client.get( self.url, {"forum_role": "Inquisitor", "course_key": str(COURSE_KEY)}, @@ -461,26 +467,26 @@ def test_unknown_forum_role_returns_no_rows_and_creates_nothing(self): assert write_queries(captured.captured_queries) == [] def test_minimal_view_returns_only_identifying_fields(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice", "view": "minimal"}) row = response.data["results"][0] assert set(row) == {"id", "username", "email"} assert row["username"] == "alice" def test_fields_parameter_projects_the_row(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice", "fields": "username,email"}) assert response.data["results"] == [{"username": "alice", "email": "alice@example.com"}] def test_fields_parameter_narrows_the_minimal_view(self): - self.login(self.admin) + self.send_api_key() response = self.client.get( self.url, {"username": "alice", "view": "minimal", "fields": "username"}, ) assert response.data["results"] == [{"username": "alice"}] def test_a_field_name_the_row_does_not_carry_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"fields": "user_name"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -494,7 +500,7 @@ def test_a_field_name_the_row_does_not_carry_is_refused(self): def test_a_field_the_minimal_preset_drops_is_refused(self): """The preset decides what the row carries, so the selection is judged against it.""" - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"view": "minimal", "fields": "name"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -504,7 +510,7 @@ def test_a_field_the_minimal_preset_drops_is_refused(self): } def test_every_unknown_field_name_is_named_at_once(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"fields": "username,e_mail,joined"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -512,7 +518,7 @@ def test_every_unknown_field_name_is_named_at_once(self): assert envelope["errors"]["fields"][0].startswith("No such field: e_mail, joined.") def test_a_field_name_with_surrounding_space_is_accepted(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice", "fields": " username , email "}) assert response.data["results"] == [{"username": "alice", "email": "alice@example.com"}] @@ -521,7 +527,7 @@ def test_an_unknown_field_does_not_answer_an_anonymous_caller(self): assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") def test_an_unknown_response_preset_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"view": "nonsense"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -531,7 +537,7 @@ def test_an_unknown_response_preset_is_refused(self): } def test_the_preset_that_belongs_to_the_preference_list_is_refused_here(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"view": "full"}) assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -539,7 +545,7 @@ def test_the_preset_that_belongs_to_the_preference_list_is_refused_here(self): def test_an_empty_response_preset_returns_the_default_shape(self): """A query string built from an empty variable narrows nothing rather than failing.""" - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice", "view": ""}) assert response.status_code == status.HTTP_200_OK assert set(response.data["results"][0]) == { @@ -551,13 +557,13 @@ def test_an_unknown_preset_does_not_answer_an_anonymous_caller(self): assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") def test_listing_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: self.client.get(self.url, {"page_size": 100}) assert write_queries(captured.captured_queries) == [] def test_head_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: response = self.client.head(self.url) assert response.status_code == status.HTTP_200_OK @@ -576,18 +582,18 @@ def test_anonymous_caller_is_unauthenticated(self): response = self.client.get(self.url_for("alice")) assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") - def test_non_admin_caller_is_forbidden(self): + def test_a_caller_without_the_key_is_forbidden(self): self.login(self.learner) response = self.client.get(self.url_for("alice")) assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") - def test_owner_who_is_not_an_admin_is_forbidden(self): + def test_the_owner_without_the_key_is_forbidden(self): self.login(self.alice) response = self.client.get(self.url_for("alice")) assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") - def test_admin_caller_receives_the_entry(self): - self.login(self.admin) + def test_a_caller_with_the_key_receives_the_entry(self): + self.send_api_key() response = self.client.get(self.url_for("alice")) assert response.status_code == status.HTTP_200_OK assert response.data["username"] == "alice" @@ -595,24 +601,24 @@ def test_admin_caller_receives_the_entry(self): assert response.data["preferences"] == {"pref-lang": "en"} def test_unknown_username_is_not_found(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("nobody")) assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") def test_username_containing_a_dot_resolves(self): UserFactory.create(username="ada.lovelace", email="ada@example.com", password=PASSWORD) - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("ada.lovelace")) assert response.status_code == status.HTTP_200_OK assert response.data["username"] == "ada.lovelace" def test_minimal_view_returns_only_identifying_fields(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice"), {"view": "minimal"}) assert set(response.data) == {"id", "username", "email"} def test_a_field_name_the_entry_does_not_carry_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice"), {"fields": "user_name"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -625,12 +631,12 @@ def test_a_field_name_the_entry_does_not_carry_is_refused(self): } def test_fields_parameter_projects_the_entry(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice"), {"fields": "username"}) assert response.data == {"username": "alice"} def test_an_unknown_response_preset_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice"), {"view": "nonsense"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -640,13 +646,13 @@ def test_an_unknown_response_preset_is_refused(self): } def test_retrieval_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: self.client.get(self.url_for("alice")) assert write_queries(captured.captured_queries) == [] def test_head_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: response = self.client.head(self.url_for("alice")) assert response.status_code == status.HTTP_200_OK @@ -659,7 +665,7 @@ class ProfilelessUserTests(UserApiV2TestCase): def test_user_without_a_profile_has_a_null_name(self): User.objects.create_user("profileless", "profileless@example.com", PASSWORD) - self.login(self.admin) + self.send_api_key() response = self.client.get( reverse("user_v2:user_detail", kwargs={"username": "profileless"}), ) @@ -683,25 +689,25 @@ def test_anonymous_caller_is_unauthenticated(self): response = self.client.get(self.url) assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") - def test_non_admin_caller_is_forbidden(self): + def test_a_caller_without_the_key_is_forbidden(self): self.login(self.learner) response = self.client.get(self.url) assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") - def test_owner_who_is_not_an_admin_is_forbidden(self): + def test_the_owner_without_the_key_is_forbidden(self): self.login(self.alice) response = self.client.get(self.url, {"username": "alice"}) assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") - def test_admin_caller_receives_every_preference(self): - self.login(self.admin) + def test_a_caller_with_the_key_receives_every_preference(self): + self.send_api_key() response = self.client.get(self.url, {"page_size": 100}) assert response.status_code == status.HTTP_200_OK assert set(response.data) == PAGINATION_KEYS assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "time_zone")] def test_row_shape_is_flat_by_default(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice"}) row = response.data["results"][0] assert set(row) == {"username", "key", "value", "url", "user"} @@ -712,7 +718,7 @@ def test_row_shape_is_flat_by_default(self): assert row["url"].endswith("/api/user/v2/user_preferences/alice,pref-lang/") def test_full_view_embeds_the_owning_user(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice", "view": "full"}) row = response.data["results"][0] assert set(row["user"]) == {"id", "url", "email", "name", "username", "preferences"} @@ -720,12 +726,12 @@ def test_full_view_embeds_the_owning_user(self): assert row["user"]["preferences"] == {"pref-lang": "en"} def test_minimal_view_drops_the_address_and_owner(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice", "view": "minimal"}) assert response.data["results"] == [{"username": "alice", "key": "pref-lang", "value": "en"}] def test_a_field_name_the_row_does_not_carry_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"fields": "preference_key"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -738,48 +744,48 @@ def test_a_field_name_the_row_does_not_carry_is_refused(self): } def test_a_page_beyond_the_last_one_is_not_found(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"page": 9999}) assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") def test_fields_parameter_projects_the_row(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice", "fields": "key,value"}) assert response.data["results"] == [{"key": "pref-lang", "value": "en"}] def test_filter_by_key(self): UserPreferenceFactory.create(user=self.bob, key="pref-lang", value="fr") - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"key": "pref-lang", "page_size": 100}) assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "pref-lang")] def test_filter_by_username(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "bob", "page_size": 100}) assert self.keys_in(response) == [("bob", "time_zone")] def test_several_names_select_the_preferences_of_each(self): """The value is a list of names, as it is on the sibling collections of this version.""" - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice,bob", "page_size": 100}) assert response.status_code == status.HTTP_200_OK assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "time_zone")] assert response.data["count"] == 2 def test_a_name_in_the_list_that_no_account_holds_is_left_out_of_the_page(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice,nobody", "page_size": 100}) assert self.keys_in(response) == [("alice", "pref-lang")] def test_an_empty_name_narrows_nothing(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "", "page_size": 100}) assert response.status_code == status.HTTP_200_OK assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "time_zone")] def test_the_owner_id_the_earlier_list_took_is_refused_rather_than_ignored(self): """A caller that ported by changing the version segment is told, not quietly unfiltered.""" - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"user": self.alice.id, "page_size": 100}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -789,26 +795,26 @@ def test_the_owner_id_the_earlier_list_took_is_refused_rather_than_ignored(self) } def test_an_answered_page_announces_no_deprecated_parameter(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"username": "alice"}) assert response.status_code == status.HTTP_200_OK assert "Deprecation" not in response def test_ordering_by_key_descending(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"ordering": "-key", "page_size": 100}) assert self.keys_in(response) == [("bob", "time_zone"), ("alice", "pref-lang")] def test_ordering_takes_the_fields_in_the_order_they_are_named(self): UserPreferenceFactory.create(user=self.bob, key="pref-lang", value="fr") - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"ordering": "key,-username", "page_size": 100}) assert self.keys_in(response) == [ ("bob", "pref-lang"), ("alice", "pref-lang"), ("bob", "time_zone"), ] def test_unknown_ordering_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"ordering": "value", "page_size": 100}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -818,26 +824,26 @@ def test_unknown_ordering_is_refused(self): } def test_listing_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: self.client.get(self.url, {"page_size": 100}) assert write_queries(captured.captured_queries) == [] def test_full_view_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: self.client.get(self.url, {"page_size": 100, "view": "full"}) assert write_queries(captured.captured_queries) == [] def test_head_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: response = self.client.head(self.url) assert response.status_code == status.HTTP_200_OK assert write_queries(captured.captured_queries) == [] def test_an_unknown_response_preset_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url, {"view": "nonsense"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -861,18 +867,18 @@ def test_anonymous_caller_is_unauthenticated(self): response = self.client.get(self.url_for("alice", "pref-lang")) assert_error_envelope(response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn") - def test_non_admin_caller_is_forbidden(self): + def test_a_caller_without_the_key_is_forbidden(self): self.login(self.learner) response = self.client.get(self.url_for("alice", "pref-lang")) assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") - def test_owner_who_is_not_an_admin_is_forbidden(self): + def test_the_owner_without_the_key_is_forbidden(self): self.login(self.alice) response = self.client.get(self.url_for("alice", "pref-lang")) assert_error_envelope(response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz") - def test_admin_caller_receives_the_preference(self): - self.login(self.admin) + def test_a_caller_with_the_key_receives_the_preference(self): + self.send_api_key() response = self.client.get(self.url_for("alice", "pref-lang")) assert response.status_code == status.HTTP_200_OK assert set(response.data) == {"username", "key", "value", "url", "user"} @@ -882,12 +888,12 @@ def test_admin_caller_receives_the_preference(self): assert response.data["user"] is None def test_full_view_embeds_the_owning_user(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice", "pref-lang"), {"view": "full"}) assert response.data["user"]["username"] == "alice" def test_a_field_name_the_preference_does_not_carry_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice", "pref-lang"), {"fields": "preference_key"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -900,30 +906,30 @@ def test_a_field_name_the_preference_does_not_carry_is_refused(self): } def test_unknown_key_is_not_found(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice", "nope")) assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") def test_key_belonging_to_another_user_is_not_found(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice", "time_zone")) assert_error_envelope(response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found") def test_an_unknown_response_preset_is_refused(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.url_for("alice", "pref-lang"), {"view": "nonsense"}) assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", ) def test_retrieval_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: self.client.get(self.url_for("alice", "pref-lang")) assert write_queries(captured.captured_queries) == [] def test_head_writes_nothing(self): - self.login(self.admin) + self.send_api_key() with CaptureQueriesContext(connection) as captured: response = self.client.head(self.url_for("alice", "pref-lang")) assert response.status_code == status.HTTP_200_OK @@ -944,6 +950,7 @@ def test_every_collection_that_selects_accounts_by_name_reads_one_list(self): would be answering a value its own addresses spell differently. """ self.login(self.admin) + self.send_api_key() selection = {"username": "alice,bob", "page_size": 100} pages = { name: self.client.get(reverse(f"user_v2:{name}"), selection) @@ -1049,7 +1056,7 @@ def test_the_directory_page_is_capped(self): User(username=f"extra-{index:03d}", email=f"extra-{index:03d}@example.com") for index in range(self.MAX_PAGE_SIZE) ) - self.login(self.admin) + self.send_api_key() response = self.client.get(reverse("user_v2:user_list"), {"page_size": 1000}) assert response.status_code == status.HTTP_200_OK assert response.data["count"] == self.MAX_PAGE_SIZE + 4 @@ -1062,7 +1069,7 @@ def test_the_stored_preference_page_is_capped(self): UserPreference(user=self.alice, key=f"extra-{index:03d}", value="x") for index in range(self.MAX_PAGE_SIZE) ) - self.login(self.admin) + self.send_api_key() response = self.client.get(reverse("user_v2:user_preference_list"), {"page_size": 1000}) assert response.status_code == status.HTTP_200_OK assert response.data["count"] == self.MAX_PAGE_SIZE + 2 @@ -1114,7 +1121,7 @@ def test_an_accept_header_this_api_cannot_answer_is_named(self): assert response["Content-Type"] == "application/json" def test_a_refused_method_is_named_on_the_gated_collections(self): - self.login(self.admin) + self.send_api_key() for url_name in ("user_v2:user_list", "user_v2:user_preference_list"): response = self.client.delete(reverse(url_name)) envelope = assert_error_envelope( @@ -1125,7 +1132,7 @@ def test_a_refused_method_is_named_on_the_gated_collections(self): assert envelope["detail"] == 'Method "DELETE" not allowed.' def test_a_refused_method_is_named_on_the_gated_members(self): - self.login(self.admin) + self.send_api_key() response = self.client.put(reverse("user_v2:user_detail", args=[self.alice.username])) envelope = assert_error_envelope( response, @@ -1174,17 +1181,17 @@ def assert_each_is_answered(self, address, parameter_sets): assert response.status_code == status.HTTP_200_OK, response.content def test_the_directory_refuses_a_parameter_it_does_not_read(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.user_list, {"lms_user_id": self.alice.id, "page_size": 100}) self.assert_refused(response, "lms_user_id", USER_QUERY_PARAMS) def test_a_mistyped_filter_refuses_the_page_instead_of_returning_every_row(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.user_list, {"usernme": "alice", "page_size": 100}) self.assert_refused(response, "usernme", USER_QUERY_PARAMS) def test_every_unrecognised_parameter_is_named_at_once(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.user_list, {"sort": "username", "limit": "10"}) envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", @@ -1192,17 +1199,17 @@ def test_every_unrecognised_parameter_is_named_at_once(self): assert sorted(envelope["errors"]) == ["limit", "sort"] def test_a_directory_entry_refuses_a_parameter_it_does_not_read(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.user_detail, {"expand": "profile"}) self.assert_refused(response, "expand", USER_QUERY_PARAMS) def test_the_preference_list_refuses_a_parameter_it_does_not_read(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.preference_list, {"value": "en", "page_size": 100}) self.assert_refused(response, "value", PREFERENCE_QUERY_PARAMS) def test_a_stored_preference_refuses_a_parameter_it_does_not_read(self): - self.login(self.admin) + self.send_api_key() response = self.client.get(self.preference_detail, {"value": "en"}) self.assert_refused(response, "value", PREFERENCE_QUERY_PARAMS) @@ -1221,7 +1228,7 @@ def test_an_unknown_parameter_does_not_answer_an_anonymous_caller(self): response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", ) - def test_an_unknown_parameter_does_not_answer_a_non_admin_caller(self): + def test_an_unknown_parameter_does_not_answer_a_caller_without_the_key(self): self.login(self.learner) response = self.client.get(self.preference_list, {"lms_user_id": self.alice.id}) assert_error_envelope( @@ -1229,7 +1236,7 @@ def test_an_unknown_parameter_does_not_answer_a_non_admin_caller(self): ) def test_the_directory_answers_every_parameter_it_reads(self): - self.login(self.admin) + self.send_api_key() self.assert_each_is_answered(self.user_list, [ {"page": 1}, {"page_size": 2}, @@ -1245,13 +1252,13 @@ def test_the_directory_answers_every_parameter_it_reads(self): ]) def test_a_directory_entry_answers_every_parameter_it_reads(self): - self.login(self.admin) + self.send_api_key() self.assert_each_is_answered(self.user_detail, [ {"view": "minimal"}, {"fields": "username"}, {"format": "json"}, {"ordering": "username"}, ]) def test_the_preference_list_answers_every_parameter_it_reads(self): - self.login(self.admin) + self.send_api_key() self.assert_each_is_answered(self.preference_list, [ {"page": 1}, {"page_size": 2}, @@ -1264,7 +1271,7 @@ def test_the_preference_list_answers_every_parameter_it_reads(self): ]) def test_a_stored_preference_answers_every_parameter_it_reads(self): - self.login(self.admin) + self.send_api_key() self.assert_each_is_answered(self.preference_detail, [ {"view": "full"}, {"fields": "key"}, {"format": "json"}, ]) @@ -1276,14 +1283,20 @@ def test_the_time_zone_list_answers_every_parameter_it_reads(self): def test_a_page_of_the_directory_is_still_narrowed_by_the_filters_it_takes(self): """The refusal guards the parameters, not the filtering they ask for.""" - self.login(self.admin) + self.send_api_key() response = self.client.get(self.user_list, {"username": "alice", "page_size": 100}) assert self.usernames_in(response) == ["alice"] @skip_unless_lms class TokenCallerTests(UserApiV2TestCase): - """The staff-gated endpoints answer a bearer of a staff token and refuse everyone else.""" + """ + The directory addresses answer a request carrying the site's API key and refuse every other. + + The key is what admits a caller here, whoever sends it: a token or a + session identifies the account a request comes from, and no account, + staff included, reads the directory without the key. + """ def setUp(self): super().setUp() @@ -1300,43 +1313,56 @@ def token_headers(self, user): """Return the request headers that carry a token identifying the given user.""" return {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(user)}"} - def test_a_staff_token_reaches_the_directory(self): - response = self.client.get( - self.addresses["user_list"], {"page_size": 100}, **self.token_headers(self.admin), - ) + def test_the_key_alone_reaches_the_directory(self): + response = self.client.get(self.addresses["user_list"], {"page_size": 100}, HTTP_X_EDX_API_KEY=API_KEY) assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] assert response.data["count"] == 4 - def test_a_staff_token_reaches_every_staff_gated_address(self): - headers = self.token_headers(self.admin) - detail = self.client.get(self.addresses["user_detail"], **headers) + def test_the_key_alone_reaches_every_directory_address(self): + self.send_api_key() + detail = self.client.get(self.addresses["user_detail"]) assert detail.status_code == status.HTTP_200_OK assert detail.data["username"] == "alice" - preferences = self.client.get( - self.addresses["preference_list"], {"username": "alice"}, **headers, - ) + preferences = self.client.get(self.addresses["preference_list"], {"username": "alice"}) assert preferences.status_code == status.HTTP_200_OK assert [(row["username"], row["key"]) for row in preferences.data["results"]] == [ ("alice", "pref-lang"), ] - preference = self.client.get(self.addresses["preference_detail"], **headers) + preference = self.client.get(self.addresses["preference_detail"]) assert preference.status_code == status.HTTP_200_OK assert preference.data["value"] == "en" - def test_the_token_and_not_a_session_identifies_the_caller(self): - token = create_jwt_for_user(self.admin) + def test_the_key_admits_whichever_account_sends_it(self): response = self.client.get( - self.addresses["user_list"], {"username": "alice"}, HTTP_AUTHORIZATION=f"JWT {token}", + self.addresses["user_list"], {"username": "alice"}, + HTTP_X_EDX_API_KEY=API_KEY, **self.token_headers(self.learner), ) assert response.status_code == status.HTTP_200_OK - assert response.wsgi_request.user == self.admin - assert response.wsgi_request.auth == token - assert "sessionid" not in response.wsgi_request.COOKIES + assert response.wsgi_request.user == self.learner + assert self.usernames_in(response) == ["alice"] + + def test_a_staff_token_without_the_key_is_forbidden_on_every_directory_address(self): + headers = self.token_headers(self.admin) + for name, address in self.addresses.items(): + with self.subTest(address=name): + assert_error_envelope( + self.client.get(address, **headers), + expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) + + def test_a_staff_session_without_the_key_is_forbidden_on_every_directory_address(self): + self.login(self.admin) + for name, address in self.addresses.items(): + with self.subTest(address=name): + assert_error_envelope( + self.client.get(address), + expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) - def test_a_learners_token_is_forbidden_on_every_staff_gated_address(self): + def test_a_learners_token_is_forbidden_on_every_directory_address(self): headers = self.token_headers(self.learner) for name, address in self.addresses.items(): with self.subTest(address=name): @@ -1345,7 +1371,7 @@ def test_a_learners_token_is_forbidden_on_every_staff_gated_address(self): response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", ) - def test_the_owner_of_the_record_is_still_not_staff(self): + def test_the_owner_of_the_record_is_still_refused_without_the_key(self): response = self.client.get( self.addresses["preference_detail"], **self.token_headers(self.alice), ) @@ -1353,9 +1379,24 @@ def test_the_owner_of_the_record_is_still_not_staff(self): response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", ) + def test_a_key_other_than_the_sites_is_unauthenticated(self): + for name, address in self.addresses.items(): + with self.subTest(address=name): + assert_error_envelope( + self.client.get(address, HTTP_X_EDX_API_KEY=f"{API_KEY}-other"), + expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + + @override_settings(EDX_API_KEY=None) + def test_no_key_admits_a_caller_on_a_site_that_configures_none(self): + assert_error_envelope( + self.client.get(self.addresses["user_list"], HTTP_X_EDX_API_KEY="None"), + expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", + ) + def test_a_token_that_does_not_decode_is_unauthenticated(self): response = self.client.get( - self.addresses["user_list"], HTTP_AUTHORIZATION="JWT not.a.token", + self.addresses["user_list"], HTTP_AUTHORIZATION="JWT not.a.token", HTTP_X_EDX_API_KEY=API_KEY, ) assert_error_envelope( response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", @@ -1372,7 +1413,7 @@ def setUp(self): joined = datetime(2024, 3, 1, tzinfo=UTC) for username in ("zoe-shared", "mia-shared", "ada-shared"): UserFactory.create(username=username, date_joined=joined) - self.login(self.admin) + self.send_api_key() def test_users_sharing_a_join_date_are_ordered_by_username(self): response = self.client.get(self.url, {"ordering": "date_joined", "page_size": 100}) @@ -1399,16 +1440,20 @@ def test_paging_through_a_shared_join_date_lists_each_user_once(self): @skip_unless_lms class DeactivatedStaffCallerTests(UserApiV2TestCase): """ - A staff account whose user record has been deactivated is refused by both halves of - the default authentication pair: the session half stops accepting it, and the active - account these views require refuses a token issued before the account was deactivated. + A staff account is refused here without the key whether or not it is still active. + + Deactivating the account changes only which half of the default + authentication pair refuses it: the session half stops accepting it, while + a token issued before the account was deactivated is still read and then + refused for the missing key. The key admits the request whatever state the + account sending it is in. """ def setUp(self): super().setUp() self.url = reverse("user_v2:user_list") self.staff = AdminFactory.create(username="deactivated-admin", password=PASSWORD) - self.staff_gated = { + self.directory = { "user_list": self.url, "user_detail": reverse("user_v2:user_detail", kwargs={"username": "alice"}), "preference_list": reverse("user_v2:user_preference_list"), @@ -1422,38 +1467,43 @@ def deactivate(self, user): user.is_active = False user.save() - def test_a_session_held_by_a_deactivated_staff_account_is_refused(self): + def test_a_session_held_by_a_staff_account_is_refused_before_and_after_it_is_deactivated(self): self.login(self.staff) - assert self.client.get(self.url).status_code == status.HTTP_200_OK + assert_error_envelope( + self.client.get(self.url), expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) self.deactivate(self.staff) response = self.client.get(self.url) assert_error_envelope( response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", ) - def test_a_token_held_by_a_deactivated_staff_account_is_refused(self): + def test_a_token_held_by_a_staff_account_is_refused_before_and_after_it_is_deactivated(self): headers = {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(self.staff)}"} - assert self.client.get(self.url, **headers).status_code == status.HTTP_200_OK + assert_error_envelope( + self.client.get(self.url, **headers), + expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", + ) self.deactivate(self.staff) response = self.client.get(self.url, {"page_size": 100}, **headers) assert_error_envelope( response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", ) - def test_a_deactivated_staff_token_is_refused_at_every_staff_gated_address(self): + def test_a_deactivated_staff_token_is_refused_at_every_directory_address(self): self.deactivate(self.staff) headers = {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(self.staff)}"} - for name, address in self.staff_gated.items(): + for name, address in self.directory.items(): with self.subTest(address=name): response = self.client.get(address, **headers) assert_error_envelope( response, expected_status=status.HTTP_403_FORBIDDEN, expected_type_slug="authz", ) - def test_a_deactivated_staff_session_is_refused_at_every_staff_gated_address(self): + def test_a_deactivated_staff_session_is_refused_at_every_directory_address(self): self.login(self.staff) self.deactivate(self.staff) - for name, address in self.staff_gated.items(): + for name, address in self.directory.items(): with self.subTest(address=name): response = self.client.get(address) assert_error_envelope( @@ -1469,9 +1519,11 @@ def test_the_directory_does_not_list_the_account_that_was_refused(self): assert response.status_code == status.HTTP_403_FORBIDDEN assert "results" not in response.data - def test_an_active_staff_token_still_reaches_the_directory(self): + def test_the_key_admits_a_deactivated_staff_account_as_it_admits_anyone(self): + self.deactivate(self.staff) response = self.client.get( - self.url, {"page_size": 100}, HTTP_AUTHORIZATION=f"JWT {create_jwt_for_user(self.staff)}", + self.url, {"page_size": 100}, + HTTP_AUTHORIZATION=f"JWT {create_jwt_for_user(self.staff)}", HTTP_X_EDX_API_KEY=API_KEY, ) assert response.status_code == status.HTTP_200_OK assert "deactivated-admin" in self.usernames_in(response) @@ -1518,8 +1570,8 @@ class QuerysetScopingSeamTests(UserApiV2TestCase): Each of these collections declares a policy that decides which rows a caller may see, and the rows it leaves out are absent from the answer - rather than refused. The policy that ships keeps every row, because only - platform administrators reach these collections at all, so these tests + rather than refused. The policy that ships keeps every row, because every + caller holding the site's API key may read all of them, so these tests put a narrowing policy in its place and read the answer: a collection that stopped consulting its policy would hand back the rows the policy left out, and a collection that no longer declared one would narrow @@ -1533,6 +1585,7 @@ def scoped(self, view_class, hidden_username): def test_user_list_leaves_out_the_rows_its_policy_excludes(self): self.login(self.admin) + self.send_api_key() patched, policy = self.scoped(UserViewSet, "alice") with patched: response = self.client.get(reverse("user_v2:user_list")) @@ -1541,7 +1594,7 @@ def test_user_list_leaves_out_the_rows_its_policy_excludes(self): assert policy.calls == [(User, self.admin)] def test_user_detail_of_an_excluded_row_is_not_found(self): - self.login(self.admin) + self.send_api_key() patched, _ = self.scoped(UserViewSet, "alice") with patched: response = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "alice"})) @@ -1550,7 +1603,7 @@ def test_user_detail_of_an_excluded_row_is_not_found(self): ) def test_user_detail_of_an_included_row_is_returned(self): - self.login(self.admin) + self.send_api_key() patched, _ = self.scoped(UserViewSet, "alice") with patched: response = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "bob"})) @@ -1559,6 +1612,7 @@ def test_user_detail_of_an_included_row_is_returned(self): def test_preference_list_leaves_out_the_rows_its_policy_excludes(self): self.login(self.admin) + self.send_api_key() patched, policy = self.scoped(UserPreferenceViewSet, "alice") with patched: response = self.client.get(reverse("user_v2:user_preference_list")) @@ -1567,7 +1621,7 @@ def test_preference_list_leaves_out_the_rows_its_policy_excludes(self): assert policy.calls == [(UserPreference, self.admin)] def test_preference_detail_of_an_excluded_row_is_not_found(self): - self.login(self.admin) + self.send_api_key() patched, _ = self.scoped(UserPreferenceViewSet, "alice") with patched: response = self.client.get( @@ -1578,7 +1632,7 @@ def test_preference_detail_of_an_excluded_row_is_not_found(self): ) def test_preference_detail_of_an_included_row_is_returned(self): - self.login(self.admin) + self.send_api_key() patched, _ = self.scoped(UserPreferenceViewSet, "alice") with patched: response = self.client.get( @@ -1700,7 +1754,7 @@ def test_options_answers_with_the_description_the_view_carries(self): This is what makes the text above published rather than internal: the framework answers an OPTIONS request with it verbatim. """ - self.login(self.admin) + self.send_api_key() answer = self.client.options(reverse("user_v2:user_list")) assert answer.status_code == status.HTTP_200_OK assert answer.json()["description"] == UserViewSet().get_view_description() @@ -1727,7 +1781,7 @@ def setUp(self): self.list_url = reverse("user_v2:user_list") self.member_url = reverse("user_v2:user_detail", kwargs={"username": "alice"}) self.preference_list_url = reverse("user_v2:user_preference_list") - self.login(self.admin) + self.send_api_key() def test_a_name_written_with_a_dot_is_refused_on_the_directory_list(self): response = self.client.get(f"{self.list_url}?fields=username.first") @@ -1803,7 +1857,7 @@ def test_an_accept_header_naming_nothing_the_address_answers_in_is_refused(self) def test_the_refusal_comes_back_in_the_body_this_version_answers_with(self): """The refusal is readable even though the caller asked for a representation it is not in.""" - self.login(self.admin) + self.send_api_key() response = self.client.get(reverse("user_v2:user_list"), HTTP_ACCEPT="text/csv") assert_error_envelope( response, expected_status=status.HTTP_406_NOT_ACCEPTABLE, expected_type_slug="not-acceptable", @@ -1829,7 +1883,7 @@ def test_an_address_that_answers_with_no_body_refuses_it_too(self): def test_an_accept_header_the_address_can_satisfy_is_answered(self): """The refusal is about what was asked for, not about asking at all.""" - self.login(self.admin) + self.send_api_key() response = self.client.get(reverse("user_v2:user_list"), HTTP_ACCEPT="application/json") assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] @@ -1902,7 +1956,7 @@ def directory_of(self, rows): def test_the_preferences_inside_a_directory_entry_come_through_their_own_policy(self): policy = HiddenKeyPolicy("pref-lang") - self.login(self.admin) + self.send_api_key() with patch.object(UserViewSet, "embedded_preference_policy", policy, create=True): response = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "alice"})) assert response.status_code == status.HTTP_200_OK @@ -1911,7 +1965,7 @@ def test_the_preferences_inside_a_directory_entry_come_through_their_own_policy( def test_a_preference_the_embedded_policy_keeps_is_still_carried(self): policy = HiddenKeyPolicy("pref-lang") - self.login(self.admin) + self.send_api_key() with patch.object(UserViewSet, "embedded_preference_policy", policy, create=True): response = self.client.get(reverse("user_v2:user_detail", kwargs={"username": "bob"})) assert response.status_code == status.HTTP_200_OK @@ -1920,7 +1974,7 @@ def test_a_preference_the_embedded_policy_keeps_is_still_carried(self): def test_the_preferences_inside_a_page_of_entries_come_through_their_own_policy(self): self.directory_of(5) policy = HiddenKeyPolicy("pref-lang") - self.login(self.admin) + self.send_api_key() with patch.object(UserViewSet, "embedded_preference_policy", policy, create=True): response = self.client.get(reverse("user_v2:user_list"), {"page_size": 100}) assert response.status_code == status.HTTP_200_OK @@ -1935,7 +1989,7 @@ def test_narrowing_the_embedded_preferences_costs_no_query_per_row(self): One row would hide a per-row query that cancels a prefetch, so this is measured at five rows and again at twenty-five. """ - self.login(self.admin) + self.send_api_key() measured = {} for rows in (5, 25): User.objects.filter(username__startswith="row-").delete() @@ -1955,7 +2009,7 @@ def test_narrowing_the_embedded_preferences_costs_no_query_per_row(self): def test_the_preferences_inside_an_embedded_owner_come_through_their_own_policy(self): """A preference asked for whole carries its owner, whose own preferences are narrowed too.""" policy = HiddenKeyPolicy("pref-lang") - self.login(self.admin) + self.send_api_key() with patch.object(UserPreferenceViewSet, "embedded_preference_policy", policy, create=True): response = self.client.get( reverse("user_v2:user_preference_detail", kwargs={"username": "alice", "key": "pref-lang"}), @@ -1965,7 +2019,7 @@ def test_the_preferences_inside_an_embedded_owner_come_through_their_own_policy( assert response.data["user"]["preferences"] == {} def test_narrowing_an_embedded_owners_preferences_costs_no_query_per_row(self): - self.login(self.admin) + self.send_api_key() measured = {} for rows in (5, 25): User.objects.filter(username__startswith="row-").delete() @@ -2017,7 +2071,7 @@ def preferences_of(self, rows): def test_an_owner_the_embedded_policy_leaves_out_is_not_carried_inside_a_page(self): policy = HiddenOwnerPolicy("alice") - self.login(self.admin) + self.send_api_key() with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): response = self.client.get( reverse("user_v2:user_preference_list"), {"view": "full", "page_size": 100}, @@ -2031,7 +2085,7 @@ def test_an_owner_the_embedded_policy_leaves_out_is_not_carried_inside_a_page(se def test_an_owner_the_embedded_policy_leaves_out_is_not_carried_inside_one_preference(self): policy = HiddenOwnerPolicy("alice") - self.login(self.admin) + self.send_api_key() with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): response = self.client.get( reverse("user_v2:user_preference_detail", kwargs={"username": "alice", "key": "pref-lang"}), @@ -2052,7 +2106,7 @@ def test_an_owner_the_embedded_policy_keeps_is_still_carried(self): consulted. It is here to show the answer is not narrowed too far. """ policy = HiddenOwnerPolicy("alice") - self.login(self.admin) + self.send_api_key() with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): response = self.client.get( reverse("user_v2:user_preference_detail", kwargs={"username": "bob", "key": "time_zone"}), @@ -2069,7 +2123,7 @@ def test_the_owners_of_a_page_are_resolved_once_however_many_rows_it_carries(sel One row would hide a per-row lookup, so this is measured at five rows and again at twenty-five, and the policy is asked once either way. """ - self.login(self.admin) + self.send_api_key() measured = {} address = reverse("user_v2:user_preference_list") for rows in (5, 25): @@ -2090,7 +2144,7 @@ def test_the_owners_of_a_page_are_resolved_once_however_many_rows_it_carries(sel def test_no_owner_is_resolved_for_a_page_that_carries_none(self): """A page that does not carry its owners does not ask which owners it could carry.""" - self.login(self.admin) + self.send_api_key() policy = HiddenOwnerPolicy("alice") with patch.object(UserPreferenceViewSet, "embedded_user_policy", policy, create=True): response = self.client.get(reverse("user_v2:user_preference_list"), {"page_size": 100}) @@ -2113,7 +2167,7 @@ def scope(self, queryset, subject): # pylint: disable=unused-argument """Return the one owner this policy keeps, built without the given collection.""" return User.objects.filter(username="bob") - self.login(self.admin) + self.send_api_key() with patch.object(UserPreferenceViewSet, "embedded_user_policy", OwnCollectionPolicy(), create=True): response = self.client.get( reverse("user_v2:user_preference_list"), {"view": "full", "page_size": 100}, diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index bb49f8502749..bbf73d6b21e4 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -43,6 +43,7 @@ from openedx.core.djangoapps.user_api.models import UserPreference from openedx.core.djangoapps.user_api.preferences.api import get_country_time_zones from openedx.core.lib.api.parsers import MergePatchParser +from openedx.core.lib.api.permissions import ApiKeyHeaderPermission from .errors import AmbiguousAccountName, CatalogedRequestErrorsMixin, ErrorExtensionsMixin, RetiredAccount from .filters import StrictOrderingFilter, UserFilterSet, UserPreferenceFilterSet @@ -259,6 +260,9 @@ def _ordering_param(sort_fields, default): _PREFERENCE_ORDERING_PARAM = _ordering_param(PREFERENCE_SORT_FIELDS, PREFERENCE_DEFAULT_SORT) _RESP_FORBIDDEN = OpenApiResponse(ErrorResponse, description="The requester may not use this endpoint.") + +#: How a caller is admitted to the user directory and to the stored preferences. +_API_KEY_ADMISSION = "Answered only to a request carrying the site's API key in the `X-Edx-Api-Key` header." #: Published by every operation of this version. Which representations an #: answer can be given in is settled as the request enters, before the address #: it names is read or written, so an ``Accept`` header naming none of them is @@ -630,7 +634,8 @@ def shape_page(self, response, request): description=( "Returns a page of the user directory. Supply `preference_key` to keep only the " "users who have stored a preference under that key, or `forum_role` together with " - "`course_key` to keep only the holders of a course forum role." + "`course_key` to keep only the holders of a course forum role. " + f"{_API_KEY_ADMISSION}" ), parameters=[_MINIMAL_VIEW_PARAM, _FIELDS_PARAM, _USER_ORDERING_PARAM], responses={ @@ -644,7 +649,7 @@ def shape_page(self, response, request): ), retrieve=extend_schema( summary="Get one user", - description="Returns the directory entry of the user with this username.", + description=f"Returns the directory entry of the user with this username. {_API_KEY_ADMISSION}", parameters=[_USER_PATH_PARAM, _MINIMAL_VIEW_PARAM, _FIELDS_PARAM], responses={ 200: _USER_SHAPES, @@ -671,8 +676,9 @@ class UserViewSet( Directory entries of the platform's users, each addressed by username. An entry carries the identifying properties of one account together with - the preferences stored against it. Only a platform administrator whose own - account is still active may read this directory. + the preferences stored against it. It is read by server integrations, + which send the site's API key in the X-Edx-Api-Key header, and is + refused to every request that does not carry that key. """ # Who may read the directory is settled in three layers, each of which can @@ -681,12 +687,12 @@ class UserViewSet( # such a caller may see, and the filter set narrows those rows by the # parameters the request carries. - permission_classes = (permissions.IsAuthenticated, IsActiveUser, permissions.IsAdminUser) + permission_classes = (ApiKeyHeaderPermission,) serializer_class = UserDirectorySerializer pagination_class = UserApiPagination queryset = User.objects.all().select_related("profile") - # Platform administrators may read every entry, so the policy keeps the - # queryset whole; a narrower policy can replace it without touching the + # A caller holding the API key may read every entry, so the policy keeps + # the queryset whole; a narrower policy can replace it without touching the # filtering below. scoping_policy = FullScopePolicy() #: The preferences carried inside an entry are rows of the stored @@ -739,7 +745,8 @@ def retrieve(self, request, *args, **kwargs): summary="List stored preferences", description=( "Returns a page of stored user preferences. Supply `key` to keep only the " - "preferences stored under that name, or `username` to keep only one user's." + "preferences stored under that name, or `username` to keep only one user's. " + f"{_API_KEY_ADMISSION}" ), parameters=[_PREFERENCE_VIEW_PARAM, _FIELDS_PARAM, _PREFERENCE_ORDERING_PARAM], responses={ @@ -756,7 +763,8 @@ def retrieve(self, request, *args, **kwargs): description=( "Returns the preference stored under this key for this user. A preference is " "identified by the pair, which the address carries as the username, a comma and " - "the key, for example `alice,time_zone`." + "the key, for example `alice,time_zone`. " + f"{_API_KEY_ADMISSION}" ), parameters=[ _PREFERENCE_USERNAME_PATH_PARAM, @@ -789,8 +797,8 @@ class UserPreferenceViewSet( A preference is identified by the two together, so a member address carries the owner's username, a comma and the name the preference is - stored under, as in alice,time_zone. Only a platform administrator whose - own account is still active may read these. + stored under, as in alice,time_zone. Like the user directory, these are + read only by a request carrying the site's API key. """ # The pair identifies a row, so the member address is built from it rather @@ -798,7 +806,7 @@ class UserPreferenceViewSet( # the collection rather than generated. Who may read these rows is settled # in the same three layers as the user directory. - permission_classes = (permissions.IsAuthenticated, IsActiveUser, permissions.IsAdminUser) + permission_classes = (ApiKeyHeaderPermission,) serializer_class = UserPreferenceRecordSerializer pagination_class = UserApiPagination queryset = ( From 3ba2cd42fb3121432d0a7563785b699cfc7e6815 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:10:47 +0500 Subject: [PATCH 42/61] fix: read an unconfirmed account's session at the email search, as v1 does POST /api/user/v1/accounts/search_emails reads a session with the class that keeps an account whose email address is unconfirmed. Its replacement, POST /api/user/v2/email_searches/, took the platform default, which drops such a session, so the same unconfirmed account was refused 401 by session and 403 by token. The search now declares the same token and session classes the account collection does. An unconfirmed account is refused 403 whichever way it signs in, with one body; an active staff account is answered as before. The refusal itself is unchanged: v1 answers an unconfirmed staff account 200 on both transports, and this address refuses it. Tests: an unconfirmed staff account and an unconfirmed learner each get the same 403 by session and by token; the unconfirmed session still reads its own account. Co-Authored-By: Claude Opus 5.5 --- .../user_api/v2/tests/test_account_views.py | 47 +++++++++++++++---- openedx/core/djangoapps/user_api/v2/views.py | 7 +++ 2 files changed, 46 insertions(+), 8 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 1d012faddd97..1d2d6265edf6 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -1816,27 +1816,58 @@ def test_a_token_held_by_a_deactivated_staff_account_is_refused(self): expected_type_slug="authz", ) - def test_a_session_whose_owner_has_not_confirmed_their_address_identifies_nobody_here(self): + def test_a_session_whose_owner_has_not_confirmed_their_address_is_refused_as_a_token_is(self): """ - Searching other people's accounts is not done from the pages an unconfirmed account reaches. + Searching other people's accounts is not done from an account that has not been confirmed. - The account addresses accept such a session because the site's own - settings pages are reached with one; this address keeps the platform - default, under which it identifies nobody, and the same session still - reads the account it belongs to. + The session is read, as it is at the account addresses, so the refusal + is the one a token of the same account gets, and the same session + still reads the account it belongs to. """ self.staff.is_active = False self.staff.save() self.login(self.staff) assert_error_envelope( self.search(["owner-caller@example.com"]), - expected_status=status.HTTP_401_UNAUTHORIZED, - expected_type_slug="authn", + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", ) own = self.client.get(self.own_url) assert own.status_code == status.HTTP_200_OK assert own.data["username"] == "staff-caller" + def test_an_unconfirmed_staff_account_gets_one_refusal_whichever_way_it_signs_in(self): + self.staff.is_active = False + self.staff.save() + by_token = assert_error_envelope( + self.search(["owner-caller@example.com"], **self.token_headers(self.staff)), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + self.login(self.staff) + by_session = assert_error_envelope( + self.search(["owner-caller@example.com"]), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert by_session["detail"] == by_token["detail"] + + def test_an_unconfirmed_learner_gets_one_refusal_whichever_way_it_signs_in(self): + self.owner.is_active = False + self.owner.save() + by_token = assert_error_envelope( + self.search(["other-caller@example.com"], **self.token_headers(self.owner)), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + self.login(self.owner) + by_session = assert_error_envelope( + self.search(["other-caller@example.com"]), + expected_status=status.HTTP_403_FORBIDDEN, + expected_type_slug="authz", + ) + assert by_session["detail"] == by_token["detail"] + def test_the_search_is_not_read_with_a_get(self): self.login(self.staff) response = self.client.get(self.url) diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index bbf73d6b21e4..b872acb818e9 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -1543,6 +1543,13 @@ class EmailSearchViewSet( # collection in an address is the name of an account, and a user may # register any name. + # The session of an account that has not confirmed its email address is + # read rather than dropped, so the active-account check refuses it with the + # answer a token of that account gets instead of the request being treated + # as anonymous. A token is read by the library class the platform's own + # pair is built on, named because a view declaring its own classes is not + # one that pair serves. + authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser) permission_classes = ( permissions.IsAuthenticated, IsActiveUser, From decbf90bb66fb38d7f1d32f21509cab885e97542 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:13:47 +0500 Subject: [PATCH 43/61] fix: refuse an image whose metadata cannot be written back with a 400 POST /api/user/v2/accounts/{username}/profile_image/ read the image's metadata once before storing it, and refused metadata only when that read raised a struct error. Metadata naming a value type that does not exist, or a pointer claiming two offsets, makes the read itself raise ValueError or TypeError, and a resolution held as a short with no values reads but makes writing it back raise IndexError, which each stored size does. All three answered 500, as they do at /api/user/v1/accounts/{username}/image. The metadata is now read and written back before anything is stored, the same two steps the stored sizes take, and those three errors are refused with the same 400 and message as any other image that cannot be read. Nothing is stored for such an upload. An image whose metadata reads and writes back is stored as before. Tests: one per error, each refused 400 with nothing stored; an image carrying well-formed metadata is stored. Co-Authored-By: Claude Opus 5.5 --- .../profile_images/v2/tests/test_views.py | 56 +++++++++++++++++++ .../djangoapps/profile_images/v2/views.py | 16 ++++-- 2 files changed, 68 insertions(+), 4 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py index 208d7c867ae8..2ad2cbee1be3 100644 --- a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py +++ b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py @@ -139,6 +139,20 @@ def image_with_unreadable_metadata(self): """Return a JPEG carrying a metadata block that is not the metadata it announces.""" return self.noisy_image(exif=b"Exif\x00\x00" + b"\xff" * 64) + def image_with_metadata_entries(self, *entries): + """ + Return a JPEG whose metadata holds one directory of the given raw entries. + + Each entry is a tag, a value type, a count and the four bytes that + carry the value, written as they stand, so an entry can say something + about itself that its value does not bear out. + """ + directory = struct.pack(" Date: Wed, 4 Nov 2026 17:58:57 +0500 Subject: [PATCH 44/61] fix: publish the superseded account requests without the replacement's bounds The search, name change and account change at the version 1 addresses published the bodies of their version 2 replacements, and with them bounds and types those handlers never hold a request to: at most 100 addresses in a search, a name of at most 255 characters, and text alone for every account property. A client generated from /lms-api/ or /api-docs/ enforces what it reads, so it refused on its own side a 101-address search, a 256-character name or a number for `bio` that the version 1 handlers answer with 200, 201 and 200. Each of the three version 1 requests is now described by the members it reads and nothing more: `emails` is a list of any length, `name` is text of any length, and the account change names each property it changes with no type. They name no component, so a later change to a version 2 serializer no longer rewrites what a version 1 address publishes. The version 2 operations keep `EmailSearch`, `NameChange` and `PatchedAccountUpdate` and their bounds, and the media types and the required mark of every version 1 request are unchanged. The tests read both documents, check each version 1 request body against the requests the handlers answer with success, drive the handlers, and pin the bounds on the version 2 components. Co-Authored-By: Claude Opus 5.5 --- lms/lib/tests/test_spectacular.py | 137 +++++++++++++++++++++ openedx/core/djangoapps/user_api/schema.py | 56 +++++++-- 2 files changed, 183 insertions(+), 10 deletions(-) diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index 2e42f59b273b..15a8274cecfd 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -10,6 +10,7 @@ from types import SimpleNamespace from unittest import mock +import jsonschema from django.test import Client, SimpleTestCase, TestCase from django.urls import path from drf_spectacular.generators import SchemaGenerator @@ -412,6 +413,142 @@ def test_no_superseded_operation_answers_with_a_body_it_does_not_describe(self): assert undescribed == [] +#: A request each superseded address answers with success that the body the +#: replacing address reads would refuse: more addresses than a search there +#: takes, a longer name than a change there takes, and a number where a change +#: there takes only text. +ACCEPTED_ONLY_BY_THE_SUPERSEDED_ADDRESS = { + ("/api/user/v1/accounts/search_emails", "post"): { + "emails": [f"crowd-{index:03d}@example.com" for index in range(101)], + }, + ("/api/user/v1/accounts/name_change/", "post"): {"name": "N" * 256}, + ("/api/user/v1/accounts/{username}", "patch"): {"bio": 5}, +} + +#: What a published body may say only where the handler reading it holds a +#: request to it. +BOUNDING_KEYWORDS = {"$ref", "format", "maxItems", "maxLength", "minItems", "minLength", "pattern"} + + +def _keywords(node): + """Return every key used anywhere inside a JSON schema.""" + if isinstance(node, dict): + return set(node).union(*(_keywords(value) for value in node.values())) + if isinstance(node, list): + return set().union(*(_keywords(value) for value in node)) + return set() + + +class SupersededRequestBodyTest(TestCase): + """ + A superseded address publishes no bound or type its handler does not hold a request to. + + Its replacement reads the same members with bounds of its own. A client + generated from either document enforces what the body it reads publishes, + so a bound borrowed from the replacement would have that client refuse, + on its own side, a request the superseded handler answers with success. + """ + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.documents = {"published": SchemaGenerator().get_schema(request=None, public=True)} + with patched_settings(get_api_docs_settings()): + cls.documents["service-wide"] = SchemaGenerator().get_schema(request=None, public=True) + + def setUp(self): + super().setUp() + self.owner = UserFactory.create(username="bodyowner", password=TEST_PASSWORD) + self.staff = UserFactory.create(username="bodystaff", password=TEST_PASSWORD, is_staff=True) + + def _published_bodies(self, address, method): + """Yield each document's name, a media type and the body published for it at one operation.""" + for name, document in self.documents.items(): + for media_type, content in document["paths"][address][method]["requestBody"]["content"].items(): + yield name, media_type, content["schema"] + + def test_each_body_publishes_the_members_it_reads_and_nothing_that_bounds_them(self): + published = {} + for address, method in ACCEPTED_ONLY_BY_THE_SUPERSEDED_ADDRESS: + for name, media_type, body in self._published_bodies(address, method): + published[(name, address, media_type)] = body + for key, body in published.items(): + assert _keywords(body) & BOUNDING_KEYWORDS == set(), key + assert published[("published", "/api/user/v1/accounts/search_emails", "application/json")] == { + "type": "object", + "properties": {"emails": {"type": "array", "items": {}}}, + "required": ["emails"], + } + assert published[("service-wide", "/api/user/v1/accounts/name_change/", "multipart/form-data")] == { + "type": "object", + "properties": {"name": {"type": "string"}}, + "required": ["name"], + } + change = published[("published", "/api/user/v1/accounts/{username}", "application/merge-patch+json")] + assert {"bio", "email", "name", "social_links", "year_of_birth"} <= set(change["properties"]) + assert set(map(json.dumps, change["properties"].values())) == {"{}"} + + def test_each_request_the_handler_accepts_is_one_its_published_body_allows(self): + for (address, method), request in ACCEPTED_ONLY_BY_THE_SUPERSEDED_ADDRESS.items(): + for name, media_type, body in self._published_bodies(address, method): + with self.subTest(document=name, address=address, media_type=media_type): + jsonschema.Draft202012Validator(body).validate(request) + + def test_each_handler_answers_those_requests_with_success(self): + owner, staff = Client(), Client() + assert owner.login(username=self.owner.username, password=TEST_PASSWORD) + assert staff.login(username=self.staff.username, password=TEST_PASSWORD) + requests = ACCEPTED_ONLY_BY_THE_SUPERSEDED_ADDRESS + answered = { + "search": staff.post( + "/api/user/v1/accounts/search_emails", + requests[("/api/user/v1/accounts/search_emails", "post")], + content_type="application/json", + ).status_code, + "name change": owner.post( + "/api/user/v1/accounts/name_change/", + requests[("/api/user/v1/accounts/name_change/", "post")], + content_type="application/json", + ).status_code, + "account change": owner.patch( + f"/api/user/v1/accounts/{self.owner.username}", + requests[("/api/user/v1/accounts/{username}", "patch")], + content_type="application/merge-patch+json", + ).status_code, + } + assert answered == {"search": 200, "name change": 201, "account change": 200} + + def test_the_replacing_addresses_publish_the_bounds_they_hold_a_request_to(self): + for name, document in self.documents.items(): + components = document["components"]["schemas"] + with self.subTest(document=name): + assert components["EmailSearch"]["properties"]["emails"]["maxItems"] == 100 + assert components["NameChange"]["properties"]["name"]["maxLength"] == 255 + assert components["PatchedAccountUpdate"]["properties"]["bio"]["type"] == "string" + paths = document["paths"] + assert paths["/api/user/v2/email_searches/"]["post"]["requestBody"]["content"][ + "application/json" + ]["schema"] == {"$ref": "#/components/schemas/EmailSearch"} + assert paths["/api/user/v2/name_changes/"]["post"]["requestBody"]["content"][ + "application/json" + ]["schema"] == {"$ref": "#/components/schemas/NameChange"} + assert paths["/api/user/v2/accounts/{username}/"]["patch"]["requestBody"]["content"][ + "application/merge-patch+json" + ]["schema"] == {"$ref": "#/components/schemas/PatchedAccountUpdate"} + + def test_a_body_that_names_a_member_it_must_carry_is_published_as_required(self): + required = { + (name, address): document["paths"][address][method]["requestBody"].get("required", False) + for name, document in self.documents.items() + for address, method in ACCEPTED_ONLY_BY_THE_SUPERSEDED_ADDRESS + } + assert required == { + (name, address): address != "/api/user/v1/accounts/{username}" + for name in self.documents + for address, _method in ACCEPTED_ONLY_BY_THE_SUPERSEDED_ADDRESS + } + + #: Each address this document already published before its body was described, #: and the success code its handler really answers. That document carried a 200 #: with no body for both, which no handler answers; the code each is diff --git a/openedx/core/djangoapps/user_api/schema.py b/openedx/core/djangoapps/user_api/schema.py index 430bedf57955..0e6a40b5918a 100644 --- a/openedx/core/djangoapps/user_api/schema.py +++ b/openedx/core/djangoapps/user_api/schema.py @@ -6,6 +6,7 @@ from importlib import import_module from drf_spectacular.utils import OpenApiResponse +from rest_framework.parsers import FormParser, JSONParser, MultiPartParser # Addresses listed here are superseded by a conforming address this schema also # publishes. Each entry is spelled out rather than matched by prefix, so an @@ -87,12 +88,18 @@ def superseded_bodies(): The views serving those addresses name no serializer, so an address published beside the one that replaces it would carry nothing on either - side of the exchange. Each entry below names the shape the handler reads or - returns with the serializer describing that same shape at the replacing - address, which the parity tests of this area hold to the same values; a - request of ``None`` is an operation that reads no body. An address whose - view names a serializer of its own is absent from the table and keeps the - component it has always published. + side of the exchange. Each entry below names the shape the handler returns + with the serializer describing that same shape at the replacing address, + which the parity tests of this area hold to the same values; a request of + ``None`` is an operation that reads no body. An address whose view names a + serializer of its own is absent from the table and keeps the component it + has always published. + + A body a handler reads is described by the members it reads and nothing + more: those handlers take a list of any length, a name of any length and a + number where text is expected, so the bounds and types the replacing + serializers publish would have a generated client refuse requests these + addresses accept. A request is keyed by media type, because a shape named on its own is published under every type the view's parsers accept: where that is more @@ -115,18 +122,35 @@ def superseded_bodies(): replacing = import_module("openedx.core.djangoapps.user_api.v2.serializers") account = {200: replacing.AccountSerializer} + account_change = { + "type": "object", + "properties": {name: {} for name in replacing.AccountUpdateSerializer().fields}, + } + email_search = { + "type": "object", + "properties": {"emails": {"type": "array", "items": {}}}, + "required": ["emails"], + } + name_change = { + "type": "object", + "properties": {"name": {"type": "string"}}, + "required": ["name"], + } described = { ("/api/user/v1/accounts", "GET"): _SupersededBodies(None, {200: replacing.AccountSerializer(many=True)}), ("/api/user/v1/accounts/{username}", "GET"): _SupersededBodies(None, account), ("/api/user/v1/accounts/{username}", "PATCH"): _SupersededBodies( - {MergePatchParser.media_type: replacing.AccountUpdateSerializer}, account, + {MergePatchParser.media_type: account_change}, account, ), ("/api/user/v1/accounts/search_emails", "POST"): _SupersededBodies( - replacing.EmailSearchSerializer, {200: replacing.EmailSearchResultSerializer(many=True)}, + {JSONParser.media_type: email_search, MergePatchParser.media_type: email_search}, + {200: replacing.EmailSearchResultSerializer(many=True)}, ), ("/api/user/v1/accounts/{username}/deactivate/", "POST"): _SupersededBodies(None, account), ("/api/user/v1/accounts/name_change/", "POST"): _SupersededBodies( - replacing.NameChangeSerializer, + dict.fromkeys( + (JSONParser.media_type, FormParser.media_type, MultiPartParser.media_type), name_change, + ), {201: OpenApiResponse(description="The change was recorded and waits to be confirmed.")}, ), ("/api/user/v1/accounts/name_change/{username}/confirm/", "POST"): _SupersededBodies( @@ -191,10 +215,22 @@ def _get_request_body(self, direction="request"): shapes = self.get_request_serializer() if body.get("required") or not isinstance(shapes, dict): return body - if any(self._get_request_for_media_type(shape, direction)[1] for shape in shapes.values()): + if any(self._requires_a_body(shape, direction) for shape in shapes.values()): body["required"] = True return body + def _requires_a_body(self, shape, direction): + """ + Say whether a request cannot be sent without this form of the body. + + A shape written out in full is published as it stands, and the + generator calls none of those required; it is required when it names a + member the request must carry, the way a serializer's is. + """ + if isinstance(shape, dict): + return bool(shape.get("required")) + return self._get_request_for_media_type(shape, direction)[1] + def get_request_serializer(self): """Return the body this operation reads, named here for the addresses this one supersedes.""" bodies = self._superseded_bodies() From 9fd376da9c41d5674f105a98f127ef9d9991bb14 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:02:27 +0500 Subject: [PATCH 45/61] fix: read a name, a searched address and the account selectors as sent Four inputs had the spaces around them removed before they were used, where the version 1 addresses use them exactly as sent, and on two of them the outcome changed: a name change for " Jane" on a profile named "Jane" was refused as the name it already carries, and `?username=%20owner` returned the owner's account where version 1 found none. The name asked for in a name change, each address in an email search, and the `username` and `email` selectors of the account list are now read untrimmed. A name is stored with its spaces, as version 1 stores it, and a name of spaces alone is still refused as blank, as version 1 refuses it. A name or a searched address with spaces before it matches no account in either version. An `email` selector with spaces around it is not a well-formed address, so it is refused with the 400 any malformed address gets, rather than returning the account the trimmed address names. The tests send each padded input to both versions and compare what each returns and stores. Co-Authored-By: Claude Opus 5.5 --- .../djangoapps/user_api/v2/serializers.py | 11 +++-- .../user_api/v2/tests/test_account_parity.py | 46 +++++++++++++++++++ .../user_api/v2/tests/test_account_views.py | 20 ++++---- .../v2/tests/test_name_change_views.py | 30 ++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 7 ++- 5 files changed, 95 insertions(+), 19 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/serializers.py b/openedx/core/djangoapps/user_api/v2/serializers.py index 97335013029f..50a6f2a17d82 100644 --- a/openedx/core/djangoapps/user_api/v2/serializers.py +++ b/openedx/core/djangoapps/user_api/v2/serializers.py @@ -452,6 +452,7 @@ class AccountQuerySerializer(serializers.Serializer): # pylint: disable=abstrac username = serializers.CharField( required=False, allow_blank=True, + trim_whitespace=False, help_text=( "Comma-separated usernames. A name no account holds is left out of the page rather than refused. " "Omit this and the other selectors to receive your own account." @@ -460,6 +461,7 @@ class AccountQuerySerializer(serializers.Serializer): # pylint: disable=abstrac email = serializers.EmailField( required=False, allow_blank=True, + trim_whitespace=False, help_text="Address of the one account to return. Only staff may select an account this way.", ) lms_user_id = serializers.IntegerField( @@ -636,7 +638,7 @@ class EmailSearchSerializer(serializers.Serializer): # pylint: disable=abstract """The addresses an account search is asked to resolve.""" emails = _TextListField( - child=serializers.CharField(allow_blank=True), + child=serializers.CharField(allow_blank=True, trim_whitespace=False), allow_empty=True, max_length=EMAIL_SEARCH_MAX_ADDRESSES, help_text=( @@ -664,15 +666,18 @@ class Meta: class NameChangeSerializer(serializers.Serializer): # pylint: disable=abstract-method - """A request to put a different full name on a user's profile.""" + """A request to put a different full name on a user's profile, stored as it is sent.""" name = serializers.CharField( max_length=NAME_MAX_LENGTH, + trim_whitespace=False, help_text="Full name to put on the profile once the request is confirmed.", ) def validate_name(self, name): - """Refuse a name carrying markup or a web address.""" + """Refuse a name of spaces alone, or one carrying markup or a web address.""" + if not name.strip(): + self.fields["name"].fail("blank") if contains_html(name): raise serializers.ValidationError("Name cannot contain the following characters: < >") if contains_url(name): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py index 54560629d99a..d4cbf4157348 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py @@ -481,6 +481,52 @@ def test_a_search_longer_than_a_page_is_refused_here_and_was_answered_before(sel "emails": ["Ensure this field has no more than 100 elements."], } + def test_a_name_with_spaces_before_it_selects_no_account_in_either_version(self): + """Both versions match a name exactly as it was sent.""" + self.login(self.staff) + for asked in (" refusal-owner", "refusal-other, refusal-owner"): + with self.subTest(username=asked): + earlier = self.client.get(EARLIER_LIST, {"username": asked}) + current = self.client.get(reverse("user_v2:account_list"), {"username": asked}) + assert current.status_code == status.HTTP_200_OK + selected = [row["username"] for row in json.loads(current.content)["results"]] + if "," in asked: + assert earlier.status_code == status.HTTP_200_OK + assert [row["username"] for row in json.loads(earlier.content)] == ["refusal-other"] + assert selected == ["refusal-other"] + else: + assert earlier.status_code == status.HTTP_404_NOT_FOUND + assert selected == [] + + def test_an_address_with_spaces_before_it_selects_no_account_in_either_version(self): + """ + Both versions read the address exactly as it was sent. + + The earlier address looked it up and found nothing behind it; this + version refuses it as an address that is not well formed. + """ + self.login(self.staff) + asked = {"email": " refusal-owner@example.com"} + earlier = self.client.get(EARLIER_LIST, asked) + assert earlier.status_code == status.HTTP_404_NOT_FOUND + + current = self.client.get(reverse("user_v2:account_list"), asked) + envelope = assert_error_envelope( + current, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"email": ["Enter a valid email address."]} + + def test_a_searched_address_with_spaces_before_it_matches_no_account_in_either_version(self): + self.login(self.staff) + emails = {"emails": ["refusal-other@example.com", " refusal-owner@example.com"]} + earlier = self.client.post(EARLIER_SEARCH, emails, format="json") + assert earlier.status_code == status.HTTP_200_OK + assert [row["username"] for row in json.loads(earlier.content)] == ["refusal-other"] + + current = self.client.post(reverse("user_v2:email_search_list"), emails, format="json") + assert current.status_code == status.HTTP_200_OK + assert [row["username"] for row in json.loads(current.content)["results"]] == ["refusal-other"] + def test_the_address_of_a_retired_account_keeps_what_the_earlier_body_carried(self): self.login(self.staff) retired_email = self.other.email diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 1d2d6265edf6..1dbfef8d3b39 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -229,20 +229,16 @@ def test_a_property_the_list_does_not_sort_by_is_refused(self): } assert "results" not in envelope - def test_a_name_sent_with_spaces_around_it_names_the_same_account_throughout(self): - """ - The name is read the same way when the answer is shaped and when the page is cut. - - What a caller may select depends on whose accounts the page carries, - and spaces around the name they sent do not make their own account - somebody else's for that purpose. - """ - self.login(self.owner) - for asked in ("owner-caller", " owner-caller", "owner-caller "): + def test_a_name_sent_with_spaces_around_it_is_read_as_sent(self): + """A name is matched exactly as it was sent, so spaces around it name no account.""" + self.login(self.staff) + exact = self.client.get(self.list_url, {"username": "owner-caller"}) + assert self.usernames_in(exact) == ["owner-caller"] + for asked in (" owner-caller", "other-caller, owner-caller"): with self.subTest(username=asked): - response = self.client.get(self.list_url, {"username": asked, "fields": "email"}) + response = self.client.get(self.list_url, {"username": asked}) assert response.status_code == status.HTTP_200_OK, response.content - assert response.data["results"] == [{"email": "owner-caller@example.com"}] + assert self.usernames_in(response) == (["other-caller"] if "," in asked else []) def test_a_name_no_account_holds_is_left_out_rather_than_refused(self): self.login(self.staff) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py index cdd8cc294a39..20428e9d8d9b 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py @@ -569,6 +569,36 @@ def test_both_versions_refuse_a_name_carrying_markup(self): } assert PendingNameChange.objects.count() == 0 + def test_both_versions_store_a_name_as_it_was_sent(self): + """Spaces around a name are kept, so the profile's name with one in front is another name.""" + self.login(self.owner) + for sent in (" Jon Doe ", " Original Name"): + with self.subTest(name=sent): + earlier = self.client.post(EARLIER_REQUEST, {"name": sent}, format="json") + assert earlier.status_code == status.HTTP_201_CREATED + assert self.pending_name(self.owner) == sent + PendingNameChange.objects.filter(user=self.owner).delete() + + later = self.request_name(sent) + assert later.status_code == earlier.status_code + assert later.data == {"name": sent} + assert self.pending_name(self.owner) == sent + PendingNameChange.objects.filter(user=self.owner).delete() + + def test_both_versions_refuse_a_name_of_spaces_alone(self): + self.login(self.owner) + earlier = self.client.post(EARLIER_REQUEST, {"name": " "}, format="json") + assert earlier.status_code == status.HTTP_400_BAD_REQUEST + assert earlier.data == {"new_name": ["This field may not be blank."]} + + envelope = assert_error_envelope( + self.request_name(" "), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="validation", + ) + assert envelope["errors"] == {"name": ["This field may not be blank."]} + assert PendingNameChange.objects.count() == 0 + def test_both_versions_confirm_a_request_the_same_way(self): PendingNameChange.objects.create(user=self.owner, new_name="Jon Doe", rationale="a test") self.login(self.staff) diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index b872acb818e9..39a95ffd7a6e 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -1204,10 +1204,9 @@ def _selection(self, request): Which accounts a request addresses is read both before the handler runs, to settle what the answer can carry, and inside it, to cut the - page. Both read the values the serializer validated, so a name sent - with spaces around it names the same account at each point; and the - serializer runs once, because it is what refuses a selector the list - does not take. + page. Both read the values the serializer validated, so the two cannot + disagree about which accounts are meant; and the serializer runs once, + because it is what refuses a selector the list does not take. """ if self._validated_selection is None: query = self.query_serializer_class(data=request.query_params) From 44e95d39e75d1ba2f435c199fb32bdda1aff7052 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:03:28 +0500 Subject: [PATCH 46/61] fix: publish the page links as members every page carries The page envelope this version publishes left `next` and `previous` out of `required`, though the paginator returns both on every page, as null where there is no page to link to. A client generated from either document typed them as optional. All six paged components now list all seven members as required; the body is unchanged. The override restates what `DefaultPagination` returns, and goes once edx-drf-extensions publishes that envelope itself (https://github.com/openedx/edx-drf-extensions/pull/599). The schema test reads both documents and checks the required members and the null links on every paged component. Co-Authored-By: Claude Opus 5.5 --- .../core/djangoapps/user_api/v2/paginators.py | 8 ++++++-- .../djangoapps/user_api/v2/tests/test_schema.py | 17 +++++++++++++---- 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/paginators.py b/openedx/core/djangoapps/user_api/v2/paginators.py index 8251e1c3f52d..3a715a2c6c37 100644 --- a/openedx/core/djangoapps/user_api/v2/paginators.py +++ b/openedx/core/djangoapps/user_api/v2/paginators.py @@ -50,10 +50,14 @@ def get_page_size(self, request): return min(rows, self.max_page_size) def get_paginated_response_schema(self, schema): - """Describe the full envelope the paginator returns.""" + """ + Describe the full envelope the paginator returns. + + Remove this override once ``DefaultPagination`` in edx-drf-extensions describes all seven members. + """ return { "type": "object", - "required": ["count", "num_pages", "current_page", "start", "results"], + "required": ["count", "num_pages", "current_page", "start", "next", "previous", "results"], "properties": { "count": { "type": "integer", diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index 1a59819998c3..7866ff54822c 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -444,12 +444,21 @@ def test_addresses_owned_by_other_apps_are_not_published(schema): @skip_unless_lms def test_pagination_envelope_is_published_in_full(schema): - """Every paged body this version publishes carries the whole envelope, not DRF's four members.""" + """ + Every paged body this version publishes carries the whole envelope, not DRF's four members. + + Each member is in every page, the links as null where there is no page + to link to, so each one is published as required in both documents. + """ paged = [name for name in VERSION_TWO_COMPONENTS if name.startswith("Paginated")] assert len(paged) == 6 - for component in paged: - published = schema["components"]["schemas"][component] - assert set(published["properties"]) == PAGINATION_MEMBERS, component + for document in (schema, service_wide_schema()): + for component in paged: + published = document["components"]["schemas"][component] + assert set(published["properties"]) == PAGINATION_MEMBERS, component + assert set(published["required"]) == PAGINATION_MEMBERS, component + assert published["properties"]["next"]["nullable"] is True, component + assert published["properties"]["previous"]["nullable"] is True, component @pytest.mark.django_db From 4133581154c18c6f3b486820c0a405ba26a48241 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:04:32 +0500 Subject: [PATCH 47/61] test: pin the two refusals the account list and member add over version 1 Two inputs the version 1 account addresses answered without refusing are refused here, and each is now held beside what version 1 answers. A staff `?email=notanemail` on the list found nothing at version 1 (404 with no body) and is a 400 naming `email` here. An unknown `?view=` on the list or the member was ignored at version 1, which answered with the whole account, and is a 400 naming `view` here, so a mistyped preset is reported rather than answered with more than was asked for. Neither input is given a different successful answer, and no caller in this repository sends either one, so both refusals stay as declared differences rather than being matched to version 1. Nothing caller-visible changes in this commit. Co-Authored-By: Claude Opus 5.5 --- .../user_api/v2/tests/test_account_parity.py | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py index d4cbf4157348..0b1eee1141d7 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py @@ -527,6 +527,50 @@ def test_a_searched_address_with_spaces_before_it_matches_no_account_in_either_v assert current.status_code == status.HTTP_200_OK assert [row["username"] for row in json.loads(current.content)["results"]] == ["refusal-other"] + def test_an_address_that_is_not_well_formed_is_refused_here_and_found_nothing_before(self): + """A difference this version declares: a malformed address is refused rather than looked up.""" + self.login(self.staff) + asked = {"email": "notanemail"} + earlier = self.client.get(EARLIER_LIST, asked) + assert earlier.status_code == status.HTTP_404_NOT_FOUND + assert earlier.content == b"" + + current = self.client.get(reverse("user_v2:account_list"), asked) + envelope = assert_error_envelope( + current, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == {"email": ["Enter a valid email address."]} + + def test_a_preset_this_version_does_not_offer_is_refused_here_and_ignored_before(self): + """ + A difference this version declares: an unknown ``view`` is refused rather than ignored. + + The earlier addresses answered any value other than ``shared`` with the + whole account, so a mistyped preset returned more than was asked for. + """ + self.login(self.owner) + refusal = { + "view": ["Ask for any of: minimal, shared, or omit this parameter for the default response."], + } + for earlier_address, address in ( + (EARLIER_LIST, reverse("user_v2:account_list")), + (earlier_detail("refusal-owner"), self.member), + ): + with self.subTest(address=address): + earlier = self.client.get(earlier_address, {"view": "bogus"}) + assert earlier.status_code == status.HTTP_200_OK + rows = json.loads(earlier.content) + rows = rows if isinstance(rows, list) else [rows] + assert [(row["username"], row["email"]) for row in rows] == [ + ("refusal-owner", "refusal-owner@example.com"), + ] + + current = self.client.get(address, {"view": "bogus"}) + envelope = assert_error_envelope( + current, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", + ) + assert envelope["errors"] == refusal + def test_the_address_of_a_retired_account_keeps_what_the_earlier_body_carried(self): self.login(self.staff) retired_email = self.other.email From a6a154e3f645875aff7462e67dc3b8d03fa82d3b Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:25:17 +0500 Subject: [PATCH 48/61] fix: read the directory's username selector as sent The `username` selector of `/api/user/v2/users/` and `/api/user/v2/user_preferences/` had the spaces around its value removed before it was matched, so `?username=%20alice` returned alice's entry, and a value of spaces alone left the list unfiltered. The account list of this version and the one selector version 1 offers by name (`/api/user/v1/accounts?username=`) match a name exactly as sent. Both selectors now read the value untrimmed. A name with a space before it selects no entry, and a value of spaces alone names nobody and answers an empty page, as it does on the account list. Unpadded values, lists and the empty value behave as before. The tests send a padded name to both directory lists and to version 1's account list and check that none of them returns the account the trimmed name would select. Co-Authored-By: Claude Opus 5.5 --- .../core/djangoapps/user_api/v2/filters.py | 2 ++ .../user_api/v2/tests/test_parity.py | 23 +++++++++++++++++++ .../user_api/v2/tests/test_views.py | 18 +++++++++++++++ 3 files changed, 43 insertions(+) diff --git a/openedx/core/djangoapps/user_api/v2/filters.py b/openedx/core/djangoapps/user_api/v2/filters.py index 60c35adf072d..83a593805dee 100644 --- a/openedx/core/djangoapps/user_api/v2/filters.py +++ b/openedx/core/djangoapps/user_api/v2/filters.py @@ -100,6 +100,7 @@ class UserFilterSet(filters.FilterSet): username = filters.CharFilter( method="filter_usernames", + strip=False, help_text=( "Comma-separated usernames. Only these users are returned, and a name no user holds " "is left out of the page rather than refused." @@ -183,6 +184,7 @@ class UserPreferenceFilterSet(filters.FilterSet): username = filters.CharFilter( field_name="user__username", method="filter_usernames", + strip=False, help_text=( "Comma-separated usernames. Only these users' preferences are returned, and a name " "no user holds is left out of the page rather than refused." diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_parity.py index 3c74118ca116..b3f846b747f5 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_parity.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_parity.py @@ -206,6 +206,29 @@ def test_a_key_other_than_the_sites_is_refused_at_both_versions(self): expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", ) + def test_a_name_with_spaces_before_it_selects_nothing_in_either_version(self): + """ + Both versions match a username exactly as it was sent. + + The directory addresses of version 1 take no username, so its account + list, the one place it selects by name, is the reading compared here. + """ + assert self.client.login(username=self.admin.username, password=PASSWORD) + exact = self.client.get("/api/user/v1/accounts", {"username": "parity-user"}) + padded = self.client.get("/api/user/v1/accounts", {"username": " parity-user"}) + self.client.logout() + assert exact.status_code == status.HTTP_200_OK + assert [account["username"] for account in json.loads(exact.content)] == ["parity-user"] + assert padded.status_code == status.HTTP_404_NOT_FOUND + + for name in ("user_v2:user_list", "user_v2:user_preference_list"): + with self.subTest(address=name): + selected = self.conforming(reverse(name), {"username": "parity-user"}) + assert [row["username"] for row in json.loads(selected.content)["results"]] == ["parity-user"] + padded = self.conforming(reverse(name), {"username": " parity-user"}) + assert padded.status_code == status.HTTP_200_OK, padded.content + assert json.loads(padded.content)["results"] == [] + def test_user_detail_parity(self): legacy = self.legacy(f"/api/user/v1/users/{self.user.id}/") new = self.conforming(reverse("user_v2:user_detail", kwargs={"username": "parity-user"})) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index a2e6b6ec3ffc..c4537e7271d4 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -303,6 +303,15 @@ def test_an_empty_name_narrows_nothing(self): assert response.status_code == status.HTTP_200_OK assert self.usernames_in(response) == ["admin-caller", "alice", "bob", "learner-caller"] + def test_a_name_sent_with_spaces_around_it_is_read_as_sent(self): + """A name is matched exactly as it was sent, so a space before it names no user.""" + self.send_api_key() + for asked, expected in ((" alice", []), ("bob, alice", ["bob"]), (" ", [])): + with self.subTest(username=asked): + response = self.client.get(self.url, {"username": asked, "page_size": 100}) + assert response.status_code == status.HTTP_200_OK, response.content + assert self.usernames_in(response) == expected + def test_filter_by_email(self): self.send_api_key() response = self.client.get(self.url, {"email": "bob@example.com"}) @@ -783,6 +792,15 @@ def test_an_empty_name_narrows_nothing(self): assert response.status_code == status.HTTP_200_OK assert self.keys_in(response) == [("alice", "pref-lang"), ("bob", "time_zone")] + def test_a_name_sent_with_spaces_around_it_is_read_as_sent(self): + """A name is matched exactly as it was sent, so a space before it names no owner.""" + self.send_api_key() + for asked, expected in ((" alice", []), ("bob, alice", [("bob", "time_zone")]), (" ", [])): + with self.subTest(username=asked): + response = self.client.get(self.url, {"username": asked, "page_size": 100}) + assert response.status_code == status.HTTP_200_OK, response.content + assert self.keys_in(response) == expected + def test_the_owner_id_the_earlier_list_took_is_refused_rather_than_ignored(self): """A caller that ported by changing the version segment is told, not quietly unfiltered.""" self.send_api_key() From 6eb8cf53c051bf75217fa563239ad823e31b0550 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:28:35 +0500 Subject: [PATCH 49/61] fix: tell an inactive non-staff caller the email search is not there `POST /api/user/v2/email_searches/` refused a non-staff caller whose account is not active with a 403, by session and by token, where the same caller with an active account is told there is nothing at the address (404). `POST /api/user/v1/accounts/search_emails` answers both with a 404, so the refusal confirmed the search to exactly the callers it is meant to stay hidden from. The check that reports the address as absent to anyone but an administrator now runs before the active-account check. An inactive non-staff caller gets the 404 an active one gets, on both transports. Nothing is admitted that was refused before: anonymous callers still get 401, an inactive administrator is still refused with 403, a restricted application's token is still refused, and the session of an unconfirmed account is still read. The tests send the search from an inactive learner by session and by token to both versions and require a 404 from each. Co-Authored-By: Claude Opus 5.5 --- .../user_api/v2/tests/test_account_parity.py | 20 +++++++++++++++++ .../user_api/v2/tests/test_account_views.py | 22 ++++++++++++++----- openedx/core/djangoapps/user_api/v2/views.py | 17 ++++++++------ 3 files changed, 46 insertions(+), 13 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py index 0b1eee1141d7..26849a248aff 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py @@ -13,6 +13,7 @@ PermissionFactory, UserFactory, ) +from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user from openedx.core.djangolib.testing.utils import skip_unless_lms from .test_parity import diff, unexpected @@ -443,6 +444,25 @@ def test_the_search_hides_itself_from_a_learner_in_both_versions(self): current, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", ) + def test_the_search_hides_itself_from_an_unconfirmed_learner_in_both_versions(self): + """The answer is the same whether the account signs in with a session or a token.""" + self.owner.is_active = False + self.owner.save() + emails = {"emails": ["refusal-other@example.com"]} + token = {"HTTP_AUTHORIZATION": f"JWT {create_jwt_for_user(self.owner)}"} + for transport in ("session", "token"): + with self.subTest(transport=transport): + headers = token if transport == "token" else {} + if transport == "session": + self.login(self.owner) + earlier = self.client.post(EARLIER_SEARCH, emails, format="json", **headers) + assert earlier.status_code == status.HTTP_404_NOT_FOUND, earlier.content + current = self.client.post(reverse("user_v2:email_search_list"), emails, format="json", **headers) + assert_error_envelope( + current, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + self.client.logout() + def test_a_search_without_addresses_keeps_its_status_and_names_the_property(self): self.login(self.staff) earlier = self.client.post(EARLIER_SEARCH, {}, format="json") diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 1dbfef8d3b39..c6cfaca9b056 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -1848,21 +1848,31 @@ def test_an_unconfirmed_staff_account_gets_one_refusal_whichever_way_it_signs_in ) assert by_session["detail"] == by_token["detail"] - def test_an_unconfirmed_learner_gets_one_refusal_whichever_way_it_signs_in(self): + def test_an_unconfirmed_learner_is_told_there_is_nothing_here_whichever_way_it_signs_in(self): + """A caller who may not search is answered as an active one is, so the refusal does not confirm the search.""" self.owner.is_active = False self.owner.save() by_token = assert_error_envelope( self.search(["other-caller@example.com"], **self.token_headers(self.owner)), - expected_status=status.HTTP_403_FORBIDDEN, - expected_type_slug="authz", + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", ) self.login(self.owner) by_session = assert_error_envelope( self.search(["other-caller@example.com"]), - expected_status=status.HTTP_403_FORBIDDEN, - expected_type_slug="authz", + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", ) - assert by_session["detail"] == by_token["detail"] + self.client.logout() + self.owner.is_active = True + self.owner.save() + self.login(self.other) + active = assert_error_envelope( + self.search(["owner-caller@example.com"]), + expected_status=status.HTTP_404_NOT_FOUND, + expected_type_slug="not-found", + ) + assert by_session["detail"] == by_token["detail"] == active["detail"] def test_the_search_is_not_read_with_a_get(self): self.login(self.staff) diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 39a95ffd7a6e..7b49ef20f4b8 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -1532,7 +1532,8 @@ class EmailSearchViewSet( made with POST, and the links on a page of results are followed by sending the body to them again rather than by fetching them. Only a platform administrator may search here; every other caller is told there is nothing - at this address. + at this address, whatever state their own account is in. An administrator + whose account is not active is refused. """ # The addresses are sent in a body so that they stay out of server logs @@ -1543,17 +1544,19 @@ class EmailSearchViewSet( # register any name. # The session of an account that has not confirmed its email address is - # read rather than dropped, so the active-account check refuses it with the - # answer a token of that account gets instead of the request being treated - # as anonymous. A token is read by the library class the platform's own - # pair is built on, named because a view declaring its own classes is not - # one that pair serves. + # read rather than dropped, so it gets the answer a token of that account + # gets instead of the request being treated as anonymous. A token is read + # by the library class the platform's own pair is built on, named because + # a view declaring its own classes is not one that pair serves. authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser) + # A caller who is not an administrator is told there is nothing here + # before the state of their own account is read, so an inactive account + # is not refused in a way that confirms the search exists. permission_classes = ( permissions.IsAuthenticated, - IsActiveUser, CanGetAccountInfo, IsStaffOrAbsent, + IsActiveUser, ) # A platform administrator may read every account the addresses match, so # the policy keeps the selection whole; a narrower policy can replace it From 4d0bb0c88a3452914080065f659527c2055c4830 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:31:35 +0500 Subject: [PATCH 50/61] fix: report an ambiguous account address under the username it carried An address of `/api/user/v2/` whose `{username}` segment the database answers with several accounts, none stored under exactly that name, is refused with a 400 of type `user/ambiguous-account-name`. The refusal listed its message under `non_field_errors`, while every other refusal this version gives for one input (`view`, `fields`, `email`, `name`, `course_key`, `forum_role`) lists it under that input's name, so a client mapping `errors` to what it sent found nothing to point at. The refusal now lists its message under `username`, the path parameter that carried the name, on the account member, the deactivation, the name change confirmation and both verification addresses. Status, type, title and message are unchanged. `non_field_errors` stays only on the refusal of a body that is not an object, which names no single property. The tests pin the key on each of those addresses; the verification addresses had no test of this refusal before. Co-Authored-By: Claude Opus 5.5 --- .../user_api/v2/tests/test_account_views.py | 4 ++-- .../v2/tests/test_name_change_views.py | 2 +- .../v2/tests/test_verification_views.py | 24 +++++++++++++++++++ openedx/core/djangoapps/user_api/v2/views.py | 5 ++-- 4 files changed, 30 insertions(+), 5 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index c6cfaca9b056..d0e1d8a5573f 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -799,7 +799,7 @@ def two_accounts(request, usernames=None, **kwargs): # pylint: disable=unused-a response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="user/ambiguous-account-name", ) assert envelope["title"] == "Ambiguous Account Name" - assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} + assert envelope["errors"] == {"username": [AMBIGUOUS_ACCOUNT_ADDRESS]} def test_a_member_address_one_of_several_accounts_is_stored_under_carries_that_one(self): """The account stored under exactly the name addressed is the answer, in whatever order they come.""" @@ -2123,7 +2123,7 @@ def test_a_deactivation_whose_address_names_more_than_one_account_deactivates_no expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="user/ambiguous-account-name", ) - assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} + assert envelope["errors"] == {"username": [AMBIGUOUS_ACCOUNT_ADDRESS]} for user in (self.owner, self.other, self.staff): user.refresh_from_db() assert user.has_usable_password(), user.username diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py index 20428e9d8d9b..6cb0302a0d25 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py @@ -472,7 +472,7 @@ def test_an_address_naming_more_than_one_account_changes_nothing(self): expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="user/ambiguous-account-name", ) - assert envelope["errors"] == {"non_field_errors": [AMBIGUOUS_ACCOUNT_ADDRESS]} + assert envelope["errors"] == {"username": [AMBIGUOUS_ACCOUNT_ADDRESS]} assert self.profile_name(self.owner) == "Original Name" assert self.pending_name(self.owner) == "Jon Doe" sibling.profile.refresh_from_db() diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py index e364d7ce1bf6..5a44bc7deb29 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py @@ -1,6 +1,7 @@ """Tests for the version 2 User API identity verification views.""" import datetime +from unittest import mock from zoneinfo import ZoneInfo import pytest @@ -20,6 +21,7 @@ ) from lms.djangoapps.verify_student.tests.factories import SSOVerificationFactory from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user +from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS from openedx.core.djangolib.testing.utils import skip_unless_lms from .test_views import PAGINATION_KEYS, write_queries @@ -871,6 +873,28 @@ def test_a_staff_caller_sending_it_is_told_no_account_holds_that_name(self): expected_type_slug="not-found", ) + def test_a_name_more_than_one_account_answers_to_is_refused_under_the_name(self): + """ + Where the database answers a name with several accounts and none is stored under it, none is read. + + The test database resolves a name only to the record stored under + exactly it, so the lookup is answered here the way it answers where a + name resolves more widely. + """ + self.login(self.staff) + with mock.patch( + "openedx.core.djangoapps.user_api.v2.views.accounts_named", + return_value=[self.other, self.staff], + ): + for address in (self.status_url, self.list_url): + with self.subTest(address=address): + envelope = assert_error_envelope( + self.client.get(address), + expected_status=status.HTTP_400_BAD_REQUEST, + expected_type_slug="user/ambiguous-account-name", + ) + assert envelope["errors"] == {"username": [AMBIGUOUS_ACCOUNT_ADDRESS]} + def test_the_account_holding_that_name_is_served_at_it(self): """A user may register the name, and reads their own records where it is addressed.""" holder = UserFactory.create(username="me", email="me@example.com", password=PASSWORD) diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 7b49ef20f4b8..c6a94527ac9c 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -484,13 +484,14 @@ def _the_one_addressed(username, records, name_of): stored under exactly the name given is the one addressed. Where none of them is stored under it the address names no one of them, so it is refused rather than worked on: which record came back first is no basis for - reading or changing an account. + reading or changing an account. The refusal is reported under the path + parameter that carried the name. """ stored_under_it = [record for record in records if name_of(record) == username] if stored_under_it: return stored_under_it[0] if len(records) > 1: - raise AmbiguousAccountName({api_settings.NON_FIELD_ERRORS_KEY: [AMBIGUOUS_ACCOUNT_ADDRESS]}) + raise AmbiguousAccountName({"username": [AMBIGUOUS_ACCOUNT_ADDRESS]}) if not records: raise NotFound return records[0] From dec231f81cb76a3a99cfba6c261eb96935e88d7c Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:38:51 +0500 Subject: [PATCH 51/61] test: drive the absent-account branches through what the services raise One test of the account member made the account lookup return an empty list, which the lookup never does: it raises `UserNotFound` when no account holds the name, and that path is already pinned by the test that requests a name nobody holds. The test proved a state production cannot reach and is removed. The 404 the account change answers when the service raises `UserNotFound` had no test. The service reads the caller's own row again before making the change, so the branch runs when that row is removed after the caller was admitted. A new test removes the row at that point and lets the real service raise; without the branch the request fails with a 500. A comment on the branch says what it is for. Nothing changes for callers. Co-Authored-By: Claude Opus 5.5 --- .../user_api/v2/tests/test_account_views.py | 30 +++++++++++++------ openedx/core/djangoapps/user_api/v2/views.py | 1 + 2 files changed, 22 insertions(+), 9 deletions(-) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index d0e1d8a5573f..9783b555cd60 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -769,15 +769,6 @@ def stored_under_a_name_written_further_apart(request, usernames=None, **kwargs) assert response.status_code == status.HTTP_200_OK assert response.data == {"username": "owner-caller", "email": "owner-caller@example.com"} - def test_a_member_address_the_lookup_resolves_to_nothing_is_reported_as_absent(self): - """A lookup that comes back with no account is an absent address rather than a fault.""" - self.login(self.staff) - with mock.patch(ACCOUNT_LOOKUP, return_value=[]): - response = self.client.get(self.detail_url("owner-caller")) - assert_error_envelope( - response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", - ) - def test_a_member_address_more_than_one_account_answers_to_is_refused(self): """ An address resolving to several accounts names none of them, so it is refused. @@ -1158,6 +1149,27 @@ def test_an_anonymous_caller_is_unauthenticated(self): response, expected_status=status.HTTP_401_UNAUTHORIZED, expected_type_slug="authn", ) + def test_an_account_removed_while_its_change_is_being_made_is_reported_as_absent(self): + """ + The account is looked up again when the change is made, and is gone by then. + + The change is made on the row the caller's own name is stored under, + so where that row has been removed since the caller was admitted the + service finds no account to change, and the address is absent. + """ + change_account = views.update_account_settings + + def removed_first(requesting_user, update, username=None): + User.objects.filter(pk=requesting_user.pk).delete() + return change_account(requesting_user, update, username=username) + + self.login(self.owner) + with mock.patch.object(views, "update_account_settings", removed_first): + response = self.patch(self.own_url, json.dumps({"bio": "x"})) + assert_error_envelope( + response, expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) + def test_a_body_in_another_media_type_is_refused(self): self.login(self.owner) response = self.client.patch( diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index c6a94527ac9c..63c6c48a6339 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -1274,6 +1274,7 @@ def partial_update(self, request, username): ) except UserNotAuthorized as exc: raise PermissionDenied from exc + # The caller's own row is read again here and can be gone by now. except UserNotFound as exc: raise NotFound from exc except AccountValidationError as exc: From 659717b416aaed7e6dbb903ab138f9c94265d90f Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:44:26 +0500 Subject: [PATCH 52/61] revert: serve /lms-api/schema/ as master serves it `/lms-api/schema/` is an existing address. This branch had wrapped it in the compressed schema cache `/api-docs/schema/` uses, so with a non-zero `OPENAPI_CACHE_TIMEOUT` the document was stored for that long and served to later callers with never-cache headers, and a deploy that changed it kept serving the stored copy until its key expired. Nothing this API needs from the document depends on that, and the change was not one a caller of the address had asked for. The address is again served by `SpectacularAPIView` directly, generating the document on each request with the headers it had before. `cached_schema_view()` is back to master's signature and docstring, since nothing else passes it a view or a resource name, and the tests of the cached address are removed. `/api-docs/schema/` is unchanged. Co-Authored-By: Claude Opus 5.5 --- lms/tests.py | 95 ----------------------------------------- lms/urls.py | 11 +---- openedx/core/apidocs.py | 38 ++++++----------- 3 files changed, 16 insertions(+), 128 deletions(-) diff --git a/lms/tests.py b/lms/tests.py index c3c78c8b9e04..ad0902262b4f 100644 --- a/lms/tests.py +++ b/lms/tests.py @@ -3,7 +3,6 @@ import logging import mimetypes -from unittest import mock from django.conf import settings # pylint: disable=unused-import # noqa: F401 from django.core.cache import cache @@ -11,11 +10,9 @@ from django.test import TestCase, override_settings from django.urls import Resolver404, URLResolver, path, resolve, reverse from django.urls.resolvers import RegexPattern -from drf_spectacular.generators import SchemaGenerator from edx_django_utils.plugins import get_plugin_url_patterns import lms.urls -from common.djangoapps.student.tests.factories import TEST_PASSWORD, UserFactory from openedx.core.apidocs import cached_schema_view from openedx.core.djangoapps.plugins.constants import ProjectType from openedx.core.djangoapps.user_api.v2.views import AccountViewSet as CurrentAccountViewSet @@ -98,98 +95,6 @@ def test_api_docs_schema_cache_per_urlconf(self): assert again.content == full.content -class NarrowSchemaCacheTests(TestCase): - """ - The document this service publishes for client generation is served from the cache. - - It is public, it costs a full generation pass, and it is the one schema - address with nothing in front of it. The cache may only serve it if every - caller is given the same document, so that is measured here too. - """ - - ADDRESS = '/lms-api/schema/' - - def _generations(self): - """Count the passes the generator makes, leaving it otherwise alone.""" - return mock.patch.object( - SchemaGenerator, - 'get_schema', - autospec=True, - side_effect=SchemaGenerator.get_schema, - ) - - @override_settings( - OPENAPI_CACHE_TIMEOUT=60, - CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}, - ) - def test_two_requests_generate_the_document_once(self): - cache.clear() - with self._generations() as generated: - first = self.client.get(self.ADDRESS) - second = self.client.get(self.ADDRESS) - assert first.status_code == 200 - assert first.content.startswith(b'openapi:') - assert second.content == first.content - assert second['Content-Type'] == first['Content-Type'] - assert generated.call_count == 1 - - @override_settings( - OPENAPI_CACHE_TIMEOUT=0, - CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}, - ) - def test_without_a_timeout_each_request_generates_it_again(self): - """A deployment that turns the cache off is served exactly what it was before.""" - cache.clear() - with self._generations() as generated: - first = self.client.get(self.ADDRESS) - second = self.client.get(self.ADDRESS) - assert first.status_code == 200 - assert second.content == first.content - assert generated.call_count == 2 - - @override_settings( - OPENAPI_CACHE_TIMEOUT=60, - CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}, - ) - def test_the_two_documents_this_service_serves_are_not_stored_under_one_key(self): - cache.clear() - narrow = self.client.get(self.ADDRESS) - wide = self.client.get('/api-docs/schema/') - assert narrow.status_code == 200 - assert wide.status_code == 200 - assert len(narrow.content) < len(wide.content) - assert self.client.get(self.ADDRESS).content == narrow.content - assert self.client.get('/api-docs/schema/').content == wide.content - - @override_settings( - OPENAPI_CACHE_TIMEOUT=60, - CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}, - ) - def test_another_language_is_not_served_the_document_already_stored(self): - cache.clear() - english = self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='en') - spanish = self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='es-419') - assert english.status_code == 200 - assert spanish.status_code == 200 - assert english.content != spanish.content - assert self.client.get(self.ADDRESS, HTTP_ACCEPT_LANGUAGE='en').content == english.content - - def test_every_caller_is_given_the_same_document(self): - """What the cache may hold: one document, not one per caller.""" - staff = UserFactory.create(username='narrowstaff', password=TEST_PASSWORD, is_staff=True) - root = UserFactory.create( - username='narrowroot', password=TEST_PASSWORD, is_staff=True, is_superuser=True, - ) - anonymous = self.client.get(self.ADDRESS) - served = {'anonymous': anonymous.content} - for user in (staff, root): - assert self.client.login(username=user.username, password=TEST_PASSWORD) - served[user.username] = self.client.get(self.ADDRESS).content - self.client.logout() - assert anonymous.status_code == 200 - assert set(served.values()) == {anonymous.content} - - def _calendars_of_an_application(request): # pylint: disable=unused-argument """Stand-in for an address an installed application serves under a claimed prefix.""" return HttpResponse() diff --git a/lms/urls.py b/lms/urls.py index d1b78cbecdbd..dded010ee06e 100644 --- a/lms/urls.py +++ b/lms/urls.py @@ -1150,14 +1150,7 @@ def _enterprise_enabled(): path('xqueue/', include((submissions_urls, 'submissions'), namespace='submissions')), ] -# LMS API schema for openedx-platform-sdk generation. Served from the same -# cache the service-wide document uses: it is public, it is generated from -# scratch on every request, and it grew several times over when this API was -# added to it. +# LMS API schema for openedx-platform-sdk generation. urlpatterns += [ - path( - 'lms-api/schema/', - cached_schema_view(SpectacularAPIView.as_view(), resource='lms-api-schema'), - name='lms-schema', - ), + path('lms-api/schema/', SpectacularAPIView.as_view(), name='lms-schema'), ] diff --git a/openedx/core/apidocs.py b/openedx/core/apidocs.py index 1450e7a27c52..05f8f59888f0 100644 --- a/openedx/core/apidocs.py +++ b/openedx/core/apidocs.py @@ -84,16 +84,9 @@ def untag_deprecated_operations(result, generator, request, public): # pylint: return result -def cached_schema_view(view=None, resource='apidocs-schema'): +def cached_schema_view(): """ - Serve a generated schema document from the cache, stored compressed. - - With no arguments this builds the service-wide ``/api-docs`` view. A view - passed in is served the same way under the ``resource`` name given, which - is what keeps each document a service publishes in a key space of its own: - the narrower document each service serves for client generation is - otherwise regenerated on every anonymous request, and it is the one schema - address with nothing in front of it. + Build the ``/api-docs`` schema view, caching the rendered document compressed. ``cache_page`` stores the pickled ``Response``, which for this schema is over memcached's default 1MB item limit. ``CACHES['default']`` sets @@ -102,18 +95,16 @@ def cached_schema_view(view=None, resource='apidocs-schema'): whole schema on every request. Storing the zlib-compressed body instead brings it to roughly a tenth of the limit. - The key covers the resource, the URLconf, the path, the negotiated - representation and the active language. The URLconf because the LMS and the - CMS serve this view at the same path and share one cache by default, so - without it whichever service generated first would serve its document at - the other's URL. The language because drf-spectacular renders the document - under whatever language is active, and ``LocaleMiddleware`` sets that from - the request's cookie or ``Accept-Language`` before this runs. - - The key does not cover who asked: a document stored here is served to every - later caller, so an address wrapped this way must publish one document for - all of them. The narrower document is held to that by a test that asks for - it anonymously, as staff and as a superuser and compares the three. + The key covers the URLconf, the path, the negotiated representation and the + active language. The URLconf because the LMS and the CMS serve this view at + the same path and share one cache by default, so without it whichever + service generated first would serve its document at the other's URL. The + language because drf-spectacular renders the document under whatever + language is active, and ``LocaleMiddleware`` sets that from the request's + cookie or ``Accept-Language`` before this runs. Nothing else in it varies by + requester -- ``SERVE_PUBLIC`` defaults to ``True``, ``SERVE_*`` cannot be set + through ``custom_settings``, and ``API_DOCS_SETTINGS`` sets ``'SERVERS': []`` + so no ``servers`` block is emitted. Only GET and HEAD are cached, as ``cache_page`` did: DRF answers OPTIONS on this view with a 200 metadata document, which would otherwise be stored and @@ -127,8 +118,7 @@ def cached_schema_view(view=None, resource='apidocs-schema'): """ from drf_spectacular.views import SpectacularAPIView # pylint: disable=import-outside-toplevel - if view is None: - view = SpectacularAPIView.as_view(custom_settings=get_api_docs_settings()) + view = SpectacularAPIView.as_view(custom_settings=get_api_docs_settings()) def _response(content_type, body): """Build the response, marking it uncacheable downstream as drf-yasg did.""" @@ -142,7 +132,7 @@ def schema_view(request, *args, **kwargs): return view(request, *args, **kwargs) cache_key = get_cache_key( - resource=resource, + resource='apidocs-schema', urlconf=settings.ROOT_URLCONF, path=request.get_full_path(), accept=request.META.get('HTTP_ACCEPT', ''), From 648b3b4d1f996a1330c46bef84664385a24b3985 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:30:20 +0500 Subject: [PATCH 53/61] fix: answer a refused method, Accept, media type or body as other APIs do The error-type catalog in edx-drf-extensions is shared by every API in the process, and typing the failures DRF raises before a handler runs is left to that library. The user API no longer registers its own types for a 405, a 406, a 415 or a body that does not parse, and its views no longer convert those exceptions into subclasses of their own. Caller-visible effect: under /api/user/v2/ those four failures keep their status and detail but now carry the type and title the shared catalog gives them, the same answer /api/enrollment/v2/ gives (today .../errors/internal, "Internal Server Error"). The two error types that name conditions only this API has, user/retired-account and user/ambiguous-account-name, stay. No other API's answers change: a probe of /api/enrollment/v2/ gives the same type for each failure on the base, before and after this change. Co-Authored-By: Claude Opus 5.5 --- .../profile_images/v2/tests/test_views.py | 20 +++++-- .../djangoapps/profile_images/v2/views.py | 4 +- openedx/core/djangoapps/user_api/v2/errors.py | 59 +------------------ .../user_api/v2/tests/test_account_parity.py | 3 +- .../user_api/v2/tests/test_account_views.py | 54 ++++++++--------- .../v2/tests/test_name_change_views.py | 12 ++-- .../v2/tests/test_verification_views.py | 6 +- .../user_api/v2/tests/test_views.py | 40 +++++++++---- openedx/core/djangoapps/user_api/v2/views.py | 20 +++---- 9 files changed, 91 insertions(+), 127 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py index 2ad2cbee1be3..5cd17332147c 100644 --- a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py +++ b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py @@ -14,9 +14,11 @@ from django.contrib.auth.models import User # pylint: disable=imported-auth-user from django.core.files.uploadedfile import SimpleUploadedFile from django.urls import reverse +from edx_rest_framework_extensions.errors import classify_error from edx_rest_framework_extensions.testing import assert_error_envelope from PIL import Image from rest_framework import status +from rest_framework.exceptions import MethodNotAllowed, ParseError, UnsupportedMediaType from rest_framework.test import APITestCase from common.djangoapps.student.tests.factories import UserFactory @@ -33,6 +35,12 @@ PASSWORD = "Password1234" +#: What the shared catalog calls each failure a request meets before a handler +#: runs; this endpoint answers them as every other standardized API does. +REFUSED_METHOD_SLUG = classify_error(MethodNotAllowed("GET"))[0] +UNSUPPORTED_MEDIA_TYPE_SLUG = classify_error(UnsupportedMediaType("text/plain"))[0] +MALFORMED_BODY_SLUG, MALFORMED_BODY_TITLE = classify_error(ParseError()) + #: Where the view records what it refused, which is where an operator reads #: why a caller was told their image could not be used. VIEWS_LOGGER = "openedx.core.djangoapps.profile_images.v2.views" @@ -486,9 +494,9 @@ def test_an_image_sent_as_the_whole_body_under_a_name_of_another_type_is_refused envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, - expected_type_slug="malformed-body", + expected_type_slug=MALFORMED_BODY_SLUG, ) - assert envelope["title"] == "Malformed Request Body" + assert envelope["title"] == MALFORMED_BODY_TITLE assert self.stored_sizes(self.owner.username) == set() assert self.has_image(self.owner) is False @@ -501,9 +509,9 @@ def test_a_form_body_that_is_not_well_formed_is_refused_as_the_callers_fault(sel envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, - expected_type_slug="malformed-body", + expected_type_slug=MALFORMED_BODY_SLUG, ) - assert envelope["title"] == "Malformed Request Body" + assert envelope["title"] == MALFORMED_BODY_TITLE assert self.stored_sizes(self.owner.username) == set() assert self.has_image(self.owner) is False @@ -656,7 +664,7 @@ def test_a_body_in_a_media_type_this_endpoint_cannot_read_is_refused(self): assert_error_envelope( self.client.post(self.url, {"file": "not an image"}, format="json"), expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, - expected_type_slug="unsupported-media-type", + expected_type_slug=UNSUPPORTED_MEDIA_TYPE_SLUG, ) assert self.stored_sizes(self.owner.username) == set() @@ -676,7 +684,7 @@ def test_the_address_is_not_read_with_a_get(self): assert_error_envelope( self.client.get(self.url), expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index c95af47fa859..e8f9de957e31 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -20,7 +20,7 @@ from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names, set_has_profile_image from openedx.core.djangoapps.user_api.errors import UserNotFound -from openedx.core.djangoapps.user_api.v2.errors import CatalogedRequestErrorsMixin +from openedx.core.djangoapps.user_api.v2.errors import ReadableErrorDetailMixin from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser, RestrictedApplicationGuardMixin from openedx.core.djangoapps.user_api.v2.serializers import ErrorResponse from openedx.core.djangoapps.user_api.v2.view_utils import ( @@ -117,7 +117,7 @@ def get_filename(self, stream, media_type, parser_context): class ProfileImageView( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, AccountResourceMixin, StrictQueryParametersMixin, APIView, diff --git a/openedx/core/djangoapps/user_api/v2/errors.py b/openedx/core/djangoapps/user_api/v2/errors.py index 6bd6b184f0cf..83bd7b5b41e0 100644 --- a/openedx/core/djangoapps/user_api/v2/errors.py +++ b/openedx/core/djangoapps/user_api/v2/errors.py @@ -1,33 +1,10 @@ """Error types this version of the User API classifies for itself.""" from edx_rest_framework_extensions.errors import register_error_type -from rest_framework.exceptions import ( - MethodNotAllowed, - NotAcceptable, - NotFound, - ParseError, - UnsupportedMediaType, - ValidationError, -) +from rest_framework.exceptions import NotFound, ValidationError from rest_framework.settings import api_settings -class RefusedMethod(MethodNotAllowed): - """A request method this API does not serve at the address it was sent to.""" - - -class UnsatisfiableAccept(NotAcceptable): - """An ``Accept`` header naming no representation this API can produce.""" - - -class UnreadableRepresentation(UnsupportedMediaType): - """A request body in a media type this API cannot read.""" - - -class MalformedBody(ParseError): - """A request body that is not well formed in the media type it was sent as.""" - - class AmbiguousAccountName(ValidationError): """ An address answered by more than one account, naming no one of them. @@ -56,10 +33,6 @@ def __init__(self, detail=None, can_cancel_retirement=False, retirement_id=None) } -register_error_type(RefusedMethod, "method-not-allowed", "Method Not Allowed") -register_error_type(UnsatisfiableAccept, "not-acceptable", "Not Acceptable") -register_error_type(UnreadableRepresentation, "unsupported-media-type", "Unsupported Media Type") -register_error_type(MalformedBody, "malformed-body", "Malformed Request Body") register_error_type(RetiredAccount, "user/retired-account", "Retired Account") register_error_type(AmbiguousAccountName, "user/ambiguous-account-name", "Ambiguous Account Name") @@ -103,36 +76,6 @@ def handle_exception(self, exc): return response -class CatalogedRequestErrorsMixin(ReadableErrorDetailMixin): - """ - Names the error type of a refused method, an unanswerable ``Accept`` - header, a body in a media type this API cannot read and a body that is not - well formed in the media type it was sent as. - - The shared catalog classifies none of them, so each would reach the caller - described as a server fault at a 4xx status. Raising this API's own - subclasses of them names each error without changing how the same failure - is classified for any other API in the process; once the shared catalog - covers them, the subclasses can give way to it. - - A view that classifies its request failures also wants the one-line - message of each of them to read as a sentence, so this carries what the - class it extends does as well, and a view names one mixin rather than two. - """ - - def handle_exception(self, exc): - """Classify the request failures the shared catalog leaves unnamed.""" - if isinstance(exc, MethodNotAllowed) and not isinstance(exc, RefusedMethod): - exc = RefusedMethod(self.request.method, detail=exc.detail) - elif isinstance(exc, NotAcceptable) and not isinstance(exc, UnsatisfiableAccept): - exc = UnsatisfiableAccept(detail=exc.detail) - elif isinstance(exc, UnsupportedMediaType) and not isinstance(exc, UnreadableRepresentation): - exc = UnreadableRepresentation(self.request.content_type, detail=exc.detail) - elif isinstance(exc, ParseError) and not isinstance(exc, MalformedBody): - exc = MalformedBody(detail=exc.detail) - return super().handle_exception(exc) - - class ErrorExtensionsMixin: """ Adds the members an exception declares to the error body it produces. diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py index 26849a248aff..0618584fd285 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_parity.py @@ -17,6 +17,7 @@ from openedx.core.djangolib.testing.utils import skip_unless_lms from .test_parity import diff, unexpected +from .test_views import UNSUPPORTED_MEDIA_TYPE_SLUG PASSWORD = "Password1234" MERGE_PATCH = "application/merge-patch+json" @@ -427,7 +428,7 @@ def test_a_body_in_another_media_type_keeps_its_status_and_gains_a_body(self): assert_error_envelope( current, expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, - expected_type_slug="unsupported-media-type", + expected_type_slug=UNSUPPORTED_MEDIA_TYPE_SLUG, ) def test_the_search_hides_itself_from_a_learner_in_both_versions(self): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 9783b555cd60..54b157f2355f 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -37,7 +37,15 @@ from openedx.core.djangolib.testing.utils import skip_unless_lms from .test_schema import name_affirmation_answering -from .test_views import PAGINATION_KEYS, write_queries, write_target +from .test_views import ( + MALFORMED_BODY_SLUG, + MALFORMED_BODY_TITLE, + PAGINATION_KEYS, + REFUSED_METHOD_SLUG, + UNSUPPORTED_MEDIA_TYPE_SLUG, + write_queries, + write_target, +) PASSWORD = "Password1234" @@ -1178,16 +1186,16 @@ def test_a_body_in_another_media_type_is_refused(self): assert_error_envelope( response, expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, - expected_type_slug="unsupported-media-type", + expected_type_slug=UNSUPPORTED_MEDIA_TYPE_SLUG, ) def test_a_body_that_is_not_well_formed_is_refused_as_the_callers_fault(self): self.login(self.owner) response = self.client.patch(self.own_url, "{not json", content_type=MERGE_PATCH) envelope = assert_error_envelope( - response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="malformed-body", + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug=MALFORMED_BODY_SLUG, ) - assert envelope["title"] == "Malformed Request Body" + assert envelope["title"] == MALFORMED_BODY_TITLE def test_a_body_that_is_not_an_object_is_refused(self): self.login(self.owner) @@ -1627,14 +1635,11 @@ def test_a_request_that_names_no_selection_is_answered_by_the_address(self): @skip_unless_lms class OtherApiClassificationTests(AccountApiV2TestCase): """ - What another API calls a request failure is not changed by what this one calls it. - - The catalog of error types is shared by every API in the process, so naming - one of the failures below for this API by registering the type it is raised - as would rename it for all of them. The names used here belong to this - API's own exception classes; the same two failures are read below at a - standardized address of another API, which keeps the name the shared - catalog gives a failure it does not know. + A body that does not parse, or arrives in a media type nothing reads, is + typed here as at a standardized address of another API. + + The catalog of error types is shared by every API in the process, so a type + registered for one of these failures here would rename it for all of them. """ #: Standardized, served by another API, and reads a request body. @@ -1663,20 +1668,11 @@ def test_another_apis_unreadable_body_keeps_the_name_the_shared_catalog_gives_it ) self.assert_unnamed(response, status.HTTP_415_UNSUPPORTED_MEDIA_TYPE) - def test_the_same_two_failures_are_named_at_an_address_of_this_api(self): - """The contrast the two above are measured against.""" + def test_the_same_two_failures_are_typed_alike_at_an_address_of_this_api(self): malformed = self.client.patch(self.own_url, "{not json", content_type=MERGE_PATCH) - assert_error_envelope( - malformed, - expected_status=status.HTTP_400_BAD_REQUEST, - expected_type_slug="malformed-body", - ) + self.assert_unnamed(malformed, status.HTTP_400_BAD_REQUEST) unreadable = self.client.patch(self.own_url, "bio=x", content_type="text/plain") - assert_error_envelope( - unreadable, - expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, - expected_type_slug="unsupported-media-type", - ) + self.assert_unnamed(unreadable, status.HTTP_415_UNSUPPORTED_MEDIA_TYPE) @skip_unless_lms @@ -1790,9 +1786,9 @@ def test_a_body_that_is_not_well_formed_is_refused_as_the_callers_fault(self): self.login(self.staff) response = self.client.post(self.url, "{not json", content_type="application/json") envelope = assert_error_envelope( - response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="malformed-body", + response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug=MALFORMED_BODY_SLUG, ) - assert envelope["title"] == "Malformed Request Body" + assert envelope["title"] == MALFORMED_BODY_TITLE def test_a_learner_is_told_there_is_nothing_at_this_address(self): """The search is hidden rather than refused, so it does not confirm what it is for.""" @@ -1892,7 +1888,7 @@ def test_the_search_is_not_read_with_a_get(self): assert_error_envelope( response, expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) def test_the_rest_of_a_search_is_read_by_sending_the_body_to_the_link_again(self): @@ -1993,7 +1989,7 @@ def test_fetching_the_link_to_the_rest_of_a_search_is_not_how_it_is_read(self): assert_error_envelope( response, expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) def test_a_page_the_search_does_not_have_is_not_found(self): @@ -2456,7 +2452,7 @@ def test_the_account_is_not_deactivated_by_reading_it(self): assert_error_envelope( response, expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) self.other.refresh_from_db() assert self.other.has_usable_password() diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py index 6cb0302a0d25..5dc37cd0a7a3 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_name_change_views.py @@ -14,6 +14,8 @@ from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS from openedx.core.djangolib.testing.utils import skip_unless_lms +from .test_views import MALFORMED_BODY_SLUG, MALFORMED_BODY_TITLE, REFUSED_METHOD_SLUG, UNSUPPORTED_MEDIA_TYPE_SLUG + PASSWORD = "Password1234" #: The version 1 addresses these views supersede. @@ -227,9 +229,9 @@ def test_a_body_that_is_not_well_formed_is_refused_as_the_callers_fault(self): envelope = assert_error_envelope( self.client.post(self.request_url, "{not json", content_type="application/json"), expected_status=status.HTTP_400_BAD_REQUEST, - expected_type_slug="malformed-body", + expected_type_slug=MALFORMED_BODY_SLUG, ) - assert envelope["title"] == "Malformed Request Body" + assert envelope["title"] == MALFORMED_BODY_TITLE assert PendingNameChange.objects.count() == 0 def test_a_body_in_a_media_type_this_endpoint_cannot_read_is_refused(self): @@ -237,7 +239,7 @@ def test_a_body_in_a_media_type_this_endpoint_cannot_read_is_refused(self): assert_error_envelope( self.client.post(self.request_url, "Jon Doe", content_type="application/xml"), expected_status=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, - expected_type_slug="unsupported-media-type", + expected_type_slug=UNSUPPORTED_MEDIA_TYPE_SLUG, ) assert PendingNameChange.objects.count() == 0 @@ -260,7 +262,7 @@ def test_the_collection_is_not_read_with_a_get(self): assert_error_envelope( self.client.get(self.request_url), expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) @@ -384,7 +386,7 @@ def test_the_address_is_not_read_with_a_get(self): assert_error_envelope( self.client.get(self.url), expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) assert self.profile_name(self.owner) == "Original Name" diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py index 5a44bc7deb29..93bb4dbcd56d 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_verification_views.py @@ -24,7 +24,7 @@ from openedx.core.djangoapps.user_api.v2.views import AMBIGUOUS_ACCOUNT_ADDRESS from openedx.core.djangolib.testing.utils import skip_unless_lms -from .test_views import PAGINATION_KEYS, write_queries +from .test_views import PAGINATION_KEYS, REFUSED_METHOD_SLUG, write_queries PASSWORD = "Password1234" @@ -282,7 +282,7 @@ def test_the_status_is_not_changed_through_this_address(self): assert_error_envelope( self.client.post(self.status_url, {}, format="json"), expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) @@ -514,7 +514,7 @@ def test_the_attempts_are_not_changed_through_this_address(self): assert_error_envelope( self.client.post(self.list_url, {}, format="json"), expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_views.py index c4537e7271d4..56efcd8933f8 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_views.py @@ -12,9 +12,11 @@ from django.test import SimpleTestCase from django.test.utils import CaptureQueriesContext, override_settings from django.urls import reverse +from edx_rest_framework_extensions.errors import classify_error from edx_rest_framework_extensions.testing import assert_error_envelope from opaque_keys.edx.keys import CourseKey from rest_framework import status +from rest_framework.exceptions import MethodNotAllowed, NotAcceptable, ParseError, UnsupportedMediaType from rest_framework.test import APIClient, APITestCase from common.djangoapps.student.models import PendingNameChange, UserProfile @@ -35,6 +37,13 @@ COURSE_KEY = CourseKey.from_string("course-v1:edX+DemoX+Demo") OTHER_COURSE_KEY = CourseKey.from_string("course-v1:edX+OtherX+Other") +#: What the shared catalog calls each failure a request meets before a handler +#: runs; this API answers them as every other standardized API does. +REFUSED_METHOD_SLUG, REFUSED_METHOD_TITLE = classify_error(MethodNotAllowed("GET")) +NOT_ACCEPTABLE_SLUG, NOT_ACCEPTABLE_TITLE = classify_error(NotAcceptable()) +UNSUPPORTED_MEDIA_TYPE_SLUG = classify_error(UnsupportedMediaType("text/plain"))[0] +MALFORMED_BODY_SLUG, MALFORMED_BODY_TITLE = classify_error(ParseError()) + PAGINATION_KEYS = {"count", "num_pages", "current_page", "start", "next", "previous", "results"} #: The query parameters each endpoint reads, in the order its refusal lists them. @@ -1108,54 +1117,54 @@ def test_the_time_zone_page_is_capped_for_an_anonymous_caller(self): class RefusedRequestTests(UserApiV2TestCase): """A method this API does not serve, and an Accept header it cannot answer.""" - #: Public, standardized, and served by another API: what its refused method - #: is called must not change because this one names its own. + #: Public, standardized, and served by another API, which answers the same + #: failures with the same type. OTHER_API_URL = "/api/enrollment/v2/courses/course-v1:edX+DemoX+Demo/" def setUp(self): super().setUp() self.public_url = reverse("user_v2:time_zone_list") - def test_a_refused_method_is_named_for_an_anonymous_caller(self): + def test_a_method_this_address_does_not_serve_is_refused_for_an_anonymous_caller(self): response = self.client.post(self.public_url, {}, format="json") envelope = assert_error_envelope( response, expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) - assert envelope["title"] == "Method Not Allowed" + assert envelope["title"] == REFUSED_METHOD_TITLE assert envelope["detail"] == 'Method "POST" not allowed.' assert response["Content-Type"] == "application/json" - def test_an_accept_header_this_api_cannot_answer_is_named(self): + def test_an_accept_header_this_api_cannot_answer_is_refused(self): response = self.client.get(self.public_url, HTTP_ACCEPT="application/xml") envelope = assert_error_envelope( response, expected_status=status.HTTP_406_NOT_ACCEPTABLE, - expected_type_slug="not-acceptable", + expected_type_slug=NOT_ACCEPTABLE_SLUG, ) - assert envelope["title"] == "Not Acceptable" + assert envelope["title"] == NOT_ACCEPTABLE_TITLE assert envelope["detail"] == "Could not satisfy the request Accept header." assert response["Content-Type"] == "application/json" - def test_a_refused_method_is_named_on_the_gated_collections(self): + def test_a_method_the_gated_collections_do_not_serve_is_refused(self): self.send_api_key() for url_name in ("user_v2:user_list", "user_v2:user_preference_list"): response = self.client.delete(reverse(url_name)) envelope = assert_error_envelope( response, expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) assert envelope["detail"] == 'Method "DELETE" not allowed.' - def test_a_refused_method_is_named_on_the_gated_members(self): + def test_a_method_the_gated_members_do_not_serve_is_refused(self): self.send_api_key() response = self.client.put(reverse("user_v2:user_detail", args=[self.alice.username])) envelope = assert_error_envelope( response, expected_status=status.HTTP_405_METHOD_NOT_ALLOWED, - expected_type_slug="method-not-allowed", + expected_type_slug=REFUSED_METHOD_SLUG, ) assert envelope["detail"] == 'Method "PUT" not allowed.' @@ -1169,6 +1178,11 @@ def test_another_api_is_classified_exactly_as_the_shared_catalog_classifies_it(s ) assert envelope["title"] == "Internal Server Error" + def test_a_refused_method_is_typed_here_as_another_api_types_it(self): + ours = self.client.post(self.public_url, {}, format="json").json() + theirs = self.client.post(self.OTHER_API_URL, {}, format="json").json() + assert (ours["status"], ours["type"], ours["title"]) == (theirs["status"], theirs["type"], theirs["title"]) + @skip_unless_lms class UnknownQueryParameterTests(UserApiV2TestCase): @@ -1878,7 +1892,7 @@ def test_the_refusal_comes_back_in_the_body_this_version_answers_with(self): self.send_api_key() response = self.client.get(reverse("user_v2:user_list"), HTTP_ACCEPT="text/csv") assert_error_envelope( - response, expected_status=status.HTTP_406_NOT_ACCEPTABLE, expected_type_slug="not-acceptable", + response, expected_status=status.HTTP_406_NOT_ACCEPTABLE, expected_type_slug=NOT_ACCEPTABLE_SLUG, ) def test_an_address_that_answers_with_no_body_refuses_it_too(self): diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 63c6c48a6339..59c822941c3d 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -45,7 +45,7 @@ from openedx.core.lib.api.parsers import MergePatchParser from openedx.core.lib.api.permissions import ApiKeyHeaderPermission -from .errors import AmbiguousAccountName, CatalogedRequestErrorsMixin, ErrorExtensionsMixin, RetiredAccount +from .errors import AmbiguousAccountName, ErrorExtensionsMixin, ReadableErrorDetailMixin, RetiredAccount from .filters import StrictOrderingFilter, UserFilterSet, UserPreferenceFilterSet from .paginators import UserApiPagination from .permissions import ( @@ -665,7 +665,7 @@ def shape_page(self, response, request): class UserViewSet( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, _ActionAddressMixin, _MemberLookupMixin, _ResponsePresetMixin, @@ -786,7 +786,7 @@ def retrieve(self, request, *args, **kwargs): class UserPreferenceViewSet( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, _ActionAddressMixin, _ResponsePresetMixin, StrictQueryParametersMixin, @@ -902,7 +902,7 @@ def retrieve(self, request, *args, **kwargs): class CountryTimeZoneViewSet( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, _ActionAddressMixin, StrictQueryParametersMixin, IterablePaginationMixin, @@ -1081,7 +1081,7 @@ def addressed_account(self): class AccountViewSet( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, ErrorExtensionsMixin, AccountResourceMixin, _ActionAddressMixin, @@ -1443,7 +1443,7 @@ def _failed_change(self, username, error): class AccountDeactivationView( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, AccountResourceMixin, StrictQueryParametersMixin, APIView, @@ -1520,7 +1520,7 @@ def get_queryset(self): class EmailSearchViewSet( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, StrictQueryParametersMixin, IterablePaginationMixin, ScopedQuerysetMixin, @@ -1622,7 +1622,7 @@ def create(self, request): class NameChangeViewSet( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, _ActionAddressMixin, StrictQueryParametersMixin, viewsets.ViewSet, @@ -1738,7 +1738,7 @@ def _verification_sort_key(attempt): class IDVerificationStatusView( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, AccountResourceMixin, StrictQueryParametersMixin, APIView, @@ -1826,7 +1826,7 @@ def get(self, request, username): class IDVerificationViewSet( StandardizedErrorMixin, RestrictedApplicationGuardMixin, - CatalogedRequestErrorsMixin, + ReadableErrorDetailMixin, AccountResourceMixin, StrictQueryParametersMixin, IterablePaginationMixin, From 48a013ed0470d96bb0181f860065990eb53aadf1 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 18:42:35 +0500 Subject: [PATCH 54/61] fix: answer an unserved address under /api/user/v2/ as the rest of the service does The version 2 mount no longer ends in a pattern that claims every address under its prefix. The fallback view, its route, the hand-kept pattern of the authentication app's addresses that it had to step around, and the reordering of lms/urls.py it forced are removed; the mount sits beside api/user/ again, where it was first added. Caller-visible effect: an address under /api/user/v2/ that no route serves gets the service's own 404, exactly as an unknown address anywhere else in the LMS does, where it used to get a JSON error body. An address of this version sent without its trailing slash is now redirected to the slashed form, as /api/user/v2/account/registration already was. Every route and URL name that existed before is still registered; the only pattern removed is the unnamed fallback. Co-Authored-By: Claude Opus 5.5 --- lms/tests.py | 95 +------------ lms/urls.py | 14 +- .../user_api/v2/tests/test_url_mount.py | 54 ++------ .../djangoapps/user_api/v2/tests/test_urls.py | 128 ++---------------- .../user_api/v2/tests/test_views.py | 2 +- openedx/core/djangoapps/user_api/v2/urls.py | 23 ---- openedx/core/djangoapps/user_api/v2/views.py | 17 --- 7 files changed, 26 insertions(+), 307 deletions(-) diff --git a/lms/tests.py b/lms/tests.py index ad0902262b4f..4a45b86a2699 100644 --- a/lms/tests.py +++ b/lms/tests.py @@ -6,19 +6,10 @@ from django.conf import settings # pylint: disable=unused-import # noqa: F401 from django.core.cache import cache -from django.http import HttpResponse from django.test import TestCase, override_settings -from django.urls import Resolver404, URLResolver, path, resolve, reverse -from django.urls.resolvers import RegexPattern -from edx_django_utils.plugins import get_plugin_url_patterns +from django.urls import path -import lms.urls from openedx.core.apidocs import cached_schema_view -from openedx.core.djangoapps.plugins.constants import ProjectType -from openedx.core.djangoapps.user_api.v2.views import AccountViewSet as CurrentAccountViewSet -from openedx.core.djangoapps.user_api.v2.views import UnknownAddressView -from openedx.core.djangoapps.user_authn.views.login import LoginSessionView -from openedx.core.djangoapps.user_authn.views.register import RegistrationView log = logging.getLogger(__name__) @@ -95,88 +86,4 @@ def test_api_docs_schema_cache_per_urlconf(self): assert again.content == full.content -def _calendars_of_an_application(request): # pylint: disable=unused-argument - """Stand-in for an address an installed application serves under a claimed prefix.""" - return HttpResponse() - - -class ClaimedPrefixTests(TestCase): - """ - A prefix whose mount answers every address under it that its own routes do not. - - The current version of the user API is mounted that way, so nothing after - it is ever consulted for an address under that prefix. An installed - application contributes its patterns at one point in the URLconf, which - leaves the order between the two as what decides whether an address such an - application registers under the prefix can be served at all. - - The authentication application registers two addresses there, so that order - is measurable against real patterns rather than asserted about a copy. - """ - - LANDMARK = "api/user/v2/account/registration/" - - def _index_of(self, route): - """Where in the URLconf the pattern that answers that address sits.""" - for index, pattern in enumerate(lms.urls.urlpatterns): - try: - if pattern.resolve(route): - return index - except Resolver404: - continue - raise AssertionError(f"nothing in the URLconf answers {route}") - - def test_the_landmark_address_is_one_an_installed_application_contributes(self): - """The order below says nothing unless an application really registers an address here.""" - contributed = URLResolver(RegexPattern(r"^/"), get_plugin_url_patterns(ProjectType.LMS)) - assert contributed.resolve(f"/{self.LANDMARK}").func.cls is RegistrationView - - def test_the_mount_that_claims_the_prefix_is_consulted_after_those_applications(self): - claimed = self._index_of("api/user/v2/nothing_here/") - assert claimed > self._index_of(self.LANDMARK) - - def test_an_address_an_application_registers_under_the_prefix_reaches_its_view(self): - patterns = list(lms.urls.urlpatterns) - patterns.insert( - self._index_of(self.LANDMARK) + 1, - path("api/user/v2/calendars/", _calendars_of_an_application), - ) - resolved = URLResolver(RegexPattern(r"^/"), patterns).resolve("/api/user/v2/calendars/") - assert resolved.func is _calendars_of_an_application, resolved.func - - def test_an_address_nothing_registers_is_still_answered_by_the_mount(self): - assert resolve("/api/user/v2/nothing_here/").func.cls is UnknownAddressView - - def test_the_version_serves_its_own_resources(self): - assert resolve("/api/user/v2/accounts/").func.cls is CurrentAccountViewSet - - def test_the_addresses_another_application_serves_under_the_prefix_still_reach_it(self): - reached = { - address: resolve(address).func.cls - for address in ( - "/api/user/v2/account/registration/", - "/api/user/v2/account/login_session/", - ) - } - assert reached == { - "/api/user/v2/account/registration/": RegistrationView, - "/api/user/v2/account/login_session/": LoginSessionView, - } - - def test_those_addresses_keep_the_names_they_are_reversed_by(self): - reversed_names = { - "user_api_registration_v2": reverse("user_api_registration_v2"), - "user_api_login_session": reverse("user_api_login_session", kwargs={"api_version": "v2"}), - } - assert reversed_names == { - "user_api_registration_v2": "/api/user/v2/account/registration/", - "user_api_login_session": "/api/user/v2/account/login_session/", - } - - def test_one_of_them_sent_without_its_trailing_slash_is_still_redirected_to_it(self): - response = self.client.get("/api/user/v2/account/registration") - assert response.status_code == 301 - assert response["Location"] == "/api/user/v2/account/registration/" - - urlpatterns = [path('api-docs/schema/', cached_schema_view())] diff --git a/lms/urls.py b/lms/urls.py index dded010ee06e..8a4c1cc929ae 100644 --- a/lms/urls.py +++ b/lms/urls.py @@ -141,8 +141,8 @@ # Course API path('api/courses/', include('lms.djangoapps.course_api.urls')), - # User API endpoints. The current version is mounted at the end of this - # file instead, for the reason given there. + # User API endpoints + path('api/user/v2/', include('openedx.core.djangoapps.user_api.v2.urls')), path('api/user/', include('openedx.core.djangoapps.user_api.urls')), # Note: these are older versions of the User API that will eventually be # subsumed by api/user listed above. @@ -1078,16 +1078,6 @@ def _enterprise_enabled(): urlpatterns.extend(get_plugin_url_patterns(ProjectType.LMS)) -# The current version of the User API, mounted after everything an installed -# application contributes. That mount answers every address under its prefix -# that its own routes do not serve, so an address registered under the prefix -# by anything mounted later is reached by nothing; mounting it here leaves such -# an address to the application that registers it, and leaves the mount only -# the addresses nothing serves. -urlpatterns += [ - path('api/user/v2/', include('openedx.core.djangoapps.user_api.v2.urls')), -] - # Course Home API urls urlpatterns += [ # This is a BFF ("backend for frontend") djangoapp for the Learning MFE (like courseware_api). diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py b/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py index 475cd056e00c..a50b202579e6 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_url_mount.py @@ -1,13 +1,12 @@ """Addresses of other apps that share the prefix version 2 of the User API is mounted on.""" -from django.test import SimpleTestCase +from django.test import SimpleTestCase, TestCase from django.urls import resolve, reverse from openedx.core.djangolib.testing.utils import skip_unless_lms AUTHN_LOGIN_VIEWS = "openedx.core.djangoapps.user_authn.views.login" AUTHN_REGISTER_VIEWS = "openedx.core.djangoapps.user_authn.views.register" -V2_VIEWS = "openedx.core.djangoapps.user_api.v2.views" @skip_unless_lms @@ -70,41 +69,16 @@ def test_both_shared_prefix_addresses_still_reverse_to_themselves(self): @skip_unless_lms -class ClaimedPrefixTests(SimpleTestCase): - """ - Every address under this prefix that no route serves is answered by this version. - - The mount matches the whole prefix, so an address under it that none of - the routes and neither of the two addresses the authentication app keeps - matches is answered here rather than left to anything mounted later. That - is what makes a mistyped address come back as JSON, and it is also what - keeps an address registered under this prefix by anything mounted after - this version from being reached at all. - """ - - def assert_refused_here(self, address): - """Assert an address under the prefix is answered by this version's refusal.""" - match = resolve(address) - view_class = match.func.view_class - assert (view_class.__module__, view_class.__name__) == (V2_VIEWS, "UnknownAddressView"), address - - def test_a_mistyped_address_is_answered_by_this_version(self): - self.assert_refused_here("/api/user/v2/acounts/") - - def test_an_address_below_a_route_of_this_version_is_answered_by_this_version(self): - self.assert_refused_here("/api/user/v2/accounts/alice/not-a-property/") - - def test_a_third_address_of_the_other_apps_shape_is_answered_here(self): - """Only the two addresses spelled out for that app are left to it; a third is not.""" - self.assert_refused_here("/api/user/v2/account/password_reset/") - - def test_an_address_a_later_mount_would_serve_is_answered_here_instead(self): - """ - The prefix is claimed whole, which is the constraint an operator needs. - - Anything mounted after this version that registers an address under - the prefix is unreachable, so the shape of such an address is pinned - here rather than left to be discovered from a 404 in a deployment. - """ - self.assert_refused_here("/api/user/v2/some_plugin/thing/") - self.assert_refused_here("/api/user/v2/badges/") +class UnservedAddressTests(TestCase): + """An address under this prefix is answered as an address anywhere else in the service is.""" + + def test_an_address_no_route_serves_is_answered_as_one_outside_this_prefix(self): + ours = self.client.get("/api/user/v2/not_a_collection/", HTTP_ACCEPT="application/json") + elsewhere = self.client.get("/api/not_a_service/v2/not_a_collection/", HTTP_ACCEPT="application/json") + assert ours.status_code == elsewhere.status_code == 404 + assert ours["Content-Type"] == elsewhere["Content-Type"] + + def test_an_address_sent_without_its_slash_is_redirected_whichever_app_serves_it(self): + for address in ("/api/user/v2/time_zones", "/api/user/v2/account/registration"): + response = self.client.get(address) + assert (response.status_code, response["Location"]) == (301, f"{address}/"), address diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_urls.py b/openedx/core/djangoapps/user_api/v2/tests/test_urls.py index b2a764d068cd..22dee33f572b 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_urls.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_urls.py @@ -4,17 +4,14 @@ import pytest from django.core.exceptions import ImproperlyConfigured -from django.urls import get_resolver, resolve, reverse +from django.urls import Resolver404, get_resolver, resolve, reverse from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser -from edx_rest_framework_extensions.testing import assert_error_envelope -from rest_framework import status from rest_framework.request import Request from rest_framework.settings import api_settings from rest_framework.test import APIRequestFactory, APITestCase from rest_framework.views import APIView -from common.djangoapps.student.tests.factories import AdminFactory from openedx.core.djangoapps.profile_images.v2.views import ProfileImageView from openedx.core.djangoapps.user_api.v2 import urls as v2_urls from openedx.core.djangoapps.user_api.v2.views import ( @@ -28,8 +25,6 @@ ) from openedx.core.djangolib.testing.utils import skip_unless_lms -PASSWORD = "Password1234" - V2_VIEW_MODULE = "openedx.core.djangoapps.user_api.v2.views" PROFILE_IMAGE_VIEW_MODULE = "openedx.core.djangoapps.profile_images.v2.views" V1_VIEW_MODULE = "openedx.core.djangoapps.user_api.views" @@ -304,28 +299,21 @@ def test_a_key_containing_a_comma_belongs_to_the_key(self): ) == "/api/user/v2/user_preferences/ada.lovelace,a,b/" def test_a_username_outside_the_allowed_pattern_does_not_reach_the_viewset(self): - match = resolve("/api/user/v2/user_preferences/al!ce,pref-lang/") - assert view_identity(match.func) == (V2_VIEW_MODULE, "UnknownAddressView") + with pytest.raises(Resolver404): + resolve("/api/user/v2/user_preferences/al!ce,pref-lang/") def test_no_database_id_member_address_is_served(self): - match = resolve("/api/user/v2/user_preferences/42/") - assert view_identity(match.func) == (V2_VIEW_MODULE, "UnknownAddressView") + with pytest.raises(Resolver404): + resolve("/api/user/v2/user_preferences/42/") @skip_unless_lms class RouteShapeTests(APITestCase): - """ - Every address this version serves is named and ends in a slash. - - The mount also carries one pattern that is neither: the fallback matched - after all of them, which answers an address no route serves. It addresses - no resource and reverses to nothing, which is why it has no name, and - pinning it here keeps a second wildcard from being added quietly beside - it. - """ + """Every address this version serves is named and ends in a slash.""" def test_every_address_is_named_and_ends_in_a_slash(self): - addresses = [pattern for pattern in v2_urls.urlpatterns if pattern.name] + addresses = v2_urls.urlpatterns + assert all(pattern.name for pattern in addresses), [str(p.pattern) for p in addresses if not p.name] assert sorted(pattern.name for pattern in addresses) == [ "account_deactivation", "account_detail", @@ -366,11 +354,6 @@ def test_the_router_route_that_is_replaced_has_to_exist(self): with pytest.raises(ImproperlyConfigured): v2_urls.without_route(routes, "user_preference_detail_renamed") - def test_the_one_unnamed_pattern_is_the_fallback_and_it_is_matched_last(self): - unnamed = [pattern for pattern in v2_urls.urlpatterns if not pattern.name] - assert len(unnamed) == 1 - assert unnamed[0] is v2_urls.urlpatterns[-1] - assert view_identity(unnamed[0].callback) == (V2_VIEW_MODULE, "UnknownAddressView") @skip_unless_lms @@ -471,98 +454,3 @@ def test_version_one_url_names_still_reverse(self): def test_unversioned_twins_still_resolve(self): match = resolve("/user_api/v1/users/") assert view_identity(match.func) == (V1_VIEW_MODULE, "UserViewSet") - - -@skip_unless_lms -class MalformedAddressTests(APITestCase): - """An address that matches no route is refused in the body shape this API answers with.""" - - def setUp(self): - super().setUp() - self.admin = AdminFactory.create(username="url-admin", password=PASSWORD) - assert self.client.login(username=self.admin.username, password=PASSWORD) - - def assert_refused_in_json(self, response): - """Assert the refusal is the standard error body and not a page meant for a browser.""" - assert response["Content-Type"].startswith("application/json"), response["Content-Type"] - assert " Date: Wed, 4 Nov 2026 18:53:42 +0500 Subject: [PATCH 55/61] fix: leave the shared profile image helper as it was and record in version 2 set_has_profile_image() in user_api/accounts/image_helpers.py goes back to its original signature, body and docstring: it takes a username, as its callers and any out-of-tree caller passing username= expect. The version 2 profile image view no longer calls it; it writes the profile of the account the request was admitted for itself, reached from that account rather than looked up again by name, with the same fields the helper sets. Caller-visible effect: none for version 1 or for any caller of the helper. Version 2 still records the image on the admitted account, and still answers 404 when that account has no profile. The tests that called the helper with an account are replaced by tests of the version 2 write: an upload is recorded on the admitted account even if it is stored under another name by the time the image is recorded, and a name answering for more than one account never comes into the write. Co-Authored-By: Claude Opus 5.5 --- .../profile_images/v2/tests/test_views.py | 79 ++++++------------- .../djangoapps/profile_images/v2/views.py | 17 ++-- .../user_api/accounts/image_helpers.py | 14 ++-- .../user_api/v2/tests/test_account_views.py | 21 ++--- 4 files changed, 50 insertions(+), 81 deletions(-) diff --git a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py index 5cd17332147c..49321ea00090 100644 --- a/openedx/core/djangoapps/profile_images/v2/tests/test_views.py +++ b/openedx/core/djangoapps/profile_images/v2/tests/test_views.py @@ -23,12 +23,7 @@ from common.djangoapps.student.tests.factories import UserFactory from openedx.core.djangoapps.oauth_dispatch.jwt import create_jwt_for_user -from openedx.core.djangoapps.user_api.accounts.image_helpers import ( - get_profile_image_names, - get_profile_image_storage, - set_has_profile_image, -) -from openedx.core.djangoapps.user_api.errors import UserNotFound +from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names, get_profile_image_storage from openedx.core.djangolib.testing.utils import skip_unless_lms from ...tests.helpers import make_image_file @@ -929,62 +924,36 @@ def test_both_versions_refuse_another_learners_image(self): @skip_unless_lms -class ImageRecordingTests(APITestCase): +class ImageRecordingTests(ProfileImageTestCase): """ - What an image is recorded on is the account handed over, not a name read again. + What an image is recorded on is the account the request was admitted for. - The recording helper takes either the account itself or the name of one. A - caller that has already settled which account it is acting on hands over - that account, and that is the account written to; a caller that has only a - name is served by the name, as before. + The profile written is reached from that account, not looked up again by + the name the account is stored under. """ - def setUp(self): - super().setUp() - self.owner = UserFactory.create(username="recorded-owner", password=PASSWORD) - self.uploaded_at = datetime.datetime(2026, 3, 4, 5, 6, tzinfo=ZoneInfo("UTC")) - - def test_the_account_handed_over_is_the_account_recorded_on(self): - """ - The account's own row is the one written, so no name is read on the way to it. + def renaming_the_owner_before_the_image_is_recorded(self): + """Store the owner under another name once the sizes are written and before the image is recorded.""" + def rename(*args, **kwargs): # pylint: disable=unused-argument + User.objects.filter(pk=self.owner.pk).update(username="image-owner-elsewhere") - The account is given a different name in the database behind the - record handed over, which a write that read a name would not find. - """ - User.objects.filter(pk=self.owner.pk).update(username="recorded-owner-elsewhere") - set_has_profile_image(self.owner, True, self.uploaded_at) - self.owner.profile.refresh_from_db() - assert self.owner.profile.has_profile_image is True - assert self.owner.profile.profile_image_uploaded_at == self.uploaded_at + return mock.patch( + "openedx.core.djangoapps.profile_images.v2.views.create_profile_images", side_effect=rename, + ) - def test_an_account_handed_over_for_clearing_is_the_account_cleared(self): - set_has_profile_image(self.owner, True, self.uploaded_at) - User.objects.filter(pk=self.owner.pk).update(username="recorded-owner-elsewhere") - set_has_profile_image(self.owner, False) - self.owner.profile.refresh_from_db() - assert self.owner.profile.has_profile_image is False - assert self.owner.profile.profile_image_uploaded_at is None + def test_an_upload_is_recorded_on_the_admitted_account_whatever_name_it_is_stored_under(self): + self.login(self.owner) + with self.renaming_the_owner_before_the_image_is_recorded(): + response = self.upload() + assert response.status_code == status.HTTP_204_NO_CONTENT + assert self.has_image(self.owner) is True - def test_a_name_handed_over_is_still_read_as_a_name(self): - """A caller holding a name rather than an account is served as it was.""" - set_has_profile_image(self.owner.username, True, self.uploaded_at) - self.owner.profile.refresh_from_db() - assert self.owner.profile.has_profile_image is True - assert self.owner.profile.profile_image_uploaded_at == self.uploaded_at - - def test_a_name_no_account_holds_is_refused(self): - with pytest.raises(UserNotFound): - set_has_profile_image("nobody-holds-this-name", False) - - def test_an_account_carrying_no_profile_is_refused(self): - profileless = UserFactory.create(username="recorded-no-profile", password=PASSWORD) - profileless.profile.delete() - with pytest.raises(UserNotFound): - set_has_profile_image(profileless, False) - - def test_recording_an_image_without_saying_when_is_refused(self): - with pytest.raises(ValueError, match="No upload datetime was supplied."): - set_has_profile_image(self.owner, True) + def test_an_admitted_account_carrying_no_profile_is_told_there_is_nothing_here(self): + self.login(self.owner) + self.owner.profile.delete() + assert_error_envelope( + self.client.delete(self.url), expected_status=status.HTTP_404_NOT_FOUND, expected_type_slug="not-found", + ) @pytest.fixture(name="image_owner") diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index e8f9de957e31..d050a7554506 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -18,8 +18,8 @@ from rest_framework.response import Response from rest_framework.views import APIView -from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names, set_has_profile_image -from openedx.core.djangoapps.user_api.errors import UserNotFound +from common.djangoapps.student.models import UserProfile +from openedx.core.djangoapps.user_api.accounts.image_helpers import get_profile_image_names from openedx.core.djangoapps.user_api.v2.errors import ReadableErrorDetailMixin from openedx.core.djangoapps.user_api.v2.permissions import IsAddressedUser, RestrictedApplicationGuardMixin from openedx.core.djangoapps.user_api.v2.serializers import ErrorResponse @@ -266,15 +266,16 @@ def _record_image(self, user, is_uploaded): """ Record on the account whether it carries an image of its own. - The account recorded on is the one the request was admitted for, which - is handed over here, so what is recorded lands on that account and on - no other. + The profile written is reached from the account the request was + admitted for rather than looked up again by name, so what is recorded + lands on that account and on no other. """ - uploaded_at = datetime.datetime.now(ZoneInfo("UTC")) if is_uploaded else None try: - set_has_profile_image(user, is_uploaded, uploaded_at) - except UserNotFound as exc: + profile = UserProfile.objects.get(user=user) + except UserProfile.DoesNotExist as exc: raise NotFound from exc + profile.profile_image_uploaded_at = datetime.datetime.now(ZoneInfo("UTC")) if is_uploaded else None + profile.save() def _unusable_image(self, username, message, reason): """Return the refusal telling the caller what the site cannot do with this image.""" diff --git a/openedx/core/djangoapps/user_api/accounts/image_helpers.py b/openedx/core/djangoapps/user_api/accounts/image_helpers.py index 3917a1957ed4..bb2ff19321cb 100644 --- a/openedx/core/djangoapps/user_api/accounts/image_helpers.py +++ b/openedx/core/djangoapps/user_api/accounts/image_helpers.py @@ -160,17 +160,14 @@ def _get_default_profile_image_urls(): ) -def set_has_profile_image(user, is_uploaded, upload_dt=None): +def set_has_profile_image(username, is_uploaded, upload_dt=None): """ System (not user-facing) API call used to store whether the user has uploaded a profile image, and if so, when. Used by profile_image API. Arguments: - user (django.contrib.auth.User or django.contrib.auth.User.username): - the user who uploaded an image, as either that user or the - username of one. A caller that has already settled which user it - is acting for passes that user, so that this records the image on - that user and nothing else is consulted on the way to it. + username (django.contrib.auth.User.username): references the user who + uploaded an image. is_uploaded (bool): whether or not the user has an uploaded profile image. @@ -181,15 +178,14 @@ def set_has_profile_image(user, is_uploaded, upload_dt=None): Raises: ValueError: is_uploaded was True, but no upload datetime was supplied. - UserNotFound: there is no such user, or the user has no profile. + UserNotFound: no user with username `username` exists. """ if is_uploaded and upload_dt is None: # pylint: disable=no-else-raise raise ValueError("No upload datetime was supplied.") elif not is_uploaded: upload_dt = None - selected = {'user__username': user} if isinstance(user, str) else {'user': user} try: - profile = UserProfile.objects.get(**selected) + profile = UserProfile.objects.get(user__username=username) except ObjectDoesNotExist: raise UserNotFound() # pylint: disable=raise-missing-from # noqa: B904 diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 54b157f2355f..8deaae27e3db 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -2153,22 +2153,25 @@ def test_an_image_is_recorded_on_the_account_the_request_was_admitted_for(self): """ What the image is recorded on is the account the request was admitted for. - The account is handed to the write as a record rather than as a name - for the write to find for itself, which is what keeps the account - written to the account the caller was admitted for. + The profile written is reached from that account rather than looked up + again by name, so a name that answers for more than one account never + comes into it. """ address = reverse( "user_v2:account_profile_image", kwargs={"username": self.owner.username}, ) self.login(self.owner) - with mock.patch( - "openedx.core.djangoapps.profile_images.v2.views.set_has_profile_image", - ) as recorded: + found = UserProfile.objects.get + + def found_by_account_only(*args, **kwargs): + if "user__username" in kwargs: + raise UserProfile.MultipleObjectsReturned + return found(*args, **kwargs) + + with mock.patch.object(UserProfile.objects, "get", side_effect=found_by_account_only): assert self.client.delete(address).status_code == status.HTTP_204_NO_CONTENT - assert recorded.call_args.args[0] == self.owner - assert recorded.call_args.args[1] is False self.owner.profile.refresh_from_db() - assert self.owner.profile.has_profile_image is True + assert self.owner.profile.has_profile_image is False @skip_unless_lms From 0846c6410bd32b68ddc85ae2c5277293c52671ee Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 19:02:51 +0500 Subject: [PATCH 56/61] test: generate the user documents once, from the user mounts only The schema tests of this area generated whole documents: the published LMS document per test, the service-wide LMS and Studio documents per class, the service-wide LMS document twice over in one test, and one test loaded the documentation settings in a subprocess. A failure in any unrelated view's generation, or any unrelated settings change, turned them red. Each document is now generated once, from the service's api/user/ mounts only and under the settings it is published with. The service-wide documents keep the "/" path prefix the whole document derives, so their operation ids are the published ones. Tests assert only user addresses. Removed: the subprocess settings test, the test that compared the whole service-wide document with and without this version (the schema gate checks that no name is lost), and the enrollment-id check, which the existing LmsAutoSchemaTest covers. Caller-visible effect: none; tests only. Co-Authored-By: Claude Opus 5.5 --- cms/lib/tests/test_spectacular.py | 11 +- lms/lib/tests/test_spectacular.py | 110 +++++----------- .../user_api/v2/tests/test_schema.py | 117 ++++++------------ 3 files changed, 77 insertions(+), 161 deletions(-) diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py index 06898c70099c..051f66d3dc17 100644 --- a/cms/lib/tests/test_spectacular.py +++ b/cms/lib/tests/test_spectacular.py @@ -1,6 +1,7 @@ """Tests for the CMS drf-spectacular hooks and schema class.""" import re +from importlib import import_module from pathlib import Path from unittest import TestCase, mock @@ -362,8 +363,14 @@ class SupersededUserOperationTest(DjangoTestCase): @classmethod def setUpClass(cls): super().setUpClass() - with patched_settings(get_api_docs_settings()): - cls.schema = SchemaGenerator().get_schema(request=None, public=True) + patterns = [ + entry for entry in import_module(settings.ROOT_URLCONF).urlpatterns + if str(entry.pattern).startswith("api/user/") + ] + # The whole document derives its path prefix from every address the + # service serves, which share nothing past the root. + with patched_settings({**get_api_docs_settings(), "SCHEMA_PATH_PREFIX": "/"}): + cls.schema = SchemaGenerator(patterns=patterns).get_schema(request=None, public=True) def _operations(self): """Every operation of a superseded address this document carries.""" diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index 15a8274cecfd..54497fd3fed9 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -1,16 +1,15 @@ """Tests for the LMS drf-spectacular hooks and schema class.""" import json -import os import re -import subprocess -import sys from collections import defaultdict -from pathlib import Path +from functools import cache +from importlib import import_module from types import SimpleNamespace from unittest import mock import jsonschema +from django.conf import settings from django.test import Client, SimpleTestCase, TestCase from django.urls import path from drf_spectacular.generators import SchemaGenerator @@ -42,6 +41,7 @@ PROFILE_IMAGE_V1_VIEWS = "openedx.core.djangoapps.profile_images.views" PROFILE_IMAGE_V2_VIEWS = "openedx.core.djangoapps.profile_images.v2.views" USER_AUTHN_VIEWS = "openedx.core.djangoapps.user_authn.views.register" +USER_MOUNT = "api/user/" COURSE_VIEWS = "lms.djangoapps.course_api.views" @@ -370,13 +370,33 @@ def _named_body(response): return body["$ref"].rsplit("/", 1)[-1] +@cache +def _user_documents(): + """ + Return the two documents this service publishes, generated once and from the user mounts only. + + Each is generated under the settings it is published with, so what it says + about a user address is what the whole document says about it. + """ + patterns = [ + entry for entry in import_module(settings.ROOT_URLCONF).urlpatterns + if str(entry.pattern).startswith(USER_MOUNT) + ] + published = SchemaGenerator(patterns=patterns).get_schema(request=None, public=True) + # The whole document derives its path prefix from every address the + # service serves, which share nothing past the root. + with patched_settings({**get_api_docs_settings(), "SCHEMA_PATH_PREFIX": "/"}): + service_wide = SchemaGenerator(patterns=patterns).get_schema(request=None, public=True) + return {"published": published, "service-wide": service_wide} + + class SupersededBodyTest(TestCase): """Every address published as superseded carries the bodies it exchanges.""" @classmethod def setUpClass(cls): super().setUpClass() - cls.schema = SchemaGenerator().get_schema(request=None, public=True) + cls.schema = _user_documents()["published"] def test_the_described_addresses_are_ones_this_schema_marks_superseded(self): described = {address for address, _method in superseded_bodies()} @@ -452,9 +472,7 @@ class SupersededRequestBodyTest(TestCase): @classmethod def setUpClass(cls): super().setUpClass() - cls.documents = {"published": SchemaGenerator().get_schema(request=None, public=True)} - with patched_settings(get_api_docs_settings()): - cls.documents["service-wide"] = SchemaGenerator().get_schema(request=None, public=True) + cls.documents = _user_documents() def setUp(self): super().setUp() @@ -572,9 +590,7 @@ class CorrectedSuccessCodeTest(TestCase): @classmethod def setUpClass(cls): super().setUpClass() - cls.documents = {"published": SchemaGenerator().get_schema(request=None, public=True)} - with patched_settings(get_api_docs_settings()): - cls.documents["service-wide"] = SchemaGenerator().get_schema(request=None, public=True) + cls.documents = _user_documents() def setUp(self): super().setUp() @@ -631,73 +647,13 @@ def test_every_document_publishes_that_code_and_nothing_beside_it(self): } -#: Loaded in a process of its own below. The service settings append a -#: component, and the documentation settings are then asked what they append, -#: so that a key one of them carries is seen to reach the other. -DOCUMENTATION_SETTINGS_CHILD = """ -import json -import os - -import lms.envs.common as service_settings - -service_settings.SPECTACULAR_SETTINGS["APPEND_COMPONENTS"] = { - "schemas": {"ServiceComponent": {"type": "object"}}, -} - -os.environ["DJANGO_SETTINGS_MODULE"] = "docs.docs_settings" -from django.conf import settings - -appended = settings.SPECTACULAR_SETTINGS.get("APPEND_COMPONENTS", {}) -print("APPENDED " + json.dumps({ - "keys": sorted(appended), - "schemas": sorted(appended.get("schemas", {})), - "security": sorted(appended.get("securitySchemes", {})), -})) -""" - - -class DocumentationSettingsTest(SimpleTestCase): - """ - The settings the published reference is generated from keep what the service appends. - - They are loaded in a process of their own because they turn every feature - flag on and add Studio's applications to the settings object this process - is already running under, so loading them here would reconfigure the - service for every test that follows. What they append holds component - names the published reference is expected to carry, and one dropped there - leaves the reference and every client built from it without that name - while no count moves. - """ - - def test_a_component_the_service_appends_reaches_the_published_reference(self): - repository = Path(__file__).resolve().parents[3] - environment = dict(os.environ, PYTHONPATH=str(repository)) - environment.pop("DJANGO_SETTINGS_MODULE", None) - finished = subprocess.run( - [sys.executable, "-c", DOCUMENTATION_SETTINGS_CHILD], - cwd=str(repository), - env=environment, - capture_output=True, - text=True, - check=False, - ) - assert finished.returncode == 0, finished.stderr[-2000:] - reported = [line for line in finished.stdout.splitlines() if line.startswith("APPENDED ")] - assert len(reported) == 1, finished.stdout[-2000:] - assert json.loads(reported[0].split(" ", 1)[1]) == { - "keys": ["schemas", "securitySchemes"], - "schemas": ["ServiceComponent"], - "security": ["Basic", "csrf", "jwt"], - } - - class PublishedDocumentTest(TestCase): - """What the service actually publishes: distinct ids, and one area per tag group.""" + """What the service publishes for the user addresses: distinct ids, and one area per tag group.""" @classmethod def setUpClass(cls): super().setUpClass() - cls.schema = SchemaGenerator().get_schema(request=None, public=True) + cls.schema = _user_documents()["published"] @classmethod def operations(cls): @@ -711,15 +667,14 @@ def test_every_operation_id_is_unique(self): ids = [operation["operationId"] for _route, operation in self.operations()] assert sorted(ids) == sorted(set(ids)) - def test_only_the_one_enrollment_pair_is_told_apart_by_a_numeral_suffix(self): + def test_no_operation_is_told_apart_by_a_numeral_suffix(self): """A numeral suffix is assigned in route order, so it is not a stable name.""" suffixed = { route: operation["operationId"] for route, operation in self.operations() if re.fullmatch(r".+_\d+", operation["operationId"]) } - # Renaming this one would change an id the document already published, so it stays. - assert suffixed == {"/api/enrollment/v1/enrollment/{course_id}": "v1_enrollment_retrieve_2"} + assert suffixed == {} def test_a_tag_group_holds_one_area_unless_it_marks_the_client_library(self): """ @@ -733,7 +688,6 @@ def test_a_tag_group_holds_one_area_unless_it_marks_the_client_library(self): for tag in operation.get("tags", []): areas[tag].add(route.split("/")[2]) assert {tag: sorted(members) for tag, members in areas.items()} == { - "v1": ["enrollment"], - "openedx-platform-sdk": ["enrollment", "user"], + "openedx-platform-sdk": ["user"], "user": ["user"], } diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py index 7866ff54822c..24748dc516a6 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_schema.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_schema.py @@ -1,5 +1,6 @@ """Tests for what version 2 of the User API publishes in the OpenAPI schema.""" +import copy import json from importlib import import_module from unittest import mock @@ -101,8 +102,8 @@ PAGINATION_MEMBERS = {"count", "num_pages", "current_page", "start", "next", "previous", "results"} -#: Where this version is mounted in the service's URL configuration. -VERSION_TWO_MOUNT = "api/user/v2/" +#: The prefix every mount serving a user address is configured under. +USER_MOUNT = "api/user/" #: The components this version contributes to the document. VERSION_TWO_COMPONENTS = ( @@ -312,51 +313,40 @@ def assert_records_match(schema, body, component, case=None): "/api/user/v1/preferences/time_zones/": "/api/user/v2/time_zones/", } -#: Legacy enrollment addresses this schema already marked before the user API joined it. -SUPERSEDED_ENROLLMENT_PATHS = { - "/api/enrollment/v2/course/{course_id}", - "/api/enrollment/v2/enrollment/{course_id}", - "/api/enrollment/v2/enrollment/{username},{course_id}", - "/api/enrollment/v2/enrollments", -} - -#: Enrollment operations whose ids must survive the widened path prefix. -ENROLLMENT_OPERATION_IDS = { - "v1_enrollments_list", - "v1_enrollment_create", - "v2_enrollments_list", - "v2_enrollments_list_legacy", - "v2_enrollment_,_retrieve", - "v2_roles_retrieve", -} +def user_patterns(): + """Return the mounts of the service's URL configuration that serve user addresses.""" + configured = import_module(settings.ROOT_URLCONF).urlpatterns + return [entry for entry in configured if str(entry.pattern).startswith(USER_MOUNT)] -@pytest.fixture(name="schema") +@pytest.fixture(name="generated_documents", scope="module") @skip_unless_lms -def schema_fixture(db): # pylint: disable=invalid-name, unused-argument - """The schema published under the service's own drf-spectacular settings.""" - return SchemaGenerator().get_schema(request=None, public=True) - +def generated_documents_fixture(django_db_setup, django_db_blocker): # pylint: disable=unused-argument + """ + Both documents the service publishes, each generated once and from the user mounts only. -def service_wide_schema(patterns=None): - """Return the document the service publishes for browsing its whole surface.""" - with patched_settings(get_api_docs_settings()): - return SchemaGenerator(patterns=patterns).get_schema(request=None, public=True) + Each is generated under the settings it is published with, so what it says + about a user address is what the whole document says about it. + """ + with django_db_blocker.unblock(): + published = SchemaGenerator(patterns=user_patterns()).get_schema(request=None, public=True) + # The whole document derives its path prefix from every address the + # service serves, which share nothing past the root. + with patched_settings({**get_api_docs_settings(), "SCHEMA_PATH_PREFIX": "/"}): + service_wide = SchemaGenerator(patterns=user_patterns()).get_schema(request=None, public=True) + return {"published": published, "service-wide": service_wide} -def patterns_without_this_version(): - """Return the service's URL configuration with this version's mount taken out.""" - configured = import_module(settings.ROOT_URLCONF).urlpatterns - remaining = [entry for entry in configured if str(entry.pattern) != VERSION_TWO_MOUNT] - assert len(remaining) == len(configured) - 1, "this version is not mounted where it is looked for" - return remaining +@pytest.fixture(name="schema") +def schema_fixture(generated_documents): + """The schema published under the service's own drf-spectacular settings.""" + return copy.deepcopy(generated_documents["published"]) -def published_names(schema): - """Return every component name and operation id a document carries.""" - return set(schema["components"]["schemas"]) | { - operation["operationId"] for _path, _method, operation in operations(schema) - } +@pytest.fixture(name="service_wide") +def service_wide_fixture(generated_documents): + """The document the service publishes for browsing its whole surface.""" + return copy.deepcopy(generated_documents["service-wide"]) def operations(schema): @@ -406,18 +396,12 @@ def test_every_operation_of_this_version_is_published_under_one_group(schema): } -@skip_unless_lms -def test_enrollment_operation_ids_survive_the_widened_prefix(schema): - published = {operation["operationId"] for _path, _method, operation in operations(schema)} - assert ENROLLMENT_OPERATION_IDS <= published - - @skip_unless_lms def test_only_superseded_addresses_are_marked_deprecated(schema): deprecated = { path for path, _method, operation in operations(schema) if operation.get("deprecated") } - assert deprecated == SUPERSEDED_ENROLLMENT_PATHS | set(SUPERSEDED_USER_ADDRESSES) + assert deprecated == set(SUPERSEDED_USER_ADDRESSES) @skip_unless_lms @@ -429,21 +413,17 @@ def test_only_this_version_and_the_addresses_it_supersedes_are_published(schema) @skip_unless_lms def test_addresses_owned_by_other_apps_are_not_published(schema): - """Neighbours of the mounts this change adds, including one under its own prefix.""" + """Neighbours of the superseded addresses, served from the same mount and left out.""" for path in ( "/api/user/v1/accounts/deactivate_logout/", "/api/user/v1/accounts/{username}/retirement_status/", "/api/user/v1/preferences/{username}", - "/api/user/v1/account/registration/", - "/api/user/v2/account/registration/", - "/api/profile_images/v1/{username}/upload", - "/api/profile_images/v1/{username}/remove", ): assert path not in schema["paths"], path @skip_unless_lms -def test_pagination_envelope_is_published_in_full(schema): +def test_pagination_envelope_is_published_in_full(schema, service_wide): """ Every paged body this version publishes carries the whole envelope, not DRF's four members. @@ -452,7 +432,7 @@ def test_pagination_envelope_is_published_in_full(schema): """ paged = [name for name in VERSION_TWO_COMPONENTS if name.startswith("Paginated")] assert len(paged) == 6 - for document in (schema, service_wide_schema()): + for document in (schema, service_wide): for component in paged: published = document["components"]["schemas"][component] assert set(published["properties"]) == PAGINATION_MEMBERS, component @@ -670,30 +650,6 @@ def test_each_superseded_body_is_published_in_the_media_types_that_address_reads assert left_out.status_code == 415 -@pytest.mark.django_db -@skip_unless_lms -def test_this_version_only_adds_to_the_service_wide_document(): - """ - Nothing published for browsing the whole service is lost when this version joins it. - - Enum post-processing runs over every operation the service publishes and - renames both sides of a name collision, so a component this version never - declared can be renamed out of the document, and a client generated from it - loses the matching model. The document is therefore read with this version - mounted and with its mount taken out, and the second has to be contained in - the first. - """ - without_this_version = published_names(service_wide_schema(patterns_without_this_version())) - whole = service_wide_schema() - missing = without_this_version - published_names(whole) - assert missing == set(), sorted(missing) - - components = whole["components"]["schemas"] - assert "user_api.User" in components - assert {"UserDirectory", "UserPreferenceRecord", "TimeZone"} <= set(components) - assert "CountryTimeZone" in components - - @skip_unless_lms def test_every_response_shape_is_published(schema): """The reduced bodies the presets return are described, not only the full one.""" @@ -1509,7 +1465,7 @@ def test_the_version_one_account_addresses_keep_an_operation_id_of_their_own(sch @skip_unless_lms -def test_each_renamed_operation_id_names_an_address_in_the_document_that_derives_it(schema): +def test_each_renamed_operation_id_names_an_address_in_the_document_that_derives_it(schema, service_wide): """ A rename that outlived the address it was written for would name nothing. @@ -1517,7 +1473,7 @@ def test_each_renamed_operation_id_names_an_address_in_the_document_that_derives document that trims the area off the front of each path and the one that trims nothing, so each entry applies to exactly one of them. """ - documents = {"this version": schema, "service-wide": service_wide_schema()} + documents = {"this version": schema, "service-wide": service_wide} for (path, method, _derived), operation_id in RENAMED_OPERATION_IDS.items(): naming = [ name for name, document in documents.items() @@ -1851,7 +1807,7 @@ def test_the_addresses_this_phase_adds_publish_no_other_query_parameters(schema) @skip_unless_lms -def test_the_stored_preference_reads_are_named_alike_in_every_document_that_publishes_them(schema): +def test_the_stored_preference_reads_are_named_alike_in_every_document_that_publishes_them(schema, service_wide): """ The collection read and the member read of this resource keep one prefix wherever published. @@ -1862,7 +1818,6 @@ def test_the_stored_preference_reads_are_named_alike_in_every_document_that_publ the front of every path and the other trims nothing, so it is named in each of them through the name that document derives. """ - service_wide = service_wide_schema() assert { (path, method): operation["operationId"] for path, method, operation in operations(schema) From ff17d049650813f2bf821fcd5a8198c335fbda82 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 19:05:12 +0500 Subject: [PATCH 57/61] test: leave the existing schema tests as they were and add beside them Three tests that existed before this work had been edited to make room for it. They are restored, and what this work needs is added next to them: - LmsApiFilterTest.test_keeps_enrollment_drops_the_rest has its name, its assertion that /api/user/v1/accounts/ is dropped, and its _endpoint() helper back. Those still hold. The user-address cases move to a new LmsApiFilterUserAddressTest with its own _served_endpoint() helper. The class docstring no longer says "only enrollment", which is no longer true of the hook. - UntagDeprecatedOperationsRegistrationTest.test_the_hook_runs_last is back as it was. The order against the user marking hook is a new method of its own. - SpectacularSettingsTest no longer pins that cms/envs/development.py sets no SPECTACULAR_SETTINGS. That has nothing to do with the user API, and a legitimate development override would have failed it. Caller-visible effect: none; tests only. Co-Authored-By: Claude Opus 5.5 --- cms/lib/tests/test_spectacular.py | 11 ------ lms/lib/tests/test_spectacular.py | 61 ++++++++++++++++++++---------- openedx/core/tests/test_apidocs.py | 23 ++++++----- 3 files changed, 51 insertions(+), 44 deletions(-) diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py index 051f66d3dc17..2a5a5b4d7afc 100644 --- a/cms/lib/tests/test_spectacular.py +++ b/cms/lib/tests/test_spectacular.py @@ -186,17 +186,6 @@ def test_environments_do_not_replace_the_common_settings(self): # A hook is set by its quoted key; a comment that names one is fine. assert not re.search(r"_HOOKS['\"]", source), module - def test_the_module_the_published_reference_is_generated_from_inherits_this_configuration(self): - """ - It takes the hooks and the prefix by inheritance rather than restating them. - - The committed reference for this service is generated under that - module, and assigning the key there would replace this configuration - wholesale, as the two modules above do -- which would publish the whole - service under no title instead of this API's own surface. - """ - assert "SPECTACULAR_SETTINGS" not in self._source("cms/envs/development.py") - class SharedSchemaBehaviourTest(SimpleTestCase): """ diff --git a/lms/lib/tests/test_spectacular.py b/lms/lib/tests/test_spectacular.py index 54497fd3fed9..dc3b00772101 100644 --- a/lms/lib/tests/test_spectacular.py +++ b/lms/lib/tests/test_spectacular.py @@ -45,7 +45,11 @@ COURSE_VIEWS = "lms.djangoapps.course_api.views" -def _endpoint(route, view_module=COURSE_VIEWS): +def _endpoint(route): + return (route, route, "GET", None) + + +def _served_endpoint(route, view_module=COURSE_VIEWS): """An endpoint tuple as the generator hands it to the hook, served from ``view_module``.""" callback = SimpleNamespace(cls=type("_View", (), {"__module__": view_module})) return (route, route, "GET", callback) @@ -56,32 +60,47 @@ def _schema(*routes): class LmsApiFilterTest(SimpleTestCase): - """The hook keeps the enrollment mounts, this version of the user mounts, and what they supersede.""" + """The pre-processing hook keeps enrollment endpoints and drops unrelated ones.""" + + def test_keeps_enrollment_drops_the_rest(self): + kept = lms_api_filter([ + _endpoint("/api/enrollment/v2/enrollments/"), + _endpoint("/api/enrollment/v1/enrollment"), + _endpoint("/api/user/v1/accounts/"), + ]) + assert [path for path, *_ in kept] == [ + "/api/enrollment/v2/enrollments/", + "/api/enrollment/v1/enrollment", + ] + + +class LmsApiFilterUserAddressTest(SimpleTestCase): + """The hook keeps the current user mounts and the addresses they supersede, beside enrollment.""" def test_keeps_enrollment_this_version_and_the_addresses_it_supersedes(self): kept = lms_api_filter([ - _endpoint("/api/enrollment/v2/enrollments/", ENROLLMENT_VIEWS), - _endpoint("/api/enrollment/v1/enrollment", ENROLLMENT_VIEWS), - _endpoint("/api/user/v2/users/", USER_API_V2_VIEWS), - _endpoint("/api/user/v2/user_preferences/{username},{key}/", USER_API_V2_VIEWS), + _served_endpoint("/api/enrollment/v2/enrollments/", ENROLLMENT_VIEWS), + _served_endpoint("/api/enrollment/v1/enrollment", ENROLLMENT_VIEWS), + _served_endpoint("/api/user/v2/users/", USER_API_V2_VIEWS), + _served_endpoint("/api/user/v2/user_preferences/{username},{key}/", USER_API_V2_VIEWS), # Superseded, and spelled with the parameter name the generator has # not renamed to ``{id}`` yet. - _endpoint("/api/user/v1/users/{pk}/", USER_API_V1_VIEWS), - _endpoint("/api/user/v1/preferences/time_zones/", USER_API_V1_VIEWS), - _endpoint("/api/user/v1/accounts", USER_API_V1_VIEWS), - _endpoint("/api/user/v1/accounts/{username}", USER_API_V1_VIEWS), - _endpoint("/api/user/v1/me", USER_API_V1_VIEWS), - _endpoint("/api/user/v1/accounts/{username}/image", USER_API_V1_VIEWS), - _endpoint("/api/user/v1/accounts/name_change/", USER_API_V1_VIEWS), + _served_endpoint("/api/user/v1/users/{pk}/", USER_API_V1_VIEWS), + _served_endpoint("/api/user/v1/preferences/time_zones/", USER_API_V1_VIEWS), + _served_endpoint("/api/user/v1/accounts", USER_API_V1_VIEWS), + _served_endpoint("/api/user/v1/accounts/{username}", USER_API_V1_VIEWS), + _served_endpoint("/api/user/v1/me", USER_API_V1_VIEWS), + _served_endpoint("/api/user/v1/accounts/{username}/image", USER_API_V1_VIEWS), + _served_endpoint("/api/user/v1/accounts/name_change/", USER_API_V1_VIEWS), # Served by this version from the app that owns the resource. - _endpoint("/api/user/v2/accounts/{username}/profile_image/", PROFILE_IMAGE_V2_VIEWS), + _served_endpoint("/api/user/v2/accounts/{username}/profile_image/", PROFILE_IMAGE_V2_VIEWS), # Neither served nor superseded by this version. - _endpoint("/api/user/v2/account/registration/", USER_AUTHN_VIEWS), - _endpoint("/api/profile_images/v1/{username}/upload", PROFILE_IMAGE_V1_VIEWS), - _endpoint("/api/user/v1/preferences/{username}", USER_API_V1_VIEWS), - _endpoint("/api/courses/v1/courses/", COURSE_VIEWS), - _endpoint("/api/user_tours/v1/tours/"), - _endpoint("/user_api/v1/users/", USER_API_V1_VIEWS), + _served_endpoint("/api/user/v2/account/registration/", USER_AUTHN_VIEWS), + _served_endpoint("/api/profile_images/v1/{username}/upload", PROFILE_IMAGE_V1_VIEWS), + _served_endpoint("/api/user/v1/preferences/{username}", USER_API_V1_VIEWS), + _served_endpoint("/api/courses/v1/courses/", COURSE_VIEWS), + _served_endpoint("/api/user_tours/v1/tours/"), + _served_endpoint("/user_api/v1/users/", USER_API_V1_VIEWS), ]) assert [path for path, *_ in kept] == [ "/api/enrollment/v2/enrollments/", @@ -102,7 +121,7 @@ def test_under_the_version_prefix_the_view_package_decides(self): """Other apps are mounted under the same prefix, so the path alone cannot admit an address.""" route = "/api/user/v2/account/registration/" admitted = { - view_module: [path for path, *_ in lms_api_filter([_endpoint(route, view_module)])] + view_module: [path for path, *_ in lms_api_filter([_served_endpoint(route, view_module)])] for view_module in (USER_AUTHN_VIEWS, USER_API_V2_VIEWS) } assert admitted == {USER_AUTHN_VIEWS: [], USER_API_V2_VIEWS: [route]} diff --git a/openedx/core/tests/test_apidocs.py b/openedx/core/tests/test_apidocs.py index 308c9685cf66..479dfa03e6fe 100644 --- a/openedx/core/tests/test_apidocs.py +++ b/openedx/core/tests/test_apidocs.py @@ -44,21 +44,20 @@ class UntagDeprecatedOperationsRegistrationTest(SimpleTestCase): """Every schema configuration runs the hook after the hooks that mark operations deprecated.""" # The other environments inherit the hooks from these two modules. - SHARED_HOOK = "'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths'," MARKING_HOOKS = { - "cms/envs/common.py": ( - "'cms.lib.spectacular.cms_mark_migrated_paths',", - SHARED_HOOK, - ), - "lms/envs/common.py": ( - "'lms.lib.spectacular.lms_mark_legacy_paths_deprecated',", - SHARED_HOOK, - ), + "cms/envs/common.py": "'cms.lib.spectacular.cms_mark_migrated_paths',", + "lms/envs/common.py": "'lms.lib.spectacular.lms_mark_legacy_paths_deprecated',", } + SHARED_HOOK = "'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths'," def test_the_hook_runs_last(self): - for module, marking_hooks in self.MARKING_HOOKS.items(): + for module, marking_hook in self.MARKING_HOOKS.items(): source = (REPO_ROOT / module).read_text() assert HOOK in source, module - for marking_hook in marking_hooks: - assert source.index(marking_hook) < source.index(HOOK), (module, marking_hook) + assert source.index(marking_hook) < source.index(HOOK), module + + def test_the_hook_runs_after_the_hook_marking_the_superseded_user_addresses(self): + for module in self.MARKING_HOOKS: + source = (REPO_ROOT / module).read_text() + assert self.SHARED_HOOK in source, module + assert source.index(self.SHARED_HOOK) < source.index(HOOK), module From 1ec6d4ca02cdfd46461a3ab020230161e1dfc059 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 19:22:49 +0500 Subject: [PATCH 58/61] docs: shorten the comments added to settings, URLconfs and schema modules The comment blocks this work added to the Studio and documentation settings, the version 2 URLconf, the shared and LMS schema modules and the version 2 views ran to six to nineteen lines of rationale. Each is cut to the line or two a maintainer needs; the rationale belongs in the pull request. The LMS schema class, its operationId method and the enrollment deprecation hook get master's docstrings back, since their behaviour is master's. No code changes. Co-Authored-By: Claude Opus 5.5 --- cms/envs/common.py | 8 +- cms/lib/spectacular.py | 8 +- docs/docs_settings.py | 7 +- lms/lib/spectacular.py | 36 +++---- .../djangoapps/profile_images/v2/views.py | 23 +--- openedx/core/djangoapps/user_api/schema.py | 99 ++++------------- openedx/core/djangoapps/user_api/v2/urls.py | 41 +------ openedx/core/djangoapps/user_api/v2/views.py | 101 ++++-------------- 8 files changed, 63 insertions(+), 260 deletions(-) diff --git a/cms/envs/common.py b/cms/envs/common.py index 99d97cf88c34..910a10eb487b 100644 --- a/cms/envs/common.py +++ b/cms/envs/common.py @@ -1338,13 +1338,7 @@ def _should_send_xblock_events(settings): 'drf_spectacular.hooks.postprocess_schema_enums', 'cms.lib.spectacular.cms_mark_superseded_paths', 'cms.lib.spectacular.cms_mark_migrated_paths', - # Studio mounts the user API at the same addresses the LMS does, and - # both services publish an unauthenticated document at /api-docs/, so - # an address superseded in one is superseded in the other. The list of - # them and the hook that reads it are shared rather than restated here, - # which is what stops a client generated from Studio's document from - # offering an address as current that the LMS document marks as - # superseded. + # Studio serves the user API too, so it marks the same addresses superseded as the LMS. 'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths', 'openedx.core.apidocs.untag_deprecated_operations', ], diff --git a/cms/lib/spectacular.py b/cms/lib/spectacular.py index 2498827d777d..979988ae6e4e 100644 --- a/cms/lib/spectacular.py +++ b/cms/lib/spectacular.py @@ -83,13 +83,7 @@ class CmsAutoSchema(SupersededUserOperations, AutoSchema): suffix in registration order. The conforming address keeps the clean id; the deprecated one is suffixed ``_legacy``. - This service also serves the user API at the same addresses the service - that replaces it does, and both publish an unauthenticated document of - everything they serve. The shared behaviour describes those addresses the - one way, so that a client generated from either document reads the same - signature and the same success code for the same request; it is taken from - where that API's own schema lives rather than copied, because two copies - of a description drift. + The superseded user addresses are described as in the LMS document. """ def get_operation_id(self): diff --git a/docs/docs_settings.py b/docs/docs_settings.py index 12e1bca30c9b..c7d8b4d92afa 100644 --- a/docs/docs_settings.py +++ b/docs/docs_settings.py @@ -82,12 +82,7 @@ # OpenAPI 3 security schemes, consumed by drf-spectacular. "Basic" uses the # OpenAPI 3 http/basic form rather than Swagger 2.0's type: basic. -# -# Whatever the service settings already append is carried through rather than -# replaced: that key holds component names the published reference is expected -# to carry, and dropping one here takes it out of the generated reference and -# out of every client built from it without changing any count that would show -# it had gone. +# Components the service settings already append are kept. SPECTACULAR_SETTINGS["APPEND_COMPONENTS"] = { # noqa: F405 **SPECTACULAR_SETTINGS.get("APPEND_COMPONENTS", {}), # noqa: F405 "securitySchemes": { diff --git a/lms/lib/spectacular.py b/lms/lib/spectacular.py index 51a908c62bc7..5ca5a02b8cc3 100644 --- a/lms/lib/spectacular.py +++ b/lms/lib/spectacular.py @@ -15,24 +15,14 @@ PUBLISHED_PATH_PATTERN = re.compile(r"^/api/enrollment/v\d+/") -# The user addresses this schema documents are the ones the version below -# serves, and beside each of those the address it supersedes. Apps older than -# that version are mounted under the same ``/api/user/v2/`` prefix, so matching -# the prefix alone would publish endpoints described nowhere here; the packages -# a view may come from decide instead. One resource of this version lives in -# the app that owns it rather than in the user API's own package. +# Older apps share this prefix, so the view's package decides what is published. PUBLISHED_USER_PREFIX = "/api/user/v2/" PUBLISHED_USER_VIEW_MODULES = ( "openedx.core.djangoapps.user_api.v2.", "openedx.core.djangoapps.profile_images.v2.", ) -# Every user address, whatever its version, belongs to one tag group. A tag is -# the first path segment left once the configured prefix is removed, which in a -# document that trims ``/api/user`` is the version, so user operations would be -# grouped with the enrollment operations that carry the same version. A document -# that trims nothing already derives a tag naming an area, and regrouping its -# operations would move them in every client generated from it. +# User operations share one tag where the derived tag would only name a version. USER_PATH_PREFIX = "/api/user/" USER_TAG = "user" @@ -69,20 +59,18 @@ def lms_api_filter(endpoints): class LmsAutoSchema(SupersededUserOperations, AutoSchema): """ - Keep colliding addresses distinct and group each operation under its own area. - - The slashless Enrollment v2 address tokenizes to the id of its conforming - twin, so the two would be told apart only by a numeral suffix, which says - which of the two addresses sorts first rather than anything about the - operation; it is suffixed ``_legacy`` instead, leaving the conforming - address the clean id, and the address listed above keeps the name it is - already published under. Each operation keeps the tag the generator derives - for it unless that tag names a version, because a client generated from a - document groups the operations it offers by tag. + Give the colliding legacy Enrollment v2 address a distinct operationId. + + It and its conforming twin tokenize to the same operationId, so + drf-spectacular would otherwise break the tie with a numeral suffix in + registration order. The conforming address keeps the clean id; the + deprecated one is suffixed ``_legacy``. + + A user operation whose derived tag would name a version is tagged ``user``. """ def get_operation_id(self): - """Keep each address that tokenizes to another one's id distinct from it.""" + """Suffix the colliding legacy address so the pair never shares an operationId.""" operation_id = super().get_operation_id() if self.path == COLLIDING_LEGACY_PATH: return f"{operation_id}_legacy" @@ -97,7 +85,7 @@ def get_tags(self): def lms_mark_legacy_paths_deprecated(result, generator, request, public): # pylint: disable=unused-argument - """Mark every legacy enrollment address ``deprecated: true``.""" + """Mark the legacy slashless Enrollment v2 addresses ``deprecated: true``.""" for path, path_item in result.get("paths", {}).items(): if not _is_legacy_path(path): continue diff --git a/openedx/core/djangoapps/profile_images/v2/views.py b/openedx/core/djangoapps/profile_images/v2/views.py index d050a7554506..ee8be165d38f 100644 --- a/openedx/core/djangoapps/profile_images/v2/views.py +++ b/openedx/core/djangoapps/profile_images/v2/views.py @@ -40,12 +40,7 @@ log = logging.getLogger(__name__) -# The name in this address is read as the name of a stored account, and the -# shorthand the account collection takes for the caller's own account is not -# translated here: a request sent under that name works on the account -# registered under it. The description below publishes that to a caller; it is -# written here for the reader of the module, because an address serving one -# account from another app follows the same rule. +# A stored username; the account collection's shorthand for the caller is not translated here. _USERNAME_PATH_PARAM = path_param( "username", "Unique name of the user whose image is addressed. The name is read as it is stored, so " @@ -131,20 +126,10 @@ class ProfileImageView( the stored sizes are served from are carried by the account itself. """ - # An account has one image, set and cleared whole and never listed or - # addressed by an identifier of its own, so it is served from this one - # address rather than routed as a collection. Clearing an image is an - # account change rather than a moderation tool, so staff are not admitted - # to somebody else's; that is not what the account collection admits, - # which is the other reason this is a view of its own rather than an - # action of that collection. + # A view of its own: only the owner is admitted, unlike the account collection. - # The site's own pages let a user who has not confirmed their email - # address set a picture, and the platform default refuses a session - # belonging to such an account. Only the session class differs in what it - # admits: a token is read by the library class the platform's own pair is - # built on, named here because a view declaring its own classes is not one - # that pair serves. + # Admits the session of an account whose email is not yet confirmed, which + # the platform default refuses; tokens are read as the platform reads them. authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser) permission_classes = (permissions.IsAuthenticated, IsAddressedUser) parser_classes = (MultiPartParser, FormParser, NamedImageUploadParser) diff --git a/openedx/core/djangoapps/user_api/schema.py b/openedx/core/djangoapps/user_api/schema.py index 0e6a40b5918a..0019a2789109 100644 --- a/openedx/core/djangoapps/user_api/schema.py +++ b/openedx/core/djangoapps/user_api/schema.py @@ -8,9 +8,8 @@ from drf_spectacular.utils import OpenApiResponse from rest_framework.parsers import FormParser, JSONParser, MultiPartParser -# Addresses listed here are superseded by a conforming address this schema also -# publishes. Each entry is spelled out rather than matched by prefix, so an -# address whose replacement has not been written yet is never marked. +# Addresses superseded by a conforming address this schema also publishes, spelled +# out rather than matched by prefix so an address with no replacement is never marked. SUPERSEDED_USER_PATHS = ( "/api/user/v1/me", "/api/user/v1/accounts", @@ -31,25 +30,9 @@ "/api/user/v1/preferences/time_zones/", ) -# A path parameter leaves no token behind, and the version 1 account collection -# has no trailing slash to tell it from the member address, so the two tokenize -# to one operation id and are told apart only by a numeral handed out in -# registration order. The collection answers with a list of accounts, which the -# generator names for a list, while the document that trims nothing off the -# front of each path has always published that address under the name derived -# for a single account -- the name that leaves the member address the numeral it -# carries there -- so that one is pinned. The key carries the id the generator -# derives, so an entry applies only to the document that derives it; a key no -# document derives would never be reached. -# -# A stored preference is addressed by the pair that identifies it, and the -# comma between the two parameters is left behind as a token of its own, so -# every document derives an id for that read carrying a bare separator where -# the rest of the resource carries a word. That read is named here in each -# document through the id that document derives, which leaves the collection -# read and the member read of the resource under the same leading tokens -# wherever they are published; neither document has published either name, so -# nothing a client imports is taken away. +# Ids pinned over the one a document derives, keyed by (path, method, derived id): the +# v1 account collection keeps the id it is already published under, and the preference +# member read drops the bare "," token its two path parameters leave. RENAMED_OPERATION_IDS = { ("/api/user/v1/accounts", "GET", "api_user_v1_accounts_list"): "api_user_v1_accounts_retrieve", ( @@ -67,9 +50,7 @@ _PATH_PARAMETER = re.compile(r"\{([\w-]+)\}") -# The superseded addresses with their parameter names removed. The generator -# renames a ``{pk}`` parameter to ``{id}`` only after this filter has run, so -# the comparison cannot depend on how a parameter is spelled. +# Compared without parameter names: the generator renames ``{pk}`` to ``{id}`` after filtering. _SUPERSEDED_USER_SHAPES = frozenset(_PATH_PARAMETER.sub("{}", path) for path in SUPERSEDED_USER_PATHS) @@ -84,37 +65,14 @@ def is_superseded_user_path(path): @cache def superseded_bodies(): """ - Return the bodies of each superseded operation, keyed by address and method. + Return the request and success bodies of each superseded operation, keyed by address and method. - The views serving those addresses name no serializer, so an address - published beside the one that replaces it would carry nothing on either - side of the exchange. Each entry below names the shape the handler returns - with the serializer describing that same shape at the replacing address, - which the parity tests of this area hold to the same values; a request of - ``None`` is an operation that reads no body. An address whose view names a - serializer of its own is absent from the table and keeps the component it - has always published. - - A body a handler reads is described by the members it reads and nothing - more: those handlers take a list of any length, a name of any length and a - number where text is expected, so the bounds and types the replacing - serializers publish would have a generated client refuse requests these - addresses accept. - - A request is keyed by media type, because a shape named on its own is - published under every type the view's parsers accept: where that is more - types than the handler reads, a client generated from the document would - pick one it refuses, and where the handler reads a body no serializer - describes, such as an image sent as the whole body, the document would - leave that form out. An address whose body is also read at the address - replacing it takes the same mapping from there, so the two cannot drift. + The v1 views name no serializer. A response is described by the v2 serializer + of the same shape; a request by the members the v1 handler reads, without the + v2 bounds, under the media types that handler reads; ``None`` reads no body. """ - # The serializers read models, which are not loaded when this module is - # first imported, so each module is read inside this one. One of them - # reaches models belonging to a single service, which code shared by both - # services may not import: a service picks that application up by name - # through its settings, and that module is picked up by name here for the - # same reason. + # Imported here because the serializers need loaded models; the v2 user + # serializers reach single-service models, so they are imported by name. # pylint: disable=import-outside-toplevel from openedx.core.djangoapps.profile_images.v2.serializers import IMAGE_UPLOAD_REQUEST from openedx.core.lib.api.parsers import MergePatchParser @@ -177,21 +135,9 @@ def superseded_bodies(): class SupersededUserOperations: """ - Describe the superseded user addresses wherever a service publishes them. - - Both services mount that API at the same addresses and both publish an - unauthenticated document of everything they serve, so what one of those - documents says about one of these addresses is what the other has to say - about it as well: a client generated from either reads the same body on - each side of the exchange, branches on the same success code, and imports - the same name. The behaviour is shared rather than restated in each - service's schema class, which is what keeps the two documents a deployment - publishes from describing one address two ways. + Describe the superseded user addresses the same way in both services' documents. - Every address ``RENAMED_OPERATION_IDS`` does not name keeps the id the - generator derives for it, because a client generated from a document takes - a module from each operationId, so renaming one drops what a consumer - already imports. + Ids not named in ``RENAMED_OPERATION_IDS`` stay as the generator derives them. """ def get_operation_id(self): @@ -201,13 +147,10 @@ def get_operation_id(self): def _get_request_body(self, direction="request"): """ - Publish a body as one the operation needs when any form it may be sent in is. + Mark the body required when any of its media types requires it. - An operation that names the media types it reads loses that mark as - soon as one of them is the bare body of a file, which carries no field - that can be called required. The forms are alternatives rather than - parts of one request, so a body that is required in any of them is a - body the operation cannot be called without. + Overrides a private method of drf-spectacular 0.30, which requires a body + only when every media type does and never requires an inline shape. """ body = super()._get_request_body(direction) if not body: @@ -220,13 +163,7 @@ def _get_request_body(self, direction="request"): return body def _requires_a_body(self, shape, direction): - """ - Say whether a request cannot be sent without this form of the body. - - A shape written out in full is published as it stands, and the - generator calls none of those required; it is required when it names a - member the request must carry, the way a serializer's is. - """ + """Say whether this form of the body names a member the request must carry.""" if isinstance(shape, dict): return bool(shape.get("required")) return self._get_request_for_media_type(shape, direction)[1] diff --git a/openedx/core/djangoapps/user_api/v2/urls.py b/openedx/core/djangoapps/user_api/v2/urls.py index 51dd1428d4b7..ca5a0154a13c 100644 --- a/openedx/core/djangoapps/user_api/v2/urls.py +++ b/openedx/core/djangoapps/user_api/v2/urls.py @@ -22,20 +22,11 @@ app_name = "user_v2" -#: A preference is identified by its owner and its key, so the router's -#: database-id member route is dropped and replaced by the address declared -#: below under the same name. +#: The router's id-based preference route, replaced by the owner,key address below. REPLACED_ROUTER_ROUTE = "user_preference_detail" def without_route(routes, name): - """ - Return ``routes`` without the one registered under ``name``. - - A name that matches nothing means the router stopped generating that route - under that name: the address it serves would then be published alongside - the one declared here instead of being replaced by it, so the mismatch is - refused here rather than discovered at the address. - """ + """Return ``routes`` without the one named ``name``, refusing a name the router does not register.""" kept = [route for route in routes if route.name != name] if len(kept) == len(routes): raise ImproperlyConfigured(f"The router registers no route named {name!r} to replace.") @@ -43,32 +34,19 @@ def without_route(routes, name): class SnakeCaseRouter(SimpleRouter): - """ - A router that names its routes ``_``. - - The names a route is registered under are the ones ``resolve()`` reports - and the ones ``reverse()`` accepts, so they are generated in the published - form rather than rewritten afterwards. - """ + """A router that names its routes ``_``.""" routes = [route._replace(name=route.name.replace("-", "_")) for route in SimpleRouter.routes] -# An address beneath an account is plural where it names rows that accumulate -# behind it, and singular where it names the one thing every account has. router = SnakeCaseRouter() router.register(r"accounts", AccountViewSet, basename="account") -# An identity check belongs to the user who went through it and is reached by -# no other route, so the collection is registered beneath the account it -# belongs to. router.register( rf"accounts/(?P{settings.USERNAME_REGEX_PARTIAL})/verifications", IDVerificationViewSet, basename="account_verification", ) -# What follows the account collection in an address is the name of an account, -# and a user may register any name, so the search over email addresses stands -# beside the accounts rather than under them. +# Beside the accounts rather than under them: an account may be named anything. router.register(r"email_searches", EmailSearchViewSet, basename="email_search") router.register(r"name_changes", NameChangeViewSet, basename="name_change") router.register(r"users", UserViewSet, basename="user") @@ -78,31 +56,22 @@ class SnakeCaseRouter(SimpleRouter): urlpatterns = [ *without_route(router.urls, REPLACED_ROUTER_ROUTE), - # The image belongs to one account and is stored in several sizes, so it - # is addressed as a property of that account rather than as a collection. re_path( rf"^accounts/(?P{settings.USERNAME_REGEX_PARTIAL})/profile_image/$", ProfileImageView.as_view(), name="account_profile_image", ), - # Disabling an account is something a privileged caller does to somebody - # else's account rather than a property of that account, so it is served - # by a view of its own beneath the account it names. re_path( rf"^accounts/(?P{settings.USERNAME_REGEX_PARTIAL})/deactivation/$", AccountDeactivationView.as_view(), name="account_deactivation", ), - # Where one account's owner stands on having proved their identity is - # worked out from the attempts behind it rather than stored, and there is - # one such summary per account, so it is served from an address of its own. re_path( rf"^accounts/(?P{settings.USERNAME_REGEX_PARTIAL})/verification_status/$", IDVerificationStatusView.as_view(), name="account_verification_status", ), - # The username half carries the pattern a username is allowed to match and - # the key half takes the rest of the segment. + # The key half takes the rest of the segment after the comma. re_path( rf"^user_preferences/(?P{settings.USERNAME_REGEX_PARTIAL})" rf",(?P{PREFERENCE_KEY_PATTERN_PARTIAL})/$", diff --git a/openedx/core/djangoapps/user_api/v2/views.py b/openedx/core/djangoapps/user_api/v2/views.py index 453f44ad4eaa..b3216d1a2a57 100644 --- a/openedx/core/djangoapps/user_api/v2/views.py +++ b/openedx/core/djangoapps/user_api/v2/views.py @@ -148,14 +148,8 @@ #: The presets an account response answers to. ACCOUNT_PRESETS = (MINIMAL_VIEW, SHARED_VIEW) -#: The member of the account collection that addresses the caller's own account. -#: It belongs to that collection, and the addresses beneath one account do not -#: translate it: each of those reads the name it is given as the name of a -#: stored account, so a request sent to one of them under this name works on -#: the account registered under it, whichever account that is. The deactivation -#: of an account publishes that in the description of the name it carries; it -#: is written here as well because an address added beside it inherits the rule -#: and not the sentence. +#: The account-collection member naming the caller's own account. Addresses +#: beneath an account do not translate it: there it is a stored username. OWN_ACCOUNT_IDENTIFIER = "me" #: What a caller is told about a member address that more than one account @@ -821,14 +815,8 @@ class UserPreferenceViewSet( #: entry rather than as rows of the page, so the policy that governs them #: is applied where they are fetched. embedded_preference_policy = FullScopePolicy() - #: The owner's entry is itself a row of the user collection rather than of - #: this one, so which owners a caller may be given the entry of is that - #: collection's decision and is declared separately for that reason. It is - #: settled for a whole page in one query, because asking it of each row in - #: turn would cost a query per row. An owner the policy leaves out is left - #: out of the row that carries it; the row itself stays, named by the owner - #: it is stored against, because which rows come back is this collection's - #: own decision and is made by the policy above it. + #: Which owners' user entries a row may embed, settled once per page; a row + #: whose owner is left out keeps only the owner's name. embedded_user_policy = FullScopePolicy() filter_backends = (DjangoFilterBackend, StrictOrderingFilter) filterset_class = UserPreferenceFilterSet @@ -958,14 +946,8 @@ def _shareable_account_fields(): return set(settings.ACCOUNT_VISIBILITY_CONFIGURATION["custom_shareable_fields"]) -#: The classes every operation on an account admits a caller by, wherever it is -#: served from. The account collection declares this tuple and every address -#: that works on one of its accounts carries it, so the rules of the resource -#: are declared once rather than restated by each address that reaches into it. -#: It is read from here rather than from the collection's own attribute because -#: that attribute is added to in place, by the first request to reach a view -#: that reads a token, and admission must not depend on which addresses a -#: process has served already. +#: Admission classes for every operation on an account, wherever it is served. +#: Read from here, not from a view attribute that middleware may extend in place. ACCOUNT_RESOURCE_PERMISSIONS = ( permissions.IsAuthenticated, CanGetAccountInfo, @@ -1107,24 +1089,11 @@ class AccountViewSet( rather than answered as an empty object. """ - # The properties of an account are read from the account service rather - # than from a table of this app's, so there is no queryset to narrow and - # the page is cut from the names the selection resolved to. The service is - # what settles which properties of each account the caller may see; the - # selection settles which accounts the page carries, and is applied in the - # handler rather than declared as a filter set because a filter set has no - # room for the retired-address refusal, which reports rows it cannot carry - # instead of leaving them out. Which properties the answer can carry is - # settled before the address is read, so a request for a property this - # kind of answer never carries is refused without reading or writing - # anything on the way to it. - - # Account settings are reached from the site's own pages by users who have - # not confirmed their email address yet, and the platform default refuses - # a session belonging to such an account. Only the session class differs in - # what it admits: a token is read by the library class the platform's own - # pair is built on, named here because a view declaring its own classes is - # not one that pair serves. + # Accounts come from the account service, not a queryset, and a filter set + # cannot report a retired address, so the selection is applied in the handler. + + # Admits the session of an account whose email is not yet confirmed, which + # the platform default refuses; tokens are read as the platform reads them. authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser) permission_classes = ACCOUNT_RESOURCE_PERMISSIONS #: A change is a merge patch: a body in any other media type is refused. @@ -1255,13 +1224,8 @@ def partial_update(self, request, username): raise ValidationError({ api_settings.NON_FIELD_ERRORS_KEY: ["Send the properties to change as an object."], }) - # The body is measured against the shape this endpoint publishes before - # anything is done with it, and then carried out as it was sent: the - # account service takes properties this version does not publish, and - # refuses the ones that cannot be changed, which dropping them here - # would turn into silence. Every property is optional of itself, which - # is what makes the body a merge patch, and a property that is an - # object of its own is still sent whole. + # Validated against the published shape, then passed on as sent so the + # account service still refuses properties that cannot be changed. AccountUpdateSerializer(data=changes).is_valid(raise_exception=True) if "email" in changes and not settings.ALLOW_EMAIL_ADDRESS_CHANGE: raise ValidationError({"email": ["This site does not let an email address be changed here."]}) @@ -1295,12 +1259,8 @@ def _accounts_named(self, request, usernames, preset=None): if not names: return [] found = self._accounts_found(request, names, preset) - # The accounts come back in the order the database returned them, which - # is not the order of the page they were selected for, so each is put - # back under the name it is stored as. Which stored names a selection - # resolves to is the database's decision and need not be the names it - # was given, so an account none of those names is written as is carried - # at the end of the page rather than left out of it. + # Restore the page's order; an account stored under none of the selected + # spellings is kept, at the end. by_name = {account["username"]: account for account in found} claimed = {name for name in names if name in by_name} ordered = [by_name[name] for name in names if name in by_name] @@ -1455,13 +1415,7 @@ class AccountDeactivationView( removed. Asking for a password reset does not undo this. """ - # Disabling an account is something a privileged caller does to somebody - # else's account rather than a property of that account, and it shares - # neither its callers nor its body with the way an account is read or - # changed: the caller holds the privilege to disable accounts and has - # confirmed their own address, and the body is read as JSON rather than as - # a merge patch. It is therefore a view of its own rather than an action - # of the account collection. + # A view of its own: its callers and body differ from the account collection's. permission_classes = (permissions.IsAuthenticated, IsActiveUser, CanDeactivateUser) @@ -1538,12 +1492,7 @@ class EmailSearchViewSet( whose account is not active is refused. """ - # The addresses are sent in a body so that they stay out of server logs - # and browser histories, which is what makes the search a POST and what - # makes its pages be followed with a body. The search stands beside the - # accounts rather than under them because what follows the account - # collection in an address is the name of an account, and a user may - # register any name. + # A POST so the addresses stay out of server logs and browser histories. # The session of an account that has not confirmed its email address is # read rather than dropped, so it gets the answer a token of that account @@ -1752,12 +1701,8 @@ class IDVerificationStatusView( account is still active may read anyone's. """ - # The summary is computed rather than stored and is never listed, so it is - # served from this one address rather than routed as a collection, and it - # is read from the identity verification service rather than from a table - # of this app's. It admits a different set of callers from the account - # collection, which is why it is a view of its own rather than an action - # of that collection. + # Computed by the identity verification service, one per account; a view of + # its own because it admits different callers from the account collection. permission_classes = ( permissions.IsAuthenticated, @@ -1840,12 +1785,8 @@ class IDVerificationViewSet( absent only when the user it names is. """ - # The attempts are collected from the identity verification service, which - # holds a table per kind of check, so there is no queryset of this app's to - # narrow: the page is cut from what those tables return and is sorted in - # the view rather than by a filter backend. An attempt is reached by no - # route other than this one, which is why the collection is addressed - # beneath the account it belongs to. + # Collected from the identity verification service's tables and sorted + # here, since there is no queryset of this app's to narrow. permission_classes = ( permissions.IsAuthenticated, From 88bce643e7b379fa47359c4bbe909ea079ba6977 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 20:04:54 +0500 Subject: [PATCH 59/61] fix: mark Studio's superseded user addresses through its own hook Studio's schema module has a fixed shape: four path constants, two post-processing hooks and one schema class. It had gained a schema class borrowed from the user API, a second list of superseded addresses and a third marking hook. The user addresses Studio marks are now entries of its own SUPERSEDED_PATHS, marked by cms_mark_superseded_paths, and CmsAutoSchema is master's class again. Studio's settings list master's four hooks. Studio serves no /api/user/v2/, and the borrowed class described its v1 user operations with the serializers of that version, which Studio does not serve. Without it, Studio's whole-service document describes those operations as the views it serves derive them, as master does, and the eight components only those serializers define leave that document. Every mark, path, operationId and the narrow Authoring API document are unchanged. Tests pin the hook list, the schema class's single base, the exact addresses marked in Studio's document and the names those operations keep. Co-Authored-By: Claude Opus 5.5 --- cms/envs/common.py | 2 - cms/lib/spectacular.py | 28 +++- cms/lib/tests/test_spectacular.py | 148 ++++----------------- openedx/core/djangoapps/user_api/schema.py | 2 +- openedx/core/tests/test_apidocs.py | 7 +- 5 files changed, 50 insertions(+), 137 deletions(-) diff --git a/cms/envs/common.py b/cms/envs/common.py index 910a10eb487b..ed0d2b0cbf3c 100644 --- a/cms/envs/common.py +++ b/cms/envs/common.py @@ -1338,8 +1338,6 @@ def _should_send_xblock_events(settings): 'drf_spectacular.hooks.postprocess_schema_enums', 'cms.lib.spectacular.cms_mark_superseded_paths', 'cms.lib.spectacular.cms_mark_migrated_paths', - # Studio serves the user API too, so it marks the same addresses superseded as the LMS. - 'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths', 'openedx.core.apidocs.untag_deprecated_operations', ], # Stripped from each path to derive its tags and operationId, so changing diff --git a/cms/lib/spectacular.py b/cms/lib/spectacular.py index 979988ae6e4e..3bf8aac24e40 100644 --- a/cms/lib/spectacular.py +++ b/cms/lib/spectacular.py @@ -4,10 +4,8 @@ from drf_spectacular.openapi import AutoSchema -from openedx.core.djangoapps.user_api.schema import SupersededUserOperations - -# Legacy operations superseded by a conforming address under /api/authoring/. -# Each is listed in the truncated spelling as well as the full one: the routes +# Legacy operations superseded by a conforming address. Each contentstore one +# is listed in the truncated spelling as well as the full one: the routes # make the final character optional, so both addresses resolve, and which one # the generator emits depends on how it renders that regex. SUPERSEDED_PATHS = ( @@ -15,6 +13,24 @@ "/api/contentstore/v0/youtube_transcripts/{course_id}/check", "/api/contentstore/v0/youtube_transcripts/{course_id}/uploa", "/api/contentstore/v0/youtube_transcripts/{course_id}/upload", + # The user API this service mounts as the LMS does; the LMS serves the replacements. + "/api/user/v1/me", + "/api/user/v1/accounts", + "/api/user/v1/accounts/search_emails", + "/api/user/v1/accounts/{username}", + "/api/user/v1/accounts/{username}/deactivate/", + "/api/user/v1/accounts/{username}/image", + "/api/user/v1/accounts/{username}/verification_status/", + "/api/user/v1/accounts/{username}/verifications/", + "/api/user/v1/accounts/name_change/", + "/api/user/v1/accounts/name_change/{username}/confirm/", + "/api/user/v1/users/", + "/api/user/v1/users/{id}/", + "/api/user/v1/user_prefs/", + "/api/user/v1/user_prefs/{id}/", + "/api/user/v1/preferences/{pref_key}/users/", + "/api/user/v1/forum_roles/{name}/users/", + "/api/user/v1/preferences/time_zones/", ) # Legacy addresses of APIs migrated to /api/authoring/, marked deprecated for @@ -74,7 +90,7 @@ def cms_mark_superseded_paths(result, generator, request, public): # pylint: di return result -class CmsAutoSchema(SupersededUserOperations, AutoSchema): +class CmsAutoSchema(AutoSchema): """ Give a colliding legacy address a distinct operationId. @@ -82,8 +98,6 @@ class CmsAutoSchema(SupersededUserOperations, AutoSchema): operationId, drf-spectacular would otherwise break the tie with a numeral suffix in registration order. The conforming address keeps the clean id; the deprecated one is suffixed ``_legacy``. - - The superseded user addresses are described as in the LMS document. """ def get_operation_id(self): diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py index 2a5a5b4d7afc..eb40478d098b 100644 --- a/cms/lib/tests/test_spectacular.py +++ b/cms/lib/tests/test_spectacular.py @@ -10,6 +10,7 @@ from django.test import TestCase as DjangoTestCase from django.urls import path as url_path from drf_spectacular.generators import SchemaGenerator +from drf_spectacular.openapi import AutoSchema from drf_spectacular.settings import patched_settings, spectacular_settings from rest_framework import serializers, viewsets from rest_framework.response import Response @@ -23,11 +24,6 @@ cms_mark_superseded_paths, ) from openedx.core.apidocs import get_api_docs_settings -from openedx.core.djangoapps.user_api.schema import ( - SUPERSEDED_USER_PATHS, - SupersededUserOperations, - superseded_bodies, -) def _endpoint(path): @@ -81,7 +77,7 @@ def test_every_operation_of_a_superseded_path_is_marked(self): assert result["paths"][path]["get"]["deprecated"] is True def test_both_spellings_of_each_superseded_path_are_listed(self): - assert set(SUPERSEDED_PATHS) == { + assert {path for path in SUPERSEDED_PATHS if path.startswith("/api/contentstore/")} == { "/api/contentstore/v0/youtube_transcripts/{course_id}/chec", "/api/contentstore/v0/youtube_transcripts/{course_id}/check", "/api/contentstore/v0/youtube_transcripts/{course_id}/uploa", @@ -164,6 +160,14 @@ def test_both_hooks_are_configured(self): assert "cms.lib.spectacular.cms_mark_superseded_paths" in hooks assert "cms.lib.spectacular.cms_mark_migrated_paths" in hooks + def test_no_marking_hook_runs_beside_the_two_this_module_defines(self): + assert settings.SPECTACULAR_SETTINGS["POSTPROCESSING_HOOKS"] == [ + "drf_spectacular.hooks.postprocess_schema_enums", + "cms.lib.spectacular.cms_mark_superseded_paths", + "cms.lib.spectacular.cms_mark_migrated_paths", + "openedx.core.apidocs.untag_deprecated_operations", + ] + def test_the_default_enum_hook_is_kept_alongside_the_new_one(self): """Setting the key replaces drf-spectacular's default list, so it is restated.""" assert "drf_spectacular.hooks.postprocess_schema_enums" in settings.SPECTACULAR_SETTINGS["POSTPROCESSING_HOOKS"] @@ -187,37 +191,6 @@ def test_environments_do_not_replace_the_common_settings(self): assert not re.search(r"_HOOKS['\"]", source), module -class SharedSchemaBehaviourTest(SimpleTestCase): - """ - Where the description this service shares with the one replacing these addresses is kept. - - Both services publish the same user addresses, so what they say about them - is held once, in a module belonging to the API being described rather than - to either service. A service reaching into the other's package for it - would tie the two together, and a copy of it here would drift from the - original the moment one of the two was corrected. - """ - - #: The module holding what the two services say the same way. - SHARED_MODULE = "openedx/core/djangoapps/user_api/schema.py" - - @staticmethod - def _source(module): - return (Path(__file__).resolve().parents[3] / module).read_text() - - def test_the_shared_description_is_read_from_the_api_it_describes(self): - assert SupersededUserOperations.__module__ == "openedx.core.djangoapps.user_api.schema" - assert SupersededUserOperations in CmsAutoSchema.__mro__ - - def test_the_shared_module_reads_no_part_of_either_service(self): - found = re.findall(r"(?m)^\s*(?:from|import) (?:lms|cms)\b", self._source(self.SHARED_MODULE)) - assert found == [] - - def test_the_schema_helpers_of_this_service_read_no_part_of_the_other(self): - found = re.findall(r"(?m)^\s*(?:from|import) lms\b", self._source("cms/lib/spectacular.py")) - assert found == [] - - class _EmptySerializer(serializers.Serializer): # pylint: disable=abstract-method pass @@ -239,6 +212,9 @@ def test_is_the_default_schema_class(self): """Views without their own ``schema`` pick this up via REST_FRAMEWORK settings.""" assert api_settings.DEFAULT_SCHEMA_CLASS is CmsAutoSchema + def test_every_operation_is_described_by_this_class_alone(self): + assert CmsAutoSchema.__bases__ == (AutoSchema,) + def test_only_the_colliding_legacy_address_is_suffixed(self): patterns = [ url_path("api/contentstore/v3/home/", _HomeViewSet.as_view({"get": "list"})), @@ -256,36 +232,6 @@ def test_only_the_colliding_legacy_address_is_suffixed(self): assert ids["/api/contentstore/v4/home/courses/"] == "v4_home_courses_list" -#: What each superseded user operation this service serves is expected to -#: exchange: the media types of the body it reads, and the success code with -#: the body it answers with. ``None`` is a response carrying no body at all. -#: -#: The table is spelled out here rather than taken from the tests of the -#: service that serves the replacements, so that a change made to what one of -#: the two documents says about these addresses and not to the other is a -#: failure here rather than a difference a client only finds after generating -#: from both. -SUPERSEDED_USER_EXCHANGES = { - ("/api/user/v1/accounts", "get"): ([], {"200": "Account[]"}), - ("/api/user/v1/accounts/{username}", "get"): ([], {"200": "Account"}), - ("/api/user/v1/accounts/{username}", "patch"): (["application/merge-patch+json"], {"200": "Account"}), - ("/api/user/v1/accounts/search_emails", "post"): ( - ["application/json", "application/merge-patch+json"], {"200": "EmailSearchResult[]"}, - ), - ("/api/user/v1/accounts/{username}/deactivate/", "post"): ([], {"200": "Account"}), - ("/api/user/v1/accounts/name_change/", "post"): ( - ["application/json", "application/x-www-form-urlencoded", "multipart/form-data"], - {"201": None}, - ), - ("/api/user/v1/accounts/name_change/{username}/confirm/", "post"): ([], {"204": None}), - ("/api/user/v1/accounts/{username}/image", "post"): ( - ["image/gif", "image/jpeg", "image/pjpeg", "image/png", "multipart/form-data"], - {"204": None}, - ), - ("/api/user/v1/accounts/{username}/image", "delete"): ([], {"204": None}), - ("/api/user/v1/accounts/{username}/verification_status/", "get"): ([], {"200": "VerificationStatus"}), -} - #: Every operation of a superseded user address this service serves, with the #: name it is published under. The names are the ones both documents have #: always carried: a client imports a function per name, so an operation that @@ -317,36 +263,18 @@ def test_only_the_colliding_legacy_address_is_suffixed(self): } -def _named_body(response): - """ - Return what a response carries: the component it names, or the shape itself. - - A component is named by its own name, suffixed ``[]`` where the body is an - array of it; a body described in place comes back as that description, and - a response with no body at all as ``None``. - """ - content = response.get("content") - if not content: - return None - body = content["application/json"]["schema"] - if body.get("type") == "array": - return f"{body['items']['$ref'].rsplit('/', 1)[-1]}[]" - if "$ref" not in body: - return body - return body["$ref"].rsplit("/", 1)[-1] +#: The user addresses this service marks superseded. +SUPERSEDED_USER_ADDRESSES = tuple(path for path in SUPERSEDED_PATHS if path.startswith("/api/user/")) class SupersededUserOperationTest(DjangoTestCase): """ - The user addresses this service serves beside the service that replaces them. + The user addresses this service serves beside the LMS, which serves their replacements. Both services mount that API at the same addresses and both publish an - unauthenticated document of everything they serve, so what one of those - documents says about an address is what the other has to say too: the same - body on each side of the exchange, the same success code, the same - published name, and the same mark saying a replacement exists. A client - generated from this service's document would otherwise offer a different - signature, and no mark, for the very same request. + unauthenticated document of everything they serve. This one marks the + addresses it lists as superseded and keeps the name each operation is + published under. """ @classmethod @@ -362,18 +290,15 @@ def setUpClass(cls): cls.schema = SchemaGenerator(patterns=patterns).get_schema(request=None, public=True) def _operations(self): - """Every operation of a superseded address this document carries.""" + """Every operation of the user addresses that have a replacement, as this document carries it.""" return { - (path, method): operation - for path in SUPERSEDED_USER_PATHS if path in self.schema["paths"] - for method, operation in self.schema["paths"][path].items() - if isinstance(operation, dict) and "operationId" in operation + (address, method): self.schema["paths"][address][method] + for address, method in SUPERSEDED_USER_OPERATION_IDS } - def test_this_service_serves_every_superseded_address(self): - """The marking and the bodies below are claims about all of them, not about some.""" - served = [path for path in SUPERSEDED_USER_PATHS if path in self.schema["paths"]] - assert served == list(SUPERSEDED_USER_PATHS) + def test_this_service_serves_every_address_it_marks(self): + """The mark is matched on the exact address, so one this document spells otherwise is never marked.""" + assert [address for address in SUPERSEDED_USER_ADDRESSES if address not in self.schema["paths"]] == [] def test_every_operation_of_those_addresses_is_marked_superseded(self): marked = {key: operation.get("deprecated") for key, operation in self._operations().items()} @@ -382,26 +307,3 @@ def test_every_operation_of_those_addresses_is_marked_superseded(self): def test_every_operation_keeps_the_name_it_is_published_under(self): published = {key: operation["operationId"] for key, operation in self._operations().items()} assert published == SUPERSEDED_USER_OPERATION_IDS - - def test_each_superseded_operation_publishes_what_it_reads_and_what_it_answers_with(self): - published = {} - for (address, method) in SUPERSEDED_USER_EXCHANGES: - operation = self.schema["paths"][address][method] - published[(address, method)] = ( - sorted((operation.get("requestBody") or {}).get("content", {})), - {code: _named_body(response) for code, response in operation["responses"].items()}, - ) - assert published == SUPERSEDED_USER_EXCHANGES - - def test_an_image_may_be_sent_as_the_whole_body_or_as_a_form_part(self): - """The forms are alternatives, and a body one of them needs is one the operation needs.""" - image = self.schema["paths"]["/api/user/v1/accounts/{username}/image"]["post"]["requestBody"] - assert image["required"] is True - assert sorted(image["content"]) == [ - "image/gif", "image/jpeg", "image/pjpeg", "image/png", "multipart/form-data", - ] - - def test_the_described_addresses_are_ones_this_document_marks_superseded(self): - described = {address for address, _method in superseded_bodies()} - marked = {re.sub(r"\{[\w-]+\}", "{}", address) for address in SUPERSEDED_USER_PATHS} - assert described <= marked, described - marked diff --git a/openedx/core/djangoapps/user_api/schema.py b/openedx/core/djangoapps/user_api/schema.py index 0019a2789109..3fa0e0fa9396 100644 --- a/openedx/core/djangoapps/user_api/schema.py +++ b/openedx/core/djangoapps/user_api/schema.py @@ -135,7 +135,7 @@ def superseded_bodies(): class SupersededUserOperations: """ - Describe the superseded user addresses the same way in both services' documents. + Describe each superseded user address by what it reads and answers with, under the name it keeps. Ids not named in ``RENAMED_OPERATION_IDS`` stay as the generator derives them. """ diff --git a/openedx/core/tests/test_apidocs.py b/openedx/core/tests/test_apidocs.py index 479dfa03e6fe..20a1a549bad5 100644 --- a/openedx/core/tests/test_apidocs.py +++ b/openedx/core/tests/test_apidocs.py @@ -57,7 +57,6 @@ def test_the_hook_runs_last(self): assert source.index(marking_hook) < source.index(HOOK), module def test_the_hook_runs_after_the_hook_marking_the_superseded_user_addresses(self): - for module in self.MARKING_HOOKS: - source = (REPO_ROOT / module).read_text() - assert self.SHARED_HOOK in source, module - assert source.index(self.SHARED_HOOK) < source.index(HOOK), module + source = (REPO_ROOT / "lms/envs/common.py").read_text() + assert self.SHARED_HOOK in source + assert source.index(self.SHARED_HOOK) < source.index(HOOK) From ff4e95181bb4ad1685dc954174135ccc10774695 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Wed, 4 Nov 2026 20:07:03 +0500 Subject: [PATCH 60/61] refactor: import the replacing serializers where lint-imports can see them The table of superseded bodies picked up the v2 user serializers by name. Those serializers import LMS models, so while Studio's schema module used this table, every Studio schema generation reached LMS code through an import the "lms and cms are independent" contract could not see. Studio no longer reads this module, so the import is now an ordinary one inside the function that needs loaded models. lint-imports keeps all four contracts. Planting the old Studio import of this module makes the contract fail and name the chain through this line, where the by-name import let it pass. Co-Authored-By: Claude Opus 5.5 --- openedx/core/djangoapps/user_api/schema.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/openedx/core/djangoapps/user_api/schema.py b/openedx/core/djangoapps/user_api/schema.py index 3fa0e0fa9396..e19207383965 100644 --- a/openedx/core/djangoapps/user_api/schema.py +++ b/openedx/core/djangoapps/user_api/schema.py @@ -3,7 +3,6 @@ import re from collections import namedtuple from functools import cache -from importlib import import_module from drf_spectacular.utils import OpenApiResponse from rest_framework.parsers import FormParser, JSONParser, MultiPartParser @@ -71,14 +70,12 @@ def superseded_bodies(): of the same shape; a request by the members the v1 handler reads, without the v2 bounds, under the media types that handler reads; ``None`` reads no body. """ - # Imported here because the serializers need loaded models; the v2 user - # serializers reach single-service models, so they are imported by name. + # Imported here because the serializers need loaded models. # pylint: disable=import-outside-toplevel from openedx.core.djangoapps.profile_images.v2.serializers import IMAGE_UPLOAD_REQUEST + from openedx.core.djangoapps.user_api.v2 import serializers as replacing from openedx.core.lib.api.parsers import MergePatchParser - replacing = import_module("openedx.core.djangoapps.user_api.v2.serializers") - account = {200: replacing.AccountSerializer} account_change = { "type": "object", From 45b7d175d3517a2351fa51f9f78b5eddba510030 Mon Sep 17 00:00:00 2001 From: Abdul-Muqadim-Arbisoft Date: Thu, 5 Nov 2026 01:06:58 +0500 Subject: [PATCH 61/61] fix: name each refused item of a list body in words A body carrying a list is refused item by item, and DRF reports that as one entry per item, each holding its own messages. The shared envelope's normalizer prints any nested value with str(), so both `errors` and the one-line `detail` carried Python's repr: an account change sent {"social_links": [{"platform": "facebook"}]} answered "social_links: {'social_link': [ErrorDetail(string='This field is required.', code='required')]}", and the item at fault could only be found by parsing that text. ReadableErrorDetailMixin now lists each refused item under a name of its own before the envelope is built: `social_links[0].social_link` for a property of one object in a list, `name[1]` for an item of a list, the object's own name for a refusal of the object as a whole. A refusal naming only parameters or properties is left as it was. The cause is the library's normalize_validation_errors; once the library names nested items itself this step can go. The account test that pinned the printed form now pins the item-named entry and the sentence. A test of the mixin through a stub view covers each branch: a property inside a list item, a list of objects, a refusal of an object as a whole, and the two refusals left unchanged. Co-Authored-By: Claude Opus 5.5 --- openedx/core/djangoapps/user_api/v2/errors.py | 59 ++++++++++++++++++- .../user_api/v2/tests/test_account_views.py | 8 +-- .../user_api/v2/tests/test_errors.py | 58 ++++++++++++++++++ 3 files changed, 118 insertions(+), 7 deletions(-) create mode 100644 openedx/core/djangoapps/user_api/v2/tests/test_errors.py diff --git a/openedx/core/djangoapps/user_api/v2/errors.py b/openedx/core/djangoapps/user_api/v2/errors.py index 83bd7b5b41e0..01e3e0ab4cef 100644 --- a/openedx/core/djangoapps/user_api/v2/errors.py +++ b/openedx/core/djangoapps/user_api/v2/errors.py @@ -51,6 +51,53 @@ def refusal_sentence(refusals): ) +def _holds_a_structure(value): + """Whether a refusal's value is a mapping, or a list holding anything but messages.""" + return isinstance(value, dict) or ( + isinstance(value, list) and any(isinstance(item, (dict, list)) for item in value) + ) + + +def _refusals_by_item(detail, name): + """ + Yield each message of a refusal with the name of the thing it is about. + + An item of a list is named after its position, counted from 0, and a + property of an object after the property: ``social_links[0]``, + ``social_links[0].social_link``. A refusal of an object as a whole keeps the + object's name. + """ + if isinstance(detail, dict): + for key, inner in detail.items(): + if isinstance(key, int): + yield from _refusals_by_item(inner, f"{name}[{key}]") + elif key == api_settings.NON_FIELD_ERRORS_KEY: + yield from _refusals_by_item(inner, name) + else: + yield from _refusals_by_item(inner, f"{name}.{key}") + elif _holds_a_structure(detail): + for index, inner in enumerate(detail): + yield from _refusals_by_item(inner, f"{name}[{index}]") + else: + yield from ((name, message) for message in (detail if isinstance(detail, list) else [detail])) + + +def _named_by_item(detail): + """ + Return a refusal with each refused item of a list listed under a name of its own. + + Nothing changes for a refusal naming only parameters or properties; one + that names nothing in particular is never nested. + """ + if not isinstance(detail, dict) or not any(_holds_a_structure(value) for value in detail.values()): + return detail + named = {} + for field, refusal in detail.items(): + for name, message in _refusals_by_item(refusal, field): + named.setdefault(name, []).append(message) + return named + + class ReadableErrorDetailMixin: """ Writes the one-line message of a refused request as a sentence. @@ -61,12 +108,20 @@ class ReadableErrorDetailMixin: Everything that puts the line in front of a person then shows the brackets, the quoting and the class names that write a data structure out: the message of the exception a generated client raises, a line in an - integration's log, the notification a page puts on the screen. The list is - left exactly as it was; only the line is rewritten, from the same values. + integration's log, the notification a page puts on the screen. The line is + rewritten from the values in the list. + + A list a body carries is refused item by item, which the standard body + would print, positions and class names included, as one message under the + list's name. Each refused item is listed under a name of its own instead + -- ``social_links[0].social_link`` -- so that the list and the line both say in words + which item was refused and why. """ def handle_exception(self, exc): """Answer with the standard body, its one-line message written in words.""" + if isinstance(exc, ValidationError): + exc.detail = _named_by_item(exc.detail) response = super().handle_exception(exc) body = getattr(response, "data", None) if isinstance(body, dict) and isinstance(body.get("errors"), dict): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py index 8deaae27e3db..e8786e95f71b 100644 --- a/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py +++ b/openedx/core/djangoapps/user_api/v2/tests/test_account_views.py @@ -1455,11 +1455,9 @@ def test_an_incomplete_object_inside_the_body_is_refused(self): envelope = assert_error_envelope( response, expected_status=status.HTTP_400_BAD_REQUEST, expected_type_slug="validation", ) - # The envelope carries one line per property, so a refusal from inside a - # list arrives as the text of the refusal rather than as its own object. - assert list(envelope["errors"]) == ["social_links"] - assert "social_link" in envelope["errors"]["social_links"][0] - assert "This field is required." in envelope["errors"]["social_links"][0] + # A refusal from inside a list is listed under the item it is about. + assert envelope["errors"] == {"social_links[0].social_link": ["This field is required."]} + assert envelope["detail"] == "social_links[0].social_link: This field is required." assert self.owner.profile.social_links.count() == 0 def test_an_empty_address_still_drops_a_platform(self): diff --git a/openedx/core/djangoapps/user_api/v2/tests/test_errors.py b/openedx/core/djangoapps/user_api/v2/tests/test_errors.py new file mode 100644 index 000000000000..96672c81280b --- /dev/null +++ b/openedx/core/djangoapps/user_api/v2/tests/test_errors.py @@ -0,0 +1,58 @@ +"""Tests for the error bodies this version of the User API writes.""" + +from django.test import SimpleTestCase +from edx_rest_framework_extensions.mixins import StandardizedErrorMixin +from rest_framework.exceptions import ValidationError +from rest_framework.permissions import AllowAny +from rest_framework.test import APIRequestFactory +from rest_framework.views import APIView + +from openedx.core.djangoapps.user_api.v2.errors import ReadableErrorDetailMixin + + +class _RefusingView(StandardizedErrorMixin, ReadableErrorDetailMixin, APIView): + """Refuses every request with the refusal it is built with.""" + + permission_classes = (AllowAny,) + refusal = None + + def post(self, request): # pylint: disable=unused-argument + raise ValidationError(self.refusal) + + +def _refused(refusal): + """Return the body a view refusing a request this way answers with.""" + view = _RefusingView.as_view(refusal=refusal) + return view(APIRequestFactory().post("/refused/", {}, format="json")).data + + +class NestedRefusalTests(SimpleTestCase): + """A refusal of one item of a list, however deep, is listed under the name of that item.""" + + def test_a_property_of_one_object_in_a_list_is_named_by_position_and_property(self): + body = _refused({"username_mappings": {1: {"c": ["Not a name."]}, 0: ["Names several."]}}) + assert body["errors"] == { + "username_mappings[1].c": ["Not a name."], + "username_mappings[0]": ["Names several."], + } + assert body["detail"] == "username_mappings[1].c: Not a name. username_mappings[0]: Names several." + + def test_a_list_of_objects_names_only_the_objects_refused(self): + body = _refused({"items": [{}, {"name": ["This field is required."]}]}) + assert body["errors"] == {"items[1].name": ["This field is required."]} + assert body["detail"] == "items[1].name: This field is required." + + def test_a_refusal_of_an_object_as_a_whole_keeps_the_name_of_the_object(self): + body = _refused({"profile": {"non_field_errors": ["The two values disagree."]}, "items": {0: "Not text."}}) + assert body["errors"] == {"profile": ["The two values disagree."], "items[0]": ["Not text."]} + assert body["detail"] == "profile: The two values disagree. items[0]: Not text." + + def test_a_refusal_naming_only_parameters_is_left_as_it_was(self): + body = _refused({"limit": ["Not a whole number."], "non_field_errors": ["Nothing was changed."]}) + assert body["errors"] == {"limit": ["Not a whole number."], "non_field_errors": ["Nothing was changed."]} + assert body["detail"] == "limit: Not a whole number. Nothing was changed." + + def test_a_refusal_naming_nothing_in_particular_is_left_as_it_was(self): + body = _refused(["Nothing may be sent here."]) + assert body["errors"] == {"non_field_errors": ["Nothing may be sent here."]} + assert body["detail"] == "Nothing may be sent here."