Skip to content

feat: standardize the two account operations the retirement pipeline does not drive - #39334

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

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

Conversation

@Abdul-Muqadim-Arbisoft

@Abdul-Muqadim-Arbisoft Abdul-Muqadim-Arbisoft commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Part of [API] User under the umbrella #38137, following docs/decisions/ and OEP-69.

This PR moves the two account operations the retirement driver does not call onto /api/user/v2/: a learner's request to close their own account, and the bulk replacement of the names accounts are stored under. Both v1 addresses keep resolving unchanged.

Why a new version. v1's closing request answers two different refusals with 403 and an empty body, and two web clients read that body as "the password was wrong". A v1 test also pins the replacement's exact two-array answer (accounts/tests/test_views.py). Neither can change in place.

Stack and merge order: #39297 → #39314 → #39330 → #39334 (this PR, on #39330). #39331 is a sibling on #39330, and whichever of the two merges second follows the merge section in #39331.

23 commits, 22 files, +4704 / −64 (this PR's own range):

commits what
from feat: let an account's owner ask for its retirement where retirements are listed to style: name two helper parameters for what they carry rather than for the action (17) the feature and its review fixes. fix: hold a name asked for to one the addresses of this version carry is undone by fix: replace a name of any shape and report a refused write for its own mapping
from test: assert the whole answer to a replacement that fails part way through to test: hold each closure and name replacement check to a subject it can see (6) corrections from the 2026-11-04 review

Operations

superseded (v1) replacement (v2)
POST /api/user/v1/accounts/deactivate_logout/ POST /api/user/v2/retirements/ (the create of the retirements collection from #39330)
POST /api/user/v1/accounts/replace_usernames/ POST /api/user/v2/username_replacements/

Declared differences a caller can see

The declared differences are listed in DECLARED_DIFFERENCES in test_retirement_request_parity.py (5 entries) and in test_username_replacement_parity.py (5 entries). Every other measured case is equal on both versions. The tests for each item are listed in the evidence comment.

Closing one's own account (POST /api/user/v2/retirements/)

  • A successful request answers 204, as v1 does.
  • Each of the three refusals now has a type of its own: user/password-not-confirmed, user/account-temporarily-locked and user/account-deletion-unavailable. v1 answers all three with 403, with an empty body or no body.
  • An account that already has a retirement record gets 409. v1 answers 500 with the pipeline's exception sentence.
  • The body is read as JSON as well as a form. v1 parses JSON and then refuses it. A media type that neither address reads gets 415. An unknown query parameter gets 400.
  • An empty password gets 403 user/password-not-confirmed and is counted as a refused attempt wherever the deployment counts attempts, as on v1. A request with no password at all gets 400 under password, as v1 also answers 400.
  • A refused password attempt stays counted after the refusal, so repeated attempts lock the account to further attempts, as they do on v1.
  • OPTIONS answers the description of the retirements collection, and it asks for the pipeline capability that collection is read with.

Replacing names (POST /api/user/v2/username_replacements/)

  • The answer is one result per mapping, in the order the mappings were given, with outcome replaced, no_such_account or failed. v1 answers two arrays.
  • A name that no account is stored under is reported no_such_account. v1 lists it among the replacements it carried out.
  • A request may carry any number of mappings, an empty list included, as on v1. An empty list is answered 200 with {"results": []}. A form body is refused by both, by v1 with 400 and here with 415.
  • The name asked for is written as it is sent, whatever its characters or length, an empty name included, as v1 does. The database decides what it stores.
    • If the database refuses a mapping's write (for example a null for an existing account, or a name longer than the column on a database that enforces the column length), that mapping gets failed with new_username: null and nothing of it is kept. Every other mapping is carried out, as v1 does.
    • v1 echoes the name it tried for a failed mapping. v2 reports none, because none was handed out.
  • A name containing characters that no address carries, such as /, is stored as v1 stores it. That account can then be reached only by operations that name it in the body, not in the path.
  • Spaces around the name asked for are trimmed, so a name of spaces alone is written as "". v1 stores the spaces.
  • The mappings of one request run inside one transaction of their own. A failure other than the database refusing one mapping answers 500 and keeps none of the mappings, whether or not the deployment runs each request in a transaction. v1 reports such a failure as one failed mapping and keeps the rest.

Published documents

  • The v1 closing and the v1 replacement are documented with the bodies their handlers read:
    • the closing takes a form with a required, unbounded password;
    • the replacement takes mappings of exactly one member each, with untyped values;
    • neither references a v2 component any more.
  • POST /api/user/v2/retirements/ publishes security: [cookieAuth, jwt, bearer]. The LMS documents and the documentation build describe jwt and bearer in components.securitySchemes.
  • ReplacementOutcomeEnum (replaced, no_such_account, failed) is new on this unreleased branch. The v2 username_mappings list publishes no minItems or maxItems, and each mapping a nullable string value, with no maxLength and no pattern.
  • Both v1 operations are marked deprecated: true in the LMS documents and in Studio's /api-docs/, because Studio serves them too. Studio describes them as its views derive them.

ADRs applied

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

  • 0025 serializers — RetirementRequestSerializer and UsernameReplacementRequestSerializer check the bodies
  • 0026 permissions — AccountDeletionEnabled is mapped to create. CanReplaceUsername is imported from v1. Every view refuses restricted-application tokens. Deny tests cover each caller
  • 0027 schema / docs — both operations publish every status; the v1 operations publish their own bodies
  • 0028 viewsets — create on RetirementViewSet; UsernameReplacementViewSet
  • 0029 errors — RFC 9457 throughout; three domain types, raised only here
  • 0030 GET idempotence — n/a: both operations are writes
  • 0031 merged endpoints — the closing request is the retirements collection's create, not a second base URL for the same record
  • 0032 pagination — n/a: neither operation answers a list to page; the replacement answers one result per mapping the request sent, and a request carries as many mappings as its caller sends, as on v1
  • 0033 filtering — n/a: neither operation is a list to filter
  • 0034 authentication — one declared deviation: create also accepts BearerAuthentication (see deviations); the replacement takes the platform default
  • 0035 MFE config — n/a
  • 0036 nested JSON — n/a: both bodies are flat
  • 0037 versioning — extends the unreleased v2
  • 0038 URL structure — no URL name added for create; username_replacements is plural snake_case
  • OEP-66 queryset scoping — create acts on the caller's own account only; the replacement acts on no collection of this version
  • OEP-69 conventions — envelope, strict parameters

In-place edits

file why
cms/lib/spectacular.py adds the two superseded paths to Studio's SUPERSEDED_PATHS
cms/lib/tests/test_spectacular.py adds two operationId rows and test_no_operation_here_names_a_credential_only_the_other_service_describes
lms/envs/common.py APPEND_COMPONENTS gains securitySchemes: dict(CREDENTIAL_SCHEMES); ENUM_NAME_OVERRIDES gains ReplacementOutcomeEnum; the import names CREDENTIAL_SCHEMES
docs/docs_settings.py carries the securitySchemes the service appends, ahead of its own; one comment sentence
lms/lib/tests/test_spectacular.py tests for the v1 bodies and the credentials
user_api/schema.py, user_api/schema_components.py (from earlier in the stack) the two superseded rows and their bodies; CREDENTIAL_SCHEMES (jwt, bearer)

Error-format decision

Versioned. v1's empty-bodied 403s are unchanged, because clients read them.

Deprecations

Both operations are marked deprecated: true, with no header and no note in code. They are tracked on #39128. This area's entry is still to be posted; its text is drafted.

No caller has to change its credentials or the form of its body to move address. The iOS client excludes the superseded address from its token-refresh retry by matching the end of the URL, and the successor's URL does not end the same way. POST /api/discussion/v1/accounts/replace_username is not marked: it belongs to another area and has no successor.

Deliberate deviations

  • The closing request accepts an OAuth2 access token (BearerAuthentication), for create only. Both shipped mobile apps call the v1 address this way, and the scheme they send is per-deployment configuration. The hygiene gate reports this as 4 × H4. A closing condition (drop the class once both apps ship without it) is drafted as an issue.
  • DatabaseError per mapping, not Exception. A programming fault answers 500 and is not reported as an ordinary failed mapping (declared above).
  • The versions gate against feat: standardize the account retirement pipeline as /api/user/v2/ #39330 lists v2 files as edited in place. They belong to the same unreleased version.

Known pre-existing behaviour, left as it is

  • AuthFailedError never passes its message to its base class, so v1's closing request answers 403 with an empty body, and a locked-out caller is never told why. The exception is shared with sign-in, so it is drafted as its own issue.
  • The discussion app's replace_username route matches neither its caller nor its own published address. This stops the replacement job after a name has been replaced here and forwarded to other services. It belongs to another area and is drafted as an issue.
  • /api-docs/schema/ caching, as described in feat: standardize the user accounts, profile image, verification and name-change API #39297.

Merging with #39331

The merge recipe is in #39331's description, under "Merging with #39334". It applies to whichever of the two PRs merges second. It was derived from a real local merge of the two heads, followed by origin/master: seven files conflict, and two of this PR's credential tests need "csrf" added although they do not conflict. The merged tree passes both services' suites with 0 failures.

Evidence

The full tables are in the evidence comment.

  • Gates (PR base feat: standardize the account retirement pipeline as /api/user/v2/ #39330, run on trees identical to this head and feat: standardize the account retirement pipeline as /api/user/v2/ #39330's head; d178206575 for the comparison against master):
  • Repo CI lint: 0 findings added in every step; "lms and cms are independent" KEPT; commitlint passes on every commit.
  • Test runs at this head (f5ce4da9b8), MongoDB attached: LMS (user_api/, lms/lib/tests/, lms/tests.py, openedx/core/tests/test_apidocs.py) 2276 passed, 0 failed; Studio (cms/lib/tests/, cms/tests.py, user_api/) 212 passed, 2038 skipped, 0 failed. Against b19da14e5d the collected ids differ by four renamed tests on each service, and no outcome changed.
  • Merged with origin/master d2dbc6a593, conflict-free (wider targets: adds oauth_dispatch/, student/tests/, djangolib/testing/tests/, and user_authn/ under Studio): Studio 384 passed, 2422 skipped, 0 failed. LMS 3701 passed, 8 skipped, 1 failed. The failure is master's own TestAccountsAPI::test_patch_email_ratelimit, a one-minute rate-limit window that a long run straddled; it passes alone and in its class. Every master test id is still collected.

Follow-ups

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.
…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 20 commits November 5, 2026 19:10
A refused request is answered by keeping what it wrote rather than rolling it
back, so what else such an answer keeps is measured against the stored rows:
the account that asked is left with no record at all, and the record another
request had already left for another account is left exactly as that request
left it, down to its step, the name and the address it carries.

A request that cannot be recorded in full is undone twice over -- the record
and the end of the session are written inside a transaction of their own, and
the whole request is rolled back as well -- and with both of those removed
together one of these tests fails on a record left behind for an account whose
request failed.
…ction of its own

The names of several accounts are replaced in one request, under a condition
that covers the whole set and with no member address of its own, so it stands
at a collection beside the others rather than beneath the accounts: what
follows the account collection in an address is the name of an account, and a
user may register any name.

Every mapping given is reported with what was done about it, in the order the
mappings were given, so that a name no account was stored under is told apart
from a name that was replaced. The operation this one replaces reports both the
same way, which has its caller forward to four other services a replacement
that happened nowhere. No name is handed out for a mapping that reached no
account, and the work either operation does is the same.

One request carries at most as many mappings as a page of any collection of
this version holds, because the answer carries one result per mapping and a
request without a ceiling is an answer without one, over a write across
several tables.

The capability asked for is the class the earlier address asks for, read from
where that address reads it, so the two cannot drift; the places a name is
kept are written out here because that address holds them inside its own
handler, and a test resolves every one of them.
… exchange

Both documents that publish them said they read no body and answer with a 200
carrying none, and both have always refused a request with no body and answered
something else: one answers nothing at all, the other two arrays of mappings.
Each is now described with the body it reads, in the forms it really reads it
in -- the request to be retired is published without JSON, which its handler
parses and then refuses -- and with the code it really answers.

The set of choices the replacement reports an outcome from is pinned to a name
of its own in the service's settings, beside the two already there. Measured,
because the reason matters: the set another field of this version publishes
under that field's name keeps its name whether or not this one is pinned, since
it is pinned itself; what takes it away is pinning this one by naming that same
set, which was driven and leaves the document without it.

The addresses each superseded operation is replaced by is now held per method
as well as per path, because an address replacing several operations serves a
method for each of them and a client told to move to one that does not serve
the method it was using has nowhere to go.
The import blocks are ordered as the repository orders them, two imports no
longer used are gone, and the two tests that held a declared difference to
being some text now hold the declared differences to being the ones the cases
around them measure, one name at a time.
… the shared ones alone

The three refusals this operation adds are subclasses of a refusal the shared
catalog already classifies, and the catalog is shared with every other API in
the process: each of them is held to the name this area gives it, and a refusal
raised by any other area is held to the name it had before. Registering one of
them against the shared class instead was driven, and both tests fail.
…sses

The list every operation that declares none of its own resolves was read from
the platform, so the expectation and the code resolved it from the same place
and the table of resolved classes asserted only that each address resolved
whatever was configured. Adding a class that takes an access token to what a
deployment configures for everything alike left all of it green while a token
cancelled a retirement, ran a disposal batch and reached an erasure.

The two classes are named here instead, and a real access token is now driven
at each of the nine requests that carry the work out, each of which answers
that it authenticates nobody while the record it was aimed at stays as it was.
The token itself is shown to be a good one at the operation that declares it.
…nswered

The outcome was read from the number of rows that carried the name given,
summed over the eight places a name is kept. A name kept only beside the work
of an account that is stored under another name was therefore reported as
replaced, carrying a name no account holds -- which the one caller of this
operation forwards verbatim to the four other services that hold the same
name. The record of an account that has already been retired keeps the name it
was registered under, so a request naming that was reported the same way.

The rows are rewritten exactly as the address this one replaces rewrites them.
What changed is where the answer is read from: the place an account's own name
is kept, counted on its own rather than summed with the rest, so the published
text about each outcome is true of it.
The names in a mapping were read as text of any shape and written straight
into the column an account's name is stored in. A name carrying a character no
address of this version carries was therefore written onto the account and
onto the record of its retirement, after which the record was answered as
absent at every address that reaches one -- so the work that has to erase that
account's data could no longer reach the row it must erase. A name longer than
the column is taken by one database and refused by another part way through a
batch.

Both bounds are now read from what stores and addresses the name, published
with the shape of a mapping, and held at the boundary in both directions.
…s an attempt

Three things besides the count of the refused attempt are in the transaction a
refused request is answered from, and the answer kept all of them while
stating that nothing else had been written: the account row the credentials
were resolved through where a token this platform signed names an account this
service holds none of, the duplicate counter rows the lockout check deletes,
and any callback registered during the request for its commit. The comment now
says so, and says that this is the state the address it replaces leaves.

What is kept is now declared for the request a caller makes for their own
retirement rather than for the type of the refusal. Both of those types are
the shared catalog's, and the collection also erases personal data, deletes
records and moves them on: a refusal of one of those raised with either type
had that operation's partial write kept. The two tests that restated the
declaration are replaced by three that drive it.
…hey do

Both parity modules ended in a test that compared a written-down list of
differences to the same list written down again, and claimed that a difference
measured and not listed, or listed and not measured, failed. Neither could
fail for anything, and three differences a caller would notice were missing
from them: the most mappings one request may carry, the space around a name
asked for, and what a caller holding an account is answered when they ask the
address what it serves.

Each module now measures everything a caller can notice at both addresses and
reads the list of differences off the two answers, so a difference nobody
declared fails, a declaration nothing measures fails, and the declared reason
is what a driver moving between the addresses is given. Removing one
declaration, and adding one for a difference the addresses do not have, were
both driven and both fail.
…t answers

A caller asking the collection of retirements what it serves was told it reads
JSON alone, while the request a caller makes for their own retirement is read
as JSON, as a web form and as a file upload -- the web form being what two
shipped applications send. It was also told the body of that request is the
retirement record, eleven properties none of which a caller sends and none of
which is the password the request cannot work without. The address where the
names of several accounts are replaced said its body carries the results it
answers with.

The description now names the forms every method of the address being asked
about reads, and the body each of its operations reads: the request for a
retirement at the collection, the erasure at the address that erases, and the
mappings at the address that replaces names. The published shape of a mapping
keeps the bounds for the operation that holds a name to them and leaves the
operation it replaces publishing what that one really reads, and the answer
the earlier replacement gives is described rather than published blank.

Ending the session is a write to the deployment's cache and not to the
records, so it is not undone by a failure after it; the comment claiming the
record and the session end together now says what each of them leaves.
…nt takes

That request is the one operation of this version a client library is
generated from, and it takes a session, a token this platform signed or an
access token the authorization endpoint handed out -- the last of those being
what two shipped applications hold and the whole reason the operation takes
it. The document described the session cookie alone, because that is the only
one of the three the generator can describe by itself, so a client generated
from the document required a cookie and offered those callers no way to send
what they hold.

The service now describes each credential it takes, from one definition the
documentation settings carry through beside the components they already carry
through, and the operation names the three it accepts. Every document is held
to describing each credential its operations name, in both services, so a name
no scheme is published under fails rather than reaching a generated client.
… name

The pin added with the schemes claimed every credential named in a document is
one that document describes. It is not, at the published base either: an
address of this API served by the authentication application names a scheme
for the header a form submission carries, and only the settings the published
reference is generated from describe it. Both service-wide documents are held
to that one exception by name, so a second undescribed credential fails, and
Studio is held to naming neither of the two the other service appends.
… the action

Each of them shadowed the decorator the module imports under that name, which
the repository's own lint reports.
…rough

The test of a replacement that fails part way through checked the status
and the detail of the answer but not its type, title or instance, unlike
every other failure test of the operation. A change that kept the status
and the sentence but answered under another type passed it unseen.

It now compares the whole envelope, as the test of an uninstalled
application beside it does.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…of their own

The version 1 closing of an account was described with the version 2
request serializer, so both documents gave it a reference to the
RetirementRequest component, and the version 1 replacement of names took
its mapping from the shape the version 2 field publishes. Whatever bound
or type the replacing address later takes on would therefore be
published for handlers that do not hold a request to it.

Both are now written out from what their handlers read:
- the closing reads a form whose `password` is required (a request
  without one is a 400) and unbounded (an empty one is read as a
  password the account does not hold, a 403);
- the replacement reads mappings of exactly one member each, as its
  handler refuses an object carrying none or several, whose value has no
  type: a value of any type is written as the name, and one the database
  refuses, such as null, is answered among the failures. The answer's
  mappings use the same shape, since the handler echoes the value.

Media types and the required marks are unchanged in /lms-api/ and
/api-docs/. RetirementRequest and UsernameReplacementRequest stay on the
version 2 operations. The tests check both documents: the exact shapes,
no bounding keyword, a jsonschema check of the requests the handlers
read, and the handlers' answers to them.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…of their own

Each mapping was rewritten in a transaction of its own, with none around
the loop. The declared difference ("keeps none of them") and the
published 500 ("Nothing was changed, and the request may be sent
again") relied on the deployment opening a transaction around each
request, and did not hold even then: the 500 envelope is built from the
exception rather than raised out of the view, so the request's
transaction commits what the mappings before the failure wrote. A
failure in the second of two mappings answered 500 with the first
account already renamed, whether ATOMIC_REQUESTS was on or off.

The loop now runs inside one transaction.atomic() of its own, so a
failure part way through keeps none of the mappings in every
deployment, and the published text is true. Each mapping keeps its own
inner transaction.

The failure test fails only the second of two mappings and runs in two
fixture classes, with request transactions on and off, each checking
that the handler wraps the view as its class says. The parity harness
measures the same failure both ways and pins each address's answer. The
statement-parity test allows exactly the two statements that open and
close the new transaction around every mapping, however many there are.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…wn mapping

The replacement refused, with a 400 for the whole batch, a name asked for
that carried characters outside the address pattern, was longer than the
column, was empty or was null. The address it replaces writes every such
name, and reports a name the database will not store (a null, or a long
name on a database holding names to the column) among its failed
replacements while carrying out every other mapping. Its one in-tree
caller, scripts/user_retirement/replace_usernames.py, sends the whole
list in one request, writes each failure to its report and forwards the
successes, so one such name stopped every replacement in the file.

The name asked for is now read as any text or null and written as asked;
the database decides what it stores. A rewrite the database refuses
(DatabaseError) is reported as the new `failed` outcome with a null
`new_username`, nothing of that mapping is kept, and the mappings after it
are carried out, with and without a transaction around each request. Any
other failure part way through still keeps none of the mappings and
answers 500.

The published mapping drops `maxLength` and `pattern`, takes a null, and
says a name the database will not store is reported as failed;
ReplacementOutcomeEnum gains `failed`.

The parity tests send both addresses the same mappings over the same
accounts (each run rolled back before the other): a name with a slash, a
quote and a hash, a 151-character name, an empty name, a null for an
account and a null for no account. Both write the same names and fail
the same mapping. The 151-character name is also sent where every write
of a name longer than its column is refused, and both report it failed
and carry out the rest. The harness measures each of these, plus a
refused write and a fault part way through. "A write that fails part way
through" is no longer a declared difference; a fault of this server part
way through is, because the earlier address reports it per mapping and
this one keeps nothing.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…account

An empty password was refused with a 400 under `password` and no attempt
was counted. The address this one replaces reads it as a password the
account does not hold: it answers 403 and counts one attempt towards
closing the account to further ones. A client that reads any 403 as "the
password was wrong" saw a different status, and blank attempts no longer
added up to a lockout.

The password field now allows an empty value, so it reaches the same
check as any other: 403 `user/password-not-confirmed`, counted where the
deployment counts attempts and kept past the refusal. Nothing else
changes: a request carrying no password is still a 400 under `password`,
and the published RetirementRequest component is unchanged (it never
published a minimum length).

Tests send an empty password as a form and as JSON, on both sides of
ENABLE_MAX_FAILED_LOGIN_ATTEMPTS. The parity test drives both addresses
and checks the status, the type and the count. The harness measures the
empty password at both addresses, so a difference here would have to be
declared.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…n see

Four checks passed with nothing to check. The Studio check of the
credentials its user operations name passed when they name none. The check
that each superseded handler's request fits its published body passed when
no body was published. The check that the replacing closure references its
own component compared an empty mapping with itself when the body carried
no media type. The check that a confirmed password clears the count of
refused attempts passed when no attempt was ever counted.

Each now first asserts the subject it reads: the credential Studio's user
operations name, a body in every document for each handler, the three forms
the closure reads, and the one attempt counted before the password clears
it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@Abdul-Muqadim-Arbisoft

Copy link
Copy Markdown
Contributor Author

Rebased onto the rewritten #39330, plus this round's corrections (23 commits, up from 19).

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/39334/head:pr-39334 6ee4199723
git range-diff ed83beab3d..6ee4199723 pr-39330..pr-39334

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

Abdul-Muqadim-Arbisoft commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

Evidence for #39334

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. _ReplacementFailureCases runs twice: in ReplacementFailureTests (request transactions on) and in ReplacementFailureWithoutRequestTransactionsTests (off).

Declared differences → tests

declared item test
three refusals told apart by type test_retirement_request_views.py::RetirementRequestRefusalTests::test_the_three_refusals_are_told_apart_by_their_type_at_one_status
an existing record → 409 test_retirement_request_views.py::RetirementAlreadyRequestedTests::test_a_record_made_some_other_way_refuses_the_request_as_a_conflict
JSON read as well as a form; another form → 415 test_retirement_request_views.py::RetirementRequestBodyTests::test_a_body_sent_as_json_is_read, ::test_a_body_in_a_form_this_operation_cannot_read_is_refused
empty password: 403, counted, as on v1 test_retirement_request_views.py::RetirementRequestBodyTests::test_a_password_sent_as_nothing_at_all_is_refused_as_not_the_accounts; AttemptsCountedTests::test_an_attempt_with_an_empty_password_is_counted; AttemptsNotCountedTests::test_an_empty_password_is_refused_and_not_counted; test_retirement_request_parity.py::RefusalParityTests::test_an_empty_password_is_refused_and_counted_by_both
a refused attempt stays counted; cleared by the right password test_retirement_request_views.py::AttemptsCountedTests::test_every_attempt_adds_to_the_count_until_the_account_is_closed_to_them, ::test_the_count_is_cleared_by_a_password_the_account_does_hold
OPTIONS asks for the pipeline capability test_retirement_request_views.py::RetirementRequestAccessTests::test_asking_the_collection_what_it_serves_is_pipeline_work
access token taken at create only test_retirement_request_views.py::RetirementRequestCredentialTests::test_an_access_token_is_taken_under_every_spelling_of_its_scheme; PipelineCredentialTests::test_an_access_token_reaches_no_operation_that_carries_the_work_out
one result per mapping, in order; no_such_account test_username_replacement_views.py::UsernameReplacementTests::test_every_mapping_is_reported_in_the_order_it_was_given, ::test_a_name_no_account_is_stored_under_is_reported_as_such
any number of mappings, an empty list included, taken as on v1; form refused test_username_replacement_views.py::UsernameReplacementBodyTests::test_more_mappings_than_a_page_holds_are_all_carried_out, ::test_a_request_carrying_an_empty_list_is_answered_with_no_results, ::test_a_body_sent_as_a_web_form_is_refused; test_username_replacement_parity.py::ReplacementOutcomeParityTests::test_more_mappings_than_a_page_holds_are_carried_out_by_both, ::test_a_request_carrying_no_mappings_at_all_is_answered_by_both
names of any shape written as v1 writes them test_username_replacement_parity.py::ReplacementOutcomeParityTests::test_names_of_every_shape_are_carried_out_alike_by_both, ::test_a_name_longer_than_its_column_is_failed_by_both_where_the_database_refuses_it; test_username_replacement_views.py::UsernameReplacementBodyTests::test_a_name_carrying_characters_no_address_carries_is_written_as_asked, ::test_a_null_name_is_reported_as_failed_and_the_mappings_after_it_are_carried_out
a refused write → failed, the rest carried out test_username_replacement_views.py::_ReplacementFailureCases::test_a_write_the_database_refuses_is_reported_and_the_rest_are_carried_out; test_username_replacement_parity.py::ReplacementOutcomeParityTests::test_a_write_the_database_refuses_part_way_through_is_reported_alike_by_both
one transaction: a fault keeps none (v1 keeps the rest) test_username_replacement_views.py::_ReplacementFailureCases::test_a_fault_part_way_through_replaces_nothing, ::test_requests_are_carried_out_as_this_class_says; test_username_replacement_parity.py::ReplacementOutcomeParityTests::test_a_fault_part_way_through_is_answered_differently
v1 bodies of their own lms/lib/tests/test_spectacular.py::SupersededClosureAndReplacementBodyTest::test_each_body_is_written_out_and_carries_nothing_that_bounds_it, ::test_each_request_the_handler_reads_is_one_its_published_body_allows, ::test_each_handler_reads_those_requests, ::test_the_replacing_addresses_publish_bodies_of_their_own, ::test_each_body_is_published_as_required
published credentials test_schema.py::test_every_credential_an_operation_publishes_is_one_the_document_describes; cms/lib/tests/test_spectacular.py::SupersededUserOperationTest::test_no_operation_here_names_a_credential_only_the_other_service_describes
v2 mapping shape test_schema.py::test_the_published_mapping_takes_a_name_of_any_shape

DECLARED_DIFFERENCES in the two parity modules, in substance:

  • Closing (5): JSON is read here, and v1 refuses it. A form neither version reads is described differently. One status with no body becomes three named refusals. An existing record while the password still works is 500 with v1's exception sentence and 409 here. OPTIONS answers the queue's description and asks for its capability.
  • Replacement (5): v1 answers two arrays, v2 one result per mapping. A name no account holds is reported as replaced by v1 and no_such_account here. A form body is refused by both, in different words. v1 stores spaces around the name, and v2 trims them. A fault part way through is reported per mapping by v1 and answered 500 with nothing kept here. A request of any number of mappings, an empty one included, is measured equal on both.

Compliance matrix

decision status evidence
0025 met RetirementRequestBodyTests, UsernameReplacementBodyTests
0026 met UsernameReplacementAccessTests::test_every_other_caller_is_forbidden, ::test_the_capability_asked_for_is_the_one_the_earlier_address_asks_for; RetirementRequestAccessTests::test_every_caller_closes_the_account_they_hold_whatever_capability_it_carries; RetirementRequestRefusalTests::test_a_deployment_that_does_not_offer_this_refuses_it_in_those_terms
0027 met SupersededClosureAndReplacementBodyTest; test_schema.py
0028 / 0031 met: create on RetirementViewSet; no second base URL RequestResolutionTests::test_each_address_and_method_resolves_the_classes_declared_for_it
0029 met (three domain types, raised only here) RetirementRequestRefusalTests::test_the_three_refusals_are_told_apart_by_their_type_at_one_status
0034 declared deviation (bearer on create) RetirementRequestCredentialTests, PipelineCredentialTests
0037 / 0038 met versions gate vs master; urls gate
OEP-66 met: own account only RetirementRequestAccessTests::test_a_request_naming_another_account_closes_the_one_it_was_made_from

Gate report

run_gates.sh (d4e6de0), same settings and sets as #39297, MongoDB attached. The run used commits whose trees are identical to this head and to #39330's head.

gate vs #39330 vs d178206575
versions FAIL 11: v2 files of the same unreleased version read as "modified in place" (stacked base) PASS
hygiene FAIL (4 FAIL, 0 WARN): exactly 4 × H4, the declared bearer deviation, at v2/views.py:70 (import) and :2879 (create's authentication classes), and v2/tests/test_retirement_request_views.py:54 and :92 FAIL (5 FAIL, 5 WARN): the same 4 × H4, plus the H3 FAIL and WARN inherited from #39297 and the 4 × H7 WARN inherited from #39330
schema (/lms-api/) PASS: 0 BREAKING, 36 WARN, 6 INFO. Every WARN is "could not resolve authenticator" 0 BREAKING
urls PASS (0 FAIL, 0 WARN), 3058 → 3059 routes, no (namespace, name) lost PASS
old-tests 1258 passed, 4 skipped —
tests 1736 passed —

Repo CI lint against #39330: ruff, xsslint, pii_check, check_keywords lms and cms, mypy and verify-dunder-init give identical output and exit 0. lint-imports: 4 kept, 0 broken, "lms and cms are independent" KEPT. pylint over this PR's 22 changed .py files adds 0 messages. commitlint: 23/23 commits pass.

Test runs, MongoDB attached. The first row is at this head (f5ce4da9b8); the rest were measured at the previous head b19da14e5d, which differs only by the commit that lifts the limit on mappings per request:

run result
at f5ce4da9b8: LMS user_api/, lms/lib/tests/, lms/tests.py, openedx/core/tests/test_apidocs.py; Studio cms/lib/tests/, cms/tests.py, user_api/ LMS 2276 passed, 0 failed; Studio 212 passed, 2038 skipped, 0 failed; collected ids differ from b19da14e5d by four renamed tests on each service, no outcome changed
LMS, -n 4: user_api/, profile_images/, user_authn/, lms/lib/tests/, lms/tests.py, openedx/core/tests/test_apidocs.py 2961 passed, 1 skipped, 0 failed
Studio, with the learning-app stub: cms/lib/tests/, cms/tests.py, user_api/ 212 passed, 2038 skipped, 0 failed
test_retirement_views.py: file order, reversed order, -p randomly seeds 1, 2, 3 and 12345 258 passed in each run
test_retirement_views.py at every commit of this PR 23/23 green
user_api/v2/, in file order and with -p randomly seed 7 1632 passed, both runs
merged with origin/master d2dbc6a593, conflict-free (tree identical to this head, plus master); LMS adds oauth_dispatch/, student/tests/ and djangolib/testing/tests/ to the targets above, Studio adds user_authn/ LMS 3701 passed, 8 skipped, 1 failed; Studio 384 passed, 2422 skipped, 0 failed; 0 master test ids lost

The one failure on the merged tree is master's own user_api/accounts/tests/test_views.py::TestAccountsAPI::test_patch_email_ratelimit (200 where 429 was expected). It runs under a fixed one-minute rate-limit window, and on a 25-minute run on a loaded host its two requests can straddle a minute boundary. This PR does not touch that file. It passes alone and inside its class (83 passed).

Served documents, merged with master: nothing of master's is lost (paths, operations, operationIds, components), 0 unresolved $ref, 0 errors master does not already log, and 12 of master's are gone.

Tests removed or changed by the corrections

These replace D2's own tests of the earlier behaviour:

  • RetirementRequestBodyTests::test_a_password_sent_as_nothing_at_all_is_refused_as_a_value
  • test_schema.py::test_the_published_mapping_holds_a_name_to_what_an_address_carries
  • EveryPlaceTheNameIsKeptTests::test_a_write_that_fails_part_way_through_replaces_nothing
  • UsernameReplacementBodyTests::test_a_name_longer_than_the_column_that_stores_it_is_refused
  • UsernameReplacementBodyTests::test_a_name_no_address_can_carry_is_refused_before_anything_is_written

Four tests that could pass with nothing to check now first assert their subject:

  • SupersededUserOperationTest::test_no_operation_here_names_a_credential_only_the_other_service_describes
  • SupersededClosureAndReplacementBodyTest::test_each_request_the_handler_reads_is_one_its_published_body_allows
  • ::test_the_replacing_addresses_publish_bodies_of_their_own
  • AttemptsCountedTests::test_the_count_is_cleared_by_a_password_the_account_does_hold

…one included

POST /api/user/v2/username_replacements/ no longer refuses a request
carrying more than 100 mappings, and no longer refuses an empty list.
Every mapping sent is carried out and reported, and a request carrying
no mappings is answered 200 with {"results": []}.

Version 1 (POST /api/user/v1/accounts/replace_usernames/) takes any
number of mappings and answers an empty list with two empty arrays, and
the replacing job in scripts/user_retirement sends every mapping of its
CSV in one request. A job given more than 100 names, or none, is now
answered as version 1 answers it.

The published request body no longer carries maxItems: 100, and its
description says the list has no limit. The two declared differences
for the cap and the empty list are removed, and parity tests send 101
mappings and an empty list to both versions and assert the same
outcome.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@Abdul-Muqadim-Arbisoft

Copy link
Copy Markdown
Contributor Author

One commit added: f5ce4da9b8 fix: carry out a name replacement however many mappings it carries, none included (a fast-forward from b19da14e5d; no history rewrite).

The replacement capped a request at 100 mappings and refused an empty list. Version 1 does neither, and the in-tree job scripts/user_retirement/replace_usernames.py sends every mapping from its CSV in one request (an empty CSV sends []), so the cap would have broken the job for any run of more than 100 names once it moves to this address. Both limits are removed, as the retirement cleanups' limit was in #39330.

Tests: ReplacementOutcomeParityTests::test_more_mappings_than_a_page_holds_are_carried_out_by_both sends 101 mappings to both versions; restoring the cap turns four tests red and restoring the empty-list refusal turns three red. LMS 2276 passed and Studio 212 passed at the new head, with no outcome changes. The description, the evidence comment and the #39128 entry are updated. The merge recipe in #39331 is unaffected (same seven files, same conflict content).

@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 (c59981f..f5ce4da). Account closure mirrors v1 step for step (refused attempts stay counted through the per-request transaction, empty password included; the legacy contract the delete-account page uses is unchanged), the per-mapping transaction on username replacement holds, and zero mappings answers {"results": []}. Two items should change before this leaves draft. Also: the body still says the #39128 entry is "to be posted" (it is, 6667972498), and the earlier #39128 entry for #39330 says these two operations carry no deprecation mark, which stops being true when this merges.

(current_username, asked_for), = mapping.items()
replacement = _name_nobody_is_stored_under(asked_for)
try:
rewritten = _rewrite_name(current_username, replacement, places)

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.

For a name auth_user does not hold, _rewrite_name still rewrites every other place in NAMES_ARE_ALSO_KEPT_IN (consent, credit, UserRetirementStatus.original_username, UserRetirementPartnerReportingStatus.original_username), and the answer is then no_such_account with new_username: null; the published enum text (serializers.py:1414) says nothing was handed out and the other services have nothing to be told. test_username_replacement_views.py:327-345 pins the rewrite. v1 reported such a mapping as a success, so replace_usernames.py forwarded it to ecommerce, discovery and credentials; with v2 the driver stops at the LMS, whose retirement rows now carry the new name while the other services keep the old one, and the learner's data there is not retired under either name.

Either don't touch the side tables when no account holds the name (so no_such_account is true), or report the mapping as replaced and return new_username so the driver forwards it as v1 did. Whichever you pick, declare it in the differences table; the current declaration does not cover this case.

# that credential as well as the two every other request here takes. It is
# declared for that one operation, because the others move and erase
# personal data and are not reached by any of those applications.
action_authentication = {

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 new v2 closing operation takes BearerAuthentication and publishes security: [cookieAuth, jwt, bearer] with a new bearer scheme, on the one retirement operation tagged openedx-platform-sdk. ADR 0034 rule 3 is that Bearer is not used in new code, and the reason the body gives (the mobile apps) does not hold: the apps call the v1 address, and v1 keeps resolving with Bearer for the whole deprecation window. The stated exit ("drop it once the apps ship without it") would remove an authentication method from a published v2 operation, which is a breaking change needing a v3, so the deviation becomes permanent. Drop Bearer here, keep v1 as the Bearer address until the apps move (track that in the DEPR entry), and remove the bearer scheme from schema_components.py/APPEND_COMPONENTS.

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.

2 participants