Repository navigation
feat: standardize the two account operations the retirement pipeline does not drive - #39334
Abdul-Muqadim-Arbisoft wants to merge 131 commits into
Conversation
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.
…ot to a maintainer
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]>
6ee4199 to
b19da14
Compare
|
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. The new commits of the 2026-11-04 round are listed in the description's commit table. Each one names its subject, and each behaviour change comes with a test that fails without it. |
Evidence for #39334Each test is named as Declared differences → tests
Compliance matrix
Gate report
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 Test runs, MongoDB attached. The first row is at this head (
The one failure on the merged tree is master's own Served documents, merged with master: nothing of master's is lost (paths, operations, operationIds, components), 0 unresolved Tests removed or changed by the correctionsThese replace D2's own tests of the earlier behaviour:
Four tests that could pass with nothing to check now first assert their subject:
|
…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]>
|
One commit added: The replacement capped a request at 100 mappings and refused an empty list. Version 1 does neither, and the in-tree job Tests: |
taimoor-ahmed-1
left a comment
There was a problem hiding this comment.
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) |
There was a problem hiding this comment.
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 = { |
There was a problem hiding this comment.
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.
Summary
Part of
[API] Userunder the umbrella #38137, followingdocs/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
403and 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):
Operations
POST /api/user/v1/accounts/deactivate_logout/POST /api/user/v2/retirements/(thecreateof 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_DIFFERENCESintest_retirement_request_parity.py(5 entries) and intest_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/)204, as v1 does.user/password-not-confirmed,user/account-temporarily-lockedanduser/account-deletion-unavailable. v1 answers all three with403, with an empty body or no body.409. v1 answers500with the pipeline's exception sentence.415. An unknown query parameter gets400.403user/password-not-confirmedand is counted as a refused attempt wherever the deployment counts attempts, as on v1. A request with no password at all gets400underpassword, as v1 also answers400.OPTIONSanswers 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/)outcomereplaced,no_such_accountorfailed. v1 answers two arrays.no_such_account. v1 lists it among the replacements it carried out.200with{"results": []}. A form body is refused by both, by v1 with400and here with415.failedwithnew_username: nulland nothing of it is kept. Every other mapping is carried out, as v1 does./, 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."". v1 stores the spaces.500and 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
password;POST /api/user/v2/retirements/publishessecurity: [cookieAuth, jwt, bearer]. The LMS documents and the documentation build describejwtandbearerincomponents.securitySchemes.ReplacementOutcomeEnum(replaced,no_such_account,failed) is new on this unreleased branch. The v2username_mappingslist publishes nominItemsormaxItems, and each mapping a nullable string value, with nomaxLengthand no pattern.deprecated: truein 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.
RetirementRequestSerializerandUsernameReplacementRequestSerializercheck the bodiesAccountDeletionEnabledis mapped tocreate.CanReplaceUsernameis imported from v1. Every view refuses restricted-application tokens. Deny tests cover each callercreateonRetirementViewSet;UsernameReplacementViewSetcreate, not a second base URL for the same recordcreatealso acceptsBearerAuthentication(see deviations); the replacement takes the platform defaultv2create;username_replacementsis plural snake_casecreateacts on the caller's own account only; the replacement acts on no collection of this versionIn-place edits
cms/lib/spectacular.pySUPERSEDED_PATHScms/lib/tests/test_spectacular.pytest_no_operation_here_names_a_credential_only_the_other_service_describeslms/envs/common.pyAPPEND_COMPONENTSgainssecuritySchemes: dict(CREDENTIAL_SCHEMES);ENUM_NAME_OVERRIDESgainsReplacementOutcomeEnum; the import namesCREDENTIAL_SCHEMESdocs/docs_settings.pysecuritySchemesthe service appends, ahead of its own; one comment sentencelms/lib/tests/test_spectacular.pyuser_api/schema.py,user_api/schema_components.py(from earlier in the stack)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_usernameis not marked: it belongs to another area and has no successor.Deliberate deviations
BearerAuthentication), forcreateonly. 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.DatabaseErrorper mapping, notException. A programming fault answers500and is not reported as an ordinary failed mapping (declared above).Known pre-existing behaviour, left as it is
AuthFailedErrornever passes its message to its base class, so v1's closing request answers403with 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.replace_usernameroute 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.
d178206575for the comparison against master):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. Againstb19da14e5dthe collected ids differ by four renamed tests on each service, and no outcome changed.origin/masterd2dbc6a593, conflict-free (wider targets: addsoauth_dispatch/,student/tests/,djangolib/testing/tests/, anduser_authn/under Studio): Studio 384 passed, 2422 skipped, 0 failed. LMS 3701 passed, 8 skipped, 1 failed. The failure is master's ownTestAccountsAPI::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
AuthFailedErrorissue and the discussion-route issue (drafts are ready).POST /api/user/v2/retirements/is tagged for the generated client.