Repository navigation
feat: standardize the user preferences and email opt-in API - #39314
Abdul-Muqadim-Arbisoft wants to merge 79 commits into
Conversation
Reference detail for this pull requestThe description is over GitHub's 65,536-character limit, so these five reference sections live here.
C1 — Caller-visible changes, the complete enumeration
Cross-cutting (all six operations)
|
| documents compared | result |
|---|---|
LMS document, origin/master → this branch |
PASS (0 BREAKING, 4 WARN, 47 INFO); 19 paths to 56 |
| LMS document, branch parent → this branch | PASS (0 BREAKING, 0 WARN, 12 INFO); every finding reads operation added — the six conforming operations and the six superseded ones |
| service-wide document, branch parent → this branch | FAIL (2 BREAKING, 0 WARN, 12 INFO); 509 paths to 512 |
service-wide document, origin/master → this branch |
FAIL (7 BREAKING, 2 WARN, 47 INFO); five of the seven belong to phase B (name_change POST, confirm POST, search_emails POST, image POST twice) and are declared in #39297 |
The two findings this phase owns correct the document; they do not change behaviour. In the
service-wide document, PATCH /api/user/v1/preferences/{username} and
PUT /api/user/v1/preferences/{username}/{preference_key} were published with a bodiless 200.
Both handlers answer 204, and always have (preferences/views.py:146 and :249 — untouched by
this diff, and asserted from both sides by
test_the_same_merge_patch_leaves_both_versions_storing_the_same_rows and
test_the_value_sent_is_stored_by_both_versions). Publishing what they really answer removes a
200 they never sent, which schema_diff.py compare reads as a removed response code. No address,
operationId, tag or component is renamed or dropped.
Exactly six existing operations change in that document, and this is all of it — read operation
by operation, parent against branch:
| operation | before | after |
|---|---|---|
GET /api/user/v1/preferences/{username} |
200, no body described |
deprecated: true; the 200 described as the preference document |
PATCH /api/user/v1/preferences/{username} |
200, no body described |
deprecated: true; a merge-patch request body; 204 |
GET …/{preference_key} |
200, no body described |
deprecated: true; the 200 described as the stored text |
PUT …/{preference_key} |
200, no body described |
deprecated: true; a JSON request body; 204 |
DELETE …/{preference_key} |
204 |
deprecated: true, and nothing else |
POST /api/user/v1/preferences/email_opt_in/ |
200, no body described |
deprecated: true; a form request body; the 200 kept, because that handler really answers 200 |
The unversioned twin POST /user_api/v1/preferences/email_opt_in/ is identical on both sides: no
request body, a bodiless 200, not deprecated. SupersededBodyInTheServiceWideDocumentTest pins
all three of those facts in the document that publishes them, and the mutation that publishes a
200 for a change answering nothing turns four tests red across both documents.
C3 — Follow-ups
Library-first — the three items Phase B named, plus two this phase leans on
flatten_detail (an ErrorDetail repr reaching clients), the missing
OpenApiAuthenticationExtension/security block for the platform's auth classes, and a DRF 3.17.2
parser RecursionError. None is patched locally; the superseded addresses answer the same way.
Two more, both carried by this phase rather than worked around:
IsActiveUser(user_api/v2/permissions.py) is a four-line permission class admitting a
caller whose own account is still active.edx-drf-extensions10.9.0 ships no equivalent —
neither the authenticated check nor the administrator check readsis_active— Its history across these
phases: the class arrives in Phase A, becomes load-bearing in Phase B, which already composes
(IsStaff & IsActiveUser)on the two ID-verification reads (views.py:1467,:1549), and is
carried forward unchanged here, where the same composition stops a deactivated administrator's
token from reading another account's preferences. This phase is not the first to rely on it;
feat: standardize the user accounts, profile image, verification and name-change API #39297's own library-first list omits it, which is the inventory error, not a change in status. It belongs in the
library beside the permission primitives it ships; it is declared here because no release carries
it yet,
and the local class is deleted in favour of the library's the release after one lands. It is
not a local copy of anything: there is nothing to copy.- A serializer field as a request or response body. drf-spectacular 0.30.0 maps a bare
serializer field only inside a serializer or a list wrapper:_get_request_for_media_typeand
_get_response_for_codehave no field branch, so handing one of theseDictFields to
OpenApiResponseor to a media-type map publishes{"type": "object", "additionalProperties": {}}
withdescription: Unspecified response bodyand emitscould not resolve …(measured on this
tree). The open-ended preference document is therefore published through the raw-schema mechanism
the generator does support, attached to the field that carries it with@extend_schema_field, and
the two are held together by tests rather than by the generator (C1 item 35). A field branch in
those two functions is the upstream change that would let the declaration be the field alone.
Next-version candidates (ADR 0037)
- A read of the email opt-in (
GET /email_opt_ins/{org}/), and addressing the choice by organization
directly instead of deriving it from a course key. This phase standardizes what exists; neither is
an operation the superseded surface offers. - Moving the language-cookie-to-preference sync off the read path, so no read of any LMS address
writes, announces a field change or emits an analytics event. All three travel together: the
middleware stores the caller'spref-langrow, and that row'spost_savesends
USER_FIELDS_CHANGEDand emits oneedx.user.settings.changedevent. The signal's one in-repo
LMS receiver isuser_authn.signals.user_fields_changed(registered as a plugin signal receiver in
user_authn/apps.py), which callssegment.identifyfor the caller — a no-op where no Segment key
is configured, an identify call per read where one is. So the change is worth more than one row: it
is a write, a signal and an event, with one receiver acting on the signal today. It is a platform
change inlang_prefmiddleware, not an API change, and it is what would let this area claim 0030
with no declared write at all. Both versions of these addresses behave identically until it lands. - A bounded read of an account's own preference rows. The row-shaped, paginated view of the same
table in this version is administrator-only, so the holder of a document reads it whole or one name
at a time, and a client that wants a handful of names makes one request per name. An owner-readable
page of those rows, or afields-style selection over the document, would give them one bounded
request; neither exists on the superseded surface either, which is why this phase adds neither. - A way to address a preference name that carries a slash. The model's key validator is applied
unanchored, soa/b,x/,/xanda//bare names a preference is really stored under, and the
document of this version stores, reads and removes them. The member address reads a name from one
path segment and a segment ends at a slash, so no member address for such a name exists at
either version: both answer the request as an unknown address, in the raw and the
percent-encoded spelling alike. Widening the segment is not the fix — it would swallow the
trailing slash and every address below it — so reaching them needs a sub-resource that carries an
encoded name, or afields-style selection over the document. Pinned as it stands by
test_a_name_carrying_a_slash_is_not_addressed_as_a_preferenceand
test_a_name_carrying_a_slash_is_stored_read_and_removed_through_the_document. - An ORM-backed, scoped selector for one account's preferences (the seam named in §10 and C5).
Risks recorded, no decision needed
- The document is unbounded. Its size is set by how many preferences the addressed account itself
stores (measured: 11–281 bytes for 1–25 names, at a constant query count). No cap is introduced: a
cap would refuse an account whose own plugins store many names, and the superseded address has none.
The row-shaped view of the same table atGET /api/user/v2/user_preferences/is
administrator-only, so it is not a bounded alternative for the account holder; an
owner-readable page of the same rows is recorded as a next-version candidate above. - Studio keeps calling v1.
/api/user/v2/is LMS-only, as in Phase B;cms/urls.pymounts the v1
package and the Studio header reversespreferences_api. No Studio client is asked to move. - No client in this repository is migrated.
common/static/js/src/lang_edx.js,
lms/static/js/student_account/emailoptin.js, the two header templates and the i18n test keep
calling v1, which is untouched.
SDK
All six operations carry tags: ["openedx-platform-sdk"], as Phase B's eleven do, so a generated
client exposes an account's preferences and the opt-in beside its account operations. Note C1 item 28:
the read of one preference is named for what it reads rather than told apart by a numeral.
C4 — The compliance matrix's evidence column, and the test inventory
One row per decision, keyed to §5 of the description. Nothing was dropped on the way here.
| Decision | Evidence (test / gate) |
|---|---|
| 0025 serializers | PreferenceDocumentTests (23), PreferenceMemberTests (22), EmailOptInViewTests (28); test_the_preference_document_is_published_as_the_open_ended_object_it_is; test_a_preference_document_the_endpoint_answers_is_what_the_document_describes; test_a_merge_patch_the_endpoint_carries_out_is_one_the_request_body_takes (a null and a text value both validate against the published request body, a number does not, and the endpoint then answers 204 to the null); test_the_preference_document_is_published_as_the_fields_that_carry_it_describe; mutations: email_opt_in declared as text → 20 failures; the nullable member dropped → 2 red; the shape detached from the changes field → 1 red; the field's ordering removed → 2 red; the field reading a value as text only → 2 red; the empty value refused by the field instead of the service → 2 red; each of the three refusals removed → red; the strict reading of the choice removed → 2 red; the required-choice guard for form bodies removed → 2 red; the organization-length refusal removed → 1 red (204 with a 300-character organization) |
| 0026 permissions | §10; PreferenceAccessTests (18), PreferenceGuardTests (5), EmailOptInAccessTests (6); mutations: IsActiveUser made a no-op → red; the administrator half added to the writes → red; the read constant emptied → red; the address comparison relaxed → red (twice: at the declaration and at HTTP) |
| 0027 schema / docs | test_the_preference_operations_carry_the_names_they_are_published_under; test_no_preference_operation_publishes_a_parameter_beyond_the_address_it_is_read_from; test_the_email_choice_publishes_the_body_it_reads_and_that_it_answers_with_nothing; test_the_email_choice_publishes_the_refusal_a_session_is_answered_with_without_its_token (drives the refusal and matches the code and the published text against it; mutation: the published 403 removed -> 2 red); test_each_superseded_body_is_published_in_the_media_types_that_address_reads; test_schema.py 75 passed, including test_each_preference_operation_publishes_the_answers_it_can_give (the five answer sets literally, so a published status no handler can answer fails here) and test_the_name_a_preference_is_stored_under_is_published_under_one_parameter_name (the path parameters of both member addresses are exactly {username, key}; mutation: the parameter renamed → 3 red) |
| 0028 viewsets | test_the_preference_viewset_serves_both_of_its_addresses; test_addresses_resolve_to_the_version_two_viewsets (both addresses resolve to the one viewset with the method sets above); test_the_preference_document_is_published_as_the_open_ended_object_it_is |
| 0029 errors | assert_error_envelope on every refusal (400 validation ×17, 401, 403, 404, 405, 415, malformed-body, 500); PreferenceServiceFailureTests (6, one of them a real DatabaseError, two of them a change that fails part way through); test_a_name_that_cannot_be_encoded_is_refused_against_the_body and test_a_value_that_cannot_be_encoded_is_refused_under_the_name_that_carried_it, each asserting the answer is application/json — the superseded address answers 500 text/html for the same body; mutations: each refusal removed → red |
| 0030 GET idempotence | PreferenceReadsWithoutTheLanguageCookieTests (10) and PreferenceReadsWithTheLanguageCookieTests (14) — one fixture class per side, covering the value that is there, the name that is not, the account that is not, and (with the cookie) the four cases where the row the middleware writes is the one being removed; plants, each measured in the round that added the capture it defeats, over the two preference modules as they then stood — now 112 and 25 tests: a SQL write in the document read → 21 failures; the language cookie removed from the fixture → 10 failures (the whole class); an announcement with no SQL behind it planted in the document read → 9 failures and in the member read → 9; an analytics event alone planted in the document read → 9 failures; a domain write on the member read's "no such name" branch → 3 failures, where the same plant left all 111 tests green before this round; a domain write on the "no such account" branch → 1 failure |
| 0031 merged endpoints | test_a_name_that_is_a_collection_of_this_version_is_read_as_a_preference_name; EmailOptInParityTests (8); test_no_superseded_preference_address_announces_its_own_removal |
| 0032 pagination | test_the_document_carries_no_pages; the row view's own deny tests, unchanged by this phase: test_a_learners_token_is_forbidden_on_every_staff_gated_address and test_the_owner_of_the_record_is_still_not_staff (v2/tests/test_views.py, where the owner of the row is refused 403 at it) |
| 0033 filtering | test_the_names_come_back_in_one_order_whatever_order_they_were_stored_in and test_the_order_the_names_come_back_in_is_the_code_of_each_character (the order is asserted as the list ["9nine", "Beta", "Zeta", "_under", "alpha"], which a sort that ignored letter case would not produce; mutation: order reversed → red); PreferenceQueryParameterTests (4) |
| 0034 authentication | test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaults in four modules (test_preference_views.py, test_account_views.py, test_email_opt_in_views.py, profile_images/v2/tests/test_views.py): each asserts the request succeeded and produced its real answer, that the attribute was not recorded, and that a second request in the same test to a sibling address on the defaults was recorded, so the assertion cannot pass against a mistyped patch target; test_urls.py::test_the_views_reached_before_an_address_is_confirmed_replace_one_class pins the tuple of all four views and keeps the tie to configuration with issubclass(platform_token, JwtAuthentication); test_an_account_with_an_unconfirmed_address_reads_and_changes_its_own_preferences; test_an_account_with_an_unconfirmed_address_records_a_choice; mutations: the monitoring subclass restored in each of the four views in turn → the view's own pin red, its neighbour's green (1 failed, 1 passed ×4), and the declaration pin red on its own; either declaration removed → red |
| 0035 MFE config | — |
| 0036 nested JSON | test_no_preference_address_shapes_what_it_answers_with |
| 0037 versioning | versions gate PASS twice (--base origin/master: added in old dirs: 0; --base Phase B's head with the six allowed globs); 18 protected paths re-verified per path (git diff --numstat + git ls-files --others): 0 changed lines, 0 untracked |
| 0038 URL structure | test_urls.py 46 passed: reverse() literals for the three new names and all four legacy ones, same-view resolution for the twin, the catch-all not swallowing either address, me routed as a stored name, every key shape a segment can carry addressable, and a name carrying a slash answered by the fallback instead, in four shapes and two spellings (test_a_name_carrying_a_slash_is_not_addressed_as_a_preference, test_a_name_carrying_a_slash_is_stored_read_and_removed_through_the_document; mutations: the key pattern widened to .+ → both red, and widened to [^/]+/? — which the single-shape version of these tests would have passed → both red on the x/ shape) |
| OEP-66 scoping | PreferenceAccessTests; test_a_null_removes_the_name_from_the_account_that_was_addressed |
| OEP-69 conventions | test_urls.py, test_schema.py, test_preference_views.py |
Test inventory
Counted from the tree; the collected counts are the gate run's own
(gates-phase-c-final.txt, tests gate, 1118 items).
| module | classes and counts |
|---|---|
user_api/v2/tests/test_preference_views.py (112) |
PreferenceDocumentTests 23, PreferenceMemberTests 22, PreferenceAccessTests 18, PreferenceReadsWithTheLanguageCookieTests 14, PreferenceReadsWithoutTheLanguageCookieTests 10, PreferenceServiceFailureTests 6, PreferenceGuardTests 5, PreferenceRefusedWithNothingBehindThemTests 5, PreferenceAddressedByMeTests 5, PreferenceQueryParameterTests 4 |
user_api/v2/tests/test_preference_parity.py (25) |
PreferenceDocumentParityTests 8, PreferenceRefusalParityTests 8, PreferenceMemberParityTests 7, SupersededAddressAnnouncementTests 2 |
user_api/v2/tests/test_email_opt_in_views.py (44) |
EmailOptInViewTests 28, EmailOptInParityTests 10, EmailOptInAccessTests 6 |
user_api/v2/tests/test_schema.py (75) |
module-level, including the preference operations' published parameters, answers, bodies and names |
user_api/v2/tests/test_urls.py (46) |
UrlLiteralTests 21, MalformedAddressTests 12, LegacyAddressTests 9, RouteShapeTests 4 |
profile_images/v2/tests/test_views.py (51) |
#39297's module; one authentication pin rewritten here |
| whole selection | 1118 passed; user_api/v2/ alone 920, profile_images/ 124, user_api/tests/ + user_api/preferences/tests/ 193 |
The last two review passes added fifteen tests and renamed five. New in
test_preference_views.py: test_the_order_the_names_come_back_in_is_the_code_of_each_character;
test_a_name_nothing_can_be_stored_under_is_refused_under_that_part_too;
test_the_names_this_address_refuses_are_the_ones_the_store_refuses;
test_an_administrator_asking_what_another_accounts_addresses_answer_is_told;
test_the_addressed_account_is_told_what_a_change_at_their_own_address_carries;
test_a_learner_asking_what_another_accounts_addresses_answer_is_refused;
test_an_anonymous_caller_asking_what_these_addresses_answer_is_refused;
test_asking_what_an_address_answers_is_guarded_as_a_read_of_it;
test_removing_the_language_removes_the_row_the_middleware_had_just_stored;
test_the_document_removing_the_language_leaves_it_removed_as_well;
test_removing_another_name_stores_the_language_the_cookie_carries;
test_a_name_stored_only_by_the_middleware_is_removed_rather_than_reported_absent. New in
test_schema.py: test_the_name_a_preference_is_stored_under_is_published_under_one_parameter_name;
test_each_preference_operation_publishes_the_answers_it_can_give. New in
test_email_opt_in_views.py: an authentication pin for EmailOptInViewSet, which had none.
The review pass before them added five more, named here because the counts above include them:
EmailOptInViewTests.test_the_row_a_refusal_opened_stands_where_a_statement_stands_on_its_own and
EmailOptInParityTests.test_neither_address_records_a_choice_for_an_account_carrying_no_profile
(what a refused choice leaves behind, on each side of the request transaction, at both addresses);
PreferenceAccessTests.test_a_session_without_the_token_that_goes_with_it_is_refused_every_change
(the three preference writes, which had no such test);
RouteShapeTests.test_every_pattern_is_anchored_where_the_mount_leaves_off and
MalformedAddressTests.test_an_address_merely_ending_in_one_this_version_serves_is_not_found (every
pattern of this version is anchored where the mount leaves off, so an address merely ending in one
it serves is not found).
Renamed, because each now asserts something else:
test_the_actions_an_administrator_may_call_against_another_account_are_the_two_reads (was named for
the permission objects rather than for what they admit), and
test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaults in four modules
(test_preference_views.py, test_account_views.py, test_email_opt_in_views.py,
profile_images/v2/tests/test_views.py), each of which previously asserted the opposite of what the
code now does. test_urls.py::test_the_views_reached_before_an_address_is_confirmed_replace_one_class
covers all four views rather than two.
Each of those four pins is built so that it cannot pass vacuously: the request under test must
succeed and produce its real answer (so a token demonstrably authenticated it), and a second
request in the same test — GET /api/user/v2/user_preferences/ with an administrator's token,
served by a viewset that declares no classes of its own — must record the attribute, which is what
proves the recorder is reachable from a request made this way at all. Without that control request,
an == [] assertion would pass against a mistyped patch target.
C5 — Authorization detail
Three layers (OEP-66)
| layer | the five preference operations | the opt-in |
|---|---|---|
| 1 endpoint access | the permission classes above | IsAuthenticated |
| 2 record visibility | the rows of the one account the address names, read through the preference service; no other account's row is reachable from these addresses | the single row (caller, org, email-optin) |
| 3 user-driven filtering | none: no parameter is read, and an unknown one is refused | none |
A future ORM-backed pass would put a selector in v2/selectors.py returning
UserPreference.objects.filter(user__username=…) and declare a scoping_policy on it; today the
account-scoped read is the model helper the whole platform shares, so duplicating it inside the view
would be the worse trade.
What the guard harnesses assert, and the me row
The me row is driven for all five operations, at both addresses. me is read as a stored
name here, so the three writes answer 403 for an administrator as well as for a learner — an
administrator is refused rather than told the name is free, because a refusal is ordered before any
account lookup — and 204 for the account that really holds the name, whose rows are the ones
changed (test_a_learner_changing_the_preferences_at_me_is_refused,
test_an_administrator_changing_them_is_refused_rather_than_told_the_name_is_free,
test_the_account_holding_that_name_is_served, which now round-trips the document patch and the
removal as well as the single write). The two reads answer 403 / 404 / 200 for the same three
callers, which is the one place the two halves differ: an administrator may read, so they reach the
lookup and are told nothing holds the name.
What the guard tests assert, and why. The preference service enforces the same
owner-or-administrator rule from behind the permission classes, so an answer produced with it in
place does not say which of the two refused a caller: relaxing IsAddressedUser, or adding the
administrator half to the writes, leaves the ordinary HTTP deny tests green. Two things cover that.
The per-action declarations are asserted directly — PreferenceGuardTests builds each action's
permission objects and checks who they admit. And PreferenceRefusedWithNothingBehindThemTests (5)
drives all five operations with the five preference service calls replaced by stand-ins that serve
whoever asks, so the classes are the only thing left that can refuse: the addressed account is
served at every address, while another learner, an administrator's three writes, a caller whose name
differs from the address only in letter case, and an administrator whose own account is no longer
active are each refused 403 with the envelope. Both mutations now go red twice, once at the
declaration and once at HTTP: a relaxed IsAddressedUser, and the administrator half added to the
writes (each 2 failed alongside the rest of the two preference modules green, measured in the pass
that added these tests). The classes remain the authorization surface (they refuse before
any handler runs, and requiring an active administrator account is a real tightening that only they
do); they are not the only thing refusing, and a future widening of theirs is visible at HTTP.
C6 — What schema generation reports, and no gate scores
- Generation emits ten new warnings, all of one kind, where the plan asked for none. Measured
on the LMS document underlms.envs.test, in one run per ref: this branch's parent (phases A and
B) emits 138 warnings / 79 unique, this branch 163 / 89, and the error count is unchanged
on both sides (36 / 6 unique). The gate's own head run reports the same163 (89 unique)and
36 (6 unique), andorigin/masterreports56 (30 unique)/28 (5 unique)for 19 paths. Every one of the ten new messages readscould not resolve authenticator <class …>. There was no OpenApiAuthenticationExtension registered for that class—
six for the three superseded views this phase publishes (PreferencesViewthree times,
PreferencesDetailViewtwice,UpdateEmailOptInPreferenceonce) and four for the two views it
adds (AccountPreferenceViewSetandEmailOptInViewSet, twice each). Replacing the monitoring
subclass with the library class in four views changed which class each warning names, not how many
there are: two per view either way. No warning disappears. The
cause is the missingOpenApiAuthenticationExtensionfor the platform's authentication classes —
the second library-first item in C3 — so until that lands, every view with a declared
authentication class costs one warning per class, whether it is being standardized or merely
published for its deprecation mark. Emitting none would mean leaving the superseded addresses out
of the document, which is how they are marked deprecated, so this misses the plan's acceptance bar
for schema generation and is recorded rather than silenced. - The generator's collision warnings go down, not up. The two reads of this resource and the
two reads of the superseded one each tokenize to one operationId; naming the read of one
preference in each pair leaves the service's own document with one collision warning
(v1_enrollment_retrieve, which master carries) and the service-wide document with the two it
already carries under/api/user/(item 28). Both pairs are pinned by tests, and both documents
were read path by path: no path, component or operationId either carried before is missing or
renamed.
Faraz32123
left a comment
There was a problem hiding this comment.
Reviewed against v1 on master. The permission mapping is right: v1's IsUserInUrlOrStaff is always truthy, so the real check is _check_authorized, and (IsStaff & IsActiveUser) | IsAddressedUser reproduces it for every caller. Bulk PATCH, null-deletes, the atomic block and the opt-in consent path are all unchanged.
Main point: CI is red. shared-with-cms-1 fails collecting test_account_views.py:44 (ACCOUNT_VISIBILITY_CONFIGURATION) and cancels the other shards, so none of the new tests have run in CI. The branch is stacked on 7f90273 and is missing #39297's 297b54f. git merge-tree shows a clean restack.
Smaller:
- 9eba272 fixes views that #39297 adds. It should live there (see my comment on #39297).
- The 0037 box is ticked, but #39128 has no entry for these six operations yet (or the promised row for
/user_api/v1/preferences/email_opt_in/). - The 0026 row says
IsAddressedUseron all six, but the opt-in only hasIsAuthenticated. That's correct for the opt-in, but the row is wrong. §10 has it right. - §2 proposes three commits but the branch has two, and d5e5c79's message doesn't list the caller-visible changes.
| return super().to_representation(dict(sorted(value.items()))) | ||
|
|
||
|
|
||
| class _PreferenceChangeField(_TextField): |
There was a problem hiding this comment.
CharField trims by default, so the value reaches the preference service already stripped. v1 runs the time_zone check on the raw value, so {"time_zone": " Asia/Tokyo"} is a 400 on v1 but stored on v2. Other keys are fine (v1's serializer trims too). Either trim_whitespace=False here and on AccountPreferenceValueSerializer.value (line 987), or declare it.
There was a problem hiding this comment.
Confirmed, and done in fix: check a preference value as it was sent, as version 1 does. Both the document's change field and AccountPreferenceValueSerializer.value have trim_whitespace=False, so the preference service sees the raw value, as it does on v1. A padded time_zone is now a 400 on both versions. Other keys are still stored trimmed, by the service, on both versions.
The parity tests are:
PreferenceDocumentParityTests::test_both_versions_check_a_time_zone_as_it_was_sentPreferenceMemberParityTests::test_both_versions_check_a_time_zone_sent_to_the_member_address_as_it_was_sent- the whitespace-only and other-value cases beside them.
| # 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) |
There was a problem hiding this comment.
The opt-in had session auth only on v1. Adding JwtAuthentication without a restricted-application guard means a third-party client's JWT, issued for something unrelated, can change marketing consent. Maybe add NotJwtRestrictedApplication, or declare it.
There was a problem hiding this comment.
Every v2 view now declares the refusal itself. fix: refuse a restricted application's token on every operation of /api/user/v2/ (#39297) adds a mixin that appends NotJwtRestrictedApplication to whatever each view resolves, and the preference and opt-in views inherit it. EveryOperationCarriesTheRefusalTests walks every route.
test: refuse a restricted application's token at every preference and email choice operation adds PreferenceTokenRefusalTests. It covers 12 operations, reads and OPTIONS included, with the JWT middleware removed, so it proves each view refuses on its own.
While checking this I found that, at the earlier head, the preference view built its read permissions from a module constant. That meant the class the middleware appends never reached the two reads. The new tests cover exactly that.
Compared with v1:
- the document and both opt-in addresses answer 403 on both versions;
- the v1 member address answers 401 because it reads no JWT, and v2 answers 403. That difference is declared.
| "/api/user/v1/users/{id}/", | ||
| "/api/user/v1/user_prefs/", | ||
| "/api/user/v1/user_prefs/{id}/", | ||
| "/api/user/v1/preferences/{username}", |
There was a problem hiding this comment.
The same v1 preferences urlconf is mounted on Studio (cms/urls.py:86), and Studio's header language selector uses preferences_api on its own host. There's no /api/user/v2 on CMS, so removing this per the DEPR would break Studio. The DEPR entry should exclude the CMS mount or plan the Studio move first.
There was a problem hiding this comment.
Right. Studio's header language selector reverses preferences_api on its own host, and Studio serves no /api/user/v2/.
- fix: leave Studio's preference addresses current in its own document keeps the three preference addresses out of Studio's own superseded list. Since feat: standardize the user accounts, profile image, verification and name-change API #39297, Studio marks only what its own
SUPERSEDED_PATHSlists. So Studio's/api-docs/publishes those six operations as current, while the LMS still marks them. SupersededUserOperationTest::test_the_preference_addresses_its_own_pages_call_are_published_as_currentpins this.- The [DEPR]: Contentstore and enrollment API versions superseded by FC-0118 #39128 entry for this PR now says removal covers the LMS mount only, and that Studio's copies stay until Studio has a replacement on its own host.
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.
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.
9eba272 to
ce73cb8
Compare
Reference detail for this pull requestThe description is over GitHub's 65,536-character limit, so these five reference sections live here.
C1 — Caller-visible changes, the complete enumeration
Cross-cutting (all six operations)
|
| documents compared | result |
|---|---|
LMS document, origin/master → this branch |
PASS (0 BREAKING, 4 WARN, 47 INFO); 19 paths to 56 |
| LMS document, branch parent → this branch | PASS (0 BREAKING, 0 WARN, 12 INFO); every finding reads operation added — the six conforming operations and the six superseded ones |
| service-wide document, branch parent → this branch | FAIL (2 BREAKING, 0 WARN, 12 INFO); 509 paths to 512 |
service-wide document, origin/master → this branch |
FAIL (7 BREAKING, 2 WARN, 47 INFO); five of the seven belong to phase B (name_change POST, confirm POST, search_emails POST, image POST twice) and are declared in #39297 |
The two findings this phase owns correct the document; they do not change behaviour. In the
service-wide document, PATCH /api/user/v1/preferences/{username} and
PUT /api/user/v1/preferences/{username}/{preference_key} were published with a bodiless 200.
Both handlers answer 204, and always have (preferences/views.py:146 and :249 — untouched by
this diff, and asserted from both sides by
test_the_same_merge_patch_leaves_both_versions_storing_the_same_rows and
test_the_value_sent_is_stored_by_both_versions). Publishing what they really answer removes a
200 they never sent, which schema_diff.py compare reads as a removed response code. No address,
operationId, tag or component is renamed or dropped.
Exactly six existing operations change in that document, and this is all of it — read operation
by operation, parent against branch:
| operation | before | after |
|---|---|---|
GET /api/user/v1/preferences/{username} |
200, no body described |
deprecated: true; the 200 described as the preference document |
PATCH /api/user/v1/preferences/{username} |
200, no body described |
deprecated: true; a merge-patch request body; 204 |
GET …/{preference_key} |
200, no body described |
deprecated: true; the 200 described as the stored text |
PUT …/{preference_key} |
200, no body described |
deprecated: true; a JSON request body; 204 |
DELETE …/{preference_key} |
204 |
deprecated: true, and nothing else |
POST /api/user/v1/preferences/email_opt_in/ |
200, no body described |
deprecated: true; a form request body; the 200 kept, because that handler really answers 200 |
The unversioned twin POST /user_api/v1/preferences/email_opt_in/ is identical on both sides: no
request body, a bodiless 200, not deprecated. SupersededBodyInTheServiceWideDocumentTest pins
all three of those facts in the document that publishes them, and the mutation that publishes a
200 for a change answering nothing turns four tests red across both documents.
What the alignment commit adds to this comparison
Everything above was measured parent-against-branch before the branch's last commit, so "exactly
six existing operations change" describes that measurement and not the branch's current head. Three
further document-level changes ride on that commit, and they are set out with their consequences in
the description's Three published-contract changes this PR carries outside the preference
surface:
- One
operationIdis renamed in the service-wide document.
GET /api/user/v2/user_preferences/{username},{key}/moves from
v2_user_preferences_retrievetoapi_user_v2_user_preferences_retrieve, because an inline pin
that published one name in both documents is replaced by one entry per document. The narrow
document is unchanged. Measured on the two generated documents: service-wide operations
680 → 680, narrow 72 → 72, URL names 2531 → 2531, no address or component added or lost on either
side.masterpublishes neither name — it does not publish this path — but the descriptions
published for phase A and for this phase both show the old one, so an SDK generated from
/api-docsduring this series must be regenerated. - A
patternis added to a phase B address. Theusernamepath parameter of
/api/user/v2/accounts/{username}/profile_image/gains^[\w .@_+-]+$, the pattern the route
already enforces and the other ten addresses already publish. ?username=on phase A's two directory collections — still open; the description carries
both the declare and the revert wording.
The four schema_diff.py compare verdicts in the table above were not re-run after that
commit, so they stand as the measurement of the earlier head rather than of the current one; they
are to be re-run before merge.
C3 — Follow-ups
Library-first — the three items Phase B named, plus two this phase leans on
flatten_detail (an ErrorDetail repr reaching clients), the missing
OpenApiAuthenticationExtension/security block for the platform's auth classes, and a DRF 3.17.2
parser RecursionError. None is patched locally; the superseded addresses answer the same way.
Two more, both carried by this phase rather than worked around:
IsActiveUser(user_api/v2/permissions.py) is a four-line permission class admitting a
caller whose own account is still active.edx-drf-extensions10.9.0 ships no equivalent —
neither the authenticated check nor the administrator check readsis_active— Its history across these
phases: the class arrives in Phase A, becomes load-bearing in Phase B, which already composes
(IsStaff & IsActiveUser)on the two ID-verification reads (views.py:1467,:1549), and is
carried forward unchanged here, where the same composition stops a deactivated administrator's
token from reading another account's preferences. This phase is not the first to rely on it;
feat: standardize the user accounts, profile image, verification and name-change API #39297's own library-first list omits it, which is the inventory error, not a change in status. It belongs in the
library beside the permission primitives it ships; it is declared here because no release carries
it yet,
and the local class is deleted in favour of the library's the release after one lands. It is
not a local copy of anything: there is nothing to copy.- A serializer field as a request or response body. drf-spectacular 0.30.0 maps a bare
serializer field only inside a serializer or a list wrapper:_get_request_for_media_typeand
_get_response_for_codehave no field branch, so handing one of theseDictFields to
OpenApiResponseor to a media-type map publishes{"type": "object", "additionalProperties": {}}
withdescription: Unspecified response bodyand emitscould not resolve …(measured on this
tree). The open-ended preference document is therefore published through the raw-schema mechanism
the generator does support, attached to the field that carries it with@extend_schema_field, and
the two are held together by tests rather than by the generator (C1 item 35). A field branch in
those two functions is the upstream change that would let the declaration be the field alone.
Next-version candidates (ADR 0037)
- A read of the email opt-in (
GET /email_opt_ins/{org}/), and addressing the choice by organization
directly instead of deriving it from a course key. This phase standardizes what exists; neither is
an operation the superseded surface offers. - Moving the language-cookie-to-preference sync off the read path, so no read of any LMS address
writes, announces a field change or emits an analytics event. All three travel together: the
middleware stores the caller'spref-langrow, and that row'spost_savesends
USER_FIELDS_CHANGEDand emits oneedx.user.settings.changedevent. The signal's one in-repo
LMS receiver isuser_authn.signals.user_fields_changed(registered as a plugin signal receiver in
user_authn/apps.py), which callssegment.identifyfor the caller — a no-op where no Segment key
is configured, an identify call per read where one is. So the change is worth more than one row: it
is a write, a signal and an event, with one receiver acting on the signal today. It is a platform
change inlang_prefmiddleware, not an API change, and it is what would let this area claim 0030
with no declared write at all. Both versions of these addresses behave identically until it lands. - A bounded read of an account's own preference rows. The row-shaped, paginated view of the same
table in this version is administrator-only, so the holder of a document reads it whole or one name
at a time, and a client that wants a handful of names makes one request per name. An owner-readable
page of those rows, or afields-style selection over the document, would give them one bounded
request; neither exists on the superseded surface either, which is why this phase adds neither. - A way to address a preference name that carries a slash. The model's key validator is applied
unanchored, soa/b,x/,/xanda//bare names a preference is really stored under, and the
document of this version stores, reads and removes them. The member address reads a name from one
path segment and a segment ends at a slash, so no member address for such a name exists at
either version: both answer the request as an unknown address, in the raw and the
percent-encoded spelling alike. Widening the segment is not the fix — it would swallow the
trailing slash and every address below it — so reaching them needs a sub-resource that carries an
encoded name, or afields-style selection over the document. Pinned as it stands by
test_a_name_carrying_a_slash_is_not_addressed_as_a_preferenceand
test_a_name_carrying_a_slash_is_stored_read_and_removed_through_the_document. - An ORM-backed, scoped selector for one account's preferences (the seam named in §10 and C5).
Risks recorded, no decision needed
- The document is unbounded. Its size is set by how many preferences the addressed account itself
stores (measured: 11–281 bytes for 1–25 names, at a constant query count). No cap is introduced: a
cap would refuse an account whose own plugins store many names, and the superseded address has none.
The row-shaped view of the same table atGET /api/user/v2/user_preferences/is
administrator-only, so it is not a bounded alternative for the account holder; an
owner-readable page of the same rows is recorded as a next-version candidate above. - Studio keeps calling v1.
/api/user/v2/is LMS-only, as in Phase B;cms/urls.pymounts the v1
package and the Studio header reversespreferences_api. No Studio client is asked to move. - No client in this repository is migrated.
common/static/js/src/lang_edx.js,
lms/static/js/student_account/emailoptin.js, the two header templates and the i18n test keep
calling v1, which is untouched.
SDK
All six operations carry tags: ["openedx-platform-sdk"], as Phase B's eleven do, so a generated
client exposes an account's preferences and the opt-in beside its account operations. Note C1 item 28:
the read of one preference is named for what it reads rather than told apart by a numeral.
C4 — The compliance matrix's evidence column, and the test inventory
One row per decision, keyed to §5 of the description. Nothing was dropped on the way here.
| Decision | Evidence (test / gate) |
|---|---|
| 0025 serializers | PreferenceDocumentTests (23), PreferenceMemberTests (22), EmailOptInViewTests (28); test_the_preference_document_is_published_as_the_open_ended_object_it_is; test_a_preference_document_the_endpoint_answers_is_what_the_document_describes; test_a_merge_patch_the_endpoint_carries_out_is_one_the_request_body_takes (a null and a text value both validate against the published request body, a number does not, and the endpoint then answers 204 to the null); test_the_preference_document_is_published_as_the_fields_that_carry_it_describe; mutations: email_opt_in declared as text → 20 failures; the nullable member dropped → 2 red; the shape detached from the changes field → 1 red; the field's ordering removed → 2 red; the field reading a value as text only → 2 red; the empty value refused by the field instead of the service → 2 red; each of the three refusals removed → red; the strict reading of the choice removed → 2 red; the required-choice guard for form bodies removed → 2 red; the organization-length refusal removed → 1 red (204 with a 300-character organization) |
| 0026 permissions | §10; PreferenceAccessTests (18), PreferenceGuardTests (5), EmailOptInAccessTests (6); mutations: IsActiveUser made a no-op → red; the administrator half added to the writes → red; the read constant emptied → red; the address comparison relaxed → red (twice: at the declaration and at HTTP) |
| 0027 schema / docs | test_the_preference_operations_carry_the_names_they_are_published_under; test_no_preference_operation_publishes_a_parameter_beyond_the_address_it_is_read_from; test_the_email_choice_publishes_the_body_it_reads_and_that_it_answers_with_nothing; test_the_email_choice_publishes_the_refusal_a_session_is_answered_with_without_its_token (drives the refusal and matches the code and the published text against it; mutation: the published 403 removed -> 2 red); test_each_superseded_body_is_published_in_the_media_types_that_address_reads; test_schema.py 75 passed, including test_each_preference_operation_publishes_the_answers_it_can_give (the five answer sets literally, so a published status no handler can answer fails here) and test_the_name_a_preference_is_stored_under_is_published_under_one_parameter_name (the path parameters of both member addresses are exactly {username, key}; mutation: the parameter renamed → 3 red) |
| 0028 viewsets | test_the_preference_viewset_serves_both_of_its_addresses; test_addresses_resolve_to_the_version_two_viewsets (both addresses resolve to the one viewset with the method sets above); test_the_preference_document_is_published_as_the_open_ended_object_it_is |
| 0029 errors | assert_error_envelope on every refusal (400 validation ×17, 401, 403, 404, 405, 415, malformed-body, 500); PreferenceServiceFailureTests (6, one of them a real DatabaseError, two of them a change that fails part way through); test_a_name_that_cannot_be_encoded_is_refused_against_the_body and test_a_value_that_cannot_be_encoded_is_refused_under_the_name_that_carried_it, each asserting the answer is application/json — the superseded address answers 500 text/html for the same body; mutations: each refusal removed → red |
| 0030 GET idempotence | PreferenceReadsWithoutTheLanguageCookieTests (10) and PreferenceReadsWithTheLanguageCookieTests (14) — one fixture class per side, covering the value that is there, the name that is not, the account that is not, and (with the cookie) the four cases where the row the middleware writes is the one being removed; plants, each measured in the round that added the capture it defeats, over the two preference modules as they then stood — now 112 and 25 tests: a SQL write in the document read → 21 failures; the language cookie removed from the fixture → 10 failures (the whole class); an announcement with no SQL behind it planted in the document read → 9 failures and in the member read → 9; an analytics event alone planted in the document read → 9 failures; a domain write on the member read's "no such name" branch → 3 failures, where the same plant left all 111 tests green before this round; a domain write on the "no such account" branch → 1 failure |
| 0031 merged endpoints | test_a_name_that_is_a_collection_of_this_version_is_read_as_a_preference_name; EmailOptInParityTests (8); test_no_superseded_preference_address_announces_its_own_removal |
| 0032 pagination | test_the_document_carries_no_pages; the row view's own deny tests, unchanged by this phase: test_a_learners_token_is_forbidden_on_every_staff_gated_address and test_the_owner_of_the_record_is_still_not_staff (v2/tests/test_views.py, where the owner of the row is refused 403 at it) |
| 0033 filtering | test_the_names_come_back_in_one_order_whatever_order_they_were_stored_in and test_the_order_the_names_come_back_in_is_the_code_of_each_character (the order is asserted as the list ["9nine", "Beta", "Zeta", "_under", "alpha"], which a sort that ignored letter case would not produce; mutation: order reversed → red); PreferenceQueryParameterTests (4) |
| 0034 authentication | test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaults in four modules (test_preference_views.py, test_account_views.py, test_email_opt_in_views.py, profile_images/v2/tests/test_views.py): each asserts the request succeeded and produced its real answer, that the attribute was not recorded, and that a second request in the same test to a sibling address on the defaults was recorded, so the assertion cannot pass against a mistyped patch target; test_urls.py::test_the_views_reached_before_an_address_is_confirmed_replace_one_class pins the tuple of all four views and keeps the tie to configuration with issubclass(platform_token, JwtAuthentication); test_an_account_with_an_unconfirmed_address_reads_and_changes_its_own_preferences; test_an_account_with_an_unconfirmed_address_records_a_choice; mutations: the monitoring subclass restored in each of the four views in turn → the view's own pin red, its neighbour's green (1 failed, 1 passed ×4), and the declaration pin red on its own; either declaration removed → red |
| 0035 MFE config | — |
| 0036 nested JSON | test_no_preference_address_shapes_what_it_answers_with |
| 0037 versioning | versions gate PASS twice (--base origin/master: added in old dirs: 0; --base Phase B's head with the six allowed globs); 18 protected paths re-verified per path (git diff --numstat + git ls-files --others): 0 changed lines, 0 untracked |
| 0038 URL structure | test_urls.py 46 passed: reverse() literals for the three new names and all four legacy ones, same-view resolution for the twin, the catch-all not swallowing either address, me routed as a stored name, every key shape a segment can carry addressable, and a name carrying a slash answered by the fallback instead, in four shapes and two spellings (test_a_name_carrying_a_slash_is_not_addressed_as_a_preference, test_a_name_carrying_a_slash_is_stored_read_and_removed_through_the_document; mutations: the key pattern widened to .+ → both red, and widened to [^/]+/? — which the single-shape version of these tests would have passed → both red on the x/ shape) |
| OEP-66 scoping | PreferenceAccessTests; test_a_null_removes_the_name_from_the_account_that_was_addressed |
| OEP-69 conventions | test_urls.py, test_schema.py, test_preference_views.py |
Test inventory
Counted from the tree; the collected counts are the gate run's own
(gates-phase-c-final.txt, tests gate, 1118 items).
| module | classes and counts |
|---|---|
user_api/v2/tests/test_preference_views.py (112) |
PreferenceDocumentTests 23, PreferenceMemberTests 22, PreferenceAccessTests 18, PreferenceReadsWithTheLanguageCookieTests 14, PreferenceReadsWithoutTheLanguageCookieTests 10, PreferenceServiceFailureTests 6, PreferenceGuardTests 5, PreferenceRefusedWithNothingBehindThemTests 5, PreferenceAddressedByMeTests 5, PreferenceQueryParameterTests 4 |
user_api/v2/tests/test_preference_parity.py (25) |
PreferenceDocumentParityTests 8, PreferenceRefusalParityTests 8, PreferenceMemberParityTests 7, SupersededAddressAnnouncementTests 2 |
user_api/v2/tests/test_email_opt_in_views.py (44) |
EmailOptInViewTests 28, EmailOptInParityTests 10, EmailOptInAccessTests 6 |
user_api/v2/tests/test_schema.py (75) |
module-level, including the preference operations' published parameters, answers, bodies and names |
user_api/v2/tests/test_urls.py (46) |
UrlLiteralTests 21, MalformedAddressTests 12, LegacyAddressTests 9, RouteShapeTests 4 |
profile_images/v2/tests/test_views.py (51) |
#39297's module; one authentication pin rewritten here |
| whole selection | 1118 passed; user_api/v2/ alone 920, profile_images/ 124, user_api/tests/ + user_api/preferences/tests/ 193 |
The last two review passes added fifteen tests and renamed five. New in
test_preference_views.py: test_the_order_the_names_come_back_in_is_the_code_of_each_character;
test_a_name_nothing_can_be_stored_under_is_refused_under_that_part_too;
test_the_names_this_address_refuses_are_the_ones_the_store_refuses;
test_an_administrator_asking_what_another_accounts_addresses_answer_is_told;
test_the_addressed_account_is_told_what_a_change_at_their_own_address_carries;
test_a_learner_asking_what_another_accounts_addresses_answer_is_refused;
test_an_anonymous_caller_asking_what_these_addresses_answer_is_refused;
test_asking_what_an_address_answers_is_guarded_as_a_read_of_it;
test_removing_the_language_removes_the_row_the_middleware_had_just_stored;
test_the_document_removing_the_language_leaves_it_removed_as_well;
test_removing_another_name_stores_the_language_the_cookie_carries;
test_a_name_stored_only_by_the_middleware_is_removed_rather_than_reported_absent. New in
test_schema.py: test_the_name_a_preference_is_stored_under_is_published_under_one_parameter_name;
test_each_preference_operation_publishes_the_answers_it_can_give. New in
test_email_opt_in_views.py: an authentication pin for EmailOptInViewSet, which had none.
The review pass before them added five more, named here because the counts above include them:
EmailOptInViewTests.test_the_row_a_refusal_opened_stands_where_a_statement_stands_on_its_own and
EmailOptInParityTests.test_neither_address_records_a_choice_for_an_account_carrying_no_profile
(what a refused choice leaves behind, on each side of the request transaction, at both addresses);
PreferenceAccessTests.test_a_session_without_the_token_that_goes_with_it_is_refused_every_change
(the three preference writes, which had no such test);
RouteShapeTests.test_every_pattern_is_anchored_where_the_mount_leaves_off and
MalformedAddressTests.test_an_address_merely_ending_in_one_this_version_serves_is_not_found (every
pattern of this version is anchored where the mount leaves off, so an address merely ending in one
it serves is not found).
Renamed, because each now asserts something else:
test_the_actions_an_administrator_may_call_against_another_account_are_the_two_reads (was named for
the permission objects rather than for what they admit), and
test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaults in four modules
(test_preference_views.py, test_account_views.py, test_email_opt_in_views.py,
profile_images/v2/tests/test_views.py), each of which previously asserted the opposite of what the
code now does. test_urls.py::test_the_views_reached_before_an_address_is_confirmed_replace_one_class
covers all four views rather than two.
Each of those four pins is built so that it cannot pass vacuously: the request under test must
succeed and produce its real answer (so a token demonstrably authenticated it), and a second
request in the same test — GET /api/user/v2/user_preferences/ with an administrator's token,
served by a viewset that declares no classes of its own — must record the attribute, which is what
proves the recorder is reachable from a request made this way at all. Without that control request,
an == [] assertion would pass against a mistyped patch target.
C5 — Authorization detail
Three layers (OEP-66)
| layer | the five preference operations | the opt-in |
|---|---|---|
| 1 endpoint access | the permission classes above | IsAuthenticated |
| 2 record visibility | the rows of the one account the address names, read through the preference service; no other account's row is reachable from these addresses | the single row (caller, org, email-optin) |
| 3 user-driven filtering | none: no parameter is read, and an unknown one is refused | none |
A future ORM-backed pass would put a selector in v2/selectors.py returning
UserPreference.objects.filter(user__username=…) and declare a scoping_policy on it; today the
account-scoped read is the model helper the whole platform shares, so duplicating it inside the view
would be the worse trade.
What the guard harnesses assert, and the me row
The me row is driven for all five operations, at both addresses. me is read as a stored
name here, so the three writes answer 403 for an administrator as well as for a learner — an
administrator is refused rather than told the name is free, because a refusal is ordered before any
account lookup — and 204 for the account that really holds the name, whose rows are the ones
changed (test_a_learner_changing_the_preferences_at_me_is_refused,
test_an_administrator_changing_them_is_refused_rather_than_told_the_name_is_free,
test_the_account_holding_that_name_is_served, which now round-trips the document patch and the
removal as well as the single write). The two reads answer 403 / 404 / 200 for the same three
callers, which is the one place the two halves differ: an administrator may read, so they reach the
lookup and are told nothing holds the name.
What the guard tests assert, and why. The preference service enforces the same
owner-or-administrator rule from behind the permission classes, so an answer produced with it in
place does not say which of the two refused a caller: relaxing IsAddressedUser, or adding the
administrator half to the writes, leaves the ordinary HTTP deny tests green. Two things cover that.
The per-action declarations are asserted directly — PreferenceGuardTests builds each action's
permission objects and checks who they admit. And PreferenceRefusedWithNothingBehindThemTests (5)
drives all five operations with the five preference service calls replaced by stand-ins that serve
whoever asks, so the classes are the only thing left that can refuse: the addressed account is
served at every address, while another learner, an administrator's three writes, a caller whose name
differs from the address only in letter case, and an administrator whose own account is no longer
active are each refused 403 with the envelope. Both mutations now go red twice, once at the
declaration and once at HTTP: a relaxed IsAddressedUser, and the administrator half added to the
writes (each 2 failed alongside the rest of the two preference modules green, measured in the pass
that added these tests). The classes remain the authorization surface (they refuse before
any handler runs, and requiring an active administrator account is a real tightening that only they
do); they are not the only thing refusing, and a future widening of theirs is visible at HTTP.
C6 — What schema generation reports, and no gate scores
- Generation emits ten new warnings, all of one kind, where the plan asked for none. Measured
on the LMS document underlms.envs.test, in one run per ref: this branch's parent (phases A and
B) emits 138 warnings / 79 unique, this branch 163 / 89, and the error count is unchanged
on both sides (36 / 6 unique). The gate's own head run reports the same163 (89 unique)and
36 (6 unique), andorigin/masterreports56 (30 unique)/28 (5 unique)for 19 paths. Every one of the ten new messages readscould not resolve authenticator <class …>. There was no OpenApiAuthenticationExtension registered for that class—
six for the three superseded views this phase publishes (PreferencesViewthree times,
PreferencesDetailViewtwice,UpdateEmailOptInPreferenceonce) and four for the two views it
adds (AccountPreferenceViewSetandEmailOptInViewSet, twice each). Replacing the monitoring
subclass with the library class in four views changed which class each warning names, not how many
there are: two per view either way. No warning disappears. The
cause is the missingOpenApiAuthenticationExtensionfor the platform's authentication classes —
the second library-first item in C3 — so until that lands, every view with a declared
authentication class costs one warning per class, whether it is being standardized or merely
published for its deprecation mark. Emitting none would mean leaving the superseded addresses out
of the document, which is how they are marked deprecated, so this misses the plan's acceptance bar
for schema generation and is recorded rather than silenced. - The generator's collision warnings go down, not up. The two reads of this resource and the
two reads of the superseded one each tokenize to one operationId; naming the read of one
preference in each pair leaves the service's own document with one collision warning
(v1_enrollment_retrieve, which master carries) and the service-wide document with the two it
already carries under/api/user/(item 28). Both pairs are pinned by tests, and both documents
were read path by path: no path, component or operationId either carried before is missing or
renamed.
Phase C — authorization and gate evidenceMoved out of the pull request description, which GitHub caps at 65,536 characters. 10. AuthorizationEvery legacy check has a named home. On its own terms: each operation selects a record by the
The three layers (OEP-66), with the selector seam a future ORM-backed pass would use, are Deny-path tests
Named tests: Asking what an address answers is guarded as a read of it. The 11. Gate report
What this run measured. This branch head, which carries phases A and B beneath it. It says The schema gate is the evidence for the operation-id work. Two addresses of this resource The one red is deliberate, and it is older than this phase. All three findings are on One tooling note. Where a gate cannot see the change
|
922b84b to
cab976a
Compare
…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.
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.
…uth 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.
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.
…er 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.
…here 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.
…ettings 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.
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.
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.
…ved 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.
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.
…source 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.
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.
…ently 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.
…rsion 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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
…ules 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 <[email protected]>
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 <[email protected]>
… 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 <[email protected]>
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 <[email protected]>
Six operations move to this version's conventions: a learner's preference
document and its individual members, addressed under the account they belong
to, and the email opt-in as a collection of its own.
GET, PATCH /api/user/v2/accounts/{username}/preferences/
GET, PUT, DELETE /api/user/v2/accounts/{username}/preferences/{key}/
POST /api/user/v2/email_opt_ins/
A preference name is the whole final segment, punctuation included, so a name
carrying a slash has no address of its own; it is read with the whole document
and removed by sending a null for it there.
The superseded /api/user/v1/ addresses keep answering exactly as they did and
are marked deprecated in the published LMS schema. The unversioned twin
/user_api/v1/preferences/email_opt_in/ is the same view at a second address: it
keeps resolving and carries no schema mark, which is how the other unversioned
twins are treated.
…uth 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.
Three operations describe the body they read in place rather than through a serializer. A shape given in place carries no field the generator can read requiredness from, so the document published no mark at all and a generated client made the body an argument the caller may omit, while each handler answers a request carrying no body with a 400. The addresses are named explicitly and each is driven in the tests with its form named and no body behind it, so the mark the document carries is held to what the handler answers. The write of one stored preference is left unmarked on the same evidence: it takes a request with no body.
…er 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.
…source 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.
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.
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.
… email choice operation The preference document and member, and the email choice address, read a token, and each of them refuses one issued to a restricted application. Until now no test sent such a token to them, so the refusal on the two preference reads was lost once already without anything noticing. The new class sends every operation (the reads and descriptions of both preference addresses, by the owner and by a staff member reading another account, the three changes, and the email choice) a token from an ordinary application, which is answered, and the same token flagged restricted, which is refused 403 with nothing read or changed. These requests run without the platform middleware that adds the same refusal to a view's own classes, and anything it added earlier in the run is set aside, so the refusal they see is the one each view resolves itself: taking the guard off either view turns its rows red whatever ran before. Side by side with the version 1 addresses, under the platform's own middleware: the document addresses answer 403 on both versions, the email choice answers 403 at both earlier addresses and here, and the earlier member address answers 401 because it reads no token of this kind at all, where this version reads the token and answers 403. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Both fields that read a preference value (each member of a merge patch of the
document, and the value sent to one preference) trimmed it before the
preference service saw it. The service checks a time zone against the zones
it holds before it trims what it stores, so `{"time_zone": " Asia/Tokyo"}` was
stored as `Asia/Tokyo` here while version 1 refuses it 400 at both of its
addresses. Neither field trims now, so the service sees the value as sent:
- a time zone with whitespace around it is refused 400 under the name in the
document, and under `value` at the member address, with the message
version 1 shows, and nothing is stored;
- any other value is still stored without the whitespace around it, because
the service trims what it stores, as it does for version 1;
- a value of whitespace alone sent to one preference is refused with the
service's empty-value message, the one version 1 answers, instead of the
field's own; through the document it was already.
The tests send each of these to both versions side by side.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The member address takes the whole of its segment as the preference name, so a name can arrive with whitespace at one end or both. The preference service stores a name without that whitespace, after it has run its checks against the name as sent. A store at `.../preferences/%20pref/` therefore answered 204 and saved the value under `pref`. A read or removal at the same address then answered 404. With `pref` already stored, the store was refused under `value` instead. A store at `.../preferences/%20time_zone/` skipped the time-zone check and saved a zone that check refuses. Version 1's member address carries no whitespace, so it answers 404 to all of these and stores nothing. Version 2 now does the same: once the caller is admitted, an address whose name has whitespace at either end is absent for every method, and nothing is stored. A caller who may not use the address is refused as before, so the address tells them nothing. The store operation publishes the 404, and the name parameter says why. A name with whitespace around it sent in a merge patch of the document is still stored without the whitespace, as version 1 stores it. The tests send each case to both versions side by side. Co-Authored-By: Claude Opus 5.5 <[email protected]>
…e never gives it `_service_failures_named` turned the preference service's `UserNotAuthorized` into a 403. The service raises it only for a caller who is neither the account named nor, for a read, a staff member. Every operation's own permission classes refuse exactly those callers first, comparing the same names and the same staff flag, so no request that reaches the service can draw it. The handler did more than sit unused. If an operation's permission classes ever admitted the wrong caller, the service's refusal would still have come back as the 403 the deny tests expect, so those tests would have stayed green. With the handler gone, such a caller gets an unhandled error and the tests fail. To check this, `IsAddressedUser` was made to admit everyone: with the handler, 3 of the 27 access and refusal-parity tests failed; without it, 14 failed. Nothing changes for callers, and the full preference suites pass. Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ocument Two tests left with the classes and fixtures that held them. Each still describes behaviour this branch has, so each is back in a form that does not generate the whole service document: - A collection above the preference document does not take a merge patch: `PATCH /api/user/v2/accounts/` and `/api/user/v2/users/` answer 405 with the standard body. This now lives with the other refused-method tests. The directory is sent the API key, which is what admits a caller there now, so the method is the only thing that can refuse the request. - The unversioned twin of the version 1 email choice address, `/user_api/v1/preferences/email_opt_in/`, still resolves. The service-wide document still publishes it as it always has: no request body, a bare 200, not deprecated. The document is generated from the twin's own route, under the settings it is published with, because the twin is mounted outside the user mounts the shared fixture covers. Each was checked against a mutation. Giving the router's collection route a PATCH fails the first test. Letting the superseded-body table match the twin, or marking the twin superseded, fails the second. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Studio mounts the v1 user API as the LMS does, but it serves no
/api/user/v2/. Its header language selector reverses preferences_api and
changes the language through PATCH /api/user/v1/preferences/{username}, so
Studio keeps those addresses and has no replacement to point a caller to.
Its whole-service document no longer marks the three preference addresses
deprecated: the preference document, one preference, and the email opt-in.
Both LMS documents still mark all three, since the LMS serves their
replacements.
Studio's test pins the six preference operations as current and every other
listed user operation as superseded; the LMS test pins all six as
superseded in both of its documents.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
…'s text type
The v1 preference change and the v1 write of one preference borrowed the
bodies of their replacements, which take only text. Both v1 handlers store
the text of a value of any type: PATCH {"num_pref": 5} and PUT 7 each answer
204 and store "5" and "7". A client generated from either LMS document
therefore refused, on its own side, values the v1 handlers store.
Each v1 write now publishes its own body. The change is an object of at
least one name whose values carry no type, the bound the handler does hold;
the write's value carries no type. The replacing addresses keep their
text-only values, the read of one preference still answers text, and media
types and required marks are unchanged in /lms-api/ and /api-docs/.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
cab976a to
75a854e
Compare
|
The commits that changed #39297's code have moved there, so this PR now holds only the preferences and opt-in work: 18 commits, down from 38. This branch was rewritten and force-pushed. The description is replaced and an evidence comment follows. What changed in the history. Each correction now sits in the PR whose code it changes. Before, some corrections to #39297's code (for example, the JWT class on the account and image views) existed only in #39314. Merging #39297 alone would have left them out. Now each PR is complete once the PRs before it merge (order: #39297 → #39314 → #39330 → #39334 / #39331). The corrections from the review round of 2026-11-04 are added as commits at the end of each PR. Commits that changed a lower PR's code moved down, with their authors and messages kept. Some fixes were folded into earlier commits of the same PR so that every commit passes the suites. How to review the rewrite. The new commits of the 2026-11-04 round are listed in the description's commit table. Each one names its subject, and each behaviour change comes with a test that fails without it. |
Evidence for #39314Each test is named as Declared differences → tests
Compliance matrix
Gate report
All 28 WARNs are drf-spectacular generation warnings (unresolved authenticator, type hints) on views newly included in the narrow document. Repo CI lint: ruff, xsslint, pii_check, check_keywords, lint-imports ("lms and cms are independent" KEPT), mypy, verify-dunder-init and pylint add 0 findings against #39297. commitlint passes on every commit. Test runs at this head (
drf-spectacular adds no error master does not log, and removes 7 of master's in LMS Tests removed or changed by the corrections
|
|
@Faraz32123 on your review of 29 October: Thanks.
|
taimoor-ahmed-1
left a comment
There was a problem hiding this comment.
Follow-up review of this PR's own range (45b7d17..75a854e). The code checks out: legacy untouched, permissions match v1's real (service-level) gate, reads write nothing (HEAD included), and the time_zone/pref-lang, account_privacy and opt-in organization cases are preserved or declared. One item should change before this leaves draft.
| "/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. | ||
| # The preference addresses are left out: this service's own pages change a |
There was a problem hiding this comment.
The deprecation plan leaves Studio's v1 preference addresses current because "this service's own pages change a preference through them", and schedules the LMS mount for removal one release out (#39128 entry 6560253430). The LMS's own pages call these routes too: lms/templates/header/header.html:91 and lms/templates/navigation/navigation.html:59 reverse('preferences_api'), common/static/js/src/lang_edx.js:40 PATCHes the language to that v1 document, and lms/static/js/student_account/emailoptin.js:8 posts to /api/user/v1/preferences/email_opt_in/. Those routes live in openedx/core/djangoapps/user_api/urls.py:187-213, which both services include, so following the entry as written either gives every LMS page that renders the header a NoReverseMatch 500 or removes Studio's copies as well.
Either track the LMS callers (the templates and the two scripts) in the MFE/caller migration issue #39349 and make the removal conditional on them moving, or apply the same "own pages" exemption to the LMS and say so in the description and the #39128 entry.
Summary
Part of
[API] Userunder the umbrella #38137, followingdocs/decisions/and OEP-69.This PR adds six operations under
/api/user/v2/. They cover one account's preferences and the email opt-in, and they replace six v1 operations at three addresses, plus the opt-in's unversioned twin./api/user/v1/keeps answering as it does today.Why a new version. The header language selector, the account and profile MFEs, and the enrolment flow call these addresses. The conforming answers differ visibly: refusals use one envelope instead of five shapes, one preference comes back as
{"key","value"}instead of a bare scalar, a value that is not text is refused rather than stored as"5", and the opt-in answers204and reads a real boolean.Stack and merge order: #39297 → #39314 (this PR, on #39297) → #39330 → #39334 and #39331 (siblings). Review this PR's own range:
git diff <#39297 head>..<this head>.18 commits, 16 files, +5346 / −35 (this PR's own range):
Operations
GET,PATCH /api/user/v1/preferences/{username}GET,PATCH /api/user/v2/accounts/{username}/preferences/GET,PUT,DELETE /api/user/v1/preferences/{username}/{preference_key}GET,PUT,DELETE /api/user/v2/accounts/{username}/preferences/{key}/POST /api/user/v1/preferences/email_opt_in/and its twinPOST /user_api/v1/preferences/email_opt_in/POST /api/user/v2/email_opt_ins/Declared differences a caller can see
INTENTIONAL_DIFFERENCESintest_preference_parity.pylists only the member's body shape and the refusal envelope members. The tests behind each item are listed in the evidence comment.Every operation
400, includingpage,page_size,viewandfields.JwtAuthenticationwithSessionAuthenticationAllowInactiveUser.BearerAuthenticationAllowInactiveUseris dropped, and the member address and the opt-in now accept JWT.403at every operation, reads andOPTIONSincluded. Each view refuses it itself, not the JWT middleware. The v1 document and both v1 opt-in addresses also answer403. The v1 member address answers401, because it reads no JWT at all.500 internal.mebeneath an account is read as a stored name.The document (
GET,PATCH …/preferences/)nullis refused400under its name. v1 stores{"num_pref": 5}as"5".application/jsongets415.time_zonewith whitespace around it is refused400. The service trims other values, and it refuses a value of whitespace alone with its own empty-value message.One preference (
…/preferences/{key}/){"key","value"}and stored from{"value"}. v1 reads and answers a bare JSON scalar.pref-langor a dotted name. The v1 route accepts only[a-zA-Z0-9_]+. A name nothing can be stored under is refused400underkey.404for every method once the caller is admitted, and nothing is stored. The v1 member address cannot carry whitespace and also answers404. A caller who may not use the address is refused401/403first.The email opt-in
204with no body. v1 answers200with an emptytext/htmlbody.course_keyinstead ofcourse_id. A course key in the earlier form is still read.email_opt_inis a strict boolean:1,on,yes,0,off,noand the like are refused400.401. An account with no profile gets404.Below the handler, unchanged: the platform's language-cookie middleware stores the caller's
pref-langon any request, exactly as at the v1 addresses. With the cookie present,DELETE …/preferences/pref-lang/answers204even if nothing was stored before the request.Published documents
/api-docs/, v1PATCH /preferences/{username}andPUT …/{preference_key}now publish204, the code their handlers answer, in place of200./api/user/v1/preferences/{username}, and Studio serves no/api/user/v2/. So these addresses are not marked in Studio's document. The LMS marks all three.Known limitation:
OPTIONSon the member address buildsactions.PUTfrom the response serializer, so it nameskeyandvalue. The request this version reads, and publishes, isvaluealone.ADRs applied
The evidence for each box is in the compliance matrix in the evidence comment.
(IsStaff & IsActiveUser) | IsAddressedUserfor reads andIsAddressedUserfor writes of preferences;IsAuthenticatedon the opt-in; every view refuses restricted-application tokens; deny tests per operationAccountPreferenceViewSetandEmailOptInViewSetJwtAuthenticationwithSessionAuthenticationAllowInactiveUser, with the reason in a commentv2package from feat: standardize the user accounts, profile image, verification and name-change API #39297; no v1 file changedemail_opt_ins; trailing slashesIn-place edits
No v1 preference view, serializer, URLconf or test is in the diff. Outside a version directory:
cms/lib/spectacular.pycms/lib/tests/test_spectacular.pylms/lib/tests/test_spectacular.pyopenedx/core/djangoapps/user_api/schema.py(from #39297)Error-format decision
Versioned. The envelope applies to
/api/user/v2/only, and the v1 preference and opt-in bodies are unchanged.Deprecations
The six v1 operations are marked
deprecated: truein the LMS documents only, with no header and no note in code. Tracked on #39128 (entry 6560253430). That entry is amended so that removal covers the LMS mount only. Studio's copies stay until Studio has a replacement on its own host. The unversioned twin/user_api/v1/preferences/email_opt_in/is listed on the entry and carries no schema mark, like the other/user_api/v1/twins.Deliberate deviations
401. v2 answers403, because it reads JWT and then refuses the token.404, as v1 does, rather than a400underkey. Admission comes first, so a stranger gets401/403.masterthe gate passes.Known pre-existing behaviour, left as it is
/api-docs/schema/caching, as described in feat: standardize the user accounts, profile image, verification and name-change API #39297.Evidence
The full tables are in the evidence comment.
d178206575ismaster's merge-base:master75a854eb0b), MongoDB attached: LMS (user_api/,profile_images/,user_authn/,lms/lib/tests/,lms/tests.py,openedx/core/tests/test_apidocs.py;-n 4) 2431 passed, 1 skipped, 0 failed; Studio (cms/lib/tests/,cms/tests.py,user_api/) 199 passed, 1530 skipped, 0 failed.origin/masterd2dbc6a593, conflict-free (wider targets, as in feat: standardize the user accounts, profile image, verification and name-change API #39297; the tree differs from this head only by the C1803 line): LMS 3176 passed, 8 skipped, 0 failed; Studio 371 passed, 1914 skipped, 0 failed. Every master test id is still collected.Follow-ups
These are shared with #39297:
str().