Skip to content

feat: standardize the user preferences and email opt-in API - #39314

Draft
Abdul-Muqadim-Arbisoft wants to merge 79 commits into
openedx:masterfrom
edly-io:feat/api-adr-user-v2-phase-c
Draft

Abdul-Muqadim-Arbisoft wants to merge 79 commits into
openedx:masterfrom
edly-io:feat/api-adr-user-v2-phase-c

Conversation

@Abdul-Muqadim-Arbisoft

@Abdul-Muqadim-Arbisoft Abdul-Muqadim-Arbisoft commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Part of [API] User under the umbrella #38137, following docs/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 answers 204 and 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):

commits what
from feat: standardize the preferences and email opt-in APIs as /api/user/v2/ to style: satisfy the repository's own lint on the lines this work adds (11) the feature and its review fixes. Some later fixes were folded into the feature commit so that every commit passes the suites. As a result, fix: admit an operation on one account by the rules of the account resource and fix: publish the two refusals every address of this version could already answer describe changes that now land in the feature commit
from test: refuse a restricted application's token at every preference and email choice operation to the last commit (7) corrections from the 2026-11-04 review

Operations

superseded (v1) replacement (v2)
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 twin POST /user_api/v1/preferences/email_opt_in/ POST /api/user/v2/email_opt_ins/

Declared differences a caller can see

INTENTIONAL_DIFFERENCES in test_preference_parity.py lists only the member's body shape and the refusal envelope members. The tests behind each item are listed in the evidence comment.

Every operation

  • Refusals use the RFC 9457 envelope. v1 answers five shapes, some of them with no body. A query parameter the operation does not read is refused 400, including page, page_size, view and fields.
  • Authentication is JwtAuthentication with SessionAuthenticationAllowInactiveUser. BearerAuthenticationAllowInactiveUser is dropped, and the member address and the opt-in now accept JWT.
  • A token issued to a restricted application is refused 403 at every operation, reads and OPTIONS included. Each view refuses it itself, not the JWT middleware. The v1 document and both v1 opt-in addresses also answer 403. The v1 member address answers 401, because it reads no JWT at all.
  • When staff read another account, their own account must be active. Work that was asked for correctly and still failed answers 500 internal. me beneath an account is read as a stored name.

The document (GET, PATCH …/preferences/)

  • Names come back sorted by character code, not in database order.
  • A value that is neither text nor null is refused 400 under its name. v1 stores {"num_pref": 5} as "5".
  • A change is merge-patch only. application/json gets 415.
  • A value reaches the preference service exactly as sent, as on v1. A time_zone with whitespace around it is refused 400. The service trims other values, and it refuses a value of whitespace alone with its own empty-value message.
  • A name with whitespace around it, sent in a merge patch, is stored without the whitespace, as on v1.

One preference (…/preferences/{key}/)

  • Read as {"key","value"} and stored from {"value"}. v1 reads and answers a bare JSON scalar.
  • Any name without a slash can be addressed, such as pref-lang or a dotted name. The v1 route accepts only [a-zA-Z0-9_]+. A name nothing can be stored under is refused 400 under key.
  • A name with whitespace at either end is answered 404 for every method once the caller is admitted, and nothing is stored. The v1 member address cannot carry whitespace and also answers 404. A caller who may not use the address is refused 401/403 first.

The email opt-in

  • Answers 204 with no body. v1 answers 200 with an empty text/html body.
  • Takes course_key instead of course_id. A course key in the earlier form is still read.
  • email_opt_in is a strict boolean: 1, on, yes, 0, off, no and the like are refused 400.
  • An anonymous caller gets 401. An account with no profile gets 404.

Below the handler, unchanged: the platform's language-cookie middleware stores the caller's pref-lang on any request, exactly as at the v1 addresses. With the cookie present, DELETE …/preferences/pref-lang/ answers 204 even if nothing was stored before the request.

Published documents

  • The v1 preference change and the v1 write of one preference are documented with the bodies those handlers read. Values carry no type, because both handlers store the text of any value. The change still requires an object that names at least one preference. The text-only values stay on the v2 components.
  • In the LMS's service-wide /api-docs/, v1 PATCH /preferences/{username} and PUT …/{preference_key} now publish 204, the code their handlers answer, in place of 200.
  • Studio leaves its three preference addresses current. Studio's header language selector reads and changes the language through /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: OPTIONS on the member address builds actions.PUT from the response serializer, so it names key and value. The request this version reads, and publishes, is value alone.

ADRs applied

The evidence for each box is in the compliance matrix in the evidence comment.

  • 0025 serializers — the document's changes and one preference's value are checked by the published serializers before the service runs
  • 0026 permissions — (IsStaff & IsActiveUser) | IsAddressedUser for reads and IsAddressedUser for writes of preferences; IsAuthenticated on the opt-in; every view refuses restricted-application tokens; deny tests per operation
  • 0027 schema / docs — every operation publishes its media types, refusals and parameters; the v1 writes publish their own bodies
  • 0028 viewsets — AccountPreferenceViewSet and EmailOptInViewSet
  • 0029 errors — partial, as in feat: standardize the user accounts, profile image, verification and name-change API #39297: the envelope is used everywhere; 405/406/415 and the unparsable body carry the library catalog's type
  • 0030 GET idempotence — reads capture no writes of their own; the language-cookie write is the platform's and is pinned on both versions
  • 0031 merged endpoints — the opt-in and its unversioned twin are answered by one address
  • 0032 pagination — n/a: the document is a single object and the opt-in a single write; no list is answered
  • 0033 filtering — n/a: nothing here is a list to filter
  • 0034 authentication — JwtAuthentication with SessionAuthenticationAllowInactiveUser, with the reason in a comment
  • 0035 MFE config — n/a: no frontend configuration is served
  • 0036 nested JSON — n/a: preferences are a flat map of name to text
  • 0037 versioning — extends the unreleased v2 package from feat: standardize the user accounts, profile image, verification and name-change API #39297; no v1 file changed
  • 0038 URL structure — preferences addressed under the account; plural email_opt_ins; trailing slashes
  • OEP-66 queryset scoping — service-backed; no view queryset; scoping is the permission pair
  • OEP-69 conventions — envelope, strict parameters, snake_case

In-place edits

No v1 preference view, serializer, URLconf or test is in the diff. Outside a version directory:

file why
cms/lib/spectacular.py two comment lines saying why Studio's list leaves out the preference addresses
cms/lib/tests/test_spectacular.py new tests: Studio publishes the six preference operations as current and marks the others
lms/lib/tests/test_spectacular.py new test classes for the v1 preference bodies, the marks and the opt-in twin
openedx/core/djangoapps/user_api/schema.py (from #39297) rows for the three superseded preference paths and their bodies

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: true in 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

  • The v1 member address answers a restricted-application token with 401. v2 answers 403, because it reads JWT and then refuses the token.
  • A whitespace-padded name at the member address answers 404, as v1 does, rather than a 400 under key. Admission comes first, so a stranger gets 401/403.
  • The versions gate run against feat: standardize the user accounts, profile image, verification and name-change API #39297 reports v2 files as "modified in place". This is the same unreleased version, and against master the gate passes.

Known pre-existing behaviour, left as it is

Evidence

The full tables are in the evidence comment.

Follow-ups

These are shared with #39297:

  • edx-drf-extensions#599, the page schema.
  • An edx-drf-extensions issue for nested validation detail flattened with str().
  • Catalog types for 405/406/415 and the unparsable body.
  • A Studio replacement for the header language selector, before Studio's v1 preference addresses can go.

@Abdul-Muqadim-Arbisoft

Abdul-Muqadim-Arbisoft commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor Author

Reference detail for this pull request

The description is over GitHub's 65,536-character limit, so these five reference sections live here.
Nothing was omitted: each one is complete, and only §3 of the description is shortened — its
full text is C1 below. Section numbers §1-§11 refer to the description; C1-C6 refer to
this comment.

section what it carries
C1 every caller-visible change, all 37 items, address by address
C2 the four document comparisons and the six superseded operations, before and after
C3 follow-ups: library-first items, next-version candidates, risks, SDK
C4 the compliance matrix's evidence column, and the test inventory
C5 authorization detail: the three layers, the guard harnesses, the me row
C6 what schema generation reports and no gate scores

C1 — Caller-visible changes, the complete enumeration

[T] = pinned by a test in this diff; [S] = also visible in the published schema.

Cross-cutting (all six operations)

  1. Every refusal is the RFC 9457 envelope. The superseded addresses answer five shapes —
    {"field_errors": …}, {"developer_message", "user_message"}, DRF's {"detail"}, bare text, and
    no body at all for 403/404. [T][S]
  2. A query parameter the operation does not read is refused 400 naming the parameters it does read,
    where the superseded addresses ignore it. This includes page, page_size, view and fields:
    the document is a singleton, not a page, and is not shaped. [T][S]
  3. Authentication is JwtAuthentication — the library class the platform's own default pair is
    built on — plus the wider session class SessionAuthenticationAllowInactiveUser;
    BearerAuthenticationAllowInactiveUser is dropped. The five preference operations and the
    opt-in therefore gain JWT where the superseded member address and the opt-in had none. The
    platform's monitoring attribute using_default_auth_classes is deliberately not recorded by
    these operations: a view that declares its own classes is not one the default pair serves, and
    the attribute exists to identify the endpoints it does. [T]
  4. A read by an administrator also requires that the administrator's own account still be active — a
    deliberate tightening of the privilege half, consistent with Phase B. [T]
  5. Work that was asked for correctly and failed anyway is 500 internal with one stable sentence and
    the specifics in the log, where the superseded addresses answer 400 with the internal message in
    the body. [T][S]
  6. me beneath an account is read as a stored name, as on Phase B's other sub-resources: a
    learner is refused 403, an administrator is told 404, and an account actually named me is
    served. [T][S]

GET /api/user/v1/preferences/{username} → GET …/accounts/{username}/preferences/

  1. The names come back in one order — sorted by name, character by character and by the code of
    each character
    , so a name beginning with a digit, a capital or an underscore comes before one
    beginning in lower case; the superseded address answers in database order. It is not the order a
    reader of English expects and the published description says so. JSON object member order carries
    no meaning for a client, so nothing breaks — it removes diff noise. [T][S]
  2. The body is published as {"type": "object", "additionalProperties": {"type": "string"}}, and a
    real response is validated against it. [S][T]

PATCH …/preferences/{username} → PATCH …/accounts/{username}/preferences/

  1. A value that is neither text nor null is refused 400 under the name that carried it; the
    superseded address spells a number out and stores "5". [T][S]
  2. The refusal is keyed by preference name and carries the service's user-facing message; the
    superseded address nests {"developer_message", "user_message"} under field_errors. The
    developer message is logged, not published. [T]
  3. A body that is not an object, and a body that names no preference, are each refused 400 with a
    message under non_field_errors (the superseded address refuses both too, in its own shape). [T]
  4. A change is still a merge patch and only a merge patch: application/json is 415. [T][S]

GET|PUT|DELETE …/{preference_key} → …/preferences/{key}/

  1. One preference is answered as {"key", "value"} and stored from {"value"}, where the superseded
    address answers and reads a bare JSON scalar. There is no reverse() or path-literal caller of
    these three operations anywhere in the repository. [T][S]
  2. Every name that carries no slash can be addressed, including pref-lang and the profile
    MFE's dotted names (visibility.bio). The superseded route's key segment matches
    [a-zA-Z0-9_]+ and cannot carry those at all, so a client that depended on its 404 for such a
    name sees 200 here. The limit of the widening is the slash: a name is the whole segment and a
    segment ends at a slash, so a stored name carrying one is addressable at neither version —
    it reaches the JSON-404 fallback, and reverse() refuses to build the address. Such a name is
    stored, read and removed with the whole document instead, which is also the only way one
    arrives; the published key description says so. The boundary is pinned at the route
    and over the wire on all three member methods, for a slash inside the name, at either end of it
    and doubled (a/b, x/, /x, a//b), and in the percent-encoded spelling as well as the raw
    one — encoding it does not reach an address either, because a request path is resolved decoded,
    which puts the slash back. [T][S]
  3. No name is reserved: …/preferences/email_opt_in/ and …/preferences/time_zones/ are ordinary
    preference names, because the collections that bear those names stand at the top of this version
    where no name can shadow them. [T]
  4. An empty value is refused 400 under value; a value the preference refuses (an unknown time
    zone) is refused 400 under value with the service's message. A name nothing can be stored
    under is refused under key instead, because that is the part of the request that carried
    it and a caller cannot mend it by changing the value they sent. [T][S]
  5. The value is read in the media types the platform reads everywhere (JSON and the two form types);
    a merge patch is 415 and PATCH on one preference is 405. [T][S]

POST …/preferences/email_opt_in/ → POST /api/user/v2/email_opt_ins/

  1. The address is a plural noun collection: the action name leaves the path (ADR 0038 rule 10). [T][S]
  2. It answers 204 with no body; the superseded address answers 200 with an empty text/html
    body. [T][S]
  3. The body field is course_key (OEP-68). course_id is simply not read here; the superseded
    address keeps reading it for its whole deprecation window. A course key written in the earlier
    slash-separated form is still accepted, by both addresses. A key that parses and names something
    other than a course is refused 400 under course_key by both: the platform's key reader
    accepts library-v1:edX+lib as a CourseKey for historical reasons, and such keys say of
    themselves that they are not courses (is_course), so the choice is not recorded against the
    organization of a library the way the superseded address refuses it (400 No course '…' found).
    A choice is recorded against the organization running a course, which is what the field
    documents. [T][S]
  4. email_opt_in is read strictly: a JSON boolean, or the text true or false in any case.
    Everything else is refused 400 under email_opt_in — "Banana", and also the further
    spellings a boolean field normally admits (1, on, yes, t, y and 0, off, no, f,
    n). The superseded address records a choice not to receive messages for every one of them,
    because it compares the text with "true" and stores False otherwise, so reading them as a
    boolean field does would have reversed five of them — an opt-in recorded where the
    superseded address recorded an opt-out, with nothing in the answer to show it. A refusal a
    caller can see was preferred to either reading. The in-repo caller sends true or false
    (lms/static/js/student_account/views/FinishAuthView.js:110), so no known client is affected;
    external clients sending another spelling now get a 400 naming the property instead of a
    silent 204. [T][S]
  5. A JSON body is read, as well as the form-encoded body the enrolment page submits; the superseded
    address reads request.POST only and answers 400 Missing POST parameters to JSON. A form body
    that names a course and no choice is refused 400 under email_opt_in, as the superseded
    address refuses it: a boolean field would otherwise have read the absent member as an unticked
    checkbox and recorded an opt-out over a stored opt-in (measured: True → False, 204), where
    the superseded address leaves the row untouched. An empty value (email_opt_in=) is refused the
    same way. [T][S]
  6. An anonymous caller is refused 401; the superseded address answers 403. [T][S]
  7. An account carrying no profile is answered 404 (the consent rule is read from the profile);
    the superseded address lets that escape as a server fault. The row a choice is kept in is opened
    before that rule is read, so where requests are served in a transaction — which is how this
    platform serves them — nothing is left behind
    by the refusal; where each statement stands on
    its own, both versions leave the identical row carrying no choice at all, which a reader
    comparing it with the word for wanting the messages reads as not wanting them. Both sides are
    driven (test_an_account_that_carries_no_profile_is_reported_absent,
    test_the_row_a_refusal_opened_stands_where_a_statement_stands_on_its_own,
    test_neither_address_records_a_choice_for_an_account_carrying_no_profile). [T][S]
  8. @ensure_csrf_cookie is not reproduced, and the session class still holds a session to the
    request token the site hands out with it: a session POST carrying none of that token is refused
    403 with the envelope, and that refusal is now published by the operation, so a generated
    client has a branch for the only refusal a browser session meets at this address. The token
    itself comes from signing in, not from anything this version serves, which is driven end to end
    here — the sign-in address sets the cookie, the sign-in is accepted with it, and the choice is
    then recorded 204 with the same token. [T][S]
  9. No account is named anywhere in the request: the choice is the caller's. A body carrying
    username changes only the caller's row, and a parameter this operation does not read is
    refused 400 like any other. [T]

Naming

  1. Route names account_preference_list, account_preference_detail, email_opt_in_list in the
    user_v2 namespace. No existing name is renamed or dropped: preferences_api,
    preferences_detail_api, preferences_email_opt_in and preferences_email_opt_in_legacy all
    keep their names, their views and their addresses. [T]
  2. Both reads of the conforming resource are published under a name of their own, with each
    document's own prefix
    : the service's own document publishes
    v2_accounts_preferences_retrieve for the whole document and
    v2_accounts_preferences_retrieve_one for one preference, and the service-wide document
    publishes api_user_v2_accounts_preferences_retrieve and
    api_user_v2_accounts_preferences_retrieve_one, so all five operations of the resource share
    one prefix within each document. The two addresses tokenize to one name, which an assembled
    document tells apart with a numeral handed out in the order the two addresses sort, so the name
    a client imports would say which address sorted first rather than what the operation reads. The
    name is set by two entries in the schema module's rename map — one per document — rather than
    by an operation_id pinned on the view, so the generator still derives every other name. The
    two reads of the superseded resource are named apart the same way in the service's own document
    (v1_preferences_retrieve and v1_preferences_retrieve_one, a third rename-map entry), while
    the service-wide document keeps every name it already publishes for them, numeral included.
    Against origin/master: nothing renamed, nothing removed (§11). [S][T]

Bounds, and the client faults that used to read as server faults

  1. A value is not bounded, and neither is the number of names one change may carry.
    UserPreference.value is a TextField (user_api/models.py:44), the superseded addresses cap
    neither, and this platform switches Django's own request guards off
    (DATA_UPLOAD_MAX_MEMORY_SIZE = None, DATA_UPLOAD_MAX_NUMBER_FIELDS = None,
    openedx/envs/common.py:152-153), so no cap is introduced here: what a field may hold belongs
    to the model that holds it, and the bounded-collection rule bounds a list response, not a
    field value. The measured bound is the one the web tier does not impose, and these are the
    costs that follow, measured on this branch: a read of the document costs the same number of
    statements whatever the document holds — and the same number the superseded address costs,
    measured against it in the same run rather than written down as a figure — while its size is
    the names and values themselves
    (251 B at 10 names, 2.5 KB at 100, 12.5 KB at 500, for nine-character names); a merge patch is
    about five statements a name, inside one transaction (10 names 72 statements in 0.09 s, 100
    names 516 in 0.22 s, 500 names 2516 in 0.84 s); and a value of 5,000,000 characters is stored
    with 204 and read back whole. The superseded addresses behave the same way at the same cost,
    which is why this is declared rather than capped: a cap would refuse an account whose own
    plugins store many names, and the addresses being replaced impose none.
  2. The one stored-shape limit now surfaced is the name: the column is max_length=255, so a
    name of 255 characters is stored and a longer one is refused 400 — under the name itself in a
    merge patch, and under key at the member address, which is the part of the request
    that carried it. The superseded addresses refuse it too, by letting the service report it in
    {"developer_message", "user_message"} with neither the body member nor the address part
    named. A read or a removal at such an address still answers 404, because nothing is stored
    under it. [T][S]
  3. Text carrying a character that stands for half of a pair is refused 400 with the envelope: the
    character has no encoding of its own, so it can be neither stored nor carried back. A value is
    refused under the name that carried it, and a name carrying one is refused against the body,
    because the answer could not name that member. The superseded document address answers
    500 text/html for all three forms of it (measured in this run: value, name, name alone), which
    is the service's own error page and not a body a client that asked for JSON can read. [T]
  4. A course_key that is not text is refused 400 naming course_key. The platform's course-key
    field reads a key by splitting the text, so a number, a list or an object reached it as a server
    fault (500 internal) before this round; the superseded address never saw one, because it reads
    form fields only and answers 400 to a JSON body at all. [T]
  5. A course whose organization is longer than the column the choice is recorded in
    (UserOrgTag.org, max_length=255) is refused 400 naming course_key. The organization is
    taken from the course key, and no key reader bounds it, so a 300-character organization was
    accepted with 204 on SQLite and would have reached a strict database as a write that fails
    below the handler — a client fault answered as a server fault. A 255-character organization is
    still recorded. The superseded address accepts the same body. [T]

What a request does below the handler

  1. A request carrying the language cookie stores the caller's language and announces that
    change.
    The platform syncs the language a user picked from its cookie into that user's own
    pref-lang row from middleware, which runs before any view and on every method, so a
    request to either preference address reaches it exactly as a request to any other LMS address
    does — a GET or HEAD, and a PATCH, PUT or DELETE alike. The row's
    post_save then sends the platform's field-change signal (USER_FIELDS_CHANGED) and emits one
    edx.user.settings.changed analytics event for the caller's own account. The signal has one
    in-repo receiver in the LMS, user_authn.signals.user_fields_changed, which calls
    segment.identify(user.id, {"pref-lang": …}) — a no-op on a deployment that configures no
    Segment key. Nothing here is new or specific to this version: the superseded addresses write
    and announce the identical row for the identical request, which the parity capture asserts from
    both sides. It is declared because it is a write, a signal and an event on a read, all three of
    which these addresses would otherwise claim not to have; C3 names the platform change that
    would remove all three. [T] covers the write, the signal and the event, each asserted by
    value; what the receiver then does is read from the code and not driven here. One
    consequence a client can see: with the cookie present, DELETE …/preferences/pref-lang/ is
    answered 204 even when the account stored nothing under that name, because the row exists by
    the time the handler looks; without the cookie the same request is answered 404. Nothing is
    left behind either way — removing pref-lang removes the row the middleware had just written,
    and a null for it in the document does the same
    (test_a_name_stored_only_by_the_middleware_is_removed_rather_than_reported_absent,
    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, which drives a DELETE of
    another name and finds the language stored by the time it answers).

What the document publishes for a body that has no fixed members

  1. The preference document is published as the open-ended object it is, and the published shape
    is the one the generator derives from the field that carries it.
    The body has no fixed set of
    members — any name an account's own features store a value under is one — so it is published as
    {"type": "object", "additionalProperties": {"type": "string"}} on the read and the same with
    nullable: true on the merge patch, rather than as a named component with properties. Those two
    shapes are what drf-spectacular derives from AccountPreferenceDocumentField and
    AccountPreferenceChangesField when it maps them as part of a serializer, byte for byte
    (measured). They are stated as raw schemas and attached to those fields with
    @extend_schema_field because drf-spectacular 0.30.0 maps a bare field only inside a serializer:
    handed one as a body it publishes additionalProperties: {} and Unspecified response body
    (C3). What holds the stated shape and the enforced one together is tests, in both directions:
    a change to either published shape fails three literal pins across both documents
    (SupersededBodyTest, SupersededBodyInTheServiceWideDocumentTest,
    test_the_preference_document_is_published_as_the_open_ended_object_it_is), and a change to what
    the fields read fails five, including the one that validates a real request against the published
    request schema and then drives it (test_a_merge_patch_the_endpoint_carries_out_is_one_the_request_body_takes).
    Reading the body as that object is also what refuses one that is not an object and one that names
    nothing to change: those two refusals are the field's, with only their wording set here, and it
    is the wording this version already answers with for the account merge patch. [T][S]

Asking what an address answers

  1. A request asking what one of these addresses answers (OPTIONS) is guarded as a read of it:
    the addressed account and an active administrator are answered 200, another learner 403 and
    an anonymous caller 401, each with the envelope the matching read answers. The actions block
    describing a change is built behind a second check carrying that change's own method, so a
    caller who may read the address but not write it is answered without it. What the superseded
    addresses answer to such a request is not driven here and is not claimed
    (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). [T]
  2. Known limitation, declared. DRF builds that actions block from the response
    serializer, so the member address's actions.PUT names key and value, while the request
    body this version reads and publishes is value alone. The published document is authoritative.
    It is recorded rather than worked around, because the alternative is hand-writing the block.
    [T]

C2 — The two documents this service publishes, operation by operation

The table is read while a document is generated, so it applies to the narrow LMS document
(SPECTACULAR_SETTINGS, served at /lms-api/) and to the service-wide /api-docs document,
which publishes every endpoint in the service and is what docs/lms-openapi.yaml is generated from.
The LMS document did not publish these six operations before; the service-wide one did. Both were
regenerated under lms.envs.test on origin/master @ 87cd3811a4, on this branch's parent and on
this branch, and compared with schema_diff.py compare:

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-extensions 10.9.0 ships no equivalent —
    neither the authenticated check nor the administrator check reads is_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_type and
    _get_response_for_code have no field branch, so handing one of these DictFields to
    OpenApiResponse or to a media-type map publishes {"type": "object", "additionalProperties": {}}
    with description: Unspecified response body and emits could 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's pref-lang row, and that row's post_save sends
    USER_FIELDS_CHANGED and emits one edx.user.settings.changed event. The signal's one in-repo
    LMS receiver is user_authn.signals.user_fields_changed (registered as a plugin signal receiver in
    user_authn/apps.py), which calls segment.identify for 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 in lang_pref middleware, 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 a fields-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, so a/b, x/, /x and a//b are 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 a fields-style selection over the document. Pinned as it stands by
    test_a_name_carrying_a_slash_is_not_addressed_as_a_preference and
    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 at GET /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.py mounts the v1
    package and the Studio header reverses preferences_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 under lms.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 same 163 (89 unique) and
    36 (6 unique), and origin/master reports 56 (30 unique) / 28 (5 unique) for 19 paths. Every one of the ten new messages reads could not resolve authenticator <class …>. There was no OpenApiAuthenticationExtension registered for that class —
    six for the three superseded views this phase publishes (PreferencesView three times,
    PreferencesDetailView twice, UpdateEmailOptInPreference once) and four for the two views it
    adds (AccountPreferenceViewSet and EmailOptInViewSet, 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 missing OpenApiAuthenticationExtension for 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 Faraz32123 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 IsAddressedUser on all six, but the opt-in only has IsAuthenticated. 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):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_sent
  • PreferenceMemberParityTests::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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread lms/lib/spectacular.py Outdated
"/api/user/v1/users/{id}/",
"/api/user/v1/user_prefs/",
"/api/user/v1/user_prefs/{id}/",
"/api/user/v1/preferences/{username}",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right. Studio's header language selector reverses preferences_api on its own host, and Studio serves no /api/user/v2/.

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.
@Abdul-Muqadim-Arbisoft
Abdul-Muqadim-Arbisoft force-pushed the feat/api-adr-user-v2-phase-c branch from 9eba272 to ce73cb8 Compare November 1, 2026 15:51
@Abdul-Muqadim-Arbisoft

Copy link
Copy Markdown
Contributor Author

Reference detail for this pull request

The description is over GitHub's 65,536-character limit, so these five reference sections live here.
Nothing was omitted: each one is complete, and only §3 of the description is shortened — its
full text is C1 below. Section numbers §1-§11 refer to the description; C1-C6 refer to
this comment.

section what it carries
C1 every caller-visible change, all 37 items, address by address
C2 the four document comparisons and the six superseded operations, before and after
C3 follow-ups: library-first items, next-version candidates, risks, SDK
C4 the compliance matrix's evidence column, and the test inventory
C5 authorization detail: the three layers, the guard harnesses, the me row
C6 what schema generation reports and no gate scores

C1 — Caller-visible changes, the complete enumeration

[T] = pinned by a test in this diff; [S] = also visible in the published schema.

Cross-cutting (all six operations)

  1. Every refusal is the RFC 9457 envelope. The superseded addresses answer five shapes —
    {"field_errors": …}, {"developer_message", "user_message"}, DRF's {"detail"}, bare text, and
    no body at all for 403/404. [T][S]
  2. A query parameter the operation does not read is refused 400 naming the parameters it does read,
    where the superseded addresses ignore it. This includes page, page_size, view and fields:
    the document is a singleton, not a page, and is not shaped. [T][S]
  3. Authentication is JwtAuthentication — the library class the platform's own default pair is
    built on — plus the wider session class SessionAuthenticationAllowInactiveUser;
    BearerAuthenticationAllowInactiveUser is dropped. The five preference operations and the
    opt-in therefore gain JWT where the superseded member address and the opt-in had none. The
    platform's monitoring attribute using_default_auth_classes is deliberately not recorded by
    these operations: a view that declares its own classes is not one the default pair serves, and
    the attribute exists to identify the endpoints it does. [T]
  4. A read by an administrator also requires that the administrator's own account still be active — a
    deliberate tightening of the privilege half, consistent with Phase B. [T]
  5. Work that was asked for correctly and failed anyway is 500 internal with one stable sentence and
    the specifics in the log, where the superseded addresses answer 400 with the internal message in
    the body. [T][S]
  6. me beneath an account is read as a stored name, as on Phase B's other sub-resources: a
    learner is refused 403, an administrator is told 404, and an account actually named me is
    served. [T][S]

GET /api/user/v1/preferences/{username} → GET …/accounts/{username}/preferences/

  1. The names come back in one order — sorted by name, character by character and by the code of
    each character
    , so a name beginning with a digit, a capital or an underscore comes before one
    beginning in lower case; the superseded address answers in database order. It is not the order a
    reader of English expects and the published description says so. JSON object member order carries
    no meaning for a client, so nothing breaks — it removes diff noise. [T][S]
  2. The body is published as {"type": "object", "additionalProperties": {"type": "string"}}, and a
    real response is validated against it. [S][T]

PATCH …/preferences/{username} → PATCH …/accounts/{username}/preferences/

  1. A value that is neither text nor null is refused 400 under the name that carried it; the
    superseded address spells a number out and stores "5". [T][S]
  2. The refusal is keyed by preference name and carries the service's user-facing message; the
    superseded address nests {"developer_message", "user_message"} under field_errors. The
    developer message is logged, not published. [T]
  3. A body that is not an object, and a body that names no preference, are each refused 400 with a
    message under non_field_errors (the superseded address refuses both too, in its own shape). [T]
  4. A change is still a merge patch and only a merge patch: application/json is 415. [T][S]

GET|PUT|DELETE …/{preference_key} → …/preferences/{key}/

  1. One preference is answered as {"key", "value"} and stored from {"value"}, where the superseded
    address answers and reads a bare JSON scalar. There is no reverse() or path-literal caller of
    these three operations anywhere in the repository. [T][S]
  2. Every name that carries no slash can be addressed, including pref-lang and the profile
    MFE's dotted names (visibility.bio). The superseded route's key segment matches
    [a-zA-Z0-9_]+ and cannot carry those at all, so a client that depended on its 404 for such a
    name sees 200 here. The limit of the widening is the slash: a name is the whole segment and a
    segment ends at a slash, so a stored name carrying one is addressable at neither version —
    it reaches the JSON-404 fallback, and reverse() refuses to build the address. Such a name is
    stored, read and removed with the whole document instead, which is also the only way one
    arrives; the published key description says so. The boundary is pinned at the route
    and over the wire on all three member methods, for a slash inside the name, at either end of it
    and doubled (a/b, x/, /x, a//b), and in the percent-encoded spelling as well as the raw
    one — encoding it does not reach an address either, because a request path is resolved decoded,
    which puts the slash back. [T][S]
  3. No name is reserved: …/preferences/email_opt_in/ and …/preferences/time_zones/ are ordinary
    preference names, because the collections that bear those names stand at the top of this version
    where no name can shadow them. [T]
  4. An empty value is refused 400 under value; a value the preference refuses (an unknown time
    zone) is refused 400 under value with the service's message. A name nothing can be stored
    under is refused under key instead, because that is the part of the request that carried
    it and a caller cannot mend it by changing the value they sent. [T][S]
  5. The value is read in the media types the platform reads everywhere (JSON and the two form types);
    a merge patch is 415 and PATCH on one preference is 405. [T][S]

POST …/preferences/email_opt_in/ → POST /api/user/v2/email_opt_ins/

  1. The address is a plural noun collection: the action name leaves the path (ADR 0038 rule 10). [T][S]
  2. It answers 204 with no body; the superseded address answers 200 with an empty text/html
    body. [T][S]
  3. The body field is course_key (OEP-68). course_id is simply not read here; the superseded
    address keeps reading it for its whole deprecation window. A course key written in the earlier
    slash-separated form is still accepted, by both addresses. A key that parses and names something
    other than a course is refused 400 under course_key by both: the platform's key reader
    accepts library-v1:edX+lib as a CourseKey for historical reasons, and such keys say of
    themselves that they are not courses (is_course), so the choice is not recorded against the
    organization of a library the way the superseded address refuses it (400 No course '…' found).
    A choice is recorded against the organization running a course, which is what the field
    documents. [T][S]
  4. email_opt_in is read strictly: a JSON boolean, or the text true or false in any case.
    Everything else is refused 400 under email_opt_in — "Banana", and also the further
    spellings a boolean field normally admits (1, on, yes, t, y and 0, off, no, f,
    n). The superseded address records a choice not to receive messages for every one of them,
    because it compares the text with "true" and stores False otherwise, so reading them as a
    boolean field does would have reversed five of them — an opt-in recorded where the
    superseded address recorded an opt-out, with nothing in the answer to show it. A refusal a
    caller can see was preferred to either reading. The in-repo caller sends true or false
    (lms/static/js/student_account/views/FinishAuthView.js:110), so no known client is affected;
    external clients sending another spelling now get a 400 naming the property instead of a
    silent 204. [T][S]
  5. A JSON body is read, as well as the form-encoded body the enrolment page submits; the superseded
    address reads request.POST only and answers 400 Missing POST parameters to JSON. A form body
    that names a course and no choice is refused 400 under email_opt_in, as the superseded
    address refuses it: a boolean field would otherwise have read the absent member as an unticked
    checkbox and recorded an opt-out over a stored opt-in (measured: True → False, 204), where
    the superseded address leaves the row untouched. An empty value (email_opt_in=) is refused the
    same way. [T][S]
  6. An anonymous caller is refused 401; the superseded address answers 403. [T][S]
  7. An account carrying no profile is answered 404 (the consent rule is read from the profile);
    the superseded address lets that escape as a server fault. The row a choice is kept in is opened
    before that rule is read, so where requests are served in a transaction — which is how this
    platform serves them — nothing is left behind
    by the refusal; where each statement stands on
    its own, both versions leave the identical row carrying no choice at all, which a reader
    comparing it with the word for wanting the messages reads as not wanting them. Both sides are
    driven (test_an_account_that_carries_no_profile_is_reported_absent,
    test_the_row_a_refusal_opened_stands_where_a_statement_stands_on_its_own,
    test_neither_address_records_a_choice_for_an_account_carrying_no_profile). [T][S]
  8. @ensure_csrf_cookie is not reproduced, and the session class still holds a session to the
    request token the site hands out with it: a session POST carrying none of that token is refused
    403 with the envelope, and that refusal is now published by the operation, so a generated
    client has a branch for the only refusal a browser session meets at this address. The token
    itself comes from signing in, not from anything this version serves, which is driven end to end
    here — the sign-in address sets the cookie, the sign-in is accepted with it, and the choice is
    then recorded 204 with the same token. [T][S]
  9. No account is named anywhere in the request: the choice is the caller's. A body carrying
    username changes only the caller's row, and a parameter this operation does not read is
    refused 400 like any other. [T]

Naming

  1. Route names account_preference_list, account_preference_detail, email_opt_in_list in the
    user_v2 namespace. No existing name is renamed or dropped: preferences_api,
    preferences_detail_api, preferences_email_opt_in and preferences_email_opt_in_legacy all
    keep their names, their views and their addresses. [T]
  2. Both reads of the conforming resource are published under a name of their own, with each
    document's own prefix
    : the service's own document publishes
    v2_accounts_preferences_retrieve for the whole document and
    v2_accounts_preferences_retrieve_one for one preference, and the service-wide document
    publishes api_user_v2_accounts_preferences_retrieve and
    api_user_v2_accounts_preferences_retrieve_one, so all five operations of the resource share
    one prefix within each document. The two addresses tokenize to one name, which an assembled
    document tells apart with a numeral handed out in the order the two addresses sort, so the name
    a client imports would say which address sorted first rather than what the operation reads. The
    name is set by two entries in the schema module's rename map — one per document — rather than
    by an operation_id pinned on the view, so the generator still derives every other name. The
    two reads of the superseded resource are named apart the same way in the service's own document
    (v1_preferences_retrieve and v1_preferences_retrieve_one, a third rename-map entry), while
    the service-wide document keeps every name it already publishes for them, numeral included.
    Against origin/master: nothing renamed, nothing removed (§11). [S][T]

Bounds, and the client faults that used to read as server faults

  1. A value is not bounded, and neither is the number of names one change may carry.
    UserPreference.value is a TextField (user_api/models.py:44), the superseded addresses cap
    neither, and this platform switches Django's own request guards off
    (DATA_UPLOAD_MAX_MEMORY_SIZE = None, DATA_UPLOAD_MAX_NUMBER_FIELDS = None,
    openedx/envs/common.py:152-153), so no cap is introduced here: what a field may hold belongs
    to the model that holds it, and the bounded-collection rule bounds a list response, not a
    field value. The measured bound is the one the web tier does not impose, and these are the
    costs that follow, measured on this branch: a read of the document costs the same number of
    statements whatever the document holds — and the same number the superseded address costs,
    measured against it in the same run rather than written down as a figure — while its size is
    the names and values themselves
    (251 B at 10 names, 2.5 KB at 100, 12.5 KB at 500, for nine-character names); a merge patch is
    about five statements a name, inside one transaction (10 names 72 statements in 0.09 s, 100
    names 516 in 0.22 s, 500 names 2516 in 0.84 s); and a value of 5,000,000 characters is stored
    with 204 and read back whole. The superseded addresses behave the same way at the same cost,
    which is why this is declared rather than capped: a cap would refuse an account whose own
    plugins store many names, and the addresses being replaced impose none.
  2. The one stored-shape limit now surfaced is the name: the column is max_length=255, so a
    name of 255 characters is stored and a longer one is refused 400 — under the name itself in a
    merge patch, and under key at the member address, which is the part of the request
    that carried it. The superseded addresses refuse it too, by letting the service report it in
    {"developer_message", "user_message"} with neither the body member nor the address part
    named. A read or a removal at such an address still answers 404, because nothing is stored
    under it. [T][S]
  3. Text carrying a character that stands for half of a pair is refused 400 with the envelope: the
    character has no encoding of its own, so it can be neither stored nor carried back. A value is
    refused under the name that carried it, and a name carrying one is refused against the body,
    because the answer could not name that member. The superseded document address answers
    500 text/html for all three forms of it (measured in this run: value, name, name alone), which
    is the service's own error page and not a body a client that asked for JSON can read. [T]
  4. A course_key that is not text is refused 400 naming course_key. The platform's course-key
    field reads a key by splitting the text, so a number, a list or an object reached it as a server
    fault (500 internal) before this round; the superseded address never saw one, because it reads
    form fields only and answers 400 to a JSON body at all. [T]
  5. A course whose organization is longer than the column the choice is recorded in
    (UserOrgTag.org, max_length=255) is refused 400 naming course_key. The organization is
    taken from the course key, and no key reader bounds it, so a 300-character organization was
    accepted with 204 on SQLite and would have reached a strict database as a write that fails
    below the handler — a client fault answered as a server fault. A 255-character organization is
    still recorded. The superseded address accepts the same body. [T]

What a request does below the handler

  1. A request carrying the language cookie stores the caller's language and announces that
    change.
    The platform syncs the language a user picked from its cookie into that user's own
    pref-lang row from middleware, which runs before any view and on every method, so a
    request to either preference address reaches it exactly as a request to any other LMS address
    does — a GET or HEAD, and a PATCH, PUT or DELETE alike. The row's
    post_save then sends the platform's field-change signal (USER_FIELDS_CHANGED) and emits one
    edx.user.settings.changed analytics event for the caller's own account. The signal has one
    in-repo receiver in the LMS, user_authn.signals.user_fields_changed, which calls
    segment.identify(user.id, {"pref-lang": …}) — a no-op on a deployment that configures no
    Segment key. Nothing here is new or specific to this version: the superseded addresses write
    and announce the identical row for the identical request, which the parity capture asserts from
    both sides. It is declared because it is a write, a signal and an event on a read, all three of
    which these addresses would otherwise claim not to have; C3 names the platform change that
    would remove all three. [T] covers the write, the signal and the event, each asserted by
    value; what the receiver then does is read from the code and not driven here. One
    consequence a client can see: with the cookie present, DELETE …/preferences/pref-lang/ is
    answered 204 even when the account stored nothing under that name, because the row exists by
    the time the handler looks; without the cookie the same request is answered 404. Nothing is
    left behind either way — removing pref-lang removes the row the middleware had just written,
    and a null for it in the document does the same
    (test_a_name_stored_only_by_the_middleware_is_removed_rather_than_reported_absent,
    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, which drives a DELETE of
    another name and finds the language stored by the time it answers).

What the document publishes for a body that has no fixed members

  1. The preference document is published as the open-ended object it is, and the published shape
    is the one the generator derives from the field that carries it.
    The body has no fixed set of
    members — any name an account's own features store a value under is one — so it is published as
    {"type": "object", "additionalProperties": {"type": "string"}} on the read and the same with
    nullable: true on the merge patch, rather than as a named component with properties. Those two
    shapes are what drf-spectacular derives from AccountPreferenceDocumentField and
    AccountPreferenceChangesField when it maps them as part of a serializer, byte for byte
    (measured). They are stated as raw schemas and attached to those fields with
    @extend_schema_field because drf-spectacular 0.30.0 maps a bare field only inside a serializer:
    handed one as a body it publishes additionalProperties: {} and Unspecified response body
    (C3). What holds the stated shape and the enforced one together is tests, in both directions:
    a change to either published shape fails three literal pins across both documents
    (SupersededBodyTest, SupersededBodyInTheServiceWideDocumentTest,
    test_the_preference_document_is_published_as_the_open_ended_object_it_is), and a change to what
    the fields read fails five, including the one that validates a real request against the published
    request schema and then drives it (test_a_merge_patch_the_endpoint_carries_out_is_one_the_request_body_takes).
    Reading the body as that object is also what refuses one that is not an object and one that names
    nothing to change: those two refusals are the field's, with only their wording set here, and it
    is the wording this version already answers with for the account merge patch. [T][S]

Asking what an address answers

  1. A request asking what one of these addresses answers (OPTIONS) is guarded as a read of it:
    the addressed account and an active administrator are answered 200, another learner 403 and
    an anonymous caller 401, each with the envelope the matching read answers. The actions block
    describing a change is built behind a second check carrying that change's own method, so a
    caller who may read the address but not write it is answered without it. What the superseded
    addresses answer to such a request is not driven here and is not claimed
    (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). [T]
  2. Known limitation, declared. DRF builds that actions block from the response
    serializer, so the member address's actions.PUT names key and value, while the request
    body this version reads and publishes is value alone. The published document is authoritative.
    It is recorded rather than worked around, because the alternative is hand-writing the block.
    [T]

C2 — The two documents this service publishes, operation by operation

The table is read while a document is generated, so it applies to the narrow LMS document
(SPECTACULAR_SETTINGS, served at /lms-api/) and to the service-wide /api-docs document,
which publishes every endpoint in the service and is what docs/lms-openapi.yaml is generated from.
The LMS document did not publish these six operations before; the service-wide one did. Both were
regenerated under lms.envs.test on origin/master @ 87cd3811a4, on this branch's parent and on
this branch, and compared with schema_diff.py compare:

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 operationId is renamed in the service-wide document.
    GET /api/user/v2/user_preferences/{username},{key}/ moves from
    v2_user_preferences_retrieve to api_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. master publishes 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-docs during this series must be regenerated.
  • A pattern is added to a phase B address. The username path 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-extensions 10.9.0 ships no equivalent —
    neither the authenticated check nor the administrator check reads is_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_type and
    _get_response_for_code have no field branch, so handing one of these DictFields to
    OpenApiResponse or to a media-type map publishes {"type": "object", "additionalProperties": {}}
    with description: Unspecified response body and emits could 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's pref-lang row, and that row's post_save sends
    USER_FIELDS_CHANGED and emits one edx.user.settings.changed event. The signal's one in-repo
    LMS receiver is user_authn.signals.user_fields_changed (registered as a plugin signal receiver in
    user_authn/apps.py), which calls segment.identify for 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 in lang_pref middleware, 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 a fields-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, so a/b, x/, /x and a//b are 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 a fields-style selection over the document. Pinned as it stands by
    test_a_name_carrying_a_slash_is_not_addressed_as_a_preference and
    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 at GET /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.py mounts the v1
    package and the Studio header reverses preferences_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 under lms.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 same 163 (89 unique) and
    36 (6 unique), and origin/master reports 56 (30 unique) / 28 (5 unique) for 19 paths. Every one of the ten new messages reads could not resolve authenticator <class …>. There was no OpenApiAuthenticationExtension registered for that class —
    six for the three superseded views this phase publishes (PreferencesView three times,
    PreferencesDetailView twice, UpdateEmailOptInPreference once) and four for the two views it
    adds (AccountPreferenceViewSet and EmailOptInViewSet, 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 missing OpenApiAuthenticationExtension for 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.

@Abdul-Muqadim-Arbisoft

Copy link
Copy Markdown
Contributor Author

Phase C — authorization and gate evidence

Moved out of the pull request description, which GitHub caps at 65,536 characters.

10. Authorization

Every legacy check has a named home. On its own terms: each operation selects a record by the
username in the address, so that is the only identifier the permission reads, compared character for
character.
The left column names the check each class is answerable for; how the superseded
version arranged its own is recorded in the area survey and is not restated here.

legacy check v2 home
IsAuthenticated on all five preference operations IsAuthenticated, first in every tuple
the preference service's own owner check behind each of the five operations (recorded in the area survey, and deliberately not restated here) IsAddressedUser: the address is the only identifier read, compared character for character
allow_staff=True on the two reads the (IsStaff & IsActiveUser) half, present only on the document read and the single-preference read
allow_staff=False on the three writes no administrator half: the only caller admitted is the addressed account
the order a refusal and an account lookup happen in (also recorded in the survey) the permission classes run before any handler, so a caller they refuse reaches no lookup: a learner naming an account nobody holds is answered 403, and 404 comes only from a lookup made for a caller they admitted
the opt-in taking no username from anywhere and always acting on the caller IsAuthenticated alone; the handler reads request.user, and no name is read from anywhere in the request
@require_post_params(["course_id","email_opt_in"]) required fields on EmailOptInSerializer, in every media type the address reads: a JSON body and a form body that leaves either one out are both refused 400 naming it (test_a_body_missing_either_half_of_the_choice_is_refused, test_a_form_that_leaves_the_choice_out_is_refused)
@ensure_csrf_cookie dropped, and the whole round is driven: the session class still holds a session to its request token, so a session POST without that token is refused 403 with the envelope, and the token comes from signing in rather than from this address — the sign-in sets the cookie, is accepted with it, and the choice is then recorded 204 (test_a_session_without_the_token_that_goes_with_it_is_refused, test_a_session_carrying_the_token_the_sign_in_handed_out_records_the_choice). That refusal is published by the operation (item 25)

The three layers (OEP-66), with the selector seam a future ORM-backed pass would use, are
C5 in the first comment: layer 1 is the permission classes above; layer 2 is the addressed account's
own rows, read through the preference service, from which no other account's row is reachable, and
the single (caller, org, email-optin) row at the opt-in; layer 3 is empty, because no parameter
narrows anything and an unknown one is refused.

Deny-path tests

caller document read preference read the three writes the opt-in
the addressed account 200 200 / 404 when the name holds nothing 204 204
another learner 403 403 403 n/a
an active administrator 200 200 403 n/a
an administrator whose own account is no longer active 403 403 403 n/a
the addressed account, email unconfirmed 200 200 204 204
anonymous 401 401 401 401
a name no account holds, administrator calling 404 404 403 n/a
a name no account holds, learner calling 403 403 403 n/a
the address in another case 403 403 403 n/a
me — learner / administrator / the account holding that name 403 / 404 / 200 403 / 404 / 200 403 / 403 / 204 n/a
a session carrying none of the request token the sign-in handed out 200 200 403 403

Named tests: PreferenceAccessTests (18), PreferenceGuardTests (5),
PreferenceRefusedWithNothingBehindThemTests (5), PreferenceAddressedByMeTests (5),
EmailOptInAccessTests (6), PreferenceRefusalParityTests (8). Each refusal is asserted through
assert_error_envelope with its error-type slug. The last row is driven at both resources: a read
is not held to the token, because only a change can be provoked from another site, so both reads
answer 200 with a session carrying none of it, while each of the three writes is refused 403
with the envelope and the stored rows stay as they were
(test_a_session_without_the_token_that_goes_with_it_is_refused_every_change and, at the opt-in,
test_a_session_without_the_token_that_goes_with_it_is_refused).

Asking what an address answers is guarded as a read of it. OPTIONS on either preference
address is answered 200 to the addressed account and to an active administrator, 403 to another
learner and 401 to an anonymous caller, each with the envelope of the matching read. The actions
block describing a change is built behind a second check carrying that change's own method, so an
administrator — who may read these addresses but not write them — is answered without it, and the
addressed account is told that a change at their own member address carries key and value
(five tests named in C4, one of them asserting the classes the request is decided by rather than
the answer alone).

The me row is driven for all five operations, at both addresses: the three writes answer
403 for an administrator as well as for a learner — a refusal is ordered before any account
lookup, so an administrator is refused rather than told the name is free — and the account that
really holds the name is served, its own rows being the ones changed. The permission classes are
also asserted directly
, action by action, and all five operations are driven again 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. That matters because the service enforces the same owner-or-administrator
rule from behind them: without those two harnesses, relaxing IsAddressedUser or adding the
administrator half to the writes leaves the ordinary HTTP deny tests green. Both mutations now go red twice, once at the declaration and once at HTTP.
C5 in the first comment carries both harnesses, the named tests and the mutation runs.

11. Gate report

run_gates.sh ran six gates on this branch head against origin/master @ 87cd3811a4, with a
mongo:7.0 service attached under the alias the test settings use and the old-tests selection
widened to both packages this phase supersedes. Five pass, one fails, nothing was skipped.

  versions PASS   hygiene PASS   schema PASS   urls FAIL   old-tests PASS   tests PASS
GATES FAILED: 1
gate result the number, and what it is
versions PASS files in new version dirs: 32, other files: 7, added in old dirs: 0
hygiene PASS (0 FAIL, 1 WARN) 39 files scanned. The WARN is H3 on user_api/v2/paginators.py:6 (class UserApiPagination(DefaultPagination)), a Phase A file this phase does not touch
schema PASS — 0 BREAKING, 64 WARN, 49 INFO the LMS document, origin/master (19 paths) against this branch (56 paths): 47 operationIds added, 43 component schemas added, zero removed and zero renamed
urls FAIL (2 FAIL, 1 WARN) 3054 head routes against 3036 base, 18 new api routes checked. All three findings name one route; see below. It is red, and nothing in this body reports it as passing
old-tests PASS — 193 passed user_api/tests/ 119 + user_api/preferences/tests/ 74, the second being the surface this phase supersedes
tests PASS — 1118 passed user_api/v2/ profile_images/ enrollments/v2/ lms/lib/tests/test_spectacular.py. user_api/v2/ alone is 920, profile_images/ 124

What this run measured. This branch head, which carries phases A and B beneath it. It says
nothing about origin/master's own state, and no claim here rests on it doing so. Its schema
comparison is of the LMS document, which is what the gate generates; the service-wide
/api-docs document is compared by no gate and is reconciled by hand in §7 and C2.

The schema gate is the evidence for the operation-id work. Two addresses of this resource
tokenize to one operationId, so the read of one preference is named through RENAMED_OPERATION_IDS
rather than left to a numeral (item 28). Renaming a published id is exactly what breaks a generated
client, so the check that matters is whether anything master publishes moved: the gate reports
additions only — 47 operationIds and 43 component schemas added, none removed and none renamed.

The one red is deliberate, and it is older than this phase. All three findings are on
api/user/v2/{_}., which is Phase A's version-level catch-all
(openedx/core/djangoapps/user_api/v2/urls.py:126): a regex route mounted last so that an address
none of this version's routes answers is refused in this version's JSON envelope instead of the
service's HTML 404 page. R6 (no trailing slash), R8 (an identifier directly under the version) and
R11 (no URL name, so reverse() is impossible) are correct readings and all three are right for
what it is: not an address, matching every remaining path, and never reversed. The gate has no
notion of a fallback route, so it will report these three for as long as the catch-all exists; what
it asks for is that the catch-all be dropped, which would give this version the HTML-404 behaviour
ADR 0029 requires it not to have. Of the 18 routes the gate checked, the other 17 are addressable
and draw no finding.

One tooling note. run_gates.sh has no way to attach a service container, and cases in both
superseded packages set up modulestore isolation, which connects to MongoDB on setup and drops
collections on teardown. The gate was therefore run on a network carrying a mongo:7.0 service
under the alias the test settings use, which is what makes the old-tests row above a measurement
of the code rather than of the harness. The published bodies of #39237 and #39297 describe
this gate from a run made before that was done; this measurement supersedes those descriptions for
all three phases.

Where a gate cannot see the change

  • Hygiene H8 cannot see these writes, and no grep can see an announcement. H8 greps
    get/list/retrieve bodies, and the write both reads reach is in platform middleware, one frame
    below the handler. A read that announces a change rather than writing one is invisible to any
    grep and to a SQL capture alike: the statement list stays empty while a receiver of the signal
    writes behind the handler. The evidence is therefore the runtime capture declared in §4, §5 and C4
    (0030), over three channels and on both sides of the language cookie, mutation-checked by planting
    in each read an announcement with no SQL behind it (9 failures from the document read, 9 from
    the member read) and an analytics event alone (9 failures); before the announcement channel was
    captured, both plants left the suite green. The same blindness ran
    one branch deeper
    : every capture case was a read that found something, so a write on the member
    read's "no such name" branch — the branch a client polling a name it never stored hits every time
    — was invisible too. A domain write planted there left all 111 tests of the two preference modules
    green; with the two branches now captured on both sides of the language cookie it fails 3.
  • Generation reports two things no gate scores. The LMS document emits ten new warnings,
    all of one kind — could not resolve authenticator …, one per declared authentication class, for
    the three superseded views this phase publishes and the two it adds — where the plan asked for
    none; the cause is the missing OpenApiAuthenticationExtension for the platform's authentication
    classes (the second library-first item in C3), and emitting none would mean leaving the superseded
    addresses out of the document, which is how they are marked deprecated. No warning disappears and
    the error count is unchanged. The generator's collision warnings go down, not up, because
    the read of one preference is named rather than left to a numeral. Both are measured ref by ref in
    C6 of the first comment, with the counts.
  • A test run under the platform's own database settings cannot see the change being made as
    one piece.
    ATOMIC_REQUESTS is on by default (openedx/envs/common.py), so a request that
    ends in a refusal has its earlier statements undone before any assertion runs: a merge patch
    whose second name cannot be removed leaves the first name as it was whether or not the
    handler groups the change itself (measured — with the handler's own grouping replaced by nothing,
    the whole preference suite stays green). The promise in the PATCH description is therefore held
    to a database without that setting as well: one test turns the request transaction off for the one
    request, asserts every name stands as it was, and is the test that goes red when the handler's
    grouping is removed. The pair is in PreferenceServiceFailureTests (6). The same seam is what the
    opt-in's refusal is measured against: where requests are served in a transaction nothing is left
    behind by an account carrying no profile, and where each statement stands on its own both versions
    leave the identical row carrying no choice at all (item 24).
  • The old-tests gate's default selection is aimed at the neighbouring package, not the superseded
    one.
    What it collects by default is user_api/tests/, which does not include
    user_api/preferences/ — the surface this phase supersedes. The selection was widened to both, so
    the gate now collects 193 tests and passes; the narrower selection would have been green while
    saying nothing about the views being superseded. The other half of that claim — that nothing of
    ours is in those files — stays argued from the diff: the eighteen protected paths carry zero
    changed lines and zero untracked files, verified per path (§7).

…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.
Abdul-Muqadim-Arbisoft and others added 25 commits November 5, 2026 19:10
…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]>
@Abdul-Muqadim-Arbisoft
Abdul-Muqadim-Arbisoft force-pushed the feat/api-adr-user-v2-phase-c branch from cab976a to 75a854e Compare November 5, 2026 19:40
@Abdul-Muqadim-Arbisoft

Copy link
Copy Markdown
Contributor Author

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.

git fetch origin pull/39314/head:pr-39314 cab976a910
git range-diff 73e7adf741..cab976a910 pr-39297..pr-39314

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.

@Abdul-Muqadim-Arbisoft

Copy link
Copy Markdown
Contributor Author

Evidence for #39314

Each test is named as module::Class::test as it exists at this head. Modules are under openedx/core/djangoapps/user_api/v2/tests/ unless a path is given.

Declared differences → tests

declared item test
restricted-application token refused at every operation, by the view itself (middleware removed in the test) test_restricted_applications.py::PreferenceTokenRefusalTests::test_a_restricted_applications_token_is_refused (ddt, 12 operations), ::test_the_same_token_from_an_ordinary_application_is_answered
…and compared with v1 (document 403, member 401, opt-in 403) test_preference_parity.py::PreferenceRefusalParityTests::test_both_versions_refuse_a_restricted_applications_token; test_email_opt_in_views.py::EmailOptInParityTests::test_every_address_refuses_a_restricted_applications_token
C's views are in the structural walk test_restricted_applications.py::EveryOperationCarriesTheRefusalTests::test_every_routed_view_inherits_the_guard, ::test_every_operation_resolves_the_refusal
names sorted by character code test_preference_views.py::PreferenceDocumentTests::test_the_order_the_names_come_back_in_is_the_code_of_each_character
a value that is not text is refused test_preference_views.py::PreferenceDocumentTests::test_a_value_that_is_not_text_is_refused_under_the_name_that_carried_it; PreferenceMemberTests::test_a_value_that_is_not_text_is_refused_under_the_property_that_carried_it
merge-patch only test_preference_views.py::PreferenceDocumentTests::test_a_change_sent_in_another_media_type_is_refused
value checked as sent (time_zone) test_preference_parity.py::PreferenceDocumentParityTests::test_both_versions_check_a_time_zone_as_it_was_sent, ::test_both_versions_store_any_other_value_without_the_whitespace_around_it, ::test_both_versions_refuse_a_value_of_whitespace_alone; PreferenceMemberParityTests::test_both_versions_check_a_time_zone_sent_to_the_member_address_as_it_was_sent, ::test_both_versions_refuse_a_value_of_whitespace_alone_with_the_same_message
a name sent in the document is stored without the surrounding whitespace test_preference_parity.py::PreferenceDocumentParityTests::test_both_versions_store_a_name_sent_in_the_document_without_the_whitespace_around_it
{"key","value"}; every single-segment name is addressable test_preference_views.py::PreferenceMemberTests::test_an_owner_reads_one_preference_as_its_name_and_its_value, ::test_every_name_one_segment_can_carry_is_readable_and_writable, ::test_a_name_nothing_can_be_stored_under_is_refused_under_that_part_too
a padded name at the member address → 404 after admission test_preference_parity.py::PreferenceMemberParityTests::test_both_versions_answer_a_name_with_whitespace_around_it_as_absent; test_preference_views.py::PreferenceMemberTests::test_a_name_with_whitespace_around_it_is_absent_to_its_owner_and_refused_to_anyone_else
opt-in 204; strict boolean; no profile → 404 test_email_opt_in_views.py::EmailOptInParityTests::test_the_earlier_address_answers_with_an_empty_body_and_this_one_with_no_body, ::test_a_value_that_only_suggests_a_choice_is_refused_here_and_not_read_as_one; EmailOptInViewTests::test_an_account_that_carries_no_profile_is_reported_absent, ::test_a_course_key_written_in_the_earlier_form_is_still_read
a method another collection does not serve stays 405 test_views.py::RefusedRequestTests::test_no_other_collection_of_this_version_learns_a_method_from_this_one
v1 preference writes publish their own bodies lms/lib/tests/test_spectacular.py::SupersededPreferenceRequestBodyTest::test_each_body_publishes_a_value_of_any_type, ::test_each_handler_stores_those_values_as_their_text
LMS marks the preference operations; Studio leaves them current lms/lib/tests/test_spectacular.py::SupersededPreferenceMarkTest::test_every_preference_operation_is_marked_superseded_in_both_documents; cms/lib/tests/test_spectacular.py::SupersededUserOperationTest::test_the_preference_addresses_its_own_pages_call_are_published_as_current, ::test_every_operation_of_the_addresses_it_lists_is_marked_superseded
the unversioned opt-in twin is left as it was published lms/lib/tests/test_spectacular.py::SupersededBodyInTheServiceWideDocumentTest::test_the_twin_of_the_opt_in_is_left_as_that_document_always_published_it

Compliance matrix

decision status how evidence
0025 met the document's changes and the member's value are checked by published serializers before the preference service runs PreferenceDocumentTests, PreferenceMemberTests
0026 met reads: (IsStaff & IsActiveUser) | IsAddressedUser; writes: IsAddressedUser; the opt-in: IsAuthenticated. Every view resolves NotJwtRestrictedApplication PreferenceAccessTests; PreferenceTokenRefusalTests
0027 met media types, refusals and parameters per operation; v1 writes publish their own bodies SupersededPreferenceRequestBodyTest; test_schema.py
0028 met AccountPreferenceViewSet, EmailOptInViewSet test_urls.py
0029 partial envelope everywhere; 405/406/415/unparsable carry the library catalog's type, as in #39297 test_views.py::RefusedRequestTests
0030 met reads write nothing of their own; the language-cookie middleware's write is the platform's and happens on both versions PreferenceReadWriteCaptureCase subclasses
0031 met one address replaces the opt-in and its twin EmailOptInParityTests::test_the_unversioned_earlier_address_records_the_same_row
0032 / 0033 / 0035 / 0036 n/a no list; no configuration; flat map —
0034 met JwtAuthentication with SessionAuthenticationAllowInactiveUser EmailOptInAccessTests::test_a_token_is_read_here_without_recording_the_address_as_one_on_the_defaults
0037 met extends the unreleased v2; no v1 file versions gate PASS vs master
0038 met preferences under the account; plural email_opt_ins urls gate PASS
OEP-66 met service-backed; scoping is the permission pair PreferenceAccessTests
OEP-69 met envelope, strict parameters PreferenceQueryParameterTests

Gate report

run_gates.sh (d4e6de0), same settings and test sets as #39297. The run used the tree one line before this head: the C1803 assertion, which differs in that line only.

gate vs #39297 vs d178206575
versions FAIL 9: v2 files of the same unreleased version read as "modified in place" PASS
hygiene PASS (0/0), 16 files FAIL (1 FAIL, 1 WARN), inherited from #39297
schema (/lms-api/) 0 BREAKING, 28 WARN, 14 INFO 0 / 63 / 49
urls PASS, 3048 → 3051 PASS, 3034 → 3051
old-tests 1255 passed, 4 skipped —
tests 1207 passed —

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 (75a854eb0b), MongoDB attached:

run result
LMS, -n 4: user_api/, profile_images/, user_authn/, lms/lib/tests/, lms/tests.py, openedx/core/tests/test_apidocs.py 2431 passed, 1 skipped, 0 failed
Studio, with the learning-app stub: cms/lib/tests/, cms/tests.py, user_api/ 199 passed, 1530 skipped, 0 failed
merged with origin/master d2dbc6a593, wider targets as in #39297 (tree: this head minus the C1803 line) LMS 3176 passed, 8 skipped, 0 failed; Studio 371 passed, 1914 skipped, 0 failed; 0 master test ids lost

drf-spectacular adds no error master does not log, and removes 7 of master's in LMS /api-docs/. Studio's documents are unchanged from master.

Tests removed or changed by the corrections

  • Removed by Studio's own-list change: SupersededUserOperationTest::test_a_body_the_handler_refuses_to_work_without_is_published_as_needed and ::test_the_write_of_one_preference_is_published_as_a_body_that_may_be_left_out. Studio no longer describes v1 bodies.
  • Renamed: SupersededUserOperationTest::test_every_operation_of_those_addresses_is_marked_superseded → ::test_every_operation_of_the_addresses_it_lists_is_marked_superseded. Studio's preference operations are now current.
  • Re-homed after the catch-all route was removed in feat: standardize the user accounts, profile image, verification and name-change API #39297: test_no_other_collection_of_this_version_learns_a_method_from_this_one (now in test_views.py::RefusedRequestTests) and test_the_twin_of_the_opt_in_is_left_as_that_document_always_published_it.

@Abdul-Muqadim-Arbisoft

Copy link
Copy Markdown
Contributor Author

@Faraz32123 on your review of 29 October:

Thanks.

@taimoor-ahmed-1 taimoor-ahmed-1 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread cms/lib/spectacular.py
"/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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants